framepayments-react-native 1.0.0 → 1.0.1

package/README.md

@@ -13,9 +13,9 @@ React Native SDK for [Frame Payments](https://framepayments.com). It bridges the
 ## Installation
 
 ```bash
-npm install @framepayments/react-native-frame
+npm install framepayments-react-native
 # or
-yarn add @framepayments/react-native-frame
+yarn add framepayments-react-native
 ```
 
 ### iOS
@@ -26,11 +26,27 @@ yarn add @framepayments/react-native-frame
    ```
    Add the **Frame-iOS** package and choose the version or branch you need. The React Native SDK’s native code depends on it; CocoaPods cannot pull it in automatically.
 
-2. **Install pods**:
+2. **Preload Frame on the main thread** (required): Add this to your `AppDelegate.m` or `AppDelegate.mm` **before** calling `[super application:didFinishLaunchingWithOptions:]`:
+   ```objc
+   #import "YourAppName-Swift.h"  // Use your app's module name
+   // ...
+   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+   {
+     [FramePreloader preloadOnMainThread];  // Prevents "Helpers are not supported by the default hub" crash
+     return [super application:application didFinishLaunchingWithOptions:launchOptions];
+   }
+   ```
+   `FramePreloader` is part of the SDK and loads Frame/Evervault/Sift on the main thread before the React Native bridge initializes.
+
+   **If your app has a different module name than the example** (e.g. not `FrameExampleTemp`), add `FRAME_SWIFT_HEADER="YourApp-Swift.h"` to your app target's **Preprocessor Macros** in Xcode build settings. The native bridge uses this to import the Swift header.
+
+3. **Install pods**:
    ```bash
    cd ios && pod install && cd ..
    ```
 
+4. Run the app (e.g. `npx react-native run-ios`). The example app already includes this setup.
+
 ### Android
 
 No extra steps; autolinking includes the native module.
@@ -39,15 +55,15 @@ No extra steps; autolinking includes the native module.
 
 ### 1. Initialize
 
-Call once at app startup (e.g. in your root component or App.js).
+Call once at app startup (e.g. in your root component or App.js). Returns a Promise; await or catch to handle native init errors.
 
 ```ts
-import Frame from '@framepayments/react-native-frame';
+import Frame from 'framepayments-react-native';
 
 Frame.initialize({
   apiKey: 'YOUR_FRAME_SECRET_KEY',
   debugMode: false, // set true for development
-});
+}).catch((e) => console.warn('Frame init failed:', e.message));
 ```
 
 ### 2. Present Checkout
@@ -113,12 +129,16 @@ const customers = await frame.customers.list();
 - **Production**: Disable `debugMode` in production to avoid logging sensitive data.
 - Payment card data is handled by the native Frame SDKs (Evervault, etc.) and never touches your JS bundle.
 
+## Troubleshooting (iOS)
+
+- **"Helpers are not supported by the default hub"** – This occurs when Frame/Evervault loads on a background thread during React Native bridge init. **Fix:** Call `[FramePreloader preloadOnMainThread]` in your `AppDelegate` before `[super application:didFinishLaunchingWithOptions:]` (see [Installation – iOS](#ios) step 2). Also ensure the **Frame-iOS** Swift package is added in Xcode (**File → Add Package Dependencies** → `https://github.com/Frame-Payments/frame-ios`).
+
 ## Running the example
 
 The [example](./example) folder contains a sample app (App.tsx, package.json) that uses the SDK for init, presentCheckout, presentCart, and frame-node for listing customers.
 
-1. **From this repo (local SDK):** Create a new React Native app (e.g. `npx react-native init FrameExample`), then copy `example/App.tsx` into it and add the dependency: `"@framepayments/react-native-frame": "file:/path/to/frame-react-native"`. Run `npm install`. On iOS: add Frame-iOS via SPM in Xcode (see [Installation – iOS](#ios) above), then `cd ios && pod install`. See [example/README.md](./example/README.md) for details.
-2. **Using the published package:** Install `@framepayments/react-native-frame` and `framepayments` in your app and use the same patterns as in `example/App.tsx`.
+1. **From this repo (local SDK):** Create a new React Native app (e.g. `npx react-native init FrameExample`), then copy `example/App.tsx` into it and add the dependency: `"framepayments-react-native": "file:/path/to/frame-react-native"`. Run `npm install`. On iOS: add Frame-iOS via SPM in Xcode (see [Installation – iOS](#ios) above), then `cd ios && pod install`. See [example/README.md](./example/README.md) for details.
+2. **Using the published package:** Install `framepayments-react-native` and `framepayments` in your app and use the same patterns as in `example/App.tsx`.
 
 ## Release checklist
 

package/android/build/.transforms/3db830673120be833016e77c88c53305/results.bin

@@ -0,0 +1 @@
+o/debug

package/android/build/.transforms/e32bd1e24a69eac3ebaf0c3a5e659207/results.bin

@@ -0,0 +1 @@
+i/

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/aapt/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.framepayments.reactnativeframe" >
+
+    <uses-sdk android:minSdkVersion="26" />
+
+    <application>
+        <activity
+            android:name="com.framepayments.reactnativeframe.FrameCheckoutActivity"
+            android:exported="false"
+            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+        <activity
+            android:name="com.framepayments.reactnativeframe.FrameFlowActivity"
+            android:exported="false"
+            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+    </application>
+
+</manifest>

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/aapt/output-metadata.json

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "artifactType": {
+    "type": "AAPT_FRIENDLY_MERGED_MANIFESTS",
+    "kind": "Directory"
+  },
+  "applicationId": "com.framepayments.reactnativeframe",
+  "variantName": "debug",
+  "elements": [
+    {
+      "type": "SINGLE",
+      "filters": [],
+      "attributes": [],
+      "outputFile": "AndroidManifest.xml"
+    }
+  ],
+  "elementType": "File"
+}

package/android/build/intermediates/aar_metadata/debug/aar-metadata.properties

@@ -0,0 +1,5 @@
+aarFormatVersion=1.0
+aarMetadataVersion=1.0
+minCompileSdk=1
+minCompileSdkExtension=0
+minAndroidGradlePluginVersion=1.0.0

package/android/build/intermediates/annotation_processor_list/debug/annotationProcessors.json

@@ -0,0 +1 @@
+{}

package/android/build/intermediates/incremental/debug/packageDebugResources/compile-file-map.properties

@@ -0,0 +1 @@
+#Wed Feb 18 13:42:41 PST 2026

package/android/build/intermediates/incremental/debug/packageDebugResources/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main" generated-set="main$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug" generated-set="debug$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/build/generated/res/resValues/debug"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated" generated-set="generated$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/build/generated/res/resValues/debug"/></dataSet><mergedItems/></merger>

package/android/build/intermediates/incremental/mergeDebugJniLibFolders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/jniLibs"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/debug/jniLibs"/></dataSet></merger>

package/android/build/intermediates/incremental/mergeDebugShaders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/shaders"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/debug/shaders"/></dataSet></merger>

package/android/build/intermediates/incremental/packageDebugAssets/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/assets"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/debug/assets"/></dataSet><dataSet config="generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/build/intermediates/shader_assets/debug/out"/></dataSet></merger>

package/android/build/intermediates/local_only_symbol_list/debug/R-def.txt

@@ -0,0 +1,2 @@
+R_DEF: Internal format may change without notice
+local

package/android/build/intermediates/manifest_merge_blame_file/debug/manifest-merger-blame-debug-report.txt

@@ -0,0 +1,27 @@
+1<?xml version="1.0" encoding="utf-8"?>
+2<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+3    package="com.framepayments.reactnativeframe" >
+4
+5    <uses-sdk android:minSdkVersion="26" />
+6
+7    <application>
+7-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:3:3-12:17
+8        <activity
+8-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:4:5-7:34
+9            android:name="com.framepayments.reactnativeframe.FrameCheckoutActivity"
+9-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:5:7-78
+10            android:exported="false"
+10-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:7:7-31
+11            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+11-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:6:7-63
+12        <activity
+12-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:8:5-11:34
+13            android:name="com.framepayments.reactnativeframe.FrameFlowActivity"
+13-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:9:7-74
+14            android:exported="false"
+14-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:11:7-31
+15            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+15-->/Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:10:7-63
+16    </application>
+17
+18</manifest>

package/android/build/intermediates/merged_manifest/debug/AndroidManifest.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.framepayments.reactnativeframe" >
+
+    <uses-sdk android:minSdkVersion="26" />
+
+    <application>
+        <activity
+            android:name="com.framepayments.reactnativeframe.FrameCheckoutActivity"
+            android:exported="false"
+            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+        <activity
+            android:name="com.framepayments.reactnativeframe.FrameFlowActivity"
+            android:exported="false"
+            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
+    </application>
+
+</manifest>

package/android/build/intermediates/navigation_json/debug/navigation.json

@@ -0,0 +1 @@
+[]

package/android/build/intermediates/symbol_list_with_package_name/debug/package-aware-r.txt

@@ -0,0 +1 @@
+com.framepayments.reactnativeframe

package/android/build/kotlin/compileDebugKotlin/cacheable/caches-jvm/lookups/counters.tab

@@ -0,0 +1,2 @@
+4
+0

package/android/build/outputs/logs/manifest-merger-debug-report.txt

@@ -0,0 +1,35 @@
+-- Merging decision tree log ---
+manifest
+ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:1:1-13:12
+INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:1:1-13:12
+	package
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:2:5-49
+		INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml
+	xmlns:android
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:1:11-69
+application
+ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:3:3-12:17
+activity#com.framepayments.reactnativeframe.FrameCheckoutActivity
+ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:4:5-7:34
+	android:exported
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:7:7-31
+	android:theme
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:6:7-63
+	android:name
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:5:7-78
+activity#com.framepayments.reactnativeframe.FrameFlowActivity
+ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:8:5-11:34
+	android:exported
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:11:7-31
+	android:theme
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:10:7-63
+	android:name
+		ADDED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml:9:7-74
+uses-sdk
+INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml reason: use-sdk injection requested
+INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml
+INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml
+	android:targetSdkVersion
+		INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml
+	android:minSdkVersion
+		INJECTED from /Users/erictownsend/Documents/GitHub/frame-react-native/example/node_modules/framepayments-react-native/android/src/main/AndroidManifest.xml