@seatlayer/server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,637 @@
+/**
+ * Typed errors.
+ *
+ * The API answers failures with `{ error, code?, message? }` and a status. A
+ * generated client would surface that as one opaque exception and leave every
+ * caller string-matching on `error`. The cases below are the ones an
+ * integration actually branches on — a sold-out seat is a business outcome that
+ * belongs in an `if`, not in a `catch` that also swallows a bad key.
+ */
+/** Raw error envelope as the API sends it. */
+interface ApiErrorBody {
+    error?: string;
+    code?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+declare class SeatLayerError extends Error {
+    readonly status: number;
+    /** Machine-readable code: `body.code ?? body.error`. */
+    readonly code: string;
+    readonly body: ApiErrorBody;
+    /** Correlation id from `X-Request-ID`. Quote it in support requests. */
+    readonly requestId: string | null;
+    constructor(status: number, body: ApiErrorBody, requestId: string | null);
+}
+/** 401/403 — bad key, revoked key, or a live key used against a test event. */
+declare class SeatLayerAuthError extends SeatLayerError {
+    constructor(status: number, body: ApiErrorBody, requestId: string | null);
+    /**
+     * True when the key's mode and the event's mode disagree — the most common
+     * cause of a "works locally, 403s in production" report.
+     */
+    get isModeMismatch(): boolean;
+}
+declare class SeatLayerNotFoundError extends SeatLayerError {
+    constructor(status: number, body: ApiErrorBody, requestId: string | null);
+}
+/**
+ * 409 — the seats moved under you. This is a normal outcome in ticketing, not
+ * an exceptional one: two buyers wanted the same seat and one lost.
+ */
+declare class SeatLayerConflictError extends SeatLayerError {
+    /** Per-object conflicts, when the endpoint reports them. */
+    readonly conflicts: Array<{
+        label: string;
+        status: string;
+    }>;
+    constructor(status: number, body: ApiErrorBody, requestId: string | null);
+    /** True when best-available could not find enough free inventory. */
+    get isSoldOut(): boolean;
+}
+/** 422 — the request was understood and rejected. */
+declare class SeatLayerValidationError extends SeatLayerError {
+    constructor(status: number, body: ApiErrorBody, requestId: string | null);
+}
+/**
+ * 429. `retryAfterSeconds` comes from the `Retry-After` header when present and
+ * falls back to the JSON field, so callers get a real number either way.
+ */
+declare class SeatLayerRateLimitError extends SeatLayerError {
+    readonly retryAfterSeconds: number;
+    constructor(status: number, body: ApiErrorBody, requestId: string | null, retryAfterSeconds: number);
+}
+/** The request never got an answer: DNS, TLS, socket, or an abort. */
+declare class SeatLayerConnectionError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+
+/**
+ * The transport: auth, idempotency, retry, and error mapping.
+ *
+ * This is the layer that decides how the SDK behaves when the network or the
+ * API misbehaves, which is most of what separates a usable client from a thin
+ * `fetch` wrapper.
+ */
+
+interface ClientOptions {
+    /** `sk_live_…` or `sk_test_…`. Never expose this to a browser. */
+    secretKey: string;
+    /** Override for self-hosted or staging. Defaults to the public API. */
+    baseUrl?: string;
+    /** Total attempts for retryable failures. Default 3 (two retries). */
+    maxRetries?: number;
+    /** Per-request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    /** Injectable for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Explicit Idempotency-Key. Omit and mutating requests get a generated one —
+     * see `shouldSendIdempotencyKey`.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    #private;
+    readonly baseUrl: string;
+    /** Whether this client is pointed at test-mode or live-mode data. */
+    readonly mode: 'live' | 'test' | 'unknown';
+    constructor(options: ClientOptions);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+/** Shared shapes. Kept hand-written so the names read like the docs. */
+type KeyMode = 'live' | 'test';
+interface ChartMeta {
+    id: string;
+    name: string;
+    status: string;
+    workspaceId?: string;
+    externalRef?: string | null;
+    updatedAt: number;
+    createdAt: number;
+    [key: string]: unknown;
+}
+interface Chart {
+    meta: ChartMeta;
+    /** The chart document. Authored in the Designer; opaque to most backends. */
+    doc?: Record<string, unknown>;
+}
+interface EventMeta {
+    key: string;
+    id: string;
+    chartId: string;
+    name?: string;
+    slug?: string | null;
+    startsAt?: number | null;
+    venue?: string | null;
+    currency?: string | null;
+    externalRef?: string | null;
+    [key: string]: unknown;
+}
+/** A priced line item. `unitPrice` is in `currency`, not in minor units. */
+interface HoldLineItem {
+    label: string;
+    objectId: string;
+    objectType: 'seat' | 'booth' | 'ga' | 'table';
+    categoryKey: string;
+    tierId: string | null;
+    unitPrice: number;
+    currency: string;
+    quantity?: number;
+    capacity?: number;
+}
+interface HoldResult {
+    ok: true;
+    holdId: string;
+    /** Epoch ms. The hold is gone after this unless booked or extended. */
+    expiresAt: number;
+    items: HoldLineItem[];
+    labels?: string[];
+}
+interface BookResult {
+    ok: true;
+    labels?: string[];
+    items?: HoldLineItem[];
+    bookingRef?: string;
+}
+interface Workspace {
+    id: string;
+    name: string;
+    status: 'active' | 'disabled';
+    isDefault: boolean;
+    externalRef?: string | null;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    status?: string;
+    [key: string]: unknown;
+}
+/**
+ * What a manage-session token is allowed to do in the browser.
+ *
+ * `event:cancel` un-books paid inventory. It is separated from `event:block`
+ * deliberately — a box-office view that only needs to hold seats back should
+ * never be able to cancel a sale.
+ */
+type ManageCapability = 'event:view' | 'event:block' | 'event:cancel' | 'event:reports';
+interface ManageSession {
+    token: string;
+    expiresAt: number;
+    capabilities: ManageCapability[];
+    [key: string]: unknown;
+}
+interface DesignerSession {
+    token: string;
+    expiresAt: number;
+    [key: string]: unknown;
+}
+
+interface ChartListOptions {
+    workspaceId?: string;
+    externalRef?: string;
+    archived?: boolean;
+    /** Page size. Clamped server-side; asking for more is not an error. */
+    limit?: number;
+    cursor?: string;
+}
+interface ChartPage {
+    charts: ChartMeta[];
+    /** Absent once the list is exhausted. */
+    nextCursor?: string;
+}
+/**
+ * Charts are the seat-map definitions events are created from.
+ *
+ * If your organisers draw their own venues in the embedded Designer, you still
+ * need this: `createDesignerSession` requires a chartId that must already
+ * exist, so the usual platform flow is copy a template here, then hand the
+ * organiser a Designer session for it.
+ */
+declare class Charts {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * One page of charts. Pass `cursor` from the previous page's `nextCursor`;
+     * its absence means the list is exhausted.
+     */
+    list(options?: ChartListOptions): Promise<ChartPage>;
+    /**
+     * Every chart, paging transparently.
+     *
+     * An async iterator rather than an array: the whole point of paginating was
+     * to stop loading an unbounded list into memory, and returning `ChartMeta[]`
+     * would hand that problem straight back to the caller.
+     *
+     *   for await (const chart of seatlayer.charts.listAll()) { … }
+     */
+    listAll(options?: Omit<ChartListOptions, 'cursor'>): AsyncGenerator<ChartMeta>;
+    create(params: {
+        name: string;
+        doc?: Record<string, unknown>;
+        externalRef?: string;
+        workspaceId?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        meta: ChartMeta;
+    }>;
+    retrieve(chartId: string): Promise<Chart>;
+    /**
+     * Replace a chart document.
+     *
+     * `expectedUpdatedAt` is required by the API for optimistic concurrency and
+     * is not optional here either: without it two concurrent writers silently
+     * overwrite each other, and a seat map is exactly the kind of document where
+     * that loses work. Read it from `retrieve()` immediately before writing.
+     *
+     * The Designer is the authoring surface. Reach for this for bulk programmatic
+     * edits and migrations, not for drawing.
+     */
+    update(chartId: string, params: {
+        doc: Record<string, unknown>;
+        expectedUpdatedAt: number;
+        name?: string;
+    }): Promise<{
+        meta: ChartMeta;
+    }>;
+    delete(chartId: string): Promise<void>;
+    /** Copy a chart — the usual way to provision a venue from a template. */
+    copy(chartId: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        meta: ChartMeta;
+    }>;
+    archive(chartId: string): Promise<{
+        meta: ChartMeta;
+    }>;
+    unarchive(chartId: string): Promise<{
+        meta: ChartMeta;
+    }>;
+    /** Publish the draft. An event can only be created from a published chart. */
+    publish(chartId: string): Promise<{
+        meta: ChartMeta;
+    }>;
+}
+
+interface EventListOptions {
+    workspaceId?: string;
+    externalRef?: string;
+    /** Page size. Clamped server-side; asking for more is not an error. */
+    limit?: number;
+    cursor?: string;
+    /** Include live availability counts. One server round-trip per event. */
+    counts?: boolean;
+}
+interface EventPage {
+    events: EventMeta[];
+    /** Absent once the list is exhausted. */
+    nextCursor?: string;
+}
+declare class Events {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * One page of events. Pass `cursor` from the previous page's `nextCursor`.
+     *
+     * Live availability `counts` cost one round-trip per event server-side. They
+     * are included by default because most callers want them; pass
+     * `counts: false` when paging a whole catalogue, where you almost certainly
+     * do not.
+     */
+    list(options?: EventListOptions): Promise<EventPage>;
+    /**
+     * Every event, paging transparently. Defaults to `counts: false` — you are
+     * walking the whole list, so per-event availability is rarely what you want
+     * and always what it costs.
+     *
+     *   for await (const event of seatlayer.events.listAll()) { … }
+     */
+    listAll(options?: Omit<EventListOptions, 'cursor'>): AsyncGenerator<EventMeta>;
+    create(params: {
+        chartId: string;
+        name?: string;
+        slug?: string;
+        startsAt?: number;
+        venue?: string;
+        externalRef?: string;
+        /** Three-letter override. Defaults to the organisation currency. */
+        currency?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        meta: EventMeta;
+    }>;
+    retrieve(eventKey: string): Promise<{
+        meta: EventMeta;
+        counts?: Record<string, number>;
+    }>;
+    update(eventKey: string, params: Record<string, unknown>): Promise<{
+        meta: EventMeta;
+    }>;
+    delete(eventKey: string): Promise<void>;
+    /** Move a live event onto the latest published version of its chart. */
+    updateChart(eventKey: string): Promise<unknown>;
+    /** Stop buyer sales. Existing holds keep their TTL. */
+    close(eventKey: string): Promise<unknown>;
+    reopen(eventKey: string): Promise<unknown>;
+    archive(eventKey: string): Promise<unknown>;
+    /** Read the checkout window (ms) buyers get for this event. */
+    retrieveHoldTtl(eventKey: string): Promise<{
+        holdTtlMs: number;
+    }>;
+    updateHoldTtl(eventKey: string, holdTtlMs: number): Promise<unknown>;
+    retrieveReport(eventKey: string): Promise<unknown>;
+    retrieveLog(eventKey: string): Promise<unknown>;
+}
+
+/**
+ * Holds, booking, blocking, availability.
+ *
+ * Two complete flows, both first-class:
+ *
+ *   browser holds → `retrieveHold` for authoritative pricing → charge → `book({holdId})`
+ *   backend books labels directly — box office, phone sales, comps
+ *
+ * Never price from what the browser tells you. `retrieveHold` is the
+ * authoritative answer, which is why it exists as a separate call.
+ */
+declare class Inventory {
+    #private;
+    constructor(http: HttpClient);
+    hold(eventKey: string, params: {
+        labels?: string[];
+        selections?: Array<{
+            label: string;
+            tierId?: string | null;
+            quantity?: number;
+        }>;
+        /** Overrides the event's checkout window for this hold. */
+        ttlMs?: number;
+        replaceHoldId?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<HoldResult>;
+    /**
+     * Ask us to pick the best free objects and hold them.
+     *
+     * The picker is the same one the buyer widget uses, so a phone order and a
+     * web order get the same answer for the same inventory. `qty` above the
+     * server cap is clamped, not rejected.
+     */
+    holdBestAvailable(eventKey: string, params: {
+        qty: number;
+        categoryKey?: string;
+        zoneId?: string;
+        ttlMs?: number;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<HoldResult>;
+    /**
+     * Pick and book in one call — the box-office shape, where payment is already
+     * taken and there is no buyer session to hold against.
+     *
+     * Prefer this over holdBestAvailable-then-book for that case: a failure
+     * between the two calls would strand inventory until the TTL expired.
+     */
+    bookBestAvailable(eventKey: string, params: {
+        qty: number;
+        bookingRef: string;
+        categoryKey?: string;
+        zoneId?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<BookResult>;
+    /**
+     * Push an active hold's expiry out by a fresh window before it lapses.
+     *
+     * Use this rather than release-and-re-hold when an order is taking longer
+     * than the checkout window — invoiced sales, a phone order on hold. Releasing
+     * first hands the seats to whoever is racing for them in between. The server
+     * clamps the window and the DO caps how many times one hold can be renewed;
+     * a hold that is gone, expired, or at its cap answers 409 `cannot_extend`.
+     */
+    extendHold(eventKey: string, params: {
+        holdId: string;
+        ttlMs?: number;
+    }): Promise<HoldResult>;
+    /** Authoritative items and prices for a hold. Charge from this, not the browser. */
+    retrieveHold(eventKey: string, holdId: string): Promise<{
+        items: HoldLineItem[];
+        expiresAt: number;
+        currency: string;
+    }>;
+    /** Free a hold early. Requires both the labels and the hold id. */
+    release(eventKey: string, params: {
+        labels: string[];
+        holdId: string;
+    }): Promise<unknown>;
+    book(eventKey: string, params: {
+        /** Book a held selection… */
+        holdId?: string;
+        /** …or book labels outright, with no prior hold. */
+        labels?: string[];
+        bookingRef?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<BookResult>;
+    boxOfficeBook(eventKey: string, params: {
+        labels: string[];
+        bookingRef: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<BookResult>;
+    /** Reverse a booking. Requires a key with cancel authority. */
+    unbook(eventKey: string, params: {
+        labels: string[];
+    }): Promise<unknown>;
+    /** Hold inventory back from sale (house seats, holds for production). */
+    block(eventKey: string, params: {
+        labels: string[];
+    }): Promise<unknown>;
+    unblock(eventKey: string, params: {
+        labels: string[];
+    }): Promise<unknown>;
+    unblockAll(eventKey: string): Promise<unknown>;
+    retrieveAvailability(eventKey: string): Promise<unknown>;
+    updateAvailability(eventKey: string, params: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * Short-lived, origin-bound browser tokens.
+ *
+ * The governing rule of this SDK: **it mints tokens, widgets consume them.**
+ * Your secret key never reaches a browser. You mint a scoped token here, hand
+ * it to your frontend, and our widget uses that.
+ */
+declare class Sessions {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Mint a manage-session token for the control room.
+     *
+     * `capabilities` is required here even though the API defaults it. That
+     * default grants all four — including `event:cancel`, which un-books paid
+     * inventory. Granting the ability to reverse sales by forgetting an argument
+     * is not a default worth inheriting, so this SDK makes you say it.
+     *
+     * `allowedOrigin` must be an https origin; the token is bound to it.
+     */
+    createManageSession(eventKey: string, params: {
+        allowedOrigin: string;
+        capabilities: ManageCapability[];
+        /** 300–14400. Defaults to 3600 server-side. */
+        expiresInSeconds?: number;
+    }): Promise<ManageSession>;
+    /** Revoke a manage token before it expires (staff logout, permission change). */
+    revokeManageSession(eventKey: string, sessionId: string): Promise<void>;
+    /**
+     * Mint a designer-session token so an organiser can edit a chart inside your
+     * own UI. Requires a chartId that already exists — create or copy one first.
+     */
+    createDesignerSession(params: {
+        workspaceId: string;
+        chartId: string;
+        allowedOrigin: string;
+        authority?: 'read-only' | 'edit' | 'publish';
+        mode?: 'normal' | 'safe';
+        expiresInSeconds?: number;
+    }): Promise<DesignerSession>;
+    revokeDesignerSession(sessionId: string): Promise<void>;
+}
+
+declare class Webhooks {
+    #private;
+    constructor(http: HttpClient);
+    list(): Promise<{
+        webhooks: Webhook[];
+    }>;
+    create(params: {
+        url: string;
+        events: string[];
+    }): Promise<{
+        webhook: Webhook;
+        secret?: string;
+    }>;
+    update(webhookId: string, params: Partial<{
+        url: string;
+        events: string[];
+        status: string;
+    }>): Promise<{
+        webhook: Webhook;
+    }>;
+    delete(webhookId: string): Promise<void>;
+    listDeliveries(webhookId: string): Promise<{
+        deliveries: unknown[];
+    }>;
+}
+
+/**
+ * Workspaces isolate one tenant's charts and events from another's. A platform
+ * typically provisions one per organiser at signup and disables it on churn.
+ */
+declare class Workspaces {
+    #private;
+    constructor(http: HttpClient);
+    list(): Promise<{
+        workspaces: Workspace[];
+    }>;
+    create(params: {
+        name: string;
+        externalRef?: string;
+    }, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        workspace: Workspace;
+    }>;
+    retrieve(workspaceId: string): Promise<{
+        workspace: Workspace;
+    }>;
+    /**
+     * Rename, re-reference, or disable a workspace.
+     *
+     * The organisation's default workspace cannot be disabled — the API answers
+     * 409 `default_workspace_required`. Promote another one first.
+     */
+    update(workspaceId: string, params: Partial<{
+        name: string;
+        externalRef: string | null;
+        status: 'active' | 'disabled';
+        isDefault: true;
+    }>): Promise<{
+        workspace: Workspace;
+    }>;
+}
+
+interface VerifyWebhookOptions {
+    /**
+     * The raw request body, exactly as received — a string or Buffer, never a
+     * parsed object. Express: `express.raw({ type: 'application/json' })`.
+     */
+    payload: string | Uint8Array;
+    /** The `X-SeatLayer-Signature` header value (`sha256=<hex>`). */
+    signature: string | null | undefined;
+    /** The signing secret from webhook creation. */
+    secret: string;
+}
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a delivery and return its parsed payload.
+ *
+ * Throws `WebhookVerificationError` on any failure — treat that as "this did
+ * not come from SeatLayer" and respond 400 without processing it.
+ *
+ * NOTE ON REPLAY: deliveries are currently signed over the body only, with no
+ * timestamp header and so no tolerance window. Replay protection is therefore
+ * yours to enforce: every event carries an `occurrenceId`, and the correct
+ * pattern is to record processed ids and ignore repeats. Do not skip this — a
+ * captured delivery stays valid indefinitely.
+ */
+declare function verifyWebhook<T = Record<string, unknown>>(options: VerifyWebhookOptions): T;
+
+/**
+ * SeatLayer server SDK.
+ *
+ * Secret-key only. This package must never be bundled into a browser — see the
+ * session-minting helpers for how browser surfaces get scoped tokens instead.
+ */
+
+declare class SeatLayer {
+    #private;
+    readonly charts: Charts;
+    readonly events: Events;
+    readonly inventory: Inventory;
+    readonly sessions: Sessions;
+    readonly webhooks: Webhooks;
+    readonly workspaces: Workspaces;
+    /** `test` or `live`, derived from the key prefix. */
+    readonly mode: 'live' | 'test' | 'unknown';
+    constructor(options: ClientOptions | string);
+    /** Dependency-aware readiness probe. Unauthenticated upstream. */
+    ready(): Promise<{
+        ok: boolean;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Escape hatch for surface this SDK does not wrap yet. Carries the same auth,
+     * retry, idempotency and error mapping as everything else.
+     */
+    request<T>(method: string, path: string, options?: Parameters<HttpClient['request']>[2]): Promise<T>;
+}
+
+export { type ApiErrorBody, type BookResult, type Chart, type ChartMeta, type ClientOptions, type DesignerSession, type EventMeta, type HoldLineItem, type HoldResult, type KeyMode, type ManageCapability, type ManageSession, type RequestOptions, SeatLayer, SeatLayerAuthError, SeatLayerConflictError, SeatLayerConnectionError, SeatLayerError, SeatLayerNotFoundError, SeatLayerRateLimitError, SeatLayerValidationError, type VerifyWebhookOptions, type Webhook, WebhookVerificationError, type Workspace, SeatLayer as default, verifyWebhook };