@shelbyb/daywalker-sdk 0.2.0 → 0.4.0

package/dist/flags/client.d.ts

@@ -1,6 +1,7 @@
 import type { ContextInput, EvaluationReason, FlagValue } from "./engine/index.js";
-import { type Logger } from "./common/index.js";
+import { SDK_VERSION, type Logger } from "./common/index.js";
 export type { ContextInput, EvaluationReason, FlagValue, Logger };
+export { SDK_VERSION };
 export interface FlagState {
     value: FlagValue;
     variation: number | null;
@@ -11,11 +12,17 @@ export interface FlagState {
 }
 export type FlagSet = Record<string, FlagState>;
 export interface ClientOptions {
-    /** Base URL of your DevPulse deployment, e.g. https://flags.example.com */
+    /** Base URL of your DevPulse deployment, e.g. https://flags.example.com (https required except on localhost). */
     baseUrl: string;
     /** Receive changes in real time over Server-Sent Events (default true). */
     streaming?: boolean;
-    /** Initial flag values, e.g. from the Node SDK's allFlagsState() for SSR. */
+    /**
+     * Never touch the network: serve `bootstrap` (or defaults), send no events, open no stream.
+     * identify() only switches the context. Used for server-side rendering; handy in tests.
+     * The client is ready immediately when `bootstrap` is given.
+     */
+    offline?: boolean;
+    /** Initial flag values, e.g. from the Node SDK's allFlagsState().toJSON() for SSR. */
     bootstrap?: FlagSet | Record<string, FlagValue>;
     /** Secure mode hash for the context (HMAC-SHA256 computed on your server). */
     hash?: string;
@@ -58,15 +65,24 @@ export declare class DevPulseClient {
     private rejectReady;
     private initialized;
     private closed;
+    /** Bumped by identify(); responses for an older context are ignored. */
+    private contextSeq;
+    private stale;
+    private detachVisibility;
     private readonly logger;
     private readonly base;
     constructor(clientSideId: string, context: ContextInput, options: ClientOptions);
     private query;
     private start;
+    /** Fetch flags for the current context and apply them unless identify() moved on (or close()) meanwhile. */
+    private loadFlags;
     private fetchFlags;
     private onStreamEvent;
     private replaceAll;
+    private flag;
     private markReady;
+    /** "stale" when the stream drops after loading (flags keep serving), "recovered" once it reconnects. */
+    private setStale;
     private fail;
     private emitChanges;
     private cacheKey;
@@ -77,22 +93,35 @@ export declare class DevPulseClient {
         timeoutMs?: number;
     }): Promise<void>;
     get isInitialized(): boolean;
+    /** True after close(); a closed client never updates again. */
+    get isClosed(): boolean;
     variation<T extends FlagValue>(key: string, defaultValue: T): T;
     variationDetail<T extends FlagValue>(key: string, defaultValue: T): EvaluationDetail<T>;
+    /** @internal Evaluate without recording an analytics event (React hooks record from an effect). */
+    peekVariationDetail<T extends FlagValue>(key: string, defaultValue: T): EvaluationDetail<T>;
+    /** @internal Record the analytics event for an evaluation made with peekVariationDetail(). */
+    recordEvaluation<T extends FlagValue>(key: string, defaultValue: T, detail: EvaluationDetail<T>): void;
     boolVariation(key: string, defaultValue: boolean): boolean;
     stringVariation(key: string, defaultValue: string): string;
     numberVariation(key: string, defaultValue: number): number;
     jsonVariation<T extends FlagValue>(key: string, defaultValue: T): T;
     /** All flag values (doesn't record evaluations). */
     allFlags(): Record<string, FlagValue>;
-    /** Switch to a different context (e.g. after login). Resolves with the new flags. */
+    /**
+     * Switch to a different context (e.g. after login). Resolves with the new flags. When calls
+     * overlap, the last one wins: an earlier call's late response is ignored.
+     */
     identify(context: ContextInput, opts?: {
         hash?: string;
     }): Promise<Record<string, FlagValue>>;
     getContext(): ContextInput;
     /** Record a custom event for metrics and experiments. */
     track(key: string, data?: unknown, metricValue?: number): void;
-    on(event: "ready" | "failed" | "change" | `change:${string}`, fn: Listener): () => void;
+    /**
+     * Events: "ready", "failed" (fatal, e.g. an invalid client-side ID), "change" / "change:<key>",
+     * "stale" (stream lost; the last flags keep serving) and "recovered".
+     */
+    on(event: "ready" | "failed" | "change" | "stale" | "recovered" | `change:${string}`, fn: Listener): () => void;
     off(event: string, fn: Listener): void;
     private emit;
     flush(): Promise<void>;

package/dist/flags/client.js

@@ -1,4 +1,10 @@
-import { EventProcessor, SseClient, encodeContext, noopLogger } from "./common/index.js";
+import { EventProcessor, SDK_VERSION, SseClient, encodeContext, noopLogger } from "./common/index.js";
+import { assertSecureUrl } from "../config.js";
+export { SDK_VERSION };
+/** A flag map without a prototype, so keys like `__proto__` or `toString` never resolve to inherited values. */
+function flagMap(entries = {}) {
+    return Object.assign(Object.create(null), entries);
+}
 function isFlagSet(x) {
     return !!x && typeof x === "object" && Object.values(x).every((v) => v && typeof v === "object" && "value" in v && "version" in v);
 }
@@ -15,7 +21,7 @@ export class DevPulseClient {
     clientSideId;
     context;
     options;
-    flags = {};
+    flags = flagMap();
     listeners = new Map();
     stream = null;
     events = null;
@@ -24,6 +30,10 @@ export class DevPulseClient {
     rejectReady;
     initialized = false;
     closed = false;
+    /** Bumped by identify(); responses for an older context are ignored. */
+    contextSeq = 0;
+    stale = false;
+    detachVisibility = null;
     logger;
     base;
     constructor(clientSideId, context, options) {
@@ -31,6 +41,7 @@ export class DevPulseClient {
         this.context = context;
         this.options = options;
         this.logger = options.logger ?? noopLogger;
+        assertSecureUrl("baseUrl", options.baseUrl);
         this.base = options.baseUrl.replace(/\/$/, "");
         this.ready = new Promise((res, rej) => {
             this.resolveReady = res;
@@ -39,15 +50,17 @@ export class DevPulseClient {
         this.ready.catch(() => undefined);
         if (options.bootstrap) {
             this.flags = isFlagSet(options.bootstrap)
-                ? { ...options.bootstrap }
-                : Object.fromEntries(Object.entries(options.bootstrap).map(([k, v]) => [k, { value: v, variation: null, version: 0 }]));
+                ? flagMap(options.bootstrap)
+                : flagMap(Object.fromEntries(Object.entries(options.bootstrap).map(([k, v]) => [k, { value: v, variation: null, version: 0 }])));
             this.markReady();
         }
         else if (options.cache) {
             const cached = this.readCache();
             if (cached)
-                this.flags = cached;
+                this.flags = flagMap(cached);
         }
+        if (options.offline)
+            return;
         if (options.sendEvents !== false && typeof globalThis.fetch === "function") {
             this.events = new EventProcessor({
                 url: `${this.base}/sdk/v1/events/client/${encodeURIComponent(clientSideId)}`,
@@ -60,10 +73,14 @@ export class DevPulseClient {
             });
             this.events.identify(context);
             const doc = globalThis.document;
-            doc?.addEventListener("visibilitychange", () => {
-                if (doc.visibilityState === "hidden")
-                    void this.events?.flush();
-            });
+            if (doc?.addEventListener) {
+                const onVisibility = () => {
+                    if (doc.visibilityState === "hidden")
+                        void this.events?.flush();
+                };
+                doc.addEventListener("visibilitychange", onVisibility);
+                this.detachVisibility = () => doc.removeEventListener("visibilitychange", onVisibility);
+            }
         }
         void this.start();
     }
@@ -78,10 +95,11 @@ export class DevPulseClient {
     async start() {
         if (this.options.streaming === false) {
             try {
-                this.replaceAll(await this.fetchFlags());
+                await this.loadFlags();
             }
             catch (err) {
-                this.fail(err);
+                if (!this.closed)
+                    this.fail(err);
             }
             return;
         }
@@ -89,7 +107,10 @@ export class DevPulseClient {
             url: () => `${this.base}/sdk/v1/client/${encodeURIComponent(this.clientSideId)}/stream?${this.query()}`,
             fetch: this.options.fetch,
             onEvent: (ev) => this.onStreamEvent(ev.type, ev.data),
-            onOpen: () => this.logger.debug("DevPulse stream connected"),
+            onOpen: () => {
+                this.logger.debug("DevPulse stream connected");
+                this.setStale(false);
+            },
             onError: (err) => {
                 this.logger.warn(`DevPulse stream error: ${err.message}`);
                 if (!err.recoverable) {
@@ -97,13 +118,23 @@ export class DevPulseClient {
                     return false;
                 }
                 // Keep serving flags while reconnecting; fetch once so a first load still succeeds.
+                this.setStale(true, err);
                 if (!this.initialized)
-                    this.fetchFlags().then((f) => this.replaceAll(f), () => undefined);
+                    this.loadFlags().catch(() => undefined);
                 return true;
             },
         });
         this.stream.start();
     }
+    /** Fetch flags for the current context and apply them unless identify() moved on (or close()) meanwhile. */
+    async loadFlags() {
+        const seq = this.contextSeq;
+        const flags = await this.fetchFlags();
+        if (seq !== this.contextSeq || this.closed)
+            return false;
+        this.replaceAll(flags);
+        return true;
+    }
     async fetchFlags() {
         const res = await (this.options.fetch ?? fetch)(`${this.base}/sdk/v1/client/${encodeURIComponent(this.clientSideId)}/flags?${this.query()}`);
         if (!res.ok)
@@ -117,7 +148,7 @@ export class DevPulseClient {
                 this.replaceAll(payload);
             else if (type === "patch") {
                 const { key, ...state } = payload;
-                const prev = this.flags[key];
+                const prev = this.flag(key);
                 if (prev && prev.version > state.version)
                     return;
                 this.flags[key] = state;
@@ -126,7 +157,7 @@ export class DevPulseClient {
             }
             else if (type === "delete") {
                 const { key, version } = payload;
-                const prev = this.flags[key];
+                const prev = this.flag(key);
                 if (!prev || prev.version > version)
                     return;
                 delete this.flags[key];
@@ -141,17 +172,20 @@ export class DevPulseClient {
     replaceAll(next) {
         const changes = {};
         for (const key of new Set([...Object.keys(this.flags), ...Object.keys(next)])) {
-            const a = this.flags[key]?.value;
-            const b = next[key]?.value;
+            const a = this.flag(key)?.value;
+            const b = Object.hasOwn(next, key) ? next[key]?.value : undefined;
             if (JSON.stringify(a) !== JSON.stringify(b))
                 changes[key] = { current: b ?? null, previous: a };
         }
-        this.flags = { ...next };
+        this.flags = flagMap(next);
         this.writeCache();
         this.markReady();
         if (Object.keys(changes).length)
             this.emitChanges(changes);
     }
+    flag(key) {
+        return Object.hasOwn(this.flags, key) ? this.flags[key] : undefined;
+    }
     markReady() {
         if (this.initialized)
             return;
@@ -159,6 +193,16 @@ export class DevPulseClient {
         this.resolveReady();
         this.emit("ready");
     }
+    /** "stale" when the stream drops after loading (flags keep serving), "recovered" once it reconnects. */
+    setStale(stale, err) {
+        if (!this.initialized || this.closed || this.stale === stale)
+            return;
+        this.stale = stale;
+        if (stale)
+            this.emit("stale", err);
+        else
+            this.emit("recovered");
+    }
     fail(err) {
         if (!this.initialized)
             this.rejectReady(err);
@@ -205,11 +249,21 @@ export class DevPulseClient {
     get isInitialized() {
         return this.initialized;
     }
+    /** True after close(); a closed client never updates again. */
+    get isClosed() {
+        return this.closed;
+    }
     variation(key, defaultValue) {
         return this.variationDetail(key, defaultValue).value;
     }
     variationDetail(key, defaultValue) {
-        const f = this.flags[key];
+        const detail = this.peekVariationDetail(key, defaultValue);
+        this.recordEvaluation(key, defaultValue, detail);
+        return detail;
+    }
+    /** @internal Evaluate without recording an analytics event (React hooks record from an effect). */
+    peekVariationDetail(key, defaultValue) {
+        const f = this.flag(key);
         let detail;
         if (!f)
             detail = { value: defaultValue, variationIndex: null, reason: { kind: "ERROR", errorKind: this.initialized ? "FLAG_NOT_FOUND" : "CLIENT_NOT_READY" } };
@@ -220,9 +274,13 @@ export class DevPulseClient {
             detail = { value: defaultValue, variationIndex: null, reason: { kind: "ERROR", errorKind: "WRONG_TYPE" } };
         else
             detail = { value: f.value, variationIndex: f.variation, reason: f.reason ?? null };
-        this.events?.recordEvaluation({ key, context: this.context, value: detail.value, default: defaultValue, variation: detail.variationIndex, version: f?.version, reason: f?.reason, trackEvents: f?.trackEvents });
         return detail;
     }
+    /** @internal Record the analytics event for an evaluation made with peekVariationDetail(). */
+    recordEvaluation(key, defaultValue, detail) {
+        const f = this.flag(key);
+        this.events?.recordEvaluation({ key, context: this.context, value: detail.value, default: defaultValue, variation: detail.variationIndex, version: f?.version, reason: f?.reason, trackEvents: f?.trackEvents });
+    }
     boolVariation(key, defaultValue) {
         return this.variation(key, defaultValue);
     }
@@ -239,14 +297,21 @@ export class DevPulseClient {
     allFlags() {
         return Object.fromEntries(Object.entries(this.flags).map(([k, v]) => [k, v.value]));
     }
-    /** Switch to a different context (e.g. after login). Resolves with the new flags. */
+    /**
+     * Switch to a different context (e.g. after login). Resolves with the new flags. When calls
+     * overlap, the last one wins: an earlier call's late response is ignored.
+     */
     async identify(context, opts = {}) {
+        this.contextSeq++;
         this.context = context;
         if (opts.hash !== undefined)
             this.options.hash = opts.hash;
+        if (this.options.offline || this.closed)
+            return this.allFlags();
         this.events?.identify(context);
-        this.replaceAll(await this.fetchFlags());
+        // Drop the old context's stream now, so none of its events land after the switch.
         this.stream?.restart();
+        await this.loadFlags();
         return this.allFlags();
     }
     getContext() {
@@ -256,6 +321,10 @@ export class DevPulseClient {
     track(key, data, metricValue) {
         this.events?.track(key, this.context, data, metricValue);
     }
+    /**
+     * Events: "ready", "failed" (fatal, e.g. an invalid client-side ID), "change" / "change:<key>",
+     * "stale" (stream lost; the last flags keep serving) and "recovered".
+     */
     on(event, fn) {
         let set = this.listeners.get(event);
         if (!set)
@@ -283,6 +352,8 @@ export class DevPulseClient {
         if (this.closed)
             return;
         this.closed = true;
+        this.detachVisibility?.();
+        this.detachVisibility = null;
         this.stream?.stop();
         await this.events?.close();
         this.listeners.clear();

package/dist/flags/common/events.d.ts

@@ -55,5 +55,14 @@ export declare class EventProcessor {
     private push;
     private drain;
     flush(): Promise<void>;
+    private send;
     close(): Promise<void>;
 }
+/** DevPulse accepts at most this many events per POST (the rest are silently dropped). */
+export declare const MAX_EVENTS_PER_REQUEST = 5000;
+/** Browser event bodies are capped at 512 KB by DevPulse; stay under it with room for brackets. */
+export declare const MAX_REQUEST_BYTES = 500000;
+/** keepalive / sendBeacon bodies must fit in the browser's 64 KiB in-flight budget. */
+export declare const KEEPALIVE_MAX_BYTES = 60000;
+/** Split events into JSON array bodies of at most MAX_EVENTS_PER_REQUEST events and MAX_REQUEST_BYTES bytes. */
+export declare function chunkEvents(events: Record<string, unknown>[], logger?: Logger, maxBytes?: number, maxEvents?: number): string[];

package/dist/flags/common/events.js

@@ -1,5 +1,23 @@
 import { parseContext } from "../engine/index.js";
 export const noopLogger = { debug() { }, info() { }, warn() { }, error() { } };
+/** Delete the value at `tokens` inside `target`, copying (not mutating) nested objects. */
+function removePointer(target, tokens) {
+    const [head, ...rest] = tokens;
+    if (!Object.hasOwn(target, head))
+        return false;
+    if (!rest.length) {
+        delete target[head];
+        return true;
+    }
+    const child = target[head];
+    if (!child || typeof child !== "object" || Array.isArray(child))
+        return false;
+    const copy = { ...child };
+    if (!removePointer(copy, rest))
+        return false;
+    target[head] = copy;
+    return true;
+}
 /**
  * Buffers analytics: per-flag summaries (counts per variation), context
  * index events (deduplicated), full feature events for tracked flags and
@@ -35,6 +53,14 @@ export class EventProcessor {
                 else
                     out[k] = v;
             }
+            // Nested JSON pointers (/address/zip): remove the leaf from a copy of each object on the path.
+            for (const ref of priv) {
+                const tokens = ref.startsWith("/") ? ref.slice(1).split("/").map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~")) : [];
+                if (tokens.length < 2 || ["key", "kind", "anonymous", "_meta"].includes(tokens[0]))
+                    continue;
+                if (removePointer(out, tokens))
+                    redacted.push(ref);
+            }
             if (redacted.length)
                 out.redactedAttributes = redacted;
             return out;
@@ -140,10 +166,18 @@ export class EventProcessor {
         const events = this.drain();
         if (!events.length)
             return;
-        const body = JSON.stringify(events);
-        const nav = globalThis.navigator;
-        if (this.opts.beacon && nav?.sendBeacon && document?.visibilityState === "hidden") {
-            if (nav.sendBeacon(this.opts.url, body))
+        for (const body of chunkEvents(events, this.logger)) {
+            if (this.disabled)
+                return;
+            await this.send(body);
+        }
+    }
+    async send(body) {
+        const bytes = byteLength(body);
+        const g = globalThis;
+        // Beacons and keepalive requests share a 64 KiB in-flight budget in browsers; bigger bodies fail outright.
+        if (this.opts.beacon && g.navigator?.sendBeacon && g.document?.visibilityState === "hidden" && bytes < KEEPALIVE_MAX_BYTES) {
+            if (g.navigator.sendBeacon(this.opts.url, body))
                 return;
         }
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -152,7 +186,7 @@ export class EventProcessor {
                     method: "POST",
                     headers: { "content-type": "application/json", ...this.opts.headers },
                     body,
-                    keepalive: body.length < 60_000,
+                    keepalive: bytes < KEEPALIVE_MAX_BYTES,
                 });
                 if (res.ok)
                     return;
@@ -167,7 +201,8 @@ export class EventProcessor {
                 if (attempt === 1)
                     this.logger.warn("Failed to send events", err);
             }
-            await new Promise((r) => setTimeout(r, 1000));
+            if (attempt === 0)
+                await new Promise((r) => unrefTimer(setTimeout(r, 1000)));
         }
     }
     async close() {
@@ -176,3 +211,39 @@ export class EventProcessor {
         await this.flush();
     }
 }
+/** DevPulse accepts at most this many events per POST (the rest are silently dropped). */
+export const MAX_EVENTS_PER_REQUEST = 5000;
+/** Browser event bodies are capped at 512 KB by DevPulse; stay under it with room for brackets. */
+export const MAX_REQUEST_BYTES = 500_000;
+/** keepalive / sendBeacon bodies must fit in the browser's 64 KiB in-flight budget. */
+export const KEEPALIVE_MAX_BYTES = 60_000;
+const encoder = new TextEncoder();
+const byteLength = (s) => encoder.encode(s).length;
+function unrefTimer(t) {
+    t.unref?.();
+    return t;
+}
+/** Split events into JSON array bodies of at most MAX_EVENTS_PER_REQUEST events and MAX_REQUEST_BYTES bytes. */
+export function chunkEvents(events, logger = noopLogger, maxBytes = MAX_REQUEST_BYTES, maxEvents = MAX_EVENTS_PER_REQUEST) {
+    const bodies = [];
+    let parts = [];
+    let size = 2; // "[" + "]"
+    for (const e of events) {
+        const json = JSON.stringify(e);
+        const n = byteLength(json);
+        if (n + 2 > maxBytes) {
+            logger.warn(`Dropping a ${String(e.kind)} event of ${n} bytes (over the ${maxBytes}-byte request limit)`);
+            continue;
+        }
+        if (parts.length && (parts.length >= maxEvents || size + n + 1 > maxBytes)) {
+            bodies.push(`[${parts.join(",")}]`);
+            parts = [];
+            size = 2;
+        }
+        size += n + (parts.length ? 1 : 0);
+        parts.push(json);
+    }
+    if (parts.length)
+        bodies.push(`[${parts.join(",")}]`);
+    return bodies;
+}

package/dist/flags/common/index.d.ts

@@ -1,5 +1,5 @@
-export { SseParser, SseClient, SseError, backoffDelay, type SseEvent, type SseClientOptions } from "./sse.js";
-export { EventProcessor, noopLogger, type EventProcessorOptions, type Logger } from "./events.js";
+export { SseParser, SseClient, SseError, backoffDelay, DEFAULT_MAX_EVENT_SIZE, MIN_SERVER_RETRY_MS, type SseEvent, type SseClientOptions } from "./sse.js";
+export { EventProcessor, noopLogger, chunkEvents, MAX_EVENTS_PER_REQUEST, MAX_REQUEST_BYTES, KEEPALIVE_MAX_BYTES, type EventProcessorOptions, type Logger } from "./events.js";
 /** Encode a context for URLs (base64url JSON), matching the DevPulse SDK endpoints. */
 export declare function encodeContext(context: unknown): string;
-export declare const SDK_VERSION = "0.1.0";
+export { SDK_VERSION } from "./version.js";

package/dist/flags/common/index.js

@@ -1,5 +1,5 @@
-export { SseParser, SseClient, SseError, backoffDelay } from "./sse.js";
-export { EventProcessor, noopLogger } from "./events.js";
+export { SseParser, SseClient, SseError, backoffDelay, DEFAULT_MAX_EVENT_SIZE, MIN_SERVER_RETRY_MS } from "./sse.js";
+export { EventProcessor, noopLogger, chunkEvents, MAX_EVENTS_PER_REQUEST, MAX_REQUEST_BYTES, KEEPALIVE_MAX_BYTES } from "./events.js";
 /** Encode a context for URLs (base64url JSON), matching the DevPulse SDK endpoints. */
 export function encodeContext(context) {
     const json = JSON.stringify(context);
@@ -9,4 +9,4 @@ export function encodeContext(context) {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-export const SDK_VERSION = "0.1.0";
+export { SDK_VERSION } from "./version.js";

package/dist/flags/common/sse.d.ts

@@ -9,16 +9,25 @@ export interface SseEvent {
     data: string;
     lastEventId: string;
 }
-/** Incremental parser: feed it chunks of text, get dispatched events back. */
+/** Default cap on one event (its pending line plus its `data` lines), in UTF-16 code units. */
+export declare const DEFAULT_MAX_EVENT_SIZE: number;
+/**
+ * Incremental parser: feed it chunks of text, get dispatched events back. Use one parser per
+ * connection: a dropped connection can leave a half-received event behind.
+ */
 export declare class SseParser {
+    private readonly maxEventSize;
     private buffer;
     private data;
+    private dataSize;
     private eventType;
     private sawFirstChunk;
     /** The previous chunk ended in CR, so an LF starting this chunk completes a CRLF. */
     private pendingCR;
     lastEventId: string;
     retry: number | null;
+    /** @param maxEventSize feed() throws an SseError once an event grows past this (bounded memory). */
+    constructor(maxEventSize?: number);
     feed(chunk: string): SseEvent[];
     private line;
 }
@@ -35,7 +44,16 @@ export interface SseClientOptions {
     maxRetryMs?: number;
     /** Reconnect if nothing (not even a heartbeat) arrives for this long. */
     readTimeoutMs?: number;
+    /** Largest single event accepted (default 1 MB); a bigger one drops the connection. */
+    maxEventSize?: number;
+    /**
+     * Send only CORS-safelisted request headers: no `cache-control` or `last-event-id`, which
+     * would trigger a preflight that DevPulse doesn't allow. Default: true in browsers and workers.
+     */
+    browser?: boolean;
 }
+/** Lower bound for a server-sent `retry:` hint, so `retry: 0` can't cause a reconnect storm. */
+export declare const MIN_SERVER_RETRY_MS = 1000;
 export declare class SseError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
@@ -49,14 +67,17 @@ export declare class SseClient {
     private controller;
     private stopped;
     private attempt;
-    private parser;
+    /** Carried across connections; the parser itself is fresh per connection. */
+    private lastEventId;
+    private retry;
     private timer;
     private watchdog;
     private reader;
     constructor(opts: SseClientOptions);
     start(): void;
     stop(): void;
-    /** Drop the current connection and reconnect immediately (e.g. after identify). */
+    /** Drop the current connection (or pending reconnect) and reconnect immediately (e.g. after identify). */
     restart(): void;
+    private clearTimer;
     private connect;
 }