@scalebun/react-native 1.0.0 → 1.0.2

package/src/config/configTypes.ts

@@ -1,32 +1,32 @@
-// Shape of GET {apiBaseUrl}/config (scalebun-dashboard-backend SdkConfigService).
-export interface SdkConfigPayload {
-  version: string;
-  flags: Array<{ key: string; enabled: boolean }>;
-  remoteConfig: Array<{ key: string; value: string; type: string }>;
-  experiments: Array<{
-    key: string;
-    salt: string;
-    goalEventName: string | null;
-    variants: Array<{ key: string; allocationPct: number }>;
-  }>;
-  rollouts: Array<{ key: string; salt: string; percentage: number }>;
-  /**
-   * Super-Admin Phase 3: the org's effective entitlements for the SDK-suppressible
-   * features. When a feature is false the SDK doesn't register its collector (no
-   * traffic → no server cost). Optional + fail-open: absent ⇒ treat as entitled.
-   */
-  entitlements?: {
-    replay?: boolean;
-    networkMonitoring?: boolean;
-    crashReporting?: boolean;
-    performanceMonitoring?: boolean;
-  };
-}
-
-export const EMPTY_CONFIG: SdkConfigPayload = {
-  version: '',
-  flags: [],
-  remoteConfig: [],
-  experiments: [],
-  rollouts: [],
-};
+// Shape of GET {apiBaseUrl}/config (scalebun-dashboard-backend SdkConfigService).
+export interface SdkConfigPayload {
+  version: string;
+  flags: Array<{ key: string; enabled: boolean }>;
+  remoteConfig: Array<{ key: string; value: string; type: string }>;
+  experiments: Array<{
+    key: string;
+    salt: string;
+    goalEventName: string | null;
+    variants: Array<{ key: string; allocationPct: number }>;
+  }>;
+  rollouts: Array<{ key: string; salt: string; percentage: number }>;
+  /**
+   * Super-Admin Phase 3: the org's effective entitlements for the SDK-suppressible
+   * features. When a feature is false the SDK doesn't register its collector (no
+   * traffic → no server cost). Optional + fail-open: absent ⇒ treat as entitled.
+   */
+  entitlements?: {
+    replay?: boolean;
+    networkMonitoring?: boolean;
+    crashReporting?: boolean;
+    performanceMonitoring?: boolean;
+  };
+}
+
+export const EMPTY_CONFIG: SdkConfigPayload = {
+  version: '',
+  flags: [],
+  remoteConfig: [],
+  experiments: [],
+  rollouts: [],
+};

package/src/core/architecture.ts

@@ -1,39 +1,39 @@
-/**
- * Runtime React Native architecture detection.
- *
- * Why this exists: our native-module resolvers prefer the codegen TurboModule
- * spec (`require('../specs/Native*').default`, i.e. `TurboModuleRegistry.get`).
- * On the **Old Architecture**, `TurboModuleRegistry.get()` does NOT return null —
- * it transparently falls back to the legacy `NativeModules` lookup via React
- * Native's built-in backward-compatibility layer. So "the turbo lookup
- * succeeded" is NOT proof the New Architecture is active. Inferring the
- * architecture from which lookup won therefore mislabels Old-Arch apps as
- * "New Architecture".
- *
- * The only reliable runtime signal is the TurboModule proxy / bridgeless flag
- * that the native runtime installs onto the global object when — and only when —
- * the New Architecture is enabled.
- */
-
-/**
- * `true` when the app is running on the React Native New Architecture
- * (TurboModules / Fabric / bridgeless), `false` on the Old Architecture (bridge)
- * or when there is no native runtime (web / SSR / tests).
- */
-export function isNewArchitecture(): boolean {
-  const g = globalThis as any;
-  // `__turboModuleProxy` is installed by the TurboModule runtime; `RN$Bridgeless`
-  // is set when running bridgeless (which is always New Architecture).
-  return g?.__turboModuleProxy != null || g?.RN$Bridgeless === true;
-}
-
-/**
- * Human-readable label for the active architecture and how a native module was
- * obtained — used in the one-time "native module via …" resolver logs so the
- * line reflects reality on both architectures.
- */
-export function nativeModuleVia(): string {
-  return isNewArchitecture()
-    ? 'TurboModule (New Architecture)'
-    : 'legacy NativeModules (Old Architecture)';
-}
+/**
+ * Runtime React Native architecture detection.
+ *
+ * Why this exists: our native-module resolvers prefer the codegen TurboModule
+ * spec (`require('../specs/Native*').default`, i.e. `TurboModuleRegistry.get`).
+ * On the **Old Architecture**, `TurboModuleRegistry.get()` does NOT return null —
+ * it transparently falls back to the legacy `NativeModules` lookup via React
+ * Native's built-in backward-compatibility layer. So "the turbo lookup
+ * succeeded" is NOT proof the New Architecture is active. Inferring the
+ * architecture from which lookup won therefore mislabels Old-Arch apps as
+ * "New Architecture".
+ *
+ * The only reliable runtime signal is the TurboModule proxy / bridgeless flag
+ * that the native runtime installs onto the global object when — and only when —
+ * the New Architecture is enabled.
+ */
+
+/**
+ * `true` when the app is running on the React Native New Architecture
+ * (TurboModules / Fabric / bridgeless), `false` on the Old Architecture (bridge)
+ * or when there is no native runtime (web / SSR / tests).
+ */
+export function isNewArchitecture(): boolean {
+  const g = globalThis as any;
+  // `__turboModuleProxy` is installed by the TurboModule runtime; `RN$Bridgeless`
+  // is set when running bridgeless (which is always New Architecture).
+  return g?.__turboModuleProxy != null || g?.RN$Bridgeless === true;
+}
+
+/**
+ * Human-readable label for the active architecture and how a native module was
+ * obtained — used in the one-time "native module via …" resolver logs so the
+ * line reflects reality on both architectures.
+ */
+export function nativeModuleVia(): string {
+  return isNewArchitecture()
+    ? 'TurboModule (New Architecture)'
+    : 'legacy NativeModules (Old Architecture)';
+}

package/src/core/clock/now.ts

@@ -1,6 +1,6 @@
-/**
- * Returns the current timestamp in milliseconds.
- */
-export function now(): number {
-    return Date.now();
-}
+/**
+ * Returns the current timestamp in milliseconds.
+ */
+export function now(): number {
+    return Date.now();
+}

package/src/core/config/schema.ts

@@ -1,231 +1,231 @@
-import { z, type Infer } from '../../vendor/protocol';
-import { DEFAULT_TIER2_SAMPLE_RATE } from '../../features/performance/config';
-import { DEFAULT_API_BASE_URL } from '../constants/endpoints';
-
-export const ConfigSchema = z.object({
-    projectId: z.string().min(1).optional(),
-    publishableKey: z.string().min(1).optional(),
-    /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud
-     * ({@link DEFAULT_API_BASE_URL}). Override only for staging or a
-     * self-hosted backend. Still validated as a URL when supplied.
-     */
-    apiBaseUrl: z.string().url('apiBaseUrl must be a valid URL').default(DEFAULT_API_BASE_URL),
-    debug: z.boolean().default(false),
-    /**
-     * SDK internal log verbosity. Recoverable transport failures are logged at
-     * 'warn' (never console.error), so they never surface as a RedBox.
-     * Default: 'warn'. If omitted and debug=true, the bootstrapper uses 'debug'.
-     */
-    logLevel: z.enum(['silent', 'error', 'warn', 'info', 'debug']).optional(),
-    flushIntervalMs: z.number().min(1000).default(5000),
-    /**
-     * When true, end the recording session on APP_BACKGROUND and start a fresh
-     * one on next foreground (per-foreground sessions). Default false: a single
-     * session spans app-switches; the server-side reaper closes it if the app is
-     * killed in the background. Background always flushes pending data regardless.
-     */
-    finalizeOnBackground: z.boolean().default(false),
-    /**
-     * Inactivity gap (ms) at/after which timeline time is treated as "idle" and
-     * excluded from the active session duration. Sent to the backend on session
-     * start and echoed back in the session detail so the dashboard draws idle
-     * bands + computes active duration with the SAME threshold the SDK declared
-     * (no client-side guess). Default 60000 (60s).
-     */
-    idleThresholdMs: z.number().min(1000).default(60_000),
-    /**
-     * Max time (ms) the app may stay backgrounded before the analytics session is
-     * finalized on the next foreground and a fresh one is opened ("cap then
-     * reaper"). Below the cap, a background/foreground round-trip keeps ONE
-     * session (background span is flagged, not split). The server-side stale
-     * reaper is the backstop for a true process kill. Default 1800000 (30 min).
-     */
-    sessionBackgroundCapMs: z.number().min(60_000).default(30 * 60 * 1000),
-    maxQueueSize: z.number().min(1).default(1000),
-    enableNetworkMonitoring: z.boolean().default(true),
-    /**
-     * Opt-in: capture request/response headers and bodies.
-     * Default: false — must be explicitly enabled by the integrator.
-     * See ScaleBunFeatures.captureNetworkBodies for the full privacy warning.
-     */
-    captureNetworkBodies: z.boolean().default(false),
-    /**
-     * Max bytes captured per body (request or response) before truncation.
-     * Range: 1 byte – 1 MiB. Default: 65536 (64 KiB).
-     */
-    networkBodyMaxBytes: z.number().min(1).max(1_048_576).default(65_536),
-    /**
-     * Persistent queue configuration.
-     * Controls whether the event queue persists to disk and its bounds.
-     */
-    persistence: z.object({
-        /** Enable disk persistence (survives app restarts). Default: true */
-        enabled: z.boolean().default(true),
-        /** Max total bytes stored on disk. Default: 5 MB (5_242_880) */
-        maxBytes: z.number().min(1024).default(5_242_880),
-        /** Max total entries stored. Default: 5000 */
-        maxEntries: z.number().min(10).default(5_000),
-        /** Strip PII from payloads before writing to disk. Default: true */
-        redactBeforeWrite: z.boolean().default(true),
-    }).default({}),
-    clientKey: z.string().optional(),
-    /**
-     * Upload replay frame bytes to object storage via presigned PUT instead of
-     * inline base64 in the frames JSON body. Default false (legacy inline). Safe
-     * to enable before the backend is ready: the SDK auto-falls back to inline if
-     * the presign endpoint reports storage is not configured. SaaS (clientKey) only.
-     */
-    useObjectStorage: z.boolean().default(false),
-    /**
-     * Native file-based replay outbox (durable, survives app restart/process kill).
-     * When true, frames are captured natively to disk and metadata is handed to the
-     * native outbox instead of buffering base64 in the JS in-memory pendingFrames.
-     * Default false: existing in-memory JS upload path stays the only path. If the
-     * native module or a native call is unavailable, the SDK falls back to the
-     * existing JS path. SaaS (clientKey) only — uploads target /ingestion endpoints.
-     */
-    enableNativeFileOutbox: z.boolean().default(false),
-    /**
-     * Allow the NATIVE outbox to perform uploads (presign -> PUT -> commit, plus
-     * JSONL telemetry batches) on its own. Default false: even with the outbox on,
-     * native only captures+stores; JS still drives flush by calling the native
-     * flush bridge method. Set true to let native upload directly. Requires
-     * enableNativeFileOutbox.
-     */
-    nativeOutboxUploadEnabled: z.boolean().default(false),
-    /**
-     * Within the native outbox, upload frame image bytes to object storage via
-     * presigned PUT (key-only metadata commit) instead of inline base64. Default
-     * false. If the presign endpoint reports storage disabled, native falls back to
-     * the JS path for that frame (it does NOT send base64 over the bridge in the
-     * outbox path). Requires enableNativeFileOutbox.
-     */
-    useObjectStorageForFrames: z.boolean().default(false),
-    /**
-     * Native outbox tuning (all additive, all optional — native parses both the
-     * `nativeOutbox*` keys here and bare `outbox*` aliases). These only take effect
-     * when enableNativeFileOutbox is true; defaults mirror the native ReplayConfig
-     * defaults so omitting them changes nothing.
-     */
-    /** Armed-retry interval for due outbox work, ms. Default 3000. */
-    nativeOutboxRetryIntervalMs: z.number().min(250).default(3000),
-    /** Server-attempt cap before a batch is moved to dead. Default 30. */
-    nativeOutboxMaxUploadAttempts: z.number().min(1).default(30),
-    /** Poison (4xx≠429) attempt cap before dead. Default 2. */
-    nativeOutboxPoisonMaxAttempts: z.number().min(1).default(2),
-    /** Honor server Retry-After on 429/503. Default true. */
-    nativeOutboxRespectRetryAfter: z.boolean().default(true),
-    /** Force fixed 3s retry, ignoring exponential backoff. Default false. */
-    nativeOutboxStrictThreeSecondRetry: z.boolean().default(false),
-    /** Count NETWORK_UNAVAILABLE failures toward the dead threshold. Default false. */
-    nativeOutboxNetworkFailuresCountTowardDead: z.boolean().default(false),
-    /** Outbox on-disk byte cap before GC. Default 100 MiB. */
-    nativeOutboxMaxBytes: z.number().min(1024).default(100 * 1024 * 1024),
-    /** Outbox max age before GC, ms. Default 7 days. */
-    nativeOutboxMaxAgeMs: z.number().min(1000).default(7 * 24 * 60 * 60 * 1000),
-    /**
-     * Performance pipeline activation flags (SaaS).
-     * Tiered by cost. Defaults are conservative ("default-safe"): cheap
-     * event-driven Tier-1 collectors on; heavier UI-hang watchdog and Tier-2
-     * sampled collectors OFF until device-measured. All flippable via config
-     * with no SDK release.
-     */
-    performance: z.object({
-        /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
-        enabled: z.boolean().default(true),
-        /** Tier-1: cheap, event-driven collectors. */
-        tier1: z.object({
-            /** App launch (one-shot at start). Default: true */
-            appLaunch: z.boolean().default(true),
-            /** Screen load (per navigation). Default: true */
-            screenLoad: z.boolean().default(true),
-            /** Network perf (slow/failed requests). Default: true */
-            network: z.boolean().default(true),
-            /** UI hang / ANR watchdog. Default: true — additive, forward-only (needs native module). */
-            uiHang: z.boolean().default(true),
-        }).default({}),
-        /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), sampled. */
-        tier2: z.object({
-            /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
-            enabled: z.boolean().default(true),
-            /** Per-session sampling fraction 0..1. Default: 10% — conservative, host-overridable (0 disables). */
-            sampleRate: z.number().min(0).max(1).default(DEFAULT_TIER2_SAMPLE_RATE),
-        }).default({}),
-    }).default({}),
-    /**
-     * Session-replay capture cadence for the unified SessionManager.
-     * 'navigation' (SDK default) captures only on screen change → a session with
-     * no navigation produces ~0 frames. 'frequency' captures on a timer
-     * (intervalMs, min 500ms) for a continuous replay. 'interactions' on gestures.
-     * Plumbed into SessionManager via SDKBootstrapper.
-     */
-    replay: z.object({
-        captureMode: z.enum(['navigation', 'interactions', 'frequency']).optional(),
-        intervalMs: z.number().min(500).optional(),
-        quality: z.enum(['high', 'normal', 'low', 'grayscale']).optional(),
-        // P2-5: emit deltas between keyframes (default false in DEFAULT_SESSION_REPLAY_CONFIG).
-        deltaEncoding: z.boolean().optional(),
-        deltaKeyframeInterval: z.number().int().min(1).optional(),
-    }).optional(),
-    /**
-     * Heatmap interaction capture (Feature #4).
-     *
-     * When true, tap/gesture coordinates (normalizedX/Y + gesture type + screen)
-     * are ALSO emitted to the always-on analytics lane — so heatmaps receive data
-     * even when no replay-recording session is active. This is ADDITIVE: it does
-     * NOT change replay-recording capture, and reuses the exact same USER_ACTION
-     * payload keys (normalizedX, normalizedY, gestureType, screen) the recording
-     * lane writes, so the backend aggregate reads them identically.
-     *
-     * Coordinates are NORMALIZED (0..1) and carry no PII. The analytics lane is
-     * SaaS-only (requires clientKey) and finalize-scoped per foreground; while ON
-     * a tap on every gesture is enqueued (bounded buffer, drop-oldest).
-     *
-     * Default: true (ON). Coords are normalized + PII-free, and volume is bounded
-     * by a per-foreground sampling cap in SessionManager (HEATMAP_MAX_INTERACTIONS_
-     * PER_WINDOW) so the gesture stream can't run away. Integrators who want zero
-     * extra analytics events can still set this false. SaaS (clientKey) only.
-     *
-     * CAVEAT: heatmaps populate going FORWARD only — sessions recorded before this
-     * shipped (or with the flag off) carry no analytics-lane interaction data.
-     */
-    captureInteractionHeatmap: z.boolean().default(true),
-    /**
-     * OTA (Over-the-Air) update configuration.
-     * When enabled, the SDK checks for JS bundle updates on app foreground
-     * and applies them atomically. Opt-in: existing integrators are unaffected.
-     * SaaS (clientKey) only.
-     */
-    ota: z.object({
-        /** Enable OTA update checking. Default: false (opt-in). */
-        enabled: z.boolean().default(false),
-        /** Check for updates on each app foreground. Default: true. */
-        checkOnForeground: z.boolean().default(true),
-        /** Override the auto-resolved channel (env-based). */
-        channelOverride: z.string().optional(),
-        /** Ed25519 public key for bundle signature verification (base64). */
-        publicSigningKey: z.string().optional(),
-        /** Block UI interaction while a mandatory update is pending. Default: false. */
-        mandatoryBlocksUi: z.boolean().default(false),
-    }).optional(),
-}).refine(
-    (data) => !!data.clientKey || (!!data.projectId && !!data.publishableKey),
-    { message: 'Either clientKey (SaaS mode) or both projectId and publishableKey (legacy mode) are required' }
-);
-
-export type ScaleBunConfig = Infer<typeof ConfigSchema>;
-
-// Re-export config types from contracts for consumers migrating to new import paths
-export type {
-    ScaleBunFeatures,
-    ScaleBunInitConfig,
-    SimplifiedInitConfig,
-    DebugConnectionConfig,
-    PrivacyConfig,
-    BrandingConfig,
-    ScaleBunUser,
-    ExportPresetName,
-    SimplifiedExportOptions,
-    ExportResult,
-} from '../../vendor/sdk-contracts';
+import { z, type Infer } from '../../vendor/protocol';
+import { DEFAULT_TIER2_SAMPLE_RATE } from '../../features/performance/config';
+import { DEFAULT_API_BASE_URL } from '../constants/endpoints';
+
+export const ConfigSchema = z.object({
+    projectId: z.string().min(1).optional(),
+    publishableKey: z.string().min(1).optional(),
+    /**
+     * Backend API base URL. Optional — defaults to the ScaleBun cloud
+     * ({@link DEFAULT_API_BASE_URL}). Override only for staging or a
+     * self-hosted backend. Still validated as a URL when supplied.
+     */
+    apiBaseUrl: z.string().url('apiBaseUrl must be a valid URL').default(DEFAULT_API_BASE_URL),
+    debug: z.boolean().default(false),
+    /**
+     * SDK internal log verbosity. Recoverable transport failures are logged at
+     * 'warn' (never console.error), so they never surface as a RedBox.
+     * Default: 'warn'. If omitted and debug=true, the bootstrapper uses 'debug'.
+     */
+    logLevel: z.enum(['silent', 'error', 'warn', 'info', 'debug']).optional(),
+    flushIntervalMs: z.number().min(1000).default(5000),
+    /**
+     * When true, end the recording session on APP_BACKGROUND and start a fresh
+     * one on next foreground (per-foreground sessions). Default false: a single
+     * session spans app-switches; the server-side reaper closes it if the app is
+     * killed in the background. Background always flushes pending data regardless.
+     */
+    finalizeOnBackground: z.boolean().default(false),
+    /**
+     * Inactivity gap (ms) at/after which timeline time is treated as "idle" and
+     * excluded from the active session duration. Sent to the backend on session
+     * start and echoed back in the session detail so the dashboard draws idle
+     * bands + computes active duration with the SAME threshold the SDK declared
+     * (no client-side guess). Default 60000 (60s).
+     */
+    idleThresholdMs: z.number().min(1000).default(60_000),
+    /**
+     * Max time (ms) the app may stay backgrounded before the analytics session is
+     * finalized on the next foreground and a fresh one is opened ("cap then
+     * reaper"). Below the cap, a background/foreground round-trip keeps ONE
+     * session (background span is flagged, not split). The server-side stale
+     * reaper is the backstop for a true process kill. Default 1800000 (30 min).
+     */
+    sessionBackgroundCapMs: z.number().min(60_000).default(30 * 60 * 1000),
+    maxQueueSize: z.number().min(1).default(1000),
+    enableNetworkMonitoring: z.boolean().default(true),
+    /**
+     * Opt-in: capture request/response headers and bodies.
+     * Default: false — must be explicitly enabled by the integrator.
+     * See ScaleBunFeatures.captureNetworkBodies for the full privacy warning.
+     */
+    captureNetworkBodies: z.boolean().default(false),
+    /**
+     * Max bytes captured per body (request or response) before truncation.
+     * Range: 1 byte – 1 MiB. Default: 65536 (64 KiB).
+     */
+    networkBodyMaxBytes: z.number().min(1).max(1_048_576).default(65_536),
+    /**
+     * Persistent queue configuration.
+     * Controls whether the event queue persists to disk and its bounds.
+     */
+    persistence: z.object({
+        /** Enable disk persistence (survives app restarts). Default: true */
+        enabled: z.boolean().default(true),
+        /** Max total bytes stored on disk. Default: 5 MB (5_242_880) */
+        maxBytes: z.number().min(1024).default(5_242_880),
+        /** Max total entries stored. Default: 5000 */
+        maxEntries: z.number().min(10).default(5_000),
+        /** Strip PII from payloads before writing to disk. Default: true */
+        redactBeforeWrite: z.boolean().default(true),
+    }).default({}),
+    clientKey: z.string().optional(),
+    /**
+     * Upload replay frame bytes to object storage via presigned PUT instead of
+     * inline base64 in the frames JSON body. Default false (legacy inline). Safe
+     * to enable before the backend is ready: the SDK auto-falls back to inline if
+     * the presign endpoint reports storage is not configured. SaaS (clientKey) only.
+     */
+    useObjectStorage: z.boolean().default(false),
+    /**
+     * Native file-based replay outbox (durable, survives app restart/process kill).
+     * When true, frames are captured natively to disk and metadata is handed to the
+     * native outbox instead of buffering base64 in the JS in-memory pendingFrames.
+     * Default false: existing in-memory JS upload path stays the only path. If the
+     * native module or a native call is unavailable, the SDK falls back to the
+     * existing JS path. SaaS (clientKey) only — uploads target /ingestion endpoints.
+     */
+    enableNativeFileOutbox: z.boolean().default(false),
+    /**
+     * Allow the NATIVE outbox to perform uploads (presign -> PUT -> commit, plus
+     * JSONL telemetry batches) on its own. Default false: even with the outbox on,
+     * native only captures+stores; JS still drives flush by calling the native
+     * flush bridge method. Set true to let native upload directly. Requires
+     * enableNativeFileOutbox.
+     */
+    nativeOutboxUploadEnabled: z.boolean().default(false),
+    /**
+     * Within the native outbox, upload frame image bytes to object storage via
+     * presigned PUT (key-only metadata commit) instead of inline base64. Default
+     * false. If the presign endpoint reports storage disabled, native falls back to
+     * the JS path for that frame (it does NOT send base64 over the bridge in the
+     * outbox path). Requires enableNativeFileOutbox.
+     */
+    useObjectStorageForFrames: z.boolean().default(false),
+    /**
+     * Native outbox tuning (all additive, all optional — native parses both the
+     * `nativeOutbox*` keys here and bare `outbox*` aliases). These only take effect
+     * when enableNativeFileOutbox is true; defaults mirror the native ReplayConfig
+     * defaults so omitting them changes nothing.
+     */
+    /** Armed-retry interval for due outbox work, ms. Default 3000. */
+    nativeOutboxRetryIntervalMs: z.number().min(250).default(3000),
+    /** Server-attempt cap before a batch is moved to dead. Default 30. */
+    nativeOutboxMaxUploadAttempts: z.number().min(1).default(30),
+    /** Poison (4xx≠429) attempt cap before dead. Default 2. */
+    nativeOutboxPoisonMaxAttempts: z.number().min(1).default(2),
+    /** Honor server Retry-After on 429/503. Default true. */
+    nativeOutboxRespectRetryAfter: z.boolean().default(true),
+    /** Force fixed 3s retry, ignoring exponential backoff. Default false. */
+    nativeOutboxStrictThreeSecondRetry: z.boolean().default(false),
+    /** Count NETWORK_UNAVAILABLE failures toward the dead threshold. Default false. */
+    nativeOutboxNetworkFailuresCountTowardDead: z.boolean().default(false),
+    /** Outbox on-disk byte cap before GC. Default 100 MiB. */
+    nativeOutboxMaxBytes: z.number().min(1024).default(100 * 1024 * 1024),
+    /** Outbox max age before GC, ms. Default 7 days. */
+    nativeOutboxMaxAgeMs: z.number().min(1000).default(7 * 24 * 60 * 60 * 1000),
+    /**
+     * Performance pipeline activation flags (SaaS).
+     * Tiered by cost. Defaults are conservative ("default-safe"): cheap
+     * event-driven Tier-1 collectors on; heavier UI-hang watchdog and Tier-2
+     * sampled collectors OFF until device-measured. All flippable via config
+     * with no SDK release.
+     */
+    performance: z.object({
+        /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
+        enabled: z.boolean().default(true),
+        /** Tier-1: cheap, event-driven collectors. */
+        tier1: z.object({
+            /** App launch (one-shot at start). Default: true */
+            appLaunch: z.boolean().default(true),
+            /** Screen load (per navigation). Default: true */
+            screenLoad: z.boolean().default(true),
+            /** Network perf (slow/failed requests). Default: true */
+            network: z.boolean().default(true),
+            /** UI hang / ANR watchdog. Default: true — additive, forward-only (needs native module). */
+            uiHang: z.boolean().default(true),
+        }).default({}),
+        /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), sampled. */
+        tier2: z.object({
+            /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
+            enabled: z.boolean().default(true),
+            /** Per-session sampling fraction 0..1. Default: 10% — conservative, host-overridable (0 disables). */
+            sampleRate: z.number().min(0).max(1).default(DEFAULT_TIER2_SAMPLE_RATE),
+        }).default({}),
+    }).default({}),
+    /**
+     * Session-replay capture cadence for the unified SessionManager.
+     * 'navigation' (SDK default) captures only on screen change → a session with
+     * no navigation produces ~0 frames. 'frequency' captures on a timer
+     * (intervalMs, min 500ms) for a continuous replay. 'interactions' on gestures.
+     * Plumbed into SessionManager via SDKBootstrapper.
+     */
+    replay: z.object({
+        captureMode: z.enum(['navigation', 'interactions', 'frequency']).optional(),
+        intervalMs: z.number().min(500).optional(),
+        quality: z.enum(['high', 'normal', 'low', 'grayscale']).optional(),
+        // P2-5: emit deltas between keyframes (default false in DEFAULT_SESSION_REPLAY_CONFIG).
+        deltaEncoding: z.boolean().optional(),
+        deltaKeyframeInterval: z.number().int().min(1).optional(),
+    }).optional(),
+    /**
+     * Heatmap interaction capture (Feature #4).
+     *
+     * When true, tap/gesture coordinates (normalizedX/Y + gesture type + screen)
+     * are ALSO emitted to the always-on analytics lane — so heatmaps receive data
+     * even when no replay-recording session is active. This is ADDITIVE: it does
+     * NOT change replay-recording capture, and reuses the exact same USER_ACTION
+     * payload keys (normalizedX, normalizedY, gestureType, screen) the recording
+     * lane writes, so the backend aggregate reads them identically.
+     *
+     * Coordinates are NORMALIZED (0..1) and carry no PII. The analytics lane is
+     * SaaS-only (requires clientKey) and finalize-scoped per foreground; while ON
+     * a tap on every gesture is enqueued (bounded buffer, drop-oldest).
+     *
+     * Default: true (ON). Coords are normalized + PII-free, and volume is bounded
+     * by a per-foreground sampling cap in SessionManager (HEATMAP_MAX_INTERACTIONS_
+     * PER_WINDOW) so the gesture stream can't run away. Integrators who want zero
+     * extra analytics events can still set this false. SaaS (clientKey) only.
+     *
+     * CAVEAT: heatmaps populate going FORWARD only — sessions recorded before this
+     * shipped (or with the flag off) carry no analytics-lane interaction data.
+     */
+    captureInteractionHeatmap: z.boolean().default(true),
+    /**
+     * OTA (Over-the-Air) update configuration.
+     * When enabled, the SDK checks for JS bundle updates on app foreground
+     * and applies them atomically. Opt-in: existing integrators are unaffected.
+     * SaaS (clientKey) only.
+     */
+    ota: z.object({
+        /** Enable OTA update checking. Default: false (opt-in). */
+        enabled: z.boolean().default(false),
+        /** Check for updates on each app foreground. Default: true. */
+        checkOnForeground: z.boolean().default(true),
+        /** Override the auto-resolved channel (env-based). */
+        channelOverride: z.string().optional(),
+        /** Ed25519 public key for bundle signature verification (base64). */
+        publicSigningKey: z.string().optional(),
+        /** Block UI interaction while a mandatory update is pending. Default: false. */
+        mandatoryBlocksUi: z.boolean().default(false),
+    }).optional(),
+}).refine(
+    (data) => !!data.clientKey || (!!data.projectId && !!data.publishableKey),
+    { message: 'Either clientKey (SaaS mode) or both projectId and publishableKey (legacy mode) are required' }
+);
+
+export type ScaleBunConfig = Infer<typeof ConfigSchema>;
+
+// Re-export config types from contracts for consumers migrating to new import paths
+export type {
+    ScaleBunFeatures,
+    ScaleBunInitConfig,
+    SimplifiedInitConfig,
+    DebugConnectionConfig,
+    PrivacyConfig,
+    BrandingConfig,
+    ScaleBunUser,
+    ExportPresetName,
+    SimplifiedExportOptions,
+    ExportResult,
+} from '../../vendor/sdk-contracts';

package/src/core/constants/endpoints.ts

@@ -1,9 +1,9 @@
-/**
- * ScaleBun cloud API base URL.
- *
- * Used as the default for `apiBaseUrl` when an integrator does not supply one,
- * so the common "just give me a project key" integration works without knowing
- * the server address. Override `apiBaseUrl` in init config to point at a
- * staging environment or a self-hosted backend.
- */
-export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com';
+/**
+ * ScaleBun cloud API base URL.
+ *
+ * Used as the default for `apiBaseUrl` when an integrator does not supply one,
+ * so the common "just give me a project key" integration works without knowing
+ * the server address. Override `apiBaseUrl` in init config to point at a
+ * staging environment or a self-hosted backend.
+ */
+export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com';