@tier0/sdk-v2 0.9.10 → 0.10.1

package/dist/esm/data/subscribe.js

@@ -23,9 +23,11 @@
  *   `delete` always passes, a late one too, and forgets the record's
  *   revision, since a record written again under the same ID may start
  *   over at revision 1.
- * - Changes in collections with employee data rules (`restricted`) come as
- *   collection-level notices unless `restricted: "record"` is asked for.
  * - Aborting `signal` or leaving the loop ends the iteration without error.
+ * - The stream runs as the App: it sees every change of the collections
+ *   granted to the App. A server opens one per process and fans it out to
+ *   browsers with `createChangeRelay`, filtering per browser by what the App
+ *   lets that visitor see.
  *
  * Events carry identities only, never record data; read the record to show it.
  */
@@ -43,18 +45,6 @@ const RESET_PAUSE_MS = 1_000;
 const HEALTHY_CONNECTION_MS = 30_000;
 /** Records whose last revision is remembered; beyond this the oldest is forgotten (a stale change may then pass, which only costs a reread). */
 const SUBSCRIBE_SEEN_RECORDS_MAX = 10_000;
-/**
- * The event as an employee's browser may see it: a change in a collection
- * with employee data rules becomes a collection-level notice without record
- * ID or revision, so it does not reveal records the employee may not read.
- * Other events pass unchanged.
- */
-export function redactRestricted(event) {
-    if (event.type !== 'change' || !event.restricted || event.change === 'collection')
-        return event;
-    const { eventId, collection, collectionId, occurredAt, restricted } = event;
-    return { type: 'change', eventId, collection, collectionId, occurredAt, restricted, change: 'collection' };
-}
 function reconnectDelay(failures, afterMs) {
     if (afterMs !== undefined)
         return Math.min(afterMs, RECONNECT_MAX_MS);
@@ -106,7 +96,7 @@ function pause(ms, signal) {
     });
 }
 export function createSubscribe(runtime) {
-    return async function* subscribe(options = {}) {
+    return async function* subscribe(options = {}, observer = {}) {
         const definitions = [...new Set((options.collections ?? runtime.declared).map(runtime.lookup))];
         if (definitions.length < 1 || definitions.length > UNS_V2_SUBSCRIBE_MAX_COLLECTIONS) {
             throw new TypeError(`data.subscribe watches 1–${UNS_V2_SUBSCRIBE_MAX_COLLECTIONS} collections; got ${definitions.length}.`);
@@ -117,10 +107,7 @@ export function createSubscribe(runtime) {
         }
         if (options.lastEventId !== undefined)
             assertEventId(options.lastEventId);
-        const redact = (options.restricted ?? 'collection') === 'collection';
         const idleMs = options.idleTimeoutMs ?? SUBSCRIBE_IDLE_TIMEOUT_MS;
-        // The subject of the request that subscribed; an App-level subscription carries none.
-        const call = { dataSubject: runtime.subject() };
         const stop = new AbortController();
         const onAbort = () => stop.abort();
         options.signal?.addEventListener('abort', onAbort, { once: true });
@@ -130,7 +117,9 @@ export function createSubscribe(runtime) {
         let failures = 0;
         const seen = new SeenRevisions(SUBSCRIBE_SEEN_RECORDS_MAX);
         /** Waits, longer each time, before the next attempt. */
-        const backOff = async (afterMs) => {
+        const backOff = async (error) => {
+            observer.retrying?.(error);
+            const afterMs = error.retry.afterMs;
             failures += 1;
             await pause(reconnectDelay(failures, afterMs), stop.signal);
         };
@@ -144,7 +133,7 @@ export function createSubscribe(runtime) {
                     // A freshly imported App answers APP_NOT_READY for a while: keep waiting for it.
                     if (!(error instanceof DataError) || !error.retry.safe || stop.signal.aborted)
                         throw error;
-                    await backOff(error.retry.afterMs);
+                    await backOff(error);
                     continue;
                 }
                 const aliases = new Map();
@@ -163,17 +152,24 @@ export function createSubscribe(runtime) {
                 const openedAt = Date.now();
                 let healthy = false;
                 let reset = false;
+                let streaming = false;
                 try {
                     arm();
-                    const stream = runtime.openStream({ collectionIds: [...aliases.keys()], ...(recordIds ? { recordIds } : {}) }, { ...call, lastEventId, signal: connection.signal });
+                    const stream = runtime.openStream({ collectionIds: [...aliases.keys()], ...(recordIds ? { recordIds } : {}) }, { lastEventId, signal: connection.signal });
                     for await (const event of stream) {
                         arm();
                         if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS)
                             healthy = true;
+                        if (!streaming) {
+                            streaming = true;
+                            observer.connected?.();
+                        }
                         if (event.type === 'heartbeat') {
                             // The connect heartbeat names the current position: resuming from it loses nothing.
-                            if (event.eventId !== undefined)
+                            if (event.eventId !== undefined) {
                                 lastEventId = event.eventId;
+                                observer.position?.(event.eventId);
+                            }
                             continue;
                         }
                         if (event.type === 'reset') {
@@ -187,20 +183,19 @@ export function createSubscribe(runtime) {
                         healthy = true;
                         // A dropped change is still a resume position.
                         lastEventId = event.eventId;
+                        observer.position?.(event.eventId);
                         if (!seen.admit(event.collectionId, event.recordId, event.revision, event.change))
                             continue;
-                        const change = {
+                        yield {
                             type: 'change',
                             eventId: event.eventId,
                             collection: aliases.get(event.collectionId) ?? event.collectionId,
                             collectionId: event.collectionId,
                             occurredAt: event.occurredAt,
-                            restricted: event.restricted,
                             change: event.change,
                             recordId: event.recordId,
                             revision: event.revision,
                         };
-                        yield redact ? redactRestricted(change) : change;
                     }
                 }
                 catch (error) {
@@ -216,7 +211,7 @@ export function createSubscribe(runtime) {
                         catch (cause) {
                             if (!(cause instanceof DataError) || !cause.retry.safe)
                                 throw cause;
-                            await backOff(cause.retry.afterMs);
+                            await backOff(cause);
                             continue;
                         }
                         if (!changed)
@@ -229,7 +224,7 @@ export function createSubscribe(runtime) {
                     }
                     if (!error.retry.safe)
                         throw error;
-                    await backOff(error.retry.afterMs);
+                    await backOff(error);
                     continue;
                 }
                 finally {

package/dist/esm/data/subscribe.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscribe.js","sourceRoot":"","sources":["../../../src/data/subscribe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `data.subscribe`: committed record changes of declared collections over\n * UNS `records:subscribe` (server-sent events), as one async iterable that\n * outlives single connections.\n *\n * - Reconnects with `Last-Event-ID` when the stream ends, breaks, or stays\n *   silent for `idleTimeoutMs` (UNS sends a heartbeat every 15 s). A stream\n *   that dies young without a change backs off, so a server dropping every\n *   connection is not hammered.\n * - Failures marked `retry.safe` (429 over the subscription limit, 503,\n *   `APP_NOT_READY` from ensure …) are retried after `retry.afterMs` or a\n *   backoff of up to 30 s, without end; any other failure ends the\n *   iteration with that DataError.\n * - `reset` is passed on: `CURSOR_EXPIRED` (the position was cleaned up after\n *   24 h, cannot be decoded after a key rotation, or the tenant database\n *   moved) or `SCOPE_CHANGED` (access changed, e.g. a collection is no longer\n *   readable). The consumer reloads what it shows; the next connection\n *   starts from now, without a resume position. A collection recreated\n *   under a new ID (see bootstrap self-healing) yields `COLLECTION_RECREATED`.\n * - UNS delivers changes in write-transaction order, not commit order, so\n *   revisions of one record may arrive out of order. A non-delete change at\n *   or below the revision already passed on for its record is dropped; a\n *   `delete` always passes, a late one too, and forgets the record's\n *   revision, since a record written again under the same ID may start\n *   over at revision 1.\n * - Changes in collections with employee data rules (`restricted`) come as\n *   collection-level notices unless `restricted: \"record\"` is asked for.\n * - Aborting `signal` or leaving the loop ends the iteration without error.\n *\n * Events carry identities only, never record data; read the record to show it.\n */\nimport { isStaleCollectionError, type EnsureState } from './bootstrap.js';\nimport type { CallOptions, DataOpenStream } from './call.js';\nimport { assertEventId, UNS_V2_SUBSCRIBE_MAX_COLLECTIONS, UNS_V2_SUBSCRIBE_MAX_RECORD_IDS } from '../uns-v2/client.js';\nimport { collectionLabel, type CollectionTarget } from './define.js';\nimport { DataError } from './error.js';\n\n/** Three missed 15 s heartbeats. */\nexport const SUBSCRIBE_IDLE_TIMEOUT_MS = 45_000;\nconst RECONNECT_BASE_MS = 500;\nconst RECONNECT_MAX_MS = 30_000;\n/** After a reset, the next connection waits at least this long. */\nconst RESET_PAUSE_MS = 1_000;\n/** A connection alive this long counts as healthy even without changes. */\nconst HEALTHY_CONNECTION_MS = 30_000;\n/** Records whose last revision is remembered; beyond this the oldest is forgotten (a stale change may then pass, which only costs a reread). */\nconst SUBSCRIBE_SEEN_RECORDS_MAX = 10_000;\n\nexport interface SubscribeOptions {\n  /** Declarations, aliases, or existing-ID references (at most 64); defaults to every declared collection. */\n  collections?: readonly (CollectionTarget | string)[];\n  /** Only changes of these record IDs (1–100, duplicates ignored), when exactly one collection is watched. */\n  recordIds?: readonly string[];\n  /**\n   * How changes in collections with employee data rules arrive.\n   * `collection` (default): as a collection-level notice without record ID\n   * or revision, safe to forward to any employee. `record`: the full event,\n   * for server-side consumers that do not forward it to browsers, or that\n   * redact per recipient with `redactRestricted`.\n   */\n  restricted?: 'collection' | 'record';\n  /** Resume after this event (e.g. a browser's `Last-Event-ID`). */\n  lastEventId?: string;\n  signal?: AbortSignal;\n  /** Reconnect when nothing, not even a heartbeat, arrives for this long. */\n  idleTimeoutMs?: number;\n}\n\ninterface ChangeBase {\n  type: 'change';\n  eventId: string;\n  /** Alias of a declared collection, or the ID of an existing collection reference. */\n  collection: string;\n  collectionId: string;\n  occurredAt: number;\n  /**\n   * The collection has employee data rules: whether an employee may see this\n   * record depends on who they are. Such changes arrive as `CollectionChange`\n   * unless the subscription asked for `restricted: \"record\"`.\n   */\n  restricted: boolean;\n}\n\n/**\n * One record committed (`record`) or deleted (`delete`) at `revision`. A\n * `record` change is never at or below a revision already passed on for the\n * same record since its last delete; a `delete` may be.\n */\nexport interface RecordChange extends ChangeBase {\n  change: 'record' | 'delete';\n  recordId: string;\n  revision: number;\n}\n\n/** Something in the collection changed; which record is not disclosed. Reload through the data rules. */\nexport interface CollectionChange extends ChangeBase {\n  change: 'collection';\n}\n\nexport type ChangeEvent = RecordChange | CollectionChange;\n/** `reason`: `CURSOR_EXPIRED`, `SCOPE_CHANGED` (from UNS) or `COLLECTION_RECREATED`. */\nexport type SubscriptionEvent = ChangeEvent | { type: 'reset'; reason: string; message?: string };\n\n/**\n * The event as an employee's browser may see it: a change in a collection\n * with employee data rules becomes a collection-level notice without record\n * ID or revision, so it does not reveal records the employee may not read.\n * Other events pass unchanged.\n */\nexport function redactRestricted<E extends SubscriptionEvent>(event: E): E | CollectionChange {\n  if (event.type !== 'change' || !event.restricted || event.change === 'collection') return event;\n  const { eventId, collection, collectionId, occurredAt, restricted } = event;\n  return { type: 'change', eventId, collection, collectionId, occurredAt, restricted, change: 'collection' };\n}\n\nexport interface SubscribeRuntime {\n  openStream: DataOpenStream;\n  ensure(targets: readonly CollectionTarget[]): Promise<EnsureState>;\n  rebuild(before: EnsureState, cause: DataError, targets: readonly CollectionTarget[]): Promise<boolean>;\n  resolve(target: CollectionTarget): Promise<string>;\n  lookup(target: CollectionTarget | string): CollectionTarget;\n  declared: readonly CollectionTarget[];\n  subject(): string | undefined;\n}\n\nfunction reconnectDelay(failures: number, afterMs: number | undefined): number {\n  if (afterMs !== undefined) return Math.min(afterMs, RECONNECT_MAX_MS);\n  const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.max(0, failures - 1));\n  return ceiling / 2 + Math.random() * (ceiling / 2);\n}\n\n/**\n * The highest revision passed on per record, so changes delivered out of\n * order are dropped (UNS orders by write transaction, not by commit).\n */\nclass SeenRevisions {\n  private readonly revisions = new Map<string, number>();\n\n  constructor(private readonly max: number) {}\n\n  /** Whether the change is new; remembers its revision, or forgets the record on delete. */\n  admit(collectionId: string, recordId: string, revision: number, change: 'record' | 'delete'): boolean {\n    const key = `${collectionId}\\u0000${recordId}`;\n    const seen = this.revisions.get(key);\n    // A delete always passes, a late one too: the record may be written again under the same ID, from revision 1.\n    if (change === 'delete') {\n      this.revisions.delete(key);\n      return true;\n    }\n    if (seen !== undefined && revision <= seen) return false;\n    this.revisions.delete(key);\n    this.revisions.set(key, revision);\n    if (this.revisions.size > this.max) this.revisions.delete(this.revisions.keys().next().value!);\n    return true;\n  }\n\n  clear() {\n    this.revisions.clear();\n  }\n}\n\nfunction pause(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal.aborted) return resolve();\n    const done = () => {\n      clearTimeout(timer);\n      signal.removeEventListener('abort', done);\n      resolve();\n    };\n    const timer = setTimeout(done, ms);\n    signal.addEventListener('abort', done, { once: true });\n  });\n}\n\nexport function createSubscribe(runtime: SubscribeRuntime) {\n  return async function* subscribe(options: SubscribeOptions = {}): AsyncGenerator<SubscriptionEvent, void, undefined> {\n    const definitions = [...new Set((options.collections ?? runtime.declared).map(runtime.lookup))];\n    if (definitions.length < 1 || definitions.length > UNS_V2_SUBSCRIBE_MAX_COLLECTIONS) {\n      throw new TypeError(`data.subscribe watches 1–${UNS_V2_SUBSCRIBE_MAX_COLLECTIONS} collections; got ${definitions.length}.`);\n    }\n    const recordIds = options.recordIds === undefined ? undefined : [...new Set(options.recordIds)];\n    if (recordIds && (recordIds.length < 1 || recordIds.length > UNS_V2_SUBSCRIBE_MAX_RECORD_IDS || definitions.length !== 1)) {\n      throw new TypeError(`data.subscribe takes 1–${UNS_V2_SUBSCRIBE_MAX_RECORD_IDS} recordIds, of exactly one collection.`);\n    }\n    if (options.lastEventId !== undefined) assertEventId(options.lastEventId);\n    const redact = (options.restricted ?? 'collection') === 'collection';\n    const idleMs = options.idleTimeoutMs ?? SUBSCRIBE_IDLE_TIMEOUT_MS;\n    // The subject of the request that subscribed; an App-level subscription carries none.\n    const call: CallOptions = { dataSubject: runtime.subject() };\n    const stop = new AbortController();\n    const onAbort = () => stop.abort();\n    options.signal?.addEventListener('abort', onAbort, { once: true });\n    if (options.signal?.aborted) stop.abort();\n    let lastEventId = options.lastEventId;\n    let failures = 0;\n    const seen = new SeenRevisions(SUBSCRIBE_SEEN_RECORDS_MAX);\n    /** Waits, longer each time, before the next attempt. */\n    const backOff = async (afterMs?: number) => {\n      failures += 1;\n      await pause(reconnectDelay(failures, afterMs), stop.signal);\n    };\n    try {\n      while (!stop.signal.aborted) {\n        let state: EnsureState;\n        try {\n          state = await runtime.ensure(definitions);\n        } catch (error) {\n          // A freshly imported App answers APP_NOT_READY for a while: keep waiting for it.\n          if (!(error instanceof DataError) || !error.retry.safe || stop.signal.aborted) throw error;\n          await backOff(error.retry.afterMs);\n          continue;\n        }\n        const aliases = new Map<string, string>();\n        for (const definition of definitions) {\n          const id = await runtime.resolve(definition);\n          aliases.set(id, collectionLabel(definition));\n        }\n\n        const connection = new AbortController();\n        const closeConnection = () => connection.abort();\n        stop.signal.addEventListener('abort', closeConnection, { once: true });\n        let idle: ReturnType<typeof setTimeout> | undefined;\n        const arm = () => {\n          clearTimeout(idle);\n          idle = setTimeout(closeConnection, idleMs);\n        };\n        const openedAt = Date.now();\n        let healthy = false;\n        let reset = false;\n        try {\n          arm();\n          const stream = runtime.openStream(\n            { collectionIds: [...aliases.keys()], ...(recordIds ? { recordIds } : {}) },\n            { ...call, lastEventId, signal: connection.signal },\n          );\n          for await (const event of stream) {\n            arm();\n            if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) healthy = true;\n            if (event.type === 'heartbeat') {\n              // The connect heartbeat names the current position: resuming from it loses nothing.\n              if (event.eventId !== undefined) lastEventId = event.eventId;\n              continue;\n            }\n            if (event.type === 'reset') {\n              lastEventId = undefined;\n              reset = true;\n              // The consumer rereads everything; revisions seen before mean nothing for what follows.\n              seen.clear();\n              yield event.message === undefined ? { type: 'reset', reason: event.reason } : { type: 'reset', reason: event.reason, message: event.message };\n              continue;\n            }\n            healthy = true;\n            // A dropped change is still a resume position.\n            lastEventId = event.eventId;\n            if (!seen.admit(event.collectionId, event.recordId, event.revision, event.change)) continue;\n            const change: RecordChange = {\n              type: 'change',\n              eventId: event.eventId,\n              collection: aliases.get(event.collectionId) ?? event.collectionId,\n              collectionId: event.collectionId,\n              occurredAt: event.occurredAt,\n              restricted: event.restricted,\n              change: event.change,\n              recordId: event.recordId,\n              revision: event.revision,\n            };\n            yield redact ? redactRestricted(change) : change;\n          }\n        } catch (error) {\n          if (stop.signal.aborted) return;\n          if (!(error instanceof DataError)) throw error;\n          if (isStaleCollectionError(error)) {\n            let changed: boolean;\n            try {\n              changed = await runtime.rebuild(state, error, definitions);\n            } catch (cause) {\n              if (!(cause instanceof DataError) || !cause.retry.safe) throw cause;\n              await backOff(cause.retry.afterMs);\n              continue;\n            }\n            if (!changed) throw error;\n            // Recreated collections have new IDs; their old cursor means nothing.\n            lastEventId = undefined;\n            seen.clear();\n            yield { type: 'reset', reason: 'COLLECTION_RECREATED' };\n            continue;\n          }\n          if (!error.retry.safe) throw error;\n          await backOff(error.retry.afterMs);\n          continue;\n        } finally {\n          clearTimeout(idle);\n          connection.abort();\n          stop.signal.removeEventListener('abort', closeConnection);\n        }\n        // The stream ended or went silent. Reconnect at once after a healthy connection, else back off.\n        if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) healthy = true;\n        if (healthy) failures = 0;\n        else failures += 1;\n        // A reset always waits a moment: a server resetting in a loop is not reconnected to in a loop.\n        const wait = Math.max(reset ? RESET_PAUSE_MS : 0, healthy ? 0 : reconnectDelay(failures, undefined));\n        if (wait > 0) await pause(wait, stop.signal);\n      }\n    } finally {\n      stop.abort();\n      options.signal?.removeEventListener('abort', onAbort);\n    }\n  };\n}\n"]}
+{"version":3,"file":"subscribe.js","sourceRoot":"","sources":["../../../src/data/subscribe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `data.subscribe`: committed record changes of declared collections over\n * UNS `records:subscribe` (server-sent events), as one async iterable that\n * outlives single connections.\n *\n * - Reconnects with `Last-Event-ID` when the stream ends, breaks, or stays\n *   silent for `idleTimeoutMs` (UNS sends a heartbeat every 15 s). A stream\n *   that dies young without a change backs off, so a server dropping every\n *   connection is not hammered.\n * - Failures marked `retry.safe` (429 over the subscription limit, 503,\n *   `APP_NOT_READY` from ensure …) are retried after `retry.afterMs` or a\n *   backoff of up to 30 s, without end; any other failure ends the\n *   iteration with that DataError.\n * - `reset` is passed on: `CURSOR_EXPIRED` (the position was cleaned up after\n *   24 h, cannot be decoded after a key rotation, or the tenant database\n *   moved) or `SCOPE_CHANGED` (access changed, e.g. a collection is no longer\n *   readable). The consumer reloads what it shows; the next connection\n *   starts from now, without a resume position. A collection recreated\n *   under a new ID (see bootstrap self-healing) yields `COLLECTION_RECREATED`.\n * - UNS delivers changes in write-transaction order, not commit order, so\n *   revisions of one record may arrive out of order. A non-delete change at\n *   or below the revision already passed on for its record is dropped; a\n *   `delete` always passes, a late one too, and forgets the record's\n *   revision, since a record written again under the same ID may start\n *   over at revision 1.\n * - Aborting `signal` or leaving the loop ends the iteration without error.\n * - The stream runs as the App: it sees every change of the collections\n *   granted to the App. A server opens one per process and fans it out to\n *   browsers with `createChangeRelay`, filtering per browser by what the App\n *   lets that visitor see.\n *\n * Events carry identities only, never record data; read the record to show it.\n */\nimport { isStaleCollectionError, type EnsureState } from './bootstrap.js';\nimport type { DataOpenStream } from './call.js';\nimport { assertEventId, UNS_V2_SUBSCRIBE_MAX_COLLECTIONS, UNS_V2_SUBSCRIBE_MAX_RECORD_IDS } from '../uns-v2/client.js';\nimport { collectionLabel, type CollectionTarget } from './define.js';\nimport { DataError } from './error.js';\n\n/** Three missed 15 s heartbeats. */\nexport const SUBSCRIBE_IDLE_TIMEOUT_MS = 45_000;\nconst RECONNECT_BASE_MS = 500;\nconst RECONNECT_MAX_MS = 30_000;\n/** After a reset, the next connection waits at least this long. */\nconst RESET_PAUSE_MS = 1_000;\n/** A connection alive this long counts as healthy even without changes. */\nconst HEALTHY_CONNECTION_MS = 30_000;\n/** Records whose last revision is remembered; beyond this the oldest is forgotten (a stale change may then pass, which only costs a reread). */\nconst SUBSCRIBE_SEEN_RECORDS_MAX = 10_000;\n\nexport interface SubscribeOptions {\n  /** Declarations, aliases, or existing-ID references (at most 64); defaults to every declared collection. */\n  collections?: readonly (CollectionTarget | string)[];\n  /** Only changes of these record IDs (1–100, duplicates ignored), when exactly one collection is watched. */\n  recordIds?: readonly string[];\n  /** Resume after this event (e.g. a browser's `Last-Event-ID`). */\n  lastEventId?: string;\n  signal?: AbortSignal;\n  /** Reconnect when nothing, not even a heartbeat, arrives for this long. */\n  idleTimeoutMs?: number;\n}\n\n/**\n * One record committed (`record`) or deleted (`delete`) at `revision`. A\n * `record` change is never at or below a revision already passed on for the\n * same record since its last delete; a `delete` may be.\n */\nexport interface RecordChange {\n  type: 'change';\n  eventId: string;\n  /** Alias of a declared collection, or the ID of an existing collection reference. */\n  collection: string;\n  collectionId: string;\n  occurredAt: number;\n  change: 'record' | 'delete';\n  recordId: string;\n  revision: number;\n}\n\n/** `reason`: `CURSOR_EXPIRED`, `SCOPE_CHANGED` (from UNS) or `COLLECTION_RECREATED`. */\nexport type SubscriptionEvent = RecordChange | { type: 'reset'; reason: string; message?: string };\n\n/**\n * What `data.subscribe` tells a server-side consumer about the upstream\n * (`createChangeRelay` uses it; not part of the public API).\n */\nexport interface SubscribeObserver {\n  /** A connection is streaming: its first frame (the connect heartbeat) arrived. */\n  connected?(): void;\n  /** The resume position moved: a heartbeat position or a change, dropped or not. */\n  position?(eventId: string): void;\n  /** An attempt failed and will be retried after a wait (e.g. 429 over the subscription limit, `APP_NOT_READY`). */\n  retrying?(error: DataError): void;\n}\n\nexport interface SubscribeRuntime {\n  openStream: DataOpenStream;\n  ensure(targets: readonly CollectionTarget[]): Promise<EnsureState>;\n  rebuild(before: EnsureState, cause: DataError, targets: readonly CollectionTarget[]): Promise<boolean>;\n  resolve(target: CollectionTarget): Promise<string>;\n  lookup(target: CollectionTarget | string): CollectionTarget;\n  declared: readonly CollectionTarget[];\n}\n\nfunction reconnectDelay(failures: number, afterMs: number | undefined): number {\n  if (afterMs !== undefined) return Math.min(afterMs, RECONNECT_MAX_MS);\n  const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.max(0, failures - 1));\n  return ceiling / 2 + Math.random() * (ceiling / 2);\n}\n\n/**\n * The highest revision passed on per record, so changes delivered out of\n * order are dropped (UNS orders by write transaction, not by commit).\n */\nclass SeenRevisions {\n  private readonly revisions = new Map<string, number>();\n\n  constructor(private readonly max: number) {}\n\n  /** Whether the change is new; remembers its revision, or forgets the record on delete. */\n  admit(collectionId: string, recordId: string, revision: number, change: 'record' | 'delete'): boolean {\n    const key = `${collectionId}\\u0000${recordId}`;\n    const seen = this.revisions.get(key);\n    // A delete always passes, a late one too: the record may be written again under the same ID, from revision 1.\n    if (change === 'delete') {\n      this.revisions.delete(key);\n      return true;\n    }\n    if (seen !== undefined && revision <= seen) return false;\n    this.revisions.delete(key);\n    this.revisions.set(key, revision);\n    if (this.revisions.size > this.max) this.revisions.delete(this.revisions.keys().next().value!);\n    return true;\n  }\n\n  clear() {\n    this.revisions.clear();\n  }\n}\n\nfunction pause(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal.aborted) return resolve();\n    const done = () => {\n      clearTimeout(timer);\n      signal.removeEventListener('abort', done);\n      resolve();\n    };\n    const timer = setTimeout(done, ms);\n    signal.addEventListener('abort', done, { once: true });\n  });\n}\n\nexport function createSubscribe(runtime: SubscribeRuntime) {\n  return async function* subscribe(options: SubscribeOptions = {}, observer: SubscribeObserver = {}): AsyncGenerator<SubscriptionEvent, void, undefined> {\n    const definitions = [...new Set((options.collections ?? runtime.declared).map(runtime.lookup))];\n    if (definitions.length < 1 || definitions.length > UNS_V2_SUBSCRIBE_MAX_COLLECTIONS) {\n      throw new TypeError(`data.subscribe watches 1–${UNS_V2_SUBSCRIBE_MAX_COLLECTIONS} collections; got ${definitions.length}.`);\n    }\n    const recordIds = options.recordIds === undefined ? undefined : [...new Set(options.recordIds)];\n    if (recordIds && (recordIds.length < 1 || recordIds.length > UNS_V2_SUBSCRIBE_MAX_RECORD_IDS || definitions.length !== 1)) {\n      throw new TypeError(`data.subscribe takes 1–${UNS_V2_SUBSCRIBE_MAX_RECORD_IDS} recordIds, of exactly one collection.`);\n    }\n    if (options.lastEventId !== undefined) assertEventId(options.lastEventId);\n    const idleMs = options.idleTimeoutMs ?? SUBSCRIBE_IDLE_TIMEOUT_MS;\n    const stop = new AbortController();\n    const onAbort = () => stop.abort();\n    options.signal?.addEventListener('abort', onAbort, { once: true });\n    if (options.signal?.aborted) stop.abort();\n    let lastEventId = options.lastEventId;\n    let failures = 0;\n    const seen = new SeenRevisions(SUBSCRIBE_SEEN_RECORDS_MAX);\n    /** Waits, longer each time, before the next attempt. */\n    const backOff = async (error: DataError) => {\n      observer.retrying?.(error);\n      const afterMs = error.retry.afterMs;\n      failures += 1;\n      await pause(reconnectDelay(failures, afterMs), stop.signal);\n    };\n    try {\n      while (!stop.signal.aborted) {\n        let state: EnsureState;\n        try {\n          state = await runtime.ensure(definitions);\n        } catch (error) {\n          // A freshly imported App answers APP_NOT_READY for a while: keep waiting for it.\n          if (!(error instanceof DataError) || !error.retry.safe || stop.signal.aborted) throw error;\n          await backOff(error);\n          continue;\n        }\n        const aliases = new Map<string, string>();\n        for (const definition of definitions) {\n          const id = await runtime.resolve(definition);\n          aliases.set(id, collectionLabel(definition));\n        }\n\n        const connection = new AbortController();\n        const closeConnection = () => connection.abort();\n        stop.signal.addEventListener('abort', closeConnection, { once: true });\n        let idle: ReturnType<typeof setTimeout> | undefined;\n        const arm = () => {\n          clearTimeout(idle);\n          idle = setTimeout(closeConnection, idleMs);\n        };\n        const openedAt = Date.now();\n        let healthy = false;\n        let reset = false;\n        let streaming = false;\n        try {\n          arm();\n          const stream = runtime.openStream(\n            { collectionIds: [...aliases.keys()], ...(recordIds ? { recordIds } : {}) },\n            { lastEventId, signal: connection.signal },\n          );\n          for await (const event of stream) {\n            arm();\n            if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) healthy = true;\n            if (!streaming) {\n              streaming = true;\n              observer.connected?.();\n            }\n            if (event.type === 'heartbeat') {\n              // The connect heartbeat names the current position: resuming from it loses nothing.\n              if (event.eventId !== undefined) {\n                lastEventId = event.eventId;\n                observer.position?.(event.eventId);\n              }\n              continue;\n            }\n            if (event.type === 'reset') {\n              lastEventId = undefined;\n              reset = true;\n              // The consumer rereads everything; revisions seen before mean nothing for what follows.\n              seen.clear();\n              yield event.message === undefined ? { type: 'reset', reason: event.reason } : { type: 'reset', reason: event.reason, message: event.message };\n              continue;\n            }\n            healthy = true;\n            // A dropped change is still a resume position.\n            lastEventId = event.eventId;\n            observer.position?.(event.eventId);\n            if (!seen.admit(event.collectionId, event.recordId, event.revision, event.change)) continue;\n            yield {\n              type: 'change',\n              eventId: event.eventId,\n              collection: aliases.get(event.collectionId) ?? event.collectionId,\n              collectionId: event.collectionId,\n              occurredAt: event.occurredAt,\n              change: event.change,\n              recordId: event.recordId,\n              revision: event.revision,\n            };\n          }\n        } catch (error) {\n          if (stop.signal.aborted) return;\n          if (!(error instanceof DataError)) throw error;\n          if (isStaleCollectionError(error)) {\n            let changed: boolean;\n            try {\n              changed = await runtime.rebuild(state, error, definitions);\n            } catch (cause) {\n              if (!(cause instanceof DataError) || !cause.retry.safe) throw cause;\n              await backOff(cause);\n              continue;\n            }\n            if (!changed) throw error;\n            // Recreated collections have new IDs; their old cursor means nothing.\n            lastEventId = undefined;\n            seen.clear();\n            yield { type: 'reset', reason: 'COLLECTION_RECREATED' };\n            continue;\n          }\n          if (!error.retry.safe) throw error;\n          await backOff(error);\n          continue;\n        } finally {\n          clearTimeout(idle);\n          connection.abort();\n          stop.signal.removeEventListener('abort', closeConnection);\n        }\n        // The stream ended or went silent. Reconnect at once after a healthy connection, else back off.\n        if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) healthy = true;\n        if (healthy) failures = 0;\n        else failures += 1;\n        // A reset always waits a moment: a server resetting in a loop is not reconnected to in a loop.\n        const wait = Math.max(reset ? RESET_PAUSE_MS : 0, healthy ? 0 : reconnectDelay(failures, undefined));\n        if (wait > 0) await pause(wait, stop.signal);\n      }\n    } finally {\n      stop.abort();\n      options.signal?.removeEventListener('abort', onAbort);\n    }\n  };\n}\n"]}

package/dist/esm/event-stream.d.ts

@@ -0,0 +1,28 @@
+import { type ServerSentEvent } from './uns-v2/sse.js';
+export interface EventStreamOptions {
+    url: string;
+    headers?: Record<string, string>;
+    lastEventId?: string;
+    fetch?: typeof globalThis.fetch;
+    onEvent(event: ServerSentEvent): void;
+    /**
+     * The stream is back after a pause for the App's sleep or an authorization
+     * failure. Events may have been missed, resume position or not.
+     */
+    onResume?(): void;
+    /** The stream ended for good; it does not reconnect. Not called after `close()`. */
+    onClose?(error: EventStreamError): void;
+    /** Reconnect when nothing, not even a heartbeat, arrives for this long. Off by default. */
+    idleTimeoutMs?: number;
+    /** Close the connection while the page is hidden and resume from the last event id when it is visible. Default true. */
+    pauseWhenHidden?: boolean;
+}
+export interface EventStream {
+    close(): void;
+}
+export declare class EventStreamError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, code: string | undefined);
+}
+export declare function openEventStream(options: EventStreamOptions): EventStream;

package/dist/esm/event-stream.js

@@ -0,0 +1,217 @@
+/**
+ * A server-sent event stream over `fetch`, for browsers. `EventSource` gives up
+ * for good on any HTTP error, so a 503 from a sleeping App or a restarting node
+ * agent (design 21.1) would end it. This one reads the error and acts on it:
+ *
+ * - `sbx_sleeping`, `sbx_starting`: stop, and reconnect on the runtime's
+ *   `resumed`. Without the runtime `sbx_sleeping` ends the stream and
+ *   `sbx_starting` waits `retry_after_ms`.
+ * - an authorization failure: reported to the runtime, then as above. A
+ *   successful reauthorization also fires `resumed`.
+ * - `node_restarting`, `upstream_error` and any other retryable failure, and a
+ *   broken connection: reconnect by itself after `retry_after_ms` or a backoff,
+ *   resuming from `Last-Event-ID`.
+ * - a non-retryable failure: ends the stream.
+ *
+ * While the runtime says `sleeping` nothing is sent: those requests would not
+ * wake the App anyway.
+ *
+ * While the page is hidden (`document.visibilityState`) the connection is
+ * closed, so a background tab does not hold a long connection to the App;
+ * when the page is visible again it reconnects at once from the last event
+ * id (`Last-Event-ID`). The server replays what was missed or answers with
+ * its own reset; `onResume` is not called for it. `pauseWhenHidden: false`
+ * keeps the connection open in the background.
+ */
+import { getPageRuntime, onPageRuntime, isAuthErrorCode, isAppSleeping, readPlatformError, reportAuthError } from './page-runtime.js';
+import { parseServerSentEvents } from './uns-v2/sse.js';
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+/** A connection alive this long resets the backoff. */
+const HEALTHY_CONNECTION_MS = 30_000;
+/**
+ * A paused stream looks again this often while the runtime still says
+ * `running`: a routing race can answer `sbx_sleeping` for a running App, and
+ * then no `resumed` ever comes. Such a request cannot wake anything.
+ */
+const PAUSE_RECHECK_MS = 30_000;
+export class EventStreamError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`Event stream refused with HTTP ${status}${code ? ` (${code})` : ''}.`);
+        this.status = status;
+        this.code = code;
+        this.name = 'EventStreamError';
+    }
+}
+function classify(status, failure) {
+    const code = failure?.code;
+    const runtime = getPageRuntime() !== undefined;
+    if (isAuthErrorCode(code)) {
+        reportAuthError(code);
+        return runtime ? { next: 'pause' } : { next: 'end', error: new EventStreamError(status, code) };
+    }
+    if (code === 'sbx_sleeping' || code === 'sbx_starting' || code === 'sbx_start_failed') {
+        if (runtime)
+            return { next: 'pause' };
+        if (code !== 'sbx_starting')
+            return { next: 'end', error: new EventStreamError(status, code) };
+    }
+    if (failure?.retryable)
+        return { next: 'reconnect', afterMs: failure.retryAfterMs };
+    // Not ours to classify: an edge proxy's 5xx passes, a route's 4xx is final.
+    if (!failure && status >= 500)
+        return { next: 'reconnect' };
+    return { next: 'end', error: new EventStreamError(status, code) };
+}
+export function openEventStream(options) {
+    const { url, onEvent, onResume, onClose, idleTimeoutMs } = options;
+    let lastEventId = options.lastEventId;
+    let closed = false;
+    let paused = isAppSleeping();
+    let resumedFromPause = false;
+    let failures = 0;
+    let resumes = 0;
+    let connection;
+    let wake;
+    const page = (options.pauseWhenHidden ?? true) && typeof document !== 'undefined' ? document : undefined;
+    let hidden = page?.visibilityState === 'hidden';
+    const onVisibility = () => {
+        hidden = page.visibilityState === 'hidden';
+        if (hidden)
+            connection?.abort();
+        wake?.();
+    };
+    page?.addEventListener('visibilitychange', onVisibility);
+    const sleep = (ms) => new Promise((resolve) => {
+        const timer = ms === undefined ? undefined : setTimeout(() => done(), ms);
+        const done = () => {
+            clearTimeout(timer);
+            wake = undefined;
+            resolve();
+        };
+        wake = done;
+    });
+    const offSleeping = onPageRuntime('sleeping', () => {
+        paused = true;
+        connection?.abort();
+        wake?.();
+    });
+    const offResumed = onPageRuntime('resumed', () => {
+        if (paused)
+            resumedFromPause = true;
+        paused = false;
+        resumes += 1;
+        wake?.();
+    });
+    function backoff() {
+        failures += 1;
+        const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** (failures - 1));
+        return ceiling / 2 + Math.random() * (ceiling / 2);
+    }
+    async function consume(body, controller) {
+        const openedAt = Date.now();
+        let idle;
+        const arm = () => {
+            if (idleTimeoutMs === undefined)
+                return;
+            clearTimeout(idle);
+            idle = setTimeout(() => controller.abort(), idleTimeoutMs);
+        };
+        arm();
+        try {
+            for await (const event of parseServerSentEvents(body)) {
+                arm();
+                if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS)
+                    failures = 0;
+                if ('comment' in event)
+                    continue;
+                if (event.id !== undefined)
+                    lastEventId = event.id;
+                if ('event' in event)
+                    onEvent(event);
+            }
+        }
+        finally {
+            clearTimeout(idle);
+        }
+    }
+    async function connect() {
+        const controller = new AbortController();
+        connection = controller;
+        const headers = { ...options.headers, Accept: 'text/event-stream' };
+        if (lastEventId !== undefined)
+            headers['Last-Event-ID'] = lastEventId;
+        try {
+            const response = await (options.fetch ?? globalThis.fetch)(url, { headers, cache: 'no-store', signal: controller.signal });
+            const type = response.headers.get('content-type') ?? '';
+            if (response.ok && /^text\/event-stream\b/i.test(type) && response.body) {
+                if (resumedFromPause) {
+                    resumedFromPause = false;
+                    onResume?.();
+                }
+                await consume(response.body, controller);
+                return { next: 'reconnect' };
+            }
+            const failure = await readPlatformError(response);
+            await response.body?.cancel().catch(() => undefined);
+            return classify(response.status, failure);
+        }
+        catch {
+            return { next: 'reconnect' };
+        }
+        finally {
+            connection = undefined;
+        }
+    }
+    async function run() {
+        while (!closed) {
+            if (hidden) {
+                await sleep();
+                continue;
+            }
+            if (paused) {
+                await sleep(getPageRuntime()?.getState() === 'running' ? PAUSE_RECHECK_MS : undefined);
+                if (getPageRuntime()?.getState() === 'running' && !closed) {
+                    resumedFromPause = true;
+                    paused = false;
+                }
+                continue;
+            }
+            const seenResumes = resumes;
+            const outcome = await connect();
+            if (closed)
+                return;
+            if (outcome.next === 'end') {
+                close();
+                onClose?.(outcome.error);
+                return;
+            }
+            if (outcome.next === 'pause') {
+                // A `resumed` that arrived while the refusal was on its way already happened.
+                if (resumes === seenResumes)
+                    paused = true;
+                else
+                    resumedFromPause = true;
+                continue;
+            }
+            // Closed for a hidden page: wait for it to be visible, not for a backoff.
+            if (hidden)
+                continue;
+            if (!paused)
+                await sleep(outcome.afterMs ?? backoff());
+        }
+    }
+    function close() {
+        closed = true;
+        offSleeping();
+        offResumed();
+        page?.removeEventListener('visibilitychange', onVisibility);
+        connection?.abort();
+        wake?.();
+    }
+    void run();
+    return { close };
+}
+//# sourceMappingURL=event-stream.js.map

package/dist/esm/event-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-stream.js","sourceRoot":"","sources":["../../src/event-stream.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A server-sent event stream over `fetch`, for browsers. `EventSource` gives up\n * for good on any HTTP error, so a 503 from a sleeping App or a restarting node\n * agent (design 21.1) would end it. This one reads the error and acts on it:\n *\n * - `sbx_sleeping`, `sbx_starting`: stop, and reconnect on the runtime's\n *   `resumed`. Without the runtime `sbx_sleeping` ends the stream and\n *   `sbx_starting` waits `retry_after_ms`.\n * - an authorization failure: reported to the runtime, then as above. A\n *   successful reauthorization also fires `resumed`.\n * - `node_restarting`, `upstream_error` and any other retryable failure, and a\n *   broken connection: reconnect by itself after `retry_after_ms` or a backoff,\n *   resuming from `Last-Event-ID`.\n * - a non-retryable failure: ends the stream.\n *\n * While the runtime says `sleeping` nothing is sent: those requests would not\n * wake the App anyway.\n *\n * While the page is hidden (`document.visibilityState`) the connection is\n * closed, so a background tab does not hold a long connection to the App;\n * when the page is visible again it reconnects at once from the last event\n * id (`Last-Event-ID`). The server replays what was missed or answers with\n * its own reset; `onResume` is not called for it. `pauseWhenHidden: false`\n * keeps the connection open in the background.\n */\nimport { getPageRuntime, onPageRuntime, isAuthErrorCode, isAppSleeping, readPlatformError, reportAuthError, type PlatformError } from './page-runtime.js';\nimport { parseServerSentEvents, type ServerSentEvent } from './uns-v2/sse.js';\n\nconst RECONNECT_BASE_MS = 1_000;\nconst RECONNECT_MAX_MS = 30_000;\n/** A connection alive this long resets the backoff. */\nconst HEALTHY_CONNECTION_MS = 30_000;\n/**\n * A paused stream looks again this often while the runtime still says\n * `running`: a routing race can answer `sbx_sleeping` for a running App, and\n * then no `resumed` ever comes. Such a request cannot wake anything.\n */\nconst PAUSE_RECHECK_MS = 30_000;\n\nexport interface EventStreamOptions {\n  url: string;\n  headers?: Record<string, string>;\n  lastEventId?: string;\n  fetch?: typeof globalThis.fetch;\n  onEvent(event: ServerSentEvent): void;\n  /**\n   * The stream is back after a pause for the App's sleep or an authorization\n   * failure. Events may have been missed, resume position or not.\n   */\n  onResume?(): void;\n  /** The stream ended for good; it does not reconnect. Not called after `close()`. */\n  onClose?(error: EventStreamError): void;\n  /** Reconnect when nothing, not even a heartbeat, arrives for this long. Off by default. */\n  idleTimeoutMs?: number;\n  /** Close the connection while the page is hidden and resume from the last event id when it is visible. Default true. */\n  pauseWhenHidden?: boolean;\n}\n\nexport interface EventStream {\n  close(): void;\n}\n\nexport class EventStreamError extends Error {\n  constructor(readonly status: number, readonly code: string | undefined) {\n    super(`Event stream refused with HTTP ${status}${code ? ` (${code})` : ''}.`);\n    this.name = 'EventStreamError';\n  }\n}\n\ntype Outcome =\n  | { next: 'reconnect'; afterMs?: number }\n  | { next: 'pause' }\n  | { next: 'end'; error: EventStreamError };\n\nfunction classify(status: number, failure: PlatformError | undefined): Outcome {\n  const code = failure?.code;\n  const runtime = getPageRuntime() !== undefined;\n  if (isAuthErrorCode(code)) {\n    reportAuthError(code);\n    return runtime ? { next: 'pause' } : { next: 'end', error: new EventStreamError(status, code) };\n  }\n  if (code === 'sbx_sleeping' || code === 'sbx_starting' || code === 'sbx_start_failed') {\n    if (runtime) return { next: 'pause' };\n    if (code !== 'sbx_starting') return { next: 'end', error: new EventStreamError(status, code) };\n  }\n  if (failure?.retryable) return { next: 'reconnect', afterMs: failure.retryAfterMs };\n  // Not ours to classify: an edge proxy's 5xx passes, a route's 4xx is final.\n  if (!failure && status >= 500) return { next: 'reconnect' };\n  return { next: 'end', error: new EventStreamError(status, code) };\n}\n\nexport function openEventStream(options: EventStreamOptions): EventStream {\n  const { url, onEvent, onResume, onClose, idleTimeoutMs } = options;\n  let lastEventId = options.lastEventId;\n  let closed = false;\n  let paused = isAppSleeping();\n  let resumedFromPause = false;\n  let failures = 0;\n  let resumes = 0;\n  let connection: AbortController | undefined;\n  let wake: (() => void) | undefined;\n  const page = (options.pauseWhenHidden ?? true) && typeof document !== 'undefined' ? document : undefined;\n  let hidden = page?.visibilityState === 'hidden';\n  const onVisibility = () => {\n    hidden = page!.visibilityState === 'hidden';\n    if (hidden) connection?.abort();\n    wake?.();\n  };\n  page?.addEventListener('visibilitychange', onVisibility);\n\n  const sleep = (ms?: number) => new Promise<void>((resolve) => {\n    const timer = ms === undefined ? undefined : setTimeout(() => done(), ms);\n    const done = () => {\n      clearTimeout(timer);\n      wake = undefined;\n      resolve();\n    };\n    wake = done;\n  });\n\n  const offSleeping = onPageRuntime('sleeping', () => {\n    paused = true;\n    connection?.abort();\n    wake?.();\n  });\n  const offResumed = onPageRuntime('resumed', () => {\n    if (paused) resumedFromPause = true;\n    paused = false;\n    resumes += 1;\n    wake?.();\n  });\n\n  function backoff(): number {\n    failures += 1;\n    const ceiling = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** (failures - 1));\n    return ceiling / 2 + Math.random() * (ceiling / 2);\n  }\n\n  async function consume(body: ReadableStream<Uint8Array>, controller: AbortController): Promise<void> {\n    const openedAt = Date.now();\n    let idle: ReturnType<typeof setTimeout> | undefined;\n    const arm = () => {\n      if (idleTimeoutMs === undefined) return;\n      clearTimeout(idle);\n      idle = setTimeout(() => controller.abort(), idleTimeoutMs);\n    };\n    arm();\n    try {\n      for await (const event of parseServerSentEvents(body)) {\n        arm();\n        if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) failures = 0;\n        if ('comment' in event) continue;\n        if (event.id !== undefined) lastEventId = event.id;\n        if ('event' in event) onEvent(event);\n      }\n    } finally {\n      clearTimeout(idle);\n    }\n  }\n\n  async function connect(): Promise<Outcome> {\n    const controller = new AbortController();\n    connection = controller;\n    const headers: Record<string, string> = { ...options.headers, Accept: 'text/event-stream' };\n    if (lastEventId !== undefined) headers['Last-Event-ID'] = lastEventId;\n    try {\n      const response = await (options.fetch ?? globalThis.fetch)(url, { headers, cache: 'no-store', signal: controller.signal });\n      const type = response.headers.get('content-type') ?? '';\n      if (response.ok && /^text\\/event-stream\\b/i.test(type) && response.body) {\n        if (resumedFromPause) {\n          resumedFromPause = false;\n          onResume?.();\n        }\n        await consume(response.body, controller);\n        return { next: 'reconnect' };\n      }\n      const failure = await readPlatformError(response);\n      await response.body?.cancel().catch(() => undefined);\n      return classify(response.status, failure);\n    } catch {\n      return { next: 'reconnect' };\n    } finally {\n      connection = undefined;\n    }\n  }\n\n  async function run(): Promise<void> {\n    while (!closed) {\n      if (hidden) {\n        await sleep();\n        continue;\n      }\n      if (paused) {\n        await sleep(getPageRuntime()?.getState() === 'running' ? PAUSE_RECHECK_MS : undefined);\n        if (getPageRuntime()?.getState() === 'running' && !closed) {\n          resumedFromPause = true;\n          paused = false;\n        }\n        continue;\n      }\n      const seenResumes = resumes;\n      const outcome = await connect();\n      if (closed) return;\n      if (outcome.next === 'end') {\n        close();\n        onClose?.(outcome.error);\n        return;\n      }\n      if (outcome.next === 'pause') {\n        // A `resumed` that arrived while the refusal was on its way already happened.\n        if (resumes === seenResumes) paused = true;\n        else resumedFromPause = true;\n        continue;\n      }\n      // Closed for a hidden page: wait for it to be visible, not for a backoff.\n      if (hidden) continue;\n      if (!paused) await sleep(outcome.afterMs ?? backoff());\n    }\n  }\n\n  function close(): void {\n    closed = true;\n    offSleeping();\n    offResumed();\n    page?.removeEventListener('visibilitychange', onVisibility);\n    connection?.abort();\n    wake?.();\n  }\n\n  void run();\n  return { close };\n}\n"]}

package/dist/esm/mq/client.d.ts

@@ -13,11 +13,40 @@ export declare class Tier0MQClient {
     private explicitUsername;
     private listeners;
     private subscriptions;
+    private topicSubscriptions;
+    private pendingTopicPackets;
+    private sentTopicPackets;
     private connectingPromise;
+    private rejectPendingConnect;
     private _connected;
+    /** Bumped by disconnect(); callbacks of an older generation are ignored. */
+    private generation;
+    /** Random clientId segment; a persistent session is found again through it. */
+    private readonly clientSuffix;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private connectWaiters;
     constructor(config?: MQTTConfig);
-    private get mqttUrl();
+    private mqttUrlFor;
+    /**
+     * Where the credential comes from; undefined when a fixed password is used.
+     * `proxy`: platform proxy mode, the node proxy puts in the App's key and
+     * the SDK sends none.
+     */
+    private tokenSource;
+    /** Local preflight before a transport exists: address and credentials must be usable. */
+    private validateConnectionConfig;
+    /**
+     * What the next connection presents. Through the node proxy the same
+     * identity reconnects, and the proxy puts in the App's current key.
+     */
+    private connectionParams;
     private ensureConnected;
+    private clearReconnect;
+    private reconnectDelay;
+    private scheduleReconnect;
+    /** The same client: mqtt.js keeps its session and offline queue. */
+    private reconnect;
     private doConnect;
     connect(config?: MQTTConfig): Promise<void>;
     subscribe(topic: string, handler: TopicHandler): void;
@@ -31,6 +60,8 @@ export declare class Tier0MQClient {
     off<K extends keyof MQTTEventMap>(event: K, handler: MQTTEventMap[K]): void;
     private emit;
     private resubscribeAll;
+    private clearTopicState;
+    private subscribeTopic;
     private topicMatch;
     get isConnected(): boolean;
     get subscribedTopics(): string[];