@bravely-studios/account-web 0.4.1 → 0.5.0

package/dist/error-firehose-client.js

@@ -0,0 +1,823 @@
+// Error Firehose Client — Phase 2 (bravely-account-web)
+//
+// Implements the client-side error telemetry pipeline as specified in
+// SYNTHESIS.md §A-§E (DECISIONS-LOCKED.md 2026-06-13).
+//
+// PUBLIC API
+//   ErrorFirehoseClient.instance(config)   — get/init the singleton
+//   ErrorFirehoseClient.observe(...)        — side-tap from the facade
+//   ErrorFirehoseClient.getConsent()        — read consent state
+//   ErrorFirehoseClient.setConsent(bool)    — write consent (true=on)
+//   ErrorFirehoseClient.shouldShowOptOutNote() — one-time note gate
+//   ErrorFirehoseClient.ackOptOutNote()     — mark note shown
+//   ErrorFirehoseClient.flush()             — force a flush (testing / shutdown)
+//
+// Key design decisions (spec refs):
+//   §B  fingerprint = SHA-256(slug|platform|severity|category|normalizedMsg|frameDigest)[:16]
+//   §C  CoalescingBuffer: 60s window OR 50 distinct fps, per-fp circuit-breaker >100/10s→5min silence
+//   §C  Global cap 50 distinct fps/60s; overflow → synthetic client.overflow event
+//   §D  Consent key bravely.error_telemetry_enabled (default false until geo resolution)
+//   §E  POST identity.bravely.dev/api/error-events, no auth header, backoff 30/60/120s ±10s
+import { getOrMintInstallId } from "./installMetrics.js";
+import { defaultStorage } from "./storage.js";
+/** Simple in-memory ConsentStorage shim for test environments. */
+export function memoryConsentStorage() {
+    const m = new Map();
+    return {
+        getItem: (k) => m.get(k) ?? null,
+        setItem: (k, v) => { m.set(k, v); },
+        removeItem: (k) => { m.delete(k); },
+    };
+}
+// ---- Consent storage keys (§D) ---------------------------------------------
+export const CONSENT_KEY = "bravely.error_telemetry_enabled";
+export const OPT_OUT_SHOWN_KEY = "bravely.error_telemetry_opt_out_shown";
+export const GEO_CACHE_KEY = "bravely.error_geo_eu";
+export const OPT_IN_SHOWN_KEY = "bravely.error_telemetry_opt_in_shown";
+export const GEO_PROBE_URL = "https://identity.bravely.dev/api/geo";
+const ENDPOINT = "https://identity.bravely.dev/api/error-events";
+// ---- Normalization + fingerprinting (§B) -----------------------------------
+/** 7-pattern scrubber — strip PII before buffering. */
+export function redactMessage(msg) {
+    return msg
+        // ba_-prefixed IDs
+        .replace(/\bba_[A-Za-z0-9_-]{1,128}/g, "ba_[redacted]")
+        // UUIDs
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "[uuid]")
+        // ISO-8601 timestamps
+        .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g, "[ts]")
+        // Hex strings >=8 chars (token-like)
+        .replace(/\b[0-9a-f]{8,}\b/gi, "[hex]")
+        // Integers >=4 digits
+        .replace(/\b\d{4,}\b/g, "[int]")
+        // Absolute paths (Unix/Windows)
+        .replace(/(?:\/(?:[a-zA-Z0-9_.-]+\/)+[a-zA-Z0-9_.-]*|[A-Za-z]:\\(?:[^\\/:*?"<>|\r\n]+\\)*[^\\/:*?"<>|\r\n]*)/g, "[path]")
+        // Email addresses
+        .replace(/[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/g, "[email]");
+}
+/**
+ * Normalize a message for fingerprinting (§B):
+ *   strip hex>=8, UUIDs, ints>=4 digits, ISO timestamps, ba_ ids, abs paths,
+ *   lowercase, collapse whitespace.
+ */
+export function normalizeForFingerprint(msg) {
+    let s = redactMessage(msg);
+    s = s.toLowerCase();
+    s = s.replace(/\s+/g, " ").trim();
+    return s;
+}
+/** Compute SHA-256 and return the first `len` hex chars. */
+async function sha256Hex(input, len) {
+    const c = globalThis.crypto;
+    if (c?.subtle) {
+        const enc = new TextEncoder();
+        const buf = await c.subtle.digest("SHA-256", enc.encode(input));
+        const hex = Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+        return hex.slice(0, len);
+    }
+    // Fallback: djb2 hash (deterministic, non-cryptographic) when SubtleCrypto is absent.
+    let h = 5381;
+    for (let i = 0; i < input.length; i++)
+        h = ((h << 5) + h) ^ input.charCodeAt(i);
+    const unsigned = (h >>> 0).toString(16).padStart(8, "0");
+    // Extend to requested length by repeating/hashing the input segments.
+    let full = unsigned;
+    let seed = input + unsigned;
+    while (full.length < len) {
+        let h2 = 5381;
+        for (let i = 0; i < seed.length; i++)
+            h2 = ((h2 << 5) + h2) ^ seed.charCodeAt(i);
+        full += (h2 >>> 0).toString(16).padStart(8, "0");
+        seed = full;
+    }
+    return full.slice(0, len);
+}
+/**
+ * Compute the daily_token for the given install_id.
+ * daily_token = sha256(install_id + "|" + UTC_date(YYYY-MM-DD) + "|" + "bravely-error-v1")[:16 hex]
+ *
+ * - Same device same UTC day → same token (daily-distinct + rate-limit)
+ * - Cannot correlate across days (different date → different token)
+ * - Cannot reverse to install_id (SHA-256 is one-way, high-entropy input)
+ * - install_id NEVER leaves the device
+ */
+export async function computeDailyToken(installId, utcDate) {
+    const date = utcDate ?? new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const input = installId + "|" + date + "|" + "bravely-error-v1";
+    return sha256Hex(input, 16);
+}
+/**
+ * Compute the 16-char fingerprint per §B.
+ *
+ * fingerprint = SHA-256(app_slug|platform|severity|category|normalizedMsg|frameDigest)[:16]
+ *
+ * Over-grouping protection: category is always in the key.
+ * Under-grouping: integer stripping means "failed after 3 retries" and
+ *   "failed after 847 retries" get the same normalized template.
+ * Short-message guard: if normalized result is <8 chars, append exception_type.
+ */
+export async function computeFingerprint(opts) {
+    let norm = normalizeForFingerprint(opts.message);
+    if (norm.length < 8 && opts.exception_type) {
+        norm = norm + " " + opts.exception_type.toLowerCase();
+    }
+    const key = [
+        opts.app_slug,
+        opts.platform,
+        opts.severity,
+        opts.category,
+        norm,
+        opts.frame_digest ?? "",
+    ].join("|");
+    return sha256Hex(key, 16);
+}
+/** Compute frame_digest: SHA-256[:12] of top-3 normalized frame symbols (no line numbers). */
+export async function computeFrameDigest(frames) {
+    const normalized = frames.slice(0, 3).map((f) => 
+    // strip line numbers like :42 or (42) or L42
+    f.replace(/(?::\d+|\(\d+\)|L\d+)\s*$/g, "").trim());
+    return sha256Hex(normalized.join("|"), 12);
+}
+/**
+ * Probe the geo endpoint once and cache the eu flag in consentStorage.
+ * - Makes ONE anonymous GET request to /api/geo (no PII, no body, stores nothing server-side)
+ * - Caches the eu flag in consentStorage under GEO_CACHE_KEY
+ * - On network failure, falls back to OS/browser locale heuristic (EU locale → eu=true)
+ * - Returns { country, eu } — never throws
+ */
+export async function probeGeo(consentStorage, probeUrlOverride) {
+    // Check cache first
+    try {
+        const cached = consentStorage.getItem(GEO_CACHE_KEY);
+        if (cached !== null) {
+            return JSON.parse(cached);
+        }
+    }
+    catch {
+        // cache miss or parse error — proceed to probe
+    }
+    // Try the network probe
+    try {
+        const url = probeUrlOverride ?? GEO_PROBE_URL;
+        const res = await fetch(url, { method: "GET" });
+        if (res.ok) {
+            const data = (await res.json());
+            // Cache result
+            try {
+                consentStorage.setItem(GEO_CACHE_KEY, JSON.stringify(data));
+            }
+            catch {
+                // storage unavailable — no-op
+            }
+            return data;
+        }
+    }
+    catch {
+        // network failure — fall through to locale fallback
+    }
+    // Offline fallback: use browser/OS locale as a conservative proxy
+    const euCountryCodes = new Set([
+        "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GR", "HR", "HU",
+        "IE", "IT", "LT", "LU", "LV", "MT", "NL", "PL", "PT", "RO", "SE", "SI", "SK",
+        // EEA
+        "IS", "LI", "NO",
+        // UK
+        "GB",
+    ]);
+    let country = "XX";
+    try {
+        // navigator.language gives e.g. "en-GB", "de-DE", "fr-FR"
+        if (typeof navigator !== "undefined" && navigator.language) {
+            const parts = navigator.language.split("-");
+            if (parts.length >= 2)
+                country = parts[parts.length - 1].toUpperCase();
+        }
+    }
+    catch {
+        // SSR or restricted — country stays XX
+    }
+    const euFallback = euCountryCodes.has(country);
+    const result = { country, eu: euFallback };
+    try {
+        consentStorage.setItem(GEO_CACHE_KEY, JSON.stringify(result));
+    }
+    catch {
+        // no-op
+    }
+    return result;
+}
+/**
+ * Resolve and persist the consent default for a new install.
+ *
+ * Call ONCE on first launch, BEFORE any observe() call.
+ * - If the user has already made a choice (CONSENT_KEY is set), does nothing.
+ * - Otherwise: probes geo, sets the default (EU→false, non-EU→true),
+ *   and returns whether an opt-in prompt should be shown to the user.
+ *
+ * EU flow (eu=true):
+ *   - default = OFF (consent NOT set / left at null → no data transmitted)
+ *   - shouldShowOptIn = true → host should show:
+ *     "Help improve <AppName> with anonymous error reports? [Enable] [Not now]"
+ *   - When user clicks Enable: call setConsent(true); ackOptInPrompt()
+ *   - When user clicks Not now: call ackOptInPrompt() (consent stays off)
+ *
+ * Non-EU flow (eu=false):
+ *   - default = ON (consent set to "true")
+ *   - shouldShowOptIn = false
+ *   - shouldShowOptOutNote() on the client returns true → show graceful opt-out note
+ *     (this is the existing OPT_OUT_SHOWN_KEY / ackOptOutNote() path)
+ */
+export async function resolveConsentDefault(consentStorage, probeUrlOverride) {
+    // If user already made a choice, respect it
+    try {
+        const existing = consentStorage.getItem(CONSENT_KEY);
+        if (existing !== null) {
+            // Already resolved; just return current state for the host
+            const geo = await probeGeo(consentStorage, probeUrlOverride);
+            return { eu: geo.eu, shouldShowOptIn: false };
+        }
+    }
+    catch {
+        // storage error — treat as no prior choice
+    }
+    const geo = await probeGeo(consentStorage, probeUrlOverride);
+    if (geo.eu) {
+        // EU: do NOT set consent (stays null = off); host must show opt-in prompt
+        return { eu: true, shouldShowOptIn: true };
+    }
+    else {
+        // Non-EU: default ON
+        try {
+            consentStorage.setItem(CONSENT_KEY, "true");
+        }
+        catch {
+            // no-op
+        }
+        return { eu: false, shouldShowOptIn: false };
+    }
+}
+/**
+ * Record that the one-time EU opt-in prompt has been shown.
+ * Call after showing the opt-in dialog regardless of the user's choice.
+ */
+export function ackOptInPrompt(consentStorage) {
+    try {
+        consentStorage.setItem(OPT_IN_SHOWN_KEY, "true");
+    }
+    catch {
+        // no-op
+    }
+}
+/**
+ * True iff the one-time EU opt-in prompt has NOT yet been shown.
+ */
+export function shouldShowOptInPrompt(consentStorage) {
+    try {
+        return consentStorage.getItem(OPT_IN_SHOWN_KEY) !== "true";
+    }
+    catch {
+        return false;
+    }
+}
+// ---- UUID helper ------------------------------------------------------------
+function mintUuid() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function")
+        return c.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (c && typeof c.getRandomValues === "function") {
+        c.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// ---- ErrorFirehoseClient singleton ------------------------------------------
+/** Max distinct fingerprints per 60s window. */
+const MAX_DISTINCT_FP = 50;
+/** Flush interval in ms. */
+const FLUSH_INTERVAL_MS = 60_000;
+/** Max batch size (events). */
+const MAX_BATCH_EVENTS = 50;
+/** Max batch size (bytes). */
+const MAX_BATCH_BYTES = 256 * 1024;
+/** Max pending batches in the in-memory queue. */
+const MAX_PENDING_BATCHES = 10;
+/** Per-fingerprint circuit-breaker: window duration. */
+const CB_WINDOW_MS = 10_000;
+/** Per-fingerprint circuit-breaker: trip threshold per window. */
+const CB_TRIP_COUNT = 100;
+/** Per-fingerprint circuit-breaker: silence duration. */
+const CB_SILENCE_MS = 5 * 60_000;
+/** Backoff schedule (ms before jitter). */
+const BACKOFF_MS = [30_000, 60_000, 120_000];
+/** Jitter range ±ms. */
+const JITTER_MS = 10_000;
+export class ErrorFirehoseClient {
+    static _instance = null;
+    cfg;
+    storage;
+    consentStore;
+    /** fingerprint → CoalescedEntry */
+    buffer = new Map();
+    /** Count of distinct fingerprints admitted in the current window (excl. overflow). */
+    windowFpCount = 0;
+    /** Overflow accumulator: count of fps dropped due to the global cap. */
+    overflowDropped = 0;
+    /** Wall-clock start of the current 60s window. */
+    windowStart = 0;
+    /** Timer handle for the flush interval. */
+    flushTimer = null;
+    /** Pending batch queue (in-memory only, NOT persisted). */
+    pendingQueue = [];
+    /** True when a flush/drain cycle is running. */
+    flushing = false;
+    /** Cached daily_token for the current UTC date. */
+    _cachedDailyToken = null;
+    _cachedDailyTokenDate = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.storage = cfg.storage ?? defaultStorage();
+        this.consentStore = cfg.consentStorage ?? defaultConsentStorage();
+        this.windowStart = Date.now();
+        this._startFlushTimer();
+    }
+    /**
+     * Get or init the singleton. Pass config on first call; subsequent calls
+     * with no config return the existing instance.
+     */
+    static instance(cfg) {
+        if (!ErrorFirehoseClient._instance) {
+            if (!cfg)
+                throw new Error("ErrorFirehoseClient: config required on first call");
+            ErrorFirehoseClient._instance = new ErrorFirehoseClient(cfg);
+        }
+        return ErrorFirehoseClient._instance;
+    }
+    /**
+     * Return the singleton if already initialized, or null.
+     * Used by the BravelyAccountManager side-tap — safe no-op when the host
+     * has not initialized the firehose yet.
+     */
+    static _tryInstance() {
+        return ErrorFirehoseClient._instance;
+    }
+    /**
+     * Reset the singleton (for testing only).
+     * @internal
+     */
+    static _reset() {
+        if (ErrorFirehoseClient._instance) {
+            ErrorFirehoseClient._instance._stopFlushTimer();
+            ErrorFirehoseClient._instance = null;
+        }
+    }
+    // ---- Consent API (§D) ---------------------------------------------------
+    /**
+     * Read the current consent state.
+     * Default is false until resolveConsentDefault() runs.
+     */
+    getConsent() {
+        try {
+            const val = this.consentStore.getItem(CONSENT_KEY);
+            if (val === null)
+                return false; // default: OFF until resolveConsentDefault() runs
+            return val !== "false";
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Write consent state. */
+    setConsent(enabled) {
+        try {
+            this.consentStore.setItem(CONSENT_KEY, enabled ? "true" : "false");
+        }
+        catch {
+            // storage unavailable — no-op cleanly
+        }
+    }
+    /**
+     * True iff the one-time opt-out note should be shown.
+     * Returns false after it has been acknowledged once (§D).
+     */
+    shouldShowOptOutNote() {
+        try {
+            return this.consentStore.getItem(OPT_OUT_SHOWN_KEY) !== "true";
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Mark the opt-out note as shown (never show again). */
+    ackOptOutNote() {
+        try {
+            this.consentStore.setItem(OPT_OUT_SHOWN_KEY, "true");
+        }
+        catch {
+            // no-op
+        }
+    }
+    // ---- Core observe() (§C) -----------------------------------------------
+    /**
+     * Side-tap from the facade warn()/error() methods — SECOND path alongside
+     * the ring buffer, never replacing it.
+     *
+     * Steps:
+     *   1. Consent gate: return immediately if disabled.
+     *   2. Redact message (7-pattern scrubber).
+     *   3. Compute fingerprint.
+     *   4. Per-fingerprint circuit-breaker check.
+     *   5. Global cap check (max 50 distinct fps/window).
+     *   6. Upsert into CoalescingBuffer.
+     */
+    async observe(severity, category, message, error, spec_id) {
+        // §C Consent gate — first check
+        if (!this.getConsent())
+            return;
+        const now = Date.now();
+        // Reset window if 60s elapsed
+        if (now - this.windowStart >= FLUSH_INTERVAL_MS) {
+            this._rotateWindow();
+        }
+        const redacted = redactMessage(message);
+        const truncatedMsg = redacted.slice(0, 256);
+        const exceptionType = error?.constructor?.name !== "Error" ? error?.constructor?.name : undefined;
+        const topFrames = extractTopFrames(error);
+        const frameDigest = topFrames.length > 0 ? await computeFrameDigest(topFrames) : undefined;
+        const fp = await computeFingerprint({
+            app_slug: this.cfg.app_slug,
+            platform: "web",
+            severity,
+            category,
+            message: truncatedMsg,
+            frame_digest: frameDigest,
+            exception_type: exceptionType,
+        });
+        // Per-fingerprint circuit-breaker (§C)
+        const existing = this.buffer.get(fp);
+        if (existing) {
+            // Check if in silence period
+            if (now < existing._silencedUntil) {
+                // Still silenced — count it but don't update the buffer
+                existing.count += 1;
+                return;
+            }
+            // Update circuit-breaker window
+            if (now - existing._cbWindowStart >= CB_WINDOW_MS) {
+                existing._cbWindowStart = now;
+                existing._cbWindowCount = 0;
+                existing._emittedOnSilence = false;
+            }
+            existing._cbWindowCount += 1;
+            if (existing._cbWindowCount > CB_TRIP_COUNT) {
+                // Trip: silence for 5 minutes, but first emit once with current count
+                if (!existing._emittedOnSilence) {
+                    existing._silencedUntil = now + CB_SILENCE_MS;
+                    existing._emittedOnSilence = true;
+                    // The entry already has count — it will be included in next flush
+                }
+                return;
+            }
+            // Normal upsert
+            existing.count += 1;
+            existing.last_seen = now;
+            const ctx = this.cfg.getContext?.();
+            if (ctx) {
+                existing.signed_in = ctx.signed_in;
+                existing.entitled = ctx.entitled;
+                existing.online = ctx.online;
+                if (ctx.session_uptime_seconds !== undefined) {
+                    existing.session_uptime_seconds = Math.round(ctx.session_uptime_seconds / 30) * 30;
+                }
+            }
+        }
+        else {
+            // New fingerprint — check global cap
+            if (this.windowFpCount >= MAX_DISTINCT_FP) {
+                // Global overflow: accumulate and emit synthetic event later
+                this.overflowDropped += 1;
+                return;
+            }
+            this.windowFpCount += 1;
+            const ctx = this.cfg.getContext?.();
+            const uptimeRounded = ctx?.session_uptime_seconds !== undefined
+                ? Math.round(ctx.session_uptime_seconds / 30) * 30
+                : undefined;
+            this.buffer.set(fp, {
+                severity,
+                category,
+                spec_id,
+                fingerprint: fp,
+                message_template: truncatedMsg,
+                exception_type: exceptionType,
+                top_frames: topFrames.length > 0 ? topFrames : undefined,
+                frame_digest: frameDigest,
+                count: 1,
+                first_seen: now,
+                last_seen: now,
+                signed_in: ctx?.signed_in ?? false,
+                entitled: ctx?.entitled ?? false,
+                online: ctx?.online ?? navigator?.onLine ?? true,
+                session_uptime_seconds: uptimeRounded,
+                _cbWindowStart: now,
+                _cbWindowCount: 1,
+                _silencedUntil: 0,
+                _emittedOnSilence: false,
+            });
+        }
+    }
+    /**
+     * Force a flush (for testing and graceful shutdown).
+     */
+    async flush() {
+        return this._flush();
+    }
+    // ---- Private internals --------------------------------------------------
+    _startFlushTimer() {
+        if (typeof setInterval === "undefined")
+            return;
+        this.flushTimer = setInterval(() => {
+            void this._flush();
+        }, FLUSH_INTERVAL_MS);
+        // Don't prevent Node process from exiting in tests
+        if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) {
+            this.flushTimer.unref();
+        }
+    }
+    _stopFlushTimer() {
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Rotate to a new 60s window. Called lazily from observe() when >=60s has
+     * elapsed since windowStart. Resets the fp admission counter and the
+     * overflow accumulator. Does NOT clear the buffer — ongoing entries carry
+     * over to the new window if not yet flushed.
+     */
+    _rotateWindow() {
+        this.windowStart = Date.now();
+        this.windowFpCount = 0;
+        this.overflowDropped = 0;
+    }
+    /**
+     * Drain the current buffer into the pending queue, then attempt to drain
+     * the pending queue (oldest-first).
+     */
+    async _flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            await this._drainBufferToQueue();
+            await this._drainPendingQueue();
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    async _drainBufferToQueue() {
+        if (this.buffer.size === 0 && this.overflowDropped === 0)
+            return;
+        const now = Date.now();
+        const events = [];
+        for (const entry of this.buffer.values()) {
+            events.push({
+                client_event_id: mintUuid(),
+                severity: entry.severity,
+                category: entry.category,
+                spec_id: entry.spec_id,
+                fingerprint: entry.fingerprint,
+                message_template: entry.message_template,
+                exception_type: entry.exception_type,
+                top_frames: entry.top_frames,
+                frame_digest: entry.frame_digest,
+                breadcrumbs: entry.breadcrumbs,
+                count: entry.count,
+                first_seen: new Date(entry.first_seen).toISOString(),
+                last_seen: new Date(entry.last_seen).toISOString(),
+                signed_in: entry.signed_in,
+                entitled: entry.entitled,
+                online: entry.online,
+                session_uptime_seconds: entry.session_uptime_seconds,
+            });
+        }
+        // Snapshot and clear the overflow accumulator BEFORE clearing the buffer.
+        // The overflow count is cleared here so the next batch doesn't double-count.
+        const droppedCount = this.overflowDropped;
+        this.overflowDropped = 0;
+        // Synthetic overflow event
+        if (droppedCount > 0) {
+            events.push({
+                client_event_id: mintUuid(),
+                severity: "warn",
+                category: "client",
+                fingerprint: "client.overflow",
+                message_template: "client.distinct_fingerprint_overflow",
+                count: droppedCount,
+                first_seen: new Date(this.windowStart).toISOString(),
+                last_seen: new Date(now).toISOString(),
+                signed_in: false,
+                entitled: false,
+                online: true,
+            });
+        }
+        // Clear the buffer entries but DO NOT rotate the window — windowFpCount
+        // and windowStart are time-based and remain valid until the 60s window
+        // elapses (checked lazily in observe()). This ensures that fps admitted in
+        // this window continue to coalesce rather than re-enter after a drain.
+        this.buffer.clear();
+        // After draining, windowFpCount reflects "fps admitted so far this window".
+        // We reset it to 0 so that the buffer is empty but we allow new fps in.
+        // However, if we're still within the window and at cap, new fps should
+        // still overflow. The correct invariant: windowFpCount = buffer.size at all
+        // times within a window. After drain, buffer.size = 0, so reset to 0.
+        this.windowFpCount = 0;
+        if (events.length === 0)
+            return;
+        // Chunk into batches of max MAX_BATCH_EVENTS events / MAX_BATCH_BYTES bytes
+        const batches = chunkIntoBatches(events, MAX_BATCH_EVENTS, MAX_BATCH_BYTES);
+        const dailyToken = await this._getDailyToken();
+        for (const chunk of batches) {
+            if (this.pendingQueue.length >= MAX_PENDING_BATCHES) {
+                // Drop oldest to make room
+                this.pendingQueue.shift();
+            }
+            this.pendingQueue.push({
+                batch: {
+                    schema_version: 1,
+                    batch_id: mintUuid(),
+                    daily_token: dailyToken,
+                    app_slug: this.cfg.app_slug,
+                    platform: "web",
+                    app_version: this.cfg.app_version,
+                    os_version: this.cfg.os_version ?? detectOsVersion(),
+                    events: chunk,
+                },
+                attempts: 0,
+                nextRetryAt: 0,
+            });
+        }
+    }
+    async _drainPendingQueue() {
+        const now = Date.now();
+        // Process ready batches (nextRetryAt <= now)
+        for (let i = 0; i < this.pendingQueue.length;) {
+            const item = this.pendingQueue[i];
+            if (item.nextRetryAt > now) {
+                i++;
+                continue;
+            }
+            const success = await this._postBatch(item.batch);
+            if (success) {
+                this.pendingQueue.splice(i, 1);
+                // don't increment i — next item shifted down
+            }
+            else {
+                item.attempts += 1;
+                if (item.attempts >= 4) {
+                    // Max 3 retries exhausted (initial + 30s + 60s + 120s → drop): drop
+                    this.pendingQueue.splice(i, 1);
+                }
+                else {
+                    // Backoff with ±10s jitter: 30s → 60s → 120s (BACKOFF_MS indices 0, 1, 2)
+                    const base = BACKOFF_MS[item.attempts - 1] ?? BACKOFF_MS[BACKOFF_MS.length - 1];
+                    const jitter = (Math.random() * 2 - 1) * JITTER_MS;
+                    item.nextRetryAt = Date.now() + base + jitter;
+                    i++;
+                }
+            }
+        }
+    }
+    /**
+     * POST a batch to the ingest endpoint. Returns true on success (2xx).
+     * Never throws.
+     */
+    async _postBatch(batch) {
+        const endpoint = this.cfg.endpointOverride ?? ENDPOINT;
+        try {
+            const body = JSON.stringify(batch);
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+                // Anonymous: NO Authorization header (§E)
+            });
+            // 200 or 202 = accepted (200 + accepted:0 on kill-switch is still ok)
+            // 400 = schema_invalid — don't retry (permanent failure)
+            // 413 = too large — don't retry
+            // 429 = rate_limited — retry with backoff
+            if (res.status === 400 || res.status === 413)
+                return true; // treat as "drop" not "retry"
+            return res.ok;
+        }
+        catch {
+            // Network failure — will retry with backoff
+            return false;
+        }
+    }
+    async _getDailyToken() {
+        const today = new Date().toISOString().slice(0, 10);
+        if (this._cachedDailyToken && this._cachedDailyTokenDate === today) {
+            return this._cachedDailyToken;
+        }
+        const installId = await getOrMintInstallId(this.storage);
+        const token = await computeDailyToken(installId, today);
+        this._cachedDailyToken = token;
+        this._cachedDailyTokenDate = today;
+        return token;
+    }
+}
+// ---- Consent storage helpers -----------------------------------------------
+/**
+ * Return the production ConsentStorage (localStorage when available, memory fallback).
+ * localStorage methods may not be available in SSR or restricted environments.
+ */
+function defaultConsentStorage() {
+    try {
+        const ls = globalThis.localStorage;
+        if (ls && typeof ls.setItem === "function")
+            return ls;
+    }
+    catch {
+        // Access denied (private mode, etc.)
+    }
+    // Fallback: in-memory (consent not persisted — no-op for SSR)
+    return memoryConsentStorage();
+}
+// ---- Helpers ---------------------------------------------------------------
+/** Extract up to 3 frame symbols from an Error stack trace. */
+function extractTopFrames(error) {
+    if (!error?.stack)
+        return [];
+    const lines = error.stack.split("\n");
+    const frames = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip the error message line (not at)
+        if (trimmed.startsWith("at ") || trimmed.match(/^[A-Za-z]/)) {
+            // Extract function/method name only (no file paths or line numbers)
+            const match = trimmed.match(/^at\s+([^\s(]+)/);
+            if (match) {
+                frames.push(match[1]);
+                if (frames.length === 3)
+                    break;
+            }
+        }
+    }
+    return frames;
+}
+/** Split events into chunks respecting both the count and byte size limits. */
+function chunkIntoBatches(events, maxCount, maxBytes) {
+    const chunks = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const ev of events) {
+        const evBytes = JSON.stringify(ev).length;
+        if (current.length > 0 &&
+            (current.length >= maxCount || currentBytes + evBytes > maxBytes)) {
+            chunks.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(ev);
+        currentBytes += evBytes;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/** Detect OS version string from the browser environment. */
+function detectOsVersion() {
+    if (typeof navigator === "undefined")
+        return "unknown";
+    const ua = navigator.userAgent;
+    // macOS
+    const mac = ua.match(/Mac OS X ([0-9_]+)/);
+    if (mac)
+        return `macOS ${mac[1].replace(/_/g, ".")}`;
+    // Windows
+    const win = ua.match(/Windows NT ([0-9.]+)/);
+    if (win)
+        return `Windows NT ${win[1]}`;
+    // iOS
+    const ios = ua.match(/iPhone OS ([0-9_]+)/);
+    if (ios)
+        return `iOS ${ios[1].replace(/_/g, ".")}`;
+    // Android
+    const android = ua.match(/Android ([0-9.]+)/);
+    if (android)
+        return `Android ${android[1]}`;
+    // Linux
+    if (ua.includes("Linux"))
+        return "Linux";
+    return "unknown";
+}
+//# sourceMappingURL=error-firehose-client.js.map