@shelbyb/daywalker-sdk 0.1.4 → 0.3.0

package/dist/flags/client.js

@@ -0,0 +1,302 @@
+import { EventProcessor, SseClient, encodeContext, noopLogger } from "./common/index.js";
+import { assertSecureUrl } from "../config.js";
+/** A flag map without a prototype, so keys like `__proto__` or `toString` never resolve to inherited values. */
+function flagMap(entries = {}) {
+    return Object.assign(Object.create(null), entries);
+}
+function isFlagSet(x) {
+    return !!x && typeof x === "object" && Object.values(x).every((v) => v && typeof v === "object" && "value" in v && "version" in v);
+}
+/**
+ * A client for one evaluation context. Fetches evaluated flags, keeps them
+ * current over SSE, and reports analytics.
+ *
+ *   const client = createClient("<client-side id>", { key: user.id }, { baseUrl });
+ *   await client.waitForInitialization();
+ *   client.on("change:new-checkout", (value) => render(value));
+ *   client.variation("new-checkout", false);
+ */
+export class DevPulseClient {
+    clientSideId;
+    context;
+    options;
+    flags = flagMap();
+    listeners = new Map();
+    stream = null;
+    events = null;
+    ready;
+    resolveReady;
+    rejectReady;
+    initialized = false;
+    closed = false;
+    logger;
+    base;
+    constructor(clientSideId, context, options) {
+        this.clientSideId = clientSideId;
+        this.context = context;
+        this.options = options;
+        this.logger = options.logger ?? noopLogger;
+        assertSecureUrl("baseUrl", options.baseUrl);
+        this.base = options.baseUrl.replace(/\/$/, "");
+        this.ready = new Promise((res, rej) => {
+            this.resolveReady = res;
+            this.rejectReady = rej;
+        });
+        this.ready.catch(() => undefined);
+        if (options.bootstrap) {
+            this.flags = isFlagSet(options.bootstrap)
+                ? flagMap(options.bootstrap)
+                : flagMap(Object.fromEntries(Object.entries(options.bootstrap).map(([k, v]) => [k, { value: v, variation: null, version: 0 }])));
+            this.markReady();
+        }
+        else if (options.cache) {
+            const cached = this.readCache();
+            if (cached)
+                this.flags = flagMap(cached);
+        }
+        if (options.sendEvents !== false && typeof globalThis.fetch === "function") {
+            this.events = new EventProcessor({
+                url: `${this.base}/sdk/v1/events/client/${encodeURIComponent(clientSideId)}`,
+                flushIntervalMs: options.flushIntervalMs ?? 5000,
+                privateAttributes: options.privateAttributes,
+                allAttributesPrivate: options.allAttributesPrivate,
+                fetch: options.fetch,
+                beacon: true,
+                logger: this.logger,
+            });
+            this.events.identify(context);
+            const doc = globalThis.document;
+            doc?.addEventListener("visibilitychange", () => {
+                if (doc.visibilityState === "hidden")
+                    void this.events?.flush();
+            });
+        }
+        void this.start();
+    }
+    query() {
+        const p = new URLSearchParams({ context: encodeContext(this.context) });
+        if (this.options.hash)
+            p.set("h", this.options.hash);
+        if (this.options.withReasons)
+            p.set("withReasons", "true");
+        return p.toString();
+    }
+    async start() {
+        if (this.options.streaming === false) {
+            try {
+                this.replaceAll(await this.fetchFlags());
+            }
+            catch (err) {
+                this.fail(err);
+            }
+            return;
+        }
+        this.stream = new SseClient({
+            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"),
+            onError: (err) => {
+                this.logger.warn(`DevPulse stream error: ${err.message}`);
+                if (!err.recoverable) {
+                    this.fail(err);
+                    return false;
+                }
+                // Keep serving flags while reconnecting; fetch once so a first load still succeeds.
+                if (!this.initialized)
+                    this.fetchFlags().then((f) => this.replaceAll(f), () => undefined);
+                return true;
+            },
+        });
+        this.stream.start();
+    }
+    async fetchFlags() {
+        const res = await (this.options.fetch ?? fetch)(`${this.base}/sdk/v1/client/${encodeURIComponent(this.clientSideId)}/flags?${this.query()}`);
+        if (!res.ok)
+            throw new Error(`Flag request failed with ${res.status}`);
+        return (await res.json());
+    }
+    onStreamEvent(type, data) {
+        try {
+            const payload = JSON.parse(data);
+            if (type === "put")
+                this.replaceAll(payload);
+            else if (type === "patch") {
+                const { key, ...state } = payload;
+                const prev = this.flag(key);
+                if (prev && prev.version > state.version)
+                    return;
+                this.flags[key] = state;
+                this.emitChanges({ [key]: { current: state.value, previous: prev?.value } });
+                this.writeCache();
+            }
+            else if (type === "delete") {
+                const { key, version } = payload;
+                const prev = this.flag(key);
+                if (!prev || prev.version > version)
+                    return;
+                delete this.flags[key];
+                this.emitChanges({ [key]: { current: null, previous: prev.value } });
+                this.writeCache();
+            }
+        }
+        catch (err) {
+            this.logger.error("Malformed stream event", err);
+        }
+    }
+    replaceAll(next) {
+        const changes = {};
+        for (const key of new Set([...Object.keys(this.flags), ...Object.keys(next)])) {
+            const a = this.flag(key)?.value;
+            const b = Object.hasOwn(next, key) ? next[key]?.value : undefined;
+            if (JSON.stringify(a) !== JSON.stringify(b))
+                changes[key] = { current: b ?? null, previous: a };
+        }
+        this.flags = flagMap(next);
+        this.writeCache();
+        this.markReady();
+        if (Object.keys(changes).length)
+            this.emitChanges(changes);
+    }
+    flag(key) {
+        return Object.hasOwn(this.flags, key) ? this.flags[key] : undefined;
+    }
+    markReady() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        this.resolveReady();
+        this.emit("ready");
+    }
+    fail(err) {
+        if (!this.initialized)
+            this.rejectReady(err);
+        this.emit("failed", err);
+    }
+    emitChanges(changes) {
+        this.emit("change", changes);
+        for (const [key, c] of Object.entries(changes))
+            this.emit(`change:${key}`, c.current, c.previous);
+    }
+    cacheKey() {
+        return `devpulse:${this.clientSideId}:${encodeContext(this.context)}`;
+    }
+    readCache() {
+        try {
+            const raw = globalThis.localStorage?.getItem(this.cacheKey());
+            return raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeCache() {
+        if (!this.options.cache)
+            return;
+        try {
+            globalThis.localStorage?.setItem(this.cacheKey(), JSON.stringify(this.flags));
+        }
+        catch {
+            /* storage full or unavailable */
+        }
+    }
+    // ---------- Public API ----------
+    /** Resolves once flags are loaded (or rejects on a fatal error such as an invalid client-side ID). */
+    waitForInitialization(opts = {}) {
+        if (!opts.timeoutMs)
+            return this.ready;
+        let timer;
+        const timeout = new Promise((_, rej) => {
+            timer = setTimeout(() => rej(new Error("DevPulse initialization timed out")), opts.timeoutMs);
+        });
+        return Promise.race([this.ready, timeout]).finally(() => clearTimeout(timer));
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    variation(key, defaultValue) {
+        return this.variationDetail(key, defaultValue).value;
+    }
+    variationDetail(key, defaultValue) {
+        const f = this.flag(key);
+        let detail;
+        if (!f)
+            detail = { value: defaultValue, variationIndex: null, reason: { kind: "ERROR", errorKind: this.initialized ? "FLAG_NOT_FOUND" : "CLIENT_NOT_READY" } };
+        // A null value means "off with no off variation": serve the caller's default.
+        else if (f.value === null)
+            detail = { value: defaultValue, variationIndex: f.variation, reason: f.reason ?? null };
+        else if (defaultValue !== null && typeof defaultValue !== typeof f.value)
+            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;
+    }
+    boolVariation(key, defaultValue) {
+        return this.variation(key, defaultValue);
+    }
+    stringVariation(key, defaultValue) {
+        return this.variation(key, defaultValue);
+    }
+    numberVariation(key, defaultValue) {
+        return this.variation(key, defaultValue);
+    }
+    jsonVariation(key, defaultValue) {
+        return this.variation(key, defaultValue);
+    }
+    /** All flag values (doesn't record evaluations). */
+    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. */
+    async identify(context, opts = {}) {
+        this.context = context;
+        if (opts.hash !== undefined)
+            this.options.hash = opts.hash;
+        this.events?.identify(context);
+        this.replaceAll(await this.fetchFlags());
+        this.stream?.restart();
+        return this.allFlags();
+    }
+    getContext() {
+        return this.context;
+    }
+    /** Record a custom event for metrics and experiments. */
+    track(key, data, metricValue) {
+        this.events?.track(key, this.context, data, metricValue);
+    }
+    on(event, fn) {
+        let set = this.listeners.get(event);
+        if (!set)
+            this.listeners.set(event, (set = new Set()));
+        set.add(fn);
+        return () => this.off(event, fn);
+    }
+    off(event, fn) {
+        this.listeners.get(event)?.delete(fn);
+    }
+    emit(event, ...args) {
+        for (const fn of this.listeners.get(event) ?? []) {
+            try {
+                fn(...args);
+            }
+            catch (err) {
+                this.logger.error(`Listener for "${event}" threw`, err);
+            }
+        }
+    }
+    async flush() {
+        await this.events?.flush();
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.stream?.stop();
+        await this.events?.close();
+        this.listeners.clear();
+    }
+}
+export function createClient(clientSideId, context, options) {
+    return new DevPulseClient(clientSideId, context, options);
+}

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

@@ -0,0 +1,59 @@
+import { type ContextInput, type EvaluationReason, type FlagValue } from "../engine/index.js";
+export interface EventProcessorOptions {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    flushIntervalMs?: number;
+    capacity?: number;
+    /** Treat every attribute (except key/kind) as private. */
+    allAttributesPrivate?: boolean;
+    /** Attribute names (or RFC 6901 pointers) never sent to DevPulse. */
+    privateAttributes?: string[];
+    /** Use navigator.sendBeacon when available (browsers, on page hide). */
+    beacon?: boolean;
+    logger?: Logger;
+}
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export declare const noopLogger: Logger;
+/**
+ * Buffers analytics: per-flag summaries (counts per variation), context
+ * index events (deduplicated), full feature events for tracked flags and
+ * experiments, and custom events. Flushes on an interval and on demand.
+ */
+export declare class EventProcessor {
+    private readonly opts;
+    private summary;
+    private summaryStart;
+    private queue;
+    private seenContexts;
+    private timer;
+    private disabled;
+    private readonly logger;
+    constructor(opts: EventProcessorOptions);
+    /** Strip private attributes and record which were removed. */
+    redact(context: ContextInput): Record<string, unknown>;
+    private contextKeys;
+    /** Queue an index event the first time a context is seen in a while. */
+    private noticeContext;
+    recordEvaluation(e: {
+        key: string;
+        context: ContextInput;
+        value: FlagValue;
+        default: FlagValue;
+        variation: number | null;
+        version?: number;
+        reason?: EvaluationReason;
+        trackEvents?: boolean;
+    }): void;
+    track(key: string, context: ContextInput, data?: unknown, metricValue?: number): void;
+    identify(context: ContextInput): void;
+    private push;
+    private drain;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/flags/common/events.js

@@ -0,0 +1,204 @@
+import { parseContext } from "../engine/index.js";
+export const noopLogger = { debug() { }, info() { }, warn() { }, error() { } };
+/** Delete the value at `tokens` inside `target`, copying (not mutating) nested objects. */
+function removePointer(target, tokens) {
+    const [head, ...rest] = tokens;
+    if (!Object.hasOwn(target, head))
+        return false;
+    if (!rest.length) {
+        delete target[head];
+        return true;
+    }
+    const child = target[head];
+    if (!child || typeof child !== "object" || Array.isArray(child))
+        return false;
+    const copy = { ...child };
+    if (!removePointer(copy, rest))
+        return false;
+    target[head] = copy;
+    return true;
+}
+/**
+ * Buffers analytics: per-flag summaries (counts per variation), context
+ * index events (deduplicated), full feature events for tracked flags and
+ * experiments, and custom events. Flushes on an interval and on demand.
+ */
+export class EventProcessor {
+    opts;
+    summary = new Map();
+    summaryStart = 0;
+    queue = [];
+    seenContexts = new Map();
+    timer = null;
+    disabled = false;
+    logger;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = opts.logger ?? noopLogger;
+        this.timer = setInterval(() => void this.flush(), opts.flushIntervalMs ?? 5000);
+        this.timer.unref?.();
+    }
+    /** Strip private attributes and record which were removed. */
+    redact(context) {
+        const strip = (c) => {
+            const meta = (c._meta ?? {});
+            const priv = new Set([...(this.opts.privateAttributes ?? []), ...(meta.privateAttributes ?? [])]);
+            const out = {};
+            const redacted = [];
+            for (const [k, v] of Object.entries(c)) {
+                if (k === "_meta")
+                    continue;
+                if (k !== "key" && k !== "kind" && k !== "anonymous" && (this.opts.allAttributesPrivate || priv.has(k) || priv.has(`/${k}`)))
+                    redacted.push(k);
+                else
+                    out[k] = v;
+            }
+            // Nested JSON pointers (/address/zip): remove the leaf from a copy of each object on the path.
+            for (const ref of priv) {
+                const tokens = ref.startsWith("/") ? ref.slice(1).split("/").map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~")) : [];
+                if (tokens.length < 2 || ["key", "kind", "anonymous", "_meta"].includes(tokens[0]))
+                    continue;
+                if (removePointer(out, tokens))
+                    redacted.push(ref);
+            }
+            if (redacted.length)
+                out.redactedAttributes = redacted;
+            return out;
+        };
+        if (context.kind === "multi") {
+            const out = { kind: "multi" };
+            for (const [k, v] of Object.entries(context))
+                if (k !== "kind")
+                    out[k] = strip(v);
+            return out;
+        }
+        return strip(context);
+    }
+    contextKeys(context) {
+        try {
+            const ctx = parseContext(context);
+            return Object.fromEntries([...ctx.kinds.values()].map((c) => [c.kind, c.key]));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Queue an index event the first time a context is seen in a while. */
+    noticeContext(context) {
+        let canonical;
+        try {
+            canonical = parseContext(context).canonicalKey;
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        const last = this.seenContexts.get(canonical);
+        if (last && now - last < 5 * 60_000)
+            return;
+        if (this.seenContexts.size > 1000)
+            this.seenContexts.clear();
+        this.seenContexts.set(canonical, now);
+        this.push({ kind: "index", creationDate: now, context: this.redact(context) });
+    }
+    recordEvaluation(e) {
+        if (this.disabled)
+            return;
+        this.noticeContext(e.context);
+        if (!this.summaryStart)
+            this.summaryStart = Date.now();
+        let s = this.summary.get(e.key);
+        if (!s)
+            this.summary.set(e.key, (s = { default: e.default, counters: new Map() }));
+        const unknown = e.version === undefined;
+        const ck = `${e.variation ?? "default"}:${e.version ?? "unknown"}`;
+        const c = s.counters.get(ck) ?? { value: e.value, count: 0, ...(unknown ? { unknown: true } : { variation: e.variation ?? undefined, version: e.version }) };
+        c.count++;
+        s.counters.set(ck, c);
+        const inExperiment = !!e.reason && "inExperiment" in e.reason && e.reason.inExperiment;
+        if (e.trackEvents || inExperiment) {
+            this.push({ kind: "feature", creationDate: Date.now(), key: e.key, version: e.version, variation: e.variation, value: e.value, default: e.default, contextKeys: this.contextKeys(e.context), ...(e.reason ? { reason: e.reason } : {}) });
+        }
+    }
+    track(key, context, data, metricValue) {
+        if (this.disabled)
+            return;
+        this.noticeContext(context);
+        const keys = this.contextKeys(context);
+        if (!keys)
+            return this.logger.warn("track() called with an invalid context");
+        this.push({ kind: "custom", key, creationDate: Date.now(), contextKeys: keys, ...(data !== undefined ? { data } : {}), ...(typeof metricValue === "number" ? { metricValue } : {}) });
+    }
+    identify(context) {
+        if (this.disabled)
+            return;
+        try {
+            parseContext(context);
+        }
+        catch {
+            return;
+        }
+        this.push({ kind: "identify", creationDate: Date.now(), context: this.redact(context) });
+    }
+    push(e) {
+        if (this.queue.length >= (this.opts.capacity ?? 10_000))
+            return this.logger.warn("Event buffer full; dropping events");
+        this.queue.push(e);
+    }
+    drain() {
+        const events = this.queue;
+        this.queue = [];
+        if (this.summary.size) {
+            events.push({
+                kind: "summary",
+                startDate: this.summaryStart,
+                endDate: Date.now(),
+                features: Object.fromEntries([...this.summary.entries()].map(([k, s]) => [k, { default: s.default, counters: [...s.counters.values()] }])),
+            });
+            this.summary.clear();
+            this.summaryStart = 0;
+        }
+        return events;
+    }
+    async flush() {
+        if (this.disabled)
+            return;
+        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))
+                return;
+        }
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const res = await (this.opts.fetch ?? fetch)(this.opts.url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", ...this.opts.headers },
+                    body,
+                    keepalive: body.length < 60_000,
+                });
+                if (res.ok)
+                    return;
+                if (res.status === 401 || res.status === 403) {
+                    this.disabled = true;
+                    return this.logger.error(`Events rejected (${res.status}); analytics disabled. Check your SDK key.`);
+                }
+                if (res.status < 500 && res.status !== 429)
+                    return this.logger.warn(`Events rejected (${res.status})`);
+            }
+            catch (err) {
+                if (attempt === 1)
+                    this.logger.warn("Failed to send events", err);
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    }
+    async close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+    }
+}

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

@@ -0,0 +1,5 @@
+export { SseParser, SseClient, SseError, backoffDelay, type SseEvent, type SseClientOptions } from "./sse.js";
+export { EventProcessor, noopLogger, 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";

package/dist/flags/common/index.js

@@ -0,0 +1,12 @@
+export { SseParser, SseClient, SseError, backoffDelay } from "./sse.js";
+export { EventProcessor, noopLogger } from "./events.js";
+/** Encode a context for URLs (base64url JSON), matching the DevPulse SDK endpoints. */
+export function encodeContext(context) {
+    const json = JSON.stringify(context);
+    const bytes = new TextEncoder().encode(json);
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export const SDK_VERSION = "0.1.0";

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

@@ -0,0 +1,62 @@
+/**
+ * Server-Sent Events over fetch, implementing the WHATWG HTML event-stream
+ * interpretation (§9.2.6): CRLF/LF/CR line endings, comments, `event`, `data`,
+ * `id` and `retry` fields. Unlike the browser EventSource it supports custom
+ * headers and request bodies and runs in Node, browsers, workers and React Native.
+ */
+export interface SseEvent {
+    type: string;
+    data: string;
+    lastEventId: string;
+}
+/** Incremental parser: feed it chunks of text, get dispatched events back. */
+export declare class SseParser {
+    private buffer;
+    private data;
+    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;
+    feed(chunk: string): SseEvent[];
+    private line;
+}
+export interface SseClientOptions {
+    url: string | (() => string);
+    headers?: Record<string, string> | (() => Record<string, string>);
+    fetch?: typeof fetch;
+    /** Called for every dispatched event. */
+    onEvent: (event: SseEvent) => void;
+    onOpen?: () => void;
+    /** Called on each failure; return false to stop reconnecting (e.g. 401). */
+    onError?: (error: SseError) => boolean | void;
+    initialRetryMs?: number;
+    maxRetryMs?: number;
+    /** Reconnect if nothing (not even a heartbeat) arrives for this long. */
+    readTimeoutMs?: number;
+}
+export declare class SseError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+    /** 4xx (except 408/429) won't succeed on retry. */
+    get recoverable(): boolean;
+}
+/** Exponential backoff with full jitter, reset after a stable connection. */
+export declare function backoffDelay(attempt: number, base: number, max: number): number;
+export declare class SseClient {
+    private readonly opts;
+    private controller;
+    private stopped;
+    private attempt;
+    private parser;
+    private timer;
+    private watchdog;
+    private reader;
+    constructor(opts: SseClientOptions);
+    start(): void;
+    stop(): void;
+    /** Drop the current connection and reconnect immediately (e.g. after identify). */
+    restart(): void;
+    private connect;
+}