@shelbyb/daywalker-sdk 0.3.0 → 0.4.1

package/dist/express.js

@@ -1,9 +1,11 @@
 import { daywalker } from "./client.js";
+import { toAuthFailureResponse } from "./middleware.js";
 /**
  * Express / Connect / Node http middleware that validates incoming Daywalker tokens.
  */
 export function daywalkerAuth(options = {}) {
     const client = options.client ?? daywalker;
+    const serviceSlug = options.serviceSlug;
     return async (req, res, next) => {
         const getHeader = (name) => {
             if (typeof req.get === "function")
@@ -33,19 +35,19 @@ export function daywalkerAuth(options = {}) {
             res.end(JSON.stringify({ error: "INVALID_TOKEN", message: "Missing Authorization header or x-api-token" }));
             return;
         }
-        const result = await client.validateToken(token);
+        const result = await client.validateToken(token, { serviceSlug });
         if (!result.ok) {
-            const status = result.status === 429 ? 429 : 401;
-            if (result.retryAfter) {
-                res.setHeader("Retry-After", String(result.retryAfter));
+            const { status, ...body } = toAuthFailureResponse(result);
+            if (body.retryAfter) {
+                res.setHeader("Retry-After", String(body.retryAfter));
             }
             if (typeof res.status === "function" && typeof res.json === "function") {
-                res.status(status).json({ error: result.error, message: result.message, retryAfter: result.retryAfter });
+                res.status(status).json(body);
                 return;
             }
             res.statusCode = status;
             res.setHeader("Content-Type", "application/json");
-            res.end(JSON.stringify({ error: result.error, message: result.message, retryAfter: result.retryAfter }));
+            res.end(JSON.stringify(body));
             return;
         }
         req.auth = result.data;

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;
@@ -15,7 +16,13 @@ export interface ClientOptions {
     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,16 +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;
@@ -78,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,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;
 }