@shelbyb/daywalker-sdk 0.3.0 → 0.4.0

package/dist/flags/client.js

@@ -1,5 +1,6 @@
-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);
@@ -29,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) {
@@ -54,6 +59,8 @@ export class DevPulseClient {
             if (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)}`,
@@ -66,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();
     }
@@ -84,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;
         }
@@ -95,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) {
@@ -103,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)
@@ -168,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);
@@ -214,10 +249,20 @@ 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 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)
@@ -229,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);
     }
@@ -248,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() {
@@ -265,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)
@@ -292,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

@@ -166,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++) {
@@ -178,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;
@@ -193,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() {
@@ -202,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;
 }

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. */