@shelbyb/daywalker-sdk 0.3.0 → 0.4.1

package/dist/flags/common/sse.js

@@ -1,13 +1,24 @@
-/** 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 const DEFAULT_MAX_EVENT_SIZE = 1024 * 1024;
+/**
+ * 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 class SseParser {
+    maxEventSize;
     buffer = "";
     data = [];
+    dataSize = 0;
     eventType = "";
     sawFirstChunk = false;
     /** The previous chunk ended in CR, so an LF starting this chunk completes a CRLF. */
     pendingCR = false;
     lastEventId = "";
     retry = null;
+    /** @param maxEventSize feed() throws an SseError once an event grows past this (bounded memory). */
+    constructor(maxEventSize = DEFAULT_MAX_EVENT_SIZE) {
+        this.maxEventSize = maxEventSize;
+    }
     feed(chunk) {
         if (!this.sawFirstChunk) {
             this.sawFirstChunk = true;
@@ -39,6 +50,12 @@ export class SseParser {
                 out.push(ev);
         }
         this.buffer = this.buffer.slice(start);
+        if (this.buffer.length + this.dataSize > this.maxEventSize) {
+            this.buffer = "";
+            this.data = [];
+            this.dataSize = 0;
+            throw new SseError(`Stream event exceeded ${this.maxEventSize} characters`);
+        }
         return out;
     }
     line(line) {
@@ -49,6 +66,7 @@ export class SseParser {
             }
             const ev = { type: this.eventType || "message", data: this.data.join("\n"), lastEventId: this.lastEventId };
             this.data = [];
+            this.dataSize = 0;
             this.eventType = "";
             return ev;
         }
@@ -65,6 +83,12 @@ export class SseParser {
                 break;
             case "data":
                 this.data.push(value);
+                this.dataSize += value.length + 1;
+                if (this.dataSize > this.maxEventSize) {
+                    this.data = [];
+                    this.dataSize = 0;
+                    throw new SseError(`Stream event exceeded ${this.maxEventSize} characters`);
+                }
                 break;
             case "id":
                 if (!value.includes("\0"))
@@ -78,6 +102,18 @@ export class SseParser {
         return null;
     }
 }
+/** Lower bound for a server-sent `retry:` hint, so `retry: 0` can't cause a reconnect storm. */
+export const MIN_SERVER_RETRY_MS = 1000;
+/** Browsers and web workers enforce CORS on fetch; Node, Deno (no document), Bun and React Native don't. */
+function isBrowserLike() {
+    const g = globalThis;
+    return typeof g.document !== "undefined" || typeof g.WorkerGlobalScope !== "undefined";
+}
+/** Let a timer not keep a Node/Deno/Bun process alive (no-op in browsers). */
+function unref(t) {
+    t.unref?.();
+    return t;
+}
 export class SseError extends Error {
     status;
     constructor(message, status) {
@@ -99,7 +135,9 @@ export class SseClient {
     controller = null;
     stopped = false;
     attempt = 0;
-    parser = new SseParser();
+    /** Carried across connections; the parser itself is fresh per connection. */
+    lastEventId = "";
+    retry = null;
     timer = null;
     watchdog = null;
     reader = null;
@@ -112,44 +150,66 @@ export class SseClient {
     }
     stop() {
         this.stopped = true;
-        if (this.timer)
-            clearTimeout(this.timer);
+        this.clearTimer();
         // Don't leave the read-timeout timer or a pending read keeping the process alive.
         if (this.watchdog)
             clearTimeout(this.watchdog);
+        this.watchdog = null;
         this.controller?.abort();
         void this.reader?.cancel().catch(() => { });
     }
-    /** 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() {
+        this.clearTimer();
         this.controller?.abort();
         this.attempt = 0;
-        this.parser = new SseParser();
+        this.lastEventId = ""; // the old stream's ids mean nothing to a new context
         if (!this.stopped)
             void this.connect();
     }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
     async connect() {
         if (this.stopped)
             return;
+        this.clearTimer();
+        this.controller?.abort(); // never two live connections
         const controller = new AbortController();
         this.controller = controller;
+        const parser = new SseParser(this.opts.maxEventSize);
+        parser.lastEventId = this.lastEventId;
+        parser.retry = this.retry;
         const f = this.opts.fetch ?? fetch;
         const resetWatchdog = () => {
             if (this.watchdog)
                 clearTimeout(this.watchdog);
-            this.watchdog = setTimeout(() => controller.abort(), this.opts.readTimeoutMs ?? 5 * 60_000);
+            this.watchdog = unref(setTimeout(() => controller.abort(), this.opts.readTimeoutMs ?? 5 * 60_000));
         };
         const connectedAt = Date.now();
         try {
             const url = typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
             const headers = typeof this.opts.headers === "function" ? this.opts.headers() : (this.opts.headers ?? {});
+            const browser = this.opts.browser ?? isBrowserLike();
             resetWatchdog();
             const res = await f(url, {
-                headers: { accept: "text/event-stream", "cache-control": "no-cache", ...(this.parser.lastEventId ? { "last-event-id": this.parser.lastEventId } : {}), ...headers },
+                headers: {
+                    accept: "text/event-stream",
+                    ...(browser ? {} : { "cache-control": "no-cache", ...(this.lastEventId ? { "last-event-id": this.lastEventId } : {}) }),
+                    ...headers,
+                },
+                // Browsers: keep the HTTP cache out of it without a non-safelisted request header.
+                ...(browser ? { cache: "no-store" } : {}),
                 signal: controller.signal,
             });
             if (!res.ok || !res.body)
                 throw new SseError(`Stream request failed with ${res.status}`, res.status);
+            if (this.controller !== controller) {
+                void res.body.cancel().catch(() => { });
+                return;
+            }
             this.opts.onOpen?.();
             const reader = res.body.getReader();
             this.reader = reader;
@@ -159,25 +219,35 @@ export class SseClient {
                 if (done)
                     break;
                 resetWatchdog();
-                for (const ev of this.parser.feed(decoder.decode(value, { stream: true })))
+                const events = parser.feed(decoder.decode(value, { stream: true }));
+                this.lastEventId = parser.lastEventId;
+                this.retry = parser.retry;
+                for (const ev of events) {
+                    if (this.controller !== controller)
+                        return; // superseded by restart()/stop() from a handler
                     this.opts.onEvent(ev);
+                }
             }
             throw new SseError("Stream closed by server");
         }
         catch (err) {
-            if (this.watchdog)
+            if (this.controller === controller && this.watchdog)
                 clearTimeout(this.watchdog);
-            if (this.stopped || (controller.signal.aborted && this.controller !== controller))
+            if (this.stopped || this.controller !== controller)
                 return;
+            controller.abort(); // release the response body
             const e = err instanceof SseError ? err : new SseError(err?.message ?? "Stream error");
             const keepGoing = this.opts.onError?.(e);
-            if (keepGoing === false || !e.recoverable)
+            if (keepGoing === false || !e.recoverable || this.stopped || this.controller !== controller)
                 return;
             if (Date.now() - connectedAt > 60_000)
                 this.attempt = 0; // was healthy for a while
-            const base = this.parser.retry ?? this.opts.initialRetryMs ?? 1000;
-            const delay = backoffDelay(this.attempt++, base, this.opts.maxRetryMs ?? 30_000);
-            this.timer = setTimeout(() => void this.connect(), delay);
+            const fromServer = this.retry !== null;
+            const base = fromServer ? Math.max(MIN_SERVER_RETRY_MS, this.retry) : (this.opts.initialRetryMs ?? 1000);
+            let delay = backoffDelay(this.attempt++, base, this.opts.maxRetryMs ?? 30_000);
+            if (fromServer)
+                delay = Math.max(MIN_SERVER_RETRY_MS, delay);
+            this.timer = unref(setTimeout(() => void this.connect(), delay));
         }
     }
 }

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

@@ -0,0 +1,2 @@
+/** The package version, sent in user agents and analytics `$lib_version`. Keep in sync with package.json. */
+export declare const SDK_VERSION = "0.4.0";

package/dist/flags/common/version.js

@@ -0,0 +1,2 @@
+/** The package version, sent in user agents and analytics `$lib_version`. Keep in sync with package.json. */
+export const SDK_VERSION = "0.4.0";

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

@@ -2,6 +2,6 @@ export * from "./types.js";
 export { parseContext, getAttribute, ContextError, type Context, type ContextInput, type SingleContext } from "./context.js";
 export { Evaluator, MemoryStore, evaluateFlag, errorDetail, type EvaluationResult, type PrerequisiteEvaluation } from "./evaluate.js";
 export { bucketContext, variationForRollout } from "./bucket.js";
-export { applyOperator, parseTime } from "./operators.js";
+export { applyOperator, parseTime, isSafePattern, compilePattern, MAX_PATTERN_LENGTH, MAX_MATCH_INPUT, MAX_MATCH_PATTERN_LENGTH, MAX_MATCH_INPUT_LENGTH, type SafeRegex } from "./operators.js";
 export { parseSemVer, compareSemVer } from "./semver.js";
 export { sha1Hex } from "./sha1.js";

package/dist/flags/engine/index.js

@@ -2,6 +2,6 @@ export * from "./types.js";
 export { parseContext, getAttribute, ContextError } from "./context.js";
 export { Evaluator, MemoryStore, evaluateFlag, errorDetail } from "./evaluate.js";
 export { bucketContext, variationForRollout } from "./bucket.js";
-export { applyOperator, parseTime } from "./operators.js";
+export { applyOperator, parseTime, isSafePattern, compilePattern, MAX_PATTERN_LENGTH, MAX_MATCH_INPUT, MAX_MATCH_PATTERN_LENGTH, MAX_MATCH_INPUT_LENGTH } from "./operators.js";
 export { parseSemVer, compareSemVer } from "./semver.js";
 export { sha1Hex } from "./sha1.js";

package/dist/flags/engine/operators.d.ts

@@ -1,10 +1,27 @@
 import type { FlagValue, Operator } from "./types.js";
-/** `matches` limits: longer inputs or patterns never match. */
+/** `matches` limits: longer inputs or patterns never match (same limits as the DevPulse server). */
 export declare const MAX_MATCH_INPUT_LENGTH = 1024;
 export declare const MAX_MATCH_PATTERN_LENGTH = 500;
+/** Server-parity aliases (`@devpulse/flag-engine` names). */
+export declare const MAX_PATTERN_LENGTH = 500;
+export declare const MAX_MATCH_INPUT = 1024;
+/** A compiled user pattern: only `test()` is exposed. */
+export type SafeRegex = {
+    test(input: string): boolean;
+};
 /**
- * Conservative ReDoS heuristic: a group that contains a quantifier or alternation and is itself
- * repeated (`(a+)+`, `(a*)*`, `(a|aa)+`, `(?:x+y)*`, `(a+){2,}`). Character classes and escapes are skipped.
+ * Compile a user-supplied pattern with RE2 (linear-time matching, no backtracking), so no
+ * pattern can stall the process however it's written (ReDoS), and every SDK agrees with the
+ * DevPulse server on what matches. RE2 has no backreferences or lookaround; patterns using
+ * them don't compile and return null (never match).
+ */
+export declare function compilePattern(pattern: string): SafeRegex | null;
+/** Whether a `matches` pattern is accepted: bounded length and valid RE2 syntax. */
+export declare function isSafePattern(pattern: string): boolean;
+/**
+ * @deprecated No longer used: `matches` runs on RE2, which is immune to ReDoS. Kept for
+ * backwards compatibility. Conservative heuristic for a group that contains a quantifier or
+ * alternation and is itself repeated (`(a+)+`, `(a|aa)+`, `(a+){2,}`).
  */
 export declare function hasNestedQuantifier(pattern: string): boolean;
 /** RFC 3339 timestamp or Unix milliseconds → epoch ms. */

package/dist/flags/engine/operators.js

@@ -1,12 +1,43 @@
+import { RE2JS } from "re2js";
 import { compareSemVer, parseSemVer } from "./semver.js";
-const regexCache = new Map();
-/** `matches` limits: longer inputs or patterns never match. */
+/** `matches` limits: longer inputs or patterns never match (same limits as the DevPulse server). */
 export const MAX_MATCH_INPUT_LENGTH = 1024;
 export const MAX_MATCH_PATTERN_LENGTH = 500;
-let warnedUnsafePattern = false;
+/** Server-parity aliases (`@devpulse/flag-engine` names). */
+export const MAX_PATTERN_LENGTH = MAX_MATCH_PATTERN_LENGTH;
+export const MAX_MATCH_INPUT = MAX_MATCH_INPUT_LENGTH;
+const regexCache = new Map();
+/**
+ * Compile a user-supplied pattern with RE2 (linear-time matching, no backtracking), so no
+ * pattern can stall the process however it's written (ReDoS), and every SDK agrees with the
+ * DevPulse server on what matches. RE2 has no backreferences or lookaround; patterns using
+ * them don't compile and return null (never match).
+ */
+export function compilePattern(pattern) {
+    if (!regexCache.has(pattern)) {
+        let re = null;
+        if (pattern.length <= MAX_MATCH_PATTERN_LENGTH) {
+            try {
+                re = RE2JS.compile(pattern);
+            }
+            catch {
+                re = null;
+            }
+        }
+        if (regexCache.size > 1000)
+            regexCache.clear();
+        regexCache.set(pattern, re);
+    }
+    return regexCache.get(pattern);
+}
+/** Whether a `matches` pattern is accepted: bounded length and valid RE2 syntax. */
+export function isSafePattern(pattern) {
+    return compilePattern(pattern) !== null;
+}
 /**
- * Conservative ReDoS heuristic: a group that contains a quantifier or alternation and is itself
- * repeated (`(a+)+`, `(a*)*`, `(a|aa)+`, `(?:x+y)*`, `(a+){2,}`). Character classes and escapes are skipped.
+ * @deprecated No longer used: `matches` runs on RE2, which is immune to ReDoS. Kept for
+ * backwards compatibility. Conservative heuristic for a group that contains a quantifier or
+ * alternation and is itself repeated (`(a+)+`, `(a|aa)+`, `(a+){2,}`).
  */
 export function hasNestedQuantifier(pattern) {
     const stack = []; // per open group: contains a quantifier / alternation
@@ -40,29 +71,6 @@ export function hasNestedQuantifier(pattern) {
     }
     return false;
 }
-function regex(pattern) {
-    if (!regexCache.has(pattern)) {
-        let re = null;
-        if (pattern.length > MAX_MATCH_PATTERN_LENGTH || hasNestedQuantifier(pattern)) {
-            if (!warnedUnsafePattern) {
-                warnedUnsafePattern = true;
-                console.warn("DevPulse: a `matches` pattern was too long or had nested quantifiers and is treated as no match");
-            }
-        }
-        else {
-            try {
-                re = new RegExp(pattern);
-            }
-            catch {
-                re = null;
-            }
-        }
-        if (regexCache.size > 1000)
-            regexCache.clear();
-        regexCache.set(pattern, re);
-    }
-    return regexCache.get(pattern);
-}
 /** RFC 3339 timestamp or Unix milliseconds → epoch ms. */
 export function parseTime(v) {
     if (typeof v === "number" && Number.isFinite(v))
@@ -97,11 +105,9 @@ export function applyOperator(op, actual, expected) {
         case "contains":
             return typeof actual === "string" && typeof expected === "string" && actual.includes(expected);
         case "matches": {
-            if (typeof actual !== "string" || typeof expected !== "string")
-                return false;
-            if (actual.length > MAX_MATCH_INPUT_LENGTH)
+            if (typeof actual !== "string" || typeof expected !== "string" || actual.length > MAX_MATCH_INPUT_LENGTH)
                 return false;
-            return regex(expected)?.test(actual) ?? false;
+            return compilePattern(expected)?.test(actual) ?? false;
         }
         case "lessThan":
         case "lessThanOrEqual":

package/dist/flags/node.d.ts

@@ -1,7 +1,9 @@
 import { EventEmitter } from "node:events";
 import { type ContextInput, type EvaluationDetail, type FlagConfig, type FlagValue, type SegmentConfig } from "./engine/index.js";
-import { type Logger } from "./common/index.js";
-export type { ContextInput, EvaluationDetail, FlagValue, Logger };
+import { SDK_VERSION, type Logger } from "./common/index.js";
+import type { FlagSet } from "./client.js";
+export type { ContextInput, EvaluationDetail, FlagSet, FlagValue, Logger };
+export { SDK_VERSION };
 export interface NodeClientOptions {
     /** Base URL of your DevPulse deployment (https required except on localhost). */
     baseUrl: string;
@@ -26,17 +28,24 @@ export interface NodeClientOptions {
 export interface AllFlagsState {
     valid: boolean;
     values: Record<string, FlagValue>;
-    /** Pass to the browser SDK's `bootstrap` option for flicker-free SSR. */
-    toJSON(): Record<string, {
-        value: FlagValue;
-        variation: number | null;
-        version: number;
-        reason?: unknown;
-    }>;
+    /** Pass to the browser SDK's `bootstrap` option for flicker-free SSR (same shape as the client endpoint). */
+    toJSON(): FlagSet;
+}
+export interface AllFlagsStateOptions {
+    /**
+     * Only flags marked "available to client-side SDKs" (default true), so the result is safe to
+     * embed in HTML. Pass false to include every flag, e.g. for server-side use only.
+     */
+    clientSideOnly?: boolean;
+    /** Include evaluation reasons (always included for experiments). */
+    withReasons?: boolean;
 }
 /**
  * Server-side client. One instance per process and SDK key.
  *
+ * Events: "ready", "failed" (fatal, e.g. an invalid SDK key), "update" / "update:<key>",
+ * "stale" (connection lost; the last data keeps serving) and "recovered".
+ *
  *   const client = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl });
  *   await client.waitForInitialization({ timeoutMs: 5000 });
  *   const enabled = await client.variation("new-checkout", { key: user.id, email: user.email }, false);
@@ -54,6 +63,7 @@ export declare class DevPulseNodeClient extends EventEmitter {
     private resolveReady;
     private rejectReady;
     private streamFailures;
+    private stale;
     private readonly logger;
     private readonly base;
     constructor(sdkKey: string, options: NodeClientOptions);
@@ -65,6 +75,8 @@ export declare class DevPulseNodeClient extends EventEmitter {
     private applyPut;
     private emitUpdate;
     private markReady;
+    /** "stale" when updates stop arriving (flags keep serving the last data), "recovered" when they resume. */
+    private setStale;
     private fail;
     waitForInitialization(opts?: {
         timeoutMs?: number;
@@ -80,13 +92,13 @@ export declare class DevPulseNodeClient extends EventEmitter {
     numberVariation(key: string, context: ContextInput, defaultValue: number): Promise<number>;
     jsonVariation<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): Promise<T>;
     /**
-     * Evaluate every flag for a context, e.g. to bootstrap a browser client
+     * Evaluate every client-side flag for a context, e.g. to bootstrap a browser client
      * during server rendering. Doesn't record analytics.
+     *
+     *   const state = await client.allFlagsState(context);
+     *   createClient(id, context, { baseUrl, bootstrap: state.toJSON() });
      */
-    allFlagsState(context: ContextInput, opts?: {
-        clientSideOnly?: boolean;
-        withReasons?: boolean;
-    }): Promise<AllFlagsState>;
+    allFlagsState(context: ContextInput, opts?: AllFlagsStateOptions): Promise<AllFlagsState>;
     /** Secure mode hash for a context, for the browser SDK's `hash` option. */
     secureModeHash(context: ContextInput): string;
     track(key: string, context: ContextInput, data?: unknown, metricValue?: number): void;

package/dist/flags/node.js

@@ -1,11 +1,15 @@
 import { createHmac } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { Evaluator, MemoryStore, evaluateFlag, parseContext } from "./engine/index.js";
-import { EventProcessor, SseClient, noopLogger } from "./common/index.js";
+import { EventProcessor, SDK_VERSION, SseClient, noopLogger } from "./common/index.js";
 import { assertSecureUrl } from "../config.js";
+export { SDK_VERSION };
 /**
  * Server-side client. One instance per process and SDK key.
  *
+ * Events: "ready", "failed" (fatal, e.g. an invalid SDK key), "update" / "update:<key>",
+ * "stale" (connection lost; the last data keeps serving) and "recovered".
+ *
  *   const client = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl });
  *   await client.waitForInitialization({ timeoutMs: 5000 });
  *   const enabled = await client.variation("new-checkout", { key: user.id, email: user.email }, false);
@@ -23,6 +27,7 @@ export class DevPulseNodeClient extends EventEmitter {
     resolveReady;
     rejectReady;
     streamFailures = 0;
+    stale = false;
     logger;
     base;
     constructor(sdkKey, options) {
@@ -61,16 +66,20 @@ export class DevPulseNodeClient extends EventEmitter {
             this.startStreaming();
     }
     headers() {
-        return { authorization: this.sdkKey, "user-agent": "DevPulseNode/0.1.0" };
+        return { authorization: this.sdkKey, "user-agent": `DevPulseNode/${SDK_VERSION}` };
     }
     startStreaming() {
         this.stream = new SseClient({
             url: `${this.base}/sdk/v1/server/stream`,
             headers: () => this.headers(),
             fetch: this.options.fetch,
+            browser: false,
+            // Full rulesets (segments with big target lists) can be large.
+            maxEventSize: 64 * 1024 * 1024,
             onOpen: () => {
                 this.streamFailures = 0;
                 this.stopPolling();
+                this.setStale(false);
             },
             onEvent: (ev) => this.onStreamEvent(ev.type, ev.data),
             onError: (err) => {
@@ -79,6 +88,9 @@ export class DevPulseNodeClient extends EventEmitter {
                     this.fail(new Error("Invalid SDK key"));
                     return false;
                 }
+                // While polling, the poll result decides whether data is stale.
+                if (!this.poller)
+                    this.setStale(true, err);
                 // After repeated failures, poll so data stays fresh while we keep retrying the stream.
                 if (++this.streamFailures >= 3)
                     this.startPolling();
@@ -94,17 +106,21 @@ export class DevPulseNodeClient extends EventEmitter {
         const poll = async () => {
             try {
                 const res = await (this.options.fetch ?? fetch)(`${this.base}/sdk/v1/server/flags`, { headers: { ...this.headers(), ...(this.etag ? { "if-none-match": this.etag } : {}) } });
-                if (res.status === 304)
+                if (res.status === 304) {
+                    this.setStale(false);
                     return this.markReady();
+                }
                 if (res.status === 401 || res.status === 403)
                     return this.fail(new Error("Invalid SDK key"));
                 if (!res.ok)
                     throw new Error(`Poll failed with ${res.status}`);
                 this.etag = res.headers.get("etag");
                 this.applyPut((await res.json()));
+                this.setStale(false);
             }
             catch (err) {
                 this.logger.warn("DevPulse poll failed", err);
+                this.setStale(true, err);
             }
         };
         this.poller = setInterval(poll, interval);
@@ -163,6 +179,16 @@ export class DevPulseNodeClient extends EventEmitter {
         this.resolveReady();
         this.emit("ready");
     }
+    /** "stale" when updates stop arriving (flags keep serving the last data), "recovered" when they resume. */
+    setStale(stale, err) {
+        if (!this.initialized || 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);
@@ -173,7 +199,12 @@ export class DevPulseNodeClient extends EventEmitter {
         const ready = this.ready.then(() => this);
         if (!opts.timeoutMs)
             return ready;
-        return Promise.race([ready, new Promise((_, rej) => setTimeout(() => rej(new Error("DevPulse initialization timed out")), opts.timeoutMs).unref?.())]);
+        let timer;
+        const timeout = new Promise((_, rej) => {
+            // Not unref'd: someone is awaiting it. Cleared as soon as either side settles.
+            timer = setTimeout(() => rej(new Error("DevPulse initialization timed out")), opts.timeoutMs);
+        });
+        return Promise.race([ready, timeout]).finally(() => clearTimeout(timer));
     }
     get isInitialized() {
         return this.initialized;
@@ -217,10 +248,14 @@ export class DevPulseNodeClient extends EventEmitter {
         return this.variation(key, context, defaultValue);
     }
     /**
-     * Evaluate every flag for a context, e.g. to bootstrap a browser client
+     * Evaluate every client-side flag for a context, e.g. to bootstrap a browser client
      * during server rendering. Doesn't record analytics.
+     *
+     *   const state = await client.allFlagsState(context);
+     *   createClient(id, context, { baseUrl, bootstrap: state.toJSON() });
      */
     async allFlagsState(context, opts = {}) {
+        const clientSideOnly = opts.clientSideOnly ?? true;
         let ctx;
         try {
             ctx = parseContext(context);
@@ -231,10 +266,19 @@ export class DevPulseNodeClient extends EventEmitter {
         const evaluator = new Evaluator(this.store);
         const state = {};
         for (const f of this.store.flags.values()) {
-            if (opts.clientSideOnly && !f.clientSide)
+            if (f.deleted || (clientSideOnly && !f.clientSide))
                 continue;
             const { detail } = evaluator.evaluate(f, ctx);
-            state[f.key] = { value: detail.value, variation: detail.variationIndex, version: f.version, ...(opts.withReasons ? { reason: detail.reason } : {}) };
+            // Same shape as the DevPulse client endpoint, so client-side analytics and experiments keep working.
+            const inExperiment = "inExperiment" in detail.reason && !!detail.reason.inExperiment;
+            state[f.key] = {
+                value: detail.value,
+                variation: detail.variationIndex,
+                version: f.version,
+                ...(opts.withReasons || inExperiment ? { reason: detail.reason } : {}),
+                ...(f.trackEvents || inExperiment ? { trackEvents: true } : {}),
+                ...(inExperiment ? { trackReason: true } : {}),
+            };
         }
         return { valid: this.initialized, values: Object.fromEntries(Object.entries(state).map(([k, v]) => [k, v.value])), toJSON: () => state };
     }

package/dist/flags/react.d.ts

@@ -10,9 +10,11 @@ export interface DevPulseProviderProps {
     children: ReactNode;
 }
 /**
- * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming)
- * no network connection is opened; flags come from `options.bootstrap`, so the
- * first client render matches the server HTML. Changing `context` calls identify().
+ * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming) and during the
+ * first client render, an offline client serves `options.bootstrap` and makes no requests, so
+ * hydration matches the server HTML. The live client is created (and closed) in an effect,
+ * which keeps StrictMode's simulated unmount from leaving a closed client behind. Changing
+ * `context` calls identify().
  */
 export declare function DevPulseProvider({ clientSideId, context, options, client: external, children }: DevPulseProviderProps): import("react").JSX.Element;
 export declare function useDevPulseClient(): DevPulseClient;
@@ -23,5 +25,5 @@ export declare function useFlagDetail<T extends FlagValue>(key: string, defaultV
 export declare function useFlags(): Record<string, FlagValue>;
 /** True once flags have loaded (always true when bootstrapped). */
 export declare function useFlagsReady(): boolean;
-/** Track a custom event for metrics and experiments. */
+/** Track a custom event for metrics and experiments. Stable across renders (safe in effect deps). */
 export declare function useTrack(): (key: string, data?: unknown, metricValue?: number) => void;