react-native-insider 8.0.1 → 8.0.2

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

@@ -0,0 +1,129 @@
+# MASTER.md — Single Source of Truth
+
+> react-native-insider | Generated by Orbit Init | 2026-04-16
+
+---
+
+## 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.0.0 |
+| iOS Geofence | InsiderGeofence | 1.2.4 |
+| iOS Hybrid | InsiderHybrid | 1.7.6 |
+| Android SDK | com.useinsider:insider | 16.0.1 |
+| 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.0)
+- iOS: `RNInsider.podspec` reads from package.json
+- Android: `build.gradle` has pinned native SDK versions (insider:16.0.1)
+- SDK string: `'RN-' + version` (e.g., RN-8.0.0)
+- 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*

package/.orbit-output/config/architecture/API_DOCS.md

@@ -0,0 +1,342 @@
+# API_DOCS.md
+
+> Generated by Orbit Init | 2026-04-16 | react-native-insider v8.0.0
+
+## Overview
+
+This SDK exposes a **React Native NativeModules bridge** — not HTTP endpoints. The JS layer (`RNInsider`) wraps native method calls that communicate with the Insider platform's native iOS/Android SDKs.
+
+---
+
+## Bridge Architecture
+
+```
+┌─────────────────────────┐
+│   Consumer App (JS/TS)  │
+│   import Insider from   │
+│   'react-native-insider'│
+└──────────┬──────────────┘
+           │ NativeModules.RNInsider
+           ▼
+┌─────────────────────────┐
+│   index.js (RNInsider)  │
+│   Static facade class   │
+│   Parameter validation   │
+│   Product serialization  │
+│   AppCards getter        │
+└──────────┬──────────────┘
+           │ RN Bridge
+     ┌─────┴─────┐
+     ▼           ▼
+┌──────────┐ ┌──────────┐
+│ iOS      │ │ Android  │
+│ RNInsider│ │ RNInsider│
+│ .m       │ │ Module   │
+│          │ │ .java    │
+└────┬─────┘ └────┬─────┘
+     │            │
+     ▼            ▼
+┌──────────┐ ┌──────────┐
+│ Insider  │ │ Insider  │
+│ Mobile   │ │ SDK      │
+│ 15.0.0   │ │ 16.0.1   │
+└──────────┘ └──────────┘
+```
+
+**Event Flow (native → JS):**
+```
+Native SDK event → RNNotificationHandler (iOS) / RCTDeviceEventEmitter (Android)
+                 → NativeEventEmitter listener in JS
+                 → insiderCallback(typeIndex, data)
+```
+
+---
+
+## RNInsider — Static API Methods
+
+### Static Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `closeButtonPosition` | `CloseButtonPosition` | Enum re-exported for `setInternalBrowserCloseButtonPosition` |
+| `AppCardsError` | `typeof InsiderAppCardsError` | Typed error class for App Cards operations |
+| `AppCardsErrorCode` | `typeof InsiderAppCardsErrorCode` | Error-code enum for App Cards |
+| `appCards` | `RNInsiderAppCards` (getter) | Singleton App Cards module |
+
+### Initialization
+
+| Method | Parameters | Returns | Platform | Description |
+|--------|-----------|---------|----------|-------------|
+| `init` | `partnerName: string, appGroup: string, callback: (type, data) => void` | `void` | Both | Initialize SDK. Registers event listeners before native init. iOS uses appGroup, Android ignores it |
+| `initWithCustomEndpoint` | `partnerName: string, appGroup: string, endpoint: string, callback: (type, data) => void` | `void` | Both | Init with custom API endpoint. iOS: single native call. Android: init() + setCustomEndpoint() |
+| `reinitWithPartnerName` | `partnerName: string` | `void` | Both | Re-initialize with different partner |
+
+### User Management
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getCurrentUser()` | — | `RNInsiderUser` | Returns singleton user instance |
+
+### Event Tracking
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `tagEvent` | `name: string` | `RNInsiderEvent` | Creates event builder. Call `.build()` to dispatch |
+
+### Product & E-commerce
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `createNewProduct` | `productID, name, taxonomy[], imageURL, price, currency` | `RNInsiderProduct` | Creates product builder |
+| `itemPurchased` | `uniqueSaleID: string, product: RNInsiderProduct, customParameters?: CustomParameters` | `void` | Track purchase. Serializes product as 3 args |
+| `itemAddedToCart` | `product: RNInsiderProduct, customParameters?: CustomParameters` | `void` | Track add-to-cart |
+| `itemRemovedFromCart` | `productID: string, saleIDOrCustomParameters?: string \| CustomParameters, customParameters?: CustomParameters` | `void` | Polymorphic 2nd arg: a string is treated as saleID; a plain object is treated as customParameters |
+| `cartCleared` | `customParameters?: CustomParameters` | `void` | Track cart clear |
+| `itemAddedToWishlist` | `product: RNInsiderProduct, customParameters?: CustomParameters` | `void` | Track wishlist add |
+| `itemRemovedFromWishlist` | `productID: string, customParameters?: CustomParameters` | `void` | Track wishlist removal |
+| `wishlistCleared` | `customParameters?: CustomParameters` | `void` | Track wishlist clear |
+
+### Page Visit Tracking
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `visitHomePage` | `customParameters?: CustomParameters` | Track home page visit |
+| `visitListingPage` | `taxonomy: string[], customParameters?: CustomParameters` | Track listing/category page |
+| `visitProductDetailPage` | `product: RNInsiderProduct, customParameters?: CustomParameters` | Track PDP visit |
+| `visitCartPage` | `products: RNInsiderProduct[], saleIDOrCustomParameters?: string \| CustomParameters, customParameters?: CustomParameters` | Polymorphic 2nd arg (saleID or customParameters). Maps products through 3-part serialization |
+| `visitWishlistPage` | `products: RNInsiderProduct[], customParameters?: CustomParameters` | Track wishlist page |
+
+### Smart Recommendations
+
+| Method | Parameters | Returns |
+|--------|-----------|---------|
+| `getSmartRecommendation` | `recommendationID: number, locale: string, currency: string, callback: (data) => void` | `void` |
+| `getSmartRecommendationWithProduct` | `product: RNInsiderProduct, recommendationID: number, locale: string, callback: (data) => void` | `void` |
+| `getSmartRecommendationWithProductIDs` | `productIDs: string[], recommendationID: number, locale: string, currency: string, callback: (data) => void` | `void` |
+| `clickSmartRecommendationProduct` | `recommendationID: number, product: RNInsiderProduct` | `void` |
+
+### Content Optimizer
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `getContentStringWithName` | `variableName, defaultValue: string, dataType: number, callback` | Get string content |
+| `getContentBoolWithName` | `variableName, defaultValue: boolean, dataType: number, callback` | Get boolean content |
+| `getContentIntWithName` | `variableName, defaultValue: number, dataType: number, callback` | Get integer content |
+| `getContentStringWithoutCache` | Same as above | String without cache |
+| `getContentBoolWithoutCache` | Same as above | Boolean without cache |
+| `getContentIntWithoutCache` | Same as above | Integer without cache |
+
+### Message Center
+
+| Method | Parameters | Notes |
+|--------|-----------|-------|
+| `getMessageCenterData` | `limit: number, startDate: Date, endDate: Date, callback` | Dates passed as epoch-millis strings. iOS wraps response in `{data: [...]}`, JS unwraps |
+| `getMessageCenterDataWithIdentifiers` | `limit: number, startDate: Date, endDate: Date, identifiers: RNInsiderIdentifier, callback` | NEW. Identifier-scoped variant. Passes `identifiers.identifiers` flat dict to native; callback receives raw response |
+
+### Push Notifications
+
+| Method | Parameters | Platform | Description |
+|--------|-----------|----------|-------------|
+| `registerWithQuietPermission` | `enabled: boolean` | iOS only | Enable quiet push permission |
+| `setForegroundPushCallback` | `callback: (notification) => void` | Both | Register foreground push listener (separate from init callback) |
+| `setActiveForegroundPushView` | — | Both | Enable active foreground push view |
+| `setHybridPushToken` | `token: string` | Android only | Set FCM/HMS token |
+| `handleNotification` | `notification: object` | Both | Manual notification handling |
+| `handleUniversalLink` | `url: string` | Android only | Handle deep link URLs |
+
+### In-App Messages
+
+| Method | Description |
+|--------|-------------|
+| `removeInapp()` | Remove current in-app message |
+| `disableInAppMessages()` | Disable in-app messages |
+| `enableInAppMessages()` | Enable in-app messages |
+
+### iOS Templates
+
+| Method | Platform | Description |
+|--------|----------|-------------|
+| `disableTemplatesForIOS()` | iOS only | Disable in-app message templates |
+| `reenableTemplatesForIOS()` | iOS only | Re-enable templates |
+
+### Geofencing
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `startTrackingGeofence` | — | Start geofence monitoring |
+| `setAllowsBackgroundLocationUpdates` | `enabled: boolean` | iOS: enable background location. Android: no-op |
+
+### GDPR & Privacy
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `setGDPRConsent` | `consent: boolean` | Set GDPR consent status |
+| `setMobileAppAccess` | `access: boolean` | Set mobile app access |
+| `enableLocationCollection` | `status: boolean` | Enable/disable location |
+| `enableIpCollection` | `status: boolean` | Enable/disable IP collection |
+| `enableCarrierCollection` | `status: boolean` | Enable/disable carrier info |
+| `enableIDFACollection` | `enabled: boolean` | iOS: IDFA collection. Android: no-op |
+
+### Identity
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getInsiderID()` | `Promise<string>` | Get current Insider ID |
+| `insiderIDListener` | `callback: (insiderID) => void` | Listen for Insider ID changes |
+
+### Miscellaneous
+
+| Method | Description |
+|--------|-------------|
+| `showNativeAppReview()` | Show native app review dialog |
+| `signUpConfirmation(customParameters?)` | Confirm sign-up event |
+| `setInternalBrowserCloseButtonPosition(position)` | Android only. Values: LEFT, RIGHT, NONE |
+| `handleURL(url)` | iOS only. Handle deep link URLs from Insider QR codes |
+
+---
+
+## RNInsiderAppCards (NEW)
+
+Accessed via `Insider.appCards`. Frozen singleton. Every async method accepts an optional `completion(error, value)` callback **or** returns a Promise.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getCampaigns(completion?)` | `() => Promise<InsiderAppCardsCampaignResponse>` | Fetch all app cards. On native error, rejects with `InsiderAppCardsError` (parsed from `{code, message}` or string) |
+| `markAsRead(appCardIds, completion?)` | `(string[]) => Promise<void>` | Mark cards as read. Validates non-empty string-array; rejects with `INVALID_PARAMETER` otherwise |
+| `markAsUnread(appCardIds, completion?)` | `(string[]) => Promise<void>` | Mark cards as unread. Same validation as `markAsRead` |
+| `delete(appCardIds, completion?)` | `(string[]) => Promise<void>` | Delete cards by id. Same validation |
+| `view(appCard)` | `(InsiderAppCard) => void` | Record a view event. Throws `InsiderAppCardsError(INVALID_PARAMETER)` if not an `InsiderAppCard` |
+| `click(appCard)` | `(InsiderAppCard) => void` | Record a click. Same instance check |
+| `clickButton(button)` | `(InsiderAppCardButton) => void` | Record button click. Throws if not an `InsiderAppCardButton` |
+
+### Native Bridge Methods Backing App Cards
+
+iOS / Android exports:
+- `getAppCardsCampaigns(callback)`
+- `markAppCardsAsRead(ids, callback)` / `markAppCardsAsUnread(ids, callback)`
+- `deleteAppCards(ids, callback)`
+- `viewAppCard(data)` / `clickAppCard(data)` / `clickAppCardButton(appCardId, data)`
+
+### Domain Models
+
+| Class | Public Surface |
+|-------|----------------|
+| `InsiderAppCard` | `id`, `type`, `isRead`, `images: InsiderAppCardImage[]`, `content: InsiderAppCardContent`, `buttons: InsiderAppCardButton[]`, `action: InsiderAppCardAction`, raw `data` (deep-cloned), `markAsRead/Unread/delete/view/click` |
+| `InsiderAppCardButton` | `id`, `appCardId`, `text`, `action`, raw `data`, `click()` |
+| `InsiderAppCardContent` | `title`, `description` |
+| `InsiderAppCardImage` | `url` |
+| `InsiderAppCardAction` (base) | `type`. Static `fromData(data)` factory dispatches on `data.type` |
+| `InsiderAppCardDeeplinkAction` | `url` (preferring url_scheme → internal_browser_url → external_browser_url), `deeplinkType`, `json` (parsed), `keysAndValues` |
+| `InsiderAppCardFeedbackAction` | type marker |
+| `InsiderAppCardOpenSettingsAction` | type marker |
+| `InsiderAppCardsCampaignResponse` | `appCards: InsiderAppCard[]` (mapped from `items`) |
+
+### Error Type
+
+```typescript
+class InsiderAppCardsError extends Error {
+  readonly code: InsiderAppCardsErrorCodeType;
+  static from(error: { code: string; message: string } | string | unknown): InsiderAppCardsError;
+}
+```
+
+`InsiderAppCardsErrorCode` values: `UNKNOWN`, `SDK_NOT_INITIALIZED`, `INVALID_PARAMETER`, `NETWORK_ERROR`, `SERVER_ERROR`, `PARSE_ERROR`.
+
+---
+
+## RNInsiderUser — Fluent Builder
+
+All methods return `this` for chaining. Singleton instance from `getCurrentUser()`.
+
+### Demographics
+`setName(s)`, `setSurname(s)`, `setAge(n)`, `setGender(InsiderGender)`, `setBirthday(Date)`, `setEmail(s)`, `setPhoneNumber(s)`, `setLanguage(s)`, `setLocale(s)`, `setFacebookID(s)`, `setTwitterID(s)`
+
+### Marketing Optins
+`setEmailOptin(b)`, `setSMSOptin(b)`, `setPushOptin(b)`, `setWhatsappOptin(b)`, `setLocationOptin(b)`
+
+### Custom Attributes
+`setCustomAttributeWithString(key, value)`, `setCustomAttributeWithInt(key, value)`, `setCustomAttributeWithDouble(key, value)`, `setCustomAttributeWithBoolean(key, value)`, `setCustomAttributeWithDate(key, date)`, `setCustomAttributeWithArray(key, array)`
+`unsetCustomAttribute(key)`
+
+### Identity
+- `login(identifiers: InsiderIdentifier, callback?)` — Login with identifiers, optional callback receives Insider ID via `loginWithReturningID`
+- `logout()` — Logout current user
+- `logoutResettingInsiderID(identifiers, insiderIDResult)` — NEW. Logs out and resets Insider ID. `identifiers` is an array of `InsiderIdentifier` instances; `insiderIDResult` callback receives the new ID
+
+---
+
+## RNInsiderProduct — Fluent Builder
+
+Created via `Insider.createNewProduct(productID, name, taxonomy, imageURL, price, currency)`.
+
+### Required Fields (set in constructor)
+`product_id`, `name`, `taxonomy`, `image_url`, `price`, `currency`
+
+### Optional Setters
+`setColor(s)`, `setSize(s)`, `setBrand(s)`, `setSku(s)`, `setGender(s)`, `setDescription(s)`, `setGroupCode(s)`, `setMultipack(s)`, `setProductType(s)`, `setGtin(s)`, `setVoucherName(s)`, `setPromotionName(s)`, `setProductURL(s)`, `setSalePrice(n)`, `setShippingCost(n)`, `setVoucherDiscount(n)`, `setPromotionDiscount(n)`, `setStock(n)`, `setQuantity(n)`, `setTags(string[])`, `setInStock(boolean)`
+
+### Custom Attributes
+`setCustomAttributeWithString(key, value)`, `setCustomAttributeWithInt(key, value)`, `setCustomAttributeWithDouble(key, value)`, `setCustomAttributeWithBoolean(key, value)`, `setCustomAttributeWithDate(key, date)`, `setCustomAttributeWithArray(key, array)`, `setCustomAttributeWithStringArray(key, array)`, `setCustomAttributeWithNumericArray(key, array)`
+
+### Serialization
+Product is passed to native as **3 separate bridge arguments**: `requiredFields` (object), `optionalFields` (object), `customParameters` (typed array).
+
+---
+
+## RNInsiderEvent — Fluent Builder
+
+Created via `Insider.tagEvent(name)`. Call `.build()` to dispatch.
+
+### Parameter Setters
+`addParameterWithString(key, value)`, `addParameterWithInt(key, value)`, `addParameterWithDouble(key, value)`, `addParameterWithBoolean(key, value)`, `addParameterWithDate(key, date)`, `addParameterWithArray(key, array)`, `addParameterWithStringArray(key, array)`, `addParameterWithNumericArray(key, array)`
+
+### Terminal
+`build()` — Sends event name + typed parameters array to native SDK
+
+---
+
+## RNInsiderIdentifier — Builder
+
+Created with `new InsiderIdentifier()`.
+
+### Methods
+`addEmail(email)`, `addPhoneNumber(phone)`, `addUserID(userID)`, `addCustomIdentifier(key, value)`
+
+### Serialization
+Passed to native as `identifiers.identifiers` (a flat key-value object).
+
+---
+
+## CustomParameters Type
+
+```typescript
+type CustomParameters = {
+  [key: string]: string | number | boolean | Date | number[] | string[];
+};
+```
+
+Processed by `parseObjectWithTypes()` which auto-detects types and converts to typed array `[{key, type, value}]` for native bridge. Dates converted to epoch millis. Unknown types silently filtered.
+
+---
+
+## Promise/Callback Bridging Pattern
+
+App Cards methods use the `resolveWithCallback(promise, completion)` helper from `src/Util.js`. If a `completion` function is provided, it's invoked as `completion(error, value)`; otherwise the underlying Promise is returned. This enables `await` syntax and Node-style callbacks from the same method signature.
+
+---
+
+## Native Event Types (Callback)
+
+| Index | Constant | Description |
+|-------|----------|-------------|
+| 0 | `NOTIFICATION_OPEN` | Push notification opened |
+| 1 | `INAPP_BUTTON_CLICK` | In-app message button clicked |
+| 2 | `TEMP_STORE_PURCHASE` | Temporary store purchase |
+| 3 | `TEMP_STORE_ADDED_TO_CART` | Temporary store add-to-cart |
+| 4 | `TEMP_STORE_CUSTOM_ACTION` | Temporary store custom action |
+| 5 | `INAPP_SEEN` | In-app message displayed |
+| 6 | `SESSION_STARTED` | New session started |
+
+Additional listeners (registered separately):
+- `FOREGROUND_PUSH` — via `setForegroundPushCallback()`
+- `INSIDER_ID_LISTENER` — via `insiderIDListener()`

package/.orbit-output/config/architecture/ARCHITECTURE.md

@@ -0,0 +1,209 @@
+# ARCHITECTURE.md
+
+> Generated by Orbit Init | 2026-04-16 | react-native-insider v8.0.0
+
+## Project Summary
+
+| Property | Value |
+|----------|-------|
+| Name | react-native-insider |
+| Version | 8.0.0 |
+| Type | React Native Bridge SDK (npm library) |
+| Architecture | Single service (one npm package) |
+| Main Languages | JavaScript, TypeScript (declarations), Objective-C (iOS), Java (Android) |
+| Frameworks | React Native 0.83.0, React 19.2.0 |
+| Native SDKs | InsiderMobile 15.0.0 (iOS), Insider 16.0.1 (Android) |
+| Testing | Jest 29.7.0 (react-native preset) |
+| CI/CD | GitHub Actions (3 workflows) |
+| Publish | npm registry (dual-track: main + -nh variant) |
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Consumer App                           │
+│              import Insider from                          │
+│              'react-native-insider'                       │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+┌──────────────────────▼───────────────────────────────────┐
+│                 JS Bridge Layer                            │
+│                                                           │
+│  index.js ─── RNInsider (static facade)                  │
+│                 │  + appCards getter                      │
+│                 │  + AppCardsError / AppCardsErrorCode    │
+│                                                           │
+│  src/ ─── InsiderUser (fluent builder, singleton)        │
+│       ├── InsiderProduct (fluent builder, per-instance)   │
+│       ├── InsiderEvent (fluent builder, per-instance)     │
+│       ├── InsiderIdentifier (builder, per-instance)       │
+│       ├── InsiderAppCards (frozen singleton, Promise+cb)  │
+│       │     └── InsiderAppCard / Button / Action models   │
+│       │     └── InsiderAppCardsError (typed Error)        │
+│       ├── Util.js (validation, type detect, resolveWithCb)│
+│       └── Enums (Gender, CallbackType, ContentOptimizer,  │
+│                  CloseButtonPosition,                     │
+│                  InsiderAppCardsErrorCode)                │
+│                                                           │
+│  TypeScript: index.d.ts + src/*.d.ts                     │
+└──────────────────────┬───────────────────────────────────┘
+                       │ NativeModules Bridge
+              ┌────────┴────────┐
+              ▼                 ▼
+┌─────────────────┐  ┌─────────────────────┐
+│    iOS Native    │  │   Android Native    │
+│                  │  │                     │
+│ RNInsider.m      │  │ RNInsiderModule.java│
+│ RNNotification   │  │ RNInsiderPackage    │
+│  Handler.m       │  │  .java              │
+│ RNUtils.m        │  │ RNUtils.java        │
+│                  │  │                     │
+│ InsiderMobile    │  │ insider:16.0.1      │
+│  15.0.0          │  │ insiderhybrid:1.3.4 │
+│ InsiderGeofence  │  │ firebase-messaging  │
+│  1.2.4           │  │ play-services       │
+│ InsiderHybrid    │  │ huawei-hms          │
+│  1.7.6           │  │                     │
+└─────────────────┘  └─────────────────────┘
+```
+
+---
+
+## Key Architectural Patterns
+
+### 1. Static Facade + Builder Pattern
+- `RNInsider` is an all-static class — no JS-side state, all state lives in native singletons
+- Products, Events, Identifiers are builder instances that accumulate state then serialize for the bridge
+- User is a singleton builder returned by `getCurrentUser()`
+- App Cards is a frozen singleton object (`Object.freeze`) accessed via `Insider.appCards` getter
+
+### 2. Three-Part Product Serialization
+Products cross the bridge as **3 separate arguments** (not a single object):
+- `requiredFields` — fixed dict with product_id, name, taxonomy, image_url, price, currency
+- `optionalFields` — accumulated dict from setter methods
+- `customParameters` — typed array `[{type, key, value}]` preserving JS type distinctions
+
+### 3. Index-Based Callback Mapping
+SDK callbacks use array-position-based type discrimination:
+- `callbackActions` array order matches `InsiderCallbackType` enum values (0-6)
+- `forEach` index naturally produces the numeric type identifier
+- Consumer checks `type === InsiderCallbackType.NOTIFICATION_OPEN` etc.
+
+### 4. Epoch-Millis-as-String Date Handling
+All dates converted to `date.getTime().toString()` before crossing the bridge because React Native's bridge doesn't support 64-bit integers. Native side parses long from string.
+
+### 5. Uniform Parameter Validation
+Every public method follows: `shouldNotProceed()` → `checkParameters()` → `showParameterWarningLog()` → try/catch with `putErrorLog()`. Returns safe defaults on failure (empty builders, early return).
+
+### 6. Platform-Aware Initialization
+- iOS: `initWithLaunchOptions(null, partnerName, appGroup, sdkVersion)`
+- Android: `init(partnerName, sdkVersion)` (no appGroup)
+- Event listeners registered BEFORE native init to prevent race conditions
+
+### 7. Promise + Callback Hybrid (App Cards)
+- App Cards methods use `Util.resolveWithCallback(promise, completion)`:
+  - With completion → Node-style `(err, value)` callback
+  - Without completion → returns a Promise (await-friendly)
+- Errors are wrapped via `InsiderAppCardsError.from()`, normalizing `{code, message}` objects or plain strings into typed errors
+
+### 8. Polymorphic Action Dispatch (App Cards)
+- `InsiderAppCardAction.fromData(data)` factory dispatches on `data.type` string:
+  - `deep_link` → `InsiderAppCardDeeplinkAction`
+  - `feedback` → `InsiderAppCardFeedbackAction`
+  - `open_settings` → `InsiderAppCardOpenSettingsAction`
+- Domain models use ES private fields (`#`) for true encapsulation
+
+### 9. Polymorphic Method Signatures
+- `itemRemovedFromCart(productID, saleIDOrCustomParameters?, customParameters?)` and `visitCartPage(products, saleIDOrCustomParameters?, customParameters?)` accept either a saleID string or a customParameters object as the second argument; runtime branches on `typeof === 'string'` vs `isPlainObject`
+
+---
+
+## Directory Layout
+
+```
+./
+├── index.js                 # Main entry — RNInsider static class
+├── index.d.ts               # TypeScript module declaration
+├── package.json             # npm config, version source of truth (8.0.0)
+├── RNInsider.podspec        # CocoaPods spec (reads version from package.json)
+├── babel.config.js          # Babel config
+├── CLAUDE.md                # Claude Code guidance
+│
+├── src/                     # JS source modules
+│   ├── InsiderUser.js/.d.ts
+│   ├── InsiderProduct.js/.d.ts
+│   ├── InsiderEvent.js/.d.ts
+│   ├── InsiderIdentifier.js/.d.ts
+│   ├── InsiderAppCards.js/.d.ts        # NEW
+│   ├── InsiderAppCard.js/.d.ts         # NEW (domain models)
+│   ├── InsiderAppCardsError.js          # NEW (typed error)
+│   ├── InsiderGender.js/.d.ts
+│   ├── InsiderCallbackType.js/.d.ts
+│   ├── ContentOptimizerDataType.js/.d.ts
+│   ├── CloseButtonPosition.js
+│   ├── Util.js                          # + resolveWithCallback
+│   └── __tests__/                       # NEW (per-module tests)
+│       ├── InsiderAppCard.test.js
+│       ├── InsiderAppCards.test.js
+│       ├── InsiderAppCardsError.test.js
+│       └── Util.test.js
+│
+├── ios/RNInsider/           # Objective-C native bridge
+│   ├── RNInsider.h/.m       # ~80 RCT_EXPORT_METHOD entries
+│   ├── RNNotificationHandler.h/.m
+│   └── RNUtils.h/.m
+├── ios/InsiderMobile.xcframework  # bundled native framework
+│
+├── android/                 # Java native bridge
+│   ├── build.gradle
+│   └── src/main/java/com/useinsider/react/
+│       ├── RNInsiderModule.java          # ~80 @ReactMethod entries
+│       ├── RNInsiderPackage.java
+│       └── RNUtils.java
+│
+├── __tests__/               # Top-level Jest tests
+│   ├── Insider.test.js
+│   ├── Util.test.js
+│   ├── getMessageCenterData.test.js
+│   ├── getMessageCenterDataWithIdentifiers.test.js   # NEW
+│   └── setInternalBrowserCloseButtonPosition.test.js
+├── __mocks__/
+│   └── react-native.js      # Global NativeModules mock
+│
+├── docs/                    # NEW — internal feature specs
+│   ├── app-cards/
+│   └── message-center/
+│
+├── example/                 # Demo React Native app (excluded from npm)
+│   ├── App.tsx
+│   ├── android/
+│   └── ios/
+│
+├── .github/workflows/       # CI/CD
+│   ├── check-pull-request.yml
+│   ├── create-release.yml
+│   └── publish-release.yml
+│
+├── devops/                  # Release/deployment scripts
+└── .orbit-output/           # Orbit architecture docs (this dir)
+```
+
+---
+
+## Related Documents
+
+- [CODE-CATALOG.md](./CODE-CATALOG.md) — Full catalog of all classes, functions, modules, and dependencies
+- [API_DOCS.md](./API_DOCS.md) — Complete bridge API reference with serialization patterns
+
+---
+
+## Version Management
+
+- **Source of truth**: `package.json` → `version` field
+- **iOS sync**: `RNInsider.podspec` reads version from `package.json`
+- **SDK version string**: JS prepends `'RN-'` prefix (e.g., `RN-8.0.0`)
+- **Release flow**: `release/X.Y.Z` branch → merge to master → GPG-signed tag → npm publish
+- **Dual-track**: Main release + `-nh` variant (non-Huawei) from `develop-nh` branch
+- **PR title format**: Must contain `MOB-[0-9]+` (enforced by CI)