@cross-deck/web 0.10.0 → 1.0.0

package/dist/index.d.mts

@@ -182,6 +182,17 @@ interface AutoTrackOptions {
      * (DataDog, Sentry Performance) and don't want duplicates.
      */
     webVitals: boolean;
+    /**
+     * Error capture (v1.0.0+) — installs window.onerror +
+     * window.onunhandledrejection listeners, wraps fetch + XHR to catch
+     * 5xx + network failures, ships each captured error as a Crossdeck
+     * event (kind: error.unhandled / error.unhandledrejection /
+     * error.handled / error.http / error.message). Errors gate on
+     * `consent.errors`. Rate-limited per-fingerprint so a runaway loop
+     * can't flood the queue; browser-extension noise filtered by
+     * default. Default true in browsers, no-op everywhere else.
+     */
+    errors: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -368,6 +379,149 @@ interface ConsentState {
     errors: boolean;
 }
 
+/**
+ * Breadcrumb ring buffer — context attached to every error report.
+ *
+ * Sentry / Datadog / Bugsnag all ship the same idea: keep a rolling
+ * record of the last N "things the user did" (page views, clicks,
+ * custom events, network calls, console logs). When an error fires,
+ * attach the buffer so the engineer reading the error can see exactly
+ * how the user got into the broken state. The single most powerful
+ * debugging signal in error monitoring — without breadcrumbs, errors
+ * are stack traces with no story.
+ *
+ * Implementation: a circular buffer with a fixed cap. Old entries are
+ * evicted as new ones arrive. The default cap (50) is enough to cover
+ * ~5 minutes of typical user activity without ballooning the error
+ * payload — Sentry uses 100 by default but the SDK is more aggressive
+ * about size since we ship breadcrumbs over the wire with every error,
+ * not as a separate batch.
+ *
+ * Privacy: breadcrumbs auto-emit from the same auto-tracking sources
+ * as analytics events (page.viewed, element.clicked). Those already
+ * skip password fields, form inputs, and cd-noTrack subtrees. Custom
+ * crumbs added via Crossdeck.addBreadcrumb() pass through the same
+ * property sanitiser as track() events.
+ */
+type BreadcrumbCategory = "navigation" | "ui.click" | "ui.input" | "http" | "console" | "custom" | "info";
+type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+interface Breadcrumb {
+    /** epoch ms */
+    timestamp: number;
+    category: BreadcrumbCategory;
+    level?: BreadcrumbLevel;
+    /** Short human-readable description. */
+    message?: string;
+    /** Arbitrary key/value context for the crumb. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
+ * stack strings into a common frame shape.
+ *
+ * Why hand-rolled, not stack-trace-js or error-stack-parser libraries:
+ * those weigh 5–15 KB after minification and we'd be pulling in their
+ * full feature matrix just for the parser. The patterns below cover
+ * the four shapes any modern browser emits, totalling ~80 lines.
+ *
+ * The output frame shape mirrors what Sentry's `mechanism: { type:
+ * 'generic' }` events ship, so future source-map symbolication on the
+ * Crossdeck backend has a stable input to work against.
+ *
+ * Defensive: never throws. An unparseable line becomes a `raw` frame
+ * with just the literal text. Engineers reading errors still get the
+ * raw stack as fallback.
+ */
+interface StackFrame {
+    /** Function name, or "?" if anonymous / unparseable. */
+    function: string;
+    /** Source file URL the frame ran in. Empty when unknown. */
+    filename: string;
+    /** 1-indexed line number, or 0 when unknown. */
+    lineno: number;
+    /** 1-indexed column number, or 0 when unknown. */
+    colno: number;
+    /**
+     * True when the frame is in the app's own code (best-effort:
+     * detected by URL not starting with chrome-extension://, etc.).
+     * Helps the dashboard's "your code vs library code" view.
+     */
+    in_app: boolean;
+    /** Raw line from the stack string for debugging when parse fails. */
+    raw: string;
+}
+
+/**
+ * Error capture — the third Crossdeck USP.
+ *
+ * Catches every error source the browser can hand us and ships them as
+ * Crossdeck events. The pipeline reuses the analytics queue:
+ *   - Same durable persistence (errors survive crashes / hard closes)
+ *   - Same exponential backoff (a flapping server doesn't flood
+ *     errors past the rate limit)
+ *   - Same Idempotency-Key (duplicate batches dedup server-side)
+ *   - Same consent gate (consent.errors)
+ *   - Same PII scrub on properties before they leave
+ *
+ * Error sources captured (each toggleable):
+ *   1. window.onerror — uncaught synchronous errors
+ *   2. window.onunhandledrejection — unhandled promise rejections
+ *   3. fetch() wrap — HTTP errors the app code didn't catch
+ *   4. XMLHttpRequest wrap — same, for legacy XHR consumers
+ *   5. Crossdeck.captureError(err) — manual API for try/catch blocks
+ *   6. Crossdeck.captureMessage(msg) — non-error events you want to
+ *      surface as issues (e.g. "we hit the soft-deprecated path")
+ *
+ * Defensive design rules:
+ *   - The error handler must NEVER throw — if our own code crashes
+ *     while reporting an error, we'd take down the host app's error
+ *     handler too. Every callback is wrapped in try/swallow.
+ *   - Recursion guard: a `_reporting` flag prevents the SDK from
+ *     reporting its own errors recursively forever.
+ *   - Rate limited per-fingerprint: max N reports per second to defend
+ *     against runaway loops (e.g. an error in setInterval).
+ *   - Browser-extension noise is filtered by default — those errors
+ *     aren't the developer's fault and would otherwise drown the
+ *     signal.
+ */
+
+type ErrorLevel = "error" | "warning" | "info";
+interface CapturedError {
+    /** When the error fired (epoch ms). */
+    timestamp: number;
+    /** error.unhandled, error.unhandledrejection, error.handled, error.message, error.http */
+    kind: "error.unhandled" | "error.unhandledrejection" | "error.handled" | "error.message" | "error.http";
+    level: ErrorLevel;
+    message: string;
+    /** The error class name when we have it (TypeError, ReferenceError, etc.) */
+    errorType: string | null;
+    /** Parsed stack frames, empty when unavailable. */
+    frames: StackFrame[];
+    /** Raw stack string for fallback display. */
+    rawStack: string | null;
+    /** Origin URL when available (window.onerror's `source` arg). */
+    filename: string | null;
+    lineno: number | null;
+    colno: number | null;
+    /** djb2 hash of message + top frames — group identical errors. */
+    fingerprint: string;
+    /** Snapshot of the breadcrumb buffer at the moment the error fired. */
+    breadcrumbs: Breadcrumb[];
+    /** Free-form context attached via Crossdeck.setContext(). */
+    context: Record<string, unknown>;
+    /** Free-form tags attached via Crossdeck.setTag(). */
+    tags: Record<string, string>;
+    /** "TypeError: x is not a function" → "TypeError" + "x is not a function". */
+    /** Whether the error happened during a fetch / XHR. */
+    http?: {
+        url: string;
+        method: string;
+        status: number;
+        statusText?: string;
+    };
+}
+
 /**
  * Public API surface for @cross-deck/web.
  *
@@ -491,6 +645,63 @@ declare class CrossdeckClient {
     consent(state: Partial<ConsentState>): ConsentState;
     /** Snapshot of the current consent state. */
     consentStatus(): ConsentState;
+    /**
+     * Manually capture an error from a try/catch block.
+     *
+     *   try { …risky… } catch (err) {
+     *     Crossdeck.captureError(err, { context: { plan: "pro" } });
+     *   }
+     *
+     * The error is shipped through the same event queue as analytics
+     * (durable, retried, rate-limited per fingerprint). Sends are gated
+     * by `consent.errors`. Returns silently — never throws, even if the
+     * SDK isn't initialised yet.
+     */
+    captureError(error: unknown, options?: {
+        context?: Record<string, unknown>;
+        tags?: Record<string, string>;
+        level?: ErrorLevel;
+    }): void;
+    /**
+     * Capture a non-error event you want to surface as an issue
+     * ("deprecated path hit", "we entered the slow code path"). Sentry
+     * captureMessage pattern. Returns silently if not initialised.
+     */
+    captureMessage(message: string, level?: ErrorLevel): void;
+    /**
+     * Attach a tag to every subsequent error report. Tags are key/value
+     * strings (Sentry pattern): `setTag("flow", "checkout")` → every
+     * error from this point on carries `tags.flow === "checkout"`.
+     */
+    setTag(key: string, value: string): void;
+    /** Bulk-set tags. Merges with existing tags. */
+    setTags(tags: Record<string, string>): void;
+    /**
+     * Attach a structured context blob to every subsequent error report.
+     * Unlike tags (flat key/value), context is a named bag of arbitrary
+     * data: `setContext("cart", { items: 3, total: 42.99 })`.
+     */
+    setContext(name: string, data: Record<string, unknown>): void;
+    /**
+     * Add a custom breadcrumb to the rolling buffer. Useful for marking
+     * domain-meaningful moments ("user opened paywall") that aren't
+     * already auto-captured. The buffer caps at 50 entries; old ones
+     * evict.
+     */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /**
+     * Install a pre-send hook for errors. Return null to drop, or a
+     * modified CapturedError to scrub / rewrite. Sentry's beforeSend
+     * pattern — the only way to redact app-specific PII (auth tokens
+     * in URLs, etc.) before the report leaves the browser.
+     */
+    setErrorBeforeSend(hook: ((err: CapturedError) => CapturedError | null) | null): void;
+    /**
+     * Internal: turn a CapturedError into a Crossdeck event and enqueue
+     * it. Goes through the same queue / persistence / consent / scrub
+     * pipeline as analytics events.
+     */
+    private reportError;
     /**
      * GDPR/CCPA "right to be forgotten" — calls the backend's
      * /v1/identity/forget endpoint to schedule a server-side deletion of
@@ -744,7 +955,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.10.0";
+declare const SDK_VERSION = "1.0.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**
@@ -817,4 +1028,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, type AuditRail, type AutoTrackOptions, CROSSDECK_ERROR_CODES, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, getErrorCode };
+export { type AliasResult, type AuditRail, type AutoTrackOptions, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };

package/dist/index.d.ts

@@ -182,6 +182,17 @@ interface AutoTrackOptions {
      * (DataDog, Sentry Performance) and don't want duplicates.
      */
     webVitals: boolean;
+    /**
+     * Error capture (v1.0.0+) — installs window.onerror +
+     * window.onunhandledrejection listeners, wraps fetch + XHR to catch
+     * 5xx + network failures, ships each captured error as a Crossdeck
+     * event (kind: error.unhandled / error.unhandledrejection /
+     * error.handled / error.http / error.message). Errors gate on
+     * `consent.errors`. Rate-limited per-fingerprint so a runaway loop
+     * can't flood the queue; browser-extension noise filtered by
+     * default. Default true in browsers, no-op everywhere else.
+     */
+    errors: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -368,6 +379,149 @@ interface ConsentState {
     errors: boolean;
 }
 
+/**
+ * Breadcrumb ring buffer — context attached to every error report.
+ *
+ * Sentry / Datadog / Bugsnag all ship the same idea: keep a rolling
+ * record of the last N "things the user did" (page views, clicks,
+ * custom events, network calls, console logs). When an error fires,
+ * attach the buffer so the engineer reading the error can see exactly
+ * how the user got into the broken state. The single most powerful
+ * debugging signal in error monitoring — without breadcrumbs, errors
+ * are stack traces with no story.
+ *
+ * Implementation: a circular buffer with a fixed cap. Old entries are
+ * evicted as new ones arrive. The default cap (50) is enough to cover
+ * ~5 minutes of typical user activity without ballooning the error
+ * payload — Sentry uses 100 by default but the SDK is more aggressive
+ * about size since we ship breadcrumbs over the wire with every error,
+ * not as a separate batch.
+ *
+ * Privacy: breadcrumbs auto-emit from the same auto-tracking sources
+ * as analytics events (page.viewed, element.clicked). Those already
+ * skip password fields, form inputs, and cd-noTrack subtrees. Custom
+ * crumbs added via Crossdeck.addBreadcrumb() pass through the same
+ * property sanitiser as track() events.
+ */
+type BreadcrumbCategory = "navigation" | "ui.click" | "ui.input" | "http" | "console" | "custom" | "info";
+type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+interface Breadcrumb {
+    /** epoch ms */
+    timestamp: number;
+    category: BreadcrumbCategory;
+    level?: BreadcrumbLevel;
+    /** Short human-readable description. */
+    message?: string;
+    /** Arbitrary key/value context for the crumb. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
+ * stack strings into a common frame shape.
+ *
+ * Why hand-rolled, not stack-trace-js or error-stack-parser libraries:
+ * those weigh 5–15 KB after minification and we'd be pulling in their
+ * full feature matrix just for the parser. The patterns below cover
+ * the four shapes any modern browser emits, totalling ~80 lines.
+ *
+ * The output frame shape mirrors what Sentry's `mechanism: { type:
+ * 'generic' }` events ship, so future source-map symbolication on the
+ * Crossdeck backend has a stable input to work against.
+ *
+ * Defensive: never throws. An unparseable line becomes a `raw` frame
+ * with just the literal text. Engineers reading errors still get the
+ * raw stack as fallback.
+ */
+interface StackFrame {
+    /** Function name, or "?" if anonymous / unparseable. */
+    function: string;
+    /** Source file URL the frame ran in. Empty when unknown. */
+    filename: string;
+    /** 1-indexed line number, or 0 when unknown. */
+    lineno: number;
+    /** 1-indexed column number, or 0 when unknown. */
+    colno: number;
+    /**
+     * True when the frame is in the app's own code (best-effort:
+     * detected by URL not starting with chrome-extension://, etc.).
+     * Helps the dashboard's "your code vs library code" view.
+     */
+    in_app: boolean;
+    /** Raw line from the stack string for debugging when parse fails. */
+    raw: string;
+}
+
+/**
+ * Error capture — the third Crossdeck USP.
+ *
+ * Catches every error source the browser can hand us and ships them as
+ * Crossdeck events. The pipeline reuses the analytics queue:
+ *   - Same durable persistence (errors survive crashes / hard closes)
+ *   - Same exponential backoff (a flapping server doesn't flood
+ *     errors past the rate limit)
+ *   - Same Idempotency-Key (duplicate batches dedup server-side)
+ *   - Same consent gate (consent.errors)
+ *   - Same PII scrub on properties before they leave
+ *
+ * Error sources captured (each toggleable):
+ *   1. window.onerror — uncaught synchronous errors
+ *   2. window.onunhandledrejection — unhandled promise rejections
+ *   3. fetch() wrap — HTTP errors the app code didn't catch
+ *   4. XMLHttpRequest wrap — same, for legacy XHR consumers
+ *   5. Crossdeck.captureError(err) — manual API for try/catch blocks
+ *   6. Crossdeck.captureMessage(msg) — non-error events you want to
+ *      surface as issues (e.g. "we hit the soft-deprecated path")
+ *
+ * Defensive design rules:
+ *   - The error handler must NEVER throw — if our own code crashes
+ *     while reporting an error, we'd take down the host app's error
+ *     handler too. Every callback is wrapped in try/swallow.
+ *   - Recursion guard: a `_reporting` flag prevents the SDK from
+ *     reporting its own errors recursively forever.
+ *   - Rate limited per-fingerprint: max N reports per second to defend
+ *     against runaway loops (e.g. an error in setInterval).
+ *   - Browser-extension noise is filtered by default — those errors
+ *     aren't the developer's fault and would otherwise drown the
+ *     signal.
+ */
+
+type ErrorLevel = "error" | "warning" | "info";
+interface CapturedError {
+    /** When the error fired (epoch ms). */
+    timestamp: number;
+    /** error.unhandled, error.unhandledrejection, error.handled, error.message, error.http */
+    kind: "error.unhandled" | "error.unhandledrejection" | "error.handled" | "error.message" | "error.http";
+    level: ErrorLevel;
+    message: string;
+    /** The error class name when we have it (TypeError, ReferenceError, etc.) */
+    errorType: string | null;
+    /** Parsed stack frames, empty when unavailable. */
+    frames: StackFrame[];
+    /** Raw stack string for fallback display. */
+    rawStack: string | null;
+    /** Origin URL when available (window.onerror's `source` arg). */
+    filename: string | null;
+    lineno: number | null;
+    colno: number | null;
+    /** djb2 hash of message + top frames — group identical errors. */
+    fingerprint: string;
+    /** Snapshot of the breadcrumb buffer at the moment the error fired. */
+    breadcrumbs: Breadcrumb[];
+    /** Free-form context attached via Crossdeck.setContext(). */
+    context: Record<string, unknown>;
+    /** Free-form tags attached via Crossdeck.setTag(). */
+    tags: Record<string, string>;
+    /** "TypeError: x is not a function" → "TypeError" + "x is not a function". */
+    /** Whether the error happened during a fetch / XHR. */
+    http?: {
+        url: string;
+        method: string;
+        status: number;
+        statusText?: string;
+    };
+}
+
 /**
  * Public API surface for @cross-deck/web.
  *
@@ -491,6 +645,63 @@ declare class CrossdeckClient {
     consent(state: Partial<ConsentState>): ConsentState;
     /** Snapshot of the current consent state. */
     consentStatus(): ConsentState;
+    /**
+     * Manually capture an error from a try/catch block.
+     *
+     *   try { …risky… } catch (err) {
+     *     Crossdeck.captureError(err, { context: { plan: "pro" } });
+     *   }
+     *
+     * The error is shipped through the same event queue as analytics
+     * (durable, retried, rate-limited per fingerprint). Sends are gated
+     * by `consent.errors`. Returns silently — never throws, even if the
+     * SDK isn't initialised yet.
+     */
+    captureError(error: unknown, options?: {
+        context?: Record<string, unknown>;
+        tags?: Record<string, string>;
+        level?: ErrorLevel;
+    }): void;
+    /**
+     * Capture a non-error event you want to surface as an issue
+     * ("deprecated path hit", "we entered the slow code path"). Sentry
+     * captureMessage pattern. Returns silently if not initialised.
+     */
+    captureMessage(message: string, level?: ErrorLevel): void;
+    /**
+     * Attach a tag to every subsequent error report. Tags are key/value
+     * strings (Sentry pattern): `setTag("flow", "checkout")` → every
+     * error from this point on carries `tags.flow === "checkout"`.
+     */
+    setTag(key: string, value: string): void;
+    /** Bulk-set tags. Merges with existing tags. */
+    setTags(tags: Record<string, string>): void;
+    /**
+     * Attach a structured context blob to every subsequent error report.
+     * Unlike tags (flat key/value), context is a named bag of arbitrary
+     * data: `setContext("cart", { items: 3, total: 42.99 })`.
+     */
+    setContext(name: string, data: Record<string, unknown>): void;
+    /**
+     * Add a custom breadcrumb to the rolling buffer. Useful for marking
+     * domain-meaningful moments ("user opened paywall") that aren't
+     * already auto-captured. The buffer caps at 50 entries; old ones
+     * evict.
+     */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /**
+     * Install a pre-send hook for errors. Return null to drop, or a
+     * modified CapturedError to scrub / rewrite. Sentry's beforeSend
+     * pattern — the only way to redact app-specific PII (auth tokens
+     * in URLs, etc.) before the report leaves the browser.
+     */
+    setErrorBeforeSend(hook: ((err: CapturedError) => CapturedError | null) | null): void;
+    /**
+     * Internal: turn a CapturedError into a Crossdeck event and enqueue
+     * it. Goes through the same queue / persistence / consent / scrub
+     * pipeline as analytics events.
+     */
+    private reportError;
     /**
      * GDPR/CCPA "right to be forgotten" — calls the backend's
      * /v1/identity/forget endpoint to schedule a server-side deletion of
@@ -744,7 +955,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.10.0";
+declare const SDK_VERSION = "1.0.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**
@@ -817,4 +1028,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, type AuditRail, type AutoTrackOptions, CROSSDECK_ERROR_CODES, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, getErrorCode };
+export { type AliasResult, type AuditRail, type AutoTrackOptions, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };