@allstak/react-native 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -1,22 +1,48 @@
 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.
+ * Fail-open HTTP transport for React Native. Telemetry sends are best-effort:
+ * they use a short timeout, never reject into the host app, and fall into a
+ * bounded in-memory ring buffer with circuit-breaker backoff when AllStak is
+ * unavailable.
  *
  * No window, no AbortController fallback shims — RN exposes both natively.
  */
+interface TransportStats {
+    queued: number;
+    sent: number;
+    failed: number;
+    dropped: number;
+    consecutiveFailures: number;
+    circuitOpenUntil: number;
+    lastTransportLatencyMs?: number;
+    lastFlushDurationMs?: number;
+}
 declare class HttpTransport {
     private baseUrl;
     private apiKey;
+    private enabled;
     private buffer;
     private flushing;
-    constructor(baseUrl: string, apiKey: string);
+    private consecutiveFailures;
+    private circuitOpenUntil;
+    private sent;
+    private failed;
+    private dropped;
+    private lastTransportLatencyMs;
+    private lastFlushDurationMs;
+    constructor(baseUrl: string, apiKey: string, enabled?: boolean);
     send(path: string, payload: unknown): Promise<void>;
+    private enqueueOrDispatch;
+    private dispatch;
     private doFetch;
+    private push;
+    private scheduleFlush;
     private flushBuffer;
+    private recordFailure;
     getBufferSize(): number;
+    noteDropped(count?: number): void;
+    getStats(): TransportStats;
     /**
      * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
      * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
@@ -44,6 +70,10 @@ declare class HttpTransport {
 /** What instrumentation hands to the module per request. */
 interface HttpRequestEvent {
     type: 'http_request';
+    traceId: string;
+    requestId: string;
+    spanId?: string;
+    parentSpanId?: string;
     method: string;
     url: string;
     statusCode?: number;
@@ -55,11 +85,19 @@ interface HttpRequestEvent {
     requestHeaders?: Record<string, string>;
     responseHeaders?: Record<string, string>;
     error?: string;
-    traceId?: string;
+    requestBodyStatus?: string;
+    responseBodyStatus?: string;
+    requestBodyRedactedFields?: string[];
+    responseBodyRedactedFields?: string[];
+    requestBodyTruncated?: boolean;
+    responseBodyTruncated?: boolean;
+    capturePolicy?: string;
+    linkConfidence?: 'exact' | 'inferred' | 'weak' | 'none';
 }
 interface HttpRequestIngestItem {
     type: 'http_request';
     traceId: string;
+    requestId: string;
     direction: 'outbound';
     method: string;
     host: string;
@@ -74,6 +112,16 @@ interface HttpRequestIngestItem {
     requestHeaders?: Record<string, string>;
     responseHeaders?: Record<string, string>;
     error?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    requestBodyStatus?: string;
+    responseBodyStatus?: string;
+    requestBodyRedactedFields?: string[];
+    responseBodyRedactedFields?: string[];
+    requestBodyTruncated?: boolean;
+    responseBodyTruncated?: boolean;
+    capturePolicy?: string;
+    linkConfidence?: 'exact' | 'inferred' | 'weak' | 'none';
     environment?: string;
     release?: string;
     dist?: string;
@@ -241,9 +289,19 @@ interface ReplaySurrogateOptions {
 }
 interface SurrogateEvent {
     ts: number;
-    k: 'screen' | 'appstate' | 'manual';
+    k: 'screen' | 'appstate' | 'manual' | 'request' | 'exception' | 'response' | 'action' | 'retry';
     data: Record<string, unknown>;
 }
+interface TimelineContext {
+    traceId?: string;
+    requestId?: string;
+    spanId?: string;
+    eventId?: string;
+    release?: string;
+    dist?: string;
+    screen?: string;
+    route?: string;
+}
 declare class ReplaySurrogate {
     private transport;
     private buffer;
@@ -256,11 +314,13 @@ declare class ReplaySurrogate {
     /** 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;
+    recordScreenView(routeName: string, params?: Record<string, unknown>, context?: TimelineContext): void;
     /** Record an AppState transition (foreground/background/inactive). */
-    recordAppState(next: string): void;
+    recordAppState(next: string, context?: TimelineContext): void;
     /** Record a free-form, customer-validated checkpoint. */
-    recordManual(label: string, data?: Record<string, unknown>): void;
+    recordManual(label: string, data?: Record<string, unknown>, context?: TimelineContext): void;
+    /** Record a forensic mobile session timeline marker. This is not replay. */
+    recordTimelineMarker(kind: SurrogateEvent['k'], label: string, data?: Record<string, unknown>, context?: TimelineContext): void;
     destroy(): void;
     /** @internal — for tests. */
     isActive(): boolean;
@@ -270,6 +330,28 @@ declare class ReplaySurrogate {
     private flush;
 }
 
+/**
+ * URL + header + body redaction utilities for HTTP instrumentation.
+ *
+ * Hard rules:
+ *   - Authorization, Cookie, X-API-Key, Set-Cookie are ALWAYS redacted
+ *     (host app cannot opt back into capturing them).
+ *   - Query params named `token`, `password`, `api_key`, `apikey`,
+ *     `authorization`, `auth`, `secret`, `access_token`, `refresh_token`,
+ *     `session` are ALWAYS redacted.
+ *   - Host app may add additional names via `redactHeaders` /
+ *     `redactQueryParams`; the always-list is the floor, not the ceiling.
+ *   - Bodies are truncated to `maxBodyBytes` (default 4096) and replaced
+ *     with `'<binary>'` when not safely-stringifiable.
+ *
+ * URL pattern matching for ignoredUrls / allowedUrls accepts strings
+ * (substring match) or RegExp (test-based). String matching is
+ * case-insensitive on the URL.
+ */
+declare const ALWAYS_REDACT_HEADERS: Set<string>;
+declare const ALWAYS_REDACT_QUERY: Set<string>;
+declare const REDACTED = "[REDACTED]";
+declare const DEFAULT_REDACT_BODY_FIELDS: string[];
 interface HttpTrackingOptions {
     /** Capture request body. Default false. Truncated to maxBodyBytes. */
     captureRequestBody?: boolean;
@@ -296,7 +378,38 @@ interface HttpTrackingOptions {
     allowedUrls?: (string | RegExp)[];
     /** Max bytes per captured body. Default 4096. */
     maxBodyBytes?: number;
+    /** Content types eligible for body capture. Default JSON + text payloads. */
+    allowedContentTypes?: string[];
+    /** Additional JSON body fields to redact recursively. */
+    redactBodyFields?: string[];
 }
+interface CapturedBody {
+    body?: string;
+    status: 'disabled' | 'captured' | 'redacted' | 'truncated' | 'unsupported' | 'empty';
+    redactedFields: string[];
+    truncated: boolean;
+    capturePolicy: string;
+}
+/**
+ * Redact sensitive query-string params in a URL. Returns the sanitized
+ * URL string. Falls back to the input when URL parsing fails (relative
+ * URLs in test environments).
+ */
+declare function redactUrl(url: string, opts: HttpTrackingOptions): string;
+/**
+ * Filter + redact an HTTP header dictionary. Returns a NEW object — does
+ * not mutate the input. When `captureHeaders` is false returns undefined
+ * (no headers in the wire payload at all).
+ */
+declare function sanitizeHeaders(headers: Record<string, string | string[] | undefined> | undefined, opts: HttpTrackingOptions): Record<string, string> | undefined;
+/**
+ * Truncate + safely-stringify a body. Returns:
+ *   - undefined when capture is disabled
+ *   - the stringified body when it's a string / number / plain object
+ *   - '<binary>' when it's a Blob / FormData / ArrayBuffer / etc
+ *   - truncated string with `…[truncated]` suffix when over maxBodyBytes
+ */
+declare function captureBodyResult(body: unknown, enabled: boolean, maxBodyBytes: number, opts?: HttpTrackingOptions, contentType?: string): CapturedBody;
 
 /**
  * Per-console-method capture flags. Defaults are set to keep the
@@ -398,6 +511,13 @@ interface AllStakConfig {
      * — 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>;
+    /**
+     * Optional fail-open screenshot capture. Off by default and provider-based
+     * so Expo/RN apps choose their own native or JS screenshot implementation.
+     * The SDK bounds timeout/size/sampling and drops screenshots before it can
+     * hurt app navigation, JS thread responsiveness, or telemetry delivery.
+     */
+    screenshot?: ScreenshotCaptureOptions;
     /** SDK identity overrides (set automatically by installReactNative). */
     sdkName?: string;
     sdkVersion?: string;
@@ -406,6 +526,28 @@ interface AllStakConfig {
     commitSha?: string;
     branch?: string;
 }
+interface ScreenshotArtifact {
+    data?: string;
+    contentType?: 'image/png' | 'image/jpeg' | 'image/webp';
+    width?: number;
+    height?: number;
+    sizeBytes?: number;
+    redacted?: boolean;
+    redactionStrategy?: string;
+}
+interface ScreenshotCaptureOptions {
+    enabled?: boolean;
+    captureOnError?: boolean;
+    timeoutMs?: number;
+    maxBytes?: number;
+    sampleRate?: number;
+    provider?: (reason: {
+        type: 'error';
+        error: Error;
+        traceId?: string;
+        requestId?: string;
+    }) => ScreenshotArtifact | null | undefined | Promise<ScreenshotArtifact | null | undefined>;
+}
 interface Breadcrumb {
     timestamp: string;
     type: string;
@@ -421,6 +563,7 @@ interface PayloadFrame {
     colno?: number;
     inApp?: boolean;
     platform?: string;
+    debugId?: string;
 }
 interface ErrorIngestPayload {
     exceptionClass: string;
@@ -435,6 +578,12 @@ interface ErrorIngestPayload {
     environment?: string;
     release?: string;
     sessionId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    requestId?: string;
+    replayId?: string;
+    service?: string;
     user?: {
         id?: string;
         email?: string;
@@ -442,6 +591,12 @@ interface ErrorIngestPayload {
     metadata?: Record<string, unknown>;
     breadcrumbs?: Breadcrumb[];
     fingerprint?: string[];
+    debugMeta?: {
+        images: Array<{
+            type: string;
+            debugId: string;
+        }>;
+    };
 }
 declare class AllStakClient {
     private transport;
@@ -517,8 +672,11 @@ declare class AllStakClient {
     }): void;
     getSessionId(): string;
     getConfig(): AllStakConfig;
+    getTransportStats(): TransportStats;
     destroy(): void;
     private sendLog;
+    private shouldCaptureScreenshot;
+    private withScreenshotMetadata;
     private passesSampleRate;
     /**
      * Returns the effective config layer = base config + every scope on the
@@ -590,6 +748,7 @@ declare const AllStak: {
     instrumentAxios<T = any>(axios: T): T;
     getSessionId(): string;
     getConfig(): AllStakConfig | null;
+    getTransportStats(): TransportStats;
     destroy(): void;
     /** @internal — exposed for testing */
     _getInstance(): AllStakClient | null;
@@ -870,4 +1029,4 @@ declare function __devTriggerNativeCrash(): Promise<void>;
  */
 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 };
+export { ALWAYS_REDACT_HEADERS, ALWAYS_REDACT_QUERY, AllStak, AllStakClient, type AllStakConfig, AllStakProvider, type AllStakProviderProps, type ArchitectureInfo, type Breadcrumb, type ConsoleCaptureOptions, DEFAULT_REDACT_BODY_FIELDS, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, REDACTED, type ReactNativeInstallOptions, ReplaySurrogate, type ReplaySurrogateOptions, SDK_NAME, SDK_VERSION, Scope, type ScreenshotArtifact, type ScreenshotCaptureOptions, type TransportStats, __devTriggerNativeCrash, __resetAutoNavigationFlagForTest, __resetConsoleInstrumentationFlagForTest, __resetProviderInstanceForTest, __setNativeModuleForTest, applyArchitectureTags, captureBodyResult, detectArchitecture, drainPendingNativeCrashes, installReactNative, instrumentNavigationFromLinking, instrumentReactNavigation, redactUrl, sanitizeHeaders, tryAutoInstrumentNavigation, useAllStak };