@scalebun/react-native 1.0.0 → 1.0.2

package/src/public/ScaleBunProvider.tsx

@@ -1,91 +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>
-    );
-}
+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

@@ -1,123 +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;
-}
+/**
+ * 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;
+}