@shelbyb/daywalker-sdk 0.1.3 → 0.2.0

package/dist/flags/client.d.ts

@@ -0,0 +1,101 @@
+import type { ContextInput, EvaluationReason, FlagValue } from "./engine/index.js";
+import { type Logger } from "./common/index.js";
+export type { ContextInput, EvaluationReason, FlagValue, Logger };
+export interface FlagState {
+    value: FlagValue;
+    variation: number | null;
+    version: number;
+    reason?: EvaluationReason;
+    trackEvents?: boolean;
+    trackReason?: boolean;
+}
+export type FlagSet = Record<string, FlagState>;
+export interface ClientOptions {
+    /** Base URL of your DevPulse deployment, e.g. https://flags.example.com */
+    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. */
+    bootstrap?: FlagSet | Record<string, FlagValue>;
+    /** Secure mode hash for the context (HMAC-SHA256 computed on your server). */
+    hash?: string;
+    /** Include evaluation reasons (for variationDetail). */
+    withReasons?: boolean;
+    sendEvents?: boolean;
+    flushIntervalMs?: number;
+    privateAttributes?: string[];
+    allAttributesPrivate?: boolean;
+    /** Cache the last flags in localStorage and use them while loading. */
+    cache?: boolean;
+    fetch?: typeof fetch;
+    logger?: Logger;
+}
+export interface EvaluationDetail<T = FlagValue> {
+    value: T;
+    variationIndex: number | null;
+    reason: EvaluationReason | null;
+}
+type Listener = (...args: unknown[]) => void;
+/**
+ * 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 declare class DevPulseClient {
+    private readonly clientSideId;
+    private context;
+    private readonly options;
+    private flags;
+    private listeners;
+    private stream;
+    private events;
+    private ready;
+    private resolveReady;
+    private rejectReady;
+    private initialized;
+    private closed;
+    private readonly logger;
+    private readonly base;
+    constructor(clientSideId: string, context: ContextInput, options: ClientOptions);
+    private query;
+    private start;
+    private fetchFlags;
+    private onStreamEvent;
+    private replaceAll;
+    private markReady;
+    private fail;
+    private emitChanges;
+    private cacheKey;
+    private readCache;
+    private writeCache;
+    /** Resolves once flags are loaded (or rejects on a fatal error such as an invalid client-side ID). */
+    waitForInitialization(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    get isInitialized(): boolean;
+    variation<T extends FlagValue>(key: string, defaultValue: T): T;
+    variationDetail<T extends FlagValue>(key: string, defaultValue: T): EvaluationDetail<T>;
+    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. */
+    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;
+    off(event: string, fn: Listener): void;
+    private emit;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createClient(clientSideId: string, context: ContextInput, options: ClientOptions): DevPulseClient;

package/dist/flags/client.js

@@ -0,0 +1,293 @@
+import { EventProcessor, SseClient, encodeContext, noopLogger } from "./common/index.js";
+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 = {};
+    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;
+        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)
+                ? { ...options.bootstrap }
+                : 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 = 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.flags[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.flags[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.flags[key]?.value;
+            const b = next[key]?.value;
+            if (JSON.stringify(a) !== JSON.stringify(b))
+                changes[key] = { current: b ?? null, previous: a };
+        }
+        this.flags = { ...next };
+        this.writeCache();
+        this.markReady();
+        if (Object.keys(changes).length)
+            this.emitChanges(changes);
+    }
+    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.flags[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,178 @@
+import { parseContext } from "../engine/index.js";
+export const noopLogger = { debug() { }, info() { }, warn() { }, error() { } };
+/**
+ * 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;
+            }
+            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";