feat(RN): Wire up accelerated checkouts with protocol events (#181)

## Stack Context

This stack is adding Checkout Protocol event support to the React Native wrapper. The parent PR introduces the first protocol event (`ec.start`) for the imperative `present()` path; this PR wires the same start event into instance-based accelerated checkout buttons.

## What?

- Adds an `events?: ProtocolHandlers` prop to `AcceleratedCheckoutButtons` using computed `CheckoutProtocol` keys.
- Routes native component dispatch envelopes to JS handlers for `[CheckoutProtocol.start]`.
- Connects iOS accelerated checkout buttons to the existing protocol relay.
- Exposes native supported protocol event constants through `constantsToExport` and warns if JS/native event lists drift.
- Adds tests and sample usage in the RN sample cart screen.

## Why?

Consumers need to observe checkout protocol events from declarative component instances, not only from `ShopifyCheckout.present()`. This keeps the public TypeScript interface consistent across both surfaces while intentionally keeping protocol support scoped to `CheckoutProtocol.start` for this PR.

## How to test

- `pnpm --dir platforms/react-native/modules/@shopify/checkout-kit-react-native typecheck`
- `pnpm --dir platforms/react-native/sample typecheck`
- `pnpm --dir platforms/react-native test -- AcceleratedCheckoutButtons.test.tsx --runInBand`
- `pnpm --dir platforms/react-native exec jest --runInBand`
- `swift test --package-path platforms/react-native/modules/@shopify/checkout-kit-react-native/ios`
- Manual iOS simulator validation with `agent-device`: tapped the sample cart `Shop Pay` accelerated checkout button and confirmed the `[CheckoutProtocol.start]` handler ran by observing the checkout start event state during validation.

---

### Before you merge

> [!IMPORTANT]
>
> - [x] I've added tests to support my implementation
> - [x] I have read and agree with the [Contribution Guidelines](./CONTRIBUTING.md)
> - [x] 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>

Author: kieran-osgood-shopify

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

@@ -51,6 +51,19 @@ const exampleConfig = {
 };
 const shopifyCheckoutKitEventEmitter = createMockEmitter();
 
+const UIManager = {
+  getViewManagerConfig: jest.fn((name: string) => {
+    if (name === 'RCTAcceleratedCheckoutButtons') {
+      return {
+        Constants: {
+          checkoutProtocolEventTypes: ['ec.start'],
+        },
+      };
+    }
+    return null;
+  }),
+};
+
 const ShopifyCheckoutKit = {
   version: '0.7.0',
   getConstants: jest.fn(() => ({
@@ -81,6 +94,7 @@ module.exports = {
     requestMultiple: jest.fn(async () => ({})),
   },
   NativeEventEmitter: jest.fn(() => shopifyCheckoutKitEventEmitter),
+  UIManager,
   requireNativeComponent,
   codegenNativeComponent,
   TurboModuleRegistry: {

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

@@ -51,7 +51,7 @@ class RCTAcceleratedCheckoutButtonsManager: RCTViewManager {
     }
 
     override func constantsToExport() -> [AnyHashable: Any]! {
-        return [:]
+        return ["checkoutProtocolEventTypes": supportedProtocolRelayMethods]
     }
 }
 
@@ -107,6 +107,7 @@ class RCTAcceleratedCheckoutButtonsView: UIView {
     @objc var onCancel: RCTBubblingEventBlock?
     @objc var onRenderStateChange: RCTBubblingEventBlock?
     @objc var onClickLink: RCTBubblingEventBlock?
+    @objc var onDispatch: RCTDirectEventBlock?
 
     // MARK: - Private
 
@@ -273,6 +274,14 @@ class RCTAcceleratedCheckoutButtonsView: UIView {
         // Attach event handlers
         buttons = attachEventListeners(to: buttons)
 
+        let client = makeRelayClient(
+            subscribedMethods: supportedProtocolRelayMethods,
+            dispatch: { [weak self] json in
+                self?.onDispatch?(["value": json])
+            }
+        )
+        buttons = buttons.connect(client)
+
         var view: AnyView
 
         let colorScheme: SwiftUI.ColorScheme = traitCollection.userInterfaceStyle == .dark ? .dark : .light

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

@@ -15,6 +15,10 @@ struct DispatchEnvelope<Payload: Encodable>: Encodable {
 // Bridges native CheckoutProtocol notifications to the React Native onDispatch
 // event stream. Payloads are emitted in protocol wire casing; JS performs the
 // schema-aware conversion to the public camelCase shape with QuickType.
+let supportedProtocolRelayMethods = [
+    CheckoutProtocol.start.method
+]
+
 func makeRelayClient(
     subscribedMethods: [String],
     dispatch: @escaping @MainActor @Sendable (String) -> Void

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

@@ -128,6 +128,11 @@ @interface RCT_EXTERN_MODULE (RCTAcceleratedCheckoutButtonsManager, RCTViewManag
  */
 RCT_EXPORT_VIEW_PROPERTY(onClickLink, RCTBubblingEventBlock)
 
+/**
+ * Emitted when a subscribed Checkout Protocol event fires. Payload contains { value } where value is a JSON envelope.
+ */
+RCT_EXPORT_VIEW_PROPERTY(onDispatch, RCTDirectEventBlock)
+
 /**
  * Emitted when the intrinsic height of the native view changes. Payload contains { height }.
  */

platforms/react-native/modules/@shopify/checkout-kit-react-native/src/components/AcceleratedCheckoutButtons.tsx

@@ -1,6 +1,7 @@
 import React, {useCallback, useMemo, useState} from 'react';
-import {Platform} from 'react-native';
+import {Platform, UIManager} from 'react-native';
 import type {AcceleratedCheckoutWallet, CheckoutException} from '..';
+import {CheckoutProtocol, type ProtocolHandlers} from '../protocol';
 import RCTAcceleratedCheckoutButtons from '../specs/RCTAcceleratedCheckoutButtonsNativeComponent';
 
 export enum RenderState {
@@ -88,6 +89,13 @@ interface CommonAcceleratedCheckoutButtonsProps {
    */
   onRenderStateChange?: (event: RenderStateChangeEvent) => void;
 
+  /**
+   * Checkout Protocol event handlers scoped to this button instance.
+   *
+   * Currently supports CheckoutProtocol.start.
+   */
+  events?: ProtocolHandlers;
+
   /**
    * Called when a link is clicked within the checkout
    */
@@ -139,6 +147,13 @@ export type AcceleratedCheckoutButtonsProps = (CartProps | VariantProps) &
  */
 
 const defaultStyles = {flex: 1};
+const nativeComponentName = 'RCTAcceleratedCheckoutButtons';
+const protocolEventTypesConstant = 'checkoutProtocolEventTypes';
+const checkoutProtocolEventTypeValues = Object.values(CheckoutProtocol);
+const checkoutProtocolEventTypes: ReadonlySet<string> = new Set(
+  checkoutProtocolEventTypeValues,
+);
+let verifiedProtocolEventParitySignature: string | undefined;
 
 export const AcceleratedCheckoutButtons: React.FC<
   AcceleratedCheckoutButtonsProps
@@ -151,6 +166,7 @@ export const AcceleratedCheckoutButtons: React.FC<
   onCancel,
   onRenderStateChange,
   onClickLink,
+  events,
   ...props
 }) => {
   const isCart = isCartProps(props);
@@ -198,6 +214,19 @@ export const AcceleratedCheckoutButtons: React.FC<
     [onClickLink],
   );
 
+  const handleDispatch = useCallback(
+    (event: {nativeEvent: unknown}) => {
+      const nativeEvent = event.nativeEvent as {value?: unknown};
+      if (typeof nativeEvent?.value !== 'string') {
+        logDispatchError('dispatch event is missing a string `value`');
+        return;
+      }
+
+      routeProtocolDispatchEnvelope(nativeEvent.value, events);
+    },
+    [events],
+  );
+
   const handleSizeChange = useCallback(
     (event: {nativeEvent: {height: number}}) => {
       setDynamicHeight(event.nativeEvent.height);
@@ -245,6 +274,8 @@ export const AcceleratedCheckoutButtons: React.FC<
     }
   }
 
+  verifyProtocolEventParity();
+
   return (
     <RCTAcceleratedCheckoutButtons
       testID="accelerated-checkout-buttons"
@@ -258,6 +289,7 @@ export const AcceleratedCheckoutButtons: React.FC<
       onCancel={handleCancel}
       onRenderStateChange={handleRenderStateChange}
       onClickLink={handleClickLink}
+      onDispatch={handleDispatch}
       onSizeChange={handleSizeChange}
     />
   );
@@ -293,3 +325,145 @@ function isVariantProps(
 ): props is VariantProps {
   return 'variantId' in props && 'quantity' in props && props.quantity > 0;
 }
+
+function verifyProtocolEventParity(): void {
+  const nativeTypes = getNativeProtocolEventTypes();
+  const signature = buildProtocolEventParitySignature(nativeTypes);
+  if (verifiedProtocolEventParitySignature === signature) return;
+
+  verifiedProtocolEventParitySignature = signature;
+
+  if (!Array.isArray(nativeTypes)) {
+    logProtocolEventParityWarning(
+      `native view manager did not report a \`${protocolEventTypesConstant}\` array. ` +
+        'The bundled native component is likely older than this JS package.',
+    );
+    return;
+  }
+
+  const jsSet = new Set<string>(checkoutProtocolEventTypeValues);
+  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) {
+    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(', ')}`);
+  }
+
+  logProtocolEventParityWarning(lines.join('\n  '));
+}
+
+function buildProtocolEventParitySignature(
+  nativeTypes: readonly string[] | undefined | null,
+): string {
+  return JSON.stringify({
+    js: [...checkoutProtocolEventTypeValues].sort(),
+    native: Array.isArray(nativeTypes) ? [...nativeTypes].sort() : nativeTypes,
+  });
+}
+
+function getNativeProtocolEventTypes(): readonly string[] | undefined | null {
+  const viewManagerConfig = UIManager.getViewManagerConfig?.(
+    nativeComponentName,
+  ) as
+    | {
+        Constants?: Record<string, unknown>;
+      }
+    | undefined;
+
+  return viewManagerConfig?.Constants?.[protocolEventTypesConstant] as
+    | readonly string[]
+    | undefined
+    | null;
+}
+
+function routeProtocolDispatchEnvelope(
+  envelopeJson: string,
+  events: ProtocolHandlers | undefined,
+): void {
+  let envelope: unknown;
+  try {
+    envelope = JSON.parse(envelopeJson);
+  } catch {
+    logDispatchError('dispatch envelope is not valid JSON', envelopeJson);
+    return;
+  }
+
+  if (!isPlainObject(envelope) || typeof envelope.type !== 'string') {
+    logDispatchError(
+      'dispatch envelope is missing a string `type` discriminator',
+      envelopeJson,
+    );
+    return;
+  }
+
+  if (!checkoutProtocolEventTypes.has(envelope.type)) {
+    logUnknownDispatchType(envelope.type);
+    return;
+  }
+
+  const handler = (events as Record<
+    string,
+    ((payload: unknown) => void) | undefined
+  > | undefined)?.[envelope.type];
+
+  if (handler == null) {
+    return;
+  }
+
+  if (!isPlainObject(envelope.payload)) {
+    logDispatchError(
+      `protocol envelope "${envelope.type}" payload is not an object`,
+      envelopeJson,
+    );
+    return;
+  }
+
+  handler(envelope.payload);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function logUnknownDispatchType(type: string): void {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[ShopifyAcceleratedCheckouts] Ignoring protocol dispatch envelope with unknown type "${type}". ` +
+      'Native emitted a Checkout Protocol event this JS package does not know how to handle. ' +
+      'Confirm native and JS package versions are compatible.',
+  );
+}
+
+function logProtocolEventParityWarning(detail: string): void {
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[ShopifyAcceleratedCheckouts] Checkout Protocol event list out of sync between JS ' +
+      'and native. Rebuild your host app so the bundled native component matches ' +
+      `this version of '@shopify/checkout-kit-react-native'.\n  ${detail}`,
+  );
+}
+
+function logDispatchError(detail: string, raw?: string): void {
+  const message = `[ShopifyAcceleratedCheckouts] Failed to handle protocol dispatch: ${detail}`;
+  if (raw == null) {
+    // eslint-disable-next-line no-console
+    console.error(message);
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.error(message, raw);
+}

platforms/react-native/modules/@shopify/checkout-kit-react-native/src/specs/RCTAcceleratedCheckoutButtonsNativeComponent.ts

@@ -19,6 +19,7 @@ type RenderStateChangeEvent = Readonly<{
 }>;
 
 type ClickLinkEvent = Readonly<{url: string}>;
+type DispatchEvent = Readonly<{value: string}>;
 type SizeChangeEvent = Readonly<{height: Double}>;
 
 type CheckoutIdentifierSpec = Readonly<{
@@ -37,6 +38,7 @@ interface NativeProps extends ViewProps {
   onCancel?: BubblingEventHandler<null>;
   onRenderStateChange?: BubblingEventHandler<RenderStateChangeEvent>;
   onClickLink?: BubblingEventHandler<ClickLinkEvent>;
+  onDispatch?: DirectEventHandler<DispatchEvent>;
   onSizeChange?: DirectEventHandler<SizeChangeEvent>;
 }