feat(rn): tighten dispatcher with parity check, payload validation, and loud unknown-type warning

- Centralise SDK lifecycle event names in a single source of truth per
  language: src/dispatch-events.ts (TS), DispatchEventTypes (Java),
  DispatchEventType enum (Swift). Native emits envelopes using these
  constants instead of free string literals.
- Expose the native list via getConstants(); JS verifies set-equality
  in the ShopifyCheckout constructor and throws DispatchEventParityError
  with a 'rebuild native code' message on mismatch (memoised per process).
- Per-case payload validation in the dispatcher: malformed 'fail' or
  'geolocationRequest' payloads now log a LifecycleEventParseError
  instead of feeding undefined into user code.
- Unknown envelope types now console.warn instead of silently routing
  to a missing handler, surfacing native/JS contract drift that slips
  past the parity check.
- Drop dead code: sendEventWithStringData, unused Context param and
  reactContext field on CustomCheckoutListener; unused mockContext in
  the Android test.
- Log warning instead of silent return when a multi-shot geolocation
  prompt arrives after the dispatcher has been released by a terminal
  event.

Author: kieran-osgood-shopify

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

@@ -49,7 +49,10 @@ const exampleConfig = {preloading: true};
 
 const ShopifyCheckoutKit = {
   version: '0.7.0',
-  getConstants: jest.fn(() => ({version: '0.7.0'})),
+  getConstants: jest.fn(() => ({
+    version: '0.7.0',
+    dispatchEventTypes: ['close', 'fail', 'geolocationRequest'],
+  })),
   preload: jest.fn(),
   present: jest.fn(),
   dismiss: jest.fn(),

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

@@ -23,7 +23,6 @@ of this software and associated documentation files (the "Software"), to deal
 
 package com.shopify.reactnative.checkoutkit;
 
-import android.content.Context;
 import android.util.Log;
 import android.webkit.GeolocationPermissions;
 
@@ -32,16 +31,15 @@ of this software and associated documentation files (the "Software"), to deal
 
 import com.shopify.checkoutkit.*;
 import com.facebook.react.bridge.Callback;
-import com.facebook.react.modules.core.DeviceEventManagerModule;
-import com.facebook.react.bridge.ReactApplicationContext;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.Map;
 
 public class CustomCheckoutListener extends DefaultCheckoutListener {
-  private final ReactApplicationContext reactContext;
+  private static final String TAG = "ShopifyCheckoutKit";
+
   private final ObjectMapper mapper = new ObjectMapper();
 
   @Nullable
@@ -52,9 +50,7 @@ public class CustomCheckoutListener extends DefaultCheckoutListener {
   private String geolocationOrigin;
   private GeolocationPermissions.Callback geolocationCallback;
 
-  public CustomCheckoutListener(Context context, ReactApplicationContext reactContext,
-      @Nullable Callback dispatch) {
-    this.reactContext = reactContext;
+  public CustomCheckoutListener(@Nullable Callback dispatch) {
     this.dispatchCallback = dispatch;
   }
 
@@ -88,14 +84,18 @@ public void onGeolocationPermissionsShowPrompt(@NonNull String origin,
     this.geolocationOrigin = origin;
 
     if (dispatchCallback == null) {
+      // 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.");
       return;
     }
     try {
       Map<String, Object> payload = new HashMap<>();
       payload.put("origin", origin);
-      dispatchCallback.invoke(buildEnvelope("geolocationRequest", payload));
+      dispatchCallback.invoke(buildEnvelope(DispatchEventTypes.GEOLOCATION_REQUEST, payload));
     } catch (IOException e) {
-      Log.e("ShopifyCheckoutKit", "Error emitting \"geolocationRequest\" event", e);
+      Log.e(TAG, "Error emitting \"geolocationRequest\" event", e);
     }
   }
 
@@ -113,9 +113,9 @@ public void onCheckoutFailed(CheckoutException checkoutError) {
       return;
     }
     try {
-      dispatchCallback.invoke(buildEnvelope("fail", populateErrorDetails(checkoutError)));
+      dispatchCallback.invoke(buildEnvelope(DispatchEventTypes.FAIL, populateErrorDetails(checkoutError)));
     } catch (IOException e) {
-      Log.e("ShopifyCheckoutKit", "Error processing checkout failed event", e);
+      Log.e(TAG, "Error processing checkout failed event", e);
     } finally {
       dispatchCallback = null;
     }
@@ -127,9 +127,9 @@ public void onCheckoutCanceled() {
       return;
     }
     try {
-      dispatchCallback.invoke(buildEnvelope("close", null));
+      dispatchCallback.invoke(buildEnvelope(DispatchEventTypes.CLOSE, null));
     } catch (IOException e) {
-      Log.e("ShopifyCheckoutKit", "Error processing checkout canceled event", e);
+      Log.e(TAG, "Error processing checkout canceled event", e);
     } finally {
       dispatchCallback = null;
     }
@@ -176,9 +176,4 @@ private String getErrorTypeName(CheckoutException error) {
     }
   }
 
-  private void sendEventWithStringData(String name, String data) {
-    reactContext
-        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
-        .emit(name, data);
-  }
 }

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

@@ -0,0 +1,49 @@
+/*
+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 java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Canonical list of SDK lifecycle event types emitted by the
+ * per-{@code present()} dispatcher.
+ *
+ * Mirrors {@code SDK_LIFECYCLE_EVENT_TYPES} in the JS package and
+ * {@code DispatchEventType} on iOS. Exposed to JS via
+ * {@code getTypedExportedConstants()} so the JS layer can verify the
+ * two sides agree at construction time.
+ */
+public final class DispatchEventTypes {
+  public static final String CLOSE = "close";
+  public static final String FAIL = "fail";
+  public static final String GEOLOCATION_REQUEST = "geolocationRequest";
+
+  public static final List<String> ALL = Collections.unmodifiableList(
+      Arrays.asList(CLOSE, FAIL, GEOLOCATION_REQUEST));
+
+  private DispatchEventTypes() {}
+}

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

@@ -68,6 +68,9 @@ public ShopifyCheckoutKitModule(ReactApplicationContext reactContext) {
   protected Map<String, Object> getTypedExportedConstants() {
     final Map<String, Object> constants = new HashMap<>();
     constants.put("version", ShopifyCheckoutKit.version);
+    // Exposed so the JS layer can verify the SDK lifecycle event set
+    // it was built against matches what this native module emits.
+    constants.put("dispatchEventTypes", DispatchEventTypes.ALL);
     return constants;
   }
 
@@ -85,7 +88,7 @@ public void removeListeners(double count) {
   public void present(String checkoutURL, @Nullable Callback dispatch) {
     Activity currentActivity = getCurrentActivity();
     if (currentActivity instanceof ComponentActivity) {
-      checkoutListener = new CustomCheckoutListener(currentActivity, this.reactContext, dispatch);
+      checkoutListener = new CustomCheckoutListener(dispatch);
       currentActivity.runOnUiThread(() -> {
         checkoutSheet = ShopifyCheckoutKit.present(checkoutURL, (ComponentActivity) currentActivity,
             checkoutListener);

platforms/react-native/modules/@shopify/checkout-kit-react-native/ios/ShopifyCheckoutKit.swift

@@ -28,16 +28,31 @@ import ShopifyCheckoutKit
 import SwiftUI
 import UIKit
 
+/// Canonical list of SDK lifecycle event types emitted by the
+/// per-`present()` dispatcher.
+///
+/// Mirrors `SDK_LIFECYCLE_EVENT_TYPES` in the JS package and
+/// `DispatchEventTypes` on Android. Exposed to JS via
+/// `constantsToExport()` so the JS layer can verify the two sides
+/// agree at construction time.
+enum DispatchEventType: String, CaseIterable {
+    case close
+    case fail
+    case geolocationRequest
+}
+
 @objc(RCTShopifyCheckoutKit)
 class RCTShopifyCheckoutKit: NSObject {
     internal var checkoutSheet: UIViewController?
     private var acceleratedCheckoutsConfiguration: Any?
     private var acceleratedCheckoutsApplePayConfiguration: Any?
     private var defaultLogLevel: LogLevel = .error
 
-    // TODO: invoke once the iOS CheckoutDelegate (or equivalent) lands upstream — until then,
-    // the dispatcher is stored but never fired (Android is the only platform delivering events).
-    // When wired, dispatch envelope JSON strings of the shape `{"type":"close"|"fail","payload":...}`.
+    /// Per-call dispatcher passed in from JS. Holds onto an
+    /// `RCTResponseSenderBlock` for the duration of one `present()` call;
+    /// nulled on the first terminal SDK lifecycle event so a single
+    /// presentation can only ever fire `close` or `fail` once. Matches
+    /// the Android `CustomCheckoutListener.dispatchCallback` lifecycle.
     private var pendingDispatchCallback: RCTResponseSenderBlock?
 
     @objc var methodQueue: DispatchQueue {
@@ -58,7 +73,10 @@ class RCTShopifyCheckoutKit: NSObject {
 
     @objc func constantsToExport() -> [AnyHashable: Any]! {
         return [
-            "version": ShopifyCheckoutKit.version
+            "version": ShopifyCheckoutKit.version,
+            // Surfaced so the JS layer can verify the SDK lifecycle event set
+            // it was built against matches what this native module emits.
+            "dispatchEventTypes": DispatchEventType.allCases.map { $0.rawValue }
         ]
     }
 
@@ -107,7 +125,7 @@ class RCTShopifyCheckoutKit: NSObject {
 
         DispatchQueue.main.async {
             if let url = URL(string: checkoutURL), let viewController = self.getCurrentViewController() {
-                let view = CheckoutViewController(checkout: url)
+                let view = CheckoutViewController(checkout: url, delegate: self)
                 viewController.present(view, animated: true)
                 self.checkoutSheet = view
             }
@@ -278,3 +296,102 @@ class RCTShopifyCheckoutKit: NSObject {
         }
     }
 }
+
+// MARK: - CheckoutDelegate
+
+extension RCTShopifyCheckoutKit: CheckoutDelegate {
+    /// Fired by the iOS SDK when the buyer dismisses the checkout sheet
+    /// without a terminal error. Mirrors
+    /// `CustomCheckoutListener.onCheckoutCanceled()` on Android.
+    func checkoutDidCancel() {
+        emitDispatchEnvelope(type: .close, payload: nil)
+    }
+
+    /// Fired by the iOS SDK when checkout terminates with an error.
+    /// Mirrors `CustomCheckoutListener.onCheckoutFailed()` on Android.
+    /// The error is serialised into the JS-side `CheckoutNativeError`
+    /// shape (`__typename` / `message` / `code` / `recoverable` /
+    /// optional `statusCode`) so it can be coerced into the matching
+    /// `CheckoutException` subclass on the JS side.
+    func checkoutDidFail(error: CheckoutError) {
+        emitDispatchEnvelope(type: .fail, payload: Self.errorPayload(from: error))
+    }
+}
+
+// MARK: - Dispatch envelope helpers
+
+private extension RCTShopifyCheckoutKit {
+    /// Builds a `{ "type": ..., "payload": ... }` envelope and forwards
+    /// it to the pending JS dispatcher. SDK lifecycle envelopes are
+    /// single-shot: the callback is released after emission so the same
+    /// presentation can only fire one terminal event.
+    func emitDispatchEnvelope(type: DispatchEventType, payload: [String: Any]?) {
+        guard let dispatch = pendingDispatchCallback else { return }
+        // Single-shot for SDK lifecycle events — release before invoking
+        // so a delegate callback that re-enters this code path (e.g. via
+        // a synchronous JS callback that triggers `dismiss()`) cannot
+        // emit a second envelope on the same handle.
+        pendingDispatchCallback = nil
+
+        var envelope: [String: Any] = ["type": type.rawValue]
+        if let payload {
+            envelope["payload"] = payload
+        }
+
+        do {
+            let data = try JSONSerialization.data(withJSONObject: envelope, options: [])
+            guard let json = String(data: data, encoding: .utf8) else {
+                NSLog("[ShopifyCheckoutKit] Failed to encode dispatch envelope for \(type.rawValue): non-UTF8 result")
+                return
+            }
+            dispatch([json])
+        } catch {
+            NSLog("[ShopifyCheckoutKit] Failed to serialize dispatch envelope for \(type.rawValue): \(error)")
+        }
+    }
+
+    /// Maps an iOS `CheckoutError` into the JSON-friendly dictionary
+    /// shape the JS dispatcher expects. Field names match Android's
+    /// `CustomCheckoutListener.populateErrorDetails` so the JS-side
+    /// `parseCheckoutError` works identically on both platforms.
+    static func errorPayload(from error: CheckoutError) -> [String: Any] {
+        switch error {
+        case let .sdkError(underlying, recoverable):
+            return [
+                "__typename": "InternalError",
+                "message": underlying.localizedDescription,
+                "code": CheckoutErrorCode.unknown.rawValue,
+                "recoverable": recoverable
+            ]
+
+        case let .checkoutUnavailable(message, code, recoverable):
+            switch code {
+            case let .clientError(clientCode):
+                return [
+                    "__typename": "CheckoutClientError",
+                    "message": message,
+                    "code": clientCode.rawValue,
+                    "recoverable": recoverable
+                ]
+            case let .httpError(statusCode):
+                return [
+                    "__typename": "CheckoutHTTPError",
+                    "message": message,
+                    // Matches the JS-side `CheckoutErrorCode.httpError`
+                    // string and Android's HttpException code value.
+                    "code": "http_error",
+                    "recoverable": recoverable,
+                    "statusCode": statusCode
+                ]
+            }
+
+        case let .checkoutExpired(message, code, recoverable):
+            return [
+                "__typename": "CheckoutExpiredError",
+                "message": message,
+                "code": code.rawValue,
+                "recoverable": recoverable
+            ]
+        }
+    }
+}

platforms/react-native/modules/@shopify/checkout-kit-react-native/package.snapshot.json

@@ -5,6 +5,7 @@
   "android/src/main/AndroidManifest.xml",
   "android/src/main/AndroidManifestNew.xml",
   "android/src/main/java/com/shopify/reactnative/checkoutkit/CustomCheckoutListener.java",
+  "android/src/main/java/com/shopify/reactnative/checkoutkit/DispatchEventTypes.java",
   "android/src/main/java/com/shopify/reactnative/checkoutkit/ShopifyCheckoutKitModule.java",
   "android/src/main/java/com/shopify/reactnative/checkoutkit/ShopifyCheckoutKitPackage.java",
   "ios/AcceleratedCheckoutButtons.swift",
@@ -18,6 +19,8 @@
   "lib/commonjs/components/AcceleratedCheckoutButtons.js.map",
   "lib/commonjs/context.js",
   "lib/commonjs/context.js.map",
+  "lib/commonjs/dispatch-events.js",
+  "lib/commonjs/dispatch-events.js.map",
   "lib/commonjs/errors.d.js",
   "lib/commonjs/errors.d.js.map",
   "lib/commonjs/index.d.js",
@@ -32,6 +35,8 @@
   "lib/module/components/AcceleratedCheckoutButtons.js.map",
   "lib/module/context.js",
   "lib/module/context.js.map",
+  "lib/module/dispatch-events.js",
+  "lib/module/dispatch-events.js.map",
   "lib/module/errors.d.js",
   "lib/module/errors.d.js.map",
   "lib/module/index.d.js",
@@ -46,6 +51,8 @@
   "lib/typescript/src/components/AcceleratedCheckoutButtons.d.ts.map",
   "lib/typescript/src/context.d.ts",
   "lib/typescript/src/context.d.ts.map",
+  "lib/typescript/src/dispatch-events.d.ts",
+  "lib/typescript/src/dispatch-events.d.ts.map",
   "lib/typescript/src/index.d.ts",
   "lib/typescript/src/index.d.ts.map",
   "lib/typescript/src/specs/NativeShopifyCheckoutKit.d.ts",
@@ -57,6 +64,7 @@
   "RNShopifyCheckoutKit.podspec",
   "src/components/AcceleratedCheckoutButtons.tsx",
   "src/context.tsx",
+  "src/dispatch-events.ts",
   "src/errors.d.ts",
   "src/index.d.ts",
   "src/index.ts",