@seatlayer/js 0.102.0 → 0.104.0

package/dist/index.d.cts

@@ -224,8 +224,13 @@ declare class BuyerAccessContext {
     /**
      * Handle a 401/403 from a scoped call. Returns true when the caller should
      * retry the same request once with the refreshed bearer.
+     *
+     * `sentAuthorization` is the `Authorization` header the failed request
+     * carried. When the caller has it, the "did the refresh change anything"
+     * check below compares against exactly that bearer; without it, the bearer
+     * this context last issued stands in.
      */
-    handleFailure(status: number, code: string | undefined): Promise<boolean>;
+    handleFailure(status: number, code: string | undefined, sentAuthorization?: string | null): Promise<boolean>;
     /** Host-driven re-acquisition (after the buyer signs in again, say). */
     refresh(reason?: BuyerAccessRefreshReason): Promise<boolean>;
     /** Drop the bearer. Called on destroy so nothing outlives the widget. */
@@ -270,7 +275,9 @@ declare function createBuyerAccessContext(options: {
  *  - close code 4401 distinguishes an expired session (refresh/reconnect) from
  *    a genuinely revoked one (typed terminal 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.
+ *    (protocol doc §5) — a quiet socket is never treated as a dead one;
+ *  - a polling fallback for a network that will not upgrade at all (see
+ *    {@link FALLBACK_AFTER_FAILED_UPGRADES}).
  */
 
 /** The projected status of one unit, as the server words it on the wire. */
@@ -358,6 +365,13 @@ interface BuyerRealtimeOptions {
      * terminal revoked state, exactly as the runtimes before 0.94 read it.
      */
     onIdleExpired?: () => void;
+    /**
+     * The availability read the polling fallback runs. Defaults to the sink's
+     * coalesced `resync`, which every sink already has.
+     */
+    poll?: () => void | Promise<void>;
+    /** The client just fell back to polling. The count beacon is sent anyway. */
+    onFallbackPolling?: () => void;
     /** Test seam. Defaults to the global WebSocket. */
     socketFactory?: (url: string, protocols: string[]) => WebSocket;
     /** Test seam for the keepalive/backoff timers. */
@@ -385,7 +399,14 @@ declare class BuyerRealtimeClient {
     private useQueryMarker;
     private hidden;
     private closedSections;
+    /** Upgrades in a row that closed (or threw) before they ever opened. */
+    private failedUpgrades;
+    /** Armed only while the socket cannot upgrade. See FALLBACK_AFTER_FAILED_UPGRADES. */
+    private pollTimer;
+    private fellBack;
     constructor(options: BuyerRealtimeOptions);
+    /** True while availability is being read on a timer instead of the socket. */
+    get polling(): boolean;
     /** Negotiated protocol, for tests and diagnostics. */
     get protocol(): 'v1' | 'legacy' | null;
     get snapshotVersion(): number | null;
@@ -399,6 +420,16 @@ declare class BuyerRealtimeClient {
     /** The server answered our resume; cancel the fallback resync. */
     private answered;
     private reportIfAccessError;
+    private upgradeFailed;
+    /**
+     * Read availability every FALLBACK_POLL_MS while the tab is visible.
+     *
+     * A hidden tab reads nothing — the widget's own visibility catch-up re-reads
+     * the moment the buyer comes back — so a forgotten tab behind a strict proxy
+     * costs no more than one that is closed. Stops the moment a socket opens.
+     */
+    private startPolling;
+    private stopPolling;
     /**
      * 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
@@ -5257,7 +5288,8 @@ interface PerformanceGroupCheckoutHandoff {
 /** What the wrapper is showing the buyer right now, for host telemetry. */
 interface PerformanceGroupStatusEvent {
     /** `checkout`: the hosted checkout could not start; the seats stay held. */
-    kind: 'idle' | 'pending' | 'recovery_failed' | 'sales_closed' | 'revision_changed' | 'checkout';
+    /** `session_ended`: the buyer's session ended; the map stopped updating. */
+    kind: 'idle' | 'pending' | 'recovery_failed' | 'sales_closed' | 'revision_changed' | 'checkout' | 'session_ended';
     message: string;
     /** The short operation reference from §12, when one applies. */
     reference?: string;
@@ -5535,6 +5567,12 @@ declare class PerformanceGroupPicker {
     private setInteractionLocked;
     private announce;
     private showStatus;
+    /**
+     * The availability poll stopped because the buyer's session ended. The map
+     * on screen is now stale, so the picker says that plainly, and the host is
+     * told through `onError` so it can offer a fresh session.
+     */
+    private sessionEnded;
     private clearStatus;
     private operationChanged;
     /**

package/dist/index.d.ts

@@ -224,8 +224,13 @@ declare class BuyerAccessContext {
     /**
      * Handle a 401/403 from a scoped call. Returns true when the caller should
      * retry the same request once with the refreshed bearer.
+     *
+     * `sentAuthorization` is the `Authorization` header the failed request
+     * carried. When the caller has it, the "did the refresh change anything"
+     * check below compares against exactly that bearer; without it, the bearer
+     * this context last issued stands in.
      */
-    handleFailure(status: number, code: string | undefined): Promise<boolean>;
+    handleFailure(status: number, code: string | undefined, sentAuthorization?: string | null): Promise<boolean>;
     /** Host-driven re-acquisition (after the buyer signs in again, say). */
     refresh(reason?: BuyerAccessRefreshReason): Promise<boolean>;
     /** Drop the bearer. Called on destroy so nothing outlives the widget. */
@@ -270,7 +275,9 @@ declare function createBuyerAccessContext(options: {
  *  - close code 4401 distinguishes an expired session (refresh/reconnect) from
  *    a genuinely revoked one (typed terminal 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.
+ *    (protocol doc §5) — a quiet socket is never treated as a dead one;
+ *  - a polling fallback for a network that will not upgrade at all (see
+ *    {@link FALLBACK_AFTER_FAILED_UPGRADES}).
  */
 
 /** The projected status of one unit, as the server words it on the wire. */
@@ -358,6 +365,13 @@ interface BuyerRealtimeOptions {
      * terminal revoked state, exactly as the runtimes before 0.94 read it.
      */
     onIdleExpired?: () => void;
+    /**
+     * The availability read the polling fallback runs. Defaults to the sink's
+     * coalesced `resync`, which every sink already has.
+     */
+    poll?: () => void | Promise<void>;
+    /** The client just fell back to polling. The count beacon is sent anyway. */
+    onFallbackPolling?: () => void;
     /** Test seam. Defaults to the global WebSocket. */
     socketFactory?: (url: string, protocols: string[]) => WebSocket;
     /** Test seam for the keepalive/backoff timers. */
@@ -385,7 +399,14 @@ declare class BuyerRealtimeClient {
     private useQueryMarker;
     private hidden;
     private closedSections;
+    /** Upgrades in a row that closed (or threw) before they ever opened. */
+    private failedUpgrades;
+    /** Armed only while the socket cannot upgrade. See FALLBACK_AFTER_FAILED_UPGRADES. */
+    private pollTimer;
+    private fellBack;
     constructor(options: BuyerRealtimeOptions);
+    /** True while availability is being read on a timer instead of the socket. */
+    get polling(): boolean;
     /** Negotiated protocol, for tests and diagnostics. */
     get protocol(): 'v1' | 'legacy' | null;
     get snapshotVersion(): number | null;
@@ -399,6 +420,16 @@ declare class BuyerRealtimeClient {
     /** The server answered our resume; cancel the fallback resync. */
     private answered;
     private reportIfAccessError;
+    private upgradeFailed;
+    /**
+     * Read availability every FALLBACK_POLL_MS while the tab is visible.
+     *
+     * A hidden tab reads nothing — the widget's own visibility catch-up re-reads
+     * the moment the buyer comes back — so a forgotten tab behind a strict proxy
+     * costs no more than one that is closed. Stops the moment a socket opens.
+     */
+    private startPolling;
+    private stopPolling;
     /**
      * 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
@@ -5257,7 +5288,8 @@ interface PerformanceGroupCheckoutHandoff {
 /** What the wrapper is showing the buyer right now, for host telemetry. */
 interface PerformanceGroupStatusEvent {
     /** `checkout`: the hosted checkout could not start; the seats stay held. */
-    kind: 'idle' | 'pending' | 'recovery_failed' | 'sales_closed' | 'revision_changed' | 'checkout';
+    /** `session_ended`: the buyer's session ended; the map stopped updating. */
+    kind: 'idle' | 'pending' | 'recovery_failed' | 'sales_closed' | 'revision_changed' | 'checkout' | 'session_ended';
     message: string;
     /** The short operation reference from §12, when one applies. */
     reference?: string;
@@ -5535,6 +5567,12 @@ declare class PerformanceGroupPicker {
     private setInteractionLocked;
     private announce;
     private showStatus;
+    /**
+     * The availability poll stopped because the buyer's session ended. The map
+     * on screen is now stale, so the picker says that plainly, and the host is
+     * told through `onError` so it can offer a fresh session.
+     */
+    private sessionEnded;
     private clearStatus;
     private operationChanged;
     /**