@usereelay/browser 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,264 @@
+/**
+ * Wire types — mirror reelay-backend's ingest contract exactly
+ * (POST /api/ingest/errors, POST /api/ingest/sessions).
+ */
+interface StackFrame {
+    file: string;
+    line: number;
+    col?: number;
+    function?: string;
+    module?: string;
+    in_app: boolean;
+    /**
+     * Full minified script URL (before origin-stripping). The backend uses it as
+     * the release-scoped source-map match key; omitted for non-URL frames.
+     */
+    abs_path?: string;
+    /**
+     * Debug id of the bundle this frame belongs to, resolved at capture time from
+     * the build-injected debug-id registry. The unambiguous source-map match key.
+     */
+    debug_id?: string;
+}
+interface ExceptionPayload {
+    type: string;
+    value: string;
+    mechanism?: string;
+    stacktrace?: StackFrame[];
+}
+interface TraceContext {
+    trace_id: string;
+    span_id?: string;
+}
+interface HTTPContext {
+    method: string;
+    url: string;
+    status_code?: number;
+    headers?: Record<string, string>;
+}
+interface TimelineLog {
+    ts: string;
+    level: string;
+    msg: string;
+}
+interface TimelineSpan {
+    span_id: string;
+    name: string;
+    status?: string;
+}
+interface Timeline {
+    logs?: TimelineLog[];
+    spans?: TimelineSpan[];
+}
+interface Breadcrumb {
+    timestamp: number;
+    type: string;
+    category?: string;
+    message?: string;
+}
+interface ErrorEventPayload {
+    event_id: string;
+    kind: 'backend' | 'frontend';
+    platform: string;
+    timestamp: string;
+    release?: string;
+    environment?: string;
+    trace?: TraceContext;
+    session_id?: string;
+    exception: ExceptionPayload;
+    http?: HTTPContext;
+    timeline?: Timeline;
+    breadcrumbs?: Breadcrumb[];
+}
+/** Options shared by every Reelay SDK. */
+interface CoreOptions {
+    /** Ingestion base URL, e.g. https://api.reelay.app */
+    endpoint: string;
+    /** The node's API key (rlyt_live_…). Never a ReelayID. */
+    token: string;
+    release?: string;
+    environment?: string;
+    /** 0–1 probability an error event is sent. Defaults to 1. */
+    sampleRate?: number;
+    /** Mutate or veto an event just before send. Return null to drop. */
+    beforeSend?: (event: ErrorEventPayload) => ErrorEventPayload | null;
+    /** Extra scrub patterns applied to all string values. */
+    scrubPatterns?: RegExp[];
+    /** Maximum buffered events while offline/rate-limited. Default 30. */
+    maxQueueSize?: number;
+    /** Emit SDK-internal diagnostics through this hook (never console by default). */
+    debug?: (message: string, detail?: unknown) => void;
+}
+
+/**
+ * Fixed-capacity ring buffer for breadcrumbs: O(1) add, bounded memory, no
+ * allocation churn. The most recent `capacity` crumbs are kept.
+ */
+declare class BreadcrumbBuffer {
+    private readonly capacity;
+    private readonly items;
+    private head;
+    private size;
+    constructor(capacity?: number);
+    add(crumb: Breadcrumb): void;
+    /** Oldest → newest snapshot. */
+    snapshot(): Breadcrumb[];
+    clear(): void;
+}
+
+/**
+ * Client-side PII scrubbing. Runs before any payload leaves the host
+ * application (CLAUDE.md §6): secrets must never reach the wire.
+ */
+declare class Scrubber {
+    private readonly patterns;
+    constructor(extraPatterns?: RegExp[]);
+    scrubString(value: string): string;
+    /**
+     * Deep-scrubs any JSON-serializable value: sensitive keys are redacted
+     * wholesale; remaining strings run through the pattern engine. Depth-capped
+     * and cycle-safe — scrubbing must never throw or hang the host app.
+     */
+    scrub<T>(value: T): T;
+    private walk;
+}
+
+/**
+ * Resilient, non-blocking transport (CLAUDE.md §4):
+ *  - never throws into the host application;
+ *  - bounded in-memory retry queue (drop-oldest, never block);
+ *  - exponential backoff with full jitter;
+ *  - honors 429 Retry-After;
+ *  - drops (never retries) 4xx payload errors — they will never succeed.
+ */
+interface TransportOptions {
+    url: string;
+    token: string;
+    maxQueueSize: number;
+    /** Injectable for tests and for sendBeacon-style senders. */
+    fetchImpl?: typeof fetch;
+    debug?: (message: string, detail?: unknown) => void;
+}
+declare class Transport {
+    private readonly opts;
+    private readonly queue;
+    private flushPromise;
+    private pausedUntil;
+    constructor(opts: TransportOptions);
+    /** Number of payloads waiting to be delivered (for flush/drain logic). */
+    get pending(): number;
+    /**
+     * Enqueues a payload and schedules an async flush. Never blocks, never
+     * throws. When the queue is full the OLDEST item is dropped — fresh errors
+     * are worth more than stale ones.
+     */
+    send(payload: unknown): void;
+    /**
+     * Drains the queue. Concurrent calls share the single running flush loop —
+     * awaiting flush() always waits for the actual drain (page unload and
+     * process exit depend on this).
+     */
+    flush(): Promise<void>;
+    private drain;
+    private deliver;
+}
+
+interface CaptureContext {
+    mechanism?: string;
+    trace?: TraceContext;
+    sessionId?: string;
+    http?: HTTPContext;
+    timeline?: Timeline;
+}
+/**
+ * BaseClient holds the behavior both runtimes share: event assembly,
+ * sampling, scrubbing, beforeSend, breadcrumbs, transport. Platform SDKs
+ * subclass it and add their instrumentation. Every public method is wrapped
+ * so the SDK can never throw into the host application (CLAUDE.md §4).
+ */
+declare class BaseClient {
+    protected readonly options: CoreOptions;
+    protected readonly transport: Transport;
+    protected readonly scrubber: Scrubber;
+    protected readonly crumbs: BreadcrumbBuffer;
+    private readonly kind;
+    private readonly platform;
+    constructor(options: CoreOptions, kind: 'backend' | 'frontend', platform: string);
+    /** Records a breadcrumb (scrubbed, bounded). Safe to call from anywhere. */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /** Captures any thrown value. Returns the event id ('' when dropped). */
+    captureException(err: unknown, ctx?: CaptureContext): string;
+    /**
+     * Hook invoked after an error event is accepted for sending. Subclasses use
+     * it to attach side data to the captured event — e.g. the browser SDK flushes
+     * the buffered session replay clip for this error id. No-op by default.
+     */
+    protected afterCapture(_eventId: string): void;
+    /** Captures a plain message as an error event. */
+    captureMessage(message: string, ctx?: CaptureContext): string;
+    /** Drains pending events (call before process exit / page hide). */
+    flush(): Promise<void>;
+    /**
+     * Runs fn inside the SDK's defensive boundary: internal failures are
+     * reported to the debug hook and swallowed — never the host's problem.
+     */
+    protected guard<T>(fn: () => T): T | undefined;
+    private sampled;
+}
+
+interface BrowserOptions extends CoreOptions {
+    /**
+     * First-party origins that receive `traceparent` + `reelay-session-id`
+     * headers on outgoing fetch/XHR — the stitching allow-list (FRD E3.2).
+     * Origins only; never send trace headers cross-origin by default.
+     */
+    tracePropagationTargets?: (string | RegExp)[];
+    /** Record DOM session replay. Default true. */
+    replay?: boolean;
+    /** Mask all text content in replay. Default true (PII-safe by default). */
+    maskAllText?: boolean;
+}
+declare class BrowserClient extends BaseClient {
+    readonly sessionId: string;
+    private readonly browserOptions;
+    private readonly tracedRequests;
+    private replayRecorder?;
+    private teardowns;
+    constructor(options: BrowserOptions);
+    install(): void;
+    uninstall(): void;
+    /** Captures with the browser session attached. */
+    capture(err: unknown, mechanism: string, trace?: TraceContext): string;
+    /**
+     * After an error is captured, flush the buffered rrweb replay clip for it —
+     * the ~30–60s of session leading up to this error, stored under a per-error
+     * replay id the dashboard reconstructs from the error event.
+     */
+    protected afterCapture(eventId: string): void;
+    /** Decides whether an outgoing request URL gets trace headers. */
+    shouldPropagate(url: string): boolean;
+    /** Mints a trace context for an outgoing request and remembers it. */
+    startRequestTrace(url: string): {
+        headers: Record<string, string>;
+        trace: TraceContext;
+    };
+}
+
+/**
+ * Initializes the Reelay browser SDK once per page.
+ *
+ * ```ts
+ * import * as Reelay from '@usereelay/browser';
+ * Reelay.init({
+ *   endpoint: 'https://api.reelay.app',
+ *   token: 'rlyt_live_…',
+ *   tracePropagationTargets: ['https://api.acme.com'],
+ * });
+ * ```
+ */
+declare function init(options: BrowserOptions): BrowserClient;
+declare function getClient(): BrowserClient | undefined;
+declare function captureException(err: unknown): string;
+declare function captureMessage(message: string): string;
+
+export { type Breadcrumb, BrowserClient, type BrowserOptions, type CoreOptions, type ErrorEventPayload, captureException, captureMessage, getClient, init };

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Wire types — mirror reelay-backend's ingest contract exactly
+ * (POST /api/ingest/errors, POST /api/ingest/sessions).
+ */
+interface StackFrame {
+    file: string;
+    line: number;
+    col?: number;
+    function?: string;
+    module?: string;
+    in_app: boolean;
+    /**
+     * Full minified script URL (before origin-stripping). The backend uses it as
+     * the release-scoped source-map match key; omitted for non-URL frames.
+     */
+    abs_path?: string;
+    /**
+     * Debug id of the bundle this frame belongs to, resolved at capture time from
+     * the build-injected debug-id registry. The unambiguous source-map match key.
+     */
+    debug_id?: string;
+}
+interface ExceptionPayload {
+    type: string;
+    value: string;
+    mechanism?: string;
+    stacktrace?: StackFrame[];
+}
+interface TraceContext {
+    trace_id: string;
+    span_id?: string;
+}
+interface HTTPContext {
+    method: string;
+    url: string;
+    status_code?: number;
+    headers?: Record<string, string>;
+}
+interface TimelineLog {
+    ts: string;
+    level: string;
+    msg: string;
+}
+interface TimelineSpan {
+    span_id: string;
+    name: string;
+    status?: string;
+}
+interface Timeline {
+    logs?: TimelineLog[];
+    spans?: TimelineSpan[];
+}
+interface Breadcrumb {
+    timestamp: number;
+    type: string;
+    category?: string;
+    message?: string;
+}
+interface ErrorEventPayload {
+    event_id: string;
+    kind: 'backend' | 'frontend';
+    platform: string;
+    timestamp: string;
+    release?: string;
+    environment?: string;
+    trace?: TraceContext;
+    session_id?: string;
+    exception: ExceptionPayload;
+    http?: HTTPContext;
+    timeline?: Timeline;
+    breadcrumbs?: Breadcrumb[];
+}
+/** Options shared by every Reelay SDK. */
+interface CoreOptions {
+    /** Ingestion base URL, e.g. https://api.reelay.app */
+    endpoint: string;
+    /** The node's API key (rlyt_live_…). Never a ReelayID. */
+    token: string;
+    release?: string;
+    environment?: string;
+    /** 0–1 probability an error event is sent. Defaults to 1. */
+    sampleRate?: number;
+    /** Mutate or veto an event just before send. Return null to drop. */
+    beforeSend?: (event: ErrorEventPayload) => ErrorEventPayload | null;
+    /** Extra scrub patterns applied to all string values. */
+    scrubPatterns?: RegExp[];
+    /** Maximum buffered events while offline/rate-limited. Default 30. */
+    maxQueueSize?: number;
+    /** Emit SDK-internal diagnostics through this hook (never console by default). */
+    debug?: (message: string, detail?: unknown) => void;
+}
+
+/**
+ * Fixed-capacity ring buffer for breadcrumbs: O(1) add, bounded memory, no
+ * allocation churn. The most recent `capacity` crumbs are kept.
+ */
+declare class BreadcrumbBuffer {
+    private readonly capacity;
+    private readonly items;
+    private head;
+    private size;
+    constructor(capacity?: number);
+    add(crumb: Breadcrumb): void;
+    /** Oldest → newest snapshot. */
+    snapshot(): Breadcrumb[];
+    clear(): void;
+}
+
+/**
+ * Client-side PII scrubbing. Runs before any payload leaves the host
+ * application (CLAUDE.md §6): secrets must never reach the wire.
+ */
+declare class Scrubber {
+    private readonly patterns;
+    constructor(extraPatterns?: RegExp[]);
+    scrubString(value: string): string;
+    /**
+     * Deep-scrubs any JSON-serializable value: sensitive keys are redacted
+     * wholesale; remaining strings run through the pattern engine. Depth-capped
+     * and cycle-safe — scrubbing must never throw or hang the host app.
+     */
+    scrub<T>(value: T): T;
+    private walk;
+}
+
+/**
+ * Resilient, non-blocking transport (CLAUDE.md §4):
+ *  - never throws into the host application;
+ *  - bounded in-memory retry queue (drop-oldest, never block);
+ *  - exponential backoff with full jitter;
+ *  - honors 429 Retry-After;
+ *  - drops (never retries) 4xx payload errors — they will never succeed.
+ */
+interface TransportOptions {
+    url: string;
+    token: string;
+    maxQueueSize: number;
+    /** Injectable for tests and for sendBeacon-style senders. */
+    fetchImpl?: typeof fetch;
+    debug?: (message: string, detail?: unknown) => void;
+}
+declare class Transport {
+    private readonly opts;
+    private readonly queue;
+    private flushPromise;
+    private pausedUntil;
+    constructor(opts: TransportOptions);
+    /** Number of payloads waiting to be delivered (for flush/drain logic). */
+    get pending(): number;
+    /**
+     * Enqueues a payload and schedules an async flush. Never blocks, never
+     * throws. When the queue is full the OLDEST item is dropped — fresh errors
+     * are worth more than stale ones.
+     */
+    send(payload: unknown): void;
+    /**
+     * Drains the queue. Concurrent calls share the single running flush loop —
+     * awaiting flush() always waits for the actual drain (page unload and
+     * process exit depend on this).
+     */
+    flush(): Promise<void>;
+    private drain;
+    private deliver;
+}
+
+interface CaptureContext {
+    mechanism?: string;
+    trace?: TraceContext;
+    sessionId?: string;
+    http?: HTTPContext;
+    timeline?: Timeline;
+}
+/**
+ * BaseClient holds the behavior both runtimes share: event assembly,
+ * sampling, scrubbing, beforeSend, breadcrumbs, transport. Platform SDKs
+ * subclass it and add their instrumentation. Every public method is wrapped
+ * so the SDK can never throw into the host application (CLAUDE.md §4).
+ */
+declare class BaseClient {
+    protected readonly options: CoreOptions;
+    protected readonly transport: Transport;
+    protected readonly scrubber: Scrubber;
+    protected readonly crumbs: BreadcrumbBuffer;
+    private readonly kind;
+    private readonly platform;
+    constructor(options: CoreOptions, kind: 'backend' | 'frontend', platform: string);
+    /** Records a breadcrumb (scrubbed, bounded). Safe to call from anywhere. */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /** Captures any thrown value. Returns the event id ('' when dropped). */
+    captureException(err: unknown, ctx?: CaptureContext): string;
+    /**
+     * Hook invoked after an error event is accepted for sending. Subclasses use
+     * it to attach side data to the captured event — e.g. the browser SDK flushes
+     * the buffered session replay clip for this error id. No-op by default.
+     */
+    protected afterCapture(_eventId: string): void;
+    /** Captures a plain message as an error event. */
+    captureMessage(message: string, ctx?: CaptureContext): string;
+    /** Drains pending events (call before process exit / page hide). */
+    flush(): Promise<void>;
+    /**
+     * Runs fn inside the SDK's defensive boundary: internal failures are
+     * reported to the debug hook and swallowed — never the host's problem.
+     */
+    protected guard<T>(fn: () => T): T | undefined;
+    private sampled;
+}
+
+interface BrowserOptions extends CoreOptions {
+    /**
+     * First-party origins that receive `traceparent` + `reelay-session-id`
+     * headers on outgoing fetch/XHR — the stitching allow-list (FRD E3.2).
+     * Origins only; never send trace headers cross-origin by default.
+     */
+    tracePropagationTargets?: (string | RegExp)[];
+    /** Record DOM session replay. Default true. */
+    replay?: boolean;
+    /** Mask all text content in replay. Default true (PII-safe by default). */
+    maskAllText?: boolean;
+}
+declare class BrowserClient extends BaseClient {
+    readonly sessionId: string;
+    private readonly browserOptions;
+    private readonly tracedRequests;
+    private replayRecorder?;
+    private teardowns;
+    constructor(options: BrowserOptions);
+    install(): void;
+    uninstall(): void;
+    /** Captures with the browser session attached. */
+    capture(err: unknown, mechanism: string, trace?: TraceContext): string;
+    /**
+     * After an error is captured, flush the buffered rrweb replay clip for it —
+     * the ~30–60s of session leading up to this error, stored under a per-error
+     * replay id the dashboard reconstructs from the error event.
+     */
+    protected afterCapture(eventId: string): void;
+    /** Decides whether an outgoing request URL gets trace headers. */
+    shouldPropagate(url: string): boolean;
+    /** Mints a trace context for an outgoing request and remembers it. */
+    startRequestTrace(url: string): {
+        headers: Record<string, string>;
+        trace: TraceContext;
+    };
+}
+
+/**
+ * Initializes the Reelay browser SDK once per page.
+ *
+ * ```ts
+ * import * as Reelay from '@usereelay/browser';
+ * Reelay.init({
+ *   endpoint: 'https://api.reelay.app',
+ *   token: 'rlyt_live_…',
+ *   tracePropagationTargets: ['https://api.acme.com'],
+ * });
+ * ```
+ */
+declare function init(options: BrowserOptions): BrowserClient;
+declare function getClient(): BrowserClient | undefined;
+declare function captureException(err: unknown): string;
+declare function captureMessage(message: string): string;
+
+export { type Breadcrumb, BrowserClient, type BrowserOptions, type CoreOptions, type ErrorEventPayload, captureException, captureMessage, getClient, init };