@allstak/react-native 0.3.4 → 0.4.0

package/dist/index.d.ts

@@ -33,6 +33,18 @@ declare class HttpTransport {
     private lastFlushDurationMs;
     constructor(baseUrl: string, apiKey: string, enabled?: boolean);
     send(path: string, payload: unknown): Promise<void>;
+    /**
+     * One-shot POST that resolves with the parsed JSON response body. Used
+     * by `captureException` to retrieve the server-assigned event id so
+     * follow-up attachment uploads can be linked.
+     *
+     * Fail-open: returns `null` on any error (network, non-2xx, parse).
+     * Respects {@link timeoutMs} via `AbortController`. Bounded retries.
+     */
+    sendAndRead<T = any>(path: string, payload: unknown, options?: {
+        timeoutMs?: number;
+        retries?: number;
+    }): Promise<T | null>;
     private enqueueOrDispatch;
     private dispatch;
     private doFetch;
@@ -438,9 +450,117 @@ interface ConsoleCaptureOptions {
 /** @internal — for tests. Resets the wrap-once flag. */
 declare function __resetConsoleInstrumentationFlagForTest(): void;
 
+/**
+ * Runtime detection for React Native screenshot capture.
+ *
+ * Determines whether native screenshot APIs (specifically
+ * `react-native-view-shot`) are usable in the current host:
+ *   - 'expo-go'        — Expo Go sandbox; native modules cannot be added
+ *                        at runtime → screenshots silently skipped.
+ *   - 'expo-dev-client'— Expo dev/prod build that bundles native deps.
+ *   - 'rn-cli'         — bare react-native (CLI) build.
+ *   - 'unknown'        — anything we couldn't classify; treat as allowed
+ *                        but log a __DEV__ warning.
+ */
+type RuntimeMode = 'expo-go' | 'expo-dev-client' | 'rn-cli' | 'unknown';
+/**
+ * Best-effort detection of the host runtime. Cached after first call.
+ */
+declare function detectRuntimeMode(): RuntimeMode;
+/** @internal — reset for tests */
+declare function __resetRuntimeModeForTest(): void;
+/** Whether a runtime allows attempting a native screenshot via view-shot. */
+declare function runtimeAllowsScreenshot(mode?: RuntimeMode): boolean;
+
+/**
+ * Flat screenshot API for `@allstak/react-native`.
+ *
+ * Mirrors the props the wizard emits (`captureScreenshotOnError`,
+ * `screenshotRedaction`, etc.) and orchestrates native capture via the
+ * optional `react-native-view-shot` peer dep.
+ *
+ * Fail-open contract: the event MUST always send even when capture is
+ * unavailable, throws, times out, or the upload fails. The capture
+ * subsystem is allowed to log in __DEV__ but must never reject into the
+ * host app's promise chain.
+ */
+
+type ScreenshotRedactionMode = 'strict' | 'balanced' | 'custom';
+type ScreenshotMaskStyle = 'solid' | 'blur';
+type ScreenshotFormat = 'png' | 'jpg' | 'webp';
+type ScreenshotNativeMode = 'auto' | 'view-shot' | 'disabled';
+type ScreenshotFailPolicy = 'disable-screenshot' | 'send-event-only';
+interface ScreenshotConfig {
+    captureScreenshotOnError: boolean;
+    screenshotRedaction: ScreenshotRedactionMode;
+    screenshotMaskStyle: ScreenshotMaskStyle;
+    screenshotMaxBytes: number;
+    screenshotQuality: number;
+    screenshotFormat: ScreenshotFormat;
+    screenshotSampleRate: number;
+    screenshotOnUnhandledOnly: boolean;
+    screenshotUploadTimeoutMs: number;
+    screenshotCaptureTimeoutMs: number;
+    screenshotNativeMode: ScreenshotNativeMode;
+    screenshotFailPolicy: ScreenshotFailPolicy;
+    beforeScreenshotCapture?: (ctx: ScreenshotContext) => boolean | Promise<boolean>;
+    beforeScreenshotUpload?: ((payload: ScreenshotUpload, meta: ScreenshotMetadata) => ScreenshotUpload | null | Promise<ScreenshotUpload | null>);
+    isScreenshotAllowed?: (ctx: ScreenshotContext) => boolean | Promise<boolean>;
+}
+interface ScreenshotContext {
+    error?: Error;
+    unhandled?: boolean;
+    runtimeMode: RuntimeMode;
+}
+interface ScreenshotUpload {
+    /** Base64-encoded image bytes (no data: prefix). */
+    dataBase64: string;
+    contentType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+}
+interface ScreenshotMetadata {
+    captureMethod: string;
+    redactionMode: ScreenshotRedactionMode;
+    maskStyle: ScreenshotMaskStyle;
+    format: ScreenshotFormat;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    maskedElements?: number;
+    privacyComponentsDetected?: number;
+    runtimeMode: RuntimeMode;
+}
+declare const DEFAULT_SCREENSHOT_CONFIG: ScreenshotConfig;
+/**
+ * Merge partial config from `init()` / provider props with sensible
+ * defaults. Any `undefined` field falls back to the default. Numeric
+ * fields are clamped to safe ranges.
+ */
+declare function resolveScreenshotConfig(partial: Partial<ScreenshotConfig> | undefined): ScreenshotConfig;
+declare function isViewShotAvailable(): boolean;
+/**
+ * Attempt a native screenshot via react-native-view-shot. Returns
+ * `null` if anything goes wrong (timeout, missing dep, no root ref).
+ * Never throws. Toggles `__setCapturing(true)` for the duration of the
+ * capture so masking primitives swap to their placeholder render.
+ */
+declare function captureViaViewShot(config: ScreenshotConfig): Promise<ScreenshotUpload | null>;
+/**
+ * Top-level orchestrator. Returns an upload + metadata if a screenshot
+ * is captured, or `null` if anything (sampling, gates, capture, etc.)
+ * skipped it. Never throws.
+ */
+declare function maybeCaptureScreenshot(config: ScreenshotConfig, ctx: ScreenshotContext): Promise<{
+    upload: ScreenshotUpload;
+    metadata: ScreenshotMetadata;
+} | null>;
+declare function pickScreenshotConfig(source: Record<string, unknown>): Partial<ScreenshotConfig>;
+
 declare const INGEST_HOST = "https://api.allstak.sa";
 declare const SDK_NAME = "allstak-react-native";
-declare const SDK_VERSION = "0.3.4";
+declare const SDK_VERSION = "0.4.0";
 
 interface AllStakConfig {
     /** Project API key (`ask_live_…`). Required. */
@@ -518,6 +638,22 @@ interface AllStakConfig {
      * hurt app navigation, JS thread responsiveness, or telemetry delivery.
      */
     screenshot?: ScreenshotCaptureOptions;
+    /** Enable on-error screenshot capture. Default: false. */
+    captureScreenshotOnError?: boolean;
+    screenshotRedaction?: ScreenshotRedactionMode;
+    screenshotMaskStyle?: ScreenshotMaskStyle;
+    screenshotMaxBytes?: number;
+    screenshotQuality?: number;
+    screenshotFormat?: ScreenshotFormat;
+    screenshotSampleRate?: number;
+    screenshotOnUnhandledOnly?: boolean;
+    screenshotUploadTimeoutMs?: number;
+    screenshotCaptureTimeoutMs?: number;
+    screenshotNativeMode?: ScreenshotNativeMode;
+    screenshotFailPolicy?: ScreenshotFailPolicy;
+    beforeScreenshotCapture?: ScreenshotConfig['beforeScreenshotCapture'];
+    beforeScreenshotUpload?: ScreenshotConfig['beforeScreenshotUpload'];
+    isScreenshotAllowed?: ScreenshotConfig['isScreenshotAllowed'];
     /** SDK identity overrides (set automatically by installReactNative). */
     sdkName?: string;
     sdkVersion?: string;
@@ -617,6 +753,14 @@ declare class AllStakClient {
     /** Snapshot of recent failed HTTP requests for error-linking. */
     getRecentFailedHttp(): readonly HttpRequestIngestItem[];
     captureException(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Flat screenshot API path. Capture first (so masking primitives can
+     * swap), send the event with a `screenshot.status` metadata tag, read
+     * back the server-assigned errorId, then upload the attachment.
+     *
+     * Fail-open at every step.
+     */
+    private runFlatScreenshotPipeline;
     /** Start a new span. Auto-parented to any currently-active span. */
     startSpan(operation: string, options?: {
         description?: string;
@@ -842,8 +986,23 @@ interface AllStakProviderProps extends ReactNativeInstallOptions {
         resetError: () => void;
     }) => React.ReactNode);
     onError?: (error: Error, componentStack?: string) => void;
+    captureScreenshotOnError?: boolean;
+    screenshotRedaction?: ScreenshotRedactionMode;
+    screenshotMaskStyle?: ScreenshotMaskStyle;
+    screenshotMaxBytes?: number;
+    screenshotQuality?: number;
+    screenshotFormat?: ScreenshotFormat;
+    screenshotSampleRate?: number;
+    screenshotOnUnhandledOnly?: boolean;
+    screenshotUploadTimeoutMs?: number;
+    screenshotCaptureTimeoutMs?: number;
+    screenshotNativeMode?: ScreenshotNativeMode;
+    screenshotFailPolicy?: ScreenshotFailPolicy;
+    beforeScreenshotCapture?: AllStakConfig['beforeScreenshotCapture'];
+    beforeScreenshotUpload?: AllStakConfig['beforeScreenshotUpload'];
+    isScreenshotAllowed?: AllStakConfig['isScreenshotAllowed'];
 }
-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 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, captureScreenshotOnError, screenshotRedaction, screenshotMaskStyle, screenshotMaxBytes, screenshotQuality, screenshotFormat, screenshotSampleRate, screenshotOnUnhandledOnly, screenshotUploadTimeoutMs, screenshotCaptureTimeoutMs, screenshotNativeMode, screenshotFailPolicy, beforeScreenshotCapture, beforeScreenshotUpload, isScreenshotAllowed, }: AllStakProviderProps): React.ReactElement;
 declare function useAllStak(): {
     captureException: (error: Error, ctx?: Record<string, unknown>) => void;
     captureMessage: (msg: string, level?: "fatal" | "error" | "warning" | "info") => void;
@@ -857,6 +1016,81 @@ declare function useAllStak(): {
 /** @internal — for tests. Resets the module-level remount-guard. */
 declare function __resetProviderInstanceForTest(): void;
 
+/**
+ * Privacy / masking primitives for AllStak React Native screenshots.
+ *
+ * Three concerns:
+ *   1. A registry of refs / views the capture path should mask when it
+ *      takes a snapshot.
+ *   2. An "isCapturing" flag that masking components subscribe to so they
+ *      can swap their children for a redacted placeholder during a capture.
+ *   3. Light wrappers (`AllStakMaskedView`, `AllStakPrivacyView`,
+ *      `AllStakTextInput`, `AllStakSensitiveText`) that opt-in to the
+ *      isCapturing swap.
+ *
+ * All wrappers are no-ops when react-native is not installed (e.g. JS
+ * test environment) — they just render their children.
+ */
+
+type PrivacyLevel = 'mask' | 'hide' | 'show';
+/** @internal — for tests. */
+declare function __resetPrivacyStateForTest(): void;
+/** Whether a capture is currently in progress. */
+declare function isCapturingScreenshot(): boolean;
+/** Register a sensitive ref. Returns an unregister function. */
+declare function registerSensitiveRef(ref: unknown): () => void;
+/**
+ * Hook returning the privacy state — host apps can build their own
+ * masking UI on top of this.
+ */
+declare function useAllStakPrivacy(): {
+    isCapturing: boolean;
+    registerSensitiveRef: typeof registerSensitiveRef;
+};
+interface AllStakMaskedViewProps {
+    children?: React.ReactNode;
+    maskLabel?: string;
+    maskColor?: string;
+    hideScreenshot?: boolean;
+    privacy?: PrivacyLevel;
+    style?: any;
+    [key: string]: unknown;
+}
+/**
+ * Masks its children during a screenshot capture. While the SDK is
+ * capturing, this component renders a solid placeholder instead of its
+ * children; the rest of the time it's a transparent passthrough.
+ */
+declare function AllStakMaskedView({ children, maskLabel, maskColor, hideScreenshot, privacy, style, ...rest }: AllStakMaskedViewProps): React.ReactElement;
+/**
+ * Stricter variant — defaults to hiding the contents from screenshots
+ * entirely. Use for credit-card fields, IBANs, passwords, etc.
+ */
+declare function AllStakPrivacyView(props: AllStakMaskedViewProps): React.ReactElement;
+interface AllStakTextInputProps {
+    privacy?: PrivacyLevel;
+    style?: any;
+    maskColor?: string;
+    [key: string]: unknown;
+}
+/**
+ * `TextInput` wrapper that swaps to a solid masked box during capture.
+ * Always treated as sensitive unless `privacy="show"`.
+ */
+declare function AllStakTextInput({ privacy, style, maskColor, ...rest }: AllStakTextInputProps): React.ReactElement;
+interface AllStakSensitiveTextProps {
+    children?: React.ReactNode;
+    privacy?: PrivacyLevel;
+    style?: any;
+    maskLabel?: string;
+    [key: string]: unknown;
+}
+/**
+ * Wraps a Text element so it renders the mask label during capture
+ * instead of its actual children. Default privacy is `'mask'`.
+ */
+declare function AllStakSensitiveText({ children, privacy, style, maskLabel, ...rest }: AllStakSensitiveTextProps): React.ReactElement;
+
 /**
  * React Native navigation breadcrumbs — two opt-in helpers:
  *
@@ -1029,4 +1263,4 @@ declare function __devTriggerNativeCrash(): Promise<void>;
  */
 declare function drainPendingNativeCrashes(release?: string): Promise<void>;
 
-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 };
+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 };