@parlor/sync 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cychien
+
+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

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @parlor/sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The live-update protocol: the cursor and event types the server and the page exchange so queries refresh when data changes. Installed by `@parlor/server` and `@parlor/client`; you do not depend on it directly.
+
+```ts
+import { INITIAL_CURSOR, SYNC_PROTOCOL_VERSION } from "@parlor/sync";
+
+console.log(SYNC_PROTOCOL_VERSION, INITIAL_CURSOR);
+```
+
+Docs: https://cychien.github.io/parlor/guides/deploy/

package/dist/channel.d.ts

@@ -0,0 +1,21 @@
+import type { Principal } from "@parlor/core";
+export interface ServerChannel {
+    readonly event: string;
+    connect(connection: ChannelConnection): () => void;
+}
+export interface ChannelConnection {
+    readonly clientId: string | undefined;
+    readonly scope: string;
+    /** Who holds the stream; absent when the server resolves no identity. */
+    readonly principal?: Principal | undefined;
+    /** Aborts when the stream ends, including when its holder's credential is revoked. */
+    readonly closed?: AbortSignal | undefined;
+    send(data: string): void;
+}
+export interface ClientChannel {
+    readonly event: string;
+    opened(): void;
+    receive(data: string): void;
+    closed(): void;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC3C,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,IAAI,IAAI,CAAC;CAChB"}

package/dist/channel.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":""}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { parseSseChunk, readSse, type SseFrame } from "./sse.js";
+export { createSyncClient, type SyncClient, type SyncClientOptions, type SyncRequest, SyncRequestTimeout, SyncUnauthorized, } from "./sync-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { parseSseChunk, readSse } from "./sse.js";
+export { createSyncClient, SyncRequestTimeout, SyncUnauthorized, } from "./sync-client.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAiB,MAAM,UAAU,CAAC;AACjE,OAAO,EACL,gBAAgB,EAIhB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/client/sse.d.ts

@@ -0,0 +1,10 @@
+export interface SseFrame {
+    readonly event: string;
+    readonly data: string;
+}
+export declare function parseSseChunk(buffer: string): {
+    frames: SseFrame[];
+    rest: string;
+};
+export declare function readSse(body: ReadableStream<Uint8Array>, onFrame: (frame: SseFrame) => void, signal?: AbortSignal, onChunk?: () => void): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/client/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/client/sse.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAkBlF;AAED,wBAAsB,OAAO,CAC3B,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,EAClC,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/client/sse.js

@@ -0,0 +1,48 @@
+export function parseSseChunk(buffer) {
+    const frames = [];
+    let rest = buffer;
+    for (;;) {
+        const end = rest.indexOf("\n\n");
+        if (end === -1)
+            break;
+        const block = rest.slice(0, end);
+        rest = rest.slice(end + 2);
+        let event = "message";
+        const data = [];
+        for (const line of block.split("\n")) {
+            if (line.startsWith(":"))
+                continue;
+            if (line.startsWith("event:"))
+                event = line.slice(6).trim();
+            else if (line.startsWith("data:"))
+                data.push(line.slice(5).trimStart());
+        }
+        if (data.length > 0)
+            frames.push({ event, data: data.join("\n") });
+    }
+    return { frames, rest };
+}
+export async function readSse(body, onFrame, signal, onChunk) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const abort = () => void reader.cancel().catch(() => { });
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            onChunk?.();
+            buffer += decoder.decode(value, { stream: true });
+            const { frames, rest } = parseSseChunk(buffer);
+            buffer = rest;
+            for (const frame of frames)
+                onFrame(frame);
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/client/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/client/sse.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,SAAS,CAAC;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,MAAM;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAC3B,IAAI,KAAK,GAAG,SAAS,CAAC;QACtB,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACnC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACvD,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAgC,EAChC,OAAkC,EAClC,MAAoB,EACpB,OAAoB;IAEpB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACzD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,OAAO,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;YAC/C,MAAM,GAAG,IAAI,CAAC;YACd,KAAK,MAAM,KAAK,IAAI,MAAM;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/client/sync-client.d.ts

@@ -0,0 +1,70 @@
+import type { ClientChannel } from "../channel.js";
+import { type SyncEvent } from "../protocol.js";
+export type SyncRequest = (path: string, init?: RequestInit) => Promise<Response>;
+export interface SyncClientOptions {
+    readonly request: SyncRequest;
+    readonly basePath?: string | undefined;
+    readonly clientId?: string | undefined;
+    readonly onEvents: (events: SyncEvent[]) => void;
+    readonly onError?: ((error: unknown) => void) | undefined;
+    readonly coalesceMs?: number | undefined;
+    readonly safetyPollMs?: number | undefined;
+    readonly hiddenPollMs?: number | undefined;
+    readonly reconnectBaseMs?: number | undefined;
+    readonly reconnectMaxMs?: number | undefined;
+    readonly isHidden?: (() => boolean) | undefined;
+    readonly setTimeout?: typeof globalThis.setTimeout | undefined;
+    readonly clearTimeout?: typeof globalThis.clearTimeout | undefined;
+    readonly channels?: readonly ClientChannel[] | undefined;
+    /**
+     * Read each time the next poll is scheduled; the interval is the larger of this and the
+     * negotiated one, so a caller can only slow polling down.
+     */
+    readonly pollEveryMs?: (() => number) | undefined;
+    /** Bounds a negotiation or a poll, not the SSE stream. Defaults to 10 s. */
+    readonly requestTimeoutMs?: number | undefined;
+    /**
+     * What the server negotiated, each time it does; `SyncClient.transport` reads `poll`
+     * during the fallback poll of a failed negotiation, this never does.
+     */
+    readonly onNegotiated?: ((transport: "sse" | "poll") => void) | undefined;
+    /**
+     * The negotiated transport's connection came back after a failure: a stream reopened
+     * after it dropped, or a poll succeeded after a failed one. A fallback poll on an SSE
+     * deployment does not count.
+     */
+    readonly onResume?: (() => void) | undefined;
+    /**
+     * The server refused the credential (401 or 403). The client never degrades to polling
+     * on it; it keeps retrying the negotiation with backoff. Defaults to `onError`.
+     */
+    readonly onUnauthorized?: ((error: SyncUnauthorized) => void) | undefined;
+}
+export declare class SyncUnauthorized extends Error {
+    readonly status: number;
+    readonly name = "SyncUnauthorized";
+    constructor(status: number);
+}
+export declare class SyncRequestTimeout extends Error {
+    readonly ms: number;
+    readonly name = "SyncRequestTimeout";
+    constructor(ms: number);
+}
+export interface SyncClient {
+    start(): void;
+    stop(): void;
+    /**
+     * Registers a channel after `start`, for features loaded lazily. It opens at once when
+     * the live stream's handshake lists it, else on the next stream. Returns the detach.
+     */
+    addChannel(channel: ClientChannel): () => void;
+    /**
+     * Skips the remaining reconnect backoff, for `online` and visibility events. While
+     * polling it polls at once; with a stream open or a request in flight it does nothing.
+     */
+    reconnectNow(): void;
+    readonly cursor: string;
+    readonly transport: "sse" | "poll" | undefined;
+}
+export declare function createSyncClient(options: SyncClientOptions): SyncClient;
+//# sourceMappingURL=sync-client.d.ts.map

package/dist/client/sync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-client.d.ts","sourceRoot":"","sources":["../../src/client/sync-client.ts"],"names":[],"mappings":"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"}

package/dist/client/sync-client.js

@@ -0,0 +1,447 @@
+import { compareCursors, cursorOf, decodeCursor, encodeCursor, INITIAL_CURSOR, LEGACY_KEEP_ALIVE_MS, streamLivenessMs, } from "../protocol.js";
+import { readSse } from "./sse.js";
+export class SyncUnauthorized extends Error {
+    status;
+    name = "SyncUnauthorized";
+    constructor(status) {
+        super(`sync was refused with HTTP ${status}`);
+        this.status = status;
+    }
+}
+export class SyncRequestTimeout extends Error {
+    ms;
+    name = "SyncRequestTimeout";
+    constructor(ms) {
+        super(`sync request timed out after ${ms} ms`);
+        this.ms = ms;
+    }
+}
+class StaleRequest extends Error {
+    name = "StaleRequest";
+}
+const refused = (response) => response.status === 401 || response.status === 403;
+const DEFAULTS = {
+    coalesceMs: 250,
+    safetyPollMs: 60_000,
+    hiddenPollMs: 10_000,
+    reconnectBaseMs: 1000,
+    reconnectMaxMs: 30_000,
+    requestTimeoutMs: 10_000,
+};
+function parseHandshake(handshake) {
+    try {
+        const { capabilities, keepAliveMs } = JSON.parse(handshake);
+        return {
+            capabilities: Array.isArray(capabilities)
+                ? capabilities.filter((c) => typeof c === "string")
+                : [],
+            keepAliveMs: typeof keepAliveMs === "number" && keepAliveMs > 0 ? keepAliveMs : undefined,
+        };
+    }
+    catch {
+        return { capabilities: [], keepAliveMs: undefined };
+    }
+}
+export function createSyncClient(options) {
+    const basePath = options.basePath ?? "/_parlor";
+    const settings = {
+        coalesceMs: options.coalesceMs ?? DEFAULTS.coalesceMs,
+        safetyPollMs: options.safetyPollMs ?? DEFAULTS.safetyPollMs,
+        hiddenPollMs: options.hiddenPollMs ?? DEFAULTS.hiddenPollMs,
+        reconnectBaseMs: options.reconnectBaseMs ?? DEFAULTS.reconnectBaseMs,
+        reconnectMaxMs: options.reconnectMaxMs ?? DEFAULTS.reconnectMaxMs,
+        requestTimeoutMs: options.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
+        clientId: options.clientId,
+        onError: options.onError,
+    };
+    const schedule = options.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms));
+    const cancel = options.clearTimeout ?? ((id) => globalThis.clearTimeout(id));
+    const isHidden = options.isHidden ?? (() => false);
+    const channels = new Map((options.channels ?? []).map((c) => [c.event, c]));
+    const guarded = (run) => {
+        try {
+            run();
+        }
+        catch (error) {
+            settings.onError?.(error);
+        }
+    };
+    let cursor = INITIAL_CURSOR;
+    let transport;
+    let negotiated;
+    let interrupted = false;
+    let running = false;
+    let controller;
+    let pollTimer;
+    let flushTimer;
+    let pending = [];
+    let reconnectDelay = settings.reconnectBaseMs;
+    let endReconnectWait;
+    let connectTimer;
+    let epoch = 0;
+    const inflight = new Set();
+    const withTimeout = async (run) => {
+        const mine = epoch;
+        const own = new AbortController();
+        inflight.add(own);
+        let timer;
+        const expired = new Promise((_, reject) => {
+            timer = schedule(() => {
+                own.abort();
+                reject(new SyncRequestTimeout(settings.requestTimeoutMs));
+            }, settings.requestTimeoutMs);
+        });
+        try {
+            const result = await Promise.race([run(own.signal), expired]);
+            if (mine !== epoch)
+                throw new StaleRequest();
+            return result;
+        }
+        catch (error) {
+            if (mine !== epoch)
+                throw new StaleRequest();
+            throw error;
+        }
+        finally {
+            inflight.delete(own);
+            if (timer !== undefined)
+                cancel(timer);
+        }
+    };
+    const resumed = () => {
+        if (!interrupted)
+            return;
+        interrupted = false;
+        guarded(() => options.onResume?.());
+    };
+    const accept = (events) => {
+        for (const event of events) {
+            const at = cursorOf(event);
+            if (compareCursors(at, cursor) <= 0)
+                continue;
+            cursor = at;
+            if (event.source && event.source === settings.clientId)
+                continue;
+            pending.push(event);
+        }
+        if (pending.length > 0 && flushTimer === undefined) {
+            flushTimer = schedule(() => {
+                flushTimer = undefined;
+                const batch = pending;
+                pending = [];
+                options.onEvents(batch);
+            }, settings.coalesceMs);
+        }
+    };
+    const since = () => (cursor === INITIAL_CURSOR ? "" : encodeCursor(cursor));
+    const poll = async (mine) => {
+        const batch = await withTimeout(async (signal) => {
+            const response = await options.request(`${basePath}/sync?since=${encodeURIComponent(since())}`, { signal });
+            if (refused(response))
+                throw new SyncUnauthorized(response.status);
+            if (!response.ok)
+                throw new Error(`sync poll failed with HTTP ${response.status}`);
+            return (await response.json());
+        });
+        if (mine !== epoch)
+            throw new StaleRequest();
+        accept(batch.events);
+        if (running && negotiated === "poll")
+            resumed();
+    };
+    const schedulePoll = (ms) => {
+        if (!running)
+            return;
+        if (pollTimer !== undefined)
+            cancel(pollTimer);
+        pollTimer = schedule(() => {
+            pollTimer = undefined;
+            let halted = false;
+            const mine = epoch;
+            void poll(mine)
+                .catch((error) => {
+                if (error instanceof StaleRequest || mine !== epoch) {
+                    halted = true;
+                    return;
+                }
+                if (negotiated === "poll")
+                    interrupted = true;
+                if (error instanceof SyncUnauthorized) {
+                    halted = true;
+                    unauthorized(error);
+                    if (transport === "poll") {
+                        transport = undefined;
+                        connectTimer = schedule(() => {
+                            connectTimer = undefined;
+                            void connect();
+                        }, backoff());
+                    }
+                    return;
+                }
+                settings.onError?.(error);
+            })
+                .finally(() => {
+                if (!halted)
+                    schedulePoll(nextPollDelay());
+            });
+        }, ms);
+    };
+    const nextPollDelay = () => {
+        if (transport === "sse")
+            return settings.safetyPollMs;
+        const base = Math.max(negotiatedPollMs, options.pollEveryMs?.() ?? 0);
+        return isHidden() ? Math.max(base, settings.hiddenPollMs) : base;
+    };
+    let negotiatedPollMs = 2000;
+    const negotiate = async () => {
+        return withTimeout(async (signal) => {
+            const response = await options.request(`${basePath}/sync/token`, {
+                method: "POST",
+                signal,
+            });
+            if (refused(response))
+                throw new SyncUnauthorized(response.status);
+            if (!response.ok)
+                throw new Error(`sync negotiation failed with HTTP ${response.status}`);
+            return (await response.json());
+        });
+    };
+    let live;
+    const stream = async (endpoint) => {
+        const own = new AbortController();
+        controller = own;
+        let keepAliveMs = LEGACY_KEEP_ALIVE_MS;
+        let silent = false;
+        let watchdog;
+        const rearm = () => {
+            if (watchdog !== undefined)
+                cancel(watchdog);
+            watchdog = schedule(() => {
+                silent = true;
+                own.abort();
+            }, streamLivenessMs(keepAliveMs));
+        };
+        const open = new Set();
+        const current = { listed: new Set(), open };
+        live = current;
+        rearm();
+        try {
+            const response = await options.request(`${endpoint}?since=${encodeURIComponent(since())}`, {
+                headers: { accept: "text/event-stream" },
+                signal: own.signal,
+            });
+            if (refused(response))
+                throw new SyncUnauthorized(response.status);
+            if (!response.ok || !response.body) {
+                throw new Error(`sync stream failed with HTTP ${response.status}`);
+            }
+            reconnectDelay = settings.reconnectBaseMs;
+            resumed();
+            await readSse(response.body, (frame) => {
+                if (frame.event === "message") {
+                    const batch = JSON.parse(frame.data);
+                    accept(batch.events);
+                    const parsed = decodeCursor(batch.cursor);
+                    if (compareCursors(parsed, cursor) > 0)
+                        cursor = parsed;
+                    return;
+                }
+                if (frame.event === "handshake") {
+                    const handshake = parseHandshake(frame.data);
+                    keepAliveMs = handshake.keepAliveMs ?? LEGACY_KEEP_ALIVE_MS;
+                    rearm();
+                    current.listed = new Set(handshake.capabilities);
+                    for (const event of handshake.capabilities) {
+                        const channel = channels.get(event);
+                        if (!channel || open.has(channel))
+                            continue;
+                        open.add(channel);
+                        guarded(() => channel.opened());
+                    }
+                    return;
+                }
+                const channel = channels.get(frame.event);
+                if (channel && open.has(channel))
+                    guarded(() => channel.receive(frame.data));
+            }, own.signal, rearm);
+        }
+        catch (error) {
+            if (!silent)
+                throw error;
+        }
+        finally {
+            if (watchdog !== undefined)
+                cancel(watchdog);
+            if (live === current)
+                live = undefined;
+            for (const channel of open)
+                guarded(() => channel.closed());
+        }
+    };
+    const unauthorized = (error) => {
+        if (pollTimer !== undefined)
+            cancel(pollTimer);
+        pollTimer = undefined;
+        (options.onUnauthorized ?? settings.onError)?.(error);
+    };
+    const backoff = () => {
+        const delay = reconnectDelay;
+        reconnectDelay = Math.min(reconnectDelay * 2, settings.reconnectMaxMs);
+        return delay;
+    };
+    let connecting = false;
+    const connect = async () => {
+        if (connecting)
+            return;
+        connecting = true;
+        const mine = epoch;
+        try {
+            await connectLoop(mine);
+        }
+        finally {
+            if (mine === epoch)
+                connecting = false;
+        }
+    };
+    const connectLoop = async (mine) => {
+        const active = () => running && mine === epoch;
+        for (;;) {
+            if (!active())
+                return;
+            let endpoint;
+            try {
+                const negotiation = await negotiate();
+                if (!active())
+                    return;
+                negotiatedPollMs = negotiation.pollIntervalMs;
+                negotiated = negotiation.transport;
+                guarded(() => options.onNegotiated?.(negotiation.transport));
+                if (negotiation.transport === "poll") {
+                    transport = "poll";
+                    schedulePoll(0);
+                    return;
+                }
+                endpoint = negotiation.endpoint;
+            }
+            catch (error) {
+                if (!active())
+                    return;
+                interrupted = true;
+                if (error instanceof SyncUnauthorized) {
+                    transport = undefined;
+                    unauthorized(error);
+                }
+                else {
+                    settings.onError?.(error);
+                    if (transport !== "poll") {
+                        transport = "poll";
+                        schedulePoll(negotiatedPollMs);
+                    }
+                }
+            }
+            if (endpoint !== undefined) {
+                transport = "sse";
+                schedulePoll(settings.safetyPollMs);
+                try {
+                    await stream(endpoint);
+                }
+                catch (error) {
+                    if (!active())
+                        return;
+                    if (error instanceof SyncUnauthorized)
+                        unauthorized(error);
+                    else
+                        settings.onError?.(error);
+                }
+                interrupted = true;
+            }
+            if (!active())
+                return;
+            const delay = backoff();
+            await new Promise((resolve) => {
+                const timer = schedule(() => {
+                    endReconnectWait = undefined;
+                    resolve();
+                }, delay);
+                endReconnectWait = () => {
+                    cancel(timer);
+                    endReconnectWait = undefined;
+                    resolve();
+                };
+            });
+        }
+    };
+    const detachChannel = (channel) => {
+        if (channels.get(channel.event) !== channel)
+            return;
+        channels.delete(channel.event);
+        if (live?.open.delete(channel))
+            guarded(() => channel.closed());
+    };
+    const start = () => {
+        if (running)
+            return;
+        running = true;
+        void connect();
+    };
+    const reconnectNow = () => {
+        if (!running)
+            return;
+        if (endReconnectWait) {
+            reconnectDelay = settings.reconnectBaseMs;
+            endReconnectWait();
+        }
+        else if (connectTimer !== undefined) {
+            cancel(connectTimer);
+            connectTimer = undefined;
+            reconnectDelay = settings.reconnectBaseMs;
+            void connect();
+        }
+        if (transport === "poll" && pollTimer !== undefined)
+            schedulePoll(0);
+    };
+    const stop = () => {
+        running = false;
+        epoch += 1;
+        for (const request of inflight)
+            request.abort();
+        inflight.clear();
+        controller?.abort();
+        controller = undefined;
+        connecting = false;
+        endReconnectWait?.();
+        if (pollTimer !== undefined)
+            cancel(pollTimer);
+        if (flushTimer !== undefined)
+            cancel(flushTimer);
+        if (connectTimer !== undefined)
+            cancel(connectTimer);
+        pollTimer = flushTimer = connectTimer = undefined;
+        pending = [];
+    };
+    return {
+        start,
+        stop,
+        addChannel(channel) {
+            const replaced = channels.get(channel.event);
+            if (replaced === channel)
+                return () => detachChannel(channel);
+            if (replaced)
+                detachChannel(replaced);
+            channels.set(channel.event, channel);
+            if (live?.listed.has(channel.event)) {
+                live.open.add(channel);
+                guarded(() => channel.opened());
+            }
+            return () => detachChannel(channel);
+        },
+        reconnectNow,
+        get cursor() {
+            return since();
+        },
+        get transport() {
+            return transport;
+        },
+    };
+}
+//# sourceMappingURL=sync-client.js.map