@seatlayer/core 0.38.0 → 0.40.0

package/dist/index.d.cts

@@ -1375,6 +1375,38 @@ interface HoldSelectionRequest {
 interface BestAvailableResponse extends HoldResponse {
     labels: string[];
 }
+/** One unit's status as the realtime wire words it (`free`/`held`/`booked`/`blocked`/…). */
+interface PickerStatusChange {
+    label: string;
+    status: string;
+}
+/**
+ * Where a transport-owned realtime client pushes reconstructed inventory.
+ *
+ * Structurally identical to the SDK's `RealtimeSink` on purpose: this file is
+ * mirrored byte-for-byte into `@seatlayer/core`, which the SDK's `@seatlayer/js`
+ * depends on — so it can never import BuyerRealtimeClient without inverting that
+ * dependency. Structural typing lets the SDK hand its client this object with no
+ * import in either direction.
+ */
+interface PickerRealtimeSink {
+    /** Apply a batch of label→status changes as ONE paint pass, not one per label. */
+    applyStatuses(changes: PickerStatusChange[]): void;
+    /** Re-pull authoritative state over HTTP (a frame that cannot be diffed). */
+    resync(): void | Promise<void>;
+    /** Section availability changed (hidden = stripped, closed = greyed). */
+    onSections?(hidden: string[], closed: string[]): void;
+    /** Scope-projected presence counters. Unused by the picker today. */
+    onPresence?(counts: {
+        shoppingSessions: number;
+        activeHolds: number;
+    }): void;
+}
+/** The live feed itself, owned by the transport. */
+interface PickerRealtimeConnection {
+    start(): void;
+    stop(): void;
+}
 /** Swappable public-surface transport (SDK PubApi or a dashboard `api.pub.*` adapter). */
 interface PickerTransport {
     chart(key: string): Promise<{
@@ -1413,6 +1445,17 @@ interface PickerTransport {
      *  subscribe ticket via `Sec-WebSocket-Protocol`, realtime-protocol v1).
      *  Absent or empty means today's plain connection. */
     socketProtocols?(key: string): string[];
+    /**
+     * Optional — the transport owns the live feed and hands back a client that
+     * speaks the compact `seatlayer.v1` protocol (snapshot diffing, `sv.<n>`
+     * resume, ping/pong liveness, jittered reconnect).
+     *
+     * When this returns a connection the controller does NOT open its own socket:
+     * one socket client, one reconnect/backoff/resume implementation. Returning
+     * null (or omitting the method) keeps the plain-WebSocket path below, which is
+     * what a transport with no realtime client of its own still gets.
+     */
+    createRealtime?(key: string, sink: PickerRealtimeSink): PickerRealtimeConnection | null;
 }
 interface PickerCallbacks extends RendererCallbacks {
     /** Selection changed (manual clicks or a server best-available pick). */
@@ -1509,6 +1552,8 @@ declare class PickerController {
     private confirmedVariableTables;
     private groupedSelectionOverhead;
     private ws;
+    /** Transport-owned v1 client; mutually exclusive with `ws`. */
+    private realtime;
     private reconnectTimer;
     private attempt;
     private closed;
@@ -1813,7 +1858,28 @@ declare class PickerController {
      */
     private attachVisibilityListener;
     private detachVisibilityListener;
+    /**
+     * The sink a transport-owned v1 client pushes into.
+     *
+     * Deliberately byte-compatible with the inline socket handler below: the same
+     * liveStatuses bookkeeping (which the hold-expiry verification reads), the
+     * same one-call-per-status paint, the same free→taken flash rule that skips
+     * the buyer's OWN just-held seats, the same keepLiveWhileHidden forceDraw, the
+     * same clearBookedHoldIfSettled + onStatusChange ordering. Hosts see the same
+     * callbacks in the same order whichever path is live.
+     */
+    private realtimeSink;
+    /** Paint one delta batch. Shared by the v1 sink and the plain-socket handler. */
+    private applyStatusChanges;
     private connect;
+    /**
+     * Backoff for the PLAIN-socket fallback (a transport with no v1 client of its
+     * own). Full jitter, for the same reason BuyerRealtimeClient uses it: a
+     * deterministic `2**attempt` schedule brings every browser that lost the same
+     * socket back in the same millisecond, and an on-sale crowd reconnecting in
+     * lockstep turns one blip into a thundering herd. The ceiling still doubles,
+     * so a sustained outage still backs off.
+     */
     private scheduleReconnect;
 }
 
@@ -1968,4 +2034,4 @@ declare function formatMinor(minor: number, currency?: string): string;
 /** Bare symbol for input adornments ("€", "$", "₹"). */
 declare function currencySymbol(currency?: string): string;
 
-export { AccessibilityType, type AvailabilityRule, BoothObject, CategoryTier, ChartDoc, ChartObject, DEFAULT_CURRENCY, type Dict, type ExpandChartOptions, ExpandedSeat, Floor, GAAreaObject, GAInventorySegment, type HoldConflict, type HoldInfo, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LabelStyle, type Locale, LodRung, MAX_EVENT_INVENTORY, MAX_GA_CAPACITY, type PanoramaResult, type PickerCallbacks, PickerController, type PickerGAArea, type PickerOptions, type PickerSeat, type PickerTransport, Point, RENDERED_QUALITY_REPORT_VERSION, RectTableSeatCounts, RectTableSide, type RenderedEvidenceState, RenderedFreeTextEvidence, type RenderedQualityFinding, type RenderedQualityFindingCode, type RenderedQualityReport, type RenderedQualitySample, RendererCallbacks, RendererOptions, RendererQualityEvidence, RendererViewMode, RowObject, type RowSeatSlot, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatOverride, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionNode, SectionObject, type SectionSummary, TIER_HEIGHT_M, TableObject, type TableSeatSlot, type TableSelectionDetails, UNGROUPED_ID, allObjects, applyHidden, chartBounds, computeSections, createRenderer, currencyExponent, currencySymbol, expandBooth, expandChart, expandRow, expandRowSlots, expandTable, expandTableSlots, floorObjects, floorsOf, formatDate, formatMinor, formatMoney, fromMinorUnits, gaAreasOf, gaInventorySegments, gaUnitLabel, gaUnitLabels, generateSeatPanorama, generateSeatThumb, getLocale, growJoinedGAInventory, hiddenObjectIds, inspectRenderedQualityEvidence, isGaUnitLabel, isSectionHidden, loadLocale, objectCenter, owningSectionForObject, pointInPolygon, pointInPolygonWithHoles, polygonLabelPoint, resolveLocale, rowInventoryCount, rowSeatPositions, sectionGeometry, setLocale, setMoneyLocale, setStringOverrides, stackFloors, t, tCount, tableInventoryCount, tableSeatCountsBySide, validGAInventorySegments };
+export { AccessibilityType, type AvailabilityRule, BoothObject, CategoryTier, ChartDoc, ChartObject, DEFAULT_CURRENCY, type Dict, type ExpandChartOptions, ExpandedSeat, Floor, GAAreaObject, GAInventorySegment, type HoldConflict, type HoldInfo, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LabelStyle, type Locale, LodRung, MAX_EVENT_INVENTORY, MAX_GA_CAPACITY, type PanoramaResult, type PickerCallbacks, PickerController, type PickerGAArea, type PickerOptions, type PickerRealtimeConnection, type PickerRealtimeSink, type PickerSeat, type PickerStatusChange, type PickerTransport, Point, RENDERED_QUALITY_REPORT_VERSION, RectTableSeatCounts, RectTableSide, type RenderedEvidenceState, RenderedFreeTextEvidence, type RenderedQualityFinding, type RenderedQualityFindingCode, type RenderedQualityReport, type RenderedQualitySample, RendererCallbacks, RendererOptions, RendererQualityEvidence, RendererViewMode, RowObject, type RowSeatSlot, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatOverride, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionNode, SectionObject, type SectionSummary, TIER_HEIGHT_M, TableObject, type TableSeatSlot, type TableSelectionDetails, UNGROUPED_ID, allObjects, applyHidden, chartBounds, computeSections, createRenderer, currencyExponent, currencySymbol, expandBooth, expandChart, expandRow, expandRowSlots, expandTable, expandTableSlots, floorObjects, floorsOf, formatDate, formatMinor, formatMoney, fromMinorUnits, gaAreasOf, gaInventorySegments, gaUnitLabel, gaUnitLabels, generateSeatPanorama, generateSeatThumb, getLocale, growJoinedGAInventory, hiddenObjectIds, inspectRenderedQualityEvidence, isGaUnitLabel, isSectionHidden, loadLocale, objectCenter, owningSectionForObject, pointInPolygon, pointInPolygonWithHoles, polygonLabelPoint, resolveLocale, rowInventoryCount, rowSeatPositions, sectionGeometry, setLocale, setMoneyLocale, setStringOverrides, stackFloors, t, tCount, tableInventoryCount, tableSeatCountsBySide, validGAInventorySegments };

package/dist/index.d.ts

@@ -1375,6 +1375,38 @@ interface HoldSelectionRequest {
 interface BestAvailableResponse extends HoldResponse {
     labels: string[];
 }
+/** One unit's status as the realtime wire words it (`free`/`held`/`booked`/`blocked`/…). */
+interface PickerStatusChange {
+    label: string;
+    status: string;
+}
+/**
+ * Where a transport-owned realtime client pushes reconstructed inventory.
+ *
+ * Structurally identical to the SDK's `RealtimeSink` on purpose: this file is
+ * mirrored byte-for-byte into `@seatlayer/core`, which the SDK's `@seatlayer/js`
+ * depends on — so it can never import BuyerRealtimeClient without inverting that
+ * dependency. Structural typing lets the SDK hand its client this object with no
+ * import in either direction.
+ */
+interface PickerRealtimeSink {
+    /** Apply a batch of label→status changes as ONE paint pass, not one per label. */
+    applyStatuses(changes: PickerStatusChange[]): void;
+    /** Re-pull authoritative state over HTTP (a frame that cannot be diffed). */
+    resync(): void | Promise<void>;
+    /** Section availability changed (hidden = stripped, closed = greyed). */
+    onSections?(hidden: string[], closed: string[]): void;
+    /** Scope-projected presence counters. Unused by the picker today. */
+    onPresence?(counts: {
+        shoppingSessions: number;
+        activeHolds: number;
+    }): void;
+}
+/** The live feed itself, owned by the transport. */
+interface PickerRealtimeConnection {
+    start(): void;
+    stop(): void;
+}
 /** Swappable public-surface transport (SDK PubApi or a dashboard `api.pub.*` adapter). */
 interface PickerTransport {
     chart(key: string): Promise<{
@@ -1413,6 +1445,17 @@ interface PickerTransport {
      *  subscribe ticket via `Sec-WebSocket-Protocol`, realtime-protocol v1).
      *  Absent or empty means today's plain connection. */
     socketProtocols?(key: string): string[];
+    /**
+     * Optional — the transport owns the live feed and hands back a client that
+     * speaks the compact `seatlayer.v1` protocol (snapshot diffing, `sv.<n>`
+     * resume, ping/pong liveness, jittered reconnect).
+     *
+     * When this returns a connection the controller does NOT open its own socket:
+     * one socket client, one reconnect/backoff/resume implementation. Returning
+     * null (or omitting the method) keeps the plain-WebSocket path below, which is
+     * what a transport with no realtime client of its own still gets.
+     */
+    createRealtime?(key: string, sink: PickerRealtimeSink): PickerRealtimeConnection | null;
 }
 interface PickerCallbacks extends RendererCallbacks {
     /** Selection changed (manual clicks or a server best-available pick). */
@@ -1509,6 +1552,8 @@ declare class PickerController {
     private confirmedVariableTables;
     private groupedSelectionOverhead;
     private ws;
+    /** Transport-owned v1 client; mutually exclusive with `ws`. */
+    private realtime;
     private reconnectTimer;
     private attempt;
     private closed;
@@ -1813,7 +1858,28 @@ declare class PickerController {
      */
     private attachVisibilityListener;
     private detachVisibilityListener;
+    /**
+     * The sink a transport-owned v1 client pushes into.
+     *
+     * Deliberately byte-compatible with the inline socket handler below: the same
+     * liveStatuses bookkeeping (which the hold-expiry verification reads), the
+     * same one-call-per-status paint, the same free→taken flash rule that skips
+     * the buyer's OWN just-held seats, the same keepLiveWhileHidden forceDraw, the
+     * same clearBookedHoldIfSettled + onStatusChange ordering. Hosts see the same
+     * callbacks in the same order whichever path is live.
+     */
+    private realtimeSink;
+    /** Paint one delta batch. Shared by the v1 sink and the plain-socket handler. */
+    private applyStatusChanges;
     private connect;
+    /**
+     * Backoff for the PLAIN-socket fallback (a transport with no v1 client of its
+     * own). Full jitter, for the same reason BuyerRealtimeClient uses it: a
+     * deterministic `2**attempt` schedule brings every browser that lost the same
+     * socket back in the same millisecond, and an on-sale crowd reconnecting in
+     * lockstep turns one blip into a thundering herd. The ceiling still doubles,
+     * so a sustained outage still backs off.
+     */
     private scheduleReconnect;
 }
 
@@ -1968,4 +2034,4 @@ declare function formatMinor(minor: number, currency?: string): string;
 /** Bare symbol for input adornments ("€", "$", "₹"). */
 declare function currencySymbol(currency?: string): string;
 
-export { AccessibilityType, type AvailabilityRule, BoothObject, CategoryTier, ChartDoc, ChartObject, DEFAULT_CURRENCY, type Dict, type ExpandChartOptions, ExpandedSeat, Floor, GAAreaObject, GAInventorySegment, type HoldConflict, type HoldInfo, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LabelStyle, type Locale, LodRung, MAX_EVENT_INVENTORY, MAX_GA_CAPACITY, type PanoramaResult, type PickerCallbacks, PickerController, type PickerGAArea, type PickerOptions, type PickerSeat, type PickerTransport, Point, RENDERED_QUALITY_REPORT_VERSION, RectTableSeatCounts, RectTableSide, type RenderedEvidenceState, RenderedFreeTextEvidence, type RenderedQualityFinding, type RenderedQualityFindingCode, type RenderedQualityReport, type RenderedQualitySample, RendererCallbacks, RendererOptions, RendererQualityEvidence, RendererViewMode, RowObject, type RowSeatSlot, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatOverride, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionNode, SectionObject, type SectionSummary, TIER_HEIGHT_M, TableObject, type TableSeatSlot, type TableSelectionDetails, UNGROUPED_ID, allObjects, applyHidden, chartBounds, computeSections, createRenderer, currencyExponent, currencySymbol, expandBooth, expandChart, expandRow, expandRowSlots, expandTable, expandTableSlots, floorObjects, floorsOf, formatDate, formatMinor, formatMoney, fromMinorUnits, gaAreasOf, gaInventorySegments, gaUnitLabel, gaUnitLabels, generateSeatPanorama, generateSeatThumb, getLocale, growJoinedGAInventory, hiddenObjectIds, inspectRenderedQualityEvidence, isGaUnitLabel, isSectionHidden, loadLocale, objectCenter, owningSectionForObject, pointInPolygon, pointInPolygonWithHoles, polygonLabelPoint, resolveLocale, rowInventoryCount, rowSeatPositions, sectionGeometry, setLocale, setMoneyLocale, setStringOverrides, stackFloors, t, tCount, tableInventoryCount, tableSeatCountsBySide, validGAInventorySegments };
+export { AccessibilityType, type AvailabilityRule, BoothObject, CategoryTier, ChartDoc, ChartObject, DEFAULT_CURRENCY, type Dict, type ExpandChartOptions, ExpandedSeat, Floor, GAAreaObject, GAInventorySegment, type HoldConflict, type HoldInfo, type HoldSelectionRequest, type HoldServerItem, ISeatmapRenderer, LabelStyle, type Locale, LodRung, MAX_EVENT_INVENTORY, MAX_GA_CAPACITY, type PanoramaResult, type PickerCallbacks, PickerController, type PickerGAArea, type PickerOptions, type PickerRealtimeConnection, type PickerRealtimeSink, type PickerSeat, type PickerStatusChange, type PickerTransport, Point, RENDERED_QUALITY_REPORT_VERSION, RectTableSeatCounts, RectTableSide, type RenderedEvidenceState, RenderedFreeTextEvidence, type RenderedQualityFinding, type RenderedQualityFindingCode, type RenderedQualityReport, type RenderedQualitySample, RendererCallbacks, RendererOptions, RendererQualityEvidence, RendererViewMode, RowObject, type RowSeatSlot, SUPPORTED_LOCALES, SeatCommercialAttributes, type SeatHoverDetails, SeatOverride, SeatStatus, SeatmapRenderer, type SectionCategory, type SectionNode, SectionObject, type SectionSummary, TIER_HEIGHT_M, TableObject, type TableSeatSlot, type TableSelectionDetails, UNGROUPED_ID, allObjects, applyHidden, chartBounds, computeSections, createRenderer, currencyExponent, currencySymbol, expandBooth, expandChart, expandRow, expandRowSlots, expandTable, expandTableSlots, floorObjects, floorsOf, formatDate, formatMinor, formatMoney, fromMinorUnits, gaAreasOf, gaInventorySegments, gaUnitLabel, gaUnitLabels, generateSeatPanorama, generateSeatThumb, getLocale, growJoinedGAInventory, hiddenObjectIds, inspectRenderedQualityEvidence, isGaUnitLabel, isSectionHidden, loadLocale, objectCenter, owningSectionForObject, pointInPolygon, pointInPolygonWithHoles, polygonLabelPoint, resolveLocale, rowInventoryCount, rowSeatPositions, sectionGeometry, setLocale, setMoneyLocale, setStringOverrides, stackFloors, t, tCount, tableInventoryCount, tableSeatCountsBySide, validGAInventorySegments };

package/dist/index.js

@@ -6611,6 +6611,8 @@ var PickerController = class {
     this.groupedSelectionOverhead = 0;
     // realtime socket
     this.ws = null;
+    /** Transport-owned v1 client; mutually exclusive with `ws`. */
+    this.realtime = null;
     this.reconnectTimer = null;
     this.attempt = 0;
     this.closed = false;
@@ -7660,6 +7662,13 @@ var PickerController = class {
       clearTimeout(this.expiryTimer);
       this.expiryTimer = null;
     }
+    if (this.realtime) {
+      try {
+        this.realtime.stop();
+      } catch {
+      }
+      this.realtime = null;
+    }
     if (this.ws) {
       try {
         this.ws.close();
@@ -7948,10 +7957,66 @@ var PickerController = class {
     }
     this.onVisibilityChange = null;
   }
+  /**
+   * The sink a transport-owned v1 client pushes into.
+   *
+   * Deliberately byte-compatible with the inline socket handler below: the same
+   * liveStatuses bookkeeping (which the hold-expiry verification reads), the
+   * same one-call-per-status paint, the same free→taken flash rule that skips
+   * the buyer's OWN just-held seats, the same keepLiveWhileHidden forceDraw, the
+   * same clearBookedHoldIfSettled + onStatusChange ordering. Hosts see the same
+   * callbacks in the same order whichever path is live.
+   */
+  realtimeSink() {
+    return {
+      applyStatuses: (changes) => this.applyStatusChanges(changes),
+      resync: () => this.resnapshot(),
+      onSections: (hidden, closed) => {
+        const rebuilt = this.syncHidden(hidden);
+        const restyled = this.syncClosed(closed);
+        if (rebuilt) void this.resnapshot();
+        if (rebuilt || restyled) this.opts.onStatusChange?.();
+      }
+    };
+  }
+  /** Paint one delta batch. Shared by the v1 sink and the plain-socket handler. */
+  applyStatusChanges(changes) {
+    const r = this.renderer;
+    if (!r) return;
+    for (const ch of changes) {
+      this.liveStatuses.set(ch.label, ch.status);
+      const ids = this.idsForLabel(ch.label);
+      if (!ids.length) continue;
+      const next = mapStatus(ch.status);
+      if (this.opts.flashOnLiveChange && next !== "free" && ids.some((id) => r.getStatus(id) === "free") && !this.hold_?.labels.includes(ch.label)) {
+        ids.forEach((id) => r.flashSeat(id, next === "held" ? "#f4b740" : "#f43f5e"));
+      }
+      r.setStatus(ids, next);
+    }
+    if (this.opts.keepLiveWhileHidden && typeof document !== "undefined" && document.visibilityState === "hidden") {
+      r.forceDraw();
+    }
+    this.clearBookedHoldIfSettled();
+    this.opts.onStatusChange?.();
+  }
   connect() {
     if (this.closed) return;
     const url = this.api.socketUrl(this.key);
     if (!url) return;
+    if (!this.realtime && this.api.createRealtime) {
+      let connection = null;
+      try {
+        connection = this.api.createRealtime(this.key, this.realtimeSink());
+      } catch {
+        connection = null;
+      }
+      if (connection) {
+        this.realtime = connection;
+        connection.start();
+        return;
+      }
+    }
+    if (this.realtime) return;
     let ws;
     try {
       const protocols = this.api.socketProtocols?.(this.key);
@@ -7986,21 +8051,7 @@ var PickerController = class {
       if (m.seats && typeof m.seats === "object") {
         this.applySeatsMap(m.seats);
       } else if (Array.isArray(m.changes)) {
-        for (const ch of m.changes) {
-          this.liveStatuses.set(ch.label, ch.status);
-          const ids = this.idsForLabel(ch.label);
-          if (!ids.length) continue;
-          const next = mapStatus(ch.status);
-          if (this.opts.flashOnLiveChange && next !== "free" && ids.some((id) => r.getStatus(id) === "free") && !this.hold_?.labels.includes(ch.label)) {
-            ids.forEach((id) => r.flashSeat(id, next === "held" ? "#f4b740" : "#f43f5e"));
-          }
-          r.setStatus(ids, next);
-        }
-        if (this.opts.keepLiveWhileHidden && typeof document !== "undefined" && document.visibilityState === "hidden") {
-          r.forceDraw();
-        }
-        this.clearBookedHoldIfSettled();
-        this.opts.onStatusChange?.();
+        this.applyStatusChanges(m.changes);
       }
     };
     ws.onclose = () => {
@@ -8014,10 +8065,18 @@ var PickerController = class {
       }
     };
   }
+  /**
+   * Backoff for the PLAIN-socket fallback (a transport with no v1 client of its
+   * own). Full jitter, for the same reason BuyerRealtimeClient uses it: a
+   * deterministic `2**attempt` schedule brings every browser that lost the same
+   * socket back in the same millisecond, and an on-sale crowd reconnecting in
+   * lockstep turns one blip into a thundering herd. The ceiling still doubles,
+   * so a sustained outage still backs off.
+   */
   scheduleReconnect() {
     if (this.closed || this.reconnectTimer) return;
     const attempt = Math.min(this.attempt++, 5);
-    const delay = Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS);
+    const delay = Math.random() * Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS);
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       this.connect();