@socure-inc/docv-react-native 5.2.6 → 5.2.8

package/README.md

@@ -7,15 +7,45 @@ The Predictive Document Verification (DocV) SDK for React Native is a React Nati
 ## Table of Contents
 
 1. [Getting Started](#getting-started)
-2. [Step 1: Install the React Native Wrapper](#step-1-install-the-react-native-wrapper)
-3. [Step 2: Configure Your iOS or Android App](#step-2-configure-your-ios-or-android-app)
-4. [Step 3: Run the App](#step-3-run-the-app)
-5. [Step 4: Generate a Transaction Token and Configure the Capture App](#step-4-generate-a-transaction-token-and-configure-the-capture-app)
-6. [Step 5: Import and Launch the SDK](#step-5-import-and-launch-the-sdk)
-7. [Step 6: Handle Response Callbacks](#step-6-handle-response-callbacks)
-8. [Step 7: Fetch the Verification Results](#step-7-fetch-the-verification-results)
+2. [React Native New Architecture Support](#react-native-new-architecture-support)
+3. [Step 1: Install the React Native Wrapper](#step-1-install-the-react-native-wrapper)
+4. [Step 2: Configure Your iOS or Android App](#step-2-configure-your-ios-or-android-app)
+5. [Step 3: Run the App](#step-3-run-the-app)
+6. [Step 4: Generate a Transaction Token and Configure the Capture App](#step-4-generate-a-transaction-token-and-configure-the-capture-app)
+7. [Step 5: Import and Launch the SDK](#step-5-import-and-launch-the-sdk)
+8. [Step 6: Handle Response Callbacks](#step-6-handle-response-callbacks)
+9. [Step 7: Fetch the Verification Results](#step-7-fetch-the-verification-results)
 
 
+## React Native New Architecture Support
+
+Starting with this version 5.2.8, the wrapper fully supports the **React Native New Architecture** (TurboModules / Fabric) introduced in React Native 0.79+. Both Old Architecture and New Architecture builds are supported from the same package with no configuration changes required.
+
+### What changed
+
+| Area | Old Architecture | New Architecture |
+|---|---|---|
+| Module system | `NativeModules` bridge | TurboModule (JSI, CodeGen spec) |
+| iOS bridge file | `.m` (ObjC extern) | `.mm` (conditional `#ifdef RCT_NEW_ARCH_ENABLED`) |
+| Android package | `ReactPackage` | `BaseReactPackage` with `ReactModuleInfoProvider` |
+| Peer dependencies | React ≥ 16.13.1, RN ≥ 0.66 | React ≥ 19.0.0, RN ≥ 0.79.0 |
+
+### New Promise-based API
+
+In addition to the existing callback-based `launchSocureDocV`, a new **Promise-based API** `launchSocureDocVWithPromise` is now available. This is the recommended API for New Architecture apps and any new integrations.
+
+```jsx
+import { launchSocureDocVWithPromise } from "@socure-inc/docv-react-native";
+```
+
+Under the New Architecture, `launchSocureDocV` also continues to work — it internally bridges callbacks over the TurboModule promise API when the legacy callback method is not available, so **existing integrations require no code changes**.
+
+### Enhanced error object
+
+The `onError` callback now includes a machine-readable `code` field alongside the existing `error` message string. See the [updated error reference](#onerror-response) for all codes.
+
+---
+
 ## Getting started
 
 Before you begin, ensure you have the following:
@@ -27,6 +57,8 @@ Before you begin, ensure you have the following:
 **React Native**
 
 - React Native CLI. See the [React Native docs](https://reactnative.dev/docs/environment-setup) for instructions on how to set up your development environment.
+- React Native **0.79.0** or later (required for New Architecture / TurboModule support)
+- React **19.0.0** or later
 
 **iOS**
 
@@ -36,6 +68,7 @@ Before you begin, ensure you have the following:
 **Android**
 
 - `compileSdkVersion: 36`
+- `minSdkVersion: 23`
 - `Java: 17`
 
 ## Step 1: Install the React Native wrapper
@@ -73,43 +106,117 @@ pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react
 Once completed, your `Podfile` should look like the following example:
 
 ```swift {4,36}
-require_relative '../node_modules/react-native/scripts/react_native_pods'
-require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
-
-platform :ios, '13.0'
-install! 'cocoapods', :deterministic_uuids => false
-
-production = ENV["PRODUCTION"] == "1"
+# Resolve react_native_pods.rb with node to allow for hoisting
+require Pod::Executable.execute_command('node', ['-p',
+  'require.resolve(
+    "react-native/scripts/react_native_pods.rb",
+    {paths: [process.argv[1]]},
+  )', __dir__]).strip
+
+platform :ios, min_ios_version_supported
+prepare_react_native_project!
+
+linkage = ENV['USE_FRAMEWORKS']
+if linkage != nil
+  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
+  use_frameworks! :linkage => linkage.to_sym
+end
 
-target 'SocureDocVDemo' do
+target 'DocVReactNativeSample' do
   config = use_native_modules!
 
-  # Flags change depending on the env values.
-  flags = get_default_flags()
-
   use_react_native!(
     :path => config[:reactNativePath],
-    # to enable hermes on iOS, change `false` to `true` and then install pods
-    :production => production,
-    :hermes_enabled => flags[:hermes_enabled],
-    :fabric_enabled => flags[:fabric_enabled],
-    :flipper_configuration => FlipperConfiguration.enabled,
     # An absolute path to your application root.
     :app_path => "#{Pod::Config.instance.installation_root}/.."
   )
 
-  target 'SocureDocVDemoTests' do
-    inherit! :complete
-    # Pods for testing
-  end
-
   post_install do |installer|
-    react_native_post_install(installer)
-    __apply_Xcode_12_5_M1_post_install_workaround(installer)
+    # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
+    react_native_post_install(
+      installer,
+      config[:reactNativePath],
+      :mac_catalyst_enabled => false,
+      # :ccache_enabled => true
+    )
+
+    # fmt fails under Xcode 26 Clang (consteval FMT_STRING). base.h redefines
+    # FMT_USE_CONSTEVAL unconditionally, so patch it to honor an external value,
+    # then force it off below. Toolchain workaround; idempotent.
+    fmt_base = File.join(installer.sandbox.root, 'fmt', 'include', 'fmt', 'base.h')
+    if File.exist?(fmt_base)
+      src = File.read(fmt_base)
+      # Turn the chain's opening `#if` into an `#elif` behind our own branch.
+      original_open = "#if !defined(__cpp_lib_is_constant_evaluated)\n#  define FMT_USE_CONSTEVAL 0\n"
+      patched_open  = "#if defined(FMT_USE_CONSTEVAL)\n// honor externally-provided value\n" \
+                      "#elif !defined(__cpp_lib_is_constant_evaluated)\n#  define FMT_USE_CONSTEVAL 0\n"
+      if src.include?(original_open)
+        src = src.sub(original_open, patched_open)
+        File.chmod(0644, fmt_base)  # pod headers are read-only
+        File.write(fmt_base, src)
+        Pod::UI.puts "[fmt] Patched base.h to honor pre-set FMT_USE_CONSTEVAL".green
+      end
+    end
+
+    # socure-docv-react-native (Swift + Obj-C++ static module) build fixes for
+    # Xcode 26 / new arch. Patch the copied pod sources; idempotent.
+    socure_ios = File.expand_path('../node_modules/@socure-inc/docv-react-native/ios', __dir__)
+
+    # Fix 1: drop the non-modular C++ import from the bridging header — it breaks
+    # Clang module scanning ("could not build module 'socure_docv_react_native'").
+    bridging = File.join(socure_ios, 'SocureDocVReactNative-Bridging-Header.h')
+    if File.exist?(bridging)
+      original = File.read(bridging)
+      patched = original.gsub(/^#import <ReactCommon\/RCTTurboModule\.h>\r?\n/, '')
+      if patched != original
+        File.chmod(0644, bridging)
+        File.write(bridging, patched)
+        Pod::UI.puts "[socure-docv] Removed non-modular C++ import from bridging header".green
+      end
+    end
+
+    # Fix 2: promote SocureDocVHelper + its @objc methods to public, else the .mm
+    # can't see them ("use of undeclared identifier 'SocureDocVHelper'").
+    swift = File.join(socure_ios, 'SocureDocVReactNative.swift')
+    if File.exist?(swift)
+      original = File.read(swift)
+      patched = original
+        .gsub(/^class SocureDocVHelper\b/, 'public class SocureDocVHelper')
+        .gsub(/^(\s*)@objc static func launch\b/, '\1@objc public static func launch')
+      if patched != original
+        File.chmod(0644, swift)
+        File.write(swift, patched)
+        Pod::UI.puts "[socure-docv] Promoted SocureDocVHelper to public for Obj-C interop".green
+      end
+    end
+
+    # Fix 3: provide the module-named header swiftc self-imports; CocoaPods only
+    # makes the dashed `...-umbrella.h`, so point a shim at it.
+    public_headers = File.join(installer.sandbox.root, 'Headers', 'Public', 'socure_docv_react_native')
+    if Dir.exist?(public_headers)
+      shim = File.join(public_headers, 'socure_docv_react_native.h')
+      shim_body = "#import \"socure-docv-react-native-umbrella.h\"\n"
+      if !File.exist?(shim) || File.read(shim) != shim_body
+        File.write(shim, shim_body)
+        Pod::UI.puts "[socure-docv] Added module-named umbrella shim header".green
+      end
+    end
+
+    installer.pods_project.targets.each do |t|
+      if ['fmt', 'glog'].include?(t.name)
+        t.build_configurations.each do |c|
+          defs = c.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || ['$(inherited)']
+          defs = [defs] unless defs.is_a?(Array)
+          defs.delete('FMT_USE_NONTYPE_TEMPLATE_ARGS=0')
+          defs.delete('FMT_CONSTEVAL=')
+          defs << 'FMT_USE_CONSTEVAL=0' unless defs.include?('FMT_USE_CONSTEVAL=0')
+          c.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = defs
+        end
+      end
+    end
   end
 
-pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'
-
+  pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'
 end
 ```
 
@@ -154,7 +261,7 @@ The DocV iOS SDK requires a device's camera permission to capture identity docum
 
 <br />
 
-For the Android app, add your project dependencies by going to the module level `build.gradle` file and making sure the `minSdkVersion` is set to at least 23 and the `compileSdkVersion` is set to at least 32.
+For the Android app, add your project dependencies by going to the module level `build.gradle` file and making sure the `minSdkVersion` is set to at least 23 and the `compileSdkVersion` is set to at least 36.
 
 ```gradle
 buildscript {
@@ -258,71 +365,151 @@ curl --location 'https://service.socure.com/api/5.0/documents/request' \
 
 ## Step 5: Import and launch the SDK
 
-1. Add the following code to your `App.js` file to import `launchSocureDocV`:
+The wrapper exposes two APIs. Use **`launchSocureDocVWithPromise`** for new integrations and any app running React Native 0.79+. Use **`launchSocureDocV`** if your codebase already uses callbacks or you need to support older React Native versions.
+
+### Option A: Promise-based API (recommended)
+
+The Promise-based API is the recommended approach for New Architecture apps. It uses `async/await` and standard JavaScript error handling.
+
+1. Import `launchSocureDocVWithPromise`:
+
+```jsx
+import { launchSocureDocVWithPromise } from "@socure-inc/docv-react-native";
+```
+
+2. Call `launchSocureDocVWithPromise` inside an `async` function:
+
+```jsx
+try {
+  const result = await launchSocureDocVWithPromise(
+    "docVTransactionToken",
+    "SOCURE_SDK_KEY",
+    false // useSocureGov
+  );
+  console.log("Success:", result.deviceSessionToken);
+} catch (error) {
+  console.log("Error code:", error.code);
+  console.log("Error message:", error.message);
+}
+```
+
+#### `launchSocureDocVWithPromise` Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `docVTransactionToken` | String | The transaction token from the [`/documents/request`](https://developer.socure.com/reference#tag/Predictive-Document-Verification) API response. Required to initiate the document verification session. |
+| `publicKey` | String | The unique SDK key from [Admin Dashboard](https://developer.socure.com/docs/admin-dashboard/developers/sdk-keys) used to authenticate the SDK. |
+| `useSocureGov` | Boolean | Set to `true` to use the GovCloud environment. Defaults to `false`. Applicable only to customers provisioned in the SocureGov environment. |
+
+**Returns:** `Promise<DocVResult>` — resolves with `{ deviceSessionToken: string }` on success, or rejects with an error object containing `code` and `message` on failure.
+
+---
+
+### Option B: Callback-based API (legacy)
+
+The callback-based API is preserved for backward compatibility. Existing integrations do not require any code changes.
+
+1. Import `launchSocureDocV`:
 
 ```jsx
-import { launchSocureDocV } from "@socure-inc/docv-react-native"
+import { launchSocureDocV } from "@socure-inc/docv-react-native";
 ```
 
 2. Call `launchSocureDocV` to initiate the Socure DocV SDK:
 
 ```jsx
-launchSocureDocV("docVTransactionToken", "SOCURE_SDK_KEY", userSocureGov, onSuccess, onError);
+launchSocureDocV(
+  "docVTransactionToken",
+  "SOCURE_SDK_KEY",
+  false, // useSocureGov
+  onSuccess,
+  onError
+);
 ```
 
-### `launchSocureDocV` Parameters
+#### `launchSocureDocV` Parameters
 
-The following table lists the parameters for the `launchSocureDocV` function:
+| Parameter | Type | Description |
+|---|---|---|
+| `docVTransactionToken` | String | The transaction token from the [`/documents/request`](https://developer.socure.com/reference#tag/Predictive-Document-Verification) API response. Required to initiate the document verification session. |
+| `publicKey` | String | The unique SDK key from [Admin Dashboard](https://developer.socure.com/docs/admin-dashboard/developers/sdk-keys) used to authenticate the SDK. |
+| `useSocureGov` | Boolean | Set to `true` to use the GovCloud environment. Defaults to `false`. Applicable only to customers provisioned in the SocureGov environment. |
+| `onSuccess` | Function | A callback function invoked when the flow completes successfully. |
+| `onError` | Function | A callback function invoked when the flow fails. |
 
-| Parameter                | Type             | Description                                                                                                                                                             |
-|--------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `SOCURE_SDK_KEY`              | String           | The unique SDK key obtained from [Admin Dashboard](https://developer.socure.com/docs/admin-dashboard/developers/sdk-keys) used to authenticate the SDK.                                            |
-| `DocV_Transaction_Token`   | String           | The transaction token retrieved from the API response of the [`/documents/request`](https://developer.socure.com/reference#tag/Predictive-Document-Verification) endpoint. Required to initiate the document verification session. |
-| `useSocureGov`           | Bool             | A Boolean flag indicating whether to use the GovCloud environment. It defaults to `false`. This is only applicable for customers provisioned in the SocureGov environment. |
-| `onSuccess`           | Function             | A callback function invoked when the flow completes successfully. |
-| `onError`           | Function             | A callback function invoked when the flow fails.                |
+> **New Architecture note:** Under React Native New Architecture, `launchSocureDocV` automatically routes through the TurboModule promise API and bridges the result back to your `onSuccess` / `onError` callbacks. No code changes are required.
 
 ## Step 6: Handle response callbacks
 
-Your app can receive response callbacks from the `launchSocureDocV` function when the flow either completes successfully or returns with an error. The SDK represents these outcomes using the `onSuccess` and `onError` callback functions.
+### Success response
 
-### `onSuccess` response
+When the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers, the SDK returns a `DocVResult` object containing a device session token.
 
-The `onSuccess` callback is triggered when the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers. It returns an object containing a device session token, which can be used for accessing device details about the specific session.
+**Promise API** — the `Promise` resolves with:
 
-```javascript 
-{ 
-  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA' 
+```javascript
+{
+  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
 }
 ```
 
+**Callback API** — the `onSuccess` callback receives the same object:
+
+```javascript
+{
+  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
+}
+```
+
+The `deviceSessionToken` can be used to access device risk details for the specific session.
+
 ### `onError` response
 
-The `onError` callback is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it. It returns a message printed with the `deviceSessionToken` and specific error details.
+The `onError` callback (and Promise rejection) is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it.
 
-```javascript title="Error object example"
-{ 
-  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA',
-  error: 'Scan canceled by the user' 
+**Promise API** — the `Promise` rejects with a JavaScript `Error`-like object. Access `error.code` and `error.message`:
+
+```javascript
+try {
+  const result = await launchSocureDocVWithPromise(token, key, false);
+} catch (error) {
+  console.log(error.code);    // e.g. "ERR_USER_CANCELED"
+  console.log(error.message); // e.g. "Scan canceled by the user"
+}
+```
+
+**Callback API** — the `onError` callback receives an object with the following shape:
+
+```javascript
+{
+  code: 'ERR_USER_CANCELED',
+  error: 'Scan canceled by the user',
+  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
 }
 ```
 
-#### Possible `onError` messages
-
-The following error messages may be returned by the Socure DocV SDK:
-
-| Error Message                                         | Error Description                                                 |
-|-------------------------------------------------------|-------------------------------------------------------------------|
-| `"No internet connection"`                              | No internet connection                     |
-| `"Failed to initiate the session"`                      | Failed to initiate the session             |
-| `"Permissions to open the camera declined by the user"` | Permissions to open the camera declined by the user                                    |
-| `"Consent declined by the user"`                        | Consent declined by the user                              |
-| `"Failed to upload the documents"`                      | Failed to upload the documents |
-| `"Invalid transaction token"`                          | Invalid transaction token           |
-| `"Invalid or missing SDK key"`                          | Invalid or missing SDK key                       |
-| `"Session expired"`                                    | Session expired                         |
-| `"Scan canceled by the user"`                           | Scan canceled by the user                   |
-| `"Unknown error"`                                       | Unknown error                                     |
+> **Migration note:** The `error` field (human-readable message string) is preserved from previous versions. The new `code` field (machine-readable constant) was added in this release to enable reliable programmatic error handling without string matching.
+
+#### Error reference
+
+The following errors may be returned by the Socure DocV SDK:
+
+| `code` | `error` message | Description |
+|---|---|---|
+| `ERR_NO_INTERNET` | `"No internet connection"` | Device has no network connectivity. |
+| `ERR_SESSION_INITIATION` | `"Failed to initiate the session"` | The SDK could not start a verification session with Socure servers. |
+| `ERR_CAMERA_PERMISSION` | `"Permissions to open the camera declined by the user"` | The user denied camera access. |
+| `ERR_CONSENT_DECLINED` | `"Consent declined by the user"` | The user declined the consent screen. |
+| `ERR_UPLOAD_FAILURE` | `"Failed to upload the documents"` | Captured images could not be uploaded. |
+| `ERR_INVALID_TOKEN` | `"Invalid transaction token"` | The `docVTransactionToken` is missing, malformed, or already used. |
+| `ERR_INVALID_KEY` | `"Invalid or missing SDK key"` | The `publicKey` (SDK key) is invalid or was not provided. |
+| `ERR_SESSION_EXPIRED` | `"Session expired"` | The verification session timed out before completion. |
+| `ERR_USER_CANCELED` | `"Scan canceled by the user"` | The user dismissed the capture flow before completing it. |
+| `ERR_NO_ACTIVITY` | `"App activity is null"` | Android only — the host `Activity` was not available when the SDK attempted to launch. |
+| `ERR_NO_DATA` | `"No result data returned from SDK"` | Android only — the SDK activity returned without data. |
+| `ERR_NO_VIEW_CONTROLLER` | `"Failed to get root view controller"` | iOS only — the root `UIViewController` could not be resolved. |
+| `ERR_ALREADY_IN_PROGRESS` | `"A DocV session is already in progress"` | A previous call has not yet resolved. Wait for it to complete before launching again. |
+| `ERR_UNKNOWN` | `"Unknown error"` | An unrecognized error occurred. |
 
 
 

package/android/build.gradle

@@ -15,7 +15,7 @@ buildscript {
 }
 
 def isNewArchitectureEnabled() {
-  return rootProject.hasProperty("newArchEnabled") &&  rootProject.getProperty("newArchEnabled") == "true"
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
 }
 
 apply plugin: 'com.android.library'
@@ -41,6 +41,7 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault('minSdkVersion')
     targetSdkVersion getExtOrIntegerDefault('targetSdkVersion')
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
   }
   buildTypes {
     release {
@@ -57,6 +58,13 @@ android {
     targetCompatibility JavaVersion.VERSION_17
   }
 
+  sourceSets {
+    main {
+      if (!isNewArchitectureEnabled()) {
+        java.srcDirs += ['src/oldarch']
+      }
+    }
+  }
 }
 
 repositories {
@@ -136,7 +144,7 @@ dependencies {
     //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation "com.socure.android:docv-capture:5.4.7"
+  implementation "com.socure.android:docv-capture:5.4.8"
 
   def retrofit_version = "2.9.0"
   implementation "com.squareup.retrofit2:retrofit:$retrofit_version"
@@ -147,7 +155,6 @@ dependencies {
 
   def okhttp_version = "4.9.3"
   implementation "com.squareup.okhttp3:logging-interceptor:$okhttp_version"
-// From node_modules
 }
 
 if (isNewArchitectureEnabled()) {