fix(rn): align error payloads with native SDK APIs

Author: kieran-osgood-shopify

platforms/react-native/README.md

@@ -601,7 +601,7 @@ shopify.present(checkoutUrl, {
     // The sheet was dismissed without a terminal error
   },
   onFail: (error: CheckoutException) => {
-    // A terminal error occurred — inspect `error.code`, `error.recoverable`, etc.
+    // A terminal error occurred — inspect `error.code`, `error.message`, etc.
   },
 });
 ```
@@ -739,9 +739,9 @@ behalf.
 The geolocation request flow follows this sequence:
 
 1. When checkout needs location data (e.g., to show nearby pickup points), it triggers a geolocation request.
-2. If you've passed an `onGeolocationRequest` callback to `present()`, that callback is invoked.
+2. If you've passed an `onGeolocationRequest` callback to `present()`, that callback is invoked. Request or check Android permissions, then call `event.respond(allow)`.
 3. Otherwise, with `features.handleGeolocationRequests: true` (the default), the module automatically handles the Android runtime permission request.
-4. The result is passed back to checkout, which then proceeds to show relevant pickup points if permission was granted.
+4. The response is passed back to checkout, which then proceeds to show relevant pickup points if permission was granted.
 
 > [!NOTE]
 > If the user denies location permissions, the checkout will still function but will not be able to show nearby pickup points. Users can manually enter their location instead.
@@ -751,13 +751,14 @@ The geolocation request flow follows this sequence:
 > [!NOTE]
 > This section is only applicable for Android.
 
-There are two ways to opt out, depending on whether you want to override the
-behavior for every presentation or just one.
+There are two ways to customize Android geolocation handling, depending on
+whether you want to override the behavior for one presentation or disable the
+fallback globally.
 
 **Per-call override.** Pass an `onGeolocationRequest` callback to
 `present()`. When set, the callback fires instead of the default handler
 for that one presentation; the consumer is responsible for resolving
-permissions and calling `initiateGeolocationRequest(allow)`:
+permissions and calling `event.respond(allow)`:
 
 ```tsx
 shopify.present(checkoutUrl, {
@@ -769,16 +770,19 @@ shopify.present(checkoutUrl, {
     const granted =
       results[coarse] === 'granted' || results[fine] === 'granted';
 
-    shopify.initiateGeolocationRequest(granted);
+    event.respond(granted);
   },
 });
 ```
 
-**Process-wide opt-out.** Set `features.handleGeolocationRequests` to
-`false` when you instantiate the `ShopifyCheckout` class to disable the
-default handler entirely. Use this if you intend to always handle
-geolocation yourself but don't want to wire the callback at every call
-site.
+`event.respond(...)` resolves checkout's pending WebView geolocation request.
+It does not request OS permissions by itself.
+
+**Process-wide default-handler opt-out.** Set
+`features.handleGeolocationRequests` to `false` when you instantiate the
+`ShopifyCheckout` class to disable the default handler entirely. When this is
+set, pass `onGeolocationRequest` to any `present()` call that may need
+geolocation; otherwise the checkout geolocation request will not be resolved.
 
 ```tsx
 const shopifyCheckout = new ShopifyCheckout(config, {handleGeolocationRequests: false});

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

@@ -52,14 +52,17 @@ const exampleConfig = {
 
 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(),
   invalidateCache: jest.fn(),
   getConfig: jest.fn(() => exampleConfig),
   setConfig: jest.fn(),
-  initiateGeolocationRequest: jest.fn(),
+  respondToGeolocationRequest: jest.fn(),
   configureAcceleratedCheckouts: jest.fn(() => true),
   isAcceleratedCheckoutAvailable: jest.fn(() => true),
   isApplePayAvailable: jest.fn(() => true),

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;
   }
 
@@ -68,6 +64,12 @@ public void invokeGeolocationCallback(boolean allow) {
     }
   }
 
+  public void release() {
+    dispatchCallback = null;
+    geolocationCallback = null;
+    geolocationOrigin = null;
+  }
+
   // Lifecycle events
 
   /**
@@ -88,14 +90,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);
     }
   }
 
@@ -109,29 +115,33 @@ public void onGeolocationPermissionsHidePrompt() {
 
   @Override
   public void onCheckoutFailed(CheckoutException checkoutError) {
-    if (dispatchCallback == null) {
+    Callback dispatch = dispatchCallback;
+    if (dispatch == null) {
+      release();
       return;
     }
     try {
-      dispatchCallback.invoke(buildEnvelope("fail", populateErrorDetails(checkoutError)));
+      dispatch.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;
+      release();
     }
   }
 
   @Override
   public void onCheckoutCanceled() {
-    if (dispatchCallback == null) {
+    Callback dispatch = dispatchCallback;
+    if (dispatch == null) {
+      release();
       return;
     }
     try {
-      dispatchCallback.invoke(buildEnvelope("close", null));
+      dispatch.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;
+      release();
     }
   }
 
@@ -150,7 +160,6 @@ private Map<String, Object> populateErrorDetails(CheckoutException checkoutError
     Map<String, Object> errorMap = new HashMap();
     errorMap.put("__typename", getErrorTypeName(checkoutError));
     errorMap.put("message", checkoutError.getErrorDescription());
-    errorMap.put("recoverable", checkoutError.isRecoverable());
     errorMap.put("code", checkoutError.getErrorCode());
 
     if (checkoutError instanceof HttpException) {
@@ -176,9 +185,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

@@ -65,6 +65,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;
   }
 
@@ -80,24 +83,36 @@ public void removeListeners(double count) {
 
   @ReactMethod
   public void present(String checkoutURL, @Nullable Callback dispatch) {
+    releaseCheckoutListener();
+
     Activity currentActivity = getCurrentActivity();
     if (currentActivity instanceof ComponentActivity) {
-      checkoutListener = new CustomCheckoutListener(currentActivity, this.reactContext, dispatch);
+      CustomCheckoutListener listener = new CustomCheckoutListener(dispatch);
+      checkoutListener = listener;
       currentActivity.runOnUiThread(() -> {
         checkoutSheet = ShopifyCheckoutKit.present(checkoutURL, (ComponentActivity) currentActivity,
-            checkoutListener);
+            listener);
       });
     }
   }
 
   @ReactMethod
   public void dismiss() {
+    releaseCheckoutListener();
+
     if (checkoutSheet != null) {
       checkoutSheet.dismiss();
       checkoutSheet = null;
     }
   }
 
+  private void releaseCheckoutListener() {
+    if (checkoutListener != null) {
+      checkoutListener.release();
+      checkoutListener = null;
+    }
+  }
+
   @ReactMethod(isBlockingSynchronousMethod = true)
   public WritableMap getConfig() {
     WritableMap resultConfig = Arguments.createMap();
@@ -170,7 +185,7 @@ public boolean isApplePayAvailable() {
   }
 
   @ReactMethod
-  public void initiateGeolocationRequest(boolean allow) {
+  public void respondToGeolocationRequest(boolean allow) {
     if (checkoutListener != null) {
       checkoutListener.invokeGeolocationCallback(allow);
     }