@circle-fin/w3s-pw-react-native-sdk 1.1.7 → 2.0.1

package/README.md

@@ -1,112 +1,225 @@
-# @circle-fin/w3s-pw-react-native-sdk
-React Native SDK for Circle Programmable Wallet
-## Install NVM
+# Circle User-Controlled Wallets React Native SDK
 
-Install Node Version Manager to use different versions of node and npm easily.
+> SDK for integrating Circle's user-controlled wallet into React Native applications
 
-```bash
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
-```
+> [!IMPORTANT]
+> This SDK supports both Expo and bare React Native projects. Select the appropriate guide based on your project type.
+>
+> - **Bare React Native** (manages native code manually) → Go to [Bare React Native Integration Guide](./BARE_REACT_NATIVE_GUIDE.md)
+> - **Expo project** (uses `expo prebuild` and has `app.json`/`app.config.js`) ↓ Continue below
 
-> **Note:** See [nvm repo](https://github.com/nvm-sh/nvm) for the most updated instruction.
+---
 
-## Authenticate the npm registry
+## Migrating from SDK v1 (Bare React Native)
 
-Create a Personal Access Token in your [GitHub setting](https://github.com/settings/tokens). Use `Configure SSO` button next to your created token to authorize `circlefin` organization. More instruction can be found [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Then, log in to `npm` on your terminal.
+If you have an existing bare React Native project using SDK v1 and want to upgrade to SDK v2, see the [SDK v1 Migration Guide](https://github.com/circlefin/w3s-react-native-sample-app-wallets/blob/master/MIGRATION_GUIDE.md).
 
-```bash
-npm login --scope=@OWNER --registry=https://registry.npmjs.org
+You can also find the SDK v1 sample app in the sample app repository's [sdk-v1 branch](https://github.com/circlefin/w3s-react-native-sample-app-wallets/tree/sdk-v1).
+
+## System Requirements
+
+| Platform     | Minimum Version | Recommended Version |
+| ------------ | --------------- | ------------------- |
+| React Native | 0.60+           | 0.76-0.81           |
+| iOS          | 15.1+           | iOS 17+             |
+| Android      | API 21+         | API 33+             |
+| Expo SDK     | 49+             | 53+                 |
+
+## Installation
+
+> [!IMPORTANT]
+> **Prerequisites**: This SDK uses native modules and requires a [development build](https://docs.expo.dev/develop/development-builds/introduction). Expo Go is not supported.
+
+Follow these steps in order. The SDK will be fully configured after running `expo prebuild`.
+
+#### Step 1: Generate Native Projects (Skip if `android`/`ios` Already Exist)
+
+If you don't have `android/` and `ios/` directories yet, generate them:
+
+```shell
+npx expo prebuild
 ```
-This will ask you to submit your GitHub personal access token as below.
-Check below links for creating GitHub PAT:
-- [Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
-- [Creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
-
-```properties
-npm notice Log in on https://registry.npmjs.org/
-Username: <insert your GitHub username here>
-Password: <insert your GitHub personal access token here>
+
+#### Step 2: Install the SDK Package
+
+```shell
+npx expo install @circle-fin/w3s-pw-react-native-sdk
 ```
-## [Enable the New Architecture]((https://reactnative.dev/docs/new-architecture-app-intro#android---enable-the-new-architecture) )
-The SDK is supporting both React Native old and [new architectures](https://reactnative.dev/docs/the-new-architecture/landing-page).
-You can enable the new architecture by changing the project setting.
-### Android
-Update the `android/gradle.properties` file as follows:
-```properties
-newArchEnabled=true
+
+#### Step 3: Configure app.json
+
+Add both required plugins to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@circle-fin/w3s-pw-react-native-sdk/plugins/withCopyFiles",
+        {
+          "sourceDir": "prebuild-sync-src",
+          "targetDir": ".",
+          "overwrite": true
+        }
+      ],
+      "@circle-fin/w3s-pw-react-native-sdk/plugins/podfile-modifier"
+    ]
+  }
+}
 ```
-### iOS
-Reinstall your pods by running pod install with the right flag:
-```shell
-RCT_NEW_ARCH_ENABLED=1 bundle exec pod install
+
+**What these plugins do:**
+
+- `withCopyFiles`: Preserves your Android/iOS configurations across rebuilds
+- `podfile-modifier`: Automatically configures iOS Podfile for Circle SDK
+
+> [!TIP]
+> Prefer manual setup? Skip `podfile-modifier` and follow the [iOS configuration](./BARE_REACT_NATIVE_GUIDE.md#step-3-configure-ios) in the **Bare React Native Integration Guide** after prebuild.
+
+<details>
+<summary><strong>Learn more about withCopyFiles plugin</strong></summary>
+
+The `withCopyFiles` plugin copies files from a source directory to your native project during prebuild, ensuring custom configurations are preserved.
+
+**Directory structure example:**
+
 ```
-## Installation
-### Using yarn
-```shell
-yarn add @circle-fin/w3s-pw-react-native-sdk
+prebuild-sync-src/
+├── android/
+│   └── build.gradle
+└── ios/
+    └── YourApp/Resources/
+        ├── CirclePWLocalizable.strings
+        └── CirclePWTheme.json
 ```
-### Using npm
-```shell
-npm install @circle-fin/w3s-pw-react-native-sdk
+
+During `expo prebuild`, files from `prebuild-sync-src/android` → `android/` and `prebuild-sync-src/ios` → `ios/`.
+
+**Options:**
+
+| Option      | Default             | Description                                   |
+| ----------- | ------------------- | --------------------------------------------- |
+| `sourceDir` | `prebuild-sync-src` | Root directory with android/ and ios/ folders |
+| `overwrite` | `true`              | Whether to overwrite existing files           |
+
+**Note:** This solves the problem of `expo prebuild --clean` erasing manual changes.
+
+</details>
+
+#### Step 4: Configure Android Repository
+
+> [!NOTE]
+> The SDK depends on `w3s-android-sdk` hosted on GitHub Gradle registry, which requires authentication.
+
+**4.1** Create `.env` in project root with your GitHub credentials:
+
+```bash
+PWSDK_MAVEN_URL=https://maven.pkg.github.com/circlefin/w3s-android-sdk
+PWSDK_MAVEN_USERNAME=<YOUR_GITHUB_USERNAME>
+PWSDK_MAVEN_PASSWORD=<YOUR_GITHUB_PAT>
 ```
-## Link Native Dependencies
-### Android
-Add the maven repository to your `android/build.gradle`. It's suggested that load settings from `local.properties`:
-```properties
+
+Get a [Personal Access Token](https://github.com/settings/tokens) with `read:packages` permission.
+
+**4.2** Add to `android/build.gradle` (project-level) in the `repositories` block:
+
+```gradle
 repositories {
-	...
-	maven {
-        	Properties properties = new Properties()
-		// Load local.properties.
-        	properties.load(new File(rootDir.absolutePath + "/local.properties").newDataInputStream())
-
-		url properties.getProperty('pwsdk.maven.url')
-		credentials {
-        		username properties.getProperty('pwsdk.maven.username')
-        		password properties.getProperty('pwsdk.maven.password')
-		}
-	}
+  // Keep your other repositories here
+  // google()
+  // mavenCentral()
+
+  maven {
+    url System.getenv('PWSDK_MAVEN_URL')
+    credentials {
+      username System.getenv('PWSDK_MAVEN_USERNAME')
+      password System.getenv('PWSDK_MAVEN_PASSWORD')
+    }
+  }
 }
 ```
-Add the maven setting values in `local.properties` file.
-```properties
-pwsdk.maven.url=https://maven.pkg.github.com/circlefin/w3s-android-sdk
-pwsdk.maven.username=<GITHUB_USERNAME>
-# Fine-grained personal access tokens or classic with package write permission.
-pwsdk.maven.password=<GITHUB_PAT>
+
+#### Step 5: Create Sync Directory Structure
+
+Create `prebuild-sync-src/` folder and copy your modified Android files:
+
+```shell
+mkdir -p prebuild-sync-src/android
+cp android/build.gradle prebuild-sync-src/android/
 ```
-### iOS
-Add below links at tne top of `ios/Podfile`:
-```ruby
-source 'https://github.com/circlefin/w3s-ios-sdk.git'
-source 'https://github.com/CocoaPods/Specs.git'
 
-platform :ios, '13.4'
+> [!IMPORTANT]
+> Place all manual Android/iOS changes in `prebuild-sync-src/` to preserve them across rebuilds.
+
+#### Step 6: Generate Native Code
+
+```shell
+npx expo prebuild --clean
 ```
-Declare dynamic link as below:
-```ruby
-target 'W3sSampleWallet' do
-  use_frameworks!
-end
+
+This command generates native directories and applies all configurations automatically.
+
+> [!TIP]
+> **Verify iOS Configuration:** Check if the Circle SDK repository was added correctly:
+>
+> ```shell
+> cat ios/Podfile | grep "circlefin"
+> ```
+>
+> Expected output: `source 'https://github.com/circlefin/w3s-ios-sdk.git'`
+
+#### Step 7: Install iOS Dependencies
+
+```shell
+cd ios && pod install && cd ..
 ```
-And add the following `post_install` hook:
-```ruby
-post_install do |installer|
-  installer.pods_project.targets.each do |target|
-    target.build_configurations.each do |config|
-      config.build_settings["ONLY_ACTIVE_ARCH"] = "NO"
-      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
-      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
-    end
-  end
-end
+
+#### Step 8: Build and Run
+
+**Local development:**
+
+For iOS:
+
+```shell
+npx expo run:ios
 ```
-## Run the Example
-### Android
-```bash
-yarn example android
+
+For Android:
+
+```shell
+npx expo run:android
 ```
-### iOS
-```bash
-yarn example ios
+
+**EAS Build:**
+
+First, install EAS CLI globally (one-time setup):
+
+```shell
+npm install -g eas-cli
+```
+
+Then build your app:
+
+```shell
+eas build --profile development --platform all
 ```
+
+> [!TIP]
+> **EAS Setup**: Add secrets `PWSDK_MAVEN_USERNAME` and `PWSDK_MAVEN_PASSWORD` to your EAS project. [Learn more](https://docs.expo.dev/build-reference/variables/)
+
+---
+
+## Additional Resources
+
+**Circle Resources:**
+
+- [User-Controlled Wallets Documentation](https://developers.circle.com/wallets/user-controlled) - Product overview and architecture
+- [React Native SDK Documentation](https://developers.circle.com/wallets/user-controlled/react-native-sdk) - Complete API reference
+- [UI Customization API](https://developers.circle.com/wallets/user-controlled/react-native-sdk-ui-customization-api) - Theming and localization options
+- [React Native Sample App](https://github.com/circlefin/w3s-react-native-sample-app-wallets) - Working Expo sample app with integration guide
+- [SDK v1 Migration Guide](https://github.com/circlefin/w3s-react-native-sample-app-wallets/blob/master/MIGRATION_GUIDE.md) - Complete guide for upgrading from bare React Native + SDK v1 to Expo Modules + SDK v2
+
+**Expo Resources:**
+
+- [Expo Development Build](https://docs.expo.dev/development/build/)
+- [EAS Build](https://docs.expo.dev/build/introduction/)

package/android/build.gradle

@@ -1,139 +1,56 @@
-// Copyright (c) 2024, Circle Internet Financial, LTD. All rights reserved.
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-// 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.
-
-buildscript {
-  // Buildscript is evaluated before everything else so we can't use getExtOrDefault
-  def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : project.properties["ProgrammablewalletRnSdk_kotlinVersion"]
-
-  repositories {
-    google()
-    mavenCentral()
+apply plugin: 'com.android.library'
+
+import groovy.json.JsonSlurper
+
+def getPackageJsonVersion() {
+    def packageJsonFile = file("${projectDir}/../package.json")
+    def packageJson = new JsonSlurper().parseText(packageJsonFile.text)
+    return packageJson.version
+}
+
+group = 'com.circlefin.programmablewalletrnsdk'
+version = getPackageJsonVersion()
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+// If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
+// The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
+// Most of the time, you may like to manage the Android SDK versions yourself.
+def useManagedAndroidSdkVersions = false
+if (useManagedAndroidSdkVersions) {
+  useDefaultAndroidSdkVersions()
+} else {
+  buildscript {
+    // Simple helper that allows the root project to override versions declared by this library.
+    ext.safeExtGet = { prop, fallback ->
+      rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+    }
   }
-
-  dependencies {
-    classpath "com.android.tools.build:gradle:8.5.0"
-    // noinspection DifferentKotlinGradleVersion
-    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+  project.android {
+    compileSdkVersion safeExtGet("compileSdkVersion", 34)
+    defaultConfig {
+      minSdkVersion safeExtGet("minSdkVersion", 21)
+      targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    }
   }
 }
 
-def isNewArchitectureEnabled() {
-  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-if (isNewArchitectureEnabled()) {
-  apply plugin: "com.facebook.react"
-}
-
-def getExtOrDefault(name) {
-  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["ProgrammablewalletRnSdk_" + name]
-}
-
-def getExtOrIntegerDefault(name) {
-  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ProgrammablewalletRnSdk_" + name]).toInteger()
-}
-
-def supportsNamespace() {
-  def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
-  def major = parsed[0].toInteger()
-  def minor = parsed[1].toInteger()
-
-  // Namespace support was added in 7.3.0
-  return (major == 7 && minor >= 3) || major >= 8
-}
-
 android {
-  if (supportsNamespace()) {
-    namespace "com.circlefin.programmablewalletrnsdk"
-
-    sourceSets {
-      main {
-        manifest.srcFile "src/main/AndroidManifestNew.xml"
-      }
-    }
-  }
-
-  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
-
+  namespace "com.circlefin.programmablewalletrnsdk"
   defaultConfig {
-    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
-    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
-    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
-    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
-  }
-
-  buildFeatures {
-    buildConfig true
+    versionCode 1
+    versionName getPackageJsonVersion()
   }
-
-  buildTypes {
-    release {
-      minifyEnabled false
-    }
-    debug {
-      testCoverageEnabled false
-    }
-  }
-
   lintOptions {
-    disable "GradleCompatible"
+    abortOnError false
   }
-
-  compileOptions {
-    sourceCompatibility JavaVersion.VERSION_11
-    targetCompatibility JavaVersion.VERSION_11
-  }
-  sourceSets {
-    main {
-      if (isNewArchitectureEnabled()) {
-        java.srcDirs += [
-          "src/newarch",
-          // This is needed to build Kotlin project with NewArch enabled
-          "${project.buildDir}/generated/source/codegen/java"
-        ]
-      } else {
-        java.srcDirs += ["src/oldarch"]
-      }
-    }
-  }
-}
-repositories {
-  mavenCentral()
-  google()
 }
 
-def kotlin_version = getExtOrDefault("kotlinVersion")
-
 dependencies {
-  // For < 0.71, this will be from the local maven repo
-  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
-  //noinspection GradleDynamicVersion
-  implementation "com.facebook.react:react-native:+"
-  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation "circle.programmablewallet:sdk:1.0.1102"
-  implementation 'com.github.bumptech.glide:glide:4.14.2'
-}
-
-if (isNewArchitectureEnabled()) {
-  react {
-    jsRootDir = file("../src/")
-    libraryName = "ProgrammablewalletRnSdk"
-    codegenJavaPackageName = "com.circlefin.programmablewalletrnsdk"
-  }
+  implementation("circle.programmablewallet:sdk:1.0.1102")
+  implementation("com.github.bumptech.glide:glide:4.16.0")
 }

package/android/src/main/AndroidManifest.xml

@@ -1,23 +1,19 @@
 <!--
-Copyright (c) 2024, Circle Internet Financial, LTD. All rights reserved.
+ Copyright 2025 Circle Internet Group, Inc. All rights reserved.
 
-SPDX-License-Identifier: Apache-2.0
+ SPDX-License-Identifier: Apache-2.0
 
-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
+ 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
+     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.
+ 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.
 -->
-
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-  package="com.circlefin.programmablewalletrnsdk">
-
-  <uses-permission android:name="android.permission.REORDER_TASKS" />
+<manifest>
 </manifest>