@scalebun/react-native 1.0.1 → 1.0.2

package/src/public/types.ts

@@ -1,312 +1,312 @@
-/**
- * ScaleBun SDK — Public Types
- *
- * User-facing TypeScript types for the SDK.
- * Only types in this file should be exported from the root index.ts.
- *
- * Preserves the current config model (projectId, publishableKey, apiBaseUrl).
- * Adds a `features` opt-out object for default-on capability control.
- */
-
-import type { ScaleBunConfig } from '../core/config/schema';
-
-// ─── Performance Config ───────────────────────────────────────────────────────
-
-/**
- * Performance pipeline activation flags, tiered by cost-vs-value.
- *
- * Defaults are conservative ("default-safe"): cheap event-driven Tier-1
- * collectors are on; the heavier UI-hang watchdog and the Tier-2 sampled
- * collectors are off until their overhead is measured on a low-end device.
- * Every flag is read at init — change rates/enablement without an SDK release.
- */
-export interface PerformanceFlags {
-    /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
-    enabled?: boolean;
-    /** Tier-1: cheap, event-driven collectors. */
-    tier1?: {
-        /** App launch (one-shot at start). Default: true */
-        appLaunch?: boolean;
-        /** Screen load (per navigation). Default: true */
-        screenLoad?: boolean;
-        /** Network perf (slow/failed requests). Default: true */
-        network?: boolean;
-        /** UI hang / ANR watchdog — emits only on a real hang. Default: true (forward-only; needs native module). */
-        uiHang?: boolean;
-    };
-    /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), per-session sampled. */
-    tier2?: {
-        /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
-        enabled?: boolean;
-        /** Per-session sampling fraction 0..1. Default: 0.1 (conservative; set 0 to disable). */
-        sampleRate?: number;
-    };
-}
-
-// ─── Feature Flags ──────────────────────────────────────────────────────────
-
-/** Feature opt-out flags. All default to `true` (enabled). */
-export interface ScaleBunFeatures {
-    /** Enable session replay capture. Default: true */
-    replay?: boolean;
-    /** Enable network request monitoring. Default: true */
-    network?: boolean;
-    /** Enable crash reporting. Default: true */
-    crashes?: boolean;
-    /** Enable unified session tracking. Default: true */
-    session?: boolean;
-    /** Enable user journey tracking. Default: true */
-    journey?: boolean;
-    /** Enable native performance monitoring. Default: true */
-    performance?: boolean;
-}
-
-// ─── Init Config ────────────────────────────────────────────────────────────
-
-/**
- * SDK initialization config.
- *
- * Extends the current core config with an optional `features` block
- * for selective feature opt-out.
- *
- * The core config properties (projectId, publishableKey, apiBaseUrl)
- * are preserved exactly as they exist today.
- */
-export interface ScaleBunInitConfig {
-    /** Project ID from dashboard */
-    projectId: string;
-    /** Publishable API key from dashboard */
-    publishableKey: string;
-    /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
-     * Override only for staging or a self-hosted backend.
-     */
-    apiBaseUrl?: string;
-    /** @deprecated Use desktopDebug instead */
-    debug?: boolean;
-    /** Enable session replay capture. Default: true */
-    sessionReplay?: boolean;
-    /** Event flush interval in ms. Default: 5000 */
-    flushIntervalMs?: number;
-    /** Max events per flush batch. Default: 1000 */
-    maxQueueSize?: number;
-    /** Enable network request monitoring. Default: true */
-    enableNetworkMonitoring?: boolean;
-    /** Feature opt-out flags (all enabled by default) */
-    features?: ScaleBunFeatures;
-    /** Performance pipeline activation flags (tiered, default-safe). */
-    performance?: PerformanceFlags;
-}
-
-// ─── User Identity ──────────────────────────────────────────────────────────
-
-/** User identity for the SDK */
-export interface ScaleBunUser {
-    /** Unique user identifier */
-    id: string;
-    /** Display name */
-    name?: string;
-    /** Email address */
-    email?: string;
-    /** Arbitrary key-value metadata */
-    attributes?: Record<string, string | number | boolean>;
-    /** Arbitrary properties (alias for attributes, used by ingestion) */
-    properties?: Record<string, any>;
-}
-
-// ─── Debug Connection Config ────────────────────────────────────────────────
-
-/**
- * Debug / desktop connection config.
- *
- * When `true`, auto-connects using resolved defaults (10.0.2.2 for Android
- * emulator, localhost otherwise, port 9333).
- *
- * When an object, provides explicit connection parameters.
- * Passing `false` or omitting disables desktop debug connection.
- */
-export type DebugConnectionConfig = boolean | {
-    /** Auto-connect to desktop using default host resolution. Default: true */
-    autoConnect?: boolean;
-    /** Explicit desktop host (IP or hostname). Overrides auto-resolution. */
-    host?: string;
-    /** Desktop WebSocket port. Default: 9333 */
-    port?: number;
-    /** App name shown in desktop device list */
-    appName?: string;
-    /** App bundle ID */
-    bundleId?: string;
-    /**
-     * Shared secret for desktop authentication.
-     * Must match the secret shown in Desktop's Connection panel.
-     *
-     * If the desktop has enforcement ON and this is omitted/wrong,
-     * the connection will be rejected (WS close code 4401).
-     *
-     * Default: null (omitted from HelloMessage — backward compatible).
-     *
-     * Migration path:
-     *   1. Open Desktop → Connection panel → copy the displayed secret.
-     *   2. Add `secret: '<copied value>'` here.
-     *   3. If the desktop has enforcement OFF, this field is ignored.
-     *
-     * SECURITY NOTE: This is local-network authentication only.
-     * The WS channel (ws://) is unencrypted. The secret prevents
-     * unauthorized connections, not eavesdropping.
-     */
-    secret?: string | null;
-};
-
-// ─── Privacy Config ─────────────────────────────────────────────────────────
-
-/** SDK-wide privacy settings */
-export interface PrivacyConfig {
-    /** Redact Authorization headers in network capture. Default: true */
-    redactAuth?: boolean;
-    /** Redact Cookie headers in network capture. Default: true */
-    redactCookies?: boolean;
-    /** Redact request/response bodies in network capture. Default: false */
-    redactBodies?: boolean;
-    /** Mask text input values in session replay. Default: false */
-    maskTextInputs?: boolean;
-    /** Mask image content in session replay. Default: false */
-    maskImages?: boolean;
-}
-
-// ─── Branding Config ────────────────────────────────────────────────────────
-
-/** Report branding settings (applied to export output) */
-export interface BrandingConfig {
-    /** Company name for report header */
-    company?: string;
-    /** Mark reports as confidential */
-    confidential?: boolean;
-    /** Custom report footer text */
-    footer?: string;
-}
-
-// ─── Export Types ───────────────────────────────────────────────────────────
-
-/** Built-in export preset names (maps to desktop BUILTIN_PRESETS) */
-export type ExportPresetName =
-    | 'executive'
-    | 'engineering'
-    | 'qa'
-    | 'forensic'
-    | 'journey'
-    | 'compact';
-
-/** Simplified export options for the public API */
-export interface SimplifiedExportOptions {
-    /** Export format. Default: 'pdf' */
-    format?: 'pdf' | 'docx';
-    /** Detail level. Default: 'standard' */
-    detail?: 'minimal' | 'standard' | 'detailed' | 'forensic';
-    /** Built-in preset to use (overrides format/detail if set) */
-    preset?: ExportPresetName;
-    /** Include screenshots in report. Default: true */
-    includeScreenshots?: boolean;
-}
-
-/** Result of an export operation */
-export interface ExportResult {
-    /** Whether the export completed successfully */
-    success: boolean;
-    /** File path where the report was saved (desktop-local) */
-    filePath?: string;
-    /** Error message if export failed */
-    error?: string;
-    /** Export was cancelled by the user */
-    cancelled?: boolean;
-}
-
-// ─── Simplified Init Config ─────────────────────────────────────────────────
-
-/**
- * Simplified SDK initialization config.
- *
- * This is the primary config type for `ScaleBun.init()`.
- * It merges the previous multi-step setup (init + enableDebug + feature flags)
- * into a single config object.
- *
- * Minimal usage:
- * ```ts
- * await ScaleBun.init({
- *   projectId: 'proj_xxx',
- *   publishableKey: 'pk_xxx',
- *   apiBaseUrl: 'https://api.scalebun.com',
- * });
- * ```
- *
- * With debug auto-connect:
- * ```ts
- * await ScaleBun.init({
- *   projectId: 'proj_xxx',
- *   publishableKey: 'pk_xxx',
- *   apiBaseUrl: 'https://api.scalebun.com',
- *   debug: true,
- * });
- * ```
- */
-export interface SimplifiedInitConfig {
-    /** Project ID from dashboard */
-    projectId: string;
-    /** Publishable API key from dashboard */
-    publishableKey: string;
-    /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
-     * Override only for staging or a self-hosted backend.
-     */
-    apiBaseUrl?: string;
-
-    /**
-     * Desktop debug connection.
-     *
-     * - `true` → auto-connect with default host/port
-     * - `{ host, port }` → explicit connection
-     * - `false` or omitted → no desktop connection
-     */
-    desktopDebug?: DebugConnectionConfig;
-
-    /** @deprecated Use desktopDebug instead. */
-    debug?: DebugConnectionConfig;
-
-    /** Enable session replay capture. Default: true */
-    sessionReplay?: boolean;
-
-    /** SDK-wide privacy settings */
-    privacy?: PrivacyConfig;
-
-    /** Feature opt-out flags (all enabled by default) */
-    features?: ScaleBunFeatures;
-
-    /** Enable verbose SDK logging. Default: false */
-    verbose?: boolean;
-    /** Event flush interval in ms. Default: 5000 */
-    flushIntervalMs?: number;
-    /** Max events per flush batch. Default: 1000 */
-    maxQueueSize?: number;
-    /** Performance pipeline activation flags (tiered, default-safe). */
-    performance?: PerformanceFlags;
-
-    // ─── Phase 1: Envelope event tracking (POST /v1/batch) ──────────────────
-    /** Dashboard App ID. Required to enable the envelope event-tracking lane. */
-    appId?: string;
-    /** SDK client key (SaaS mode). Also used to authenticate the envelope lane. */
-    clientKey?: string;
-    /** Platform override: ios | android | web | react_native. Default: react_native. */
-    platform?: 'ios' | 'android' | 'web' | 'react_native';
-    /**
-     * Enable the Phase 1 envelope tracking lane (first_open/app_open/session_start/
-     * track/identify/trackPurchase → /v1/batch). Default: true when appId is present.
-     */
-    eventTracking?: boolean;
-    /**
-     * Upload zero-instrumentation screen, deep-link, interaction, push, and Engage
-     * events. Direct `ScaleBun.init()` integrations must opt in; the application-
-     * level `ScaleBunProvider` enables it by default.
-     */
-    automaticEventTracking?: boolean;
-    /** Auto-emit first_open/app_open/session_start on init. Default: true. */
-    autoLifecycleEvents?: boolean;
-}
+/**
+ * ScaleBun SDK — Public Types
+ *
+ * User-facing TypeScript types for the SDK.
+ * Only types in this file should be exported from the root index.ts.
+ *
+ * Preserves the current config model (projectId, publishableKey, apiBaseUrl).
+ * Adds a `features` opt-out object for default-on capability control.
+ */
+
+import type { ScaleBunConfig } from '../core/config/schema';
+
+// ─── Performance Config ───────────────────────────────────────────────────────
+
+/**
+ * Performance pipeline activation flags, tiered by cost-vs-value.
+ *
+ * Defaults are conservative ("default-safe"): cheap event-driven Tier-1
+ * collectors are on; the heavier UI-hang watchdog and the Tier-2 sampled
+ * collectors are off until their overhead is measured on a low-end device.
+ * Every flag is read at init — change rates/enablement without an SDK release.
+ */
+export interface PerformanceFlags {
+    /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
+    enabled?: boolean;
+    /** Tier-1: cheap, event-driven collectors. */
+    tier1?: {
+        /** App launch (one-shot at start). Default: true */
+        appLaunch?: boolean;
+        /** Screen load (per navigation). Default: true */
+        screenLoad?: boolean;
+        /** Network perf (slow/failed requests). Default: true */
+        network?: boolean;
+        /** UI hang / ANR watchdog — emits only on a real hang. Default: true (forward-only; needs native module). */
+        uiHang?: boolean;
+    };
+    /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), per-session sampled. */
+    tier2?: {
+        /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
+        enabled?: boolean;
+        /** Per-session sampling fraction 0..1. Default: 0.1 (conservative; set 0 to disable). */
+        sampleRate?: number;
+    };
+}
+
+// ─── Feature Flags ──────────────────────────────────────────────────────────
+
+/** Feature opt-out flags. All default to `true` (enabled). */
+export interface ScaleBunFeatures {
+    /** Enable session replay capture. Default: true */
+    replay?: boolean;
+    /** Enable network request monitoring. Default: true */
+    network?: boolean;
+    /** Enable crash reporting. Default: true */
+    crashes?: boolean;
+    /** Enable unified session tracking. Default: true */
+    session?: boolean;
+    /** Enable user journey tracking. Default: true */
+    journey?: boolean;
+    /** Enable native performance monitoring. Default: true */
+    performance?: boolean;
+}
+
+// ─── Init Config ────────────────────────────────────────────────────────────
+
+/**
+ * SDK initialization config.
+ *
+ * Extends the current core config with an optional `features` block
+ * for selective feature opt-out.
+ *
+ * The core config properties (projectId, publishableKey, apiBaseUrl)
+ * are preserved exactly as they exist today.
+ */
+export interface ScaleBunInitConfig {
+    /** Project ID from dashboard */
+    projectId: string;
+    /** Publishable API key from dashboard */
+    publishableKey: string;
+    /**
+     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
+     * Override only for staging or a self-hosted backend.
+     */
+    apiBaseUrl?: string;
+    /** @deprecated Use desktopDebug instead */
+    debug?: boolean;
+    /** Enable session replay capture. Default: true */
+    sessionReplay?: boolean;
+    /** Event flush interval in ms. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max events per flush batch. Default: 1000 */
+    maxQueueSize?: number;
+    /** Enable network request monitoring. Default: true */
+    enableNetworkMonitoring?: boolean;
+    /** Feature opt-out flags (all enabled by default) */
+    features?: ScaleBunFeatures;
+    /** Performance pipeline activation flags (tiered, default-safe). */
+    performance?: PerformanceFlags;
+}
+
+// ─── User Identity ──────────────────────────────────────────────────────────
+
+/** User identity for the SDK */
+export interface ScaleBunUser {
+    /** Unique user identifier */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Arbitrary key-value metadata */
+    attributes?: Record<string, string | number | boolean>;
+    /** Arbitrary properties (alias for attributes, used by ingestion) */
+    properties?: Record<string, any>;
+}
+
+// ─── Debug Connection Config ────────────────────────────────────────────────
+
+/**
+ * Debug / desktop connection config.
+ *
+ * When `true`, auto-connects using resolved defaults (10.0.2.2 for Android
+ * emulator, localhost otherwise, port 9333).
+ *
+ * When an object, provides explicit connection parameters.
+ * Passing `false` or omitting disables desktop debug connection.
+ */
+export type DebugConnectionConfig = boolean | {
+    /** Auto-connect to desktop using default host resolution. Default: true */
+    autoConnect?: boolean;
+    /** Explicit desktop host (IP or hostname). Overrides auto-resolution. */
+    host?: string;
+    /** Desktop WebSocket port. Default: 9333 */
+    port?: number;
+    /** App name shown in desktop device list */
+    appName?: string;
+    /** App bundle ID */
+    bundleId?: string;
+    /**
+     * Shared secret for desktop authentication.
+     * Must match the secret shown in Desktop's Connection panel.
+     *
+     * If the desktop has enforcement ON and this is omitted/wrong,
+     * the connection will be rejected (WS close code 4401).
+     *
+     * Default: null (omitted from HelloMessage — backward compatible).
+     *
+     * Migration path:
+     *   1. Open Desktop → Connection panel → copy the displayed secret.
+     *   2. Add `secret: '<copied value>'` here.
+     *   3. If the desktop has enforcement OFF, this field is ignored.
+     *
+     * SECURITY NOTE: This is local-network authentication only.
+     * The WS channel (ws://) is unencrypted. The secret prevents
+     * unauthorized connections, not eavesdropping.
+     */
+    secret?: string | null;
+};
+
+// ─── Privacy Config ─────────────────────────────────────────────────────────
+
+/** SDK-wide privacy settings */
+export interface PrivacyConfig {
+    /** Redact Authorization headers in network capture. Default: true */
+    redactAuth?: boolean;
+    /** Redact Cookie headers in network capture. Default: true */
+    redactCookies?: boolean;
+    /** Redact request/response bodies in network capture. Default: false */
+    redactBodies?: boolean;
+    /** Mask text input values in session replay. Default: false */
+    maskTextInputs?: boolean;
+    /** Mask image content in session replay. Default: false */
+    maskImages?: boolean;
+}
+
+// ─── Branding Config ────────────────────────────────────────────────────────
+
+/** Report branding settings (applied to export output) */
+export interface BrandingConfig {
+    /** Company name for report header */
+    company?: string;
+    /** Mark reports as confidential */
+    confidential?: boolean;
+    /** Custom report footer text */
+    footer?: string;
+}
+
+// ─── Export Types ───────────────────────────────────────────────────────────
+
+/** Built-in export preset names (maps to desktop BUILTIN_PRESETS) */
+export type ExportPresetName =
+    | 'executive'
+    | 'engineering'
+    | 'qa'
+    | 'forensic'
+    | 'journey'
+    | 'compact';
+
+/** Simplified export options for the public API */
+export interface SimplifiedExportOptions {
+    /** Export format. Default: 'pdf' */
+    format?: 'pdf' | 'docx';
+    /** Detail level. Default: 'standard' */
+    detail?: 'minimal' | 'standard' | 'detailed' | 'forensic';
+    /** Built-in preset to use (overrides format/detail if set) */
+    preset?: ExportPresetName;
+    /** Include screenshots in report. Default: true */
+    includeScreenshots?: boolean;
+}
+
+/** Result of an export operation */
+export interface ExportResult {
+    /** Whether the export completed successfully */
+    success: boolean;
+    /** File path where the report was saved (desktop-local) */
+    filePath?: string;
+    /** Error message if export failed */
+    error?: string;
+    /** Export was cancelled by the user */
+    cancelled?: boolean;
+}
+
+// ─── Simplified Init Config ─────────────────────────────────────────────────
+
+/**
+ * Simplified SDK initialization config.
+ *
+ * This is the primary config type for `ScaleBun.init()`.
+ * It merges the previous multi-step setup (init + enableDebug + feature flags)
+ * into a single config object.
+ *
+ * Minimal usage:
+ * ```ts
+ * await ScaleBun.init({
+ *   projectId: 'proj_xxx',
+ *   publishableKey: 'pk_xxx',
+ *   apiBaseUrl: 'https://api.scalebun.com',
+ * });
+ * ```
+ *
+ * With debug auto-connect:
+ * ```ts
+ * await ScaleBun.init({
+ *   projectId: 'proj_xxx',
+ *   publishableKey: 'pk_xxx',
+ *   apiBaseUrl: 'https://api.scalebun.com',
+ *   debug: true,
+ * });
+ * ```
+ */
+export interface SimplifiedInitConfig {
+    /** Project ID from dashboard */
+    projectId: string;
+    /** Publishable API key from dashboard */
+    publishableKey: string;
+    /**
+     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
+     * Override only for staging or a self-hosted backend.
+     */
+    apiBaseUrl?: string;
+
+    /**
+     * Desktop debug connection.
+     *
+     * - `true` → auto-connect with default host/port
+     * - `{ host, port }` → explicit connection
+     * - `false` or omitted → no desktop connection
+     */
+    desktopDebug?: DebugConnectionConfig;
+
+    /** @deprecated Use desktopDebug instead. */
+    debug?: DebugConnectionConfig;
+
+    /** Enable session replay capture. Default: true */
+    sessionReplay?: boolean;
+
+    /** SDK-wide privacy settings */
+    privacy?: PrivacyConfig;
+
+    /** Feature opt-out flags (all enabled by default) */
+    features?: ScaleBunFeatures;
+
+    /** Enable verbose SDK logging. Default: false */
+    verbose?: boolean;
+    /** Event flush interval in ms. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max events per flush batch. Default: 1000 */
+    maxQueueSize?: number;
+    /** Performance pipeline activation flags (tiered, default-safe). */
+    performance?: PerformanceFlags;
+
+    // ─── Phase 1: Envelope event tracking (POST /v1/batch) ──────────────────
+    /** Dashboard App ID. Required to enable the envelope event-tracking lane. */
+    appId?: string;
+    /** SDK client key (SaaS mode). Also used to authenticate the envelope lane. */
+    clientKey?: string;
+    /** Platform override: ios | android | web | react_native. Default: react_native. */
+    platform?: 'ios' | 'android' | 'web' | 'react_native';
+    /**
+     * Enable the Phase 1 envelope tracking lane (first_open/app_open/session_start/
+     * track/identify/trackPurchase → /v1/batch). Default: true when appId is present.
+     */
+    eventTracking?: boolean;
+    /**
+     * Upload zero-instrumentation screen, deep-link, interaction, push, and Engage
+     * events. Direct `ScaleBun.init()` integrations must opt in; the application-
+     * level `ScaleBunProvider` enables it by default.
+     */
+    automaticEventTracking?: boolean;
+    /** Auto-emit first_open/app_open/session_start on init. Default: true. */
+    autoLifecycleEvents?: boolean;
+}