@seatlayer/js 0.36.3 → 0.38.0

package/dist/index.d.cts

@@ -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;
@@ -2725,8 +2906,31 @@ interface SeatManagerOptions {
     onSelectionChange?: (seats: ExpandedSeat[]) => void;
     /** A block/unblock/cancel action completed successfully. */
     onActionComplete?: (result: SeatManagerActionResult) => void;
+    /**
+     * The realtime link connected or dropped, with the moment the numbers on
+     * screen were last known good.
+     *
+     * A host embedding this cockpit renders its own chrome around it, and until
+     * now had no way to know the board had gone stale: the manager tracked the
+     * drop internally (its own LIVE/RECONNECTING pill) and told nobody. A host
+     * that polls on a timer and pauses while the tab is hidden therefore showed
+     * arbitrarily old numbers that looked exactly like fresh ones.
+     */
+    onConnectionChange?: (state: SeatManagerConnection) => void;
     onError?: (err: unknown) => void;
 }
+/** Realtime link state, as reported to the embedding host. */
+interface SeatManagerConnection {
+    /** `live` while the socket is open; `reconnecting` from drop until reopen. */
+    status: 'live' | 'reconnecting';
+    /**
+     * `Date.now()` of the last snapshot or delta accepted from the server, or
+     * null before the first one. This is the honest "as of" for whatever the host
+     * is displaying — NOT the time the connection dropped, which is later and
+     * would overstate freshness.
+     */
+    lastMessageAt: number | null;
+}
 declare class SeatManager {
     private readonly opts;
     private readonly api;
@@ -2758,6 +2962,11 @@ declare class SeatManager {
     private reconnectTimer;
     private attempt;
     private closed;
+    /** Mirrors the `live` root class, so the getter never has to read the DOM. */
+    private connectionStatus;
+    /** When the server last told us something. Stamped on accepted traffic only —
+     *  a socket that opens and says nothing has not refreshed anything. */
+    private lastMessageAt;
     private ready;
     private feed;
     private feedTimer;
@@ -2804,8 +3013,10 @@ declare class SeatManager {
     private resolveChannelCapabilities;
     /** The adapter between the cockpit's internals and Channels mode. */
     private buildChannelsHost;
-    /** Approximate on-screen seat size, for the channel overlay's marks. Derived
-     *  from the live camera so the overlay tracks zoom without a renderer hook. */
+    /** Actual on-screen seat diameter, for the channel overlay's marks. The
+     * renderer's base seat radius is 9 chart units; retaining the camera scale
+     * (rather than capping it) keeps every preview paint aligned with the real
+     * chart geometry at deep zoom. */
     private seatPixelSize;
     /** Toggle the normalized sales-velocity outline overlay without changing seat colors. */
     setHeatOverlay(enabled: boolean): void;
@@ -2837,6 +3048,14 @@ declare class SeatManager {
     getSelection(): ExpandedSeat[];
     getReport(): Promise<ReportResult>;
     getControlRoomSnapshot(windowMinutes?: number): Promise<ControlRoomSnapshot>;
+    /**
+     * The realtime link's current state and the "as of" behind it.
+     *
+     * Pair with `onConnectionChange` for the edges: a host that mounts after a
+     * drop, or re-reads on tab focus, needs to be able to ASK rather than wait
+     * for the next transition that may never come.
+     */
+    getConnection(): SeatManagerConnection;
     getLog(opts?: {
         limit?: number;
         before?: number;
@@ -2850,8 +3069,9 @@ declare class SeatManager {
     zoomToFit(): void;
     destroy(): void;
     private buildRenderer;
-    /** Block and Channels are both bulk-selection tools: marquee, ⌘A, category,
-     *  section. The two differ only in WHICH statuses they may act on. */
+    /** Block always uses a marquee. Channels only enables its marquee after the
+     * organizer deliberately chooses Assign seats; Pan map keeps desktop drag
+     * available for large charts. */
     private isBulkSelectMode;
     /**
      * Block never touches held or booked inventory, so it cannot select it.
@@ -3131,6 +3351,12 @@ interface ChannelsModeHost {
     } | null;
     /** Approximate on-screen seat size in CSS pixels, for the overlay marks. */
     seatPixelSize(): number;
+    /** Whether the live renderer is currently showing individual seats. */
+    isSeatDetail(): boolean;
+    /** Return a sectional venue to its section-only overview. */
+    showSectionOverview(): void;
+    /** Focus one section using the renderer's real camera transition. */
+    focusSection(sectionId: string): void;
     isCompact(): boolean;
     /** Make the canvas non-interactive behind a full-detent sheet (§13). */
     setMapInert(inert: boolean): void;
@@ -3157,6 +3383,10 @@ declare class ChannelsMode {
     private loadError;
     private loading;
     private view;
+    /** Pan is intentionally the initial desktop interaction. Assignment's
+     * marquee is powerful, but must never make an organizer lose map navigation. */
+    private mapIntent;
+    private focusedSectionId;
     private showArchived;
     private detailChannelId;
     private targetChannelId;
@@ -3173,6 +3403,15 @@ declare class ChannelsMode {
     private links;
     private linksChannelId;
     private linksState;
+    /**
+     * Monotonic read generations — one for the channel list + allocation, one for
+     * the open channel's links. Reads are concurrent (a 10s poll versus a
+     * mutation's own reload), and the network does not promise to answer them in
+     * order. Only the NEWEST read of each kind may write to state; an older
+     * answer that arrives late is dropped, never painted.
+     */
+    private listSeq;
+    private linksSeq;
     private previewAudience;
     private previewIncludePublic;
     private previewProjection;
@@ -3207,6 +3446,11 @@ declare class ChannelsMode {
      * all rather than collect a selection nothing can act on.
      */
     canSelect(): boolean;
+    /** Bulk seat assignment is explicit. In Pan map, clicks can still inspect a
+     * single seat, while a primary-button drag always moves the camera. */
+    usesMarqueeSelection(): boolean;
+    /** The renderer calls this when the organizer opens a section from overview. */
+    handleSectionFocus(sectionId: string): void;
     /**
      * Organizer realtime integration point. M5 ships a per-scope socket for
      * buyers; the organizer channel-count stream is a later milestone. When it
@@ -3235,11 +3479,22 @@ declare class ChannelsMode {
      * Repaint the allocation (or preview) overlay in ONE canvas pass.
      *
      * Channel identity on the map is a fill in the administrative color PLUS the
-     * letter flags below — never color alone. Physical status keeps its own cue:
-     * only FREE units take a channel fill, so sold/held/blocked seats still read
-     * exactly as they do in every other tool.
+     * letter flags below — never color alone. In buyer preview the map instead
+     * uses two explicit, channel-neutral access states. Physical status keeps its
+     * own cue: only FREE units are repainted, so sold/held/blocked seats still
+     * read exactly as they do in every other tool.
      */
     private paintOverlay;
+    /** Draw an eligible seat's actual chart label without inventing a new buyer
+     * identifier. Long labels scale down and are omitted rather than overflowing
+     * into an adjacent seat. */
+    private paintPreviewSeatLabel;
+    /** A section overview is a navigation map. These transparent, keyboardable
+     * hit areas sit over the renderer's section shells so both mouse and keyboard
+     * always take the organizer into the real focused-section camera state. */
+    private paintSectionTargets;
+    /** Keep renderer section names legible over a dense, zoomed-out preview. */
+    private paintPreviewSectionLabels;
     /** Letter flags at each channel's centroid — the non-color identity cue. */
     private paintFlags;
     private setStaged;
@@ -3251,6 +3506,7 @@ declare class ChannelsMode {
     private loadPreview;
     paintRail(): void;
     private viewSegmentHtml;
+    private mapNavigationHtml;
     private countsHtml;
     private channelRowHtml;
     private listRailHtml;
@@ -3314,6 +3570,17 @@ declare class ChannelsMode {
      */
     private renderSeatListDialog;
     private reloadLinks;
+    /**
+     * The reload EVERY link mutation owes the panel.
+     *
+     * A create/rotate/revoke changes two things the detail panel renders: the
+     * channel's access line (the server sets `access.intent` on create, and clears
+     * it when the last live link goes) and the link status list. Both are re-read
+     * here and the rail repainted, so the panel the organizer is already looking
+     * at is current the moment the mutation lands — no reload, and no dependence
+     * on HOW the one-time reveal was dismissed (the button, Escape, or never).
+     */
+    private reloadAfterLinkChange;
     private linkById;
     /**
      * Create. The three policy fields carry the owner's defaults and every one of
@@ -3357,4 +3624,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 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 };