react-native-nami-sdk 3.3.8 → 3.3.9-dev.202603131926

package/ARCHITECTURE.md

@@ -0,0 +1,166 @@
+# React Native SDK Architecture
+
+The Nami React Native SDK (`react-native-nami-sdk`) is a TypeScript bridge layer that exposes native Android and iOS SDK functionality to React Native applications via TurboModules.
+
+## Build System
+
+- **Language:** TypeScript 5 (strict mode), Kotlin (Android bridge), Swift (iOS bridge)
+- **Package Manager:** npm
+- **TypeScript Output:** Declaration files only (`emitDeclarationOnly`)
+- **Native Code Generation:** React Native Codegen (TurboModule specs)
+- **Linting:** ESLint with @react-native config, Prettier
+
+### Native Dependencies
+
+| Platform | SDK |
+|----------|-----|
+| Android (Google Play) | `com.namiml:sdk-android` |
+| Android (Amazon) | `com.namiml:sdk-amazon` |
+| iOS/tvOS | `Nami` CocoaPod |
+
+## Directory Structure
+
+```
+sdk/react-native/
+├── src/                           # TypeScript bridge layer
+│   ├── index.ts                   # Main exports
+│   ├── types.ts                   # Type definitions
+│   ├── transformers.ts            # Data transformation utilities
+│   ├── version.ts                 # Auto-generated version constant
+│   ├── Nami.ts                    # Core SDK initialization
+│   ├── NamiPaywallManager.ts      # Paywall display/events
+│   ├── NamiCampaignManager.ts     # Campaign management
+│   ├── NamiCustomerManager.ts     # Customer identity
+│   ├── NamiEntitlementManager.ts  # Entitlement access
+│   ├── NamiPurchaseManager.ts     # Purchase operations
+│   ├── NamiFlowManager.ts         # Flow management
+│   └── NamiOverlayControl.tsx     # React component for overlay UI
+├── specs/                         # TurboModule native interface specs
+├── android/                       # Kotlin native bridge modules
+│   └── src/main/java/com/namiml/reactnative/
+├── ios/                           # Swift + Objective-C native bridge
+├── dist/                          # Built .d.ts type declarations
+├── examples/
+│   ├── Basic/                     # Full-featured sample (with Detox e2e)
+│   └── TestNamiTV/                # tvOS sample
+├── build-utils/                   # Version management scripts
+└── scripts/                       # Version generation
+```
+
+## Bridge Architecture
+
+```
+JavaScript (React Native)
+    |
+TurboModule TypeScript Specs (/specs)
+    |
+Native Bridge Modules (Kotlin + Swift)
+    |
+Native SDKs (com.namiml:sdk-android / Nami CocoaPod)
+    |
+Platform APIs (Google Play Billing / StoreKit)
+```
+
+The React Native SDK is a **thin bridge** - it does NOT reimplement networking, IAP handling, paywall rendering, entitlement validation, or purchase tracking. All business logic lives in the native SDKs.
+
+## Manager Classes
+
+Each TypeScript manager wraps a corresponding TurboModule:
+
+| Manager | Key Methods |
+|---------|-------------|
+| `Nami` | `configure()`, `sdkConfigured()`, `sdkVersion()` |
+| `NamiPaywallManager` | `buySkuComplete()`, handler registration (buy, close, sign-in, restore, deeplink) |
+| `NamiCampaignManager` | `launch()`, `allCampaigns()`, `isCampaignAvailable()`, `isFlow()`, `refresh()`, `getProductGroups()` |
+| `NamiCustomerManager` | `login()`, `logout()`, `journeyState()`, `setCustomerAttribute()`, `setAnonymousMode()`, `deviceId()` |
+| `NamiEntitlementManager` | `active()`, `isEntitlementActive()`, `refresh()`, `clearProvisionalEntitlementGrants()` |
+| `NamiPurchaseManager` | `allPurchases()`, `skuPurchased()`, `restorePurchases()`, `presentCodeRedemptionSheet()` |
+| `NamiFlowManager` | `pause()`, `resume()`, `finish()`, `isFlowOpen()`, `registerStepHandoff()` |
+| `NamiOverlayControl` | `presentOverlay()`, `finishOverlay()`, React `NamiOverlayHost` component |
+
+## Native Bridge Modules
+
+### Android (`android/` - Kotlin)
+
+- **NamiBridgePackage.java** - TurboReactPackage registering all modules
+- **NamiBridgeModule.kt** - `RNNami` core configuration
+- **NamiCampaignManagerBridgeModule.kt** - Campaign bridge
+- **NamiPaywallManagerBridgeModule.kt** - Paywall bridge
+- **NamiPurchaseManagerBridge.kt** - Purchase bridge
+- **NamiEntitlementManagerBridge.kt** - Entitlement bridge
+- **NamiCustomerManagerBridge.kt** - Customer bridge
+- **NamiFlowManagerBridge.kt** - Flow bridge
+- **NamiOverlayControlBridge.kt** - Overlay + ReactOverlayActivity
+- **NamiUtil.kt** - Data transformation (WritableMap/WritableArray)
+
+Android supports two product flavors: `play` (Google Play) and `amazon` (Amazon Appstore).
+
+### iOS (`ios/` - Swift)
+
+Parallel Swift implementations for each bridge module, plus Objective-C `.m` files for Codegen/legacy architecture support.
+
+## Type System (`src/types.ts`)
+
+Key types exported to consumers:
+
+- **NamiConfiguration** - SDK init params (appPlatformID, logLevel, language)
+- **NamiSKU** - Product details with platform-specific pricing (Apple, Google, Amazon)
+- **NamiPurchase** - Purchase record with timestamps, transaction IDs, source
+- **NamiEntitlement** - Entitlement with active purchases and related SKUs
+- **NamiCampaign** - Campaign metadata (name, rule type, form factors, segment)
+- **CustomerJourneyState** - Subscription lifecycle flags
+- **NamiPaywallEvent** - Comprehensive event (30+ actions)
+- **NamiPaywallAction** - Enum: BUY_SKU, SELECT_SKU, RESTORE_PURCHASES, VIDEO_STARTED, etc.
+
+## Testing
+
+### Unit Tests
+
+TypeScript unit tests using Jest + ts-jest, covering the pure data transformation layer in `src/transformers.ts`:
+
+- **`parsePurchaseDates`** — converts native timestamp numbers to JS Date objects
+- **`coerceSkuType`** — validates raw strings against `NamiSKUType` union, falls back to `'unknown'`
+- **`mapToNamiPaywallAction`** — validates raw strings against the `NamiPaywallAction` enum (28 values), falls back to `UNKNOWN`
+- **`parseEntitlements`** — transforms raw entitlement arrays, parsing nested purchase dates and defaulting missing SKU arrays
+
+```bash
+# From monorepo root
+make test-react-native
+
+# Or directly
+cd sdk/react-native && npm test
+```
+
+Test files live in `src/__tests__/` and are excluded from TypeScript compilation output via `tsconfig.json`.
+
+### E2E Tests
+
+- Detox framework in `examples/Basic/e2e/` (iOS simulator + Android emulator)
+- CI via GitHub Actions with artifact upload on failure
+
+#### Local Native SDK Resolution
+
+In the monorepo, native SDKs may not yet be published when e2e tests run against a PR. The workflow resolves this by building native SDKs locally before the Detox build:
+
+**iOS** — The `NAMI_SDK_LOCAL_PATH` environment variable points to `sdk/apple/` in the monorepo. When set, each example app's Podfile overrides the published `Nami` CocoaPod with a local `:path` reference. CI builds the XCFramework first (`make build-apple`), then sets the env var so `pod install` picks up the local artifact.
+
+**Android** — CI publishes the SDK to `mavenLocal` via `./gradlew sdk:publishPublicGooglePublicationToMavenLocal sdk:publishPublicAmazonPublicationToMavenLocal`. The example app's `build.gradle` already includes `mavenLocal()` in its repository list, so Gradle resolves the local artifact without any code changes.
+
+Both approaches are temporary until dev release publishing is in place, at which point the pre-build steps and env var can be removed.
+
+### Code Quality
+
+- ESLint + TypeScript compilation checks in CI
+
+## Peer Dependencies
+
+- React >= 18
+- React Native >= 0.73
+
+## Architectural Patterns
+
+- **Bridge/Adapter** - TypeScript wrappers over native TurboModules
+- **Event Emitter** - NativeEventEmitter for real-time native-to-JS events
+- **Thin Client** - All business logic delegated to native SDKs
+- **Codegen** - TurboModule specs for typed native module generation (New Architecture)
+- **Transformer** - Data conversion between native types and JS objects

package/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog - React Native SDK

package/android/build.gradle

@@ -15,7 +15,7 @@ apply plugin: 'com.android.library'
 // apply plugin: 'maven'
 apply plugin: "kotlin-android"
 buildscript {
-    ext.kotlin_version = '1.9.20'
+    ext.kotlin_version = '2.1.0'
     // The Android Gradle plugin is only required when opening the android folder stand-alone.
     // This avoids unnecessary downloads and potential conflicts when the library is included as a
     // module dependency in an application project.
@@ -85,8 +85,8 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
 
-    playImplementation "com.namiml:sdk-android:3.3.8"
-    amazonImplementation "com.namiml:sdk-amazon:3.3.8"
+    playImplementation "com.namiml:sdk-android:3.3.9-dev.202603131926"
+    amazonImplementation "com.namiml:sdk-amazon:3.3.9-dev.202603131926"
 
     implementation "com.facebook.react:react-native:+"  // From node_modules
     coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"

package/android/src/main/java/com/namiml/reactnative/NamiCampaignManagerBridge.kt

@@ -140,9 +140,9 @@ class NamiCampaignManagerBridgeModule internal constructor(
             }
 
             if (context.hasKey("productGroups")) {
-                paywallLaunchContext = PaywallLaunchContext(productGroups.toList(), customAttributes, customObject)
+                paywallLaunchContext = PaywallLaunchContext(productGroups = productGroups.toList(), customAttributes = customAttributes, customObject = customObject)
             } else {
-                paywallLaunchContext = PaywallLaunchContext(null, customAttributes, customObject)
+                paywallLaunchContext = PaywallLaunchContext(productGroups = null, customAttributes = customAttributes, customObject = customObject)
             }
         }
 

package/dist/src/transformers.d.ts

@@ -1,3 +1,6 @@
-import type { NamiPurchase, NamiSKUType } from './types';
+import type { NamiEntitlement, NamiPurchase, NamiSKUType } from './types';
+import { NamiPaywallAction } from './types';
 export declare function parsePurchaseDates(purchase: any): NamiPurchase;
 export declare function coerceSkuType(raw: string): NamiSKUType;
+export declare function mapToNamiPaywallAction(action: string): NamiPaywallAction;
+export declare function parseEntitlements(entitlements: any[]): NamiEntitlement[];

package/dist/src/version.d.ts

@@ -2,4 +2,4 @@
  * Auto-generated file. Do not edit manually.
  * React Native Nami SDK version.
  */
-export declare const NAMI_REACT_NATIVE_VERSION = "3.3.8";
+export declare const NAMI_REACT_NATIVE_VERSION = "3.3.9-dev.202603131926";

package/jest.config.ts

@@ -0,0 +1,10 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+};
+
+export default config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nami-sdk",
-  "version": "3.3.8",
+  "version": "3.3.9-dev.202603131926",
   "description": "React Native SDK for Nami - No-code paywall and onboarding flows with A/B testing.",
   "main": "index.ts",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     "build": "tsc",
     "generate:version": "ts-node scripts/generate-version.ts",
     "prepare": "npm run generate:version && npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest",
     "android": "react-native run-android",
     "android-clean": "cd android && rm -rf .gradle && rm -rf .idea && rm -rf android.iml && rm -rf local.properties",
     "ios": "react-native run-ios",
@@ -73,19 +73,14 @@
     "eslint": "^8.57.1",
     "eslint-plugin-prettier": "^5.5.0",
     "eslint-plugin-react-hooks": "^5.2.0",
+    "jest": "^30.2.0",
     "prettier": "^3.6.0",
     "react": "^18.2.0",
     "react-native": "^0.73.0",
     "react-native-codegen": "^0.0.12",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.0.2"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/namiml/react-native-nami-sdk.git"
-  },
-  "homepage": "https://www.namiml.com",
-  "bugs": {
-    "url": "https://github.com/namiml/react-native-nami-sdk/issues"
-  }
+  "homepage": "https://www.nami.ml"
 }

package/react-native-nami-sdk.podspec

@@ -21,7 +21,7 @@ Pod::Spec.new do |s|
   s.requires_arc  = true
   s.swift_version = '5.0'  # or your supported version
 
-  s.dependency 'Nami', '3.3.8'
+  s.dependency 'Nami', '3.3.9'
   s.dependency 'React'
 
   pod_target_xcconfig = {

package/src/NamiCampaignManager.ts

@@ -10,7 +10,7 @@ import type {
   NamiCampaign,
   NamiError,
 } from './types';
-import { NamiPaywallAction } from './types';
+import { mapToNamiPaywallAction } from './transformers';
 
 const RNNamiCampaignManager: Spec =
   TurboModuleRegistry.getEnforcing<Spec>('RNNamiCampaignManager') ??
@@ -21,16 +21,6 @@ export enum NamiCampaignManagerEvents {
   NamiPaywallEvent = 'NamiPaywallEvent',
 }
 
-const validPaywallActions = new Set(
-  Object.values(NamiPaywallAction) as NamiPaywallAction[],
-);
-
-function mapToNamiPaywallAction(action: string): NamiPaywallAction {
-  return validPaywallActions.has(action as NamiPaywallAction)
-    ? (action as NamiPaywallAction)
-    : NamiPaywallAction.UNKNOWN;
-}
-
 const emitter = new NativeEventEmitter(NativeModules.RNNamiCampaignManager);
 
 export const NamiCampaignManager = {

package/src/NamiEntitlementManager.ts

@@ -6,7 +6,7 @@ import {
 } from 'react-native';
 import type { Spec } from '../specs/NativeNamiEntitlementManager';
 import type { NamiEntitlement } from './types';
-import { parsePurchaseDates } from './transformers';
+import { parseEntitlements } from './transformers';
 
 const RNNamiEntitlementManager: Spec =
   TurboModuleRegistry.getEnforcing?.<Spec>('RNNamiEntitlementManager') ??
@@ -18,15 +18,6 @@ export enum NamiEntitlementManagerEvents {
   EntitlementsChanged = 'EntitlementsChanged',
 }
 
-function parseEntitlements(entitlements: any[]): NamiEntitlement[] {
-  return entitlements.map((ent) => ({
-    ...ent,
-    activePurchases: ent.activePurchases.map(parsePurchaseDates),
-    relatedSkus: ent.relatedSkus ?? [],
-    purchasedSkus: ent.purchasedSkus ?? [],
-  }));
-}
-
 export const NamiEntitlementManager = {
   emitter,
 

package/src/__tests__/transformers.test.ts

@@ -0,0 +1,177 @@
+import {
+  parsePurchaseDates,
+  coerceSkuType,
+  mapToNamiPaywallAction,
+  parseEntitlements,
+} from '../transformers';
+import { NamiPaywallAction } from '../types';
+
+describe('parsePurchaseDates', () => {
+  it('converts timestamp numbers to Date objects', () => {
+    const raw = {
+      skuId: 'com.example.monthly',
+      purchaseInitiatedTimestamp: 1700000000000,
+      expires: 1700086400000,
+    };
+    const result = parsePurchaseDates(raw);
+
+    expect(result.purchaseInitiatedTimestamp).toBeInstanceOf(Date);
+    expect(result.purchaseInitiatedTimestamp.getTime()).toBe(1700000000000);
+    expect(result.expires).toBeInstanceOf(Date);
+    expect(result.expires!.getTime()).toBe(1700086400000);
+  });
+
+  it('sets expires to undefined when absent', () => {
+    const raw = {
+      skuId: 'com.example.lifetime',
+      purchaseInitiatedTimestamp: 1700000000000,
+    };
+    const result = parsePurchaseDates(raw);
+
+    expect(result.expires).toBeUndefined();
+  });
+
+  it('sets expires to undefined when explicitly null', () => {
+    const raw = {
+      skuId: 'com.example.lifetime',
+      purchaseInitiatedTimestamp: 1700000000000,
+      expires: null,
+    };
+    const result = parsePurchaseDates(raw);
+
+    expect(result.expires).toBeUndefined();
+  });
+
+  it('preserves all other fields via spread', () => {
+    const raw = {
+      skuId: 'com.example.monthly',
+      transactionIdentifier: 'txn_123',
+      purchaseSource: 'CAMPAIGN' as const,
+      purchaseInitiatedTimestamp: 1700000000000,
+      sku: { id: 'sku_1', skuId: 'com.example.monthly', type: 'subscription' },
+    };
+    const result = parsePurchaseDates(raw);
+
+    expect(result.skuId).toBe('com.example.monthly');
+    expect(result.transactionIdentifier).toBe('txn_123');
+    expect(result.purchaseSource).toBe('CAMPAIGN');
+    expect(result.sku).toEqual(raw.sku);
+  });
+});
+
+describe('coerceSkuType', () => {
+  it.each(['unknown', 'one_time_purchase', 'subscription'] as const)(
+    'accepts valid type "%s"',
+    (type) => {
+      expect(coerceSkuType(type)).toBe(type);
+    },
+  );
+
+  it('returns "unknown" for invalid types', () => {
+    expect(coerceSkuType('invalid')).toBe('unknown');
+    expect(coerceSkuType('')).toBe('unknown');
+    expect(coerceSkuType('SUBSCRIPTION')).toBe('unknown');
+  });
+});
+
+describe('mapToNamiPaywallAction', () => {
+  it.each(Object.values(NamiPaywallAction))(
+    'accepts valid action "%s"',
+    (action) => {
+      expect(mapToNamiPaywallAction(action)).toBe(action);
+    },
+  );
+
+  it('returns UNKNOWN for unrecognized actions', () => {
+    expect(mapToNamiPaywallAction('NOT_A_REAL_ACTION')).toBe(
+      NamiPaywallAction.UNKNOWN,
+    );
+    expect(mapToNamiPaywallAction('')).toBe(NamiPaywallAction.UNKNOWN);
+    expect(mapToNamiPaywallAction('buy_sku')).toBe(NamiPaywallAction.UNKNOWN);
+  });
+});
+
+describe('parseEntitlements', () => {
+  const rawPurchase = {
+    skuId: 'com.example.monthly',
+    purchaseInitiatedTimestamp: 1700000000000,
+    expires: 1700086400000,
+  };
+
+  it('converts activePurchases dates', () => {
+    const raw = [
+      {
+        name: 'Premium',
+        desc: 'Premium access',
+        referenceId: 'premium',
+        activePurchases: [rawPurchase],
+        purchasedSkus: [{ id: 'sku_1', skuId: 'com.example.monthly', type: 'subscription' }],
+        relatedSkus: [],
+      },
+    ];
+    const result = parseEntitlements(raw);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].activePurchases[0].purchaseInitiatedTimestamp).toBeInstanceOf(Date);
+    expect(result[0].activePurchases[0].expires).toBeInstanceOf(Date);
+  });
+
+  it('defaults relatedSkus and purchasedSkus to empty arrays when missing', () => {
+    const raw = [
+      {
+        name: 'Basic',
+        desc: 'Basic access',
+        referenceId: 'basic',
+        activePurchases: [],
+      },
+    ];
+    const result = parseEntitlements(raw);
+
+    expect(result[0].relatedSkus).toEqual([]);
+    expect(result[0].purchasedSkus).toEqual([]);
+  });
+
+  it('preserves existing relatedSkus and purchasedSkus', () => {
+    const sku = { id: 'sku_1', skuId: 'com.example.monthly', type: 'subscription' };
+    const raw = [
+      {
+        name: 'Premium',
+        desc: 'Premium access',
+        referenceId: 'premium',
+        activePurchases: [],
+        purchasedSkus: [sku],
+        relatedSkus: [sku],
+      },
+    ];
+    const result = parseEntitlements(raw);
+
+    expect(result[0].purchasedSkus).toEqual([sku]);
+    expect(result[0].relatedSkus).toEqual([sku]);
+  });
+
+  it('handles empty array', () => {
+    expect(parseEntitlements([])).toEqual([]);
+  });
+
+  it('handles multiple entitlements', () => {
+    const raw = [
+      {
+        name: 'A',
+        desc: '',
+        referenceId: 'a',
+        activePurchases: [rawPurchase],
+      },
+      {
+        name: 'B',
+        desc: '',
+        referenceId: 'b',
+        activePurchases: [rawPurchase, rawPurchase],
+      },
+    ];
+    const result = parseEntitlements(raw);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].activePurchases).toHaveLength(1);
+    expect(result[1].activePurchases).toHaveLength(2);
+  });
+});

package/src/transformers.ts

@@ -1,4 +1,5 @@
-import type { NamiPurchase, NamiSKUType } from './types';
+import type { NamiEntitlement, NamiPurchase, NamiSKUType } from './types';
+import { NamiPaywallAction } from './types';
 
 export function parsePurchaseDates(purchase: any): NamiPurchase {
   return {
@@ -19,3 +20,22 @@ export function coerceSkuType(raw: string): NamiSKUType {
     ? (raw as NamiSKUType)
     : 'unknown';
 }
+
+const validPaywallActions = new Set(
+  Object.values(NamiPaywallAction) as NamiPaywallAction[],
+);
+
+export function mapToNamiPaywallAction(action: string): NamiPaywallAction {
+  return validPaywallActions.has(action as NamiPaywallAction)
+    ? (action as NamiPaywallAction)
+    : NamiPaywallAction.UNKNOWN;
+}
+
+export function parseEntitlements(entitlements: any[]): NamiEntitlement[] {
+  return entitlements.map((ent) => ({
+    ...ent,
+    activePurchases: ent.activePurchases.map(parsePurchaseDates),
+    relatedSkus: ent.relatedSkus ?? [],
+    purchasedSkus: ent.purchasedSkus ?? [],
+  }));
+}

package/src/version.ts

@@ -2,4 +2,4 @@
  * Auto-generated file. Do not edit manually.
  * React Native Nami SDK version.
  */
-export const NAMI_REACT_NATIVE_VERSION = '3.3.8';
+export const NAMI_REACT_NATIVE_VERSION = '3.3.9-dev.202603131926';

package/tsconfig.json

@@ -67,6 +67,8 @@
     "./build-utils",
     "./specs/*",
     "**/*.spec.*",
+    "**/*.test.*",
+    "**/__tests__/**",
     "**/*.d.ts"
   ]
 }