react-native-insider 8.1.0 → 9.0.0

package/src/InsiderEvents.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Parameters attached to a recorded Insider event.
+ *
+ * Sourced from the native SDK — the map is unmodifiable on Android and a defensive copy
+ * on iOS. Treat it as READ-ONLY; do not mutate it.
+ *
+ * Values are normalized for the bridge on both platforms before delivery. In particular a
+ * `Date` nested inside the parameters arrives as epoch **MILLISECONDS** (a number),
+ * following this SDK's epoch-millis convention for dates crossing the bridge. Note the
+ * deliberate contrast with the callback's top-level `timestamp`, which is in SECONDS.
+ * Values of a type the bridge cannot represent degrade to their string description rather
+ * than being dropped.
+ */
+export type InsiderRecordedEventParameters = {
+	readonly [key: string]: any;
+};
+
+/**
+ * Callback invoked for every event recorded by the Insider SDK.
+ *
+ * ⚠️ `timestamp` IS IN **SECONDS**, NOT MILLISECONDS. ⚠️
+ *
+ * @param name - The recorded event name.
+ * @param parameters - Read-only event parameters.
+ * @param timestamp - Whole seconds since the Unix epoch. Convert with
+ *                    `new Date(timestamp * 1000)`.
+ */
+export type InsiderEventRecordedCallback = (
+	name: string,
+	parameters: InsiderRecordedEventParameters,
+	timestamp: number
+) => void;
+
+/** Handle returned by `events.addObserver`; call `remove()` to unsubscribe. */
+export interface InsiderEventSubscription {
+	/**
+	 * Unsubscribes this listener. When the last subscriber is removed the underlying
+	 * native observer is unregistered as well.
+	 */
+	remove(): void;
+}
+
+/**
+ * Main API for subscribing to the Insider SDK's recorded-event stream.
+ *
+ * Mirrors the native SDK namespaces — `[[Insider events] addObserver:]` on iOS,
+ * `Insider.Instance.events().addObserver(...)` on Android — so the wrapper reads
+ * the way the SDK it wraps does.
+ */
+interface InsiderEvents {
+	/**
+	 * Subscribes to every event recorded by the Insider SDK.
+	 *
+	 * ## ⚠️ `timestamp` is in SECONDS, not milliseconds
+	 *
+	 * The `timestamp` argument is passed through from the native SDKs **unchanged**, in
+	 * **whole seconds** since the Unix epoch (this is deliberate — it keeps parity with the
+	 * native Android/iOS SDKs). JavaScript's `Date` constructor and `Date.now()` both use
+	 * **milliseconds**, so you MUST multiply by 1000 before building a `Date`:
+	 *
+	 * ```typescript
+	 * Insider.events.addObserver((name, parameters, timestamp) => {
+	 *   const date = new Date(timestamp * 1000); // ✅ correct — timestamp is in SECONDS
+	 *   // const wrong = new Date(timestamp);    // ❌ WRONG — yields a date in 1970
+	 * });
+	 * ```
+	 *
+	 * ## Threading
+	 *
+	 * The native SDK delivers on a dedicated background thread, so the callback may be
+	 * invoked off the JS main work loop. Keep the callback cheap and non-blocking.
+	 *
+	 * ## Parameters are read-only
+	 *
+	 * `parameters` is unmodifiable on Android / a defensive copy on iOS. Do not mutate it.
+	 *
+	 * ## Unsubscribing
+	 *
+	 * Unlike `insiderIDListener`, this method returns a subscription. Call `remove()` on it
+	 * to unsubscribe — important because this fires on EVERY event. Multiple subscribers are
+	 * supported; the native observer is registered once and torn down only when the last
+	 * subscriber is removed.
+	 *
+	 * @param callback - Invoked as `(name, parameters, timestamp)` for each recorded event.
+	 * @returns A subscription handle, or `undefined` if the SDK is unavailable or the
+	 *          callback failed validation.
+	 */
+	addObserver(callback: InsiderEventRecordedCallback): InsiderEventSubscription | undefined;
+}
+
+declare const InsiderEvents: InsiderEvents;
+
+export default InsiderEvents;

package/src/InsiderEvents.js

@@ -0,0 +1,124 @@
+import { NativeModules } from 'react-native';
+
+import { shouldNotProceed, generateJSONErrorString, checkParameters, showParameterWarningLog } from './Util';
+import eventHandler from './EventHandler';
+
+const Insider = NativeModules.RNInsider;
+
+const INSIDER_EVENT_RECORDED = 'INSIDER_EVENT_RECORDED';
+
+/**
+ * JS-side fan-out registry for the native event-recorded stream.
+ *
+ * NOTE — deliberate deviation from the older `insiderIDListener` API:
+ * `insiderIDListener` returns nothing, so a caller can never unsubscribe and every
+ * extra call stacks another duplicate native + JS listener. That is tolerable for a
+ * rarely-firing ID change, but `events.addObserver` fires on EVERY tagged event,
+ * so leaked/duplicated subscriptions are a real correctness and performance problem.
+ *
+ * Therefore this API registers with the native SDK exactly ONCE (guarded by
+ * `eventRecordedNativeSubscription`) and fans out to N JS subscribers itself. Each
+ * subscriber gets back a `{ remove() }` handle; when the LAST subscriber is removed we
+ * tear the native observer down again. This matters on Android in particular, where the
+ * native SDK holds observers STRONGLY and would otherwise keep the listener (and the
+ * emitter it captures) alive for the lifetime of the process.
+ */
+// Holds one record per SUBSCRIPTION rather than per callback, so that registering the
+// same function twice yields two independent subscriptions (a Set keyed on the function
+// itself would dedupe them, and removing one would silently kill the other).
+const eventRecordedSubscribers = new Set();
+let eventRecordedNativeSubscription = null;
+
+function dispatchEventRecorded(payload) {
+  if (payload === null || payload === undefined) return;
+
+  // Copy first: a subscriber may call remove() from inside its own callback, and
+  // mutating the Set while iterating it would skip the following subscribers.
+  const subscribers = Array.from(eventRecordedSubscribers);
+  subscribers.forEach(subscriber => {
+    try {
+      subscriber.callback(payload.name, payload.parameters || {}, payload.timestamp);
+    } catch (error) {
+      Insider.putErrorLog(generateJSONErrorString(error));
+    }
+  });
+}
+
+function removeEventRecordedSubscriber(subscriber) {
+  try {
+    if (!eventRecordedSubscribers.delete(subscriber)) return;
+    if (eventRecordedSubscribers.size > 0) return;
+
+    if (eventRecordedNativeSubscription !== null) {
+      eventRecordedNativeSubscription.remove();
+      eventRecordedNativeSubscription = null;
+    }
+
+    Insider.unregisterInsiderEventListener();
+  } catch (error) {
+    Insider.putErrorLog(generateJSONErrorString(error));
+  }
+}
+
+const InsiderEvents = Object.freeze({
+  /**
+   * Subscribes to every event recorded by the Insider SDK.
+   *
+   * IMPORTANT: `timestamp` is delivered in WHOLE SECONDS since the Unix epoch —
+   * NOT milliseconds — matching the native SDKs exactly. Use
+   * `new Date(timestamp * 1000)` to build a JS Date.
+   *
+   * Unlike `insiderIDListener`, this returns a subscription; call `remove()` on it to
+   * unsubscribe. The native observer is registered once and torn down when the last
+   * subscriber leaves.
+   *
+   * @param {(name: string, parameters: object, timestamp: number) => void} callback
+   * @returns {{ remove: () => void } | undefined} subscription, or undefined if setup failed
+   */
+  addObserver(callback) {
+    if (shouldNotProceed()) return;
+    if (checkParameters([{ type: 'function', value: callback }])) {
+      showParameterWarningLog("events.addObserver", [{ type: 'function', value: callback }]);
+      return;
+    }
+    const subscriber = { callback: callback };
+    // Tracks whether THIS call is the one performing native registration. Only a failure
+    // during that phase may be rolled back — see the catch below.
+    let isRegisteringNatively = false;
+
+    try {
+      eventRecordedSubscribers.add(subscriber);
+
+      if (eventRecordedNativeSubscription === null) {
+        isRegisteringNatively = true;
+
+        eventRecordedNativeSubscription = eventHandler.addListener(INSIDER_EVENT_RECORDED, dispatchEventRecorded);
+
+        Insider.registerInsiderEventListener();
+      }
+
+      return {
+        remove: () => removeEventRecordedSubscriber(subscriber)
+      };
+    } catch (error) {
+      Insider.putErrorLog(generateJSONErrorString(error));
+
+      // Roll the failed subscribe back so a later call can retry. Without this the
+      // half-built state (non-null `eventRecordedNativeSubscription` + a registered
+      // subscriber) would permanently satisfy the guard above, and events would never
+      // arrive with nothing left to re-trigger registration.
+      eventRecordedSubscribers.delete(subscriber);
+
+      // ONLY undo the native side when this call is the one that was registering it.
+      // If registration already succeeded earlier, a throw here came from somewhere else
+      // on a live stream — tearing down and letting a later subscribe re-register would
+      // stack a SECOND native observer and double-deliver every event.
+      if (isRegisteringNatively && eventRecordedNativeSubscription !== null) {
+        eventRecordedNativeSubscription.remove();
+        eventRecordedNativeSubscription = null;
+      }
+    }
+  },
+});
+
+export default InsiderEvents;

package/src/InsiderIdentifier.js

@@ -7,10 +7,10 @@ const Insider = NativeModules.RNInsider;
 const ADD_EMAIL = 'addEmail';
 const ADD_PHONE_NUMBER = 'addPhoneNumber';
 const ADD_USER_ID = 'addUserID';
-const ADD_CUSTOM_IDENTIFIER = 'addCustomIdentifier';
 
 export default class RNInsiderIdentifier {
   identifiers = {};
+  // Stryker disable next-line BlockStatement: the field initializer above already sets identifiers to {}
   constructor() {
     this.identifiers = {};
   }

package/src/InsiderUser.d.ts

@@ -17,10 +17,11 @@ declare class RNInsiderUser {
   setPushOptin(value: boolean): this;
   setLocationOptin(value: boolean): this;
   setWhatsappOptin(value: boolean): this;
+  setPromotionalOptin(value: boolean): this;
 
-  login(identifiers: RNInsiderIdentifier, insiderIDResult?: (insiderID: string) => void): this;
+  login(identifiers: RNInsiderIdentifier, insiderIDResult?: (insiderID: string | null) => void): this;
   logout(): this;
-  logoutResettingInsiderID(identifiers?: RNInsiderIdentifier[] | null, insiderIDResult?: (insiderID: string) => void): this;
+  logoutResettingInsiderID(identifiers?: RNInsiderIdentifier[] | null, insiderIDResult?: (insiderID: string | null) => void): this;
 
   setCustomAttributeWithString(key: string, value: string): this;
   setCustomAttributeWithInt(key: string, value: number): this;

package/src/InsiderUser.js

@@ -229,10 +229,30 @@ export default class RNInsiderUser {
         return this;
     }
 
+    setPromotionalOptin(value) {
+        if (shouldNotProceed()) return this;
+        if (checkParameters([{ type: 'boolean', value }])) {
+            showParameterWarningLog("setPromotionalOptin", [{ type: 'boolean', value }]);
+            return this;
+        }
+        try {
+            Insider.setPromotionalOptin(value);
+        } catch (error) {
+            Insider.putErrorLog(generateJSONErrorString(error));
+        }
+        return this;
+    }
+
     login(identifiers, insiderIDResult) {
         if (shouldNotProceed()) { return this; }
         try {
             if (insiderIDResult !== null && insiderIDResult !== undefined) {
+                if (checkParameters([{ type: 'function', value: insiderIDResult }])) {
+                    showParameterWarningLog("login", [{ type: 'function', value: insiderIDResult }]);
+
+                    return this;
+                }
+
                 Insider.loginWithReturningID(identifiers.identifiers, insiderIDResult);
 
                 return;
@@ -258,6 +278,13 @@ export default class RNInsiderUser {
     logoutResettingInsiderID(identifiers, insiderIDResult) {
         if (shouldNotProceed()) { return this; }
         try {
+            if (insiderIDResult !== null && insiderIDResult !== undefined
+                && checkParameters([{ type: 'function', value: insiderIDResult }])) {
+                showParameterWarningLog("logoutResettingInsiderID", [{ type: 'function', value: insiderIDResult }]);
+
+                return this;
+            }
+
             const identifiersArray = (identifiers && Array.isArray(identifiers))
                 ? identifiers.map(id => id.identifiers)
                 : null;

package/src/Util.js

@@ -13,6 +13,7 @@ export function generateJSONErrorString(error) {
 export function checkParameters(parameters) {
   return parameters.some(param =>
     param.value === null ||
+    // Stryker disable next-line ConditionalExpression: typeof undefined never equals a declared type, so the type check below already rejects it
     param.value === undefined ||
     param.type !== typeof param.value
   );
@@ -25,7 +26,7 @@ export function showParameterWarningLog(functionName, parameters = []) {
   }
 
   const invalidParams = parameters
-    .filter(param => param.value === null || param.value === undefined || param.type !== typeof param.value)
+    .filter(param => checkParameters([param]))
     .map(param => `Expected ${param.type} but got ${typeof param.value} (${param.value})`);
 
   console.warn(

package/src/specs/InsiderAppFrameNativeComponent.ts

@@ -0,0 +1,54 @@
+import type {HostComponent, ViewProps} from 'react-native';
+import type {
+  DirectEventHandler,
+  Double,
+  Int32,
+} from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+export type InsiderAppFrameDismissEvent = Readonly<{
+  placementId: string;
+}>;
+
+export type InsiderAppFrameStatusEvent = Readonly<{
+  placementId: string;
+  status: string;
+  previousStatus: string;
+}>;
+
+export type InsiderAppFrameErrorEvent = Readonly<{
+  placementId: string;
+  code: string;
+  /** Always the canonical text for `code`; the originating error travels in `cause`. */
+  message: string;
+  /**
+   * The originating platform error's message, or an empty string — codegen event payloads
+   * are non-nullable.
+   */
+  cause: string;
+  dismissCode: Int32;
+}>;
+
+export type InsiderAppFrameHeightEvent = Readonly<{
+  placementId: string;
+  height: Double;
+}>;
+
+export type InsiderAppFrameActionEvent = Readonly<{
+  placementId: string;
+  data: string;
+}>;
+
+export interface NativeProps extends ViewProps {
+  placementId?: string;
+
+  onStatusChange?: DirectEventHandler<InsiderAppFrameStatusEvent>;
+  onLoadError?: DirectEventHandler<InsiderAppFrameErrorEvent>;
+  onHeightChange?: DirectEventHandler<InsiderAppFrameHeightEvent>;
+  onDismissRequest?: DirectEventHandler<InsiderAppFrameDismissEvent>;
+  onAction?: DirectEventHandler<InsiderAppFrameActionEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'InsiderAppFrameView',
+) as HostComponent<NativeProps>;

package/.orbit-output/config/MASTER.md

@@ -1,129 +0,0 @@
-# MASTER.md — Single Source of Truth
-
-> react-native-insider v8.0.3 | Generated by Orbit Init | 2026-04-16 (synced 2026-06-29)
-
----
-
-## Project Overview
-
-React Native bridge SDK (`react-native-insider`) wrapping native Insider iOS/Android SDKs via NativeModules. Published to npm as a library — not an application. v8.0.0 introduces the **App Cards** module and **identifier-scoped Message Center**.
-
-## Technology Stack
-
-| Layer | Technology | Version |
-|-------|-----------|---------|
-| JS Bridge | JavaScript (ES6+, ES private fields) | — |
-| Type Declarations | TypeScript (.d.ts) | — |
-| iOS Native | Objective-C | — |
-| Android Native | Java | — |
-| Framework | React Native | 0.83.0 |
-| React | React | 19.2.0 |
-| iOS SDK | InsiderMobile | 15.1.0 |
-| iOS Geofence | InsiderGeofence | 1.2.4 |
-| iOS Hybrid | InsiderHybrid | 1.7.6 |
-| Android SDK | com.useinsider:insider | 16.0.7 |
-| Android Hybrid | com.useinsider:insiderhybrid | 1.3.4 |
-| Testing | Jest | 29.7.0 |
-| Build | Babel + @react-native/babel-preset | 0.83.0 |
-| Android Build | Android Gradle Plugin | 8.4.2 |
-| CI/CD | GitHub Actions | 3 workflows |
-
-## Project Structure
-
-```
-./
-├── index.js / index.d.ts          # Main entry point (re-exports AppCardsError)
-├── src/                            # JS modules
-│   ├── InsiderUser/Product/Event/Identifier (fluent builders)
-│   ├── InsiderAppCards / InsiderAppCard / InsiderAppCardsError  (App Cards)
-│   ├── Util.js                     # validation + resolveWithCallback
-│   ├── *Enum* (Gender, CallbackType, ContentOptimizerDataType, CloseButtonPosition)
-│   └── __tests__/                  # per-module tests
-├── ios/RNInsider/                  # Objective-C bridge
-├── android/src/main/java/          # Java bridge
-├── __tests__/ + __mocks__/         # Jest tests
-├── docs/                           # internal feature specs
-├── example/                        # Demo React Native app
-├── .github/workflows/              # CI/CD
-├── .orbit-output/                  # Orbit architecture docs (below)
-└── devops/                         # Release scripts
-```
-
-## .orbit Structure
-
-```
-.orbit-output/
-├── config/
-│   ├── MASTER.md                          # THIS FILE — single source of truth
-│   └── architecture/
-│       ├── ARCHITECTURE.md                # Architecture overview + diagrams
-│       ├── CODE-CATALOG.md                # All classes, functions, modules
-│       ├── API_DOCS.md                    # Bridge API reference
-│       └── project.yaml                   # Machine-readable config
-```
-
-**When to read:**
-- New to project → ARCHITECTURE.md
-- Looking for a class/function → CODE-CATALOG.md
-- Understanding bridge API → API_DOCS.md
-- Quick reference → this file (MASTER.md)
-
-## Code Patterns
-
-### Naming
-- Classes: `PascalCase` (RNInsider, RNInsiderProduct, InsiderAppCard)
-- Methods: `camelCase` (tagEvent, getCurrentUser, markAsRead)
-- Constants: `UPPER_SNAKE_CASE` (NOTIFICATION_OPEN, INVALID_PARAMETER)
-- Product field keys: `snake_case` strings (product_id, sale_price)
-- Private fields: `#field` (App Card domain models)
-
-### Architecture Pattern
-- **Static facade** (RNInsider) + **fluent builders** (Product, Event, User, Identifier) + **frozen singleton** (AppCards)
-- Every public method: `shouldNotProceed()` → `checkParameters()` → try/catch → `putErrorLog()`
-- Products serialized as 3 bridge args: requiredFields, optionalFields, customParameters
-- Dates as epoch-millis strings (bridge int64 limitation)
-- Callback events indexed by array position matching InsiderCallbackType enum
-- App Cards: Promise + completion-callback duality via `Util.resolveWithCallback`
-- Polymorphic action types via `InsiderAppCardAction.fromData()` factory
-- Polymorphic 2nd arg in `itemRemovedFromCart` and `visitCartPage` (saleID OR customParameters)
-
-### Testing
-- Jest with react-native preset
-- Global mock in `__mocks__/react-native.js`
-- Test pattern: `describe('Class.method') → it('should ...')`
-- Per-module suites under `src/__tests__/` plus top-level `__tests__/`
-
-## Common Commands
-
-| Command | Purpose |
-|---------|---------|
-| `npm test` | Run all Jest tests |
-| `npx jest __tests__/Util.test.js` | Run single test file |
-| `npm install` | Install dependencies |
-| `npm pack` | Pack for local testing |
-| `cd example && npm install` | Install example app deps |
-| `cd example/ios && pod install` | Install iOS pods for example |
-
-## Key Entry Points
-
-| File | Role |
-|------|------|
-| `index.js` | Main SDK entry — RNInsider static class |
-| `src/InsiderAppCards.js` | App Cards module (Promise + callback API) |
-| `ios/RNInsider/RNInsider.m` | iOS bridge module |
-| `android/.../RNInsiderModule.java` | Android bridge module |
-| `example/App.tsx` | Example app entry |
-
-## Version Management
-
-- Source of truth: `package.json` → version (currently 8.0.3)
-- iOS: `RNInsider.podspec` reads from package.json
-- Android: `build.gradle` has pinned native SDK versions (insider:16.0.7)
-- SDK string: `'RN-' + version` (e.g., RN-8.0.3)
-- Release: `release/X.Y.Z` branch → master merge → npm publish
-- Dual-track: main + `-nh` (non-Huawei) variant
-- PR titles must contain `MOB-[0-9]+`
-
----
-
-*Auto-generated by Orbit Init v3.11 | 2026-04-16 (synced 2026-06-12)*