feat(RN): Add wiring for protocol events - add ec.start (#170)

### What changes are you making?

Part of the scope of this PR is to add a translation layer between the the core native SDKs and the React native JavaScript runtime. 
The models that are generated for Swift and Kotlin automatically camel case at their encode decode boundary, which means the raw json is read as snake case and the Swift and Kotlin properties are then turned into camel case when they are turned back into raw json, they're back in snake_case. 

QuickType now generates some functions we can use to convert between the raw snake_case and camelCase 


### How to test

<!-- Please outline the steps to test your changes -->

---

### Before you merge

> [!IMPORTANT]
>
> - [ ] I've added tests to support my implementation
> - [ ] I have read and agree with the [Contribution Guidelines](./CONTRIBUTING.md)
> - [ ] I have read and agree with the [Code of Conduct](./CODE_OF_CONDUCT.md)
> - [ ] I've updated the relevant platform README (`platforms/swift/README.md` and/or `platforms/android/README.md`)

---

<details>
<summary>Releasing a new Swift version?</summary>

- [ ] I have bumped the version in `ShopifyCheckoutKit.podspec`
- [ ] I have bumped the version in `platforms/swift/Sources/ShopifyCheckoutKit/ShopifyCheckoutKit.swift`
- [ ] I have updated `platforms/swift/CHANGELOG.md`
- [ ] I have updated the SwiftPM/CocoaPods version snippets in `platforms/swift/README.md` (major version only)

</details>

<details>
<summary>Releasing a new Android version?</summary>

- [ ] I have bumped the `versionName` in `platforms/android/lib/build.gradle`
- [ ] I have updated `platforms/android/CHANGELOG.md`
- [ ] I have updated the Gradle/Maven version snippets in `platforms/android/README.md`

</details>

> [!TIP]
> See the [Contributing documentation](./CONTRIBUTING.md) for the full release process per platform.

Author: kieran-osgood-shopify

.gitignore

@@ -31,6 +31,7 @@ apollo-ios-cli
 
 # Android / Gradle
 .gradle/
+.kotlin/
 build/
 captures/
 .externalNativeBuild

AGENTS.md

@@ -9,3 +9,56 @@ protocol/        # cross-platform communication layer based on UCP
 e2e/             # cross-platform end-to-end tests
 .github/         # workflows, issue templates, CODEOWNERS
 ```
+
+## React Native development with local native SDK changes
+
+Until the new native SDK libraries have stable released versions, assume React Native validation needs the local native SDK workflow. Use `--local` whenever running the React Native sample or native React Native tests that depend on the in-repo Swift/Kotlin SDKs.
+
+Use the React Native `--local` workflow when you need to test React Native against native SDK changes that exist in this repository but have not been released as a SemVer/CocoaPods/Maven version yet.
+
+This applies when changes are made under:
+
+- `platforms/swift/` — the iOS Swift SDK / CocoaPods sources
+- `platforms/android/` — the Android SDK / Maven artifact sources
+
+It does **not** refer to the React Native wrapper platform folders:
+
+- `platforms/react-native/modules/@shopify/checkout-kit-react-native/ios/`
+- `platforms/react-native/modules/@shopify/checkout-kit-react-native/android/`
+
+### What `--local` does
+
+- For React Native iOS, `--local` wires CocoaPods to the in-repo `platforms/swift/` sources via a local path instead of a released pod version.
+- For React Native Android, `--local` publishes/uses the in-repo `platforms/android/` SDK through Maven Local so Gradle resolves the local SDK artifact instead of a released Maven version.
+
+### When to use it
+
+Use `--local` whenever you are validating React Native behavior that depends on unreleased native SDK changes, for example:
+
+- a new Swift SDK API that the React Native iOS bridge calls
+- a new Android SDK API that the React Native Android bridge calls
+- generated protocol/model changes under the native SDKs that the React Native module consumes
+- any change in `platforms/swift/` or `platforms/android/` that has not yet been released and consumed through normal dependency versions
+
+Re-run the relevant local workflow whenever `platforms/swift/` or `platforms/android/` changes, because the React Native sample/tests need to re-resolve those local native SDK sources/artifacts.
+
+```bash
+# iOS sample using local platforms/swift sources
+dev rn ios --local
+
+# Android sample using local platforms/android via Maven Local
+dev rn android --local
+
+# React Native Android unit tests using local platforms/android via Maven Local
+# `dev rn test android` publishes platforms/android/lib to ~/.m2 first, then runs the RN module tests.
+dev rn test android
+```
+
+For ad-hoc Android Gradle test commands, publish the local Android SDK first and set `USE_LOCAL_SDK=1` so the React Native module resolves `com.shopify:checkout-kit:1.0.0` from Maven Local instead of the unreleased placeholder artifact:
+
+```bash
+cd platforms/react-native
+USE_LOCAL_SDK=1 ./scripts/publish_android_snapshot
+cd sample/android
+USE_LOCAL_SDK=1 ./gradlew :shopify_checkout-kit-react-native:testDebugUnitTest
+```

dev.yml

@@ -276,6 +276,35 @@ commands:
       build:
         desc: Build the @shopify/checkout-kit-react-native module
         run: cd platforms/react-native && pnpm module build
+      test:
+        desc: Run React Native module tests (JS + iOS + Android)
+        long_desc: |
+          Runs unit tests across all three React Native targets:
+            - JS:      Jest tests in `platforms/react-native/modules/@shopify/checkout-kit-react-native/tests/`
+            - iOS:     Swift Package tests at `platforms/react-native/modules/@shopify/checkout-kit-react-native/ios/`
+            - Android: Gradle JVM tests for `:shopify_checkout-kit-react-native` (requires a local Maven publish of `:lib`)
+        run: |
+          set -e
+          cd platforms/react-native && pnpm test
+          cd modules/@shopify/checkout-kit-react-native/ios && swift test
+          cd ../../../../
+          USE_LOCAL_SDK=1 ./scripts/publish_android_snapshot
+          cd sample/android && USE_LOCAL_SDK=1 ./gradlew :shopify_checkout-kit-react-native:test
+        subcommands:
+          js:
+            desc: Run JS unit tests via jest
+            run: cd platforms/react-native && pnpm test
+          ios:
+            desc: Run native iOS unit tests (Swift Package at modules/.../ios)
+            run: cd platforms/react-native/modules/@shopify/checkout-kit-react-native/ios && swift test
+          android:
+            desc: Run native Android unit tests for the RN module (publishes/uses local platforms/android SDK)
+            run: |
+              set -e
+              cd platforms/react-native
+              USE_LOCAL_SDK=1 ./scripts/publish_android_snapshot
+              cd sample/android
+              USE_LOCAL_SDK=1 ./gradlew :shopify_checkout-kit-react-native:test
       lint:
         desc: Run all React Native lint checks (Swift, module, sample)
         aliases: [style]

platforms/react-native/README.md

@@ -621,11 +621,6 @@ shopify.present(checkoutUrl, {
 `onClose` and `onFail` are mutually exclusive — exactly one of them fires
 per `present(...)` call, after which both handles are released.
 
-> Protocol-level callbacks (`start`, `complete`, `error` on the protocol
-> client) are not part of this section and will land in a follow-up release
-> alongside a `<CheckoutSheet>` component. Checkout completion is not
-> currently surfaced through the per-call callbacks.
-
 ## Identity & customer accounts
 
 Buyer-aware checkout experience reduces friction and increases conversion.

platforms/react-native/__mocks__/react-native.ts

@@ -49,13 +49,17 @@ const exampleConfig = {
   colorScheme: 'automatic',
   logLevel: 'error',
 };
+const shopifyCheckoutKitEventEmitter = createMockEmitter();
 
 const ShopifyCheckoutKit = {
   version: '0.7.0',
   getConstants: jest.fn(() => ({
     version: '0.7.0',
     dispatchEventTypes: ['close', 'fail', 'geolocationRequest'],
   })),
+  onDispatch: jest.fn((callback: (envelopeJson: string) => void) =>
+    shopifyCheckoutKitEventEmitter.addListener('onDispatch', callback),
+  ),
   preload: jest.fn(),
   present: jest.fn(),
   dismiss: jest.fn(),
@@ -76,7 +80,7 @@ module.exports = {
   PermissionsAndroid: {
     requestMultiple: jest.fn(async () => ({})),
   },
-  NativeEventEmitter: jest.fn(() => createMockEmitter()),
+  NativeEventEmitter: jest.fn(() => shopifyCheckoutKitEventEmitter),
   requireNativeComponent,
   codegenNativeComponent,
   TurboModuleRegistry: {
@@ -90,7 +94,7 @@ module.exports = {
   NativeModules: {
     ShopifyCheckoutKit: {
       ...ShopifyCheckoutKit,
-      eventEmitter: createMockEmitter(),
+      eventEmitter: shopifyCheckoutKitEventEmitter,
     },
   },
   StyleSheet,

platforms/react-native/jest.config.js

@@ -1,7 +1,7 @@
 module.exports = {
   preset: 'react-native',
   modulePathIgnorePatterns: ['modules/@shopify/checkout-kit-react-native/lib'],
-  modulePaths: ['<rootDir>/sample/node_modules'],
+  modulePaths: ['<rootDir>/node_modules', '<rootDir>/sample/node_modules'],
   setupFiles: ['<rootDir>/jest.setup.ts'],
   transform: {
     '\\.[jt]sx?$': 'babel-jest',

platforms/react-native/metro.config.js

@@ -3,6 +3,7 @@ const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
 
 const root = path.resolve(__dirname);
 const sample = path.resolve(root, 'sample');
+const protocol = path.resolve(root, '../../protocol/languages/typescript');
 
 /**
  * Metro configuration
@@ -13,7 +14,7 @@ const sample = path.resolve(root, 'sample');
 const config = mergeConfig(getDefaultConfig(__dirname), {
   projectRoot: sample,
 
-  watchFolders: [root],
+  watchFolders: [root, protocol],
 
   resolver: {
     resolveRequest: (context, moduleName, platform) => {
@@ -46,6 +47,8 @@ const config = mergeConfig(getDefaultConfig(__dirname), {
         'modules',
         '@shopify/checkout-kit-react-native',
       ),
+      '@shopify/checkout-kit-protocol': protocol,
+      '@babel/runtime': path.resolve(root, 'node_modules', '@babel/runtime'),
     },
   },
 

platforms/react-native/modules/@shopify/checkout-kit-react-native/RNShopifyCheckoutKit.podspec

@@ -14,6 +14,11 @@ Pod::Spec.new do |s|
   s.source       = { :git => "https://github.com/Shopify/checkout-kit.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/*.{h,m,mm,swift}"
+  # `ios/Package.swift` is the manifest for the nested SwiftPM test package
+  # (ProtocolRelay unit tests). It imports `PackageDescription` which only
+  # exists in the SwiftPM toolchain, so it must not be compiled by
+  # CocoaPods/Xcode when the RN module is consumed from an iOS app.
+  s.exclude_files = "ios/Package.swift"
 
   s.dependency "React-Core"
 

platforms/react-native/modules/@shopify/checkout-kit-react-native/android/build.gradle

@@ -1,16 +1,22 @@
 buildscript {
+  ext.kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "2.1.20"
+
   repositories {
     google()
     mavenCentral()
   }
 
   dependencies {
     classpath "com.android.tools.build:gradle:8.11.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
   }
 }
 
 apply plugin: "com.android.library"
 apply plugin: "com.facebook.react"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "org.jetbrains.kotlin.plugin.serialization"
 
 def getExtOrIntegerDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties[name]).toInteger()
@@ -73,8 +79,17 @@ android {
     sourceCompatibility JavaVersion.VERSION_1_8
     targetCompatibility JavaVersion.VERSION_1_8
   }
+
+  kotlinOptions {
+    jvmTarget = "1.8"
+  }
+
+  testOptions {
+    unitTests.includeAndroidResources = true
+  }
 }
 
+
 repositories {
   mavenLocal()
   mavenCentral()
@@ -97,5 +112,10 @@ dependencies {
 
   implementation(shopifySdkArtifact)
   implementation("com.fasterxml.jackson.core:jackson-databind:2.12.5")
+  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
   debugImplementation(shopifySdkArtifact)
+
+  testImplementation "junit:junit:4.13.2"
+  testImplementation "org.assertj:assertj-core:3.27.7"
+  testImplementation "org.robolectric:robolectric:4.16.1"
 }

platforms/react-native/modules/@shopify/checkout-kit-react-native/android/gradle.properties

@@ -3,3 +3,8 @@ targetSdkVersion=35
 compileSdkVersion=36
 ndkVersion=23.1.7779620
 buildToolsVersion = "35.0.0"
+
+# Opt out of the React Native Gradle plugin's JdkConfiguratorUtils, which otherwise
+# silently rewrites compileOptions to 17 and pins the Kotlin JVM toolchain to 17 for
+# every com.android.library it sees. We mirror :lib's pinned JVM 1.8 contract instead.
+react.internal.disableJavaVersionAlignment=true