@shelbyb/daywalker-sdk 0.2.0 → 0.4.0

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/context.js

@@ -11,7 +11,8 @@ function parseSingle(kind, raw) {
         throw new ContextError(`Context "${kind}" needs a non-empty string key`);
     const meta = (obj._meta ?? {});
     const privateAttributes = Array.isArray(meta.privateAttributes) ? meta.privateAttributes.filter((a) => typeof a === "string") : [];
-    const attributes = {};
+    // No prototype: `constructor`, `toString`, `__proto__` resolve only if the context sets them.
+    const attributes = Object.create(null);
     for (const [k, v] of Object.entries(obj))
         if (k !== "_meta" && k !== "kind")
             attributes[k] = v;
@@ -53,7 +54,7 @@ export function getAttribute(ctx, ref) {
     if (ref === "key")
         return ctx.key;
     if (!ref.startsWith("/"))
-        return ctx.attributes[ref];
+        return Object.hasOwn(ctx.attributes, ref) ? ctx.attributes[ref] : undefined;
     const tokens = ref
         .slice(1)
         .split("/")
@@ -70,7 +71,7 @@ export function getAttribute(ctx, ref) {
             cur = cur[Number(t)];
         }
         else {
-            cur = cur[t];
+            cur = Object.hasOwn(cur, t) ? cur[t] : undefined;
         }
     }
     return cur;

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,4 +1,29 @@
 import type { FlagValue, Operator } from "./types.js";
+/** `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;
+};
+/**
+ * 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. */
 export declare function parseTime(v: unknown): number | null;
 /** Compare one context value with one clause value. Type mismatches never match. */

package/dist/flags/engine/operators.js

@@ -1,13 +1,28 @@
+import { RE2JS } from "re2js";
 import { compareSemVer, parseSemVer } from "./semver.js";
+/** `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;
+/** 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();
-function regex(pattern) {
+/**
+ * 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;
-        try {
-            re = new RegExp(pattern);
-        }
-        catch {
-            re = null;
+        if (pattern.length <= MAX_MATCH_PATTERN_LENGTH) {
+            try {
+                re = RE2JS.compile(pattern);
+            }
+            catch {
+                re = null;
+            }
         }
         if (regexCache.size > 1000)
             regexCache.clear();
@@ -15,6 +30,47 @@ function regex(pattern) {
     }
     return regexCache.get(pattern);
 }
+/** Whether a `matches` pattern is accepted: bounded length and valid RE2 syntax. */
+export function isSafePattern(pattern) {
+    return compilePattern(pattern) !== null;
+}
+/**
+ * @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
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\") {
+            i++;
+        }
+        else if (ch === "[") {
+            for (i++; i < pattern.length && pattern[i] !== "]"; i++)
+                if (pattern[i] === "\\")
+                    i++;
+        }
+        else if (ch === "(") {
+            stack.push(false);
+            if (pattern[i + 1] === "?")
+                i++; // group modifier, not a quantifier
+        }
+        else if (ch === ")") {
+            const risky = stack.pop() ?? false;
+            const next = pattern[i + 1];
+            const repeated = next === "*" || next === "+" || next === "{";
+            if (risky && repeated)
+                return true;
+            if ((risky || repeated) && stack.length)
+                stack[stack.length - 1] = true;
+        }
+        else if ((ch === "*" || ch === "+" || ch === "?" || ch === "{" || ch === "|") && stack.length) {
+            stack[stack.length - 1] = true;
+        }
+    }
+    return false;
+}
 /** RFC 3339 timestamp or Unix milliseconds → epoch ms. */
 export function parseTime(v) {
     if (typeof v === "number" && Number.isFinite(v))
@@ -49,9 +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")
+            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,9 +1,11 @@
 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. */
+    /** Base URL of your DevPulse deployment (https required except on localhost). */
     baseUrl: string;
     /** Real-time updates over SSE (default). Set false to poll instead. */
     stream?: boolean;
@@ -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,10 +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);
@@ -22,6 +27,7 @@ export class DevPulseNodeClient extends EventEmitter {
     resolveReady;
     rejectReady;
     streamFailures = 0;
+    stale = false;
     logger;
     base;
     constructor(sdkKey, options) {
@@ -41,6 +47,8 @@ export class DevPulseNodeClient extends EventEmitter {
             this.markReady();
             return;
         }
+        // Checked once the SDK key will actually be sent (offline / fixture clients make no requests).
+        assertSecureUrl("baseUrl", options.baseUrl);
         if (options.sendEvents !== false) {
             this.events = new EventProcessor({
                 url: `${this.base}/sdk/v1/events`,
@@ -58,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) => {
@@ -76,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();
@@ -91,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);
@@ -160,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);
@@ -170,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;
@@ -214,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);
@@ -228,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;