drengr-js 0.1.0

package/dist/esm/sink.js

@@ -0,0 +1,271 @@
+/**
+ * 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 { nativeFetch, projectBody } from './capture.js';
+import { redactBody } from './redact.js';
+const QUEUE_KEY = 'drengr_queue_v1';
+const BASE_BACKOFF_MS = 2000;
+const MAX_BACKOFF_MS = 5 * 60000;
+export function defaultStorage() {
+    try {
+        const ls = globalThis.localStorage;
+        if (ls) {
+            const probe = '__drengr_probe__';
+            ls.setItem(probe, '1');
+            ls.removeItem(probe);
+            return ls;
+        }
+    }
+    catch { /* private mode / RN / node — fall through */ }
+    const mem = new Map();
+    return {
+        getItem: (k) => mem.get(k) ?? null,
+        setItem: (k, v) => void mem.set(k, v),
+        removeItem: (k) => void mem.delete(k),
+    };
+}
+export class IngestSink {
+    constructor(opts) {
+        this.queue = [];
+        this.timer = null;
+        this.sending = false;
+        this.retries = 0;
+        this.persistScheduled = false;
+        this.persisting = false;
+        this.persistDirty = false;
+        this.experiments = {};
+        /** Map a captured exchange to an ingest event and enqueue it. */
+        this.addNetwork = (e) => {
+            try {
+                this.enqueue(this.toNet(e));
+            }
+            catch { /* never throw into the app */ }
+        };
+        /** 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. */
+        this.identify = (externalId, traits) => {
+            if (typeof externalId !== 'string' || externalId.length === 0)
+                return;
+            let redactedTraits = null;
+            try {
+                if (traits)
+                    redactedTraits = projectBody(redactBody(JSON.stringify(traits)));
+            }
+            catch { /* bad traits: ship identify without them */ }
+            try {
+                this.externalId = externalId;
+                this.enqueue({
+                    kind: 'identify',
+                    event_id: randomId(),
+                    ts_ms: Date.now(),
+                    external_id: externalId,
+                    ...(redactedTraits != null ? { traits: redactedTraits } : {}),
+                });
+            }
+            catch { /* never throw into the app */ }
+        };
+        /** Sets/clears a session-scoped experiment variant (attached to every event
+         *  hereafter as `experiments`). variant null/empty clears the key. Fail-open. */
+        this.setExperiment = (key, variant) => {
+            try {
+                if (typeof key !== 'string' || key.length === 0)
+                    return;
+                if (!variant)
+                    delete this.experiments[key];
+                else
+                    this.experiments[key] = variant;
+            }
+            catch { /* never throw into the app */ }
+        };
+        this.url = opts.url;
+        this.key = opts.publishableKey;
+        this.context = opts.context;
+        this.storage = opts.storage ?? defaultStorage();
+        this.maxBatch = opts.maxBatch ?? 50;
+        this.maxQueue = opts.maxQueue ?? 500;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 10000;
+        void this.restore();
+    }
+    toNet(e) {
+        const status = e.statusCode ?? 0;
+        const failed = e.errorText != null || status >= 400;
+        const reqBody = projectBody(e.requestBody);
+        const respBody = projectBody(e.responseBody);
+        return {
+            kind: failed ? 'net_fail' : 'net',
+            event_id: randomId(),
+            ts_ms: e.timestampMs,
+            method: e.method,
+            url: e.url, // already redacted by the capture layer
+            status,
+            error_kind: failed
+                ? e.errorText != null
+                    ? 'transport'
+                    : status >= 500
+                        ? 'server'
+                        : 'client'
+                : '',
+            duration_ms: e.durationMs,
+            req_bytes: e.requestBodyBytes,
+            resp_bytes: e.responseBodyBytes,
+            ...(reqBody != null ? { req_body: reqBody } : {}),
+            ...(respBody != null ? { body: respBody } : {}),
+        };
+    }
+    enqueue(ev) {
+        this.queue.push(ev);
+        while (this.queue.length > this.maxQueue) {
+            this.queue.shift(); // drop oldest on overflow — never block
+        }
+        this.schedulePersist();
+        if (this.retries > 0)
+            return; // backoff timer drives the flush
+        if (this.queue.length >= this.maxBatch) {
+            void this.flush();
+        }
+        else if (this.timer == null) {
+            this.timer = setTimeout(() => void this.flush(), this.flushIntervalMs);
+        }
+    }
+    async flush() {
+        if (this.timer != null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.sending || this.queue.length === 0)
+            return;
+        this.sending = true;
+        const batch = this.queue.splice(0, 1000);
+        // sent_at_ms = device clock AT SEND: the server derives clock error from it
+        // and corrects timeline placement exactly. Set per attempt.
+        const envelope = { ...this.context, sent_at_ms: Date.now(), events: batch };
+        if (this.externalId)
+            envelope.external_id = this.externalId;
+        if (Object.keys(this.experiments).length > 0)
+            envelope.experiments = { ...this.experiments };
+        let acked = false;
+        let permanent = false;
+        try {
+            // nativeFetch: the pre-patch fetch — delivery is invisible to capture.
+            const resp = await nativeFetch()(this.url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.key}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(envelope),
+                keepalive: batch.length < 30, // survive page unload for small batches
+            });
+            acked = resp.status >= 200 && resp.status < 300;
+            // A non-retriable 4xx (revoked key 401, bad batch 400/413) will never
+            // succeed — retrying it forever head-of-line-blocks the queue and drops all
+            // newer events. Drop it. 429/408 are transient and still retry.
+            permanent = resp.status >= 400 && resp.status < 500 && resp.status !== 429 && resp.status !== 408;
+        }
+        catch {
+            acked = false; // best-effort: never throw into the app
+        }
+        finally {
+            this.sending = false;
+            if (acked || permanent) {
+                this.retries = 0; // batch consumed (delivered or dropped as permanent)
+                this.schedulePersist();
+                if (this.queue.length > 0 && this.timer == null) {
+                    this.timer = setTimeout(() => void this.flush(), this.flushIntervalMs);
+                }
+            }
+            else {
+                // Keep the batch: requeue at the front, shed newest on overflow.
+                this.queue.unshift(...batch);
+                while (this.queue.length > this.maxQueue)
+                    this.queue.pop();
+                this.schedulePersist();
+                this.armBackoff();
+            }
+        }
+    }
+    armBackoff() {
+        if (this.timer != null)
+            clearTimeout(this.timer);
+        const exp = BASE_BACKOFF_MS * 2 ** Math.min(this.retries, 20);
+        const capped = Math.min(exp, MAX_BACKOFF_MS);
+        const delay = BASE_BACKOFF_MS + Math.floor(Math.random() * capped);
+        this.retries++;
+        this.timer = setTimeout(() => void this.flush(), delay);
+    }
+    // --- persistence (writer-loops-until-clean; overlap marks dirty) ---
+    schedulePersist() {
+        if (this.persistScheduled)
+            return;
+        this.persistScheduled = true;
+        queueMicrotask(() => void this.persist());
+    }
+    async persist() {
+        this.persistScheduled = false;
+        if (this.persisting) {
+            this.persistDirty = true; // the in-flight writer re-snapshots
+            return;
+        }
+        this.persisting = true;
+        try {
+            do {
+                this.persistDirty = false;
+                if (this.queue.length === 0) {
+                    await this.storage.removeItem(QUEUE_KEY);
+                }
+                else {
+                    await this.storage.setItem(QUEUE_KEY, JSON.stringify(this.queue));
+                }
+            } while (this.persistDirty);
+        }
+        catch { /* best-effort */ }
+        finally {
+            this.persisting = false;
+        }
+    }
+    async restore() {
+        try {
+            const raw = await this.storage.getItem(QUEUE_KEY);
+            if (!raw)
+                return;
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                for (const ev of parsed) {
+                    if (ev && typeof ev === 'object')
+                        this.queue.push(ev);
+                }
+                while (this.queue.length > this.maxQueue)
+                    this.queue.shift();
+                if (this.queue.length > 0 && this.timer == null) {
+                    this.timer = setTimeout(() => void this.flush(), this.flushIntervalMs);
+                }
+            }
+        }
+        catch { /* corrupt/missing store: start empty */ }
+    }
+}
+function randomId() {
+    try {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID().replace(/-/g, '');
+    }
+    catch { /* fall through */ }
+    let out = '';
+    for (let i = 0; i < 32; i++)
+        out += Math.floor(Math.random() * 16).toString(16);
+    return out;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "drengr-js",
+  "version": "0.1.0",
+  "description": "Zero-code network analytics for JavaScript runtimes (Web, React Native, Electron) \u2014 one call captures every fetch/XHR exchange with secret/PII redaction in-process, no track() calls.",
+  "license": "Apache-2.0",
+  "homepage": "https://drengr.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SharminSirajudeen/drengr-community.git"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "network",
+    "observability",
+    "fetch",
+    "xhr",
+    "react-native",
+    "electron",
+    "redaction"
+  ],
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^24.0.0"
+  }
+}