@allstak/react 0.1.3 → 0.2.1

package/dist/index.d.ts

@@ -1 +1,552 @@
-export { AllStak, AllStakErrorBoundary, AllStakErrorBoundaryProps, useAllStak, withAllStakProfiler } from '@allstak/js/react';
+import * as React from 'react';
+
+/**
+ * Per-call scoped context isolation.
+ *
+ * A `Scope` carries the same shape as the top-level config (user, tags,
+ * extras, contexts, fingerprint, level) but only applies inside the
+ * `withScope` callback that owns it. The client merges the active scope
+ * stack on top of the base config when building each event payload, so:
+ *
+ *   - context set inside `withScope` does NOT leak out
+ *   - nested scopes layer additively (later wins on key conflicts)
+ *   - throwing or async work in the callback still pops the scope
+ *
+ * Use this on the server (SSR / RSC / API route handlers) to attach
+ * per-request user/tags without leaking that data into another request
+ * being processed concurrently.
+ */
+type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+declare class Scope {
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    tags: Record<string, string>;
+    extras: Record<string, unknown>;
+    contexts: Record<string, Record<string, unknown>>;
+    fingerprint?: string[];
+    level?: Severity;
+    setUser(user: {
+        id?: string;
+        email?: string;
+    }): this;
+    setTag(key: string, value: string): this;
+    setTags(tags: Record<string, string>): this;
+    setExtra(key: string, value: unknown): this;
+    setExtras(extras: Record<string, unknown>): this;
+    setContext(name: string, ctx: Record<string, unknown> | null): this;
+    setLevel(level: Severity): this;
+    setFingerprint(fingerprint: string[] | null): this;
+    clear(): this;
+}
+
+/**
+ * Minimal HTTP transport for React Native. Uses the global `fetch` (always
+ * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
+ * in-memory ring buffer that we retry on the next successful flush.
+ *
+ * No window, no AbortController fallback shims — RN exposes both natively.
+ */
+declare class HttpTransport {
+    private baseUrl;
+    private apiKey;
+    private buffer;
+    private flushing;
+    constructor(baseUrl: string, apiKey: string);
+    send(path: string, payload: unknown): Promise<void>;
+    private doFetch;
+    private flushBuffer;
+    getBufferSize(): number;
+    /**
+     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
+     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
+     * Useful at process exit / before navigation away.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+
+/**
+ * Lightweight distributed tracing primitives.
+ *
+ * A `Span` represents a unit of work — `startSpan('http.client', { description: 'GET /api/users' })`
+ * returns a Span; call `span.finish()` when the work completes. Spans
+ * batch into the transport's `/ingest/v1/spans` channel and ship every 5s
+ * (or when 20 spans accumulate).
+ *
+ * Trace propagation: each span carries a `traceId` (UUID, generated lazily
+ * on first call to `getTraceId()`) and a `spanId`. Nested calls to
+ * `startSpan()` automatically inherit the active span as their parent.
+ *
+ * Sampling: `tracesSampleRate` (config) gates whether `startSpan` actually
+ * records anything — drops when `Math.random() >= rate`. The returned
+ * Span is a no-op shim in that case so call sites don't need to null-check.
+ */
+
+interface SpanData {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+    operation: string;
+    description: string;
+    status: 'ok' | 'error' | 'timeout';
+    durationMs: number;
+    startTimeMillis: number;
+    endTimeMillis: number;
+    service: string;
+    environment: string;
+    tags: Record<string, string>;
+    data: string;
+}
+declare class Span {
+    private _traceId;
+    private _spanId;
+    private _parentSpanId;
+    private _operation;
+    private _description;
+    private _service;
+    private _environment;
+    private _tags;
+    private _onFinish;
+    private _finished;
+    private _startTimeMillis;
+    private _data;
+    constructor(_traceId: string, _spanId: string, _parentSpanId: string, _operation: string, _description: string, _service: string, _environment: string, _tags: Record<string, string>, _onFinish: (data: SpanData) => void);
+    setTag(key: string, value: string): this;
+    setData(data: string): this;
+    setDescription(description: string): this;
+    finish(status?: 'ok' | 'error' | 'timeout'): void;
+    get traceId(): string;
+    get spanId(): string;
+    get isFinished(): boolean;
+}
+
+/**
+ * Lightweight session-replay surrogate for the browser.
+ *
+ * **Status:** experimental. Captures DOM mutation events as a chronological
+ * log so a server-side replay viewer can reconstruct the visible page over
+ * time. Privacy-first defaults:
+ *
+ *   - all `<input>`, `<textarea>`, `<select>` values are masked by default
+ *   - elements with `data-allstak-mask` are entirely replaced with `***`
+ *   - `[type="password"]` is always masked, even with masking off
+ *   - `sampleRate` defaults to 0 — replay is OPT-IN per init
+ *
+ * NOT a drop-in replacement for full DOM-snapshot replay libraries — it
+ * does not record initial paint, window resizes, scroll positions, or
+ * canvas content. It records:
+ *
+ *   1. an initial sanitized DOM snapshot at start
+ *   2. mutations: childList add/remove + attributes (filtered)
+ *   3. user input events with values masked
+ *   4. a periodic flush of the buffered log to /ingest/v1/replay
+ *
+ * Because the wire format is a JSON event log (not a binary blob), payloads
+ * are larger than dedicated replay tools — appropriate for low-volume
+ * debugging, not for sampling 100% of production traffic.
+ */
+
+type AddBreadcrumbFn$2 = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
+interface ReplayOptions {
+    enabled?: boolean;
+    /** Probability per session that replay records. Default 0 (opt-in). */
+    sampleRate?: number;
+    /** Mask all text inputs / textareas / selects by default. Default true. */
+    maskAllInputs?: boolean;
+    /** Custom attribute name that flags an element to be masked. Default `data-allstak-mask`. */
+    maskAttribute?: string;
+    /** Max number of events buffered before forced flush. Default 200. */
+    maxBufferedEvents?: number;
+}
+interface ReplayEvent {
+    /** UNIX millis when the event was observed. */
+    ts: number;
+    /** event kind */
+    k: 'snap' | 'mut' | 'input' | 'nav';
+    /** Free-form JSON-friendly payload. */
+    data: Record<string, unknown>;
+}
+declare class ReplayRecorder {
+    private transport;
+    private addBreadcrumb;
+    private buffer;
+    private flushTimer;
+    private observer;
+    private inputListener;
+    private opts;
+    private sessionId;
+    private destroyed;
+    constructor(transport: HttpTransport, sessionId: string, addBreadcrumb: AddBreadcrumbFn$2, options?: ReplayOptions);
+    start(): void;
+    destroy(): void;
+    /** @internal — exposed for tests. */
+    getBuffer(): ReadonlyArray<ReplayEvent>;
+    private push;
+    private flush;
+    private snapshotBody;
+    private maskTree;
+    private maskInputValue;
+    private describeNode;
+    private describePath;
+    private safeAttribute;
+}
+
+/**
+ * Standalone AllStak client for the browser/React environment. No external
+ * AllStak SDK dependencies — only the browser's native `fetch`, AbortController,
+ * Date, JSON, and (optionally) `window` for unhandled error auto-capture.
+ *
+ * Surface mirrors the public AllStak API used by web apps:
+ *   init / captureException / captureMessage / addBreadcrumb / clearBreadcrumbs
+ *   setUser / setTag / setIdentity / getSessionId
+ */
+
+declare const INGEST_HOST = "https://api.allstak.sa";
+declare const SDK_NAME = "allstak-react";
+declare const SDK_VERSION = "0.2.1";
+
+interface AllStakConfig {
+    /** Project API key (`ask_live_…`). Required. */
+    apiKey: string;
+    /** Optional ingest host override; defaults to {@link INGEST_HOST}. */
+    host?: string;
+    environment?: string;
+    release?: string;
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    tags?: Record<string, string>;
+    /** Per-event extra data attached to every capture (override per call via context arg). */
+    extras?: Record<string, unknown>;
+    /** Named context bags (e.g. `app`, `device`). Each lives under `metadata['context.<name>']`. */
+    contexts?: Record<string, Record<string, unknown>>;
+    /**
+     * Default severity level for events that don't specify their own.
+     * Customer-set default severity, mirrors `setLevel`.
+     */
+    level?: 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+    /**
+     * Custom grouping fingerprint applied to every event. Customer-set grouping override —
+     * `setFingerprint`. Pass an empty array or `null` to clear.
+     */
+    fingerprint?: string[];
+    /** Probability in [0, 1] that any new span is recorded. Default 1. */
+    tracesSampleRate?: number;
+    /** Service name attached to every span (defaults to release if unset). */
+    service?: string;
+    maxBreadcrumbs?: number;
+    /** Auto-capture unhandled `error` and `unhandledrejection` on `window`. Default: true */
+    autoCaptureBrowserErrors?: boolean;
+    /** Wrap `globalThis.fetch` to record HTTP breadcrumbs. Default: true */
+    autoBreadcrumbsFetch?: boolean;
+    /** Wrap `console.warn` and `console.error` to record log breadcrumbs. Default: true */
+    autoBreadcrumbsConsole?: boolean;
+    /** Wrap `history.pushState`/`replaceState` and listen to `popstate` for SPA navigation breadcrumbs. Default: true */
+    autoBreadcrumbsNavigation?: boolean;
+    /**
+     * Experimental session-replay surrogate. **Off by default.** Enable with
+     * `replay: { sampleRate: 0.1 }`. Captures sanitized initial DOM snapshot +
+     * subsequent mutations + masked input events. See `src/replay.ts` for
+     * the full privacy contract.
+     */
+    replay?: ReplayOptions;
+    /**
+     * Probability in [0, 1] that any given error is sent. Default: 1 (no sampling).
+     * Applied per event before {@link beforeSend}.
+     */
+    sampleRate?: number;
+    /**
+     * Mutate or drop an event before it is sent. Return `null` (or a falsy
+     * value) to drop. Sync or async. Errors thrown inside the hook are caught
+     * — the event is sent as-is so a buggy hook can't black-hole telemetry.
+     */
+    beforeSend?: (event: ErrorIngestPayload) => ErrorIngestPayload | null | undefined | Promise<ErrorIngestPayload | null | undefined>;
+    /** SDK identity overrides. */
+    sdkName?: string;
+    sdkVersion?: string;
+    platform?: string;
+    dist?: string;
+    commitSha?: string;
+    branch?: string;
+}
+interface Breadcrumb {
+    timestamp: string;
+    type: string;
+    message: string;
+    level: string;
+    data?: Record<string, unknown>;
+}
+interface PayloadFrame {
+    filename?: string;
+    absPath?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    inApp?: boolean;
+    platform?: string;
+    debugId?: string;
+}
+interface ErrorIngestPayload {
+    exceptionClass: string;
+    message: string;
+    stackTrace?: string[];
+    frames?: PayloadFrame[];
+    platform?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+    dist?: string;
+    level: string;
+    environment?: string;
+    release?: string;
+    sessionId?: string;
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    metadata?: Record<string, unknown>;
+    breadcrumbs?: Breadcrumb[];
+    requestContext?: {
+        method?: string;
+        path?: string;
+        host?: string;
+        userAgent?: string;
+    };
+    fingerprint?: string[];
+}
+declare class AllStakClient {
+    private transport;
+    private config;
+    private sessionId;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    private scopeStack;
+    private tracing;
+    private replay;
+    private onErrorHandler;
+    private onRejectionHandler;
+    constructor(config: AllStakConfig);
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    /** Start a new span — auto-parented to any currently-active span. */
+    startSpan(operation: string, options?: {
+        description?: string;
+        tags?: Record<string, string>;
+    }): Span;
+    /** Get (and lazily create) the active trace ID. */
+    getTraceId(): string;
+    /** Override the active trace ID, e.g. from an inbound request header. */
+    setTraceId(traceId: string): void;
+    /** ID of the currently-active span, or null. */
+    getCurrentSpanId(): string | null;
+    /** Reset the trace ID and the active span stack. */
+    resetTrace(): void;
+    captureMessage(message: string, level?: 'fatal' | 'error' | 'warning' | 'info', options?: {
+        as?: 'log' | 'error' | 'both';
+    }): void;
+    addBreadcrumb(type: string, message: string, level?: string, data?: Record<string, unknown>): void;
+    clearBreadcrumbs(): void;
+    setUser(user: {
+        id?: string;
+        email?: string;
+    }): void;
+    setTag(key: string, value: string): void;
+    /** Bulk-set tags. Merges with existing tags. */
+    setTags(tags: Record<string, string>): void;
+    /** Set a single extra value. */
+    setExtra(key: string, value: unknown): void;
+    /** Bulk-set extras. Merges with existing extras. */
+    setExtras(extras: Record<string, unknown>): void;
+    /**
+     * Attach a named context bag (e.g. `app`, `device`, `runtime`) — appears
+     * under `metadata['context.<name>']` on every subsequent event. Pass
+     * `null` to remove a previously-set context.
+     */
+    setContext(name: string, ctx: Record<string, unknown> | null): void;
+    /**
+     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
+     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+    /** Set the default severity level applied to subsequent captures. */
+    setLevel(level: 'fatal' | 'error' | 'warning' | 'info' | 'debug'): void;
+    /**
+     * Set a custom grouping fingerprint applied to subsequent events.
+     * Pass `null` or an empty array to clear and revert to default grouping.
+     */
+    setFingerprint(fingerprint: string[] | null): void;
+    setIdentity(identity: {
+        sdkName?: string;
+        sdkVersion?: string;
+        platform?: string;
+        dist?: string;
+    }): void;
+    getSessionId(): string;
+    getConfig(): AllStakConfig;
+    destroy(): void;
+    private installBrowserHandlers;
+    private sendLog;
+    private passesSampleRate;
+    /**
+     * Returns the effective config layer = base config + every active scope.
+     * Scope-only overrides (set inside `withScope`) flow into the wire
+     * payload without leaking out of the callback.
+     */
+    private effective;
+    private buildMetadata;
+    /**
+     * Run `callback` with a fresh, temporary {@link Scope} that isolates
+     * any user/tag/extra/context/fingerprint/level it sets. The scope is
+     * popped automatically when the callback returns or throws — including
+     * for `Promise`-returning callbacks (the pop runs in `.finally`).
+     *
+     * Use this on the server (SSR / RSC / API route handlers) to attach
+     * per-request user/tags without leaking that data into another request
+     * being processed concurrently.
+     */
+    withScope<T>(callback: (scope: Scope) => T): T;
+    /** Direct access to the topmost active scope, or null. @internal */
+    getCurrentScope(): Scope | null;
+    private sendThroughBeforeSend;
+    private releaseTags;
+}
+declare const AllStak: {
+    init(config: AllStakConfig): AllStakClient;
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    captureMessage(message: string, level?: "fatal" | "error" | "warning" | "info", options?: {
+        as?: "log" | "error" | "both";
+    }): void;
+    addBreadcrumb(type: string, message: string, level?: string, data?: Record<string, unknown>): void;
+    clearBreadcrumbs(): void;
+    setUser(user: {
+        id?: string;
+        email?: string;
+    }): void;
+    setTag(key: string, value: string): void;
+    setTags(tags: Record<string, string>): void;
+    setExtra(key: string, value: unknown): void;
+    setExtras(extras: Record<string, unknown>): void;
+    setContext(name: string, ctx: Record<string, unknown> | null): void;
+    setLevel(level: "fatal" | "error" | "warning" | "info" | "debug"): void;
+    setFingerprint(fingerprint: string[] | null): void;
+    flush(timeoutMs?: number): Promise<boolean>;
+    setIdentity(identity: {
+        sdkName?: string;
+        sdkVersion?: string;
+        platform?: string;
+        dist?: string;
+    }): void;
+    /**
+     * Run `callback` with a fresh, temporary {@link Scope}. Any user/tag/
+     * extra/context/fingerprint/level set on the scope is visible only inside
+     * the callback. Pop is automatic (sync, async, throwing).
+     */
+    withScope<T>(callback: (scope: Scope) => T): T;
+    startSpan(operation: string, options?: {
+        description?: string;
+        tags?: Record<string, string>;
+    }): Span;
+    getTraceId(): string;
+    setTraceId(traceId: string): void;
+    getCurrentSpanId(): string | null;
+    resetTrace(): void;
+    getSessionId(): string;
+    getConfig(): AllStakConfig | null;
+    destroy(): void;
+    /** @internal */ _getInstance(): AllStakClient | null;
+};
+
+/**
+ * Browser navigation breadcrumbs — minimal fallback that doesn't depend on
+ * any specific router library. Wraps `history.pushState`/`replaceState` and
+ * listens to `popstate` so SPA navigation transitions appear in the
+ * breadcrumb feed regardless of which router (React Router, Next, Remix,
+ * none) the app uses.
+ *
+ * Idempotent — calling twice is safe (the wrappers tag themselves).
+ *
+ * For framework-specific instrumentation (React Router's `useNavigate`,
+ * Next's `router.events`), bind manually with `AllStak.addBreadcrumb`.
+ */
+type AddBreadcrumbFn$1 = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
+declare function instrumentBrowserNavigation(addBreadcrumb: AddBreadcrumbFn$1): void;
+declare function instrumentReactRouter(location: {
+    pathname: string;
+    search?: string;
+}, addBreadcrumb?: AddBreadcrumbFn$1): void;
+declare function instrumentNextRouter(url: string, addBreadcrumb?: AddBreadcrumbFn$1): void;
+
+/**
+ * Idempotent instrumentation of `globalThis.fetch` and `console.warn/error`
+ * to feed breadcrumbs into the AllStak client. Safe to call once at init.
+ *
+ * - `instrumentFetch`: wraps fetch and records a breadcrumb per request
+ *   (success and failure). Skips requests targeting the SDK's own ingest
+ *   host so the wrap never recurses. Preserves the original return type
+ *   and rethrows fetch errors after the breadcrumb is recorded.
+ * - `instrumentConsole`: wraps `console.warn` and `console.error` to
+ *   record `log`-type breadcrumbs at the corresponding level.
+ *
+ * Both patches use a flag on the wrapper function so a second call is a
+ * no-op — important because hot-module-reload in dev would otherwise
+ * stack patches and double-fire breadcrumbs.
+ */
+type AddBreadcrumbFn = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
+declare function instrumentFetch(addBreadcrumb: AddBreadcrumbFn, ownBaseUrl?: string): void;
+declare function instrumentConsole(addBreadcrumb: AddBreadcrumbFn): void;
+
+/**
+ * @allstak/react — standalone React SDK.
+ *
+ * Self-contained: no @allstak/js or @allstak-io/* dependencies. Ships its own
+ * AllStak client (init/capture/breadcrumbs/transport) plus React-specific
+ * helpers (ErrorBoundary, useAllStak hook, withAllStakProfiler HOC).
+ *
+ * Usage:
+ *   AllStak.init({ apiKey, environment, release });
+ *   <AllStakErrorBoundary>...</AllStakErrorBoundary>
+ *   const { captureException } = useAllStak();
+ */
+
+interface AllStakErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode | ((props: {
+        error: Error;
+        reset: () => void;
+    }) => React.ReactNode);
+    /** Extra tags attached only to errors captured by this boundary. */
+    tags?: Record<string, string>;
+    /** Called after the error has been captured. */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+interface AllStakErrorBoundaryState {
+    error: Error | null;
+}
+declare class AllStakErrorBoundary extends React.Component<AllStakErrorBoundaryProps, AllStakErrorBoundaryState> {
+    state: AllStakErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): AllStakErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    private reset;
+    render(): React.ReactNode;
+}
+/**
+ * Convenience hook — exposes the most common capture/context APIs with a
+ * stable identity so components don't have to import the namespace.
+ */
+declare function useAllStak(): {
+    captureException: (error: Error, ctx?: Record<string, unknown>) => void;
+    captureMessage: (msg: string, level?: "fatal" | "error" | "warning" | "info") => void;
+    setUser: (user: {
+        id?: string;
+        email?: string;
+    }) => void;
+    setTag: (key: string, value: string) => void;
+    addBreadcrumb: (type: string, message: string, level?: string, data?: Record<string, unknown>) => void;
+};
+/**
+ * HOC: drops a navigation breadcrumb when a component mounts. Useful for
+ * marking screen boundaries without a router.
+ */
+declare function withAllStakProfiler<P extends object>(Component: React.ComponentType<P>, name?: string): React.FC<P>;
+
+export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };