@shelbyb/daywalker-sdk 0.1.4 → 0.2.0

package/README.md

@@ -220,6 +220,29 @@ The exact signature base and test cases are verified against [`test-vectors/sign
 
 ---
 
+## DevPulse SDKs (one package)
+
+The same package ships the [DevPulse](https://github.com/shelbyb/devpulse) client SDKs as subpath exports. Each subpath is tree-shakeable and has zero dependencies; `react` and the OpenFeature SDKs are optional peer dependencies used only by their subpaths.
+
+| Import | What it is | Docs |
+|---|---|---|
+| `@shelbyb/daywalker-sdk/flags` | Feature flags for browsers and JS clients, real-time over SSE | [docs/flags.md](./docs/flags.md) |
+| `@shelbyb/daywalker-sdk/flags/node` | Server-side flags with local evaluation and streaming updates | [docs/flags-node.md](./docs/flags-node.md) |
+| `@shelbyb/daywalker-sdk/flags/react` | React provider and hooks (SSR bootstrap, no flicker) | [docs/flags-react.md](./docs/flags-react.md) |
+| `@shelbyb/daywalker-sdk/flags/engine` | The deterministic evaluation engine (advanced / testing) | — |
+| `@shelbyb/daywalker-sdk/openfeature/server`, `/openfeature/web` | OpenFeature providers | [docs/openfeature.md](./docs/openfeature.md) |
+| `@shelbyb/daywalker-sdk/analytics` | Product analytics: events, page views, identify, sessions (browser and Node) | [docs/analytics.md](./docs/analytics.md) |
+
+```ts
+import { createClient } from "@shelbyb/daywalker-sdk/flags";
+import { createAnalytics } from "@shelbyb/daywalker-sdk/analytics";
+
+const flags = createClient(clientSideId, { kind: "user", key: user.id }, { baseUrl: "https://devpulse.example.com" });
+const analytics = createAnalytics({ writeKey: "dpa_…", host: "https://devpulse.example.com", flags }); // events carry $feature/<key>
+```
+
+---
+
 ## License
 
 MIT

package/dist/analytics/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * DevPulse product analytics. Works in browsers (automatic page views,
+ * sessions, persistence, sendBeacon on page hide) and in Node (pass a
+ * distinctId per call). Events are batched and retried with backoff.
+ */
+export type Properties = Record<string, unknown>;
+/** Anything with `allFlags()`, e.g. a DevPulse feature-flag client. */
+export type FlagSource = {
+    allFlags(): Record<string, unknown>;
+};
+export type AnalyticsOptions = {
+    /** The project's public write key (dpa_…). */
+    writeKey: string;
+    /** Your DevPulse URL, e.g. https://devpulse.example.com */
+    host: string;
+    /** Capture $pageview on load and on client-side navigation (browsers). Default true. */
+    autocapturePageviews?: boolean;
+    /** Send when this many events are queued. Default 20 (1 in Node is not needed: use flush()). */
+    flushAt?: number;
+    /** Send queued events this often, in ms. Default 2000 in browsers, 10000 in Node. */
+    flushInterval?: number;
+    /** Events kept while offline; the oldest are dropped past this. Default 1000. */
+    maxQueueSize?: number;
+    /** Where the anonymous id, super properties and session live. Default localStorage in browsers. */
+    persistence?: "localStorage" | "memory";
+    /** A new session starts after this much inactivity. Default 30. */
+    sessionTimeoutMinutes?: number;
+    /** Adds `$feature/<key>` properties with each flag's current value to every event. */
+    flags?: FlagSource;
+    /** Don't send anything when the browser's Do Not Track is on. Default false. */
+    respectDoNotTrack?: boolean;
+    /** Start opted out (e.g. until the user accepts a consent banner). */
+    optedOut?: boolean;
+    fetch?: typeof fetch;
+    onError?: (err: Error) => void;
+};
+export type CaptureOptions = {
+    /** Server-side: who did it. Defaults to the current browser user. */
+    distinctId?: string;
+    timestamp?: Date;
+    $set?: Properties;
+    $set_once?: Properties;
+};
+export declare const VERSION = "0.1.0";
+/** Time-ordered UUID (v7). */
+export declare function uuidv7(ms?: number): string;
+export declare class Analytics {
+    private opts;
+    private store;
+    private state;
+    private queue;
+    private timer;
+    private sending;
+    private backoff;
+    private lastUrl;
+    private cleanup;
+    private endpoint;
+    constructor(options: AnalyticsOptions);
+    /** Record an event. */
+    capture(event: string, properties?: Properties, opts?: CaptureOptions): void;
+    /** Record a page view (automatic unless autocapturePageviews is false). */
+    pageview(properties?: Properties): void;
+    /**
+     * Link this browser to a known user. Events from before (the anonymous id)
+     * are merged into the user's profile. Optionally set person properties.
+     */
+    identify(distinctId: string, set?: Properties, setOnce?: Properties): void;
+    /** Update the current person's properties. */
+    setPersonProperties(set?: Properties, setOnce?: Properties, opts?: {
+        distinctId?: string;
+    }): void;
+    /** Properties sent with every event from now on (persisted in browsers). */
+    register(properties: Properties): void;
+    unregister(key: string): void;
+    /** On logout: a new anonymous id, no super properties, a new session. */
+    reset(): void;
+    optOut(): void;
+    optIn(): void;
+    hasOptedOut(): boolean;
+    getDistinctId(): string;
+    getSessionId(): string | null;
+    /** Send everything queued now. */
+    flush(): Promise<void>;
+    /** Flush and detach listeners (call before a Node process exits). */
+    shutdown(): Promise<void>;
+    private disabled;
+    private context;
+    private flagProps;
+    /** Rolling session: renewed after inactivity or at most every 24 hours. */
+    private session;
+    private enqueue;
+    private schedule;
+    /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
+    private send;
+    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    private beacon;
+    private attachBrowser;
+}
+export declare function createAnalytics(options: AnalyticsOptions): Analytics;

package/dist/analytics/index.js

@@ -0,0 +1,352 @@
+/**
+ * DevPulse product analytics. Works in browsers (automatic page views,
+ * sessions, persistence, sendBeacon on page hide) and in Node (pass a
+ * distinctId per call). Events are batched and retried with backoff.
+ */
+export const VERSION = "0.1.0";
+const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+const MAX_SESSION_MS = 24 * 3_600_000;
+/** Time-ordered UUID (v7). */
+export function uuidv7(ms = Date.now()) {
+    const b = new Uint8Array(16);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        c.getRandomValues(b);
+    else
+        for (let i = 0; i < 16; i++)
+            b[i] = Math.floor(Math.random() * 256);
+    for (let i = 0; i < 6; i++)
+        b[i] = Math.floor(ms / 2 ** (8 * (5 - i))) % 256;
+    b[6] = (b[6] & 0x0f) | 0x70;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+class Store {
+    key;
+    local;
+    mem = null;
+    constructor(key, local) {
+        this.key = key;
+        this.local = local;
+    }
+    load() {
+        if (this.mem)
+            return this.mem;
+        if (this.local) {
+            try {
+                const raw = localStorage.getItem(this.key);
+                if (raw)
+                    this.mem = JSON.parse(raw);
+            }
+            catch {
+                /* storage blocked: memory only */
+            }
+        }
+        return this.mem;
+    }
+    save(s) {
+        this.mem = s;
+        if (!this.local)
+            return;
+        try {
+            localStorage.setItem(this.key, JSON.stringify(s));
+        }
+        catch {
+            /* storage full or blocked */
+        }
+    }
+}
+export class Analytics {
+    opts;
+    store;
+    state;
+    queue = [];
+    timer;
+    sending = null;
+    backoff = 0;
+    lastUrl = "";
+    cleanup = [];
+    endpoint;
+    constructor(options) {
+        if (!options.writeKey)
+            throw new Error("writeKey is required");
+        if (!options.host)
+            throw new Error("host is required");
+        this.opts = { flushAt: 20, flushInterval: isBrowser ? 2000 : 10000, maxQueueSize: 1000, sessionTimeoutMinutes: 30, ...options };
+        this.endpoint = `${options.host.replace(/\/+$/, "")}/a/batch`;
+        this.store = new Store(`dp_analytics_${options.writeKey}`, (options.persistence ?? (isBrowser ? "localStorage" : "memory")) === "localStorage" && isBrowser);
+        this.state = this.store.load() ?? { distinctId: uuidv7(), identified: false, props: {} };
+        if (options.optedOut !== undefined)
+            this.state.optedOut = options.optedOut;
+        this.store.save(this.state);
+        if (isBrowser)
+            this.attachBrowser();
+    }
+    // ---------- Public API ----------
+    /** Record an event. */
+    capture(event, properties = {}, opts = {}) {
+        if (!event || this.disabled())
+            return;
+        const now = opts.timestamp ?? new Date();
+        const props = { ...this.context(), ...this.state.props, ...this.flagProps(), ...properties };
+        if (!opts.distinctId)
+            props.$session_id = this.session(now.getTime());
+        const e = { uuid: uuidv7(now.getTime()), event, distinct_id: opts.distinctId ?? this.state.distinctId, timestamp: now.toISOString(), properties: props };
+        if (opts.$set)
+            e.$set = opts.$set;
+        if (opts.$set_once)
+            e.$set_once = opts.$set_once;
+        this.enqueue(e);
+    }
+    /** Record a page view (automatic unless autocapturePageviews is false). */
+    pageview(properties = {}) {
+        if (!isBrowser)
+            return this.capture("$pageview", properties);
+        const url = location.href;
+        this.lastUrl = url;
+        const utm = Object.fromEntries([...new URLSearchParams(location.search)].filter(([k]) => /^utm_(source|medium|campaign|term|content)$/.test(k)));
+        let setOnce;
+        if (!this.state.initialSent) {
+            setOnce = {
+                $initial_referrer: document.referrer || "$direct",
+                $initial_referring_domain: referringDomain(document.referrer) ?? "$direct",
+                $initial_current_url: url,
+                $initial_pathname: location.pathname,
+                ...Object.fromEntries(Object.entries(utm).map(([k, v]) => [`$initial_${k}`, v])),
+            };
+            this.state.initialSent = true;
+            this.store.save(this.state);
+        }
+        this.capture("$pageview", { $title: document.title, ...utm, ...properties }, { $set_once: setOnce });
+    }
+    /**
+     * Link this browser to a known user. Events from before (the anonymous id)
+     * are merged into the user's profile. Optionally set person properties.
+     */
+    identify(distinctId, set, setOnce) {
+        if (!distinctId || this.disabled())
+            return;
+        const previous = this.state.distinctId;
+        if (previous === distinctId) {
+            if (set || setOnce)
+                this.setPersonProperties(set, setOnce);
+            return;
+        }
+        this.state = { ...this.state, distinctId, identified: true };
+        this.store.save(this.state);
+        this.capture("$identify", { $anon_distinct_id: previous }, { $set: set, $set_once: setOnce });
+    }
+    /** Update the current person's properties. */
+    setPersonProperties(set, setOnce, opts = {}) {
+        this.capture("$set", {}, { distinctId: opts.distinctId, $set: set, $set_once: setOnce });
+    }
+    /** Properties sent with every event from now on (persisted in browsers). */
+    register(properties) {
+        this.state = { ...this.state, props: { ...this.state.props, ...properties } };
+        this.store.save(this.state);
+    }
+    unregister(key) {
+        const props = { ...this.state.props };
+        delete props[key];
+        this.state = { ...this.state, props };
+        this.store.save(this.state);
+    }
+    /** On logout: a new anonymous id, no super properties, a new session. */
+    reset() {
+        this.state = { distinctId: uuidv7(), identified: false, props: {}, optedOut: this.state.optedOut, initialSent: this.state.initialSent };
+        this.store.save(this.state);
+    }
+    optOut() {
+        this.state = { ...this.state, optedOut: true };
+        this.store.save(this.state);
+        this.queue = [];
+    }
+    optIn() {
+        this.state = { ...this.state, optedOut: false };
+        this.store.save(this.state);
+    }
+    hasOptedOut() {
+        return !!this.state.optedOut;
+    }
+    getDistinctId() {
+        return this.state.distinctId;
+    }
+    getSessionId() {
+        return this.state.session?.id ?? null;
+    }
+    /** Send everything queued now. */
+    async flush() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        while (this.queue.length) {
+            if (this.sending)
+                await this.sending;
+            else {
+                this.sending = this.send().finally(() => (this.sending = null));
+                const ok = await this.sending;
+                if (!ok)
+                    return;
+            }
+        }
+    }
+    /** Flush and detach listeners (call before a Node process exits). */
+    async shutdown() {
+        for (const fn of this.cleanup.splice(0))
+            fn();
+        await this.flush();
+    }
+    // ---------- Internals ----------
+    disabled() {
+        if (this.state.optedOut)
+            return true;
+        if (this.opts.respectDoNotTrack && isBrowser) {
+            const nav = navigator;
+            return nav.doNotTrack === "1" || nav.msDoNotTrack === "1" || window.doNotTrack === "1";
+        }
+        return false;
+    }
+    context() {
+        const base = { $lib: "devpulse-analytics", $lib_version: VERSION };
+        if (!isBrowser)
+            return base;
+        return {
+            ...base,
+            $current_url: location.href,
+            $host: location.host,
+            $pathname: location.pathname,
+            $referrer: document.referrer || "$direct",
+            $referring_domain: referringDomain(document.referrer) ?? "$direct",
+            $screen_width: screen.width,
+            $screen_height: screen.height,
+            $viewport_width: window.innerWidth,
+            $viewport_height: window.innerHeight,
+            $browser_language: navigator.language,
+            $device_id: this.state.identified ? undefined : this.state.distinctId,
+        };
+    }
+    flagProps() {
+        if (!this.opts.flags)
+            return {};
+        try {
+            const all = this.opts.flags.allFlags();
+            return Object.fromEntries(Object.entries(all).map(([k, v]) => [`$feature/${k}`, v]));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Rolling session: renewed after inactivity or at most every 24 hours. */
+    session(now) {
+        const s = this.state.session;
+        const timeout = this.opts.sessionTimeoutMinutes * 60_000;
+        if (!s || now - s.last > timeout || now - s.start > MAX_SESSION_MS)
+            this.state.session = { id: uuidv7(now), last: now, start: now };
+        else
+            s.last = now;
+        this.store.save(this.state);
+        return this.state.session.id;
+    }
+    enqueue(e) {
+        this.queue.push(e);
+        if (this.queue.length > this.opts.maxQueueSize)
+            this.queue.splice(0, this.queue.length - this.opts.maxQueueSize);
+        if (this.queue.length >= this.opts.flushAt && !this.backoff)
+            void this.flush();
+        else
+            this.schedule();
+    }
+    schedule() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, this.backoff || this.opts.flushInterval);
+        this.timer.unref?.();
+    }
+    /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
+    async send() {
+        const batch = this.queue.splice(0, 100);
+        if (!batch.length)
+            return true;
+        const f = this.opts.fetch ?? globalThis.fetch;
+        try {
+            const res = await f(this.endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() }),
+                keepalive: isBrowser,
+            });
+            if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 429)) {
+                if (!res.ok)
+                    this.opts.onError?.(new Error(`DevPulse analytics rejected ${batch.length} events: HTTP ${res.status}`));
+                this.backoff = 0;
+                return true;
+            }
+            throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            this.queue.unshift(...batch);
+            this.backoff = Math.min(60_000, (this.backoff || 1000) * 2);
+            this.opts.onError?.(err);
+            this.schedule();
+            return false;
+        }
+    }
+    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    beacon() {
+        if (!this.queue.length || typeof navigator.sendBeacon !== "function")
+            return;
+        const batch = this.queue.splice(0, 100);
+        const body = JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() });
+        // text/plain avoids a CORS preflight, which beacons can't do.
+        if (!navigator.sendBeacon(this.endpoint, new Blob([body], { type: "text/plain" })))
+            this.queue.unshift(...batch);
+    }
+    attachBrowser() {
+        const onHide = () => document.visibilityState === "hidden" && this.beacon();
+        const onPageHide = () => this.beacon();
+        document.addEventListener("visibilitychange", onHide);
+        window.addEventListener("pagehide", onPageHide);
+        this.cleanup.push(() => {
+            document.removeEventListener("visibilitychange", onHide);
+            window.removeEventListener("pagehide", onPageHide);
+        });
+        if (this.opts.autocapturePageviews === false)
+            return;
+        const onNav = () => {
+            // Route changes fire before the new title is set; give the app a tick.
+            setTimeout(() => location.href !== this.lastUrl && this.pageview(), 0);
+        };
+        const { pushState, replaceState } = history;
+        history.pushState = function (...args) {
+            pushState.apply(this, args);
+            onNav();
+        };
+        history.replaceState = function (...args) {
+            replaceState.apply(this, args);
+            onNav();
+        };
+        window.addEventListener("popstate", onNav);
+        this.cleanup.push(() => {
+            history.pushState = pushState;
+            history.replaceState = replaceState;
+            window.removeEventListener("popstate", onNav);
+        });
+        this.pageview();
+    }
+}
+function referringDomain(ref) {
+    if (!ref)
+        return undefined;
+    try {
+        return new URL(ref).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createAnalytics(options) {
+    return new Analytics(options);
+}

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;