@seatlayer/js 0.103.0 → 0.104.0

package/dist/index.d.cts

@@ -275,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. */
@@ -363,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. */
@@ -390,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;
@@ -404,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

package/dist/index.d.ts

@@ -275,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. */
@@ -363,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. */
@@ -390,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;
@@ -404,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