@cxpinsight/react-native 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CXPinsight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @cxpinsight/react-native
+
+Engagement tracking, native survey modals, session replay and visual setup mode for React Native and Expo apps.
+
+Install once. New surveys, triggers and capture settings ship from the CXPinsight dashboard — no app release required.
+
+```sh
+npm install @cxpinsight/react-native
+npx expo install react-native-view-shot   # optional — screenshots in the replay
+```
+
+## Quick start
+
+### 1. Auto-instrument taps, inputs and scroll
+
+Add the Babel plugin so taps, text input and scroll are captured without touching your screens.
+
+```js
+// babel.config.js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['@cxpinsight/react-native/babel'],
+  };
+};
+```
+
+The plugin rewrites `TouchableOpacity`, `Pressable`, `TextInput` and `ScrollView` imports in **your** source only — never inside `node_modules`, and never inside the SDK itself.
+
+### 2. Initialise at startup
+
+```js
+import { CXPinsight } from '@cxpinsight/react-native';
+import { captureScreen } from 'react-native-view-shot';
+
+CXPinsight.init({
+  applicationId: 'YOUR_APPLICATION_ID',
+  apiKey: 'YOUR_API_KEY',
+  apiBase: 'https://your-gateway.example.com',
+
+  record: true,             // session replay: screens, taps, scroll, inputs
+  recordMaskInputs: true,   // never store typed text
+  captureScreen: () =>      // optional screenshots in the replay timeline
+    captureScreen({ format: 'jpg', quality: 0.3, result: 'base64' }),
+});
+```
+
+On a physical device `apiBase` must be reachable from the device — use your machine's LAN IP, not `localhost`. The SDK checks this at startup and logs a specific message if it looks wrong.
+
+### 3. Report screen changes
+
+```jsx
+import { useRef } from 'react';
+import { CXPinsightProvider, CXPinsight } from '@cxpinsight/react-native';
+
+const navigationRef = useRef(null);
+
+<CXPinsightProvider navigationRef={navigationRef}>
+  <NavigationContainer
+    ref={navigationRef}
+    onStateChange={() => {
+      const name = navigationRef.current?.getCurrentRoute()?.name;
+      if (name) CXPinsight.trackScreen(name);
+    }}
+  >
+    {/* your navigators */}
+  </NavigationContainer>
+</CXPinsightProvider>
+```
+
+`CXPinsightProvider` also hosts the survey modal and setup overlay, so it must wrap the app for surveys to appear.
+
+### 4. Identify the user after sign-in
+
+```js
+CXPinsight.identify({ id: user.id, email: user.email, name: user.name });
+```
+
+Events recorded before `identify()` are re-attributed to the user automatically, so one visitor does not show up as two.
+
+## API
+
+| Method | Purpose |
+| --- | --- |
+| `init(config, callbacks?)` | Start the SDK. Call once at startup. |
+| `identify(user)` | Attach a real user identity; re-attributes prior anonymous activity. |
+| `track(name, data?)` | Record a custom event. |
+| `trackScreen(name, data?)` | Record a screen view. |
+| `trackFunnelStep(...)` / `trackExperiment(...)` / `trackConversion(...)` | Typed helpers over `track`. |
+| `showSurvey(surveyId)` | Present a survey immediately. |
+| `startRecording()` / `stopRecording()` | Session replay, for hosts that gate on their own consent UI. |
+| `enterSetupMode()` / `exitSetupMode()` | Visual element mapping — tap an element to make it trackable. |
+| `flush()` | Force-send queued events. |
+| `reset()` | Clear the stored identity, session and frequency caps. |
+
+## Configuration
+
+| Option | Default | |
+| --- | --- | --- |
+| `applicationId` | — | **Required.** |
+| `apiKey` | — | **Required.** |
+| `apiBase` | — | Your CXPinsight gateway URL. |
+| `record` | dashboard | Session replay. Omit to follow the dashboard toggle. |
+| `recordMaskInputs` | `true` | Never persist typed text. |
+| `captureScreen` | — | Screenshot provider; omit for a timeline-only replay. |
+| `captureNetwork` | `true` | Sanitised `api_call` events — method, host, path, status. Never bodies or headers. |
+| `sessionTimeout` | 30 min | Inactivity before a new session starts. |
+| `flushInterval` / `flushThreshold` | 30 s / 10 | Event batching. |
+| `theme` | OS | `'light'` / `'dark'` if your app has its own toggle. |
+| `brandingPalette` | — | Your app's colours, so surveys can match them. |
+| `debug` | `false` | Verbose logging. |
+
+Values omitted here are filled from the application's dashboard settings at startup, so capture behaviour can change without an app release.
+
+## Privacy
+
+- Typed text is never stored in replays when `recordMaskInputs` is on (the default).
+- Network capture records method, host, path, status and duration only. Query strings are stripped; request and response bodies and headers are never read.
+- The SDK's own backend calls are excluded from network capture.
+- Events are queued locally and persist across launches, so nothing is lost offline.
+
+## Requirements
+
+- React Native 0.72+ or Expo SDK 49+
+- `@react-native-async-storage/async-storage` (required peer dependency)
+- Optional: `@react-native-community/datetimepicker` for date questions, `expo-speech` and `expo-speech-recognition` for voice surveys, `react-native-view-shot` for replay screenshots, `expo-constants` and `expo-localization` for richer device metadata
+
+## License
+
+MIT

package/babel.js

@@ -0,0 +1,101 @@
+/**
+ * CXP Babel Plugin — automatically replaces React Native touch component
+ * imports with CXP's instrumented versions at build time.
+ *
+ * Usage in babel.config.js:
+ *
+ *   module.exports = function(api) {
+ *     api.cache(true);
+ *     return {
+ *       presets: ['babel-preset-expo'],
+ *       plugins: ['@cxpinsight/react-native/babel'],
+ *     };
+ *   };
+ *
+ * This transforms:
+ *   import { TouchableOpacity, Pressable, TextInput } from 'react-native';
+ *
+ * Into:
+ *   import { TouchableOpacity } from '@cxpinsight/react-native/instrumented/TouchableOpacity';
+ *
+ * That path is a re-export of the package's own build output (see
+ * scripts/make-shims.js), so the instrumented components an app loads are the
+ * SAME module instance the SDK subscribes to. Pointing it anywhere else — src/,
+ * or a second module format — gives the app one copy and the SDK another, and
+ * taps are then delivered to a listener list nobody is subscribed to.
+ *   import { Pressable } from '@cxpinsight/react-native/instrumented/Pressable';
+ *   import { TextInput } from '@cxpinsight/react-native/instrumented/TextInput';
+ *   // (other imports from 'react-native' are left untouched)
+ */
+
+const INSTRUMENTED_COMPONENTS = {
+  TouchableOpacity: '@cxpinsight/react-native/instrumented/TouchableOpacity',
+  Pressable: '@cxpinsight/react-native/instrumented/Pressable',
+  TextInput: '@cxpinsight/react-native/instrumented/TextInput',
+  ScrollView: '@cxpinsight/react-native/instrumented/ScrollView',
+};
+
+module.exports = function cxpInsightBabelPlugin({ types: t }) {
+  return {
+    name: 'cxpinsight-auto-instrument',
+    visitor: {
+      ImportDeclaration(path, state) {
+        if (path.node.source.value !== 'react-native') return;
+
+        // CRITICAL: Only instrument the app's own source. Never rewrite files inside
+        // node_modules — rewriting react-native's own internals (e.g. VirtualizedList,
+        // which imports ScrollView from 'react-native') creates a circular dependency
+        // that leaves react-native's contexts half-initialized ("Cannot read property
+        // 'Consumer' of undefined"). Also skip the SDK itself, whose instrumented
+        // components must import from the real 'react-native'.
+        const filename = state.filename || state.file?.opts?.filename || '';
+        if (
+          filename.includes('/node_modules/') ||
+          filename.includes('cxpinsight-react-native') ||
+          filename.includes('@cxpinsight/react-native') ||
+          filename.includes('cxpinsight/react-native')
+        ) {
+          return;
+        }
+
+        const specifiersToRedirect = [];
+        const specifiersToKeep = [];
+
+        for (const specifier of path.node.specifiers) {
+          if (
+            t.isImportSpecifier(specifier) &&
+            t.isIdentifier(specifier.imported) &&
+            INSTRUMENTED_COMPONENTS[specifier.imported.name]
+          ) {
+            specifiersToRedirect.push(specifier);
+          } else {
+            specifiersToKeep.push(specifier);
+          }
+        }
+
+        if (specifiersToRedirect.length === 0) return;
+
+        // Create new import declarations for instrumented components
+        const newImports = specifiersToRedirect.map((specifier) => {
+          const componentName = specifier.imported.name;
+          const source = INSTRUMENTED_COMPONENTS[componentName];
+          return t.importDeclaration(
+            [t.importSpecifier(specifier.local, t.identifier(componentName))],
+            t.stringLiteral(source),
+          );
+        });
+
+        if (specifiersToKeep.length > 0) {
+          // Replace original with remaining specifiers + add new imports
+          path.node.specifiers = specifiersToKeep;
+          for (const imp of newImports) {
+            path.insertAfter(imp);
+          }
+        } else {
+          // All specifiers were redirected — replace entire import
+          path.replaceWithMultiple(newImports);
+        }
+      },
+    },
+  };
+};

package/instrumented/Pressable.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+export * from '../lib/instrumented/Pressable';

package/instrumented/Pressable.js

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+module.exports = require('../lib/instrumented/Pressable');

package/instrumented/ScrollView.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+export * from '../lib/instrumented/ScrollView';

package/instrumented/ScrollView.js

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+module.exports = require('../lib/instrumented/ScrollView');

package/instrumented/TextInput.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+export * from '../lib/instrumented/TextInput';

package/instrumented/TextInput.js

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+module.exports = require('../lib/instrumented/TextInput');

package/instrumented/TouchableOpacity.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+export * from '../lib/instrumented/TouchableOpacity';

package/instrumented/TouchableOpacity.js

@@ -0,0 +1,2 @@
+// Generated by scripts/make-shims.js — do not edit.
+module.exports = require('../lib/instrumented/TouchableOpacity');

package/lib/CXPinsight.d.ts

@@ -0,0 +1,113 @@
+import type { CXPinsightConfig, CXPinsightCallbacks, UserIdentity, FunnelStepOptions, ExperimentOptions, ConversionOptions } from './types';
+type SurveyPresenter = (surveyId: string) => void;
+type SetupPresenter = (show: boolean) => void;
+declare class CXPinsightSDK {
+    private initialized;
+    private config;
+    private callbacks;
+    private userId;
+    private userIdentity;
+    private surveyPresenter;
+    private setupPresenter;
+    private autoEventUnsub;
+    private currentScreen;
+    private previousScreen;
+    private engagementStartTs;
+    private engagementAccumMs;
+    private engagementActive;
+    private startEngagementClock;
+    private pauseEngagementClock;
+    private resumeEngagementClock;
+    private getEngagementMs;
+    private static errorHandlerInstalled;
+    /** Initialize the SDK. Call once at app startup. */
+    init(config: CXPinsightConfig, callbacks?: CXPinsightCallbacks): Promise<void>;
+    /**
+     * P1 — merge the server's canonical SdkConfig into `config`, filling only the
+     * flat init() fields the app left undefined (client always wins). Bounded to a
+     * short timeout so a slow network never stalls init; any failure is swallowed
+     * and the app's config/defaults stand. Runs before the capture/session/queue
+     * consumers in init().
+     */
+    private applyServerSdkConfig;
+    /** Roll the recording + engagement clock onto a freshly-started session. */
+    private onSessionRollover;
+    /** Wire native signals → typed analytics events (shared taxonomy). */
+    private startAutoEvents;
+    /** Track a custom event */
+    /**
+     * One-shot reachability check of `apiBase` at init. Logs a precise, actionable
+     * warning for the common misconfigurations (frontend port, a service instead of the
+     * gateway, or localhost on a physical device). Never throws or blocks init.
+     */
+    private verifyConnectivity;
+    track(eventName: string, data?: Record<string, unknown>, eventType?: string, teeToRecording?: boolean): void;
+    /** Track a screen view (triggers remote page_view rules) */
+    trackScreen(screenName: string, data?: Record<string, unknown>): void;
+    /** Identify the current user */
+    identify(user: UserIdentity): Promise<void>;
+    /** Track a funnel step */
+    trackFunnelStep(funnelId: string, stepNumber: number, stepName?: string, options?: FunnelStepOptions): void;
+    /** Track an experiment impression */
+    trackExperiment(experimentId: string, variantId: string, options?: ExperimentOptions): void;
+    /** Track a conversion event */
+    trackConversion(eventName: string, options?: ConversionOptions): void;
+    /** Enter setup mode. Shows the setup code entry UI. */
+    enterSetupMode(): void;
+    /** Exit setup mode and clean up. */
+    exitSetupMode(): Promise<void>;
+    /** Check if setup mode is currently active. */
+    isInSetupMode(): boolean;
+    /** Get the current setup session state. */
+    getSetupState(): import("./setup/SetupController").SetupSessionState | null;
+    /** Get the stable device ID (generates one if first time). */
+    getDeviceId(): Promise<string>;
+    /** Programmatically show a survey */
+    showSurvey(surveyId: string): void;
+    /**
+     * Start mobile session (timeline) recording. Use this when gating on your own
+     * consent UI: show your banner, then call after the user accepts. No-op if
+     * already recording or the SDK isn't initialized.
+     */
+    startRecording(): Promise<void>;
+    /** Stop mobile session recording and flush the final chunk. */
+    stopRecording(): Promise<void>;
+    /** Reset all SDK state (call on logout) */
+    reset(): Promise<void>;
+    /** Manual flush for testing */
+    flush(): Promise<void>;
+    /** @internal Register the survey presenter from CXPinsightProvider */
+    _registerSurveyPresenter(presenter: SurveyPresenter): void;
+    /** @internal Unregister the survey presenter */
+    _unregisterSurveyPresenter(): void;
+    /** @internal Register the setup presenter from CXPinsightProvider */
+    _registerSetupPresenter(presenter: SetupPresenter): void;
+    /** @internal Unregister the setup presenter */
+    _unregisterSetupPresenter(): void;
+    /** @internal Get callbacks */
+    _getCallbacks(): CXPinsightCallbacks;
+    /** @internal Get userId */
+    _getUserId(): string;
+    /** @internal Get the full identity blob (or null if identify() was
+     *  never called). Consumed by the variables resolver so
+     *  {source: 'sdk'} v1.1 variables interpolate to identify()-supplied
+     *  values. Return type kept broad ({[k]:unknown}) because the caller
+     *  looks up variable-name keys against it, not typed properties. */
+    _getUserIdentity(): Record<string, unknown> | null;
+    /** @internal Get config */
+    _getConfig(): CXPinsightConfig | null;
+    /** @internal Host-supplied palette override from CXPinsight.init({ brandingPalette }).
+     *  Read by SurveyModal to layer over survey.branding.palette + defaults.
+     *  Returns null when the app didn't pass one — palette resolver falls back. */
+    _getInitBrandingPalette(): {
+        light?: Record<string, string>;
+        dark?: Record<string, string>;
+    } | null;
+    /** @internal Check initialization */
+    _isInitialized(): boolean;
+    private log;
+}
+/** Singleton SDK instance */
+export declare const CXPinsight: CXPinsightSDK;
+export {};
+//# sourceMappingURL=CXPinsight.d.ts.map

package/lib/CXPinsight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CXPinsight.d.ts","sourceRoot":"","sources":["../src/CXPinsight.ts"],"names":[],"mappings":"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"}