@seatlayer/js 0.37.0 → 0.39.0

package/dist/index.d.ts

@@ -239,6 +239,52 @@ interface BestAvailableResult {
     items?: HoldResult['items'];
     zoneId?: string;
 }
+/** A gateway the organizer can be connected to. */
+type PaymentProviderName = 'stripe' | 'razorpay';
+/**
+ * Why `payment-options` came back with an empty list.
+ *
+ * The three are NOT interchangeable and two of them give opposite advice:
+ * `not_configured` means the organizer takes payment somewhere else,
+ * `payments_off_for_event` means they deliberately do not sell THIS event
+ * online, and `unavailable_for_event` means they switched it on and it is
+ * broken. Collapsing them makes the widget blame a working integration for a
+ * decision that was made on purpose.
+ */
+type PaymentOptionsReason = 'not_configured' | 'payments_off_for_event' | 'unavailable_for_event';
+/**
+ * What this event can take money through. Since the per-event gateway column
+ * landed, `providers` holds AT MOST ONE entry — the gateway the organizer
+ * assigned — so no browser can choose which one charges.
+ *
+ * `reason` is optional on the wire: a widget pinned against an older worker
+ * still parses, and its absence means what that worker meant by an empty list.
+ */
+interface PaymentOptionsResult {
+    providers: PaymentProviderName[];
+    currency: string | null;
+    reason?: PaymentOptionsReason | null;
+}
+/** A started payment. Exactly one of the two handoffs comes back. */
+interface CheckoutSessionResult {
+    orderId: string;
+    totalMinor: number;
+    currency: string;
+    expiresAt: number;
+    /** Hosted gateway page — navigate to it. */
+    redirectUrl?: string;
+    /** In-page modal gateway — open it without leaving the page. */
+    clientPayload?: Record<string, unknown>;
+}
+/** An order's state while its gateway webhook is in flight. */
+interface OrderStatusResult {
+    orderId: string;
+    status: string;
+    totalMinor: number;
+    currency: string;
+    amountFormatted: string;
+    seatCount: number;
+}
 interface PubApiOptions {
     /**
      * Buyer access session. When present, EVERY scoped operation on this client
@@ -1183,13 +1229,82 @@ interface SeatPickerOptions {
      * photo when a seat carries one. Default true; set false to hide the affordance.
      */
     seatView?: boolean;
+    /**
+     * WHERE the buyer goes once their seats are held. Default `'handoff'`.
+     *
+     *   'handoff'  (default, and every integration that has ever existed) the
+     *              widget fires {@link onCheckout} with a holdId and priced line
+     *              items, and YOUR server takes the money. Nothing about this path
+     *              changes, and no payment code is even downloaded.
+     *   'hosted'   the widget takes the money through the gateway the ORGANIZER
+     *              connected, on their account — the "sell tickets with no
+     *              backend" path. Requires the org to be on hosted checkout and
+     *              the event to have a gateway assigned; when it does not, this
+     *              falls back to `'handoff'` for that buyer rather than dead-ending
+     *              them, and reports why through {@link onCheckoutUnavailable}.
+     *
+     * Named for the destination rather than as a boolean flag because there is a
+     * real third answer coming and `hostedCheckout: true` would have no room for
+     * it; spelling the default out also makes a host's intent legible in their own
+     * source instead of hiding it in an absent option.
+     *
+     * TWO THINGS ARE WORTH KNOWING BEFORE YOU SWITCH THIS ON:
+     *
+     * 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".
+     */
+    checkout?: 'handoff' | 'hosted';
     /**
      * 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)
      * is the stable, self-contained {@link CheckoutHandoff} to build your order
      * against — holdId, expiry, currency and priced line items. Prefer it.
+     *
+     * Under `checkout: 'hosted'` this fires ONLY when hosted checkout cannot run
+     * for this event, so a host can keep one code path for both. It never fires
+     * alongside a payment the widget is taking itself.
      */
     onCheckout?: (hold: HoldResult, seats: PickerSeat[], handoff: CheckoutHandoff) => void;
+    /**
+     * `checkout: 'hosted'` was asked for and this event cannot take money.
+     * The seats ARE held — the buyer is mid-journey — so this is a routing
+     * decision, not an error, and it is never collapsed into {@link onError}.
+     *
+     * `reason` carries the server's three-way answer verbatim, because two of the
+     * three give opposite advice: `payments_off_for_event` means the organizer
+     * deliberately does not sell this event online (nothing is wrong), while
+     * `unavailable_for_event` means they switched it on and it is broken. Anything
+     * unreadable — a failed lookup, an older worker — reads as `not_configured`,
+     * which asserts the least about them.
+     *
+     * `onCheckout` fires immediately after this with the same hold. Supply either
+     * (or both) and you own the next screen; supply NEITHER and the widget shows
+     * the buyer an honest card of its own rather than swallowing the press.
+     */
+    onCheckoutUnavailable?: (event: {
+        reason: PaymentOptionsReason;
+        handoff: CheckoutHandoff;
+    }) => void;
+    /**
+     * `checkout: 'hosted'` only — the gateway's webhook landed and the order is
+     * PAID. The one signal a host with no backend actually needs, and the only
+     * place a receipt can come from on a page that has no server of its own.
+     *
+     * Distinct from {@link onBooked}, which reports the same sale seen from the
+     * seat map over the realtime channel and cannot fire at all for a buyer whose
+     * widget was torn down by a redirect to the gateway.
+     */
+    onOrderConfirmed?: (order: OrderStatusResult) => void;
     /**
      * The held seats were BOOKED (P4) — your server completed payment and the
      * booking landed over the realtime channel while the widget was still open.
@@ -1265,6 +1380,20 @@ declare class SeatPicker {
     private handedOff;
     /** Guards single onBooked + single success overlay per hold. */
     private bookedShown;
+    /**
+     * `'hosted'` only when the host asked for it AND the widget owns its own
+     * transport. Resolved once in the constructor so every later read is a field
+     * comparison rather than a re-derivation that could drift.
+     */
+    private readonly checkoutMode;
+    /**
+     * In-flight or settled `payment-options` for this event, started at render in
+     * hosted mode. One request, kicked off while the buyer is still choosing, so
+     * pressing Pay does not wait on a lookup whose answer never changes mid-session.
+     */
+    private paymentOptions;
+    /** The mounted payment card, while one is up. */
+    private checkoutPanel;
     private extendEl;
     private bookedEl;
     private gaQty;
@@ -1426,6 +1555,22 @@ declare class SeatPicker {
     static open(options: Omit<SeatPickerOptions, 'container'>): Promise<SeatPicker>;
     constructor(options: SeatPickerOptions);
     render(): Promise<this>;
+    /**
+     * A hosted gateway returned this buyer to a page that runs the widget, with
+     * `?order=…&status=…` in the URL. Pick the order up and finish the story.
+     *
+     * Only `success` resumes. `cancelled` means the buyer backed out at the
+     * gateway and their seats are still held — the map they are looking at IS the
+     * right screen, and opening a card to say "you cancelled" would be noise.
+     *
+     * The two parameters are then stripped with `replaceState`, because they are a
+     * one-shot instruction: leaving them in place would re-open the confirmation
+     * on every later navigation, and would carry an order id into browser history
+     * and any Referer this page later sends. `status` is only ever removed
+     * alongside an `order` we actually consumed, so a host page that uses a
+     * `status` parameter of its own keeps it.
+     */
+    private resumeHostedOrder;
     /**
      * Move layout-dependent chrome between its wide dock (map regions / zoom
      * column) and its narrow dock (the sheet's consolidated Filters row), and
@@ -1589,6 +1734,10 @@ declare class SeatPicker {
      * uploaded photo (seat.viewUrl) when present, else a panorama generated from
      * the chart geometry — the stage placed at this seat's true bearing + size.
      * Zero extra dependencies: an equirectangular image panned with `repeat-x`.
+     *
+     * Async only because the generator is a lazy chunk (see `loadPanorama`); an
+     * organizer photo needs no generator and never waits on it. The two callers
+     * are click handlers, so nothing observes the promise.
      */
     private openSeatView;
     private closeSeatView;
@@ -1637,6 +1786,38 @@ declare class SeatPicker {
      */
     private detectBooked;
     private showBooked;
+    /**
+     * The seats are held. Send the buyer wherever this picker's `checkout` option
+     * says they go.
+     *
+     * The default branch is the literal call that stood here before hosted
+     * checkout existed, unchanged, so nothing about an existing integration moves.
+     */
+    private checkoutHandoff;
+    /**
+     * Take the money ourselves, through the organizer's own gateway.
+     *
+     * Order of operations matters: ASK FIRST, load second. `payment-options` is
+     * already in flight from render, and its answer decides whether any payment
+     * code is fetched at all — an event that cannot charge never downloads the
+     * card that would have charged it.
+     *
+     * An empty list is not a failure and never dead-ends the buyer. It routes them
+     * to whatever the host has: `onCheckoutUnavailable` (with the server's reason,
+     * so the host can say the right one of three very different sentences), then
+     * `onCheckout` with the ordinary handoff. A host that supplied neither gets
+     * the widget's own honest card instead of a press that did nothing.
+     */
+    private startHostedCheckout;
+    /**
+     * Fetch the checkout chunk and put its card over the map.
+     *
+     * Every failure here lands the buyer back on a map with their seats still
+     * held, which is a place they can act from — a blocked chunk request must not
+     * leave them staring at a CTA that no longer does anything.
+     */
+    private openCheckoutPanel;
+    private closeCheckoutPanel;
     /** Assemble the stable {@link CheckoutHandoff} from a hold's server line items. */
     private buildHandoff;
     private emitHoldChange;
@@ -2765,13 +2946,39 @@ declare class SeatManager {
     private labelToId;
     private labelToSeat;
     private allIds;
+    /**
+     * GA inventory units — real sellable labels the server counts, with NO seat
+     * geometry and therefore no renderer binding. They live here rather than in
+     * `labelToId`/`allIds` so every paint path keeps addressing paintable nodes
+     * only, while the tally denominator finally covers the same universe the
+     * numerator does. Without them a GA sale hit `booked` but not `total`:
+     * Free under-reported by GA capacity and SOLD% could exceed 100%.
+     */
+    private gaUnitLabelSet;
     private status;
+    /** Live non-free counters, moved by each delta rather than re-walked. */
+    private counts;
+    /** Bumped whenever the seat model is replaced wholesale (a full snapshot). */
+    private modelVersion;
     private currency;
     private authoritativeGrossRevenue;
     private revenueStatus;
     private revenueRequest;
-    private revenueRefreshTimer;
     private controlRoomSnapshot;
+    /**
+     * The server's own totals, pinned to the client model they were read against.
+     * Display = server baseline + (client now − client then), so the authoritative
+     * numbers land exactly on arrival and deltas still move them between reads.
+     * A wholesale model replacement invalidates the pairing (`model`), and the
+     * client tallies — themselves a fresh authenticated read — take over.
+     */
+    private serverBaseline;
+    /** Latest presence frame, held whether or not a snapshot has landed yet. */
+    private livePresence;
+    /** Latest cumulative booked gross pushed on a delta frame. */
+    private liveGross;
+    /** Coalesces a burst of deltas into one KPI/rail repaint. */
+    private paintHandle;
     private trendWindowMinutes;
     private heatEnabled;
     private followLive;
@@ -2901,6 +3108,22 @@ declare class SeatManager {
     private selectableStatuses;
     private updateRendererInteraction;
     private handleSeatSelect;
+    /**
+     * Build the client's inventory universe from the chart.
+     *
+     * `expandChart` yields SEATS — it has no output for a GA area, whose capacity
+     * is sold as N synthetic unit labels. The server's seat map keys, its deltas
+     * and its `totals` all speak those labels, so a client that only knows seats
+     * counts GA sales in the numerator (every key of the snapshot is written into
+     * `status`) while leaving them out of the denominator. Registering the GA
+     * units here — labels only, never a render binding — is what makes the two
+     * agree.
+     */
+    private buildUnitUniverse;
+    /** Every sellable unit the client knows: seats + GA capacity. */
+    private unitTotal;
+    /** Every label the client models, whether or not it can be painted. */
+    private knownLabels;
     private repaintAll;
     /**
      * Open the cockpit's realtime socket AS THE ORGANIZER.
@@ -2920,6 +3143,16 @@ declare class SeatManager {
     private connect;
     private scheduleReconnect;
     private onMessage;
+    /**
+     * Adopt the cumulative booked gross a delta frame carried.
+     *
+     * Stashed with its arrival time so an in-flight control-room read can decide
+     * whether it is holding the newer number: a frame that landed after the
+     * request started is newer than the response, one that landed before is not.
+     */
+    private applyLiveGross;
+    /** The single writer for a label's status, so the counters never drift. */
+    private setStatusLabel;
     private resnapshot;
     /**
      * Replace the whole seat model.
@@ -2930,6 +3163,8 @@ declare class SeatManager {
      * the mode really is free, wrong the moment it is not.
      */
     private applySnapshot;
+    /** The one O(n) walk left: a wholesale model replacement re-bases the counters. */
+    private recountAll;
     /** Optimistic local write shared by organizer actions. Paint and tally once,
      * even when an arena-sized operation changes hundreds of seats. */
     private setSeatsLocal;
@@ -2944,9 +3179,39 @@ declare class SeatManager {
     private locateActivity;
     private showLiveEvent;
     private applyReportRevenue;
+    /**
+     * Read the server's own control-room projection.
+     *
+     * Called on mount, on every socket (re)connect and after an organizer action —
+     * never on a timer and never per delta frame. Presence and gross that arrived
+     * on the socket AFTER this request started are newer than the response, so
+     * they survive it; anything older defers to the read.
+     */
     private refreshControlRoom;
-    private scheduleRevenueRefresh;
+    /** Pin the server's totals to the client model they were read against. */
+    private rebaseServerTotals;
+    /** What the client's own model says — GA units included since `render()`. */
+    private clientTallies;
+    /**
+     * The numbers the KPI bar and rail render.
+     *
+     * The server is the authority: its totals land exactly as read, and the
+     * delta-driven client model carries them forward until the next read. Before
+     * the first snapshot — and after a wholesale model replacement invalidates the
+     * pairing — the client model stands alone.
+     */
+    private buildTallies;
+    /**
+     * Queue one KPI/rail repaint for this burst of changes.
+     *
+     * A delta frame can carry hundreds of seats and `paintKpis` rebuilds eight
+     * nodes from scratch, so painting per change is what made an arena-sized
+     * frame expensive. Coalescing on a frame keeps the burst to a single rebuild;
+     * without `requestAnimationFrame` (SSR, an older test env) it paints inline
+     * rather than dropping the update.
+     */
     private recomputeTallies;
+    private flushTallies;
     private verbFor;
     private pushActivity;
     private seedFeed;
@@ -2969,6 +3234,9 @@ declare class SeatManager {
     private paintKpis;
     private paintRail;
     private renderViewRail;
+    /** Live presence wins over the snapshot's copy — it is the fresher channel,
+     *  and it exists from the first frame rather than the first fetch. */
+    private presenceCounts;
     private paintMonitorInsights;
     private applyHeatOverlay;
     private renderInspectRail;
@@ -3443,4 +3711,4 @@ declare class ChannelsMode {
     handleBack(): boolean;
 }
 
-export { ACCESS_LINK_DEFAULTS, type AccessLinkRecord, type AccessLinkReveal, type AccessLinkState, type AccessLinkStatus, type AccessLinkStatusRecord, ApiError, type ArchiveBlockedDetails, type AssignmentBuckets, type AssignmentDropDetails, type AssignmentResult, type AttachPickerFrameOptions, type BestAvailableResult, type BucketRow, BuyerAccessContext, type BuyerAccessExpiredEvent, type BuyerAccessRefreshReason, type BuyerAccessToken, type BuyerAccessTokenProvider, BuyerAccessUnavailableError, type BuyerAccessUnavailableEvent, type BuyerAccessUnavailableReason, BuyerRealtimeClient, type BuyerRealtimeOptions, type ChannelAccessIntent, type ChannelAccessSummary, type ChannelAllocationPage, type ChannelAuditEntry, type ChannelAuditPage, type ChannelCounts, type ChannelListResult, type ChannelPreviewProjection, type ChannelRecord, type ChannelSeatStatus, type ChannelState, type ChannelsCapabilities, type ChannelsClient, ChannelsMode, type ChannelsModeHost, type ChannelsSeatView, type CheckoutHandoff, type CheckoutLineItem, type ControlRoomActivityEntry, type ControlRoomSectionMetric, type ControlRoomSnapshot, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, type LogEntry, type LogPage, ManageApi, ManageApiError, PUBLIC_CHANNEL_ID, PUBLIC_CHANNEL_NAME, type Projection, type PubApiOptions, type RealtimeSink, type ReportByStatus, type ReportCategoryMeta, type ReportCategoryRow, type ReportResult, type ResumedHoldResult, SeatManager, type SeatManagerActionResult, type SeatManagerActivity, type SeatManagerCapability, type SeatManagerConnection, type SeatManagerMode, type SeatManagerOptions, type SeatManagerTallies, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedObjectUnavailableEvent, type SelectedSeat, type SelectionSourceRow, type StatusChange, type SubscribeTicket$1 as SubscribeTicket, accessIntentLabel, accessLine, accessLinkBadge, accessLinkErrorCopy, accessLinkIsLive, accessLinkPolicyLines, attachPickerFrame, bucketRows, bucketRowsHtml, createBuyerAccessContext, createControllerSink, dropReviewRows, isPublicChannelId, markerLetter, markerOf, mutationCount, needsMoveConfirmation, planAssignment, retryAfterCopy, selectionSources, stateBadge, suggestMarker };
+export { ACCESS_LINK_DEFAULTS, type AccessLinkRecord, type AccessLinkReveal, type AccessLinkState, type AccessLinkStatus, type AccessLinkStatusRecord, ApiError, type ArchiveBlockedDetails, type AssignmentBuckets, type AssignmentDropDetails, type AssignmentResult, type AttachPickerFrameOptions, type BestAvailableResult, type BucketRow, BuyerAccessContext, type BuyerAccessExpiredEvent, type BuyerAccessRefreshReason, type BuyerAccessToken, type BuyerAccessTokenProvider, BuyerAccessUnavailableError, type BuyerAccessUnavailableEvent, type BuyerAccessUnavailableReason, BuyerRealtimeClient, type BuyerRealtimeOptions, type ChannelAccessIntent, type ChannelAccessSummary, type ChannelAllocationPage, type ChannelAuditEntry, type ChannelAuditPage, type ChannelCounts, type ChannelListResult, type ChannelPreviewProjection, type ChannelRecord, type ChannelSeatStatus, type ChannelState, type ChannelsCapabilities, type ChannelsClient, ChannelsMode, type ChannelsModeHost, type ChannelsSeatView, type CheckoutHandoff, type CheckoutLineItem, type CheckoutSessionResult, type ControlRoomActivityEntry, type ControlRoomSectionMetric, type ControlRoomSnapshot, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, type LogEntry, type LogPage, ManageApi, ManageApiError, type OrderStatusResult, PUBLIC_CHANNEL_ID, PUBLIC_CHANNEL_NAME, type PaymentOptionsReason, type PaymentOptionsResult, type PaymentProviderName, type Projection, type PubApiOptions, type RealtimeSink, type ReportByStatus, type ReportCategoryMeta, type ReportCategoryRow, type ReportResult, type ResumedHoldResult, SeatManager, type SeatManagerActionResult, type SeatManagerActivity, type SeatManagerCapability, type SeatManagerConnection, type SeatManagerMode, type SeatManagerOptions, type SeatManagerTallies, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedObjectUnavailableEvent, type SelectedSeat, type SelectionSourceRow, type StatusChange, type SubscribeTicket$1 as SubscribeTicket, accessIntentLabel, accessLine, accessLinkBadge, accessLinkErrorCopy, accessLinkIsLive, accessLinkPolicyLines, attachPickerFrame, bucketRows, bucketRowsHtml, createBuyerAccessContext, createControllerSink, dropReviewRows, isPublicChannelId, markerLetter, markerOf, mutationCount, needsMoveConfirmation, planAssignment, retryAfterCopy, selectionSources, stateBadge, suggestMarker };