feat: add first protocol event

Author: kieran-osgood-shopify

.gitignore

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

AGENTS.md

@@ -9,3 +9,41 @@ 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
+
+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 needs 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
+```

dev.yml

@@ -267,6 +267,28 @@ 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 ../../../../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 (uses local Maven publish of :lib)
+            run: cd platforms/react-native/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

@@ -615,10 +615,16 @@ 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.
+> [!IMPORTANT]
+> `present(...)` supports one active checkout presentation at a time. Starting
+> another presentation while a checkout sheet is already active is unsupported;
+> callbacks and protocol handlers are scoped to the currently active
+> presentation. For multiple inline checkout surfaces, use component-scoped APIs
+> where available.
+
+> Protocol-level callbacks are configured separately from these SDK lifecycle
+> callbacks. Checkout completion is not currently surfaced through the per-call
+> SDK lifecycle callbacks.
 
 ## Identity & customer accounts
 

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/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
+  # (CasingTransform / 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,6 +112,11 @@ 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

platforms/react-native/modules/@shopify/checkout-kit-react-native/android/src/main/java/com/shopify/reactnative/checkoutkit/CasingTransform.kt

@@ -0,0 +1,89 @@
+/*
+ * MIT License
+ *
+ * Copyright 2023-present, Shopify Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.shopify.reactnative.checkoutkit
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.decodeFromJsonElement
+import kotlinx.serialization.json.encodeToJsonElement
+
+/**
+ * Bridges typed snake_case payloads (per @SerialName annotations on the native models)
+ * with camelCase JSON expected by JavaScript consumers.
+ */
+internal object CasingTransform {
+
+    private const val CAMEL_TO_SNAKE_BUFFER_PADDING: Int = 4
+
+    internal val json: Json = Json { ignoreUnknownKeys = true }
+
+    fun snakeToCamel(s: String): String {
+        if (s.isEmpty() || !s.contains('_')) return s
+        val builder = StringBuilder(s.length)
+        var upperNext = false
+        for (ch in s) {
+            if (ch == '_') {
+                upperNext = true
+            } else if (upperNext) {
+                builder.append(ch.uppercaseChar())
+                upperNext = false
+            } else {
+                builder.append(ch)
+            }
+        }
+        return builder.toString()
+    }
+
+    fun camelToSnake(s: String): String {
+        if (s.isEmpty()) return s
+        val builder = StringBuilder(s.length + CAMEL_TO_SNAKE_BUFFER_PADDING)
+        for (ch in s) {
+            if (ch.isUpperCase()) {
+                builder.append('_').append(ch.lowercaseChar())
+            } else {
+                builder.append(ch)
+            }
+        }
+        return builder.toString()
+    }
+
+    fun transformKeys(element: JsonElement, fn: (String) -> String): JsonElement = when (element) {
+        is JsonObject -> JsonObject(element.entries.associate { (key, value) -> fn(key) to transformKeys(value, fn) })
+        is JsonArray -> JsonArray(element.map { transformKeys(it, fn) })
+        else -> element
+    }
+
+    inline fun <reified T> encodeForJS(payload: T): String {
+        val element = json.encodeToJsonElement(payload)
+        val transformed = transformKeys(element, ::snakeToCamel)
+        return json.encodeToString(JsonElement.serializer(), transformed)
+    }
+
+    inline fun <reified T> decodeFromJS(json: String): T {
+        val element = Json.parseToJsonElement(json)
+        val transformed = transformKeys(element, ::camelToSnake)
+        return CasingTransform.json.decodeFromJsonElement(transformed)
+    }
+}

platforms/react-native/modules/@shopify/checkout-kit-react-native/android/src/main/java/com/shopify/reactnative/checkoutkit/CustomCheckoutListener.java

@@ -30,7 +30,6 @@ of this software and associated documentation files (the "Software"), to deal
 import androidx.annotation.Nullable;
 
 import com.shopify.checkoutkit.*;
-import com.facebook.react.bridge.Callback;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.io.IOException;
@@ -42,16 +41,19 @@ public class CustomCheckoutListener extends DefaultCheckoutListener {
 
   private final ObjectMapper mapper = new ObjectMapper();
 
-  @Nullable
-  private Callback dispatchCallback;
+  private final DispatchHandle dispatch;
 
   // Geolocation-specific variables
 
   private String geolocationOrigin;
   private GeolocationPermissions.Callback geolocationCallback;
 
-  public CustomCheckoutListener(@Nullable Callback dispatch) {
-    this.dispatchCallback = dispatch;
+  public CustomCheckoutListener(@NonNull DispatchCallback dispatch) {
+    this(new DispatchHandle(dispatch));
+  }
+
+  public CustomCheckoutListener(@NonNull DispatchHandle dispatch) {
+    this.dispatch = dispatch;
   }
 
   // Public methods
@@ -65,7 +67,7 @@ public void invokeGeolocationCallback(boolean allow) {
   }
 
   public void release() {
-    dispatchCallback = null;
+    dispatch.release();
     geolocationCallback = null;
     geolocationOrigin = null;
   }
@@ -86,20 +88,21 @@ public void release() {
   public void onGeolocationPermissionsShowPrompt(@NonNull String origin,
       @NonNull GeolocationPermissions.Callback callback) {
 
-    this.geolocationCallback = callback;
-    this.geolocationOrigin = origin;
-
-    if (dispatchCallback == null) {
+    if (dispatch.isReleased()) {
       // Multi-shot geolocation requests can in principle arrive after a
-      // terminal event has nulled the dispatcher. Log so the silence is
-      // observable rather than mystifying.
-      Log.w(TAG, "Dropping geolocationRequest \u2014 dispatcher already released by a terminal event.");
+      // terminal event or explicit dismiss has released the dispatcher. Log
+      // so the silence is observable rather than mystifying.
+      Log.w(TAG, "Dropping geolocationRequest — dispatcher already released.");
       return;
     }
+
+    this.geolocationCallback = callback;
+    this.geolocationOrigin = origin;
+
     try {
       Map<String, Object> payload = new HashMap<>();
       payload.put("origin", origin);
-      dispatchCallback.invoke(buildEnvelope(DispatchEventTypes.GEOLOCATION_REQUEST, payload));
+      dispatch.invoke(buildEnvelope(DispatchEventTypes.GEOLOCATION_REQUEST, payload));
     } catch (IOException e) {
       Log.e(TAG, "Error emitting \"geolocationRequest\" event", e);
     }
@@ -115,9 +118,7 @@ public void onGeolocationPermissionsHidePrompt() {
 
   @Override
   public void onCheckoutFailed(CheckoutException checkoutError) {
-    Callback dispatch = dispatchCallback;
-    if (dispatch == null) {
-      release();
+    if (dispatch.isReleased()) {
       return;
     }
     try {
@@ -131,9 +132,7 @@ public void onCheckoutFailed(CheckoutException checkoutError) {
 
   @Override
   public void onCheckoutCanceled() {
-    Callback dispatch = dispatchCallback;
-    if (dispatch == null) {
-      release();
+    if (dispatch.isReleased()) {
       return;
     }
     try {