@allstak/react-native 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -558,9 +558,165 @@ declare function maybeCaptureScreenshot(config: ScreenshotConfig, ctx: Screensho
 } | null>;
 declare function pickScreenshotConfig(source: Record<string, unknown>): Partial<ScreenshotConfig>;
 
+/**
+ * Auto-collected Sentry-shape context bags for React Native events.
+ *
+ * Lazily requires optional metadata packages and never throws when they
+ * are absent. Output uses Sentry's RN context shape so the dashboard can
+ * render contexts mechanically:
+ *
+ *   contexts.device     — model, manufacturer, family, arch, simulator, …
+ *   contexts.os         — name, version, build
+ *   contexts.app        — app_name, app_identifier, app_build, app_version, …
+ *   contexts.react_native — react_native_version, expo, hermes, fabric, …
+ *   contexts.runtime    — name, version (e.g. hermes 0.74.x)
+ *
+ * All collectors fail-open: a missing optional dep means the corresponding
+ * context bag is shallow (only what we can read from globals + react-native
+ * Platform) rather than failing the whole event.
+ */
+interface SentryContexts {
+    device?: Record<string, unknown>;
+    os?: Record<string, unknown>;
+    app?: Record<string, unknown>;
+    react_native?: Record<string, unknown>;
+    runtime?: Record<string, unknown>;
+    user?: Record<string, unknown>;
+}
+interface AutoTags {
+    [key: string]: string;
+}
+interface CollectContextOptions {
+    /** Include free/total memory + battery when collectors permit. Default true. */
+    captureDeviceContext?: boolean;
+    /** Include battery_level + charging. Default false (privacy). */
+    captureBattery?: boolean;
+    /** Include screen orientation + dimensions. Default true. */
+    captureScreenContext?: boolean;
+    /** Include user.email if config.user.email present. Default false. */
+    sendDefaultPii?: boolean;
+}
+/**
+ * Collect all Sentry-shape context bags + a flat tag dictionary in one
+ * pass. Safe to call once during init, then re-used by every event via
+ * client.config.contexts.
+ *
+ * Returns null for any context bag whose source data is entirely missing
+ * (rather than emitting empty {}); the dashboard renderer can then hide
+ * the panel cleanly.
+ */
+declare function collectAutoContexts(opts?: CollectContextOptions): {
+    contexts: SentryContexts;
+    tags: AutoTags;
+};
+/**
+ * Convert a user object to a Sentry-shape `contexts.user` bag,
+ * respecting `sendDefaultPii`.
+ */
+declare function buildUserContext(user: {
+    id?: string;
+    email?: string;
+    username?: string;
+    ip_address?: string;
+} | undefined, opts?: {
+    sendDefaultPii?: boolean;
+}): Record<string, unknown> | undefined;
+
+/**
+ * Engine-agnostic Error.stack parser. Handles V8 / Hermes ("at fn (file:l:c)")
+ * and Gecko / JSC ("fn@file:l:c"). Output mirrors the backend
+ * ErrorIngestRequest.Frame shape so the dashboard can render frames directly.
+ */
+interface StackFrame {
+    filename?: string;
+    absPath?: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    inApp?: boolean;
+    platform?: string;
+}
+
+/**
+ * Mechanism + exception envelope helpers — Sentry-shape exception
+ * extraction for AllStak React Native events.
+ *
+ * Exposes:
+ *   - MechanismType: literal type of the entry-point classification
+ *   - buildExceptionChain: walks `error.cause` and returns each linked
+ *     exception in Sentry's `exception.values` order (innermost first)
+ *   - extractAxiosRequest: detects `error.isAxiosError === true` and
+ *     returns a sanitized request panel suitable for the event payload
+ *   - classifyHttpError: HTTP category one of `http_client_error` |
+ *     `http_server_error` | `network` | `timeout` | `cancel`
+ */
+
+type MechanismType = 'onerror' | 'onunhandledrejection' | 'errorboundary' | 'captureException' | 'captureMessage' | 'native_crash';
+interface ExceptionValue {
+    type: string;
+    value: string;
+    module?: string;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+    mechanism?: {
+        type: MechanismType;
+        handled: boolean;
+        synthetic?: boolean;
+        data?: Record<string, unknown>;
+    };
+}
+interface SanitizedHttpRequest {
+    method?: string;
+    url_sanitized: string;
+    status_code?: number;
+    duration_ms?: number;
+    category: 'http_client_error' | 'http_server_error' | 'network' | 'timeout' | 'cancel';
+}
+/**
+ * Strip the query string entirely. Headers/auth/etc never leak in
+ * the URL-only sanitizer; bodies are never extracted here.
+ */
+declare function sanitizeUrl(url: string | undefined): string;
+/**
+ * Walk `error.cause` recursively and return each linked exception as
+ * a Sentry-shape `ExceptionValue`. The outer (most-recent) exception
+ * is the LAST element so the dashboard can render innermost → outer
+ * — matching Sentry's convention.
+ *
+ * Hard cap at 5 links to avoid pathological cycles.
+ */
+declare function buildExceptionChain(err: Error, mechanism: MechanismType, handled: boolean): ExceptionValue[];
+/**
+ * Detect an axios-style error and pull out the request metadata
+ * suitable for inclusion in the event payload's `request` panel.
+ * Returns null when this is not an AxiosError-shaped object.
+ *
+ * Privacy: URL query strings are dropped. NO headers or bodies are
+ * extracted here regardless of axios config.
+ */
+declare function extractAxiosRequest(err: unknown): SanitizedHttpRequest | null;
+/**
+ * Classify an HTTP/network error into Sentry-style category tags.
+ *
+ * Priority:
+ *   1. AxiosError.code === 'ECONNABORTED' / 'ETIMEDOUT' → 'timeout'
+ *   2. AxiosError.code === 'ERR_CANCELED' → 'cancel'
+ *   3. status 5xx → 'http_server_error'
+ *   4. status 4xx → 'http_client_error'
+ *   5. fall back to 'network'
+ */
+declare function classifyHttpError(err: any, status?: number): SanitizedHttpRequest['category'];
+/**
+ * Look at a thrown value and decide whether it should carry an HTTP
+ * `request` panel (axios is the only auto-detected source today; fetch
+ * Response/TypeError still surface as plain errors).
+ */
+declare function maybeExtractHttpRequest(err: unknown): SanitizedHttpRequest | null;
+
 declare const INGEST_HOST = "https://api.allstak.sa";
 declare const SDK_NAME = "allstak-react-native";
-declare const SDK_VERSION = "0.4.0";
+declare const SDK_VERSION = "0.5.0";
 
 interface AllStakConfig {
     /** Project API key (`ask_live_…`). Required. */
@@ -661,6 +817,35 @@ interface AllStakConfig {
     dist?: string;
     commitSha?: string;
     branch?: string;
+    /**
+     * Auto-collect device/os/app/react_native/runtime contexts on init.
+     * Default: true. Optional metadata packages (expo-application,
+     * expo-device, expo-constants, react-native-device-info) are
+     * lazy-required and missing deps simply produce shallower contexts.
+     */
+    captureDeviceContext?: boolean;
+    /** Include battery info (requires `expo-battery`). Default false. */
+    captureBattery?: boolean;
+    /** Include screen dimensions + orientation. Default true. */
+    captureScreenContext?: boolean;
+    /** Include user.email / user.ip_address on events. Default false. */
+    sendDefaultPii?: boolean;
+    /** Stamp client.ip on outgoing events. Default false. */
+    collectIpAddress?: boolean;
+    /**
+     * Mutate or drop a breadcrumb before it is appended to the buffer.
+     * Return `null` to drop. Errors thrown are swallowed; the original
+     * breadcrumb is appended so a buggy hook can't black-hole telemetry.
+     */
+    beforeBreadcrumb?: (crumb: Breadcrumb) => Breadcrumb | null | undefined;
+    /** Drop HTTP breadcrumbs/events whose URL matches any of these. */
+    denyUrls?: (string | RegExp)[];
+    /** When set, ONLY emit HTTP breadcrumbs/events for matching URLs. */
+    allowUrls?: (string | RegExp)[];
+    /** Extra keys to scrub from breadcrumb data + event metadata. */
+    scrubKeys?: string[];
+    /** Additional regexes to scrub from string values in event data. */
+    scrubPatterns?: RegExp[];
 }
 interface ScreenshotArtifact {
     data?: string;
@@ -733,6 +918,34 @@ interface ErrorIngestPayload {
             debugId: string;
         }>;
     };
+    /** UUID v4 generated for this event. */
+    eventId?: string;
+    /** ISO-8601 timestamp when the event was captured (client-side). */
+    timestamp?: string;
+    /** Was this error handled by the host? false for unhandled JS / promise / native crashes. */
+    handled?: boolean;
+    /** Entry point that captured the error. */
+    mechanism?: MechanismType;
+    /** Current screen / route at the time of capture. */
+    transaction?: string;
+    /** Sentry-shape exception chain (innermost first). Includes mechanism on the outermost. */
+    exception?: {
+        values: ExceptionValue[];
+    };
+    /** Sentry-shape context bags: device, os, app, react_native, runtime, user, trace. */
+    contexts?: SentryContexts & {
+        trace?: {
+            trace_id?: string;
+            span_id?: string;
+            parent_span_id?: string;
+            op?: string;
+            status?: string;
+        };
+    };
+    /** Sentry-shape tags dictionary (flat key/value). */
+    tags?: Record<string, string>;
+    /** HTTP request panel for AxiosError-shaped errors. */
+    request?: SanitizedHttpRequest;
 }
 declare class AllStakClient {
     private transport;
@@ -745,6 +958,12 @@ declare class AllStakClient {
     private replay;
     private httpRequests;
     private _instrumentAxios;
+    /** Auto-collected Sentry-shape contexts (device/os/app/react_native/runtime). */
+    private autoContexts;
+    /** Auto-collected tags (device.model, os.name, js_engine, …). */
+    private autoTags;
+    /** Current screen / transaction name — set via setCurrentScreen() or nav auto-instrument. */
+    private currentTransaction;
     constructor(config: AllStakConfig);
     /** Access the replay surrogate (or null if not initialized / sampled out). */
     getReplay(): ReplaySurrogate | null;
@@ -752,7 +971,10 @@ declare class AllStakClient {
     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;
+    captureException(error: Error, context?: Record<string, unknown>, opts?: {
+        mechanism?: MechanismType;
+        handled?: boolean;
+    }): void;
     /**
      * Flat screenshot API path. Capture first (so masking primitives can
      * swap), send the event with a `screenshot.status` metadata tag, read
@@ -778,6 +1000,17 @@ declare class AllStakClient {
         as?: 'log' | 'error' | 'both';
     }): void;
     addBreadcrumb(type: string, message: string, level?: string, data?: Record<string, unknown>): void;
+    /**
+     * Set the current screen / route name. Stamps `transaction` on every
+     * subsequent event and emits a `navigation` breadcrumb. Use this when
+     * not on `@react-navigation/native` (the nav auto-instrument calls
+     * this for you).
+     */
+    setCurrentScreen(name: string): void;
+    /** @internal — current transaction (or undefined). */
+    getCurrentTransaction(): string | undefined;
+    /** @internal — set transaction without emitting a breadcrumb. */
+    __setTransactionSilent(name: string | null): void;
     clearBreadcrumbs(): void;
     setUser(user: {
         id?: string;
@@ -847,7 +1080,10 @@ declare class AllStakClient {
 }
 declare const AllStak: {
     init(config: AllStakConfig): AllStakClient;
-    captureException(error: Error, context?: Record<string, unknown>): void;
+    captureException(error: Error, context?: Record<string, unknown>, opts?: {
+        mechanism?: MechanismType;
+        handled?: boolean;
+    }): void;
     captureMessage(message: string, level?: "fatal" | "error" | "warning" | "info", options?: {
         as?: "log" | "error" | "both";
     }): void;
@@ -871,6 +1107,11 @@ declare const AllStak: {
         platform?: string;
         dist?: string;
     }): void;
+    /** Set the current screen / transaction name. Stamps event.transaction + emits nav breadcrumb. */
+    setCurrentScreen(name: string): void;
+    getCurrentTransaction(): string | undefined;
+    /** @internal — set transaction without emitting a breadcrumb (nav auto-instrument uses this). */
+    __setTransactionSilent(name: string | null): 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
@@ -1263,4 +1504,4 @@ declare function __devTriggerNativeCrash(): Promise<void>;
  */
 declare function drainPendingNativeCrashes(release?: string): Promise<void>;
 
-export { ALWAYS_REDACT_HEADERS, ALWAYS_REDACT_QUERY, AllStak, AllStakClient, type AllStakConfig, AllStakMaskedView, type AllStakMaskedViewProps, AllStakPrivacyView, AllStakProvider, type AllStakProviderProps, AllStakSensitiveText, type AllStakSensitiveTextProps, AllStakTextInput, type AllStakTextInputProps, type ArchitectureInfo, type Breadcrumb, type ConsoleCaptureOptions, DEFAULT_REDACT_BODY_FIELDS, DEFAULT_SCREENSHOT_CONFIG, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type PrivacyLevel, REDACTED, type ReactNativeInstallOptions, ReplaySurrogate, type ReplaySurrogateOptions, type RuntimeMode, SDK_NAME, SDK_VERSION, Scope, type ScreenshotArtifact, type ScreenshotCaptureOptions, type ScreenshotConfig, type ScreenshotContext, type ScreenshotFailPolicy, type ScreenshotFormat, type ScreenshotMaskStyle, type ScreenshotMetadata, type ScreenshotNativeMode, type ScreenshotRedactionMode, type ScreenshotUpload, type TransportStats, __devTriggerNativeCrash, __resetAutoNavigationFlagForTest, __resetConsoleInstrumentationFlagForTest, __resetPrivacyStateForTest, __resetProviderInstanceForTest, __resetRuntimeModeForTest, __setNativeModuleForTest, applyArchitectureTags, captureBodyResult, captureViaViewShot, detectArchitecture, detectRuntimeMode, drainPendingNativeCrashes, installReactNative, instrumentNavigationFromLinking, instrumentReactNavigation, isCapturingScreenshot, isViewShotAvailable, maybeCaptureScreenshot, pickScreenshotConfig, redactUrl, registerSensitiveRef, resolveScreenshotConfig, runtimeAllowsScreenshot, sanitizeHeaders, tryAutoInstrumentNavigation, useAllStak, useAllStakPrivacy };
+export { ALWAYS_REDACT_HEADERS, ALWAYS_REDACT_QUERY, AllStak, AllStakClient, type AllStakConfig, AllStakMaskedView, type AllStakMaskedViewProps, AllStakPrivacyView, AllStakProvider, type AllStakProviderProps, AllStakSensitiveText, type AllStakSensitiveTextProps, AllStakTextInput, type AllStakTextInputProps, type ArchitectureInfo, type Breadcrumb, type CollectContextOptions, type ConsoleCaptureOptions, DEFAULT_REDACT_BODY_FIELDS, DEFAULT_SCREENSHOT_CONFIG, type ExceptionValue, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type MechanismType, type PrivacyLevel, REDACTED, type ReactNativeInstallOptions, ReplaySurrogate, type ReplaySurrogateOptions, type RuntimeMode, SDK_NAME, SDK_VERSION, type SanitizedHttpRequest, Scope, type ScreenshotArtifact, type ScreenshotCaptureOptions, type ScreenshotConfig, type ScreenshotContext, type ScreenshotFailPolicy, type ScreenshotFormat, type ScreenshotMaskStyle, type ScreenshotMetadata, type ScreenshotNativeMode, type ScreenshotRedactionMode, type ScreenshotUpload, type SentryContexts, type TransportStats, __devTriggerNativeCrash, __resetAutoNavigationFlagForTest, __resetConsoleInstrumentationFlagForTest, __resetPrivacyStateForTest, __resetProviderInstanceForTest, __resetRuntimeModeForTest, __setNativeModuleForTest, applyArchitectureTags, buildExceptionChain, buildUserContext, captureBodyResult, captureViaViewShot, classifyHttpError, collectAutoContexts, detectArchitecture, detectRuntimeMode, drainPendingNativeCrashes, extractAxiosRequest, installReactNative, instrumentNavigationFromLinking, instrumentReactNavigation, isCapturingScreenshot, isViewShotAvailable, maybeCaptureScreenshot, maybeExtractHttpRequest, pickScreenshotConfig, redactUrl, registerSensitiveRef, resolveScreenshotConfig, runtimeAllowsScreenshot, sanitizeHeaders, sanitizeUrl, tryAutoInstrumentNavigation, useAllStak, useAllStakPrivacy };