@koderlabs/tasks-sdk-rn 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,174 @@
+import { InitOptions, Client } from '@koderlabs/tasks-sdk';
+
+interface RnInitOptions extends InitOptions {
+    /**
+     * Capture global uncaught JS errors via ErrorUtils.setGlobalHandler.
+     * Default: true.
+     */
+    captureGlobalErrors?: boolean;
+    /**
+     * Capture unhandled promise rejections.
+     * Default: true. Uses HermesInternal where available, falls back to
+     * process.on('unhandledRejection') for legacy JSC.
+     */
+    captureUnhandledRejections?: boolean;
+    /**
+     * Capture console.error / console.warn as breadcrumbs.
+     * Default: true.
+     */
+    captureConsole?: boolean;
+    /**
+     * Capture fetch() request/response metadata as breadcrumbs.
+     * Default: true. Bodies are never captured (PII risk).
+     */
+    captureNetwork?: boolean;
+    /** Allowlist regex — only record breadcrumbs for matching URLs. */
+    networkIncludeUrls?: RegExp[];
+    /** Denylist regex — skip URLs (ingest endpoint is always skipped). */
+    networkExcludeUrls?: RegExp[];
+    /** Tag requests above this duration as `slow:true`. Default 2000ms. */
+    networkSlowThresholdMs?: number;
+    /**
+     * Include URL query string in network breadcrumbs. Default false — query
+     * strings often contain tokens / emails / IDs that you don't want shipped.
+     * Set to true only if you've already stripped sensitive params upstream.
+     */
+    networkIncludeQueryString?: boolean;
+    /**
+     * Capture AppState foreground/background transitions as breadcrumbs.
+     * Default: true.
+     */
+    captureAppState?: boolean;
+    /**
+     * Recover native crash JSON written by the Expo config plugin's
+     * uncaught-exception handler on the previous launch. Default: true.
+     * No-op when `expo-file-system` isn't installed.
+     */
+    captureNativeCrash?: boolean;
+    /**
+     * Max breadcrumbs to retain in ring buffer.
+     * Default: 50.
+     */
+    maxBreadcrumbs?: number;
+    /**
+     * Surface native-crash recovery errors (file IO, parse, native module load).
+     * Without this, a failed crash decode is indistinguishable from "no crash" —
+     * operators rely on this to detect silent capture regressions.
+     */
+    onNativeCrashError?: (err: {
+        stage: string;
+        message: string;
+        cause?: unknown;
+    }) => void;
+    /**
+     * Override the platform/release info auto-detected from react-native.
+     * Useful in tests where react-native is not loaded.
+     */
+    platformOverride?: {
+        os?: string;
+        osVersion?: string;
+        deviceModel?: string;
+        bundleId?: string;
+    };
+}
+interface Breadcrumb {
+    ts: string;
+    category: 'navigation' | 'http' | 'console' | 'user' | 'custom';
+    message: string;
+    level?: 'info' | 'warning' | 'error';
+    data?: Record<string, unknown>;
+}
+
+declare class BreadcrumbBuffer {
+    private max;
+    private buf;
+    constructor(max?: number);
+    add(b: Breadcrumb): void;
+    drain(): Breadcrumb[];
+    clear(): void;
+}
+
+/**
+ * Navigation breadcrumb helpers. Router-agnostic.
+ *
+ * Two integration styles are supported:
+ *
+ *  1. Manual — the app pushes a breadcrumb on every screen change by calling
+ *     `recordNavigation(from, to, params?)`. Works with any navigator (React
+ *     Navigation, Expo Router, custom).
+ *
+ *  2. Helper-attached — the app passes a navigation listener / state observer
+ *     into `attachReactNavigation()` or `attachExpoRouter()` which wires the
+ *     internal callbacks. These are thin wrappers — they only call
+ *     `recordNavigation` — but keep the integration surface obvious for
+ *     copy-paste setup code.
+ *
+ * Navigation breadcrumbs use category 'navigation' so triagers can filter
+ * them alongside AppState transitions and deep-link openings.
+ */
+
+/**
+ * Record a manual navigation breadcrumb. Safe to call from any router.
+ * Empty `from` is allowed for the initial route.
+ */
+declare function recordNavigation(buffer: BreadcrumbBuffer, to: string, opts?: {
+    from?: string;
+    params?: Record<string, unknown>;
+}): void;
+/**
+ * Attach to React Navigation 6/7 — pass the navigation container ref.
+ * Listens to 'state' and records the active route name on every change.
+ *
+ * Usage:
+ *   const navRef = useNavigationContainerRef();
+ *   useEffect(() => attachReactNavigation(client.buffer, navRef), [navRef]);
+ */
+declare function attachReactNavigation(buffer: BreadcrumbBuffer, navRef: {
+    addListener: (event: 'state' | string, fn: () => void) => () => void;
+    getCurrentRoute?: () => {
+        name: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+}): () => void;
+/**
+ * Attach to Expo Router. Expo Router doesn't surface a single listener
+ * channel — pass `usePathname()` output to `recordNavigation` from a
+ * top-level effect. This helper provides a callback the app calls each
+ * time its top-level `_layout.tsx` sees a path change.
+ *
+ * Usage:
+ *   const pathname = usePathname();
+ *   const reportPath = useExpoRouterReporter(client.buffer);
+ *   useEffect(() => reportPath(pathname), [pathname]);
+ */
+declare function useExpoRouterReporter(buffer: BreadcrumbBuffer): (pathname: string) => void;
+
+interface RnClientHandle {
+    client: Client;
+    buffer: BreadcrumbBuffer;
+    /** Manually capture an error. */
+    captureException(err: unknown, ctx?: {
+        level?: 'fatal' | 'error' | 'warning';
+    }): void;
+    /** Add a manual breadcrumb. */
+    addBreadcrumb(b: {
+        category: 'navigation' | 'http' | 'console' | 'user' | 'custom';
+        message: string;
+        data?: Record<string, unknown>;
+        level?: 'info' | 'warning' | 'error';
+    }): void;
+    /** Record a navigation transition. */
+    recordNavigation(to: string, opts?: {
+        from?: string;
+        params?: Record<string, unknown>;
+    }): void;
+    /** Flush queued events / spans. Best-effort; resolves when done. */
+    flush(): Promise<void>;
+    /** Stop all auto-instrumentation. */
+    close(): Promise<void>;
+}
+declare function init(opts: RnInitOptions): RnClientHandle;
+declare function getClient(): Client | null;
+declare function getBuffer(): BreadcrumbBuffer | null;
+
+export { type Breadcrumb, BreadcrumbBuffer, type RnClientHandle, type RnInitOptions, attachReactNavigation, getBuffer, getClient, init, recordNavigation, useExpoRouterReporter };

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+import { InitOptions, Client } from '@koderlabs/tasks-sdk';
+
+interface RnInitOptions extends InitOptions {
+    /**
+     * Capture global uncaught JS errors via ErrorUtils.setGlobalHandler.
+     * Default: true.
+     */
+    captureGlobalErrors?: boolean;
+    /**
+     * Capture unhandled promise rejections.
+     * Default: true. Uses HermesInternal where available, falls back to
+     * process.on('unhandledRejection') for legacy JSC.
+     */
+    captureUnhandledRejections?: boolean;
+    /**
+     * Capture console.error / console.warn as breadcrumbs.
+     * Default: true.
+     */
+    captureConsole?: boolean;
+    /**
+     * Capture fetch() request/response metadata as breadcrumbs.
+     * Default: true. Bodies are never captured (PII risk).
+     */
+    captureNetwork?: boolean;
+    /** Allowlist regex — only record breadcrumbs for matching URLs. */
+    networkIncludeUrls?: RegExp[];
+    /** Denylist regex — skip URLs (ingest endpoint is always skipped). */
+    networkExcludeUrls?: RegExp[];
+    /** Tag requests above this duration as `slow:true`. Default 2000ms. */
+    networkSlowThresholdMs?: number;
+    /**
+     * Include URL query string in network breadcrumbs. Default false — query
+     * strings often contain tokens / emails / IDs that you don't want shipped.
+     * Set to true only if you've already stripped sensitive params upstream.
+     */
+    networkIncludeQueryString?: boolean;
+    /**
+     * Capture AppState foreground/background transitions as breadcrumbs.
+     * Default: true.
+     */
+    captureAppState?: boolean;
+    /**
+     * Recover native crash JSON written by the Expo config plugin's
+     * uncaught-exception handler on the previous launch. Default: true.
+     * No-op when `expo-file-system` isn't installed.
+     */
+    captureNativeCrash?: boolean;
+    /**
+     * Max breadcrumbs to retain in ring buffer.
+     * Default: 50.
+     */
+    maxBreadcrumbs?: number;
+    /**
+     * Surface native-crash recovery errors (file IO, parse, native module load).
+     * Without this, a failed crash decode is indistinguishable from "no crash" —
+     * operators rely on this to detect silent capture regressions.
+     */
+    onNativeCrashError?: (err: {
+        stage: string;
+        message: string;
+        cause?: unknown;
+    }) => void;
+    /**
+     * Override the platform/release info auto-detected from react-native.
+     * Useful in tests where react-native is not loaded.
+     */
+    platformOverride?: {
+        os?: string;
+        osVersion?: string;
+        deviceModel?: string;
+        bundleId?: string;
+    };
+}
+interface Breadcrumb {
+    ts: string;
+    category: 'navigation' | 'http' | 'console' | 'user' | 'custom';
+    message: string;
+    level?: 'info' | 'warning' | 'error';
+    data?: Record<string, unknown>;
+}
+
+declare class BreadcrumbBuffer {
+    private max;
+    private buf;
+    constructor(max?: number);
+    add(b: Breadcrumb): void;
+    drain(): Breadcrumb[];
+    clear(): void;
+}
+
+/**
+ * Navigation breadcrumb helpers. Router-agnostic.
+ *
+ * Two integration styles are supported:
+ *
+ *  1. Manual — the app pushes a breadcrumb on every screen change by calling
+ *     `recordNavigation(from, to, params?)`. Works with any navigator (React
+ *     Navigation, Expo Router, custom).
+ *
+ *  2. Helper-attached — the app passes a navigation listener / state observer
+ *     into `attachReactNavigation()` or `attachExpoRouter()` which wires the
+ *     internal callbacks. These are thin wrappers — they only call
+ *     `recordNavigation` — but keep the integration surface obvious for
+ *     copy-paste setup code.
+ *
+ * Navigation breadcrumbs use category 'navigation' so triagers can filter
+ * them alongside AppState transitions and deep-link openings.
+ */
+
+/**
+ * Record a manual navigation breadcrumb. Safe to call from any router.
+ * Empty `from` is allowed for the initial route.
+ */
+declare function recordNavigation(buffer: BreadcrumbBuffer, to: string, opts?: {
+    from?: string;
+    params?: Record<string, unknown>;
+}): void;
+/**
+ * Attach to React Navigation 6/7 — pass the navigation container ref.
+ * Listens to 'state' and records the active route name on every change.
+ *
+ * Usage:
+ *   const navRef = useNavigationContainerRef();
+ *   useEffect(() => attachReactNavigation(client.buffer, navRef), [navRef]);
+ */
+declare function attachReactNavigation(buffer: BreadcrumbBuffer, navRef: {
+    addListener: (event: 'state' | string, fn: () => void) => () => void;
+    getCurrentRoute?: () => {
+        name: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+}): () => void;
+/**
+ * Attach to Expo Router. Expo Router doesn't surface a single listener
+ * channel — pass `usePathname()` output to `recordNavigation` from a
+ * top-level effect. This helper provides a callback the app calls each
+ * time its top-level `_layout.tsx` sees a path change.
+ *
+ * Usage:
+ *   const pathname = usePathname();
+ *   const reportPath = useExpoRouterReporter(client.buffer);
+ *   useEffect(() => reportPath(pathname), [pathname]);
+ */
+declare function useExpoRouterReporter(buffer: BreadcrumbBuffer): (pathname: string) => void;
+
+interface RnClientHandle {
+    client: Client;
+    buffer: BreadcrumbBuffer;
+    /** Manually capture an error. */
+    captureException(err: unknown, ctx?: {
+        level?: 'fatal' | 'error' | 'warning';
+    }): void;
+    /** Add a manual breadcrumb. */
+    addBreadcrumb(b: {
+        category: 'navigation' | 'http' | 'console' | 'user' | 'custom';
+        message: string;
+        data?: Record<string, unknown>;
+        level?: 'info' | 'warning' | 'error';
+    }): void;
+    /** Record a navigation transition. */
+    recordNavigation(to: string, opts?: {
+        from?: string;
+        params?: Record<string, unknown>;
+    }): void;
+    /** Flush queued events / spans. Best-effort; resolves when done. */
+    flush(): Promise<void>;
+    /** Stop all auto-instrumentation. */
+    close(): Promise<void>;
+}
+declare function init(opts: RnInitOptions): RnClientHandle;
+declare function getClient(): Client | null;
+declare function getBuffer(): BreadcrumbBuffer | null;
+
+export { type Breadcrumb, BreadcrumbBuffer, type RnClientHandle, type RnInitOptions, attachReactNavigation, getBuffer, getClient, init, recordNavigation, useExpoRouterReporter };