@allstak/react-native 0.1.3 → 0.3.1

package/dist/index.d.mts

@@ -1 +1,873 @@
-export { AllStak, ReactNativeInstallOptions, installReactNative } from '@allstak/js/react-native';
+import * as React from 'react';
+
+/**
+ * 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 before navigation away or during native crash drain.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+
+/**
+ * HTTP request batching + transport for the React Native SDK.
+ *
+ * Mirrors the wire shape used by `@allstak/js`'s HttpRequestModule so the
+ * existing backend ingest endpoint (`/ingest/v1/http-requests`) accepts
+ * events from this SDK without a schema change. Adds optional rich fields
+ * (headers, bodies, error string) — these ride alongside the existing
+ * required fields and are tolerated as additive metadata server-side.
+ *
+ * Batching:
+ *   - flushes on a 5s timer OR when 20 events queue up
+ *   - flushes immediately on `destroy()`
+ *   - `getRecentFailed(n)` returns the last n failed requests (statusCode
+ *     >= 400 OR error set), used by error-linking on the next captureException
+ */
+
+/** What instrumentation hands to the module per request. */
+interface HttpRequestEvent {
+    type: 'http_request';
+    method: string;
+    url: string;
+    statusCode?: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    traceId?: string;
+}
+interface HttpRequestIngestItem {
+    type: 'http_request';
+    traceId: string;
+    direction: 'outbound';
+    method: string;
+    host: string;
+    path: string;
+    url: string;
+    statusCode: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    'sdk.name'?: string;
+    'sdk.version'?: string;
+    timestamp: string;
+}
+interface ModuleDefaults {
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+}
+declare class HttpRequestModule {
+    private transport;
+    private queue;
+    private recentFailed;
+    private flushTimer;
+    private destroyed;
+    private defaults;
+    constructor(transport: HttpTransport);
+    setDefaults(defaults: ModuleDefaults): void;
+    capture(ev: HttpRequestEvent): void;
+    /** Snapshot of the last failed requests for error-linking. Newest last. */
+    getRecentFailed(): ReadonlyArray<HttpRequestIngestItem>;
+    flush(): void;
+    destroy(): void;
+    /** @internal — for tests. */
+    getQueueSize(): number;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * React Native "replay surrogate" — a privacy-first view-state breadcrumb
+ * recorder for environments where binary screen capture isn't available
+ * (Expo Go, JS-only test runners, or apps that can't link a native module
+ * for legal/compliance reasons).
+ *
+ * **What it captures (chronological, opt-in via sampleRate):**
+ *   - the active route name on every navigation event
+ *   - AppState foreground/background transitions (already covered by
+ *     installReactNative's AppState breadcrumb wiring — we reuse that)
+ *   - explicit `recordScreenView(name, params)` calls from the host app
+ *     (used by router integrations or manual checkpoints)
+ *
+ * **What it intentionally does NOT capture:**
+ *   - any user input values (text fields, password inputs, search queries)
+ *   - any rendered text content from the visible screen
+ *   - screenshots of any kind
+ *   - URL path parameters by default (only the route name + opt-in `safeParams`)
+ *
+ * Hard rule: by default `safeParams` is `[]` and route params are dropped.
+ * Callers must explicitly enumerate which param keys are safe to log.
+ */
+
+interface ReplaySurrogateOptions {
+    enabled?: boolean;
+    /** Probability in [0, 1] per session that recording happens. Default 0 (opt-in). */
+    sampleRate?: number;
+    /**
+     * Whitelist of route-param keys that are safe to record alongside the
+     * route name. Anything not on this list is dropped. Default `[]`.
+     */
+    safeParams?: string[];
+    /** Max events buffered before forced flush. Default 200. */
+    maxBufferedEvents?: number;
+}
+interface SurrogateEvent {
+    ts: number;
+    k: 'screen' | 'appstate' | 'manual';
+    data: Record<string, unknown>;
+}
+declare class ReplaySurrogate {
+    private transport;
+    private buffer;
+    private flushTimer;
+    private opts;
+    private sessionId;
+    private active;
+    private destroyed;
+    constructor(transport: HttpTransport, sessionId: string, options?: ReplaySurrogateOptions);
+    /** Enable recording for this session if sample-rate roll passes. */
+    start(): boolean;
+    /** Record a screen view. Filters params through the safeParams allow-list. */
+    recordScreenView(routeName: string, params?: Record<string, unknown>): void;
+    /** Record an AppState transition (foreground/background/inactive). */
+    recordAppState(next: string): void;
+    /** Record a free-form, customer-validated checkpoint. */
+    recordManual(label: string, data?: Record<string, unknown>): void;
+    destroy(): void;
+    /** @internal — for tests. */
+    isActive(): boolean;
+    /** @internal — for tests. */
+    getBuffer(): ReadonlyArray<SurrogateEvent>;
+    private push;
+    private flush;
+}
+
+interface HttpTrackingOptions {
+    /** Capture request body. Default false. Truncated to maxBodyBytes. */
+    captureRequestBody?: boolean;
+    /** Capture response body. Default false. Truncated to maxBodyBytes. */
+    captureResponseBody?: boolean;
+    /**
+     * Capture request + response headers. Default false. Hard-redacted
+     * names are always stripped regardless of this flag.
+     */
+    captureHeaders?: boolean;
+    /** Additional header names to redact (case-insensitive). */
+    redactHeaders?: string[];
+    /** Additional query-param names to redact (case-insensitive). */
+    redactQueryParams?: string[];
+    /**
+     * Skip URLs matching any of these patterns. String = case-insensitive
+     * substring match; RegExp = `.test()` against the full URL.
+     */
+    ignoredUrls?: (string | RegExp)[];
+    /**
+     * If non-empty, only capture URLs matching at least one of these
+     * patterns. Takes precedence over ignoredUrls.
+     */
+    allowedUrls?: (string | RegExp)[];
+    /** Max bytes per captured body. Default 4096. */
+    maxBodyBytes?: number;
+}
+
+/**
+ * Per-console-method capture flags. Defaults are set to keep the
+ * dashboard signal-to-noise high: `warn` and `error` capture by default
+ * (most apps fire those at human-meaningful moments), `log` and `info`
+ * are OFF by default since typical apps log thousands of debug lines
+ * per session.
+ *
+ * Override per-method:
+ *
+ *   <AllStakProvider captureConsole={{ log: true, info: true }} />
+ *
+ * Or to fully suppress:
+ *
+ *   <AllStakProvider captureConsole={{ warn: false, error: false }} />
+ *
+ * Setting `autoConsoleBreadcrumbs={false}` on the provider/install is a
+ * higher-level kill switch — it skips wrapping any console method.
+ */
+interface ConsoleCaptureOptions {
+    log?: boolean;
+    info?: boolean;
+    warn?: boolean;
+    error?: boolean;
+}
+/** @internal — for tests. Resets the wrap-once flag. */
+declare function __resetConsoleInstrumentationFlagForTest(): void;
+
+declare const INGEST_HOST = "https://api.allstak.sa";
+declare const SDK_NAME = "allstak-react-native";
+declare const SDK_VERSION = "0.3.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.
+     * Affects `captureException` (sets `payload.level`) and the default of
+     * `captureMessage`. Customer-set default severity, mirrors `setLevel`.
+     */
+    level?: 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+    /**
+     * Custom grouping fingerprint applied to every event. The backend uses
+     * this in place of stack-based grouping. 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;
+    /**
+     * Privacy-first view-state replay surrogate. **Off by default.** Enable
+     * with `replay: { sampleRate: 0.1, safeParams: ['screenId'] }`. Captures
+     * route names + AppState transitions + manual checkpoints — never inputs
+     * or rendered text. See `src/replay-surrogate.ts` for the privacy contract.
+     */
+    replay?: ReplaySurrogateOptions;
+    /**
+     * Auto-instrument outbound HTTP — wraps `fetch`, `XMLHttpRequest`, and
+     * (when present) `axios`. Default: false. Combine with `httpTracking`
+     * to control body/header capture and redaction. Idempotent.
+     */
+    enableHttpTracking?: boolean;
+    /**
+     * Privacy + capture controls for HTTP instrumentation. Bodies and
+     * headers are OFF by default; auth headers and sensitive query params
+     * are ALWAYS redacted.
+     */
+    httpTracking?: HttpTrackingOptions;
+    /**
+     * Per-console-method capture flags. Defaults: warn + error captured,
+     * log + info NOT captured (to avoid breadcrumb spam from typical app
+     * logging). Set `{ log: true, info: true }` to opt-in.
+     */
+    captureConsole?: ConsoleCaptureOptions;
+    maxBreadcrumbs?: number;
+    /**
+     * 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 (set automatically by installReactNative). */
+    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;
+}
+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[];
+    fingerprint?: string[];
+}
+declare class AllStakClient {
+    private transport;
+    private config;
+    private sessionId;
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    private scopeStack;
+    private tracing;
+    private replay;
+    private httpRequests;
+    private _instrumentAxios;
+    constructor(config: AllStakConfig);
+    /** Access the replay surrogate (or null if not initialized / sampled out). */
+    getReplay(): ReplaySurrogate | null;
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
+    /** Snapshot of recent failed HTTP requests for error-linking. */
+    getRecentFailedHttp(): readonly HttpRequestIngestItem[];
+    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 sendLog;
+    private passesSampleRate;
+    /**
+     * Returns the effective config layer = base config + every scope on the
+     * stack. Inner code reads from this instead of `this.config` directly so
+     * 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 to attach per-request context without leaking
+     * across concurrent requests.
+     */
+    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 scoped context. Any user/tag/extra/context/
+     * fingerprint/level set on the passed `Scope` is visible only inside the
+     * callback (and any captures made within it). Pop is automatic, including
+     * for async callbacks and thrown errors.
+     */
+    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;
+    /** Access the privacy-first replay surrogate (or null if disabled / sampled out). */
+    getReplay(): ReplaySurrogate | null;
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
+    getSessionId(): string;
+    getConfig(): AllStakConfig | null;
+    destroy(): void;
+    /** @internal — exposed for testing */
+    _getInstance(): AllStakClient | null;
+};
+
+/**
+ * React Native runtime integration — ErrorUtils, Hermes promise rejection
+ * tracking, Platform tags, AppState breadcrumbs, XHR network capture,
+ * fetch breadcrumbs, and console breadcrumbs.
+ *
+ * Extracted from index.ts so AllStakProvider can call it without circular
+ * imports.
+ */
+interface ReactNativeInstallOptions {
+    /** Auto-capture unhandled JS exceptions via ErrorUtils. Default: true */
+    autoErrorHandler?: boolean;
+    /** Auto-capture unhandled promise rejections (Hermes). Default: true */
+    autoPromiseRejections?: boolean;
+    /** Auto-attach Platform.* info as tags. Default: true */
+    autoDeviceTags?: boolean;
+    /** Auto-emit breadcrumbs on AppState change. Default: true */
+    autoAppStateBreadcrumbs?: boolean;
+    /** Auto-instrument XHR (RN's fetch is XHR-based) for network breadcrumbs. Default: true */
+    autoNetworkCapture?: boolean;
+    /** Wrap `globalThis.fetch` to record HTTP breadcrumbs. Default: true */
+    autoFetchBreadcrumbs?: boolean;
+    /**
+     * Wrap `console.*` methods to record log breadcrumbs. Default: true.
+     * Per-method capture is controlled by `captureConsole` in AllStakConfig
+     * (warn + error default on, log + info default off).
+     */
+    autoConsoleBreadcrumbs?: boolean;
+    /**
+     * Auto-detect `@react-navigation/native` and patch `NavigationContainer`
+     * so route changes ship as breadcrumbs without the host app needing
+     * to call `instrumentReactNavigation(ref)`. Default: true. When the
+     * package is not installed, this silently no-ops.
+     */
+    autoNavigationBreadcrumbs?: boolean;
+    /**
+     * Emit a `[AllStak] Navigation auto-instrumentation enabled/not applied`
+     * console log so developers can confirm the wiring at startup. The
+     * provider sets this from its `debug` prop; defaults to false when
+     * called manually.
+     */
+    debugLogs?: boolean;
+}
+declare function installReactNative(options?: ReactNativeInstallOptions): void;
+
+interface AllStakProviderProps extends ReactNativeInstallOptions {
+    children: React.ReactNode;
+    apiKey: string;
+    environment?: string;
+    release?: string;
+    host?: string;
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    tags?: Record<string, string>;
+    debug?: boolean;
+    enableHttpTracking?: boolean;
+    httpTracking?: AllStakConfig['httpTracking'];
+    /**
+     * Per-console-method capture flags. Defaults: warn + error on, log +
+     * info off. Set `{ log: true, info: true }` to opt-in to verbose
+     * capture, or `{ warn: false, error: false }` to suppress.
+     */
+    captureConsole?: AllStakConfig['captureConsole'];
+    sampleRate?: number;
+    beforeSend?: AllStakConfig['beforeSend'];
+    replay?: AllStakConfig['replay'];
+    tracesSampleRate?: number;
+    service?: string;
+    dist?: string;
+    /**
+     * Tear down the SDK when the provider unmounts. Default `false`.
+     *
+     * Most apps mount `AllStakProvider` once at the root and never unmount
+     * it. Setting this to `true` risks disabling telemetry if the provider
+     * re-mounts (Fast Refresh in dev, route key changes, React 18 Strict
+     * Mode double-mount, etc.) — there is a brief window between unmount
+     * and remount where captures throw.
+     *
+     * Leave at the default unless you genuinely need to dispose the SDK
+     * (e.g. test harness, multi-tenant container that switches projects).
+     */
+    destroyOnUnmount?: boolean;
+    fallback?: React.ReactNode | ((props: {
+        error: Error;
+        resetError: () => void;
+    }) => React.ReactNode);
+    onError?: (error: Error, componentStack?: string) => void;
+}
+declare function AllStakProvider({ children, apiKey, environment, release, host, user, tags, debug, enableHttpTracking, httpTracking, captureConsole, sampleRate, beforeSend, replay, tracesSampleRate, service, dist, destroyOnUnmount, fallback, onError, autoErrorHandler, autoPromiseRejections, autoDeviceTags, autoAppStateBreadcrumbs, autoNetworkCapture, autoFetchBreadcrumbs, autoConsoleBreadcrumbs, autoNavigationBreadcrumbs, }: AllStakProviderProps): React.ReactElement;
+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;
+};
+/** @internal — for tests. Resets the module-level remount-guard. */
+declare function __resetProviderInstanceForTest(): void;
+
+/**
+ * React Native navigation breadcrumbs — two opt-in helpers:
+ *
+ *   - instrumentReactNavigation(navigationRef): call once after the
+ *     NavigationContainer is mounted. Subscribes to `state` events on the
+ *     NavigationContainerRef and emits a breadcrumb whenever the active
+ *     route name changes. Works with @react-navigation/native v6+ without
+ *     adding it as a dependency (the ref shape is duck-typed).
+ *
+ *   - instrumentNavigationFromLinking(): registers a Linking event
+ *     listener so deep links also appear in breadcrumbs. Useful when the
+ *     app uses Linking.openURL(...) instead of (or alongside) a router.
+ *
+ * Both helpers are idempotent and never throw if the underlying RN module
+ * isn't present (Expo Go, JS-only test runs).
+ */
+type NavigationRef = {
+    getCurrentRoute?: () => {
+        name?: string;
+    } | undefined;
+    addListener?: (event: string, cb: () => void) => () => void;
+};
+interface ReactNavigationOptions {
+    /**
+     * Whitelist of route-param keys safe to record alongside the route name.
+     * Anything outside this list is dropped — params commonly carry user IDs,
+     * order numbers, etc. Default `[]`.
+     */
+    safeParams?: string[];
+    /**
+     * Also forward the screen view to the replay surrogate (if active).
+     * Default true — the surrogate itself decides whether it's recording.
+     */
+    forwardToReplay?: boolean;
+}
+/**
+ * Subscribe to a `@react-navigation/native` NavigationContainerRef and
+ * emit a navigation breadcrumb whenever the active route changes. Captures:
+ *
+ *   - route name change (from -> to)
+ *   - whitelisted route params (via `safeParams`)
+ *   - state change → forwarded to replay surrogate when enabled
+ *
+ * Idempotent — installs once per ref. Returns an unsubscribe function.
+ */
+declare function instrumentReactNavigation(navigationRef: NavigationRef, options?: ReactNavigationOptions): () => void;
+/**
+ * Register a Linking listener so `openURL`/deep-link launches surface
+ * as breadcrumbs. No-op if `react-native` isn't available (test env).
+ */
+declare function instrumentNavigationFromLinking(): void;
+/**
+ * Best-effort automatic instrumentation of `@react-navigation/native`.
+ *
+ * **What it does:**
+ *   - Tries `require('@react-navigation/native')`. If the package is not
+ *     installed, returns `false` and is otherwise a no-op.
+ *   - If found, monkey-patches the module's exported `NavigationContainer`
+ *     with a wrapper that auto-creates an internal ref, forwards the
+ *     user's `ref` prop, and on mount calls `instrumentReactNavigation`
+ *     so route changes ship as breadcrumbs.
+ *   - Idempotent: a flag on the module's exports object prevents double
+ *     patching across hot-reload cycles or repeated `installReactNative`
+ *     calls.
+ *
+ * **Why this works:**
+ *   Babel's CommonJS interop preserves runtime property lookups for
+ *   named imports — `import { NavigationContainer } from '@react-navigation/native'`
+ *   compiles to `_rnav.NavigationContainer` accesses at use-site, so
+ *   patching the module's exports object before the host app renders
+ *   means user code transparently picks up our wrapper.
+ *
+ * **Why it might fail:**
+ *   - `@react-navigation/native` not installed → returns false silently.
+ *   - Module exports frozen or sealed (rare in CJS-style RN builds).
+ *   - User imported `NavigationContainer` via a deep path that bypasses
+ *     the index module.
+ *   In any failure case the manual API (`instrumentReactNavigation(ref)`)
+ *   is still available as a fallback.
+ */
+declare function tryAutoInstrumentNavigation(): boolean;
+/** @internal — for tests. Resets the auto-patch flag on the cached module. */
+declare function __resetAutoNavigationFlagForTest(): void;
+
+/**
+ * React Native architecture / runtime detection.
+ *
+ * **Status:** the JS-level check is implemented and tested. The native
+ * AllStak modules (Java + Obj-C) are written in legacy module style and
+ * are known to interoperate with the New Architecture (Fabric +
+ * TurboModules) via the RN interop layer. End-to-end integration on a
+ * real Fabric build has not yet been verified — see README §"New
+ * Architecture support" for current status.
+ *
+ * The two booleans returned here are read off well-known global flags
+ * that RN exposes to JS:
+ *
+ *   - `globalThis.__turboModuleProxy` — present when TurboModules is
+ *     enabled (New Architecture).
+ *   - `globalThis.RN$Bridgeless` — present when bridgeless mode is on.
+ *
+ * If the host app surfaces this through `AllStak.setTag('rn.newArch', '1')`
+ * we can correlate New-Arch crashes specifically and prioritize a fix.
+ */
+interface ArchitectureInfo {
+    /** True when TurboModules / New Architecture is detected at runtime. */
+    newArchitecture: boolean;
+    /** True when bridgeless mode is detected. */
+    bridgeless: boolean;
+    /** True when the JS engine is Hermes. */
+    hermes: boolean;
+    /** Free-form tag suitable for `AllStak.setTag('rn.architecture', ...)`. */
+    tag: 'new-arch' | 'old-arch' | 'unknown';
+}
+declare function detectArchitecture(): ArchitectureInfo;
+/**
+ * Convenience: stamp `rn.architecture`, `rn.bridgeless`, and `rn.hermes`
+ * tags on the active AllStak singleton based on detection. Safe to call
+ * any time after `AllStak.init()` and before the first capture.
+ */
+declare function applyArchitectureTags(setTag: (key: string, value: string) => void): ArchitectureInfo;
+
+/**
+ * @allstak/react-native — standalone React Native SDK.
+ *
+ * Self-contained: depends only on `react-native` (peer) and the global
+ * `fetch`/`AbortController` that RN guarantees. Contains no `window`,
+ * `document`, `localStorage`, `sessionStorage`, or browser DOM event
+ * listeners.
+ *
+ * Recommended usage (one-liner):
+ *
+ *   import { AllStakProvider } from '@allstak/react-native';
+ *
+ *   export default function App() {
+ *     return (
+ *       <AllStakProvider apiKey="YOUR_API_KEY" environment="production">
+ *         <AppRoot />
+ *       </AllStakProvider>
+ *     );
+ *   }
+ *
+ * Advanced / manual usage:
+ *
+ *   import { AllStak, installReactNative } from '@allstak/react-native';
+ *   AllStak.init({ apiKey, environment, release });
+ *   installReactNative();
+ *
+ * Native crash capture (Java/Kotlin on Android, Obj-C/Swift on iOS) lives
+ * under the `native/` directory in this package. See README.
+ */
+
+declare function __setNativeModuleForTest(mod: any): void;
+/**
+ * DEV-ONLY: deliberately trigger a native iOS or Android crash via the
+ * linked AllStak native module. This is intended for verifying the
+ * native-crash → drain → ingest pipeline during SDK development. It
+ * **terminates the app process** — never expose this in production UI.
+ *
+ *   import { __devTriggerNativeCrash } from '@allstak/react-native';
+ *   if (__DEV__) __devTriggerNativeCrash();  // app dies; relaunch drains
+ *
+ * No-op when the native module is not linked.
+ */
+declare function __devTriggerNativeCrash(): Promise<void>;
+/**
+ * Drain any native crash stashed by AllStakCrashHandler on the previous
+ * launch and ship it to /ingest/v1/errors. No-op when the native module
+ * is not linked (Expo Go, JS-only test runners, etc).
+ */
+declare function drainPendingNativeCrashes(release?: string): Promise<void>;
+
+export { AllStak, AllStakClient, type AllStakConfig, AllStakProvider, type AllStakProviderProps, type ArchitectureInfo, type Breadcrumb, type ConsoleCaptureOptions, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type ReactNativeInstallOptions, ReplaySurrogate, type ReplaySurrogateOptions, SDK_NAME, SDK_VERSION, Scope, __devTriggerNativeCrash, __resetAutoNavigationFlagForTest, __resetConsoleInstrumentationFlagForTest, __resetProviderInstanceForTest, __setNativeModuleForTest, applyArchitectureTags, detectArchitecture, drainPendingNativeCrashes, installReactNative, instrumentNavigationFromLinking, instrumentReactNavigation, tryAutoInstrumentNavigation, useAllStak };