@scalebun-release/react-native 2.5.0

package/src/public/ScaleBunProvider.tsx

@@ -0,0 +1,91 @@
+import React, {
+    type ReactElement,
+    type ReactNode,
+    useEffect,
+    useRef,
+} from 'react';
+import ScaleBun from './ScaleBunFacade';
+import type {
+    ScaleBunInitConfig,
+    SimplifiedInitConfig,
+} from './types';
+import {
+    EngagePromptProvider,
+    type EngagePromptProviderProps,
+} from '../features/engage/EngagePromptProvider';
+import { ScaleBunDebugRoot } from '../features/journey/ScaleBunDebugRoot';
+
+export interface ScaleBunProviderProps
+    extends Omit<EngagePromptProviderProps, 'engage' | 'children'> {
+    /** The same object accepted by `ScaleBun.init()`. Read once on mount. */
+    config: SimplifiedInitConfig | ScaleBunInitConfig | Record<string, unknown>;
+    /** Optional React Navigation ref used by automatic screen collection. */
+    navigationRef?: unknown;
+    /**
+     * Capture privacy-safe root touch metadata without wrapping individual
+     * buttons. Defaults to true; no text/input value is collected.
+     */
+    captureInteractions?: boolean;
+    onReady?: () => void;
+    onInitError?: (error: unknown) => void;
+    children: ReactNode;
+}
+
+/**
+ * One application-level wrapper for initialization, Engage rendering, screen
+ * discovery, and zero-instrumentation interaction collection.
+ */
+export function ScaleBunProvider({
+    config,
+    navigationRef,
+    captureInteractions = true,
+    onReady,
+    onInitError,
+    children,
+    ...engageProps
+}: ScaleBunProviderProps): ReactElement {
+    const configRecord = config as Record<string, unknown>;
+    // Mounting the unified provider is the explicit adoption boundary for the
+    // zero-instrumentation stream. A caller can still opt out in config.
+    const automaticEventTracking =
+        configRecord.eventTracking !== false &&
+        configRecord.automaticEventTracking !== false;
+    const initialConfig = useRef({
+        ...configRecord,
+        automaticEventTracking,
+    });
+
+    useEffect(() => {
+        let active = true;
+        Promise.resolve(ScaleBun.init(initialConfig.current))
+            .then(() => {
+                if (active) onReady?.();
+            })
+            .catch((error) => {
+                if (active) onInitError?.(error);
+            });
+        return () => {
+            active = false;
+        };
+        // SDK initialization is intentionally once-per-provider mount.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    useEffect(() => {
+        if (navigationRef) ScaleBun.setNavigationRef(navigationRef);
+    }, [navigationRef]);
+
+    return (
+        <ScaleBunDebugRoot
+            navigationRef={navigationRef}
+            captureAutomaticInteractions={
+                captureInteractions && automaticEventTracking
+            }
+            suppressDeprecationWarning
+        >
+            <EngagePromptProvider engage={ScaleBun.engage} {...engageProps}>
+                {children}
+            </EngagePromptProvider>
+        </ScaleBunDebugRoot>
+    );
+}

package/src/public/typedTracker.ts

@@ -0,0 +1,123 @@
+/**
+ * TYPED TRACKING PLAN — compile-time checking for `track()`.
+ *
+ * Mirrors the web SDK's `typedTracker.ts` on purpose: `track(name, props)` is the ONE call that
+ * behaves identically on both platforms. The automatic-event vocabularies share nothing — web emits
+ * `$pageview`/`$autocapture`/`$form_start`, this SDK emits `screen_viewed`/`app_foregrounded`/
+ * `permission_result` — so any event a product wants on BOTH has to be an explicit `track()`. A
+ * cross-platform event deserves one shared declaration, and this is the shape of it.
+ *
+ *   const tracker = createTypedTracker(ScaleBun, {
+ *     appointment_booked: {
+ *       required: ['clinic_id', 'slot_type'],
+ *       props: { clinic_id: 'string', slot_type: 'string', lead_time_hours: 'number' },
+ *     },
+ *   });
+ *
+ *   tracker.track('appointment_booked', { clinic_id: 'jc_01', slot_type: 'same_day' });   // ✓
+ *   tracker.track('appointment_bookd',  { … });                       // ✗ unknown event
+ *   tracker.track('appointment_booked', { clinic_id: 1, … });         // ✗ wrong type
+ *
+ * ⚠️ ONE DIFFERENCE FROM WEB, stated rather than left to be discovered: the web SDK ALSO evaluates
+ * its plan at RUNTIME (`analyticsOptions.plan` → `governance.ts`), so there a violation additionally
+ * warns and — in strict mode — drops. **This SDK has no runtime governance consumer today.** So
+ * `tracker.plan` is types-only here. It is exported in the identical shape so a single plan object
+ * can be shared with a web build and so it is already correct if runtime governance ever lands, but
+ * nothing on this platform reads it yet. Do not assume a violation is caught at runtime on mobile.
+ *
+ * Zero third-party dependencies, ~10 lines of runtime. Everything else is types, which cost nothing
+ * in the bundle.
+ */
+
+/** The primitive types a plan can declare. */
+export type PlanPropType = 'string' | 'number' | 'boolean';
+
+export interface TrackedEventSpec {
+    /** Property keys that must be present. */
+    readonly required?: readonly string[];
+    /** Expected primitive type per property key. */
+    readonly props?: Readonly<Record<string, PlanPropType>>;
+}
+
+export type TrackedEventMap = Readonly<Record<string, TrackedEventSpec>>;
+
+type Primitive<T> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
+
+type RequiredKeys<S extends TrackedEventSpec> = S['required'] extends readonly (infer K extends string)[] ? K : never;
+
+type Declared<S extends TrackedEventSpec> = S['props'] extends Readonly<Record<string, PlanPropType>>
+    ? S['props']
+    : Record<never, never>;
+
+/**
+ * The props object for one event: declared-and-required become mandatory, declared-and-not-required
+ * become optional, and a key listed in `required` but never typed stays mandatory as `unknown` — the
+ * plan said it must be there, and silently dropping it would be worse than typing it loosely.
+ */
+export type PropsFor<S extends TrackedEventSpec> = {
+    [K in keyof Declared<S> as K extends RequiredKeys<S> ? K : never]: Primitive<Declared<S>[K]>;
+} & {
+    [K in keyof Declared<S> as K extends RequiredKeys<S> ? never : K]?: Primitive<Declared<S>[K]>;
+} & {
+    [K in Exclude<RequiredKeys<S>, keyof Declared<S>>]: unknown;
+};
+
+/** Whether an event can be tracked with no argument at all (nothing required). */
+type PropsArg<S extends TrackedEventSpec> = Record<string, never> extends PropsFor<S>
+    ? [props?: PropsFor<S>]
+    : [props: PropsFor<S>];
+
+/** The minimum surface a tracker needs — the ScaleBun facade satisfies it structurally. */
+export interface TrackTarget {
+    track(name: string, props?: Record<string, any>): void;
+}
+
+/** The plan shape, kept byte-identical to web so one declaration can serve both platforms. */
+export interface TypedTrackerPlan<M extends TrackedEventMap> {
+    events: M;
+    allowUnknownEvents: boolean;
+    strict: boolean;
+}
+
+export interface TypedTracker<M extends TrackedEventMap> {
+    /** Type-checked `track`. Unknown event names and bad props are compile errors. */
+    track<N extends keyof M & string>(name: N, ...args: PropsArg<M[N]>): void;
+    /**
+     * The plan object. On WEB this goes to `init({ analytics: { plan } })` and is enforced at runtime;
+     * on this platform nothing reads it yet — see the note at the top of this file.
+     */
+    readonly plan: TypedTrackerPlan<M>;
+    /** Escape hatch for a genuinely dynamic name — explicit, so it is greppable in review. */
+    trackUnchecked(name: string, props?: Record<string, any>): void;
+}
+
+export function createTypedTracker<const M extends TrackedEventMap>(
+    sdk: TrackTarget,
+    events: M,
+    options: { allowUnknownEvents?: boolean; strict?: boolean } = {},
+): TypedTracker<M> {
+    const plan: TypedTrackerPlan<M> = {
+        events,
+        // Deliberately the STRICTER pair: if you declared a plan in code, an undeclared event is a
+        // mistake. `strict` still defaults to false — dropping events is never a default.
+        allowUnknownEvents: options.allowUnknownEvents ?? false,
+        strict: options.strict ?? false,
+    };
+    return {
+        track(name, ...args) {
+            sdk.track(name, args[0] as Record<string, any> | undefined);
+        },
+        plan,
+        trackUnchecked(name, props) {
+            sdk.track(name, props);
+        },
+    };
+}
+
+/**
+ * Declare a plan without wiring a tracker — for sharing one plan across modules or across platforms.
+ * Identity at runtime; its whole job is to preserve the literal types (via `const`).
+ */
+export function defineTrackingPlan<const M extends TrackedEventMap>(events: M): M {
+    return events;
+}

package/src/public/types.ts

@@ -0,0 +1,362 @@
+/**
+ * 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;
+    /**
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
+     */
+    apiBaseUrl?: string;
+    /** @deprecated Use desktopDebug instead */
+    debug?: boolean;
+    /** Enable session replay capture (feature on/off). Default: true */
+    sessionReplay?: boolean;
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
+    /** 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;
+    /**
+     * Capture `console.*` output into the Diagnose → Logs lane (SaaS mode). Default: **false**.
+     * Off by default because console output can carry PII/secrets and adds ingest volume.
+     * Requires a `clientKey`; no desktop-debug/devTools setup needed.
+     */
+    captureConsoleLogs?: boolean;
+}
+
+// ─── 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: true */
+    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',
+ * });
+ * ```
+ *
+ * With debug auto-connect:
+ * ```ts
+ * await ScaleBun.init({
+ *   projectId: 'proj_xxx',
+ *   publishableKey: 'pk_xxx',
+ *   debug: true,
+ * });
+ * ```
+ */
+export interface SimplifiedInitConfig {
+    /** Project ID from dashboard */
+    projectId: string;
+    /** Publishable API key from dashboard */
+    publishableKey: string;
+    /**
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
+     */
+    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 (feature on/off). Default: true */
+    sessionReplay?: boolean;
+
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
+
+    /** 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;
+
+    /**
+     * Capture `console.*` output into the Diagnose → Logs lane (SaaS mode). Default: **false**.
+     * Off by default because console output can carry PII/secrets and adds ingest volume —
+     * enable it deliberately. Requires a `clientKey`; no desktop-debug/devTools setup needed.
+     */
+    captureConsoleLogs?: boolean;
+
+    // ─── 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;
+    /**
+     * Patch React Native's ScrollView export so every scroll view reports its scroll offset,
+     * giving taps their content depth without the app swapping to ScaleBunScrollView.
+     *
+     * OFF BY DEFAULT because it changes what the host renders, not merely what the SDK records:
+     * every scroll view in the app — including ones inside libraries you did not write — routes
+     * through an SDK wrapper. Turn it on deliberately. With it off, taps on a plain ScrollView
+     * report no content depth and say so, rather than reporting a fabricated offset of 0.
+     */
+    autoInstrumentScrollViews?: boolean;
+    /** Platform OVERRIDE — auto-detected from Platform.OS when omitted (integrations should omit it). */
+    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;
+}