@telemetry-tracker/core 1.3.0 → 1.5.0

package/dist/device-context.d.ts

@@ -0,0 +1,9 @@
+/** Lightweight browser/OS hints for session ingest (no UA parser dependency). */
+export type DeviceContext = {
+    device_browser?: string;
+    device_os?: string;
+    country?: string;
+};
+/** Best-effort device + country from the runtime environment. */
+export declare function readDeviceContext(): DeviceContext;
+//# sourceMappingURL=device-context.d.ts.map

package/dist/device-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-context.d.ts","sourceRoot":"","sources":["../src/device-context.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,MAAM,MAAM,aAAa,GAAG;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAkCF,iEAAiE;AACjE,wBAAgB,iBAAiB,IAAI,aAAa,CASjD"}

package/dist/device-context.js

@@ -0,0 +1,53 @@
+/** Lightweight browser/OS hints for session ingest (no UA parser dependency). */
+function parseBrowser(ua) {
+    if (/Edg\//i.test(ua))
+        return "Edge";
+    if (/OPR\//i.test(ua) || /Opera/i.test(ua))
+        return "Opera";
+    if (/Firefox\//i.test(ua))
+        return "Firefox";
+    if (/Chrome\//i.test(ua) && !/Edg\//i.test(ua))
+        return "Chrome";
+    if (/Safari\//i.test(ua) && !/Chrome\//i.test(ua))
+        return "Safari";
+    return undefined;
+}
+function parseOs(ua) {
+    if (/Windows NT/i.test(ua))
+        return "Windows";
+    if (/Mac OS X|Macintosh/i.test(ua))
+        return "macOS";
+    if (/Android/i.test(ua))
+        return "Android";
+    if (/(iPhone|iPad|iPod)/i.test(ua))
+        return "iOS";
+    if (/Linux/i.test(ua))
+        return "Linux";
+    return undefined;
+}
+function localeCountry() {
+    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat !== "function") {
+        return undefined;
+    }
+    try {
+        const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+        const match = locale.match(/[-_]([A-Za-z]{2})\b/);
+        if (!match)
+            return undefined;
+        return match[1].toUpperCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Best-effort device + country from the runtime environment. */
+export function readDeviceContext() {
+    const out = {};
+    if (typeof navigator !== "undefined" && navigator.userAgent) {
+        const ua = navigator.userAgent;
+        out.device_browser = parseBrowser(ua);
+        out.device_os = parseOs(ua);
+    }
+    out.country = localeCountry();
+    return out;
+}

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 import { SDK_VERSION } from "./version.js";
 export { SDK_VERSION };
+export { toReportableError } from "./to-reportable-error.js";
+export { scrubPiiText, scrubPiiRecord } from "./pii-scrub.js";
+export { WEB_VITAL_EVENT_NAME, installWebVitals, rateWebVital, buildWebVitalProperties, setWebVitalsCaptureEnabled, isWebVitalsCaptureEnabled, type WebVitalEventProperties, type WebVitalMetricName, type WebVitalRating, } from "./web-vitals.js";
 export declare function getAnonymousId(): string;
+export type TelemetryPiiScrubConfig = boolean | {
+    /** Extra property/context keys to redact (case-insensitive). */
+    denyKeys?: string[];
+};
 export type TelemetryConfig = {
     ingestUrl: string;
     app: string;
@@ -13,19 +20,39 @@ export type TelemetryConfig = {
     batchInterval?: number;
     /** Max queue size before flush. Default 10. */
     batchSize?: number;
+    /** Capture Core Web Vitals (LCP, INP, CLS, TTFB) in browser. Default true. */
+    webVitals?: boolean;
+    /**
+     * Optional client-side PII scrubbing before send (default off).
+     * Complements server ingest scrubbing — never rely on this alone.
+     * See https://github.com/Telemetry-Tracker/telemetry-tracker/blob/develop/docs/PII-SCRUBBING.md
+     */
+    piiScrub?: TelemetryPiiScrubConfig;
 };
 export declare function getSessionId(): string | null;
 /** End the current session and clear the in-memory session id. */
 export declare function endSession(): void;
 export declare function init(c: TelemetryConfig): void;
-export declare function identify(id: string | null): void;
+/**
+ * Stop ingesting: flush/end session, clear config and batch timer.
+ * Browser error and session listeners stay installed but no-op while config is unset.
+ */
+export declare function shutdown(): void;
+export type IdentifyTraits = {
+    email?: string | null;
+};
+export declare function identify(id: string | null, traits?: IdentifyTraits): void;
 /** Headers for ingest POST requests (Authorization + Content-Type). */
 export declare function buildIngestHeaders(cfg: Pick<TelemetryConfig, "apiKey">): Record<string, string>;
+declare function resolveClientPiiScrub(cfg: TelemetryConfig | null): {
+    denyKeys?: string[];
+} | null;
+/** @internal exported for tests */
+export { resolveClientPiiScrub };
 export declare function trackEvent(name: string, properties?: Record<string, unknown>): void;
-export declare function trackError(error: Error | {
-    message: string;
-    stack?: string;
-}, context?: Record<string, unknown>): void;
+export declare function trackError(error: unknown, context?: Record<string, unknown>): void;
+/** Send an error and resolve after the ingest request settles. Fatal handlers await this. */
+export declare function ingestError(error: unknown, context?: Record<string, unknown>): Promise<void>;
 export declare function screen(name: string): void;
 export declare function getUserId(): string | null;
 export declare function getConfigOrNull(): TelemetryConfig | null;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,CAAC;AAiBvB,wBAAgB,cAAc,IAAI,MAAM,CAkBvC;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA6GF,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,kEAAkE;AAClE,wBAAgB,UAAU,IAAI,IAAI,CAOjC;AA4CD,wBAAgB,IAAI,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAgB7C;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEhD;AAYD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/F;AA4DD,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAqBN;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAcN;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,eAAe,IAAI,eAAe,GAAG,IAAI,CAExD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,0BAA0B,EAC1B,yBAAyB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAyCzB,wBAAgB,cAAc,IAAI,MAAM,CAkBvC;AAED,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP;IACE,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC,CAAC;AA0HF,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,kEAAkE;AAClE,wBAAgB,UAAU,IAAI,IAAI,CAOjC;AA4CD,wBAAgB,IAAI,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAwB7C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAS/B;AAQD,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CASzE;AAYD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO/F;AA6ED,iBAAS,qBAAqB,CAC5B,GAAG,EAAE,eAAe,GAAG,IAAI,GAC1B;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAahC;AAED,mCAAmC;AACnC,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAWjC,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAsBN;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAEN;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CA+Cf;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED,wBAAgB,eAAe,IAAI,eAAe,GAAG,IAAI,CAExD"}

package/dist/index.js

@@ -1,17 +1,44 @@
-const REPORTED = Symbol.for("telemetry.reported");
+import { readDeviceContext } from "./device-context.js";
+import { installWebVitals, setWebVitalsCaptureEnabled, WEB_VITAL_EVENT_NAME, } from "./web-vitals.js";
+import { scrubPiiRecord, scrubPiiText } from "./pii-scrub.js";
 import { SDK_VERSION } from "./version.js";
+import { toReportableError } from "./to-reportable-error.js";
 export { SDK_VERSION };
+export { toReportableError } from "./to-reportable-error.js";
+export { scrubPiiText, scrubPiiRecord } from "./pii-scrub.js";
+export { WEB_VITAL_EVENT_NAME, installWebVitals, rateWebVital, buildWebVitalProperties, setWebVitalsCaptureEnabled, isWebVitalsCaptureEnabled, } from "./web-vitals.js";
 const ANON_STORAGE_KEY = "tacko_telemetry_anon_id";
+/** In-flight ingest promises so a later fatal flush can await trackError(e); throw e. */
+const inFlightIngest = new WeakMap();
+/** Completed error reports — WeakSet so we never mutate frozen/sealed Error objects. */
+const reportedErrors = new WeakSet();
 let anonymousId = null;
+let fallbackIdSeq = 0;
+function bytesToUuid(bytes) {
+    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)}`;
+}
+/** Prefer Web Crypto; fall back for Node/RN hosts without a global crypto polyfill. */
 function generateUUID() {
-    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-        return crypto.randomUUID();
+    const webCrypto = typeof globalThis !== "undefined" ? globalThis.crypto : undefined;
+    if (webCrypto && typeof webCrypto.randomUUID === "function") {
+        return webCrypto.randomUUID();
     }
-    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === "x" ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
+    if (webCrypto && typeof webCrypto.getRandomValues === "function") {
+        const bytes = new Uint8Array(16);
+        webCrypto.getRandomValues(bytes);
+        return bytesToUuid(bytes);
+    }
+    // Constrained runtimes: unique analytics IDs without Math.random (CodeQL insecure-randomness).
+    const bytes = new Uint8Array(16);
+    let n = (Date.now() ^ (++fallbackIdSeq * 0x9e3779b9)) >>> 0;
+    for (let i = 0; i < 16; i++) {
+        n = (Math.imul(n, 1664525) + 1013904223) >>> 0;
+        bytes[i] = n & 0xff;
+    }
+    return bytesToUuid(bytes);
 }
 export function getAnonymousId() {
     if (anonymousId)
@@ -37,6 +64,7 @@ export function getAnonymousId() {
 }
 let config = null;
 let userId = null;
+let userEmail = null;
 let browserHandlersInstalled = false;
 let sessionLifecycleInstalled = false;
 let sessionId = null;
@@ -50,14 +78,20 @@ function ensureUrlFromCfg(cfg, path) {
     return `${base}${path}`;
 }
 function buildSessionPayload(cfg, endedAt) {
+    const device = readDeviceContext();
     return {
         session_id: sessionId,
         app: cfg.app,
         platform: cfg.platform ?? undefined,
         environment: cfg.environment ?? undefined,
+        release: cfg.release ?? undefined,
         user_id: userId ?? undefined,
+        user_email: userEmail ?? undefined,
         anonymous_id: getAnonymousId(),
         sdk_version: SDK_VERSION,
+        country: device.country ?? undefined,
+        device_browser: device.device_browser ?? undefined,
+        device_os: device.device_os ?? undefined,
         started_at: sessionStartedAt?.toISOString(),
         ended_at: endedAt?.toISOString(),
     };
@@ -102,12 +136,12 @@ function closeSessionKeepalive(endedAt) {
     sessionStartedAt = null;
 }
 function startSession() {
+    const cfg = getConfigOrNull();
+    if (!cfg)
+        return;
     sessionId = generateUUID();
     sessionStartedAt = new Date();
-    const cfg = getConfigOrNull();
-    if (cfg) {
-        void postSession(cfg);
-    }
+    void postSession(cfg);
 }
 function installBrowserSessionLifecycle() {
     if (sessionLifecycleInstalled)
@@ -120,8 +154,14 @@ function installBrowserSessionLifecycle() {
     window.addEventListener("pagehide", (event) => {
         if (event.persisted)
             return;
+        flushEventsKeepalive();
         closeSessionKeepalive(new Date());
     });
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") {
+            flushEventsKeepalive();
+        }
+    });
     window.addEventListener("pageshow", (event) => {
         if (event.persisted)
             return;
@@ -176,6 +216,10 @@ function installBrowserErrorHandlers() {
     });
 }
 export function init(c) {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
     if (sessionId) {
         endSession();
     }
@@ -192,9 +236,39 @@ export function init(c) {
     installBrowserErrorHandlers();
     startSession();
     installBrowserSessionLifecycle();
+    setWebVitalsCaptureEnabled(c.webVitals !== false);
+    if (c.webVitals !== false) {
+        installBrowserWebVitals();
+    }
 }
-export function identify(id) {
+/**
+ * Stop ingesting: flush/end session, clear config and batch timer.
+ * Browser error and session listeners stay installed but no-op while config is unset.
+ */
+export function shutdown() {
+    flushEvents();
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    endSession();
+    config = null;
+    setWebVitalsCaptureEnabled(false);
+}
+function installBrowserWebVitals() {
+    installWebVitals((properties) => {
+        trackEvent(WEB_VITAL_EVENT_NAME, properties);
+    });
+}
+export function identify(id, traits) {
     userId = id;
+    if (traits && "email" in traits) {
+        userEmail = traits.email ?? null;
+    }
+    const cfg = getConfigOrNull();
+    if (cfg && sessionId) {
+        void postSession(cfg);
+    }
 }
 function getConfig() {
     if (!config)
@@ -251,6 +325,17 @@ function flushEvents() {
     if (!cfg || eventQueue.length === 0)
         return;
     const batch = eventQueue.splice(0, eventQueue.length);
+    sendEventBatch(cfg, batch, false);
+}
+/** Flush queued events with keepalive for tab hide / unload (CLS and short visits). */
+function flushEventsKeepalive() {
+    const cfg = getConfigOrNull();
+    if (!cfg || eventQueue.length === 0)
+        return;
+    const batch = eventQueue.splice(0, eventQueue.length);
+    sendEventBatch(cfg, batch, true);
+}
+function sendEventBatch(cfg, batch, keepalive) {
     const base = cfg.ingestUrl.replace(/\/$/, "");
     const anonId = getAnonymousId();
     const events = batch.map((e) => ({
@@ -265,21 +350,52 @@ function flushEvents() {
         sdk_version: SDK_VERSION,
         properties: e.properties,
     }));
-    fetch(`${base}/ingest/batch`, {
-        method: "POST",
-        headers: buildIngestHeaders(cfg),
-        body: JSON.stringify({ events }),
-    }).catch((e) => console.warn("[telemetry] batch send error:", e));
+    try {
+        void fetch(`${base}/ingest/batch`, {
+            method: "POST",
+            headers: buildIngestHeaders(cfg),
+            body: JSON.stringify({ events }),
+            ...(keepalive ? { keepalive: true } : {}),
+        }).catch((e) => console.warn("[telemetry] batch send error:", e));
+    }
+    catch (e) {
+        console.warn("[telemetry] batch send error:", e);
+    }
+}
+function resolveClientPiiScrub(cfg) {
+    // Opt-in only: omitted / false / null → no client scrubbing.
+    if (cfg?.piiScrub == null || cfg.piiScrub === false)
+        return null;
+    if (cfg.piiScrub === true)
+        return {};
+    if (typeof cfg.piiScrub === "object") {
+        // `{ denyKeys: [] }` still enables default pattern/key scrubbing (no extra keys).
+        return {
+            ...(cfg.piiScrub.denyKeys && cfg.piiScrub.denyKeys.length > 0
+                ? { denyKeys: cfg.piiScrub.denyKeys }
+                : {}),
+        };
+    }
+    return null;
+}
+/** @internal exported for tests */
+export { resolveClientPiiScrub };
+function scrubEventProperties(cfg, properties) {
+    const opts = resolveClientPiiScrub(cfg);
+    if (!opts || properties === undefined)
+        return properties;
+    return scrubPiiRecord(properties, opts);
 }
 export function trackEvent(name, properties) {
     const cfg = getConfigOrNull();
     const interval = cfg?.batchInterval ?? DEFAULT_BATCH_INTERVAL;
     const batchSize = cfg?.batchSize ?? DEFAULT_BATCH_SIZE;
+    const scrubbedProperties = scrubEventProperties(cfg, properties ?? undefined);
     const item = {
         name,
         user_id: userId,
         session_id: sessionId ?? undefined,
-        properties: properties ?? undefined,
+        properties: scrubbedProperties,
     };
     if (interval > 0 && typeof setInterval !== "undefined") {
         eventQueue.push(item);
@@ -296,22 +412,53 @@ export function trackEvent(name, properties) {
     }
 }
 export function trackError(error, context) {
-    if (!getConfigOrNull())
-        return;
-    const err = error instanceof Error ? error : { message: error.message, stack: error.stack };
-    if (err && typeof err === "object" && err[REPORTED])
-        return;
-    const message = err instanceof Error ? err.message : err.message;
-    const stack = err instanceof Error ? err.stack : err.stack;
-    if (err instanceof Error)
-        err[REPORTED] = true;
-    send("/ingest/error", {
-        message,
-        stack: stack ?? undefined,
-        context: context ?? undefined,
-        user_id: userId ?? undefined,
-        session_id: sessionId ?? undefined,
-    }).catch(() => { });
+    void ingestError(error, context);
+}
+/** Send an error and resolve after the ingest request settles. Fatal handlers await this. */
+export function ingestError(error, context) {
+    try {
+        const cfg = getConfigOrNull();
+        if (!cfg)
+            return Promise.resolve();
+        const err = toReportableError(error);
+        const existing = inFlightIngest.get(err);
+        if (existing)
+            return existing;
+        if (reportedErrors.has(err)) {
+            return Promise.resolve();
+        }
+        let message = err.message;
+        let stack = err.stack;
+        let scrubbedContext = context ?? undefined;
+        const scrubOpts = resolveClientPiiScrub(cfg);
+        if (scrubOpts) {
+            message = scrubPiiText(message);
+            if (stack != null)
+                stack = scrubPiiText(stack);
+            if (scrubbedContext != null) {
+                scrubbedContext = scrubPiiRecord(scrubbedContext, scrubOpts);
+            }
+        }
+        // Non-mutating dedupe — safe for Object.freeze / seal / preventExtensions.
+        reportedErrors.add(err);
+        const pending = send("/ingest/error", {
+            message,
+            stack: stack ?? undefined,
+            context: scrubbedContext,
+            user_id: userId ?? undefined,
+            session_id: sessionId ?? undefined,
+        })
+            .catch(() => { })
+            .finally(() => {
+            inFlightIngest.delete(err);
+        });
+        inFlightIngest.set(err, pending);
+        return pending;
+    }
+    catch {
+        // Never let telemetry-internal failures escape into the caller's crash path.
+        return Promise.resolve();
+    }
 }
 export function screen(name) {
     trackEvent("$screen", { name });

package/dist/pii-scrub.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Optional client-side PII scrubbing for @telemetry-tracker/core.
+ * Complements server ingest scrubbing; never replaces it.
+ */
+export type ClientPiiScrubOptions = {
+    denyKeys?: string[];
+    /** Max object/array nesting depth (default 8). */
+    maxDepth?: number;
+    /**
+     * Soft threshold: when exceeded, switch to the bounded remainder pass
+     * (still redacts nested keys/strings). Default 500.
+     */
+    maxNodes?: number;
+};
+/** Scrub PII patterns in free-form text. Preserves newlines. */
+export declare function scrubPiiText(text: string): string;
+export declare function scrubPiiValue(value: unknown, options?: ClientPiiScrubOptions): unknown;
+export declare function scrubPiiRecord(record: Record<string, unknown> | undefined, options?: ClientPiiScrubOptions): Record<string, unknown> | undefined;
+//# sourceMappingURL=pii-scrub.d.ts.map

package/dist/pii-scrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii-scrub.d.ts","sourceRoot":"","sources":["../src/pii-scrub.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AA4DF,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBjD;AA4CD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAoDT;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGrC"}

package/dist/pii-scrub.js

@@ -0,0 +1,156 @@
+/**
+ * Optional client-side PII scrubbing for @telemetry-tracker/core.
+ * Complements server ingest scrubbing; never replaces it.
+ */
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_NODES = 500;
+const EMAIL_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const JWT_RE = /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{4,}\b/gi;
+const API_KEY_RE = /\b(?:tt_live_[A-Za-z0-9_]+|sk-[A-Za-z0-9]{16,}|pk-[A-Za-z0-9]{16,})\b/g;
+const SENSITIVE_PARAM_RE = /([?&](?:password|token|secret|api[_-]?key|access[_-]?token|auth|session|cookie)=)[^&\s]+/gi;
+const SENSITIVE_ASSIGNMENT_RE = /\b(?:password|token|secret|api[_-]?key|access[_-]?token|auth|session|cookie)\s*=\s*[^\s&]+/gi;
+const COOKIE_HEADER_RE = /\b(cookie|set-cookie)\s*:\s*[^\n]+/gi;
+const AUTHORIZATION_HEADER_RE = /\bauthorization\s*:\s*[^\n]+/gi;
+const SENSITIVE_KEY_PLACEHOLDERS = {
+    email: "[email]",
+    useremail: "[email]",
+    mail: "[email]",
+    phone: "[phone]",
+    phonenumber: "[phone]",
+    mobile: "[phone]",
+    ssn: "[ssn]",
+    password: "[password]",
+    secret: "[secret]",
+    token: "[token]",
+    accesstoken: "[token]",
+    refreshtoken: "[token]",
+    apikey: "[api-key]",
+    authorization: "[bearer-token]",
+    cookie: "[cookie]",
+    setcookie: "[cookie]",
+};
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function denyKeySet(denyKeys) {
+    if (!denyKeys?.length)
+        return EMPTY;
+    const set = new Set();
+    for (const key of denyKeys) {
+        const n = normalizeKey(key);
+        if (n)
+            set.add(n);
+    }
+    return set;
+}
+const EMPTY = new Set();
+function resolvePlaceholder(key, denyNormalized) {
+    const n = normalizeKey(key);
+    return SENSITIVE_KEY_PLACEHOLDERS[n] ?? (denyNormalized.has(n) ? "[redacted]" : null);
+}
+/** Scrub PII patterns in free-form text. Preserves newlines. */
+export function scrubPiiText(text) {
+    let out = text;
+    out = out.replace(EMAIL_RE, "[email]");
+    out = out.replace(JWT_RE, "[token]");
+    out = out.replace(BEARER_RE, "[bearer-token]");
+    out = out.replace(API_KEY_RE, "[api-key]");
+    out = scrubPaymentCardNumbers(out);
+    out = scrubPhoneNumbers(out);
+    out = out.replace(SENSITIVE_PARAM_RE, "$1[redacted]");
+    out = out.replace(SENSITIVE_ASSIGNMENT_RE, (match) => `${match.split("=")[0].trim()}=[redacted]`);
+    out = out.replace(COOKIE_HEADER_RE, (_, header) => `${header}: [cookie]`);
+    out = out.replace(AUTHORIZATION_HEADER_RE, "authorization: [bearer-token]");
+    return out;
+}
+function passesLuhn(digits) {
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    let alternate = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = digits.charCodeAt(i) - 48;
+        if (alternate) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alternate = !alternate;
+    }
+    return sum % 10 === 0;
+}
+function scrubPaymentCardNumbers(text) {
+    return text.replace(/(?<![A-Za-z0-9])(?:\d[ -]*?){13,19}(?![A-Za-z0-9])/g, (match) => {
+        const digits = match.replace(/\D/g, "");
+        return passesLuhn(digits) ? "[card]" : match;
+    });
+}
+function scrubPhoneNumbers(text) {
+    let out = text;
+    // Plus-prefixed: + and 7–15 digits with optional spaces/dashes between digits
+    // Dots excluded so version-like 123.456.7890 is not treated as a phone.
+    out = out.replace(/(?<![\w])\+[1-9](?:[\s-]*\d){6,14}(?![\d])/g, "[phone]");
+    // North American style with separators (space/dash only; no dots)
+    out = out.replace(/(?<![\w])(?:\+?1[\s-]?)?\(?\d{3}\)?[\s-]\d{3}[\s-]\d{4}(?![\d])/g, "[phone]");
+    return out;
+}
+export function scrubPiiValue(value, options) {
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxNodes = options?.maxNodes ?? DEFAULT_MAX_NODES;
+    const denyNormalized = denyKeySet(options?.denyKeys);
+    let nodes = 0;
+    /** Bounded recursive pass after soft limits — never returns nested structures unchanged. */
+    function scrubRemainder(node, hardCap) {
+        hardCap.n += 1;
+        // Absolute ceiling so limit fallback cannot hang the client.
+        if (hardCap.n > 10000) {
+            return typeof node === "string" ? scrubPiiText(node) : "[truncated]";
+        }
+        if (typeof node === "string")
+            return scrubPiiText(node);
+        if (Array.isArray(node)) {
+            return node.map((item) => scrubRemainder(item, hardCap));
+        }
+        if (node && typeof node === "object") {
+            const out = {};
+            for (const [key, child] of Object.entries(node)) {
+                const placeholder = resolvePlaceholder(key, denyNormalized);
+                out[key] =
+                    placeholder != null ? placeholder : scrubRemainder(child, hardCap);
+            }
+            return out;
+        }
+        return node;
+    }
+    function walk(node, depth) {
+        nodes += 1;
+        if (nodes > maxNodes || depth > maxDepth) {
+            return scrubRemainder(node, { n: 0 });
+        }
+        if (node == null || typeof node === "boolean" || typeof node === "number") {
+            return node;
+        }
+        if (typeof node === "string")
+            return scrubPiiText(node);
+        if (Array.isArray(node))
+            return node.map((item) => walk(item, depth + 1));
+        if (typeof node === "object") {
+            const out = {};
+            for (const [key, child] of Object.entries(node)) {
+                const placeholder = resolvePlaceholder(key, denyNormalized);
+                out[key] =
+                    placeholder != null ? placeholder : walk(child, depth + 1);
+            }
+            return out;
+        }
+        return node;
+    }
+    return walk(value, 0);
+}
+export function scrubPiiRecord(record, options) {
+    if (record == null)
+        return undefined;
+    return scrubPiiValue(record, options);
+}

package/dist/to-reportable-error.d.ts

@@ -0,0 +1,3 @@
+/** Normalize any thrown/rejected value into a reportable Error. */
+export declare function toReportableError(value: unknown): Error;
+//# sourceMappingURL=to-reportable-error.d.ts.map

package/dist/to-reportable-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-reportable-error.d.ts","sourceRoot":"","sources":["../src/to-reportable-error.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAuBvD"}

package/dist/to-reportable-error.js

@@ -0,0 +1,30 @@
+/** Normalize any thrown/rejected value into a reportable Error. */
+export function toReportableError(value) {
+    if (value instanceof Error)
+        return value;
+    if (value === null)
+        return new Error("null");
+    if (value === undefined)
+        return new Error("undefined");
+    if (typeof value === "string")
+        return new Error(value);
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return new Error(String(value));
+    }
+    if (typeof value === "symbol")
+        return new Error(value.toString());
+    if (typeof value === "object") {
+        try {
+            const json = JSON.stringify(value);
+            if (typeof json === "string")
+                return new Error(json);
+        }
+        catch {
+            // circular / non-serializable
+        }
+        return new Error(Object.prototype.toString.call(value));
+    }
+    return new Error(String(value));
+}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Injected at build time from package.json. Do not edit manually. */
-export declare const SDK_VERSION = "1.3.0";
+export declare const SDK_VERSION = "1.5.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Injected at build time from package.json. Do not edit manually. */
-export const SDK_VERSION = "1.3.0";
+export const SDK_VERSION = "1.5.0";

package/dist/web-vitals.d.ts

@@ -0,0 +1,24 @@
+/** Core Web Vitals capture for browser apps (issue #193). */
+import type { Metric } from "web-vitals";
+export declare const WEB_VITAL_EVENT_NAME = "$web_vital";
+export type WebVitalMetricName = "LCP" | "INP" | "CLS" | "TTFB" | "FID";
+export type WebVitalRating = "good" | "needs-improvement" | "poor";
+export type WebVitalEventProperties = {
+    metric: WebVitalMetricName;
+    value: number;
+    rating: WebVitalRating;
+    path: string;
+    id: string;
+    navigation_type?: string;
+    connection_type?: string;
+};
+export declare function rateWebVital(metric: WebVitalMetricName, value: number): WebVitalRating;
+export declare function buildWebVitalProperties(metric: Metric): WebVitalEventProperties;
+/** Toggle capture without unregistering library listeners (checked on every report). */
+export declare function setWebVitalsCaptureEnabled(enabled: boolean): void;
+export declare function isWebVitalsCaptureEnabled(): boolean;
+/** Register Core Web Vitals listeners; calls `report` once per finalized metric sample. */
+export declare function installWebVitals(report: (properties: WebVitalEventProperties) => void): void;
+/** @internal Test helper — reset install guard. */
+export declare function resetWebVitalsInstallState(): void;
+//# sourceMappingURL=web-vitals.d.ts.map

package/dist/web-vitals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-vitals.d.ts","sourceRoot":"","sources":["../src/web-vitals.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAExE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAWF,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAKtF;AAcD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB,CAW/E;AAKD,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjE;AAED,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,CAAC,UAAU,EAAE,uBAAuB,KAAK,IAAI,GACpD,IAAI,CA8BN;AAED,mDAAmD;AACnD,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD"}

package/dist/web-vitals.js

@@ -0,0 +1,87 @@
+/** Core Web Vitals capture for browser apps (issue #193). */
+export const WEB_VITAL_EVENT_NAME = "$web_vital";
+/** Google Web Vitals thresholds — used in tests and when rating is computed locally. */
+const THRESHOLDS = {
+    LCP: [2500, 4000],
+    INP: [200, 500],
+    CLS: [0.1, 0.25],
+    TTFB: [800, 1800],
+    FID: [100, 300],
+};
+export function rateWebVital(metric, value) {
+    const [goodMax, poorMin] = THRESHOLDS[metric];
+    if (value <= goodMax)
+        return "good";
+    if (value >= poorMin)
+        return "poor";
+    return "needs-improvement";
+}
+function readPagePath() {
+    if (typeof window === "undefined")
+        return "/";
+    return window.location.pathname || "/";
+}
+function readConnectionType() {
+    if (typeof navigator === "undefined")
+        return undefined;
+    const conn = navigator
+        .connection;
+    return conn?.effectiveType?.trim() || undefined;
+}
+export function buildWebVitalProperties(metric) {
+    const name = metric.name;
+    return {
+        metric: name,
+        value: metric.value,
+        rating: metric.rating,
+        path: readPagePath(),
+        id: metric.id,
+        navigation_type: metric.navigationType,
+        connection_type: readConnectionType(),
+    };
+}
+let webVitalsInstalled = false;
+let webVitalsCaptureEnabled = false;
+/** Toggle capture without unregistering library listeners (checked on every report). */
+export function setWebVitalsCaptureEnabled(enabled) {
+    webVitalsCaptureEnabled = enabled;
+}
+export function isWebVitalsCaptureEnabled() {
+    return webVitalsCaptureEnabled;
+}
+/** Register Core Web Vitals listeners; calls `report` once per finalized metric sample. */
+export function installWebVitals(report) {
+    if (webVitalsInstalled)
+        return;
+    if (typeof window === "undefined" ||
+        typeof document === "undefined" ||
+        typeof window.addEventListener !== "function") {
+        return;
+    }
+    webVitalsInstalled = true;
+    void import("web-vitals")
+        .then(({ onCLS, onINP, onLCP, onTTFB }) => {
+        if (!webVitalsCaptureEnabled) {
+            webVitalsInstalled = false;
+            return;
+        }
+        const handle = (metric) => {
+            if (!webVitalsCaptureEnabled)
+                return;
+            report(buildWebVitalProperties(metric));
+        };
+        onCLS(handle);
+        onINP(handle);
+        onLCP(handle);
+        onTTFB(handle);
+    })
+        .catch((err) => {
+        console.warn("[telemetry] web vitals install failed:", err);
+        webVitalsInstalled = false;
+    });
+}
+/** @internal Test helper — reset install guard. */
+export function resetWebVitalsInstallState() {
+    webVitalsInstalled = false;
+    webVitalsCaptureEnabled = false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-tracker/core",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Lightweight telemetry client: events, errors, sessions. Framework-agnostic core.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,10 @@
     "typescript": "^5.6.3",
     "vitest": "^3.2.6"
   },
+  "dependencies": {
+    "web-vitals": "^4.2.4"
+  },
+  "gitHead": "886d9f8e0b92a78471f27b87365fc40ba7043ce1",
   "scripts": {
     "build": "node scripts/inject-version.cjs && rm -rf dist && tsc",
     "dev": "tsc --watch",