@streamotter/client 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orca Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @streamotter/client
+
+The StreamOtter browser SDK. Subscribe to a **state channel** served by a [StreamOtter gateway](https://www.npmjs.com/package/@streamotter/gateway): each subscription gets an authoritative snapshot, then full-state updates in revision order. It also reports whether the view is verifiably current (`live`) or not (`stale`), so a screen is never silently wrong.
+
+> **Release candidate.** `0.1.0-rc.1` is published under the `next` tag. Package versions follow SemVer independently of the V1 protocol (`protocolVersion: 1`).
+
+```bash
+npm install @streamotter/client@next
+```
+
+Transport: Socket.IO 4.8.3 over WebSocket only. Targets current evergreen browsers. ESM only, with TypeScript declarations included.
+
+## Subscribe
+
+Generate your channel types from the project configuration (`streamotter generate`, from [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli)), then:
+
+```ts
+import { createClient } from "@streamotter/client";
+import { channelVersions, type AppChannels } from "./generated/streamotter.generated.js";
+
+const client = createClient<AppChannels>({
+  origin: "https://app.example.com",   // default: the page's origin
+  // path: "/streamotter/socket.io",     // default
+  getToken: ({ signal }) => session.getAccessToken(signal)  // your application's session token
+});
+
+const job = client.subscribe("jobProgress", {
+  channelVersion: channelVersions.jobProgress,
+  params: { jobId: "job_1" }
+});
+job.on("data", event => render(event.data));          // full state; replace, don't merge
+job.on("state", ({ state }) => showDeliveryState(state));
+job.on("error", error => console.warn(`[${error.code}] ${error.message}`));
+await job.ready({ timeoutMs: 30_000 });               // resolves at the next `live`
+```
+
+`subscribe()` returns immediately and starts in the next microtask, so listeners attached synchronously never miss the snapshot. Data events are not replayed to listeners added later. Each `data` event carries `kind` (`"snapshot"` or `"update"`), `revision` (a decimal string), `data`, and `receivedAt`.
+
+The gateway decides who may see what. `getToken` supplies your application's own session token, which the gateway's `authenticate` handler verifies. The browser never chooses its tenant.
+
+## Render the delivery state
+
+| State | Meaning | What to show |
+| --- | --- | --- |
+| `authorizing`, `synchronizing` | Checking access, loading the snapshot | A loading state. Keep any previous data visibly provisional. |
+| `live` | Synchronized with the gateway while its source is healthy | The data as current. |
+| `stale` | Connection loss, source outage, overflow, or a snapshot timeout. The SDK is recovering automatically. | The last data, marked as possibly out of date. |
+| `resync-required` | Automatic recovery used its attempts (three per incident) | A retry action that calls `job.resync()`. |
+| `failed` | Terminal: access denied (`FORBIDDEN`), a handler failed, or the data was invalid | The error. To try again, create a new subscription. |
+| `closed` | Unsubscribed, or the client was closed | Nothing. |
+
+`live` means synchronized up to the gateway's drain boundary. It is not a wall-clock freshness guarantee. Treat every other state as "may be stale".
+
+The client has its own connection state (`client.state`, `client.on("state", …)`): `idle`, `connecting`, `connected`, `reconnecting`, `auth-required`, `closed`. Network failures reconnect automatically with full-jitter backoff (500 ms up to 30 s) while subscriptions are active, and every active subscription gets a fresh snapshot. `auth-required` means the token was rejected or expired, or `getToken` failed or timed out (10 s). Refresh the user's session, then call `client.reconnect()`. If the signed-in account changes, the old subscriptions close with `UNAUTHENTICATED` instead of showing the previous user's data.
+
+## Handle errors
+
+Every failure is a `StreamError`: `{ code, message, retryable, requestId, details? }`. Promises (`ready`, `resync`, `reconnect`) reject with it, and `error` listeners receive it. `isStreamError(value)` narrows unknown values.
+
+- `FORBIDDEN`: this user may not see this channel instance. Unknown channels also return `FORBIDDEN`, so nothing leaks. Don't retry.
+- `UNAUTHENTICATED`: the session is invalid or expired. Re-authenticate, then `client.reconnect()`.
+- `RESYNC_REQUIRED`, `TIMEOUT`, `SOURCE_UNAVAILABLE`, `OVERLOADED`: may work later. Offer a retry, but don't loop.
+- `INVALID_PARAMS`: the parameters don't match the channel's schema.
+- `CLIENT_CLOSED`: the client was closed.
+
+A listener that throws, or returns a rejected promise, fails its subscription with `HANDLER_FAILED`. Keep listeners cheap: state replacement, not heavy processing.
+
+## Clean up
+
+```ts
+await job.unsubscribe();   // idempotent; resolves after the gateway confirms (at most 5 s)
+await client.close();      // closes every subscription and the connection, permanently
+```
+
+Unsubscribe when a view unmounts. Close a shared client only when its owning application scope ends.
+
+## React hook pattern
+
+Create one client per signed-in session and one subscription per mounted component:
+
+```tsx
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { createClient, type Client, type StreamError, type SubscriptionState } from "@streamotter/client";
+import { channelVersions, type AppChannels, type JobProgress } from "./generated/streamotter.generated.js";
+
+const ClientContext = createContext<Client<AppChannels> | null>(null);
+
+export function StreamOtterProvider({ getToken, children }: { getToken: () => Promise<string>; children: ReactNode }) {
+  const client = useMemo(() => createClient<AppChannels>({ getToken }), [getToken]);
+  useEffect(() => () => { void client.close(); }, [client]);
+  return <ClientContext.Provider value={client}>{children}</ClientContext.Provider>;
+}
+
+export function useJobProgress(jobId: string) {
+  const client = useContext(ClientContext);
+  const [data, setData] = useState<JobProgress | null>(null);
+  const [state, setState] = useState<SubscriptionState>("idle");
+  const [error, setError] = useState<StreamError | null>(null);
+  useEffect(() => {
+    if (client === null) return;
+    setData(null);
+    setError(null);
+    const job = client.subscribe("jobProgress", { channelVersion: channelVersions.jobProgress, params: { jobId } });
+    const offData = job.on("data", event => setData(event.data));
+    const offState = job.on("state", change => setState(change.state));
+    const offError = job.on("error", setError);
+    return () => { offData(); offState(); offError(); void job.unsubscribe(); };
+  }, [client, jobId]);
+  return { data, state, error, live: state === "live" };
+}
+```
+
+Pass a stable `getToken` (for example from `useCallback`) so the client is not recreated on every render. The [reference application](https://github.com/jfricano/StreamOtter/tree/main/examples/order-dashboard) has vanilla TypeScript and React versions of this pattern, including denied access and reconnection.
+
+## More
+
+- [V1 API specification](https://github.com/jfricano/StreamOtter/blob/main/docs/V1_API.md): SDK (§4), states and synchronization (§5), errors (§9)
+- [Implementation status](https://github.com/jfricano/StreamOtter/blob/main/docs/IMPLEMENTATION_STATUS.md): what is verified, and the known limitations (for example, automated browser checks cover Chromium only)
+- [Repository](https://github.com/jfricano/StreamOtter) · [Issues](https://github.com/jfricano/StreamOtter/issues)
+
+MIT License © 2026 Orca Solutions

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import { type ChannelMap, type Client, type ClientOptions, type ConnectionState, type StateChange, type StreamError, type Subscription, type Unlisten, type WaitOptions } from "@streamotter/contracts";
+import { Connection } from "./connection.ts";
+import { type ManagedSubscription, type SubscriptionOwner } from "./subscription.ts";
+/**
+ * Browser SDK client. Owns one Socket.IO connection at a time, reconnects with
+ * full-jitter backoff while subscriptions are active, suspends on authentication
+ * rejection until reconnect(), refreshes before token expiry, and closes prior
+ * subscriptions when the authenticated identity changes.
+ */
+export declare class StreamClient<C extends ChannelMap> implements Client<C>, SubscriptionOwner {
+    #private;
+    constructor(options: ClientOptions);
+    get state(): ConnectionState;
+    get closed(): boolean;
+    get authRequired(): boolean;
+    get connection(): Connection | null;
+    register(subscription: ManagedSubscription): void;
+    unregister(subscription: ManagedSubscription): void;
+    controlTimedOut(connection: Connection): void;
+    randomId(): string;
+    logListenerFailure(error: unknown): void;
+    subscribe<K extends keyof C & string>(channel: K, options: {
+        channelVersion: C[K]["version"];
+        params: C[K]["params"];
+    }): Subscription<C[K]["data"]>;
+    on(event: "state", listener: (state: StateChange<ConnectionState>) => void): Unlisten;
+    on(event: "error", listener: (error: StreamError) => void): Unlisten;
+    /** Obtains a new token, replaces the connection, and recreates active subscriptions with fresh snapshots. */
+    reconnect(options?: WaitOptions): Promise<void>;
+    close(): Promise<void>;
+}
+/** Creates an idle client; it connects when the first subscription starts. */
+export declare function createClient<C extends ChannelMap>(options: ClientOptions): Client<C>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EACzD,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EACpG,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAsB,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAuBzG;;;;;GAKG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,UAAU,CAAE,YAAW,MAAM,CAAC,CAAC,CAAC,EAAE,iBAAiB;;gBAsBzE,OAAO,EAAE,aAAa;IAUlC,IAAI,KAAK,IAAI,eAAe,CAE3B;IAID,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,UAAU,IAAI,UAAU,GAAG,IAAI,CAElC;IAED,QAAQ,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;IAYjD,UAAU,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;IAInD,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAM7C,QAAQ,IAAI,MAAM;IAIlB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAMxC,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE;QAAE,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;KAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAanJ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,KAAK,IAAI,GAAG,QAAQ;IACrF,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,QAAQ;IAUpE,6GAA6G;IAC7G,SAAS,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAgSvB;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAEpF"}

package/dist/client.js

@@ -0,0 +1,462 @@
+import { asStreamOtterError, DEFAULT_READY_TIMEOUT_MS, DEFAULT_SOCKET_PATH, GET_TOKEN_TIMEOUT_MS, parseUtcTimestamp, RECONNECT_BASE_MS, RECONNECT_CAP_MS, streamError, StreamOtterError, TOKEN_REFRESH_LEAD_MS } from "@streamotter/contracts";
+import { Connection } from "./connection.js";
+import { ClientSubscription } from "./subscription.js";
+function resolveOrigin(origin) {
+    const candidate = origin ?? globalThis.location?.origin;
+    if (typeof candidate !== "string") {
+        throw new StreamOtterError("INVALID_REQUEST", { message: "origin is required outside a browser page." });
+    }
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new StreamOtterError("INVALID_REQUEST", { message: "origin must be an absolute http(s) origin." });
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.origin !== candidate.replace(/\/$/, "")) {
+        throw new StreamOtterError("INVALID_REQUEST", { message: "origin must be an absolute http(s) origin without a path." });
+    }
+    return url.origin;
+}
+function randomId() {
+    return globalThis.crypto.randomUUID();
+}
+/**
+ * Browser SDK client. Owns one Socket.IO connection at a time, reconnects with
+ * full-jitter backoff while subscriptions are active, suspends on authentication
+ * rejection until reconnect(), refreshes before token expiry, and closes prior
+ * subscriptions when the authenticated identity changes.
+ */
+export class StreamClient {
+    #origin;
+    #path;
+    #getToken;
+    #stateListeners = new Set();
+    #errorListeners = new Set();
+    #subscriptions = new Set();
+    #state = "idle";
+    #connection = null;
+    #identityKey = null;
+    #generation = 0;
+    #connecting = false;
+    #suspended = false;
+    #closed = false;
+    #everConnected = false;
+    #attempt = 0;
+    #lastConnectionError = null;
+    #reconnectTimer = null;
+    #refreshTimer = null;
+    #tokenAbort = null;
+    #closing = null;
+    constructor(options) {
+        if (typeof options !== "object" || options === null || typeof options.getToken !== "function") {
+            throw new StreamOtterError("INVALID_REQUEST", { message: "createClient requires a getToken function." });
+        }
+        this.#origin = resolveOrigin(options.origin);
+        this.#path = options.path ?? DEFAULT_SOCKET_PATH;
+        if (!this.#path.startsWith("/"))
+            throw new StreamOtterError("INVALID_REQUEST", { message: "path must start with /." });
+        this.#getToken = options.getToken;
+    }
+    get state() {
+        return this.#state;
+    }
+    // --- SubscriptionOwner ---------------------------------------------------------------
+    get closed() {
+        return this.#closed;
+    }
+    get authRequired() {
+        return this.#suspended;
+    }
+    get connection() {
+        return this.#connection !== null && this.#connection.connected ? this.#connection : null;
+    }
+    register(subscription) {
+        if (this.#closed)
+            return;
+        this.#subscriptions.add(subscription);
+        if (this.#suspended) {
+            subscription.authRequired(this.#lastConnectionError ?? streamError("UNAUTHENTICATED"));
+            return;
+        }
+        const connection = this.connection;
+        if (connection !== null)
+            subscription.attach(connection);
+        else
+            this.#ensureConnection();
+    }
+    unregister(subscription) {
+        this.#subscriptions.delete(subscription);
+    }
+    controlTimedOut(connection) {
+        if (connection !== this.#connection)
+            return;
+        // After an ambiguous control request, rebuild on a new connection instead of retrying on this one.
+        connection.close();
+    }
+    randomId() {
+        return randomId();
+    }
+    logListenerFailure(error) {
+        console.error("[streamotter] listener failed", error);
+    }
+    // --- public API ------------------------------------------------------------------------
+    subscribe(channel, options) {
+        if (this.#closed)
+            throw new StreamOtterError("CLIENT_CLOSED");
+        if (typeof channel !== "string" || typeof options !== "object" || options === null
+            || typeof options.channelVersion !== "number" || typeof options.params !== "object" || options.params === null) {
+            throw new StreamOtterError("INVALID_REQUEST", { message: "subscribe requires a channel name, channelVersion, and params." });
+        }
+        const unsupported = Object.keys(options).find(key => key !== "channelVersion" && key !== "params");
+        if (unsupported !== undefined) {
+            throw new StreamOtterError("UNSUPPORTED_CAPABILITY", { message: `"${unsupported}" is not supported by this SDK version.` });
+        }
+        return new ClientSubscription(this, channel, options.channelVersion, { ...options.params });
+    }
+    on(event, listener) {
+        const set = (event === "state" ? this.#stateListeners : event === "error" ? this.#errorListeners : undefined);
+        if (set === undefined || typeof listener !== "function") {
+            throw new StreamOtterError("INVALID_REQUEST", { message: "on() accepts \"state\" or \"error\" with a function." });
+        }
+        set.add(listener);
+        return () => { set.delete(listener); };
+    }
+    /** Obtains a new token, replaces the connection, and recreates active subscriptions with fresh snapshots. */
+    reconnect(options) {
+        if (this.#closed)
+            return Promise.reject(new StreamOtterError("CLIENT_CLOSED"));
+        this.#suspended = false;
+        this.#lastConnectionError = null;
+        this.#attempt = 0;
+        this.#clearReconnectTimer();
+        const previous = this.#connection;
+        this.#connection = null;
+        this.#connecting = false;
+        this.#generation++;
+        if (previous !== null) {
+            previous.close();
+            for (const subscription of this.#subscriptions)
+                subscription.detach();
+        }
+        const wait = this.#waitForConnection(options);
+        void this.#connect(true);
+        return wait;
+    }
+    close() {
+        if (this.#closing !== null)
+            return this.#closing;
+        this.#closed = true;
+        this.#generation++;
+        this.#clearReconnectTimer();
+        this.#clearRefreshTimer();
+        this.#tokenAbort?.abort();
+        const error = streamError("CLIENT_CLOSED");
+        for (const subscription of [...this.#subscriptions])
+            subscription.terminateLocally("closed", error, false);
+        this.#subscriptions.clear();
+        this.#connection?.close();
+        this.#connection = null;
+        this.#setState("closed");
+        this.#stateListeners.clear();
+        this.#errorListeners.clear();
+        this.#closing = Promise.resolve();
+        return this.#closing;
+    }
+    // --- connection management -------------------------------------------------------------
+    #ensureConnection() {
+        if (this.#closed || this.#suspended || this.#connecting || this.#reconnectTimer !== null)
+            return;
+        if (this.#connection !== null)
+            return;
+        void this.#connect(false);
+    }
+    async #connect(explicit) {
+        if (this.#closed)
+            return;
+        const generation = ++this.#generation;
+        this.#connecting = true;
+        this.#setState(this.#everConnected && !explicit ? "reconnecting" : "connecting");
+        let opened;
+        try {
+            opened = await this.#open();
+        }
+        catch (error) {
+            if (generation !== this.#generation)
+                return;
+            this.#connecting = false;
+            this.#handleConnectFailure(error);
+            return;
+        }
+        if (generation !== this.#generation) {
+            opened.connection.close();
+            return;
+        }
+        this.#connecting = false;
+        this.#adopt(opened.connection, opened.hello);
+    }
+    /** getToken (ten-second deadline) then a new authenticated connection. */
+    async #open() {
+        const controller = new AbortController();
+        this.#tokenAbort = controller;
+        let token;
+        let timer;
+        try {
+            token = await Promise.race([
+                Promise.resolve().then(() => this.#getToken({ signal: controller.signal })),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => {
+                        controller.abort();
+                        reject(streamError("UNAUTHENTICATED", { message: "getToken did not resolve within ten seconds.", retryable: true }));
+                    }, GET_TOKEN_TIMEOUT_MS);
+                })
+            ]);
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && "code" in error && error.code === "UNAUTHENTICATED")
+                throw error;
+            throw streamError("UNAUTHENTICATED", { message: "getToken failed; call reconnect() once the application session is available.", retryable: true });
+        }
+        finally {
+            clearTimeout(timer);
+            if (this.#tokenAbort === controller)
+                this.#tokenAbort = null;
+        }
+        if (typeof token !== "string" || token.length === 0) {
+            throw streamError("UNAUTHENTICATED", { message: "getToken must resolve to a non-empty string.", retryable: false });
+        }
+        let connection = null;
+        const events = {
+            state: (frame) => this.#route(connection, frame.subscriptionId, sub => sub.handleState(connection, frame)),
+            data: (frame) => this.#route(connection, frame.subscriptionId, sub => sub.handleData(connection, frame)),
+            error: (frame) => this.#handleErrorFrame(connection, frame),
+            disconnect: () => this.#handleDisconnect(connection)
+        };
+        connection = new Connection({ origin: this.#origin, path: this.#path, token, events });
+        const hello = await connection.ready;
+        return { connection, hello };
+    }
+    #adopt(connection, hello) {
+        if (this.#closed) {
+            connection.close();
+            return;
+        }
+        const previous = this.#connection;
+        this.#connection = connection;
+        if (previous !== null && previous !== connection)
+            previous.close();
+        if (this.#identityKey !== null && hello.identityKey !== this.#identityKey) {
+            // Never carry a previous user's view across an account switch.
+            const error = streamError("UNAUTHENTICATED", { message: "The authenticated identity changed; create new subscriptions for the new identity." });
+            for (const subscription of [...this.#subscriptions])
+                subscription.terminateLocally("closed", error, true);
+            this.#subscriptions.clear();
+            this.#emitError(error);
+        }
+        this.#identityKey = hello.identityKey;
+        this.#everConnected = true;
+        this.#attempt = 0;
+        this.#lastConnectionError = null;
+        this.#setState("connected");
+        this.#scheduleRefresh(hello.authExpiresAt);
+        for (const subscription of [...this.#subscriptions])
+            subscription.attach(connection);
+    }
+    #handleConnectFailure(error) {
+        this.#lastConnectionError = error;
+        this.#emitError(error);
+        const suspend = error.code === "UNAUTHENTICATED" || error.code === "FORBIDDEN"
+            || error.code === "INVALID_REQUEST" || error.code === "UNSUPPORTED_CAPABILITY";
+        if (suspend)
+            this.#suspend(error);
+        else
+            this.#scheduleReconnect();
+    }
+    #handleDisconnect(connection) {
+        if (connection === null || connection !== this.#connection)
+            return;
+        this.#connection = null;
+        this.#clearRefreshTimer();
+        const error = this.#lastConnectionError;
+        const reason = error?.code;
+        for (const subscription of this.#subscriptions)
+            subscription.detach(reason);
+        if (this.#closed)
+            return;
+        if (error !== null && error.code === "UNAUTHENTICATED" && !error.retryable) {
+            this.#suspend(error);
+            return;
+        }
+        if (error !== null && error.code === "UNAUTHENTICATED")
+            this.#attempt = 0; // Expiry: reconnect promptly.
+        this.#scheduleReconnect();
+    }
+    #suspend(error) {
+        this.#suspended = true;
+        this.#clearReconnectTimer();
+        this.#setState("auth-required", error.code);
+        for (const subscription of [...this.#subscriptions])
+            subscription.authRequired(error);
+    }
+    #scheduleReconnect() {
+        if (this.#closed || this.#suspended)
+            return;
+        this.#clearReconnectTimer();
+        if (this.#subscriptions.size === 0) {
+            this.#setState("idle");
+            return;
+        }
+        this.#setState("reconnecting", this.#lastConnectionError?.code);
+        const ceiling = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** this.#attempt);
+        this.#attempt++;
+        const delay = Math.random() * ceiling;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            if (this.#subscriptions.size === 0) {
+                this.#setState("idle");
+                return;
+            }
+            void this.#connect(false);
+        }, delay);
+    }
+    #scheduleRefresh(authExpiresAt) {
+        this.#clearRefreshTimer();
+        const expiresAt = parseUtcTimestamp(authExpiresAt);
+        if (!Number.isFinite(expiresAt))
+            return;
+        const delay = expiresAt - TOKEN_REFRESH_LEAD_MS - Date.now();
+        if (delay <= 0 || delay > 2_147_000_000)
+            return;
+        this.#refreshTimer = setTimeout(() => {
+            this.#refreshTimer = null;
+            void this.#refresh(expiresAt);
+        }, delay);
+    }
+    /** Replaces the connection with a freshly authenticated one before the token expires. */
+    async #refresh(expiresAt) {
+        if (this.#closed || this.#suspended || this.#connection === null)
+            return;
+        const generation = this.#generation;
+        try {
+            const opened = await this.#open();
+            if (generation !== this.#generation || this.#closed || this.#suspended) {
+                opened.connection.close();
+                return;
+            }
+            this.#generation++;
+            this.#adopt(opened.connection, opened.hello);
+        }
+        catch (error) {
+            if (generation !== this.#generation)
+                return;
+            this.#emitError(error);
+            if (Date.now() + 5_000 < expiresAt) {
+                this.#refreshTimer = setTimeout(() => {
+                    this.#refreshTimer = null;
+                    void this.#refresh(expiresAt);
+                }, 5_000);
+            }
+        }
+    }
+    #waitForConnection(options) {
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+        const signal = options?.signal;
+        if (signal?.aborted)
+            return Promise.reject(new StreamOtterError("CANCELLED"));
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                unlisten();
+            };
+            const onAbort = () => { cleanup(); reject(new StreamOtterError("CANCELLED")); };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new StreamOtterError("TIMEOUT", { message: `The client did not connect within ${timeoutMs} ms.` }));
+            }, timeoutMs);
+            const unlisten = this.#onInternalState(state => {
+                if (state === "connected") {
+                    cleanup();
+                    resolve();
+                }
+                else if (state === "auth-required") {
+                    cleanup();
+                    reject(asStreamOtterError(this.#lastConnectionError ?? streamError("UNAUTHENTICATED")));
+                }
+                else if (state === "closed") {
+                    cleanup();
+                    reject(new StreamOtterError("CLIENT_CLOSED"));
+                }
+            });
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    #internalStateListeners = new Set();
+    #onInternalState(listener) {
+        this.#internalStateListeners.add(listener);
+        return () => { this.#internalStateListeners.delete(listener); };
+    }
+    #route(connection, subscriptionId, handle) {
+        if (connection === null || connection !== this.#connection)
+            return;
+        for (const subscription of this.#subscriptions) {
+            if (subscription.id === subscriptionId) {
+                handle(subscription);
+                return;
+            }
+        }
+    }
+    #handleErrorFrame(connection, frame) {
+        if (connection === null || connection !== this.#connection)
+            return;
+        if (frame.subscriptionId !== undefined) {
+            this.#route(connection, frame.subscriptionId, subscription => subscription.handleError(connection, frame.error));
+            return;
+        }
+        this.#lastConnectionError = frame.error;
+        this.#emitError(frame.error);
+    }
+    #setState(state, reason) {
+        if (this.#state === state)
+            return;
+        this.#state = state;
+        const change = reason === undefined ? { state } : { state, reason };
+        for (const listener of [...this.#internalStateListeners])
+            listener(state);
+        for (const listener of [...this.#stateListeners]) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                this.logListenerFailure(error);
+            }
+        }
+    }
+    #emitError(error) {
+        for (const listener of [...this.#errorListeners]) {
+            try {
+                listener(error);
+            }
+            catch (cause) {
+                this.logListenerFailure(cause);
+            }
+        }
+    }
+    #clearReconnectTimer() {
+        if (this.#reconnectTimer !== null) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
+        }
+    }
+    #clearRefreshTimer() {
+        if (this.#refreshTimer !== null) {
+            clearTimeout(this.#refreshTimer);
+            this.#refreshTimer = null;
+        }
+    }
+}
+/** Creates an idle client; it connects when the first subscription starts. */
+export function createClient(options) {
+    return new StreamClient(options);
+}
+//# sourceMappingURL=client.js.map