clintplay-react-native 0.1.0

package/app.plugin.js

@@ -0,0 +1,29 @@
+// Expo config plugin for clintplay-react-native.
+//
+// Consumers add this to their `app.json` plugins array:
+//
+//   {
+//     "expo": {
+//       "plugins": ["clintplay-react-native"]
+//     }
+//   }
+//
+// Today this plugin is a no-op: the SDK is JS-only and needs nothing
+// at prebuild time. It exists now so consumers can wire it once and
+// the upgrade path for the native TurboModule (PR 2) is seamless —
+// when PR 2 lands, the same plugin reference will start emitting
+// iOS AppDelegate hooks + Android MainApplication wiring without any
+// app-side change.
+//
+// We expose this as `app.plugin.js` (not `dist/...`) because Expo's
+// resolver looks for the plugin file relative to the package root,
+// and the file must NOT be wrapped in a build step (Expo CLI requires
+// CommonJS top-level export).
+
+/**
+ * @param {import('@expo/config-plugins').ExpoConfig} config
+ * @returns {import('@expo/config-plugins').ExpoConfig}
+ */
+const withClintplay = (config) => config;
+
+module.exports = withClintplay;

package/clintplay-react-native.podspec

@@ -0,0 +1,40 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+folly_compiler_flags = "-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32"
+
+Pod::Spec.new do |s|
+  s.name         = "clintplay-react-native"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = { "ThreadCode" => "" }
+
+  s.platforms    = { :ios => "13.4" }
+  s.source       = { :git => "https://github.com/clintdigital/clintplay.git" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.resource_bundles = { "clintplay_react_native_privacy" => ["ios/PrivacyInfo.xcprivacy"] }
+
+  # New Arch (Fabric + TurboModules). Without this guard the install
+  # still works on legacy-arch apps — the .mm file branches on
+  # `RCT_NEW_ARCH_ENABLED` so the same source serves both.
+  if defined?(install_modules_dependencies()) != nil
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+
+    if ENV["RCT_NEW_ARCH_ENABLED"] == "1" then
+      s.compiler_flags = folly_compiler_flags + " -DRCT_NEW_ARCH_ENABLED=1"
+      s.pod_target_xcconfig = {
+        "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\""
+      }
+      s.dependency "React-Codegen"
+      s.dependency "RCT-Folly"
+      s.dependency "RCTRequired"
+      s.dependency "RCTTypeSafety"
+      s.dependency "ReactCommon/turbomodule/core"
+    end
+  end
+end

package/dist/index.d.mts

@@ -0,0 +1,280 @@
+import React from 'react';
+import { ViewProps, View, TextInputProps, TextInput, ImageProps, Image, StyleProp, ViewStyle } from 'react-native';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe';
+interface DeviceInfo {
+    platform: 'ios' | 'android' | 'web';
+    osVersion?: string;
+}
+interface MetaEvent {
+    type: 'meta';
+    ts: number;
+    sessionId: string;
+    sdkVersion: string;
+    device: DeviceInfo;
+}
+interface ScreenEvent {
+    type: 'screen';
+    ts: number;
+    width: number;
+    height: number;
+    scale: number;
+    orientation: 'portrait' | 'landscape';
+}
+interface LifecycleEvent {
+    type: 'lifecycle';
+    ts: number;
+    state: 'active' | 'background' | 'inactive';
+}
+interface NavigationEvent {
+    type: 'navigation';
+    ts: number;
+    from?: string;
+    to: string;
+}
+interface TouchEvent {
+    type: 'touch';
+    ts: number;
+    x: number;
+    y: number;
+    screenX?: number;
+    screenY?: number;
+    kind: 'start' | 'move' | 'end' | 'tap' | 'long-press';
+}
+interface ErrorEvent {
+    type: 'error';
+    ts: number;
+    message: string;
+    stack?: string;
+    name?: string;
+    fatal: boolean;
+}
+interface LogEvent {
+    type: 'log';
+    ts: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+}
+interface IdentifyEvent {
+    type: 'identify';
+    ts: number;
+    userId: string | null;
+    traits?: Record<string, unknown>;
+}
+interface NetworkEvent {
+    type: 'network';
+    ts: number;
+    method: string;
+    url: string;
+    status?: number;
+    durationMs?: number;
+    error?: string;
+}
+interface WireframeNode {
+    id: number;
+    type: string;
+    className?: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    width?: number;
+    height?: number;
+    bg?: string;
+    backgroundColor?: string;
+    text?: string;
+    masked?: boolean;
+    tag?: number;
+    accessibilityIdentifier?: string;
+    accessibilityLabel?: string;
+    children?: WireframeNode[];
+}
+interface WireframeEvent {
+    type: 'wireframe';
+    ts: number;
+    version: number;
+    nodes: WireframeNode[];
+}
+type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent;
+interface BackendEvent {
+    type: string;
+    timestamp: number;
+    sessionId: string;
+    data: unknown;
+}
+interface ReplayBatch {
+    projectId: string;
+    sessionId: string;
+    events: BackendEvent[];
+    sentAt: number;
+    anonId?: string;
+    sdkVersion?: string;
+}
+interface ClintplayReactNativeConfig {
+    apiUrl: string;
+    apiKey?: string;
+    projectId?: string;
+    anonId?: string;
+    flushIntervalMs?: number;
+    flushSize?: number;
+    maxBufferSize?: number;
+    enabled?: boolean;
+    debug?: boolean;
+    sampleRate?: number;
+    captureNetwork?: boolean;
+    captureConsole?: boolean;
+    captureConsoleLog?: boolean;
+    captureWireframe?: boolean;
+    wireframeIntervalMs?: number;
+    sanitizeUrl?: (url: string) => string;
+    excludeEventTypes?: ReadonlyArray<EventType>;
+    asyncStorage?: AsyncStorageLike;
+}
+interface AsyncStorageLike {
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+}
+
+declare const CLINTPLAY_MASK_ID = "clintplay-mask";
+interface ClintplayMaskViewProps extends ViewProps {
+    children?: React.ReactNode;
+}
+declare const ClintplayMaskView: React.ForwardRefExoticComponent<ClintplayMaskViewProps & React.RefAttributes<View>>;
+
+type ClintplayMaskTextInputProps = TextInputProps;
+declare const ClintplayMaskTextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<TextInput>>;
+
+type ClintplayMaskImageProps = ImageProps;
+declare const ClintplayMaskImage: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<Image>>;
+
+interface ClintplayCaptureProviderProps extends ViewProps {
+    children?: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    enabled?: boolean;
+}
+declare function ClintplayCaptureProvider({ children, style, enabled, onTouchStart, onTouchEnd, onTouchCancel, ...rest }: ClintplayCaptureProviderProps): react_jsx_runtime.JSX.Element;
+
+interface NavigationRouteLike {
+    key?: string;
+    name?: string;
+    params?: Record<string, unknown>;
+    state?: NavigationStateLike | unknown;
+}
+interface NavigationStateLike {
+    key?: string;
+    index?: number;
+    routes?: NavigationRouteLike[];
+    routeNames?: string[];
+    [key: string]: unknown;
+}
+type NavigationStateListenerCallback = (to: string, from?: string) => void;
+interface NavigationStateListenerOptions {
+    /**
+     * Initial previous route name if known.
+     */
+    initialRouteName?: string;
+    /**
+     * Optional custom callback invoked when the route changes.
+     */
+    onRouteChanged?: NavigationStateListenerCallback;
+}
+/**
+ * Sanitizes a route name or pathname by stripping query parameters (?token=...)
+ * and fragments (#section...).
+ */
+declare function sanitizeRoute(route?: string): string | undefined;
+/**
+ * Traverses a nested React Navigation state tree to extract the active leaf route name.
+ */
+declare function getActiveRouteName(state: unknown, depth?: number): string | undefined;
+/**
+ * Creates an `onStateChange` listener for React Navigation's `<NavigationContainer>`.
+ * Automatically extracts the active leaf screen name and emits a `navigation` event
+ * while preventing duplicate consecutive emissions.
+ */
+declare function createClintplayNavigationStateListener(options?: NavigationStateListenerOptions | NavigationStateListenerCallback): (state: unknown) => void;
+interface ClintplayNavigationTrackerProps {
+    children?: React.ReactNode | ((props: {
+        onStateChange: (state: unknown) => void;
+    }) => React.ReactNode);
+    pathname?: string;
+    onStateChange?: (state: unknown) => void;
+    initialRouteName?: string;
+    onRouteChanged?: NavigationStateListenerCallback;
+}
+/**
+ * Navigation tracker component for React Navigation and Expo Router.
+ * Can be used as a wrapper, helper, or render-prop provider around `<NavigationContainer>`,
+ * or as a standalone tracker component `<ClintplayNavigationTracker pathname={pathname} />`.
+ */
+declare function ClintplayNavigationTracker({ children, pathname, onStateChange, initialRouteName, onRouteChanged, }: ClintplayNavigationTrackerProps): react_jsx_runtime.JSX.Element;
+
+interface UseClintplayNavigationOptions {
+    /**
+     * Initial previous route name if known.
+     */
+    from?: string;
+    /**
+     * Optional custom callback triggered on screen change.
+     */
+    onRouteChanged?: (to: string, from?: string) => void;
+}
+interface UseClintplayNavigationResult {
+    (state: unknown): void;
+    onStateChange: (state: unknown) => void;
+    trackScreen: (to: string, from?: string) => void;
+}
+/**
+ * Resets the shared last tracked route. Used primarily for test isolation.
+ */
+declare function _resetLastTrackedRoute(): void;
+/**
+ * Hook for automatic or manual screen tracking in React Native and Expo Router.
+ *
+ * Usage:
+ *
+ * 1. Screen-level tracking (Expo Router or per-screen):
+ * ```tsx
+ * const pathname = usePathname();
+ * useClintplayNavigationTracking(pathname);
+ * ```
+ *
+ * 2. NavigationContainer onStateChange helper:
+ * ```tsx
+ * const { onStateChange } = useClintplayNavigationTracking();
+ * <NavigationContainer onStateChange={onStateChange} />
+ * ```
+ */
+declare function useClintplayNavigationTracking(routeNameOrPath?: string, options?: UseClintplayNavigationOptions): UseClintplayNavigationResult;
+
+declare const SDK_VERSION: string;
+declare function formatEventForBatch(event: ReplayEvent | BackendEvent, defaultSessionId: string): BackendEvent;
+declare function init(rawConfig: ClintplayReactNativeConfig): void;
+declare function identify(userId: string | null, traits?: Record<string, unknown>): void;
+declare function reset(options?: {
+    clearOfflineQueue?: boolean;
+}): void;
+declare function trackScreen(path: string, from?: string): void;
+declare function reportError(err: unknown): void;
+declare function flush(): Promise<void>;
+declare function stop(): Promise<void>;
+declare function current(): {
+    sessionId: string;
+    userId: string | null;
+} | null;
+declare const Clintplay: {
+    init: typeof init;
+    identify: typeof identify;
+    reset: typeof reset;
+    trackScreen: typeof trackScreen;
+    reportError: typeof reportError;
+    flush: typeof flush;
+    stop: typeof stop;
+    current: typeof current;
+};
+
+export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, sanitizeRoute, useClintplayNavigationTracking };

package/dist/index.d.ts

@@ -0,0 +1,280 @@
+import React from 'react';
+import { ViewProps, View, TextInputProps, TextInput, ImageProps, Image, StyleProp, ViewStyle } from 'react-native';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe';
+interface DeviceInfo {
+    platform: 'ios' | 'android' | 'web';
+    osVersion?: string;
+}
+interface MetaEvent {
+    type: 'meta';
+    ts: number;
+    sessionId: string;
+    sdkVersion: string;
+    device: DeviceInfo;
+}
+interface ScreenEvent {
+    type: 'screen';
+    ts: number;
+    width: number;
+    height: number;
+    scale: number;
+    orientation: 'portrait' | 'landscape';
+}
+interface LifecycleEvent {
+    type: 'lifecycle';
+    ts: number;
+    state: 'active' | 'background' | 'inactive';
+}
+interface NavigationEvent {
+    type: 'navigation';
+    ts: number;
+    from?: string;
+    to: string;
+}
+interface TouchEvent {
+    type: 'touch';
+    ts: number;
+    x: number;
+    y: number;
+    screenX?: number;
+    screenY?: number;
+    kind: 'start' | 'move' | 'end' | 'tap' | 'long-press';
+}
+interface ErrorEvent {
+    type: 'error';
+    ts: number;
+    message: string;
+    stack?: string;
+    name?: string;
+    fatal: boolean;
+}
+interface LogEvent {
+    type: 'log';
+    ts: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+}
+interface IdentifyEvent {
+    type: 'identify';
+    ts: number;
+    userId: string | null;
+    traits?: Record<string, unknown>;
+}
+interface NetworkEvent {
+    type: 'network';
+    ts: number;
+    method: string;
+    url: string;
+    status?: number;
+    durationMs?: number;
+    error?: string;
+}
+interface WireframeNode {
+    id: number;
+    type: string;
+    className?: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    width?: number;
+    height?: number;
+    bg?: string;
+    backgroundColor?: string;
+    text?: string;
+    masked?: boolean;
+    tag?: number;
+    accessibilityIdentifier?: string;
+    accessibilityLabel?: string;
+    children?: WireframeNode[];
+}
+interface WireframeEvent {
+    type: 'wireframe';
+    ts: number;
+    version: number;
+    nodes: WireframeNode[];
+}
+type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent;
+interface BackendEvent {
+    type: string;
+    timestamp: number;
+    sessionId: string;
+    data: unknown;
+}
+interface ReplayBatch {
+    projectId: string;
+    sessionId: string;
+    events: BackendEvent[];
+    sentAt: number;
+    anonId?: string;
+    sdkVersion?: string;
+}
+interface ClintplayReactNativeConfig {
+    apiUrl: string;
+    apiKey?: string;
+    projectId?: string;
+    anonId?: string;
+    flushIntervalMs?: number;
+    flushSize?: number;
+    maxBufferSize?: number;
+    enabled?: boolean;
+    debug?: boolean;
+    sampleRate?: number;
+    captureNetwork?: boolean;
+    captureConsole?: boolean;
+    captureConsoleLog?: boolean;
+    captureWireframe?: boolean;
+    wireframeIntervalMs?: number;
+    sanitizeUrl?: (url: string) => string;
+    excludeEventTypes?: ReadonlyArray<EventType>;
+    asyncStorage?: AsyncStorageLike;
+}
+interface AsyncStorageLike {
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+    multiRemove(keys: readonly string[]): Promise<void>;
+}
+
+declare const CLINTPLAY_MASK_ID = "clintplay-mask";
+interface ClintplayMaskViewProps extends ViewProps {
+    children?: React.ReactNode;
+}
+declare const ClintplayMaskView: React.ForwardRefExoticComponent<ClintplayMaskViewProps & React.RefAttributes<View>>;
+
+type ClintplayMaskTextInputProps = TextInputProps;
+declare const ClintplayMaskTextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<TextInput>>;
+
+type ClintplayMaskImageProps = ImageProps;
+declare const ClintplayMaskImage: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<Image>>;
+
+interface ClintplayCaptureProviderProps extends ViewProps {
+    children?: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    enabled?: boolean;
+}
+declare function ClintplayCaptureProvider({ children, style, enabled, onTouchStart, onTouchEnd, onTouchCancel, ...rest }: ClintplayCaptureProviderProps): react_jsx_runtime.JSX.Element;
+
+interface NavigationRouteLike {
+    key?: string;
+    name?: string;
+    params?: Record<string, unknown>;
+    state?: NavigationStateLike | unknown;
+}
+interface NavigationStateLike {
+    key?: string;
+    index?: number;
+    routes?: NavigationRouteLike[];
+    routeNames?: string[];
+    [key: string]: unknown;
+}
+type NavigationStateListenerCallback = (to: string, from?: string) => void;
+interface NavigationStateListenerOptions {
+    /**
+     * Initial previous route name if known.
+     */
+    initialRouteName?: string;
+    /**
+     * Optional custom callback invoked when the route changes.
+     */
+    onRouteChanged?: NavigationStateListenerCallback;
+}
+/**
+ * Sanitizes a route name or pathname by stripping query parameters (?token=...)
+ * and fragments (#section...).
+ */
+declare function sanitizeRoute(route?: string): string | undefined;
+/**
+ * Traverses a nested React Navigation state tree to extract the active leaf route name.
+ */
+declare function getActiveRouteName(state: unknown, depth?: number): string | undefined;
+/**
+ * Creates an `onStateChange` listener for React Navigation's `<NavigationContainer>`.
+ * Automatically extracts the active leaf screen name and emits a `navigation` event
+ * while preventing duplicate consecutive emissions.
+ */
+declare function createClintplayNavigationStateListener(options?: NavigationStateListenerOptions | NavigationStateListenerCallback): (state: unknown) => void;
+interface ClintplayNavigationTrackerProps {
+    children?: React.ReactNode | ((props: {
+        onStateChange: (state: unknown) => void;
+    }) => React.ReactNode);
+    pathname?: string;
+    onStateChange?: (state: unknown) => void;
+    initialRouteName?: string;
+    onRouteChanged?: NavigationStateListenerCallback;
+}
+/**
+ * Navigation tracker component for React Navigation and Expo Router.
+ * Can be used as a wrapper, helper, or render-prop provider around `<NavigationContainer>`,
+ * or as a standalone tracker component `<ClintplayNavigationTracker pathname={pathname} />`.
+ */
+declare function ClintplayNavigationTracker({ children, pathname, onStateChange, initialRouteName, onRouteChanged, }: ClintplayNavigationTrackerProps): react_jsx_runtime.JSX.Element;
+
+interface UseClintplayNavigationOptions {
+    /**
+     * Initial previous route name if known.
+     */
+    from?: string;
+    /**
+     * Optional custom callback triggered on screen change.
+     */
+    onRouteChanged?: (to: string, from?: string) => void;
+}
+interface UseClintplayNavigationResult {
+    (state: unknown): void;
+    onStateChange: (state: unknown) => void;
+    trackScreen: (to: string, from?: string) => void;
+}
+/**
+ * Resets the shared last tracked route. Used primarily for test isolation.
+ */
+declare function _resetLastTrackedRoute(): void;
+/**
+ * Hook for automatic or manual screen tracking in React Native and Expo Router.
+ *
+ * Usage:
+ *
+ * 1. Screen-level tracking (Expo Router or per-screen):
+ * ```tsx
+ * const pathname = usePathname();
+ * useClintplayNavigationTracking(pathname);
+ * ```
+ *
+ * 2. NavigationContainer onStateChange helper:
+ * ```tsx
+ * const { onStateChange } = useClintplayNavigationTracking();
+ * <NavigationContainer onStateChange={onStateChange} />
+ * ```
+ */
+declare function useClintplayNavigationTracking(routeNameOrPath?: string, options?: UseClintplayNavigationOptions): UseClintplayNavigationResult;
+
+declare const SDK_VERSION: string;
+declare function formatEventForBatch(event: ReplayEvent | BackendEvent, defaultSessionId: string): BackendEvent;
+declare function init(rawConfig: ClintplayReactNativeConfig): void;
+declare function identify(userId: string | null, traits?: Record<string, unknown>): void;
+declare function reset(options?: {
+    clearOfflineQueue?: boolean;
+}): void;
+declare function trackScreen(path: string, from?: string): void;
+declare function reportError(err: unknown): void;
+declare function flush(): Promise<void>;
+declare function stop(): Promise<void>;
+declare function current(): {
+    sessionId: string;
+    userId: string | null;
+} | null;
+declare const Clintplay: {
+    init: typeof init;
+    identify: typeof identify;
+    reset: typeof reset;
+    trackScreen: typeof trackScreen;
+    reportError: typeof reportError;
+    flush: typeof flush;
+    stop: typeof stop;
+    current: typeof current;
+};
+
+export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, sanitizeRoute, useClintplayNavigationTracking };