drengr-js 0.1.0

package/dist/esm/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Drengr Analytics for JavaScript runtimes — Web, React Native, Electron.
+ * One call captures every fetch/XHR exchange (secret/PII redaction applied
+ * in-process before anything leaves the runtime) and ships it to your org's
+ * ingest endpoint under a publishable key.
+ *
+ *   import { Drengr } from 'drengr-js';
+ *   Drengr.start({
+ *     ingestUrl: 'https://<ref>.supabase.co/functions/v1/ingest',
+ *     publishableKey: 'drengr_pk_…',
+ *     appPackage: 'com.example.app',
+ *   });
+ */
+import { type CaptureOptions, type NetworkEvent } from './capture.js';
+import { IngestSink, type StorageAdapter } from './sink.js';
+export type { NetworkEvent, StorageAdapter };
+export { IngestSink };
+export * as redact from './redact.js';
+export interface DrengrOptions {
+    ingestUrl: string;
+    publishableKey: string;
+    /** Stable app identifier shown in the dashboard (reverse-DNS or domain). */
+    appPackage: string;
+    /** Extra envelope context merged over the defaults. */
+    context?: Record<string, unknown>;
+    /** Storage for the offline queue + install id. Default: localStorage or memory. */
+    storage?: StorageAdapter;
+    maxBodyBytes?: number;
+    captureWhen?: CaptureOptions['captureWhen'];
+    ignoreHosts?: string[];
+    redactHeaders?: string[];
+    /** Start paused (e.g. behind a consent gate); call setEnabled(true) later. */
+    enabled?: boolean;
+    /** Called after each capture, before delivery — for debugging. */
+    onEvent?: (e: NetworkEvent) => void;
+}
+export declare const Drengr: {
+    /** Install capture + delivery. Subsequent calls are ignored (stop() first). */
+    start(options: DrengrOptions): void;
+    /** Pause/resume capture (consent gate). Delivery of already-captured events continues. */
+    setEnabled(v: boolean): void;
+    /** Persistently opt this install OUT of capture (GDPR). Unlike setEnabled(false),
+     *  this survives restart: it writes the opt-out flag to storage AND pauses now, so
+     *  start() reads it and stays paused on the next launch. */
+    optOut(): void;
+    /** Reverse optOut(): clear the persisted flag and resume capture. */
+    optIn(): void;
+    /** Flush the queue now (e.g. before navigation). Best-effort. */
+    flush(): Promise<void>;
+    /** Sets external_id (your own stable, non-PII user id — not an email) on the
+     *  session and all events hereafter; emits one identify event. traits are
+     *  redacted before delivery. Fail-open: no-op if start() hasn't run or
+     *  externalId is empty. */
+    identify(externalId: string, traits?: Record<string, unknown>): void;
+    /** Tags the session with an experiment variant, attached to all events
+     *  hereafter as `experiments`. Pass a null/empty variant to clear the key. */
+    setExperiment(key: string, variant: string | null): void;
+    /** Uninstall capture, restoring the runtime's own fetch/XHR. */
+    stop(): void;
+};
+export declare const SDK_VERSION = "0.1.0";

package/dist/esm/index.js

@@ -0,0 +1,181 @@
+/**
+ * Drengr Analytics for JavaScript runtimes — Web, React Native, Electron.
+ * One call captures every fetch/XHR exchange (secret/PII redaction applied
+ * in-process before anything leaves the runtime) and ships it to your org's
+ * ingest endpoint under a publishable key.
+ *
+ *   import { Drengr } from 'drengr-js';
+ *   Drengr.start({
+ *     ingestUrl: 'https://<ref>.supabase.co/functions/v1/ingest',
+ *     publishableKey: 'drengr_pk_…',
+ *     appPackage: 'com.example.app',
+ *   });
+ */
+import { install, isInstalled, setEnabled, uninstall, } from './capture.js';
+import { IngestSink, defaultStorage } from './sink.js';
+export { IngestSink };
+export * as redact from './redact.js';
+const INSTALL_KEY = 'drengr_install_id';
+const OPTOUT_KEY = 'drengr_opt_out';
+let sink = null;
+let storageRef = null;
+function runtimeOs() {
+    try {
+        const nav = globalThis.navigator;
+        if (nav?.product === 'ReactNative')
+            return 'react-native';
+        const proc = globalThis.process;
+        if (proc?.versions?.electron)
+            return 'electron';
+        if (nav?.userAgent)
+            return 'web';
+        if (proc?.versions?.node)
+            return 'node';
+    }
+    catch { /* fall through */ }
+    return 'js';
+}
+function isThenable(v) {
+    return typeof v === 'object' && v !== null && typeof v.then === 'function';
+}
+function genId() {
+    try {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID();
+    }
+    catch { /* fall through */ }
+    return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+}
+export const Drengr = {
+    /** Install capture + delivery. Subsequent calls are ignored (stop() first). */
+    start(options) {
+        if (isInstalled())
+            return;
+        const storage = options.storage ?? defaultStorage();
+        storageRef = storage; // so optOut()/optIn() can persist the choice after start()
+        // A mutable context: on async storage (React Native's AsyncStorage) the
+        // install_id resolves after start() returns, so the sink reads it lazily and
+        // we backfill here before the first flush.
+        const context = {
+            app_package: options.appPackage,
+            os: runtimeOs(),
+            install_id: '', // filled sync (localStorage) or async (AsyncStorage) below
+            session_id: `s-${Date.now()}`,
+            sdk_version: SDK_VERSION,
+            ...options.context,
+        };
+        const s = new IngestSink({
+            url: options.ingestUrl,
+            publishableKey: options.publishableKey,
+            storage,
+            context,
+        });
+        sink = s;
+        // CONSENT-SAFE START. Sync storage (localStorage): read the opt-out NOW and
+        // fold it into startPaused so an opted-out user is paused BEFORE capture goes
+        // live — reading it a microtask later let same-tick requests leak. Async
+        // storage (RN AsyncStorage): can't read synchronously, so start PAUSED and
+        // enable only after the async read resolves (never if opted out).
+        const asyncStore = isThenable(storage.getItem(INSTALL_KEY));
+        const syncOptOut = !asyncStore && storage.getItem(OPTOUT_KEY) === '1';
+        const startPaused = options.enabled === false || asyncStore || syncOptOut;
+        // Always exclude our OWN ingest host: on React Native fetch is XHR-backed, so
+        // the pre-patch fetch the sink uses still routes through the patched XHR and
+        // would self-capture every delivery. Ignoring the host closes that loop.
+        const ignoreHosts = new Set((options.ignoreHosts ?? []).map((h) => h.toLowerCase()));
+        try {
+            const ih = new URL(options.ingestUrl).host;
+            if (ih)
+                ignoreHosts.add(ih.toLowerCase());
+        }
+        catch { /* malformed ingest URL: nothing to add */ }
+        install({
+            maxBodyBytes: options.maxBodyBytes,
+            captureWhen: options.captureWhen,
+            ignoreHosts,
+            redactHeaderNames: options.redactHeaders
+                ? new Set(options.redactHeaders.map((h) => h.toLowerCase()))
+                : undefined,
+            onEvent: (e) => {
+                try {
+                    options.onEvent?.(e);
+                }
+                catch { /* app callback must not break delivery */ }
+                s.addNetwork(e);
+            },
+        });
+        if (startPaused)
+            setEnabled(false);
+        // Resolve install_id + opt-out across BOTH sync and async storage.
+        void Promise.resolve(storage.getItem(INSTALL_KEY)).then((existing) => {
+            let id = typeof existing === 'string' && existing ? existing : '';
+            if (!id) {
+                id = genId();
+                try {
+                    void storage.setItem(INSTALL_KEY, id);
+                }
+                catch { /* memory-only ok */ }
+            }
+            context.install_id = id;
+        });
+        void Promise.resolve(storage.getItem(OPTOUT_KEY)).then((v) => {
+            if (v === '1') {
+                setEnabled(false); // opted out — stay paused regardless
+            }
+            else if (options.enabled !== false && !syncOptOut) {
+                setEnabled(true); // not opted out and not explicitly disabled — resume
+            }
+        });
+    },
+    /** Pause/resume capture (consent gate). Delivery of already-captured events continues. */
+    setEnabled(v) {
+        setEnabled(v);
+    },
+    /** Persistently opt this install OUT of capture (GDPR). Unlike setEnabled(false),
+     *  this survives restart: it writes the opt-out flag to storage AND pauses now, so
+     *  start() reads it and stays paused on the next launch. */
+    optOut() {
+        setEnabled(false);
+        try {
+            void storageRef?.setItem(OPTOUT_KEY, '1');
+        }
+        catch { /* memory-only ok */ }
+    },
+    /** Reverse optOut(): clear the persisted flag and resume capture. */
+    optIn() {
+        try {
+            void storageRef?.removeItem(OPTOUT_KEY);
+        }
+        catch { /* memory-only ok */ }
+        setEnabled(true);
+    },
+    /** Flush the queue now (e.g. before navigation). Best-effort. */
+    flush() {
+        return sink?.flush() ?? Promise.resolve();
+    },
+    /** Sets external_id (your own stable, non-PII user id — not an email) on the
+     *  session and all events hereafter; emits one identify event. traits are
+     *  redacted before delivery. Fail-open: no-op if start() hasn't run or
+     *  externalId is empty. */
+    identify(externalId, traits) {
+        try {
+            sink?.identify(externalId, traits);
+        }
+        catch { /* fail-open */ }
+    },
+    /** Tags the session with an experiment variant, attached to all events
+     *  hereafter as `experiments`. Pass a null/empty variant to clear the key. */
+    setExperiment(key, variant) {
+        try {
+            sink?.setExperiment(key, variant);
+        }
+        catch { /* fail-open */ }
+    },
+    /** Uninstall capture, restoring the runtime's own fetch/XHR. */
+    stop() {
+        uninstall();
+        sink = null;
+    },
+};
+export const SDK_VERSION = '0.1.0';

package/dist/esm/redact.d.ts

@@ -0,0 +1,18 @@
+export declare const redactMask = "[REDACTED]";
+/** Header names (lowercase) whose values are always masked. */
+export declare const sensitiveHeaders: Set<string>;
+/** Whether a header/query/field name denotes a secret. */
+export declare function isSensitiveName(name: string): boolean;
+/** Mask the values of sensitive headers; preserve every key. */
+export declare function redactHeaders(headers: Record<string, string>, extra?: Set<string>): Record<string, string>;
+/** Redact card numbers, JWTs, bearer tokens, cookie lines, and PII anywhere in a string. */
+export declare function scrubValues(s: string): string;
+/** Mask sensitive query/fragment params and scrub secrets in the path. */
+export declare function redactUrl(url: string): string;
+/** Mask values whose adjacent name is sensitive (see note above). Best-effort. */
+export declare function scrubNamedValues(s: string): string;
+/** Redact a body string: structurally (JSON keys / form fields) then by value. */
+export declare function redactBody(body: string): string;
+/** Project an already-redacted body into `dotted.path → scalar`, keeping only
+ *  analytics scalars (num/bool/short non-mask strings). Null when nothing safe remains. */
+export declare function projectBody(body: string | null | undefined): string | null;

package/dist/esm/redact.js

@@ -0,0 +1,341 @@
+// Secret + PII redaction for captured events (port of redact.dart): structural
+// key-masking + value-level scrubbing; best-effort, never throws (input unchanged).
+export const redactMask = '[REDACTED]';
+/** Header names (lowercase) whose values are always masked. */
+export const sensitiveHeaders = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'x-auth-token',
+    'x-api-key',
+    'x-access-token',
+    'x-session-token',
+    'x-secret',
+    'www-authenticate',
+    'proxy-authenticate',
+    'x-csrf-token',
+    'x-xsrf-token',
+]);
+/** Whole-name matches only — short tokens here so `pin` doesn't hit `shipping`. */
+const sensitiveExact = new Set([
+    'password', 'passwd', 'pwd', 'pass', 'passphrase', 'secret', 'token',
+    'authorization', 'pin', 'cvv', 'cvc', 'csc', 'cvv2', 'ssn', 'sin',
+    'otp', 'totp', 'iban',
+    // De-masked (3-tier policy): 'auth', 'pan', 'sig' — see the Dart source note.
+]);
+/** Longer fragments safe to match as substrings of a normalized name. */
+const sensitiveFragments = [
+    'token', 'secret', 'password', 'passphrase', 'apikey', 'apisecret',
+    'accesstoken', 'refreshtoken', 'idtoken', 'oauthtoken', 'privatekey',
+    'secretkey', 'sessiontoken', 'cardnumber', 'cardno', 'ccnumber',
+    'creditcard', 'accountnumber', 'routingnumber', 'sortcode',
+    // Rare-substring tokens as fragments to catch compounds (card_cvv, user_ssn); pin/pass/sin stay whole-name-only.
+    'cvv', 'cvc', 'cvv2', 'ssn', 'otp', 'totp', 'passphrase',
+    // Personal data (PII), redacted by default — 0-code means 0-code PII safety.
+    'email', 'phone', 'firstname', 'lastname', 'fullname', 'username',
+    'recipientname', 'customername', 'sendername', 'passport', 'nationality',
+    'address', 'birthdate', 'dateofbirth', 'promocode', 'promotioncode',
+    'messagetext', 'giftmessage',
+    // De-masked: 'sessionid' (correlation key, not a credential), 'signature'.
+];
+/** Whether a header/query/field name denotes a secret. */
+export function isSensitiveName(name) {
+    const n = name.toLowerCase().replace(/[_\-$@.\s]/g, '');
+    if (sensitiveExact.has(n))
+        return true;
+    for (const f of sensitiveFragments) {
+        if (n.includes(f))
+            return true;
+    }
+    return false;
+}
+/** Mask the values of sensitive headers; preserve every key. */
+export function redactHeaders(headers, extra = new Set()) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        const lk = k.toLowerCase();
+        out[k] = sensitiveHeaders.has(lk) || extra.has(lk) ? redactMask : v;
+    }
+    return out;
+}
+// --- value-level scrubbers (run over any text or URL) ---
+// 13+ digits with optional single space/dash separators between digits.
+const digitRun = /[0-9](?:[ -]?[0-9]){11,}/g;
+const jwtRe = /eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]*/g;
+const bearerRe = /[Bb]earer\s+[A-Za-z0-9\-._~+/]+=*/g;
+const cookieLineRe = /^(set-cookie|cookie)\s*:\s*.*$/gim;
+// Free-text PII by VALUE PATTERN (audit blocker #1). Phone needs separators so bare id/timestamp runs aren't hit.
+const emailRe = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const ssnRe = /\b\d{3}-\d{2}-\d{4}\b/g;
+const phoneRe = /(?:\+\d{1,3}[ .-]?)?\(?\d{3}\)?[ .-]\d{3}[ .-]\d{4}\b/g;
+// Well-known opaque SECRETS by unambiguous vendor prefix — catches a key under a
+// benign field name (name-masking misses). Zero-FP by anchoring on the prefix.
+const secretTokenRe = /\b(?:(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35}|gh[opusr]_[A-Za-z0-9]{36,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g;
+// PEM private key block (catastrophic if shipped).
+const pemRe = /-----BEGIN[A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z0-9 ]*PRIVATE KEY-----/g;
+function luhn(digits) {
+    if (digits.length < 13)
+        return false;
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = digits.charCodeAt(i) - 48;
+        if (n < 0 || n > 9)
+            return false;
+        if (alt) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+/** Redact card numbers, JWTs, bearer tokens, cookie lines, and PII anywhere in a string. */
+export function scrubValues(s) {
+    let out = s.replace(digitRun, (m) => {
+        const digits = m.replace(/[ -]/g, '');
+        if (digits.length > 40)
+            return '[REDACTED-PAN]'; // suspicious + bounds work
+        for (let len = 13; len <= 19 && len <= digits.length; len++) {
+            for (let i = 0; i + len <= digits.length; i++) {
+                if (luhn(digits.substring(i, i + len)))
+                    return '[REDACTED-PAN]';
+            }
+        }
+        return m;
+    });
+    out = out.replace(jwtRe, '[REDACTED-JWT]');
+    out = out.replace(bearerRe, `Bearer ${redactMask}`);
+    out = out.replace(cookieLineRe, (_m, p1) => `${p1}: ${redactMask}`);
+    out = out.replace(emailRe, '[REDACTED-EMAIL]');
+    out = out.replace(ssnRe, '[REDACTED-SSN]');
+    out = out.replace(phoneRe, '[REDACTED-PHONE]');
+    out = out.replace(secretTokenRe, '[REDACTED-SECRET]');
+    out = out.replace(pemRe, '[REDACTED-KEY]');
+    return out;
+}
+/** Mask sensitive query/fragment params and scrub secrets in the path. */
+export function redactUrl(url) {
+    try {
+        let result = url;
+        let u = null;
+        let relative = false;
+        try {
+            u = new URL(url);
+        }
+        catch {
+            // Relative URL: parse against a dummy base so query/fragment masking runs, then strip it — else params leak.
+            try {
+                u = new URL(url, 'http://drengr.invalid');
+                relative = true;
+            }
+            catch {
+                u = null;
+            }
+        }
+        if (u) {
+            if (u.search.length > 1) {
+                const params = new URLSearchParams(u.search);
+                const masked = new URLSearchParams();
+                for (const [k, v] of params) {
+                    masked.append(k, isSensitiveName(k) ? redactMask : v);
+                }
+                u.search = masked.toString();
+            }
+            const frag = u.hash.startsWith('#') ? u.hash.slice(1) : u.hash;
+            if (frag.includes('=')) {
+                const newFrag = frag
+                    .split('&')
+                    .map((pair) => {
+                    const i = pair.indexOf('=');
+                    if (i > 0 && isSensitiveName(pair.substring(0, i))) {
+                        return `${pair.substring(0, i)}=${redactMask}`;
+                    }
+                    return pair;
+                })
+                    .join('&');
+                u.hash = `#${newFrag}`;
+            }
+            result = relative ? u.toString().slice('http://drengr.invalid'.length) : u.toString();
+        }
+        return scrubValues(result);
+    }
+    catch {
+        return url;
+    }
+}
+// Mask a value whenever its adjacent NAME is sensitive — for bodies key-masking
+// can't reach (JSON truncated past the cap, XML/SOAP) and inline literals in a
+// parsed JSON string (GraphQL `query`). Value stops at any backslash/quote so a
+// JSON-wrapped literal matches the INNERMOST name:"value" pair. Bounded → no ReDoS.
+// escNamed runs FIRST (anchored on the escaped quote) so a plain-quote wrapper
+// can't shadow the first inner literal.
+const escNamedRe = /([A-Za-z][A-Za-z0-9_.\-]{0,63})(\s*[:=]\s*)\\"[^"\\]{0,8192}\\"/g;
+const dqNamedRe = /(["']?)([A-Za-z][A-Za-z0-9_.\-]{0,63})\1(\s*[:=]\s*\\?")[^"\\]{0,8192}(\\?")/g;
+const sqNamedRe = /(["']?)([A-Za-z][A-Za-z0-9_.\-]{0,63})\1(\s*[:=]\s*\\?')[^'\\]{0,8192}(\\?')/g;
+// XML element text: <name>value</name>
+const xmlElemRe = /<([A-Za-z][A-Za-z0-9_.\-:]{0,63})>[^<]{0,8192}<\/\1\s*>/g;
+// Bare numeric/bool under a quoted JSON key ("cvv":123) — value-scrubbing skips short digit runs, so it'd leak.
+const jsonNumRe = /("[A-Za-z][A-Za-z0-9_.\-]{0,63}"\s*:\s*)(-?\d[\d.eE+\-]{0,40}|true|false)/g;
+/** Mask values whose adjacent name is sensitive (see note above). Best-effort. */
+export function scrubNamedValues(s) {
+    let out = s.replace(escNamedRe, (m, name, sep) => isSensitiveName(name) ? `${name}${sep}\\"${redactMask}\\"` : m);
+    out = out.replace(dqNamedRe, (m, q, name, sep, close) => isSensitiveName(name) ? `${q}${name}${q}${sep}${redactMask}${close}` : m);
+    out = out.replace(sqNamedRe, (m, q, name, sep, close) => isSensitiveName(name) ? `${q}${name}${q}${sep}${redactMask}${close}` : m);
+    out = out.replace(xmlElemRe, (m, name) => isSensitiveName(name) ? `<${name}>${redactMask}</${name}>` : m);
+    out = out.replace(jsonNumRe, (m, head, _val) => {
+        const name = head.slice(1, head.indexOf('"', 1));
+        return isSensitiveName(name) ? `${head}${redactMask}` : m;
+    });
+    return out;
+}
+/** Redact a body string: structurally (JSON keys / form fields) then by value. */
+export function redactBody(body) {
+    try {
+        const decoded = tryJson(body);
+        let out;
+        if (decoded !== undefined)
+            out = scrubValues(JSON.stringify(redactJson(decoded)));
+        else if (looksFormEncoded(body))
+            out = scrubValues(redactFormEncoded(body));
+        else
+            out = scrubValues(body);
+        // Net values sensitive by NAME that survived structural + value passes. See scrubNamedValues.
+        return scrubNamedValues(out);
+    }
+    catch {
+        return body;
+    }
+}
+function tryJson(body) {
+    const t = body.trimStart();
+    if (t.length === 0 || (t[0] !== '{' && t[0] !== '['))
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function redactJson(v) {
+    if (Array.isArray(v))
+        return v.map(redactJson);
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            out[k] = isSensitiveName(k) ? redactMask : redactJson(val);
+        }
+        return out;
+    }
+    return v;
+}
+function looksFormEncoded(body) {
+    if (!body.includes('=') || body.includes('\n') || body.includes(' '))
+        return false;
+    return /^[^=&]+=[^&]*(?:&[^=&]+=[^&]*)*$/.test(body);
+}
+function redactFormEncoded(body) {
+    return body
+        .split('&')
+        .map((pair) => {
+        const i = pair.indexOf('=');
+        if (i <= 0)
+            return pair;
+        const key = pair.substring(0, i);
+        let name = key;
+        try {
+            name = decodeURIComponent(key.replace(/\+/g, ' '));
+        }
+        catch {
+            /* keep raw */
+        }
+        if (isSensitiveName(name))
+            return `${key}=${redactMask}`;
+        // Scrub the DECODED value — else an encoded value slips the outer scrubValues and projectBody ships the secret.
+        let val = pair.substring(i + 1);
+        try {
+            val = decodeURIComponent(val.replace(/\+/g, ' '));
+        }
+        catch {
+            /* keep raw */
+        }
+        return `${key}=${scrubValues(val)}`;
+    })
+        .join('&');
+}
+// --- safe projection (the annotatable DTO shipped to the server) ---
+const projMaxKeys = 512;
+const projMaxDepth = 12;
+const projMaxStrLen = 1024;
+/** Project an already-redacted body into `dotted.path → scalar`, keeping only
+ *  analytics scalars (num/bool/short non-mask strings). Null when nothing safe remains. */
+export function projectBody(body) {
+    if (!body)
+        return null;
+    const decoded = tryJson(body) ?? tryForm(body);
+    if (decoded === undefined || decoded === null)
+        return null;
+    const out = {};
+    try {
+        flatten('', decoded, out, 0);
+        if (Object.keys(out).length === 0)
+            return null;
+        return JSON.stringify(out);
+    }
+    catch {
+        return null;
+    }
+}
+function tryForm(body) {
+    if (!looksFormEncoded(body))
+        return undefined;
+    const map = {};
+    for (const pair of body.split('&')) {
+        const i = pair.indexOf('=');
+        if (i <= 0)
+            continue;
+        let k = pair.substring(0, i);
+        let v = pair.substring(i + 1);
+        try {
+            k = decodeURIComponent(k.replace(/\+/g, ' '));
+        }
+        catch { /* keep raw */ }
+        try {
+            v = decodeURIComponent(v.replace(/\+/g, ' '));
+        }
+        catch { /* keep raw */ }
+        map[k] = v;
+    }
+    return Object.keys(map).length === 0 ? undefined : map;
+}
+function flatten(prefix, v, out, depth) {
+    if (Object.keys(out).length >= projMaxKeys || depth > projMaxDepth)
+        return;
+    if (Array.isArray(v)) {
+        for (let i = 0; i < v.length && Object.keys(out).length < projMaxKeys; i++) {
+            flatten(prefix === '' ? `${i}` : `${prefix}.${i}`, v[i], out, depth + 1);
+        }
+    }
+    else if (v !== null && typeof v === 'object') {
+        for (const [k, val] of Object.entries(v)) {
+            if (Object.keys(out).length < projMaxKeys) {
+                flatten(prefix === '' ? k : `${prefix}.${k}`, val, out, depth + 1);
+            }
+        }
+    }
+    else if (typeof v === 'string') {
+        if (v.length === 0 || v.length > projMaxStrLen)
+            return;
+        if (v.startsWith('[REDACTED'))
+            return; // redactor dropped it — no signal
+        out[prefix] = v;
+    }
+    else if (typeof v === 'number' || typeof v === 'boolean') {
+        out[prefix] = v;
+    }
+    // null / other types: skip
+}

package/dist/esm/sink.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Batches captured signals and ships them to the Drengr ingest endpoint,
+ * authenticated by a publishable key. Port of the proven Dart IngestSink,
+ * carrying both device-run lessons from birth:
+ *  - delivery uses the PRE-PATCH fetch (structurally invisible to capture —
+ *    the self-capture loop cannot exist);
+ *  - the persistence scheduler uses the writer-loops-until-clean pattern
+ *    (an overlap marks dirty and returns; never reschedules a microtask,
+ *    which starved the event loop and froze the Flutter demo).
+ *
+ * Best-effort and non-blocking: never throws into the app, drops oldest on
+ * overflow, retries with exponential backoff + full jitter, persists the
+ * queue through a pluggable storage adapter (localStorage on web,
+ * AsyncStorage-compatible on React Native, in-memory fallback anywhere).
+ */
+import { type NetworkEvent } from './capture.js';
+/** Minimal async-tolerant KV storage. localStorage satisfies it directly;
+ *  React Native's AsyncStorage satisfies it via its promise API. */
+export interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+export interface IngestSinkOptions {
+    /** Full ingest URL, e.g. https://<ref>.supabase.co/functions/v1/ingest */
+    url: string;
+    /** Publishable key (drengr_pk_…) sent as Authorization: Bearer. */
+    publishableKey: string;
+    /** Shared envelope context (app_package, os, install_id, session_id, …). */
+    context: Record<string, unknown>;
+    storage?: StorageAdapter;
+    maxBatch?: number;
+    maxQueue?: number;
+    flushIntervalMs?: number;
+}
+export declare function defaultStorage(): StorageAdapter;
+export declare class IngestSink {
+    private readonly url;
+    private readonly key;
+    private readonly context;
+    private readonly storage;
+    private readonly maxBatch;
+    private readonly maxQueue;
+    private readonly flushIntervalMs;
+    private queue;
+    private timer;
+    private sending;
+    private retries;
+    private persistScheduled;
+    private persisting;
+    private persistDirty;
+    private externalId;
+    private experiments;
+    constructor(opts: IngestSinkOptions);
+    /** Map a captured exchange to an ingest event and enqueue it. */
+    addNetwork: (e: NetworkEvent) => void;
+    /** Sets the session's external_id (attached to every event hereafter) and emits
+     *  one identify event. traits go through the same redact+project pipeline as
+     *  bodies. Fail-open: invalid externalId is a no-op. */
+    identify: (externalId: string, traits?: Record<string, unknown>) => void;
+    /** Sets/clears a session-scoped experiment variant (attached to every event
+     *  hereafter as `experiments`). variant null/empty clears the key. Fail-open. */
+    setExperiment: (key: string, variant: string | null | undefined) => void;
+    private toNet;
+    private enqueue;
+    flush(): Promise<void>;
+    private armBackoff;
+    private schedulePersist;
+    private persist;
+    private restore;
+}