framepayments-react-native 1.0.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2024 Frame Payments
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,135 @@
+# Frame React Native SDK
+
+React Native SDK for [Frame Payments](https://framepayments.com). It bridges the native Frame iOS and Android SDKs to provide payment UI (checkout and cart modals) and initialization. For API operations (customers, charge intents, refunds, etc.), use the [framepayments](https://www.npmjs.com/package/framepayments) (frame-node) package from JavaScript.
+
+## Requirements
+
+- React Native >= 0.72
+- iOS 17+ / Android 8.0+ (API 26+)
+- A [Frame](https://framepayments.com) account and API key
+
+**Tested with:** Frame iOS SDK (SPM) and Frame Android SDK 1.2.x. Other compatible versions may work but are not officially tested.
+
+## Installation
+
+```bash
+npm install @framepayments/react-native-frame
+# or
+yarn add @framepayments/react-native-frame
+```
+
+### iOS
+
+1. **Add the Frame iOS SDK via Swift Package Manager** (required): In Xcode, open your project, then go to **File → Add Package Dependencies**. Enter:
+   ```
+   https://github.com/Frame-Payments/frame-ios
+   ```
+   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**:
+   ```bash
+   cd ios && pod install && cd ..
+   ```
+
+### Android
+
+No extra steps; autolinking includes the native module.
+
+## Usage
+
+### 1. Initialize
+
+Call once at app startup (e.g. in your root component or App.js).
+
+```ts
+import Frame from '@framepayments/react-native-frame';
+
+Frame.initialize({
+  apiKey: 'YOUR_FRAME_SECRET_KEY',
+  debugMode: false, // set true for development
+});
+```
+
+### 2. Present Checkout
+
+Opens the native checkout modal. Resolves with the created charge intent on success.
+
+```ts
+const chargeIntent = await Frame.presentCheckout({
+  customerId: 'cus_xxx', // optional
+  amount: 10000, // cents
+});
+```
+
+### 3. Present Cart
+
+Opens the cart flow (cart screen then checkout). Resolves with the charge intent when the user completes payment.
+
+```ts
+const chargeIntent = await Frame.presentCart({
+  customerId: 'cus_xxx', // optional
+  items: [
+    { id: '1', title: 'Product A', amountInCents: 10000, imageUrl: 'https://...' },
+  ],
+  shippingAmountInCents: 500,
+});
+```
+
+### Error handling
+
+The SDK rejects with an error object that includes `code` and `message`. Common codes:
+
+- `NOT_INITIALIZED` – You called `presentCheckout` or `presentCart` before `Frame.initialize()`.
+- `USER_CANCELED` – The user dismissed the modal or closed checkout without completing payment.
+- `NO_ACTIVITY` / `NO_ROOT_VC` – No host activity or view controller available (e.g. app not ready).
+
+```ts
+try {
+  const intent = await Frame.presentCheckout({ amount: 10000 });
+} catch (e: any) {
+  if (e.code === 'USER_CANCELED') return;
+  console.error(e.code, e.message);
+}
+```
+
+### API calls (customers, charge intents, refunds)
+
+Install the Frame Node SDK (optional peer dependency) and use it from your React Native app:
+
+```bash
+npm install framepayments
+```
+
+```ts
+import { FrameSDK } from 'framepayments';
+
+const frame = new FrameSDK({ apiKey: 'YOUR_SECRET_KEY' });
+const customers = await frame.customers.list();
+```
+
+## Security
+
+- **API key**: Use your Frame **secret** key only in a secure context. Do not commit it to source control; use environment variables or a secure config.
+- **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.
+
+## 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`.
+
+## Release checklist
+
+For maintainers publishing a new version:
+
+1. Bump version in `package.json`
+2. Update `CHANGELOG.md` with the new version and date
+3. Commit and tag: `git tag v1.0.0`
+4. Push and create a GitHub release
+5. Publish: `npm publish --access public` (for scoped packages)
+
+## License
+
+Apache-2.0

package/android/build.gradle

@@ -0,0 +1,46 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath 'com.android.tools.build:gradle:8.1.0'
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0"
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.framepayments.reactnativeframe"
+  compileSdk safeExtGet('compileSdkVersion', 34)
+  defaultConfig {
+    minSdk safeExtGet('minSdkVersion', 26)
+    targetSdk safeExtGet('targetSdkVersion', 34)
+  }
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_11
+    targetCompatibility JavaVersion.VERSION_11
+  }
+  kotlinOptions {
+    jvmTarget = '11'
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+  maven { url "https://jitpack.io" }
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-native:+'
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.0"
+  implementation 'com.framepayments:framesdk:1.2.0'
+  implementation 'com.framepayments:framesdk_ui:1.2.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,12 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <activity
+      android:name="com.framepayments.reactnativeframe.FrameCheckoutActivity"
+      android:theme="@style/Theme.AppCompat.Light.NoActionBar"
+      android:exported="false" />
+    <activity
+      android:name="com.framepayments.reactnativeframe.FrameFlowActivity"
+      android:theme="@style/Theme.AppCompat.Light.NoActionBar"
+      android:exported="false" />
+  </application>
+</manifest>

package/android/src/main/java/com/framepayments/reactnativeframe/FrameCheckoutActivity.kt

@@ -0,0 +1,40 @@
+package com.framepayments.reactnativeframe
+
+import android.content.Intent
+import android.os.Bundle
+import android.widget.FrameLayout
+import androidx.appcompat.app.AppCompatActivity
+import com.framepayments.framesdk.FrameNetworking
+import com.framepayments.framesdk.chargeintents.ChargeIntent
+import com.framepayments.framesdk_ui.FrameCheckoutView
+import com.google.gson.Gson
+
+class FrameCheckoutActivity : AppCompatActivity() {
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    val container = FrameLayout(this).apply {
+      layoutParams = FrameLayout.LayoutParams(
+        FrameLayout.LayoutParams.MATCH_PARENT,
+        FrameLayout.LayoutParams.MATCH_PARENT
+      )
+    }
+    setContentView(container)
+    val customerId = intent.getStringExtra(EXTRA_CUSTOMER_ID)
+    val amount = intent.getIntExtra(EXTRA_AMOUNT, 0)
+    val checkoutView = FrameCheckoutView(this)
+    checkoutView.configure(customerId, amount) { chargeIntent ->
+      val json = Gson().toJson(chargeIntent)
+      setResult(RESULT_OK, Intent().putExtra(EXTRA_CHARGE_INTENT_JSON, json))
+      finish()
+    }
+    container.addView(checkoutView)
+  }
+
+  companion object {
+    const val EXTRA_CUSTOMER_ID = "customer_id"
+    const val EXTRA_AMOUNT = "amount"
+    const val EXTRA_CHARGE_INTENT_JSON = "charge_intent_json"
+    const val REQUEST_CODE = 9001
+  }
+}

package/android/src/main/java/com/framepayments/reactnativeframe/FrameFlowActivity.kt

@@ -0,0 +1,84 @@
+package com.framepayments.reactnativeframe
+
+import android.content.Intent
+import android.os.Bundle
+import android.widget.FrameLayout
+import androidx.appcompat.app.AppCompatActivity
+import com.framepayments.framesdk_ui.FrameCartItem
+import com.framepayments.framesdk_ui.FrameCartView
+import com.framepayments.framesdk_ui.FrameCheckoutView
+import com.google.gson.Gson
+import com.google.gson.reflect.TypeToken
+
+class FrameFlowActivity : AppCompatActivity() {
+
+  private var cartView: FrameCartView? = null
+  private var checkoutView: FrameCheckoutView? = null
+  private val container by lazy {
+    FrameLayout(this).apply {
+      layoutParams = FrameLayout.LayoutParams(
+        FrameLayout.LayoutParams.MATCH_PARENT,
+        FrameLayout.LayoutParams.MATCH_PARENT
+      )
+      id = android.R.id.content
+    }
+  }
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    setContentView(container)
+    val customerId = intent.getStringExtra(EXTRA_CUSTOMER_ID)
+    val itemsJson = intent.getStringExtra(EXTRA_ITEMS_JSON)
+    val shippingCents = intent.getIntExtra(EXTRA_SHIPPING_CENTS, 0)
+    val items: List<FrameCartItem> = parseCartItems(itemsJson) ?: emptyList()
+    showCart(customerId, items, shippingCents)
+  }
+
+  private fun parseCartItems(json: String?): List<FrameCartItem>? {
+    if (json.isNullOrBlank()) return emptyList()
+    return try {
+      val type = object : TypeToken<List<CartItemDto>>() {}.type
+      val list: List<CartItemDto> = Gson().fromJson(json, type)
+      list.map { FrameCartItem(it.id, it.title, it.amountInCents, it.imageUrl) }
+    } catch (e: Exception) {
+      null
+    }
+  }
+
+  private data class CartItemDto(
+    val id: String,
+    val title: String,
+    val amountInCents: Int,
+    val imageUrl: String
+  )
+
+  private fun showCart(customerId: String?, items: List<FrameCartItem>, shippingCents: Int) {
+    container.removeAllViews()
+    cartView = FrameCartView(this).apply {
+      configure(customerId, items, shippingCents) { totalCents ->
+        showCheckout(customerId, totalCents)
+      }
+    }
+    container.addView(cartView)
+  }
+
+  private fun showCheckout(customerId: String?, amount: Int) {
+    container.removeAllViews()
+    checkoutView = FrameCheckoutView(this).apply {
+      configure(customerId, amount) { chargeIntent ->
+        val json = Gson().toJson(chargeIntent)
+        setResult(RESULT_OK, Intent().putExtra(EXTRA_CHARGE_INTENT_JSON, json))
+        finish()
+      }
+    }
+    container.addView(checkoutView)
+  }
+
+  companion object {
+    const val EXTRA_CUSTOMER_ID = "customer_id"
+    const val EXTRA_ITEMS_JSON = "items_json"
+    const val EXTRA_SHIPPING_CENTS = "shipping_cents"
+    const val EXTRA_CHARGE_INTENT_JSON = "charge_intent_json"
+    const val REQUEST_CODE = 9002
+  }
+}

package/android/src/main/java/com/framepayments/reactnativeframe/FrameSDKModule.kt

@@ -0,0 +1,175 @@
+package com.framepayments.reactnativeframe
+
+import android.app.Activity
+import android.content.Intent
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableNativeArray
+import com.facebook.react.bridge.WritableNativeMap
+import org.json.JSONArray
+import com.framepayments.framesdk.FrameNetworking
+import org.json.JSONObject
+
+class FrameSDKModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext), ActivityEventListener {
+
+  init {
+    reactContext.addActivityEventListener(this)
+  }
+
+  private var checkoutPromise: Promise? = null
+  private var cartPromise: Promise? = null
+
+  override fun getName(): String = "FrameSDK"
+
+  @ReactMethod
+  fun initialize(apiKey: String, debugMode: Boolean, promise: Promise) {
+    try {
+      val ctx = reactApplicationContext.applicationContext
+      FrameNetworking.initializeWithAPIKey(ctx, apiKey, debugMode)
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("INIT_FAILED", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun presentCheckout(customerId: String?, amount: Double, promise: Promise) {
+    val activity = currentActivity ?: run {
+      promise.reject("NO_ACTIVITY", "No current activity", null)
+      return
+    }
+    checkoutPromise = promise
+    val intent = Intent(activity, FrameCheckoutActivity::class.java).apply {
+      putExtra(FrameCheckoutActivity.EXTRA_CUSTOMER_ID, customerId)
+      putExtra(FrameCheckoutActivity.EXTRA_AMOUNT, amount.toInt())
+    }
+    activity.startActivityForResult(intent, FrameCheckoutActivity.REQUEST_CODE)
+  }
+
+  @ReactMethod
+  fun presentCart(
+    customerId: String?,
+    items: com.facebook.react.bridge.ReadableArray,
+    shippingAmountInCents: Double,
+    promise: Promise
+  ) {
+    val activity = currentActivity ?: run {
+      promise.reject("NO_ACTIVITY", "No current activity", null)
+      return
+    }
+    val itemsJson = readableArrayToJson(items) ?: run {
+      promise.reject("INVALID_ITEMS", "Invalid cart items", null)
+      return
+    }
+    cartPromise = promise
+    val intent = Intent(activity, FrameFlowActivity::class.java).apply {
+      putExtra(FrameFlowActivity.EXTRA_CUSTOMER_ID, customerId)
+      putExtra(FrameFlowActivity.EXTRA_ITEMS_JSON, itemsJson)
+      putExtra(FrameFlowActivity.EXTRA_SHIPPING_CENTS, shippingAmountInCents.toInt())
+    }
+    activity.startActivityForResult(intent, FrameFlowActivity.REQUEST_CODE)
+  }
+
+  private fun readableArrayToJson(items: com.facebook.react.bridge.ReadableArray): String? {
+    val arr = org.json.JSONArray()
+    for (i in 0 until items.size()) {
+      val item = items.getMap(i) ?: return null
+      val obj = org.json.JSONObject()
+      obj.put("id", item.getString("id"))
+      obj.put("title", item.getString("title"))
+      obj.put("amountInCents", item.getDouble("amountInCents").toInt())
+      obj.put("imageUrl", item.getString("imageUrl"))
+      arr.put(obj)
+    }
+    return arr.toString()
+  }
+
+  override fun onActivityResult(activity: Activity?, requestCode: Int, resultCode: Int, data: Intent?) {
+    when (requestCode) {
+      FrameCheckoutActivity.REQUEST_CODE -> handleCheckoutResult(resultCode, data)
+      FrameFlowActivity.REQUEST_CODE -> handleCartResult(resultCode, data)
+      else -> return
+    }
+  }
+
+  private fun handleCheckoutResult(resultCode: Int, data: Intent?) {
+    val promise = checkoutPromise ?: return
+    checkoutPromise = null
+    if (resultCode == Activity.RESULT_OK && data != null) {
+      val json = data.getStringExtra(FrameCheckoutActivity.EXTRA_CHARGE_INTENT_JSON)
+      if (json != null) {
+        try {
+          val obj = JSONObject(json)
+          val map = jsonObjectToWritableMap(obj)
+          promise.resolve(map)
+        } catch (e: Exception) {
+          promise.reject("PARSE_ERROR", e.message, e)
+        }
+      } else {
+        promise.reject("NO_RESULT", "No charge intent in result", null)
+      }
+    } else {
+      promise.reject("USER_CANCELED", "User cancelled checkout", null)
+    }
+  }
+
+  private fun handleCartResult(resultCode: Int, data: Intent?) {
+    val promise = cartPromise ?: return
+    cartPromise = null
+    if (resultCode == Activity.RESULT_OK && data != null) {
+      val json = data.getStringExtra(FrameFlowActivity.EXTRA_CHARGE_INTENT_JSON)
+      if (json != null) {
+        try {
+          val obj = JSONObject(json)
+          val map = jsonObjectToWritableMap(obj)
+          promise.resolve(map)
+        } catch (e: Exception) {
+          promise.reject("PARSE_ERROR", e.message, e)
+        }
+      } else {
+        promise.reject("NO_RESULT", "No charge intent in result", null)
+      }
+    } else {
+      promise.reject("USER_CANCELED", "User cancelled", null)
+    }
+  }
+
+  private fun jsonObjectToWritableMap(obj: JSONObject): WritableNativeMap {
+    val map = WritableNativeMap()
+    for (key in obj.keys()) {
+      if (obj.isNull(key)) continue
+      when (val v = obj.get(key)) {
+        is String -> map.putString(key, v)
+        is Int -> map.putInt(key, v)
+        is Long -> map.putDouble(key, v.toDouble())
+        is Double -> map.putDouble(key, v)
+        is Boolean -> map.putBoolean(key, v)
+        is JSONObject -> map.putMap(key, jsonObjectToWritableMap(v))
+        is JSONArray -> map.putArray(key, jsonArrayToWritableArray(v))
+      }
+    }
+    return map
+  }
+
+  private fun jsonArrayToWritableArray(arr: JSONArray): WritableNativeArray {
+    val list = WritableNativeArray()
+    for (i in 0 until arr.length()) {
+      when (val v = arr.get(i)) {
+        is String -> list.pushString(v)
+        is Int -> list.pushInt(v)
+        is Long -> list.pushDouble(v.toDouble())
+        is Double -> list.pushDouble(v)
+        is Boolean -> list.pushBoolean(v)
+        is JSONObject -> list.pushMap(jsonObjectToWritableMap(v))
+        is JSONArray -> list.pushArray(jsonArrayToWritableArray(v))
+      }
+    }
+    return list
+  }
+
+  override fun onNewIntent(intent: Intent?) {}
+}

package/android/src/main/java/com/framepayments/reactnativeframe/FrameSDKPackage.kt

@@ -0,0 +1,16 @@
+package com.framepayments.reactnativeframe
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class FrameSDKPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(FrameSDKModule(reactContext))
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return emptyList()
+  }
+}

package/ios/FrameReactNative.podspec

@@ -0,0 +1,26 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name         = 'FrameReactNative'
+  s.version      = package['version']
+  s.summary      = package['description']
+  s.homepage     = package['homepage']
+  s.license      = package['license']
+  s.authors      = package['author']
+  s.platforms    = { :ios => '17.0' }
+  s.source       = { :git => package['repository']['url'], :tag => "#{s.version}" }
+  s.source_files = '**/*.{h,m,mm,swift}'
+  s.requires_arc = true
+
+  s.dependency 'React-Core'
+
+  # Frame-iOS SDK – must be available to the app. Add via Swift Package Manager in Xcode:
+  # File → Add Package Dependencies → https://github.com/Frame-Payments/frame-ios
+  # Our native code imports Frame; ensure the app target links Frame-iOS (SPM).
+  # If Frame-iOS is provided as a pod in the future, uncomment:
+  # s.dependency 'Frame-iOS'
+
+  install_modules_dependencies(s) if respond_to?(:install_modules_dependencies)
+end

package/ios/FrameSDKBridge.m

@@ -0,0 +1,26 @@
+//
+//  FrameSDKBridge.m
+//  FrameReactNative
+//
+
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(FrameSDK, FrameSDKBridge)
+
+RCT_EXTERN_METHOD(initialize:(NSString *)apiKey
+                  debugMode:(BOOL)debugMode
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(presentCheckout:(id)customerId
+                  amount:(nonnull NSNumber *)amount
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(presentCart:(id)customerId
+                  items:(NSArray *)items
+                  shippingAmountInCents:(nonnull NSNumber *)shippingAmountInCents
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end