@shelbyb/daywalker-sdk 0.1.3 → 0.2.0

package/README.md

@@ -210,14 +210,39 @@ Inbound tokens may be supplied as `x-api-token: srv_live_...` or `Authorization:
 
 Each outbound request signed by `@shelbyb/daywalker-sdk` includes:
 - `Content-Digest: sha-256=:<base64-encoded-hash>:`
-- `Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");created=<unix_seconds>;keyid="<kid>";alg="ed25519"`
+- `Signature-Input: sig1=("@method" "@path" "@authority" "content-digest");created=<unix_seconds>;keyid="<kid>";alg="ed25519";nonce="<random>"`
 - `Signature: sig1=:<base64-encoded-signature>:`
 - `Authorization: Bearer <DAYWALKER_API_KEY>`
 
+A fresh random `nonce` is generated for every attempt (including retries), so identical requests in the same second still produce unique signatures and never trip replay protection. `validateToken()` also shares one in-flight request between concurrent callers for the same token, and briefly caches failures (`negativeCacheTtlMs`, default 3000ms; 429s and network errors are never cached).
+
 The exact signature base and test cases are verified against [`test-vectors/signing-rfc9421.json`](./test-vectors/signing-rfc9421.json).
 
 ---
 
+## 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/client.d.ts

@@ -9,6 +9,7 @@ export declare class Daywalker {
     private readonly _rawConfig;
     private _signingKeyPromise?;
     private readonly _cache;
+    private readonly _inflight;
     constructor(config?: DaywalkerConfig);
     get config(): ResolvedConfig;
     toJSON(): Record<string, unknown>;
@@ -31,6 +32,7 @@ export declare class Daywalker {
         forceRefresh?: boolean;
         offlineOnly?: boolean;
     }): Promise<ValidateResult>;
+    private _validateOnline;
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */

package/dist/client.js

@@ -15,11 +15,20 @@ function parseRetryAfter(headerValue) {
     }
     return undefined;
 }
+function generateNonce() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 export class Daywalker {
     _config;
     _rawConfig;
     _signingKeyPromise;
     _cache = new Map();
+    _inflight = new Map();
     constructor(config = {}) {
         this._rawConfig = config;
         this._config = resolveConfig(config);
@@ -104,6 +113,7 @@ export class Daywalker {
                     key: signingKey,
                     keyid: this._config.keyId ?? undefined,
                     apiKey: this._config.apiKey ?? undefined,
+                    nonce: generateNonce(),
                 });
                 for (const [k, v] of Object.entries(signedHeaders)) {
                     if (v !== undefined) {
@@ -231,7 +241,25 @@ export class Daywalker {
                 message: "Offline verification requires DAYWALKER_PUBLIC_KEY and a valid JWT token lease",
             };
         }
-        // Online verification
+        // Online verification, deduplicated across concurrent callers
+        const inflightKey = `${cacheKey}`;
+        const pending = this._inflight.get(inflightKey);
+        if (pending)
+            return pending;
+        const run = this._validateOnline(token, serviceSlug, cacheKey).finally(() => {
+            this._inflight.delete(inflightKey);
+        });
+        this._inflight.set(inflightKey, run);
+        return run;
+    }
+    async _validateOnline(token, serviceSlug, cacheKey) {
+        const negTtl = this._config.negativeCacheTtlMs;
+        const fail = (result) => {
+            if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR") {
+                this._cache.set(cacheKey, { result, expiresAt: Date.now() + negTtl });
+            }
+            return result;
+        };
         try {
             const validateBody = { token };
             if (serviceSlug) {
@@ -282,12 +310,12 @@ export class Daywalker {
             else if (json.error === "REVOKED" || /revoked/i.test(errMsg)) {
                 error = "REVOKED";
             }
-            return {
+            return fail({
                 ok: false,
                 error,
                 status: res.status,
                 message: redactSecrets(errMsg || `Validation failed with HTTP ${res.status}`),
-            };
+            });
         }
         catch (err) {
             return {

package/dist/config.d.ts

@@ -10,6 +10,7 @@ export interface ResolvedConfig {
     daywalkerPublicKey: string | PublicJwk | null;
     authUrl: string;
     cacheTtlMs: number;
+    negativeCacheTtlMs: number;
     maxRetries: number;
     problems: string[];
 }

package/dist/config.js

@@ -82,6 +82,7 @@ export function resolveConfig(options = {}) {
     const daywalkerPublicKey = options.daywalkerPublicKey ?? (env.DAYWALKER_PUBLIC_KEY ? env.DAYWALKER_PUBLIC_KEY.trim() : null);
     const authUrl = (options.authUrl ?? env.DAYWALKER_AUTH_URL ?? "https://auth.daywalker.dev").replace(/\/+$/, "");
     const cacheTtlMs = options.cacheTtlMs ?? 60_000;
+    const negativeCacheTtlMs = options.negativeCacheTtlMs ?? 3_000;
     const maxRetries = options.maxRetries ?? (options.retry?.maxRetries ?? 3);
     return {
         apiKey,
@@ -94,6 +95,7 @@ export function resolveConfig(options = {}) {
         daywalkerPublicKey,
         authUrl,
         cacheTtlMs,
+        negativeCacheTtlMs,
         maxRetries,
         problems,
     };