@solutiondesk/events 0.0.0-stage → 1.0.0-1edea54

package/dist/index.d.cts

@@ -0,0 +1,516 @@
+/**
+ * The HTTP part shared by the public SolutionDesk SDKs. Runs on any runtime with
+ * a WHATWG `fetch` (Node ≥ 18, Deno, Bun, edge runtimes, browsers) — and on
+ * purpose names no DOM or Node type, so the published `.d.ts` files need neither
+ * `lib: ["dom"]` nor `@types/node`.
+ */
+/** The production API. */
+declare const DEFAULT_BASE_URL = "https://api.solutiondesk.io";
+/** The response parts the SDK reads — what every `fetch` implementation returns. */
+interface FetchResponseLike {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** What the SDK passes to `fetch` (plus whatever you set in `fetchOptions`). */
+interface FetchInitLike {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/**
+ * A `fetch` implementation. The global `fetch` fits, so do `undici`, `node-fetch`
+ * and wrappers (e.g. one that adds tracing). Declared bivariantly so a fetch with
+ * a richer `init` type is accepted.
+ */
+type FetchLike = {
+    bivarianceHack(input: string, init?: FetchInitLike): Promise<FetchResponseLike>;
+}["bivarianceHack"];
+/** A response kept for `If-None-Match` revalidation. */
+interface CachedResponse {
+    etag: string;
+    body: unknown;
+}
+/**
+ * Where the client keeps answers for ETag revalidation. Any `Map` fits; bring
+ * your own to share it between clients or to bound it differently.
+ */
+interface EtagCache {
+    get(key: string): CachedResponse | undefined;
+    set(key: string, value: CachedResponse): unknown;
+}
+/** Options every client factory takes. */
+interface BaseClientOptions {
+    /** The API origin, without `/v1`. Defaults to `https://api.solutiondesk.io`. */
+    baseUrl?: string;
+    /** A `fetch` implementation; defaults to the global one. */
+    fetch?: FetchLike;
+    /** Headers sent with every request (e.g. `accept-language` forwarded from your visitor). */
+    headers?: Record<string, string>;
+    /**
+     * Revalidate with `If-None-Match`: the client remembers each answer's `ETag`
+     * and, when the API answers `304 Not Modified`, returns the remembered body.
+     * `true` keeps up to 500 answers in memory; or pass your own {@link EtagCache}.
+     * Off by default (your framework's fetch cache may already do this).
+     */
+    etagCache?: boolean | EtagCache;
+}
+/** Per-call options. */
+interface RequestOptions {
+    /** Cancels the request (an `AbortSignal`). */
+    signal?: unknown;
+    /** Extra headers for this request. */
+    headers?: Record<string, string>;
+    /**
+     * Extra `fetch` options for this request, passed through unchanged — e.g.
+     * Next.js `{ next: { revalidate: 60, tags: ["legal"] } }` or `{ cache: "no-store" }`.
+     */
+    fetchOptions?: Record<string, unknown>;
+}
+/** Any non-2xx answer of the API (and a failed network request, with `status` 0). */
+declare class SolutionDeskError extends Error {
+    /** The HTTP status; `0` when no answer arrived (network error, aborted). */
+    readonly status: number;
+    /** The parsed JSON body of the error answer (usually `{ error: string }`), else its text. */
+    readonly body: unknown;
+    /** The requested URL. */
+    readonly url: string;
+    /** Messages per input field on a `400` (e.g. `{ email: "Enter a valid email address." }`). */
+    readonly fields: Record<string, string>;
+    constructor(message: string, init: {
+        status: number;
+        body?: unknown;
+        url: string;
+        cause?: unknown;
+    });
+    /** `404`: unknown workspace, module turned off or unknown item — on purpose indistinguishable. */
+    get isNotFound(): boolean;
+    /** `429`: over the rate limit; try again later. */
+    get isRateLimited(): boolean;
+}
+/** A bounded in-memory {@link EtagCache} (oldest entry dropped first). */
+declare function createMemoryEtagCache(maxEntries?: number): EtagCache;
+
+/**
+ * Public blog and event images come in a fixed set of widths (`<url>?w=<width>`,
+ * WebP, never wider than the original); the API refuses any other width.
+ */
+declare const IMAGE_WIDTHS: readonly [320, 640, 960, 1280, 1920];
+type ImageWidth = (typeof IMAGE_WIDTHS)[number];
+/** The smallest offered width that is at least `width` (1920 for anything wider). */
+declare function imageWidthFor(width: number): ImageWidth;
+/**
+ * The address of an image at (at least) `width` pixels — e.g. for a Next.js
+ * custom image loader: `({ src, width }) => imageUrl(src, width)`. Without a
+ * width the original address is returned.
+ */
+declare function imageUrl(url: string, width?: number): string;
+
+/**
+ * Webhook signature check with Web Crypto only — the same code runs in Node,
+ * Deno, Bun, edge runtimes and browsers. The header SolutionDesk sends is
+ * `X-SolutionDesk-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`.
+ */
+/** The header that carries the signature. */
+declare const SIGNATURE_HEADER = "x-solutiondesk-signature";
+/** The header that names the event (also in the body as `event`). */
+declare const EVENT_HEADER = "x-solutiondesk-event";
+interface VerifyWebhookOptions {
+    /** How old (or how far in the future) the signed time may be. Default 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** "Now" in milliseconds (or a `Date`) — for tests. Default `Date.now()`. */
+    now?: number | Date;
+    /**
+     * A Web Crypto implementation. Default `globalThis.crypto`. On Node 18 pass
+     * `require("node:crypto").webcrypto` (Node 19+ has it globally).
+     */
+    crypto?: {
+        subtle: object;
+    };
+}
+/** The raw request body, exactly as received. */
+type WebhookBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Check a SolutionDesk webhook signature. `true` only when the header is well
+ * formed, its time lies within the tolerance and the HMAC matches — anything
+ * else (missing, tampered, expired, malformed) is `false`, never an exception.
+ *
+ * @param secret The webhook's signing secret (`whsec_…`), shown once in SolutionDesk.
+ * @param rawBody The request body exactly as received — not re-serialized JSON.
+ * @param header The `X-SolutionDesk-Signature` header.
+ */
+declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, header: string | null | undefined, options?: VerifyWebhookOptions): Promise<boolean>;
+/**
+ * Verify, then parse the body: the typed payload, or `null` when the signature
+ * doesn't check out (answer such a call with `400`/`401` and ignore it).
+ */
+declare function parseWebhook<T>(secret: string, rawBody: WebhookBody, header: string | null | undefined, options?: VerifyWebhookOptions): Promise<T | null>;
+
+/**
+ * The answers and inputs of the public event pages API
+ * (`/v1/event-pages/{workspace}/…`) and of the host registration route
+ * (`POST /v1/integration/events/{event}/registrations`). Written by hand so the
+ * package has no dependencies; a drift test in the SolutionDesk repository
+ * keeps them in line with the API's own contracts.
+ */
+/** An event image (cover or gallery). Public, cached for a year; a changed image gets a new address. */
+interface EventImageView {
+    id: string;
+    url: string;
+    /** Every web-ready width (WebP, `<url>?w=<width>`) for `<img srcset>`. */
+    srcset: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    /** Who made it, shown small on the image. */
+    credit: string | null;
+}
+/** A talk as visitors see it. */
+interface PublicEventSession {
+    id: string;
+    title: string;
+    description: string | null;
+    startsAt: string;
+    endsAt: string;
+    track: string | null;
+    speakers: {
+        name: string;
+        role: string | null;
+        bio: string | null;
+    }[];
+    /** May be picked in the form (published, selectable, not full). */
+    choosable: boolean;
+    /** Has a seat limit and no seat left. */
+    full: boolean;
+}
+/** A choice of a `select` / `multiselect` field. */
+interface FormOption {
+    id: string;
+    label: string;
+}
+interface FormFieldBase {
+    /** The key of this field's value in `answers`. */
+    id: string;
+    label: string;
+    help?: string | undefined;
+    required: boolean;
+}
+/**
+ * One of the event's own form questions. The value to send in `answers[id]`:
+ * text for `text`/`textarea`/`email`/`phone`, a number for `number`, `YYYY-MM-DD`
+ * for `date`, the option `id` for `select`, a list of option ids for
+ * `multiselect`, a list of session ids for `sessions`, `true` for a ticked
+ * `checkbox`/`consent`/`newsletter`.
+ */
+type FormField = (FormFieldBase & {
+    type: "text";
+    maxLength: number;
+}) | (FormFieldBase & {
+    type: "textarea";
+    maxLength: number;
+}) | (FormFieldBase & {
+    type: "email";
+}) | (FormFieldBase & {
+    type: "phone";
+}) | (FormFieldBase & {
+    type: "number";
+    min?: number | undefined;
+    max?: number | undefined;
+}) | (FormFieldBase & {
+    type: "date";
+}) | (FormFieldBase & {
+    type: "select";
+    options: FormOption[];
+}) | (FormFieldBase & {
+    type: "multiselect";
+    options: FormOption[];
+}) | (FormFieldBase & {
+    type: "checkbox";
+})
+/** A required box with its text and an optional link (privacy policy, photo consent …). */
+ | (FormFieldBase & {
+    type: "consent";
+    text: string;
+    linkUrl?: string | undefined;
+    required: true;
+})
+/** Pick talks from the programme (`sessions` with `choosable: true`). */
+ | (FormFieldBase & {
+    type: "sessions";
+})
+/** An optional, unticked box to subscribe to a newsletter (confirmed by its own mail). */
+ | (FormFieldBase & {
+    type: "newsletter";
+    listId: string;
+    required: false;
+    /** The list's consent text to show next to the box. */
+    text?: string | undefined;
+});
+type FormFieldType = FormField["type"];
+/** The registration form. First name, last name and email are always asked. */
+interface FormDefinition {
+    askCompany: boolean;
+    askJobTitle: boolean;
+    /** Only counts while `askCompany` is on. */
+    companyRequired: boolean;
+    /** Only counts while `askJobTitle` is on. */
+    jobTitleRequired: boolean;
+    fields: FormField[];
+}
+/** Whether a visitor can register right now, and if not why. */
+type PublicRegistrationState = {
+    open: true;
+    waitlist: boolean;
+} | {
+    open: false;
+    reason: "closed" | "invite_only" | "full" | "ended" | "cancelled";
+};
+/** The workspace an event belongs to. */
+interface PublicEventWorkspace {
+    name: string;
+    slug: string;
+    logoUrl: string | null;
+}
+/** An event with everything its page shows. */
+interface PublicEvent {
+    /** The language of the texts below (`lang`, else the visitor's, else the main one). */
+    locale: string;
+    /** The languages the event is offered in, main language first. */
+    languages: {
+        code: string;
+        label: string;
+    }[];
+    slug: string;
+    title: string;
+    /**
+     * Formatted text as safe HTML: paragraphs, headings, lists, links and
+     * emphasis — no styles, scripts or images. Style the tags yourself.
+     */
+    description: string | null;
+    /** The same as plain text, e.g. for previews and meta tags. */
+    descriptionText: string | null;
+    status: "published" | "registration_closed" | "ended" | "cancelled";
+    /** ISO times in UTC; show them in `timeZone`. */
+    startsAt: string;
+    endsAt: string;
+    timeZone: string;
+    /** Online events never expose their link here — it's sent after registering. */
+    location: {
+        kind: "onsite";
+        name: string | null;
+        address: string;
+    } | {
+        kind: "online";
+    };
+    access: "invite_only" | "open" | "open_with_approval";
+    /** The picture on top of the event; `null` when none is set. */
+    coverImage: EventImageView | null;
+    /** More pictures of the event, in the team's order. */
+    images: EventImageView[];
+    /** False for invite-only events whose programme is hidden from uninvited visitors. */
+    programmeVisible: boolean;
+    sessions: PublicEventSession[];
+    form: FormDefinition;
+    registration: PublicRegistrationState;
+}
+/** `GET /v1/event-pages/{workspace}/{event}[?invite=…]`. */
+interface PublicEventPayload {
+    workspace: PublicEventWorkspace;
+    event: PublicEvent;
+    /** Present with a valid invitation token: the email is fixed to it. */
+    invitation: {
+        email: string;
+        name: string | null;
+    } | null;
+}
+/** An event in the list: the page's facts and cover, without programme, form and gallery. */
+type PublicEventListItem = Omit<PublicEvent, "programmeVisible" | "sessions" | "form" | "images"> & {
+    /** The event page (on the workspace's events domain when it has one). */
+    url: string;
+};
+/** `GET /v1/event-pages/{workspace}[?when=upcoming|past]`. */
+interface PublicEventsListPayload {
+    workspace: PublicEventWorkspace;
+    /** Upcoming: soonest first. Past: latest first. At most 100. */
+    events: PublicEventListItem[];
+}
+/** One event's notice for your own website (a bar on top or a window in the middle). */
+interface PublicAnnouncement {
+    /** The event's slug. */
+    event: string;
+    /** The language of the texts. */
+    locale: string;
+    eventTitle: string;
+    startsAt: string;
+    endsAt: string;
+    timeZone: string;
+    style: "bar" | "modal";
+    title: string;
+    message: string | null;
+    buttonLabel: string;
+    /** The event's cover image; `null` when none is set. */
+    image: EventImageView | null;
+    /** Where the button leads (the event page unless the team set another page). */
+    url: string;
+    /** Bumped when the team shows it again to everyone; a closed round stays closed. */
+    round: number;
+    /** Only with `visitor`: that visitor already closed this round. */
+    dismissed?: boolean;
+}
+/** `GET /v1/event-pages/{workspace}/announcement`. */
+interface PublicAnnouncementsPayload {
+    announcements: PublicAnnouncement[];
+}
+/** A value in `answers` (see {@link FormField} for which type each field takes). */
+type RegistrationAnswer = string | number | boolean | string[];
+/** `POST /v1/event-pages/{workspace}/{event}/registrations` — what the public form sends. */
+interface PublicRegistrationInput {
+    firstName: string;
+    lastName: string;
+    email: string;
+    /** When the form asks for it (`askCompany`); required with `companyRequired`. */
+    company?: string;
+    /** When the form asks for it (`askJobTitle`); required with `jobTitleRequired`. */
+    jobTitle?: string;
+    /** Values of the event's own form fields, keyed by field `id`. */
+    answers?: Record<string, RegistrationAnswer>;
+    /** The invitation token from `?invite=`. */
+    invite?: string;
+    /** The language the person registered in (one of the event's `languages`); their mails use it. */
+    locale?: string;
+    /**
+     * Anti-bot honeypot: the value of a hidden "website" input that people never
+     * see. Must stay empty — a filled one is silently dropped (the answer still
+     * says `check_email`).
+     */
+    website?: string;
+    /**
+     * Anti-bot timer: milliseconds the form was open before sending. Under 1500
+     * is treated as a bot and silently dropped. Leave it out when you don't measure it.
+     */
+    elapsedMs?: number;
+}
+/**
+ * What happened. Public sign-ups always get `check_email` — whether the address
+ * was new, already registered or invalid stays private.
+ */
+interface PublicRegistrationResult {
+    result: "check_email" | "confirmed" | "pending_approval" | "waitlisted";
+}
+/**
+ * `POST /v1/integration/events/{event}/registrations` — your server registers
+ * someone who is signed in to your product; you vouch for the email, so no
+ * confirmation mail is sent.
+ */
+type HostRegistrationInput = Omit<PublicRegistrationInput, "website" | "elapsedMs" | "invite">;
+
+interface EventsClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/event-pages/acme`. */
+    workspace: string;
+    /**
+     * The language to show events in by default (any of an event's `languages`).
+     * Without it the request's `Accept-Language` decides, then the event's main
+     * language. Override per call.
+     */
+    lang?: string;
+}
+interface LangParams {
+    /** The language to ask for; overrides the client's `lang`. */
+    lang?: string;
+}
+interface ListEventsParams extends LangParams {
+    /** `upcoming` (default): not ended yet, soonest first. `past`: ended, latest first. */
+    when?: "upcoming" | "past";
+}
+interface GetEventParams extends LangParams {
+    /** The invitation token from an invitation link (`?invite=`): fixes the email, shows a hidden programme. */
+    invite?: string;
+}
+interface AnnouncementParams extends LangParams {
+    /** Only this event's announcement (its slug). */
+    event?: string;
+    /**
+     * Your signed-in user as a SHA-256 hex digest (64 characters) of their id —
+     * answers then carry `dismissed` for announcements they closed on any device.
+     */
+    visitor?: string;
+}
+interface DismissAnnouncementInput {
+    /** The event's slug. */
+    event: string;
+    /** The same SHA-256 hex digest as in {@link AnnouncementParams.visitor}. */
+    visitor: string;
+    /** The announcement's `round`. */
+    round: number;
+}
+interface EventsClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /**
+     * The workspace's published events (`GET /v1/event-pages/{workspace}`), at most
+     * 100. Invite-only events are never listed.
+     */
+    listEvents(params?: ListEventsParams, options?: RequestOptions): Promise<PublicEventsListPayload>;
+    /**
+     * Everything on an event's page (`GET /v1/event-pages/{workspace}/{event}`),
+     * including the registration form. Throws a `SolutionDeskError` with status
+     * 404 for an unknown or unpublished event.
+     */
+    getEvent(slug: string, params?: GetEventParams, options?: RequestOptions): Promise<PublicEventPayload>;
+    /** The events' announcements for your own website, soonest event first. */
+    getAnnouncements(params?: AnnouncementParams, options?: RequestOptions): Promise<PublicAnnouncementsPayload>;
+    /** Remember that a known visitor closed an announcement (this round). */
+    dismissAnnouncement(input: DismissAnnouncementInput, options?: RequestOptions): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Register someone the way the public form does
+     * (`POST /v1/event-pages/{workspace}/{event}/registrations`). The person
+     * confirms by email; the answer is `{ result: "check_email" }` either way.
+     *
+     * From a browser this only works on the websites listed under Event
+     * settings → Your websites (CORS). Send the anti-bot fields `website`
+     * (honeypot, empty) and `elapsedMs`. A wrong answer throws a
+     * `SolutionDeskError` with status 400 and `fields` (field id → message).
+     * Limited to 10 registrations per IP address in 10 minutes and 3 an hour
+     * per email address.
+     */
+    register(slug: string, input: PublicRegistrationInput, options?: RequestOptions): Promise<PublicRegistrationResult>;
+    /** The address of an event image at (at least) `width` pixels: 320, 640, 960, 1280 or 1920. */
+    imageUrl(url: string, width?: number): string;
+}
+/**
+ * A client for the public event pages — no key, no login; only published
+ * events. Safe in the browser and on the server.
+ *
+ * @example
+ * const events = createEventsClient({ workspace: "acme", lang: "en" });
+ * const { events: upcoming } = await events.listEvents();
+ */
+declare function createEventsClient(options: EventsClientOptions): EventsClient;
+interface EventsHostClientOptions extends Omit<BaseClientOptions, "etagCache"> {
+    /** An API key of your workspace (Settings → API keys). Keep it on your server. */
+    apiKey: string;
+}
+interface EventsHostClient {
+    /**
+     * Register someone who is signed in to your product
+     * (`POST /v1/integration/events/{event}/registrations`). You vouch for the
+     * email, so the registration is placed at once — no confirmation mail —
+     * with the same rules otherwise: access, capacity, waiting list, required
+     * form answers. Answers `confirmed`, `pending_approval` or `waitlisted`; the
+     * person gets a mail with a link to change or cancel.
+     */
+    register(slug: string, input: HostRegistrationInput, options?: RequestOptions): Promise<PublicRegistrationResult>;
+}
+/**
+ * **Server only.** A client for the events part of the host API, authenticated
+ * with your workspace's API key (`Authorization: Bearer …`). Never ship the key
+ * to a browser.
+ */
+declare function createEventsHostClient(options: EventsHostClientOptions): EventsHostClient;
+
+export { type AnnouncementParams, type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, type DismissAnnouncementInput, EVENT_HEADER, type EtagCache, type EventImageView, type EventsClient, type EventsClientOptions, type EventsHostClient, type EventsHostClientOptions, type FetchInitLike, type FetchLike, type FetchResponseLike, type FormDefinition, type FormField, type FormFieldType, type FormOption, type GetEventParams, type HostRegistrationInput, IMAGE_WIDTHS, type ImageWidth, type LangParams, type ListEventsParams, type PublicAnnouncement, type PublicAnnouncementsPayload, type PublicEvent, type PublicEventListItem, type PublicEventPayload, type PublicEventSession, type PublicEventWorkspace, type PublicEventsListPayload, type PublicRegistrationInput, type PublicRegistrationResult, type PublicRegistrationState, type RegistrationAnswer, type RequestOptions, SIGNATURE_HEADER, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createEventsClient, createEventsHostClient, createMemoryEtagCache, imageUrl, imageWidthFor, parseWebhook, verifyWebhookSignature };