TypeScript SDK

# Not on npm yet: install the package tarball we send you
npm install ./citron-sdk-0.1.0.tgz

import { createClient } from '@citron/sdk';

export const citron = createClient({
  baseUrl: 'https://api.console.citronos.com', // "…/v1" is accepted too
  apiKey: process.env.CITRON_API_KEY,          // ck_pub_… (content and GraphQL only)
  locale: 'bg',                                // flatten localized fields to Bulgarian
  richtext: 'html',                            // html | json | both (API default: both)
  orgSlug: 'your-org',                         // for contact, forms and booking helpers
  timeoutMs: 10_000,                           // per attempt
  retry: { retries: 2, baseDelayMs: 300, maxDelayMs: 10_000 }, // or false
  cache: false,                                // true / { ttlMs } for an in-memory ETag cache
});

const { data, meta } = await citron.collection('products').list({
  locale: 'en',
  filter: {
    category: 'station',              // filter[category]=station
    capacity: { gte: 5 },             // filter[capacity][gte]=5
    code: { in: ['BIO-6', 'BIO-10'] }, // filter[code][in]=BIO-6,BIO-10
  },
  sort: '-publishedAt',               // or { field: 'publishedAt', order: 'desc' }
  page: 1,
  limit: 20,                          // sent as pageSize
});
console.log(meta.total, data.length);

npx citron-sdk typegen \
  --base-url https://api.console.citronos.com \
  --api-key "$CITRON_API_KEY" \
  --org your-org \
  --out src/citron.generated.ts

import { createClient } from '@citron/sdk';
import type { CitronCollections } from './citron.generated';

const citron = createClient<CitronCollections>({
  baseUrl: 'https://api.console.citronos.com',
  apiKey: process.env.CITRON_API_KEY,
  locale: 'en',
});

const { data } = await citron.collection('products').list({ filter: { category: 'station' } });
const name: string | null | undefined = data[0]?.data.name; // typed from the collection

// @ts-expect-error: a misspelt collection is a compile error
citron.collection('prodcts');

// persisted: true does both steps for you and uses GET by default
const data = await citron.graphql<{ products: { data: { slug: string | null }[]; meta: { total: number } } }>(
  'query ($n: Int) { products(pageSize: $n) { data { slug } meta { total } } }',
  { n: 10 },
  { persisted: true },
);
console.log(data.products.meta.total);

const types = await citron.booking.types({ orgSlug: 'your-org' });
const slots = await citron.booking.slots(
  { typeId: types[0].id, mode: 'online', from: new Date(), to: new Date(Date.now() + 14 * 86_400_000) },
  { orgSlug: 'your-org' },
);

const appointment = await citron.booking.book(
  {
    contact: { name: 'Ivan Petrov', email: 'ivan@example.com', phone: '+359888000000' },
    appointmentTypeId: types[0].id,
    staffUserId: slots[0].staffUserId,
    mode: 'online',
    startsAt: slots[0].startsAt,
  },
  { idempotencyKey, orgSlug: 'your-org' },
);
console.log(appointment.id, appointment.status);

import { constructWebhookEvent, WebhookVerificationError } from '@citron/sdk/webhooks';

// Any runtime with Request/Response: Node 18+, edge, Workers
export async function handleCitronWebhook(req: Request): Promise<Response> {
  const raw = await req.text(); // the RAW body: re-serialised JSON has different bytes
  try {
    const event = await constructWebhookEvent(raw, req.headers.get('x-citron-signature'), process.env.CITRON_WEBHOOK_SECRET!, {
      maxAgeSeconds: 24 * 3600, // optional; the signed "at" makes old deliveries refusable
    });
    console.log(event.event, event.collection, event.entry.slug);
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response(null, { status: 401 });
    throw err;
  }
}

import { CitronGraphQLError, isCitronError } from '@citron/sdk';

try {
  await citron.collection('products').get('does-not-exist');
} catch (err) {
  if (err instanceof CitronGraphQLError) {
    console.error(err.errors, err.data); // GraphQL errors and partial data
  } else if (isCitronError(err)) {
    console.error(err.status, err.code, err.message, err.requestId, err.details);
    if (err.isNotFound) { /* render your 404 */ }
    if (err.isRetryable) { /* 0, 408, 429 or 5xx; err.retryAfter when the server said */ }
  } else {
    throw err;
  }
}

// lib/citron.ts
import { createClient } from '@citron/sdk';
import { citronTags } from '@citron/sdk/next';

export const citron = createClient({
  baseUrl: process.env.CITRON_BASE_URL!,
  apiKey: process.env.CITRON_API_KEY!,
  locale: 'bg',
  richtext: 'html',
});

export const getProduct = (slug: string) =>
  citron.collection('products').find(slug, {
    populate: ['related'],
    fetchOptions: { next: { revalidate: 3600, tags: citronTags('products', slug) } },
  });