@seatlayer/js 0.39.0 → 0.41.0

package/dist/index.d.ts

@@ -185,6 +185,176 @@ declare function createBuyerAccessContext(options: {
     buyerAccessToken?: string | BuyerAccessToken;
 }, hooks?: Pick<BuyerAccessContextOptions, 'onExpired' | 'onUnavailable'>): BuyerAccessContext | null;
 
+/**
+ * BuyerRealtimeClient — the client half of `docs/realtime-protocol-2026-08-01.md`.
+ *
+ * Why this exists as a separate socket rather than inside PickerController:
+ * a private scope authenticates with a one-use **subscribe ticket** carried in
+ * `Sec-WebSocket-Protocol`, and a browser can only set that at construction —
+ * `new WebSocket(url, protocols)`. The controller's socket is built from a URL
+ * alone (`PickerTransport.socketUrl`), and a bearer must never travel in a URL
+ * because URLs are routinely logged. So an access-scoped picker asks the
+ * transport for an empty `socketUrl()` (the controller then skips its own
+ * connection entirely) and this client owns the wire instead.
+ *
+ * A tokenless public picker never reaches this file. It keeps the controller's
+ * original socket, offers no subprotocol, and therefore receives byte-for-byte
+ * the frames it received before this module existed (protocol doc §1).
+ *
+ * What it implements:
+ *  - protocol negotiation: offer `seatlayer.v1`, believe the 101 echo, and fall
+ *    back to legacy frame handling when the server (or a proxy) does not echo;
+ *  - the ticket exchange, one mint per connection attempt, ticket in the
+ *    subprotocol list and never in the URL;
+ *  - compact `{default, exceptions}` snapshot reconstruction;
+ *  - `sv.<n>` resume, handling BOTH outcomes (a `resumed` delta or a full
+ *    snapshot) on every reconnect;
+ *  - close code 4401 as a typed access-revoked state, never a reconnect loop;
+ *  - liveness by ping/pong only. Silence is normal and carries no information
+ *    (protocol doc §5) — a quiet socket is never treated as a dead one.
+ */
+
+/** The projected status of one unit, as the server words it on the wire. */
+type WireStatus = string;
+/** A scope's projection: one default plus the units that differ from it. */
+interface Projection {
+    default: WireStatus;
+    exceptions: Record<string, WireStatus>;
+}
+interface StatusChange {
+    label: string;
+    status: WireStatus;
+}
+/** Where reconstructed inventory goes. Implemented over PickerController. */
+interface RealtimeSink {
+    /** Apply a batch of label→status changes. Implementations must paint this as
+     *  ONE pass, not one pass per label (motion system §4 rule 2). */
+    applyStatuses(changes: StatusChange[]): void;
+    /** Re-pull authoritative state over the scoped HTTP route. Used when a frame
+     *  cannot be diffed against what we hold (first snapshot, or the scope's
+     *  default itself changed, which redefines every unit we were never told
+     *  about). */
+    resync(): void | Promise<void>;
+    /** Section availability changed (channel-agnostic; identical for every scope). */
+    onSections?(hidden: string[], closed: string[]): void;
+    /** Scope-projected presence counters. */
+    onPresence?(counts: {
+        shoppingSessions: number;
+        activeHolds: number;
+    }): void;
+}
+interface SubscribeTicket$1 {
+    ticket?: string;
+    /** Exactly what to hand `new WebSocket(url, protocols)`, per protocol doc §3. */
+    protocols?: string[];
+}
+interface BuyerRealtimeOptions {
+    /** The subscribe URL. Must never carry a credential — asserted below. */
+    url: string;
+    sink: RealtimeSink;
+    /** Mint a one-use ticket for THIS connection attempt. Returns null for the
+     *  anonymous public case (no ticket needed). Throwing stops the client. */
+    mintTicket?: () => Promise<SubscribeTicket$1 | null>;
+    /** Typed access states. 4401 arrives here as `revoked`. */
+    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    /** Test seam. Defaults to the global WebSocket. */
+    socketFactory?: (url: string, protocols: string[]) => WebSocket;
+    /** Test seam for the keepalive/backoff timers. */
+    now?: () => number;
+}
+declare class BuyerRealtimeClient {
+    private readonly opts;
+    private ws;
+    private stopped;
+    private attempt;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private resumeTimer;
+    /** Our model of this scope's projection. Null until the first snapshot. */
+    private projection;
+    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
+    private version;
+    /** True once the 101 echoed `seatlayer.v1`. */
+    private v1;
+    /** Set when we offered v1 and the handshake came back without it — a proxy
+     *  most likely stripped the header, so the next attempt selects the v1 frame
+     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
+     *  selects a format and can never carry a credential or widen a scope. */
+    private useQueryMarker;
+    private hidden;
+    private closedSections;
+    constructor(options: BuyerRealtimeOptions);
+    /** Negotiated protocol, for tests and diagnostics. */
+    get protocol(): 'v1' | 'legacy' | null;
+    get snapshotVersion(): number | null;
+    start(): void;
+    /** Stop for good (destroy, or a revocation). Safe to call twice. */
+    stop(): void;
+    /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
+    restart(): void;
+    private connect;
+    private handleFrame;
+    /** The server answered our resume; cancel the fallback resync. */
+    private answered;
+    private reportIfAccessError;
+    /**
+     * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
+     * for minutes is the normal, correct state for a narrowly-scoped buyer on a
+     * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+     */
+    private startKeepalive;
+    /**
+     * FULL jitter, not plain exponential backoff.
+     *
+     * A deterministic `2**attempt` schedule makes every browser that lost the same
+     * socket — a worker redeploy, a DO eviction, a flaky edge PoP — come back in
+     * the same millisecond, and an on-sale crowd reconnecting in lockstep is the
+     * thing that turns one blip into a self-sustaining thundering herd. Full
+     * jitter (`random() * ceiling`) spreads the same crowd across the whole
+     * window; the ceiling still doubles, so a persistent outage still backs off.
+     *
+     * `Math.random` is correct here: this is client code choosing a delay, not a
+     * Workflow step that has to replay deterministically.
+     */
+    private scheduleReconnect;
+    private clearPongTimer;
+    private clearTimers;
+}
+/**
+ * The slice of PickerController this module drives. Structural on purpose — it
+ * keeps this file free of an `@seatlayer/core` import, and every member here is
+ * public controller API, so nothing in the engine mirror has to change.
+ */
+interface PickerControllerLike {
+    idForLabel(label: string): string | undefined;
+    tableSelection(seatIdOrLabel: string): {
+        physicalSeatIds: string[];
+    } | null;
+    setStatus(ids: string[], status: 'free' | 'held' | 'booked' | 'not_for_sale'): void;
+    getStatus(id: string): string | undefined;
+    flashSeat(id: string, color?: string): void;
+    currentHold(): {
+        labels: string[];
+    } | null;
+    getSelection(): Array<{
+        id: string;
+        label: string;
+    }>;
+    deselect(ids: string[]): void;
+    refresh(): Promise<void>;
+}
+interface ControllerSinkOptions {
+    /** Pulse seats other buyers take, as the controller's own socket does. */
+    flashOnLiveChange?: boolean;
+    /** Selected-but-unheld units that stopped being selectable. */
+    onSelectedObjectUnavailable?: (labels: string[], reason: 'ineligible' | 'taken') => void;
+    /** Section availability changed and the chart itself needs rebuilding. */
+    onSections?: (hidden: string[], closed: string[]) => void;
+    onStatusChange?: () => void;
+}
+declare function createControllerSink(controller: PickerControllerLike, options?: ControllerSinkOptions): RealtimeSink;
+
 /**
  * Minimal client for the public embed surface of workers/api (the `/pub/*`
  * routes). Deliberately self-contained — it does NOT reuse src/lib/api.ts,
@@ -217,7 +387,15 @@ declare class ApiError extends Error {
     conflicts?: HoldConflict[];
     /** Present when best-available 409s ('not_enough_together' | 'sold_out'). */
     reason?: string;
-    constructor(status: number, message: string, code?: string, conflicts?: HoldConflict[], reason?: string);
+    /**
+     * Seconds the server asked the caller to wait, off a 429's `Retry-After`.
+     *
+     * Present ONLY on a rate-limit error, and it is the server's number — never a
+     * guess. A widget that catches this can say "try again in N seconds" instead
+     * of rendering the blank map a swallowed 429 used to produce.
+     */
+    retryAfterS?: number;
+    constructor(status: number, message: string, code?: string, conflicts?: HoldConflict[], reason?: string, retryAfterS?: number);
 }
 interface HoldResult {
     holdId: string;
@@ -425,6 +603,21 @@ interface SeatingChartOptions {
      */
     onSelectedObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
     onError?: (err: unknown) => void;
+    /**
+     * What the BUYER sees when the chart cannot load.
+     *
+     * `'message'` (the default) renders a plain, styleable notice with a Try
+     * again button. This used to be silent unconditionally: `render()` returned
+     * with an EMPTY mounted div and only `onError` fired, so a host that had not
+     * wired `onError` — or had wired it to a logger — showed buyers a blank
+     * rectangle where the seat map belongs, on the host's own domain, which
+     * reads as a broken website rather than a temporary fault. `SeatPicker` has
+     * always failed loud with a retry; this is the embed class catching up.
+     *
+     * `'none'` restores the silent behaviour for hosts that render their own
+     * failure UI from `onError`.
+     */
+    errorDisplay?: 'message' | 'none';
     /**
      * Multi-floor charts only: fires when the buyer taps a deck in the stacked
      * 3D view, after the picker switches to that floor — lets the host page sync
@@ -446,6 +639,7 @@ declare class SeatingChart {
     private mount;
     private hostEl;
     private rendered;
+    private retryBtn;
     private mode_;
     private tipEl;
     private tipPos;
@@ -590,165 +784,15 @@ declare class SeatingChart {
      * true when a fresh bearer is held; the realtime feed restarts with it.
      */
     refreshAccess(): Promise<boolean>;
-    destroy(): void;
-}
-
-/**
- * BuyerRealtimeClient — the client half of `docs/realtime-protocol-2026-08-01.md`.
- *
- * Why this exists as a separate socket rather than inside PickerController:
- * a private scope authenticates with a one-use **subscribe ticket** carried in
- * `Sec-WebSocket-Protocol`, and a browser can only set that at construction —
- * `new WebSocket(url, protocols)`. The controller's socket is built from a URL
- * alone (`PickerTransport.socketUrl`), and a bearer must never travel in a URL
- * because URLs are routinely logged. So an access-scoped picker asks the
- * transport for an empty `socketUrl()` (the controller then skips its own
- * connection entirely) and this client owns the wire instead.
- *
- * A tokenless public picker never reaches this file. It keeps the controller's
- * original socket, offers no subprotocol, and therefore receives byte-for-byte
- * the frames it received before this module existed (protocol doc §1).
- *
- * What it implements:
- *  - protocol negotiation: offer `seatlayer.v1`, believe the 101 echo, and fall
- *    back to legacy frame handling when the server (or a proxy) does not echo;
- *  - the ticket exchange, one mint per connection attempt, ticket in the
- *    subprotocol list and never in the URL;
- *  - compact `{default, exceptions}` snapshot reconstruction;
- *  - `sv.<n>` resume, handling BOTH outcomes (a `resumed` delta or a full
- *    snapshot) on every reconnect;
- *  - close code 4401 as a typed access-revoked state, never a reconnect loop;
- *  - liveness by ping/pong only. Silence is normal and carries no information
- *    (protocol doc §5) — a quiet socket is never treated as a dead one.
- */
-
-/** The projected status of one unit, as the server words it on the wire. */
-type WireStatus = string;
-/** A scope's projection: one default plus the units that differ from it. */
-interface Projection {
-    default: WireStatus;
-    exceptions: Record<string, WireStatus>;
-}
-interface StatusChange {
-    label: string;
-    status: WireStatus;
-}
-/** Where reconstructed inventory goes. Implemented over PickerController. */
-interface RealtimeSink {
-    /** Apply a batch of label→status changes. Implementations must paint this as
-     *  ONE pass, not one pass per label (motion system §4 rule 2). */
-    applyStatuses(changes: StatusChange[]): void;
-    /** Re-pull authoritative state over the scoped HTTP route. Used when a frame
-     *  cannot be diffed against what we hold (first snapshot, or the scope's
-     *  default itself changed, which redefines every unit we were never told
-     *  about). */
-    resync(): void | Promise<void>;
-    /** Section availability changed (channel-agnostic; identical for every scope). */
-    onSections?(hidden: string[], closed: string[]): void;
-    /** Scope-projected presence counters. */
-    onPresence?(counts: {
-        shoppingSessions: number;
-        activeHolds: number;
-    }): void;
-}
-interface SubscribeTicket$1 {
-    ticket?: string;
-    /** Exactly what to hand `new WebSocket(url, protocols)`, per protocol doc §3. */
-    protocols?: string[];
-}
-interface BuyerRealtimeOptions {
-    /** The subscribe URL. Must never carry a credential — asserted below. */
-    url: string;
-    sink: RealtimeSink;
-    /** Mint a one-use ticket for THIS connection attempt. Returns null for the
-     *  anonymous public case (no ticket needed). Throwing stops the client. */
-    mintTicket?: () => Promise<SubscribeTicket$1 | null>;
-    /** Typed access states. 4401 arrives here as `revoked`. */
-    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
-    /** Test seam. Defaults to the global WebSocket. */
-    socketFactory?: (url: string, protocols: string[]) => WebSocket;
-    /** Test seam for the keepalive/backoff timers. */
-    now?: () => number;
-}
-declare class BuyerRealtimeClient {
-    private readonly opts;
-    private ws;
-    private stopped;
-    private attempt;
-    private reconnectTimer;
-    private pingTimer;
-    private pongTimer;
-    private resumeTimer;
-    /** Our model of this scope's projection. Null until the first snapshot. */
-    private projection;
-    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
-    private version;
-    /** True once the 101 echoed `seatlayer.v1`. */
-    private v1;
-    /** Set when we offered v1 and the handshake came back without it — a proxy
-     *  most likely stripped the header, so the next attempt selects the v1 frame
-     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
-     *  selects a format and can never carry a credential or widen a scope. */
-    private useQueryMarker;
-    private hidden;
-    private closedSections;
-    constructor(options: BuyerRealtimeOptions);
-    /** Negotiated protocol, for tests and diagnostics. */
-    get protocol(): 'v1' | 'legacy' | null;
-    get snapshotVersion(): number | null;
-    start(): void;
-    /** Stop for good (destroy, or a revocation). Safe to call twice. */
-    stop(): void;
-    /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
-    restart(): void;
-    private connect;
-    private handleFrame;
-    /** The server answered our resume; cancel the fallback resync. */
-    private answered;
-    private reportIfAccessError;
     /**
-     * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
-     * for minutes is the normal, correct state for a narrowly-scoped buyer on a
-     * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+     * The visible failure state. Deliberately inline-styled and dependency-free:
+     * this renders on a stranger's website, where our stylesheet may not have
+     * loaded (the chart fetch just failed) and where inheriting the host's own
+     * styles is likelier to produce something unreadable than something on-brand.
      */
-    private startKeepalive;
-    private scheduleReconnect;
-    private clearPongTimer;
-    private clearTimers;
-}
-/**
- * The slice of PickerController this module drives. Structural on purpose — it
- * keeps this file free of an `@seatlayer/core` import, and every member here is
- * public controller API, so nothing in the engine mirror has to change.
- */
-interface PickerControllerLike {
-    idForLabel(label: string): string | undefined;
-    tableSelection(seatIdOrLabel: string): {
-        physicalSeatIds: string[];
-    } | null;
-    setStatus(ids: string[], status: 'free' | 'held' | 'booked' | 'not_for_sale'): void;
-    getStatus(id: string): string | undefined;
-    flashSeat(id: string, color?: string): void;
-    currentHold(): {
-        labels: string[];
-    } | null;
-    getSelection(): Array<{
-        id: string;
-        label: string;
-    }>;
-    deselect(ids: string[]): void;
-    refresh(): Promise<void>;
-}
-interface ControllerSinkOptions {
-    /** Pulse seats other buyers take, as the controller's own socket does. */
-    flashOnLiveChange?: boolean;
-    /** Selected-but-unheld units that stopped being selectable. */
-    onSelectedObjectUnavailable?: (labels: string[], reason: 'ineligible' | 'taken') => void;
-    /** Section availability changed and the chart itself needs rebuilding. */
-    onSections?: (hidden: string[], closed: string[]) => void;
-    onStatusChange?: () => void;
+    private showLoadFailure;
+    destroy(): void;
 }
-declare function createControllerSink(controller: PickerControllerLike, options?: ControllerSinkOptions): RealtimeSink;
 
 /**
  * A secure, framework-neutral host for the SeatLayer chart Designer.
@@ -1253,17 +1297,33 @@ interface SeatPickerOptions {
      * 1. It needs the widget's own transport. A host-supplied `transport` owns its
      *    credentials and its backend, so hosted checkout stays off there (with one
      *    console warning) rather than reaching past it to api.seatlayer.io.
-     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER IS THE SERVER'S CHOICE. The
-     *    checkout session's return URL is built from the deployment's own allowed
-     *    origins, so a buyer paying by card from an embed on your domain comes back
-     *    to SeatLayer's buyer page and is confirmed THERE, not in this widget. The
-     *    widget resumes in place only when it is mounted on a page that actually
-     *    receives `?order=…&status=success` (a page on an allowed origin, and the
-     *    in-page gateways, which never navigate away at all). Until the server
-     *    accepts a caller-supplied return URL, treat a card payment from a
-     *    third-party embed as "the buyer finishes on our page".
+     * 2. WHERE A HOSTED GATEWAY RETURNS THE BUYER is settled by {@link returnUrl}
+     *    and by the organizer. Without one — or from an origin the organizer has
+     *    not declared — the buyer comes back to SeatLayer's own buyer page and is
+     *    confirmed THERE, not in this widget. Declare the embedding site under
+     *    Embed domains in the dashboard and pass `returnUrl`, and the buyer
+     *    returns to your page instead. In-page gateways never navigate away at
+     *    all, so they are unaffected either way.
      */
     checkout?: 'handoff' | 'hosted';
+    /**
+     * Where a redirecting gateway should send the buyer back to, for
+     * `checkout: 'hosted'`.
+     *
+     * The server keeps this URL verbatim — path and query included — and only
+     * stamps `?order=…&status=success|cancelled` onto it, so point it at
+     * whichever of YOUR pages should confirm the purchase (often just
+     * `window.location.href`). Mount a picker on that page and it resumes in
+     * place from those parameters.
+     *
+     * It is validated, not trusted: the organizer declares their embed origins
+     * in the dashboard, and an undeclared origin is ignored rather than
+     * refused — the sale still completes, the buyer just finishes on
+     * SeatLayer's page. Supplying a URL therefore cannot authorize it, which is
+     * what stops a copied snippet from redirecting a paid buyer anywhere it
+     * likes.
+     */
+    returnUrl?: string;
     /**
      * Buyer pressed the CTA and the hold succeeded — hand off to YOUR checkout.
      * `hold` and `seats` are the legacy args (unchanged since 0.6). `handoff` (P4)