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',
  'geolocationRequest', or protocol 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 — preserves the protocol dispatch fallthrough
  while making contract drift visible.
- 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,52 @@
+/*
+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.
+ *
+ * Protocol-layer method names (e.g. {@code ec.start}) are intentionally
+ * not listed here \u2014 they belong to the shared protocol package.
+ */
+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

@@ -70,6 +70,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;
   }
 
@@ -87,7 +90,7 @@ public void removeListeners(double count) {
   public void present(String checkoutURL, ReadableArray subscribedMethods, @Nullable Callback dispatch) {
     Activity currentActivity = getCurrentActivity();
     if (currentActivity instanceof ComponentActivity) {
-      checkoutListener = new CustomCheckoutListener(currentActivity, this.reactContext, dispatch);
+      checkoutListener = new CustomCheckoutListener(dispatch);
 
       List<String> methods = new ArrayList<>();
       for (int i = 0; i < subscribedMethods.size(); i++) {

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

@@ -28,16 +28,32 @@ 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":...}`.
+    // 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 SDK lifecycle events).
+    //
+    // When wired, emit envelope JSON of the shape `{"type":"<DispatchEventType>","payload":...}`
+    // using `DispatchEventType` rawValues so the JS-side parity check stays meaningful.
     private var pendingDispatchCallback: RCTResponseSenderBlock?
 
     @objc var methodQueue: DispatchQueue {
@@ -58,7 +74,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 }
         ]
     }
 

platforms/react-native/modules/@shopify/checkout-kit-react-native/src/dispatch-events.ts

@@ -0,0 +1,142 @@
+/*
+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.
+*/
+
+/**
+ * Canonical list of SDK lifecycle event types delivered through the
+ * per-`present()` dispatcher.
+ *
+ * The set must be kept in sync with the native equivalents:
+ *   - android: `DispatchEventTypes.ALL` (Java)
+ *   - ios:     `DispatchEventType.allCases` (Swift)
+ *
+ * Drift is detected at runtime by `verifyDispatchEventParity`, which is
+ * invoked from the `ShopifyCheckout` constructor against the
+ * `dispatchEventTypes` array reported by `RNShopifyCheckoutKit.getConstants()`.
+ *
+ * Protocol-layer method names (e.g. `ec.start`) are intentionally NOT
+ * listed here — those are owned by `@shopify/checkout-kit-protocol` and
+ * versioned independently of this bridge.
+ */
+export const SDK_LIFECYCLE_EVENT_TYPES = [
+  'close',
+  'fail',
+  'geolocationRequest',
+] as const;
+
+export type SdkLifecycleEventType = (typeof SDK_LIFECYCLE_EVENT_TYPES)[number];
+
+const sdkLifecycleEventSet: ReadonlySet<string> = new Set(
+  SDK_LIFECYCLE_EVENT_TYPES,
+);
+
+export function isSdkLifecycleEventType(
+  value: string,
+): value is SdkLifecycleEventType {
+  return sdkLifecycleEventSet.has(value);
+}
+
+/**
+ * Thrown when the SDK lifecycle event list reported by the native
+ * module does not match the list this JS package was built against.
+ *
+ * This almost always means the bundled native module is older or newer
+ * than the JS package — the host app needs a clean native rebuild.
+ */
+export class DispatchEventParityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DispatchEventParityError';
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DispatchEventParityError);
+    }
+  }
+}
+
+let parityVerified = false;
+
+/**
+ * Compares the JS-side SDK lifecycle event list against the list the
+ * native module reports through `getConstants()`. Throws a
+ * `DispatchEventParityError` describing the diff on mismatch — the
+ * dispatch contract is unsafe to use otherwise.
+ *
+ * Set-equality, order-independent. Memoised: runs at most once per JS
+ * process. Use `__resetDispatchEventParityForTests` to reset in tests.
+ */
+export function verifyDispatchEventParity(
+  nativeTypes: readonly string[] | undefined | null,
+): void {
+  if (parityVerified) return;
+
+  if (!Array.isArray(nativeTypes)) {
+    throw new DispatchEventParityError(
+      buildMessage(
+        'native module did not report a `dispatchEventTypes` array in getConstants(). ' +
+          'The bundled native module is likely older than this JS package.',
+      ),
+    );
+  }
+
+  const jsSet = new Set<string>(SDK_LIFECYCLE_EVENT_TYPES);
+  const nativeSet = new Set<string>(nativeTypes);
+
+  const missingFromJs = [...nativeSet].filter(t => !jsSet.has(t)).sort();
+  const missingFromNative = [...jsSet].filter(t => !nativeSet.has(t)).sort();
+
+  if (missingFromJs.length === 0 && missingFromNative.length === 0) {
+    parityVerified = true;
+    return;
+  }
+
+  const lines = [
+    `js     = [${[...jsSet].sort().join(', ')}]`,
+    `native = [${[...nativeSet].sort().join(', ')}]`,
+  ];
+  if (missingFromJs.length > 0) {
+    lines.push(`events missing from js:     ${missingFromJs.join(', ')}`);
+  }
+  if (missingFromNative.length > 0) {
+    lines.push(`events missing from native: ${missingFromNative.join(', ')}`);
+  }
+
+  throw new DispatchEventParityError(buildMessage(lines.join('\n  ')));
+}
+
+function buildMessage(detail: string): string {
+  return (
+    '[ShopifyCheckoutKit] SDK lifecycle event list out of sync between JS ' +
+    "and native. Rebuild your host app so the bundled native module matches " +
+    "this version of '@shopify/checkout-kit-react-native'.\n  " +
+    detail
+  );
+}
+
+/**
+ * Test-only — resets the cached verification flag so unit tests can
+ * exercise both success and failure paths in isolation. Not part of
+ * the public API.
+ */
+export function __resetDispatchEventParityForTests(): void {
+  parityVerified = false;
+}