react-native-iap 16.4.0 → 16.5.0

package/lib/module/index.js

@@ -56,6 +56,7 @@ export { kitApi, KitApiError } from "./kit-api.js";
 
 // Create the RnIap HybridObject instance lazily to avoid early JSI crashes
 let iapRef = null;
+let attachingPendingNativeListeners = false;
 
 /**
  * Check if Nitro runtime is ready for IAP operations.
@@ -101,29 +102,41 @@ export const isStandardIOS = () => {
 const isAndroidStoreRuntime = () => {
   return Platform.OS === 'android' || isVegaOS();
 };
-const IAP = {
-  get instance() {
-    if (iapRef) return iapRef;
-    if (isVegaOS()) {
-      const vegaModule = getVegaIapModule();
-      if (!vegaModule) {
-        throw new Error('Amazon Vega IAP module is unavailable. Install @amazon-devices/keplerscript-appstore-iap-lib in the Vega app target and build with the React Native for Vega kepler platform.');
-      }
-      iapRef = vegaModule;
-      return iapRef;
+function getRawIapInstance() {
+  if (iapRef) return iapRef;
+  if (isVegaOS()) {
+    const vegaModule = getVegaIapModule();
+    if (!vegaModule) {
+      throw new Error('Amazon Vega IAP module is unavailable. Install @amazon-devices/keplerscript-appstore-iap-lib in the Vega app target and build with the React Native for Vega kepler platform.');
     }
+    iapRef = vegaModule;
+    return iapRef;
+  }
 
-    // Attempt to create the HybridObject and map common Nitro/JSI readiness errors
-    try {
-      iapRef = NitroModules.createHybridObject('RnIap');
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro') || msg.includes('JSI') || msg.includes('dispatcher') || msg.includes('HybridObject')) {
-        throw new Error('Nitro runtime not installed yet. Ensure react-native-nitro-modules is initialized before calling IAP.');
+  // Attempt to create the HybridObject and map common Nitro/JSI readiness errors
+  try {
+    iapRef = NitroModules.createHybridObject('RnIap');
+  } catch (e) {
+    const msg = toErrorMessage(e);
+    if (msg.includes('Nitro') || msg.includes('JSI') || msg.includes('dispatcher') || msg.includes('HybridObject')) {
+      throw new Error('Nitro runtime not installed yet. Ensure react-native-nitro-modules is initialized before calling IAP.');
+    }
+    throw e;
+  }
+  return iapRef;
+}
+const IAP = {
+  get instance() {
+    const instance = getRawIapInstance();
+    if (!attachingPendingNativeListeners) {
+      attachingPendingNativeListeners = true;
+      try {
+        tryAttachPendingNativeListeners();
+      } finally {
+        attachingPendingNativeListeners = false;
       }
-      throw e;
     }
-    return iapRef;
+    return instance;
   }
 };
 
@@ -135,6 +148,17 @@ const IAP = {
 // hyodotdev/openiap#382.
 // ============================================================================
 
+function attachNativeListenerOrDefer(label, attach) {
+  try {
+    attach();
+  } catch (error) {
+    if (toErrorMessage(error).includes('Nitro runtime not installed')) {
+      RnIapConsole.warn(`[${label}] Nitro not ready yet; will retry on the next native operation`);
+      return;
+    }
+    throw error;
+  }
+}
 const purchaseUpdateJsListeners = new Set();
 const purchaseUpdateDuplicateJsListeners = new Set();
 let purchaseUpdateNativeAttached = false;
@@ -161,6 +185,23 @@ const purchaseUpdateNativeHandler = nitroPurchase => {
 const purchaseUpdateDuplicateNativeHandler = nitroPurchase => {
   emitPurchaseUpdateToListeners(nitroPurchase, purchaseUpdateDuplicateJsListeners);
 };
+function tryAttachPurchaseUpdateNative(receiveDuplicateTransactionUpdatesIOS) {
+  const alreadyAttached = receiveDuplicateTransactionUpdatesIOS ? purchaseUpdateDuplicateNativeAttached : purchaseUpdateNativeAttached;
+  if (alreadyAttached) return;
+  attachNativeListenerOrDefer('purchaseUpdatedListener', () => {
+    const nativeOptions = receiveDuplicateTransactionUpdatesIOS ? {
+      dedupeTransactionIOS: false
+    } : undefined;
+    const token = getRawIapInstance().addPurchaseUpdatedListener(receiveDuplicateTransactionUpdatesIOS ? purchaseUpdateDuplicateNativeHandler : purchaseUpdateNativeHandler, nativeOptions);
+    if (receiveDuplicateTransactionUpdatesIOS) {
+      purchaseUpdateDuplicateNativeToken = typeof token === 'number' ? token : null;
+      purchaseUpdateDuplicateNativeAttached = true;
+    } else {
+      purchaseUpdateNativeToken = typeof token === 'number' ? token : null;
+      purchaseUpdateNativeAttached = true;
+    }
+  });
+}
 const purchaseErrorJsListeners = new Set();
 let purchaseErrorNativeAttached = false;
 const purchaseErrorNativeHandler = error => {
@@ -184,6 +225,13 @@ const purchaseErrorNativeHandler = error => {
     }
   }
 };
+function tryAttachPurchaseErrorNative() {
+  if (purchaseErrorNativeAttached) return;
+  attachNativeListenerOrDefer('purchaseErrorListener', () => {
+    getRawIapInstance().addPurchaseErrorListener(purchaseErrorNativeHandler);
+    purchaseErrorNativeAttached = true;
+  });
+}
 const promotedProductJsListeners = new Set();
 let promotedProductNativeAttached = false;
 const promotedProductNativeHandler = nitroProduct => {
@@ -200,6 +248,13 @@ const promotedProductNativeHandler = nitroProduct => {
     RnIapConsole.error('Invalid promoted product data received from native — id:', nitroProduct?.id ?? 'unknown');
   }
 };
+function tryAttachPromotedProductNative() {
+  if (promotedProductNativeAttached) return;
+  attachNativeListenerOrDefer('promotedProductListenerIOS', () => {
+    getRawIapInstance().addPromotedProductListenerIOS(promotedProductNativeHandler);
+    promotedProductNativeAttached = true;
+  });
+}
 
 /**
  * Reset all JS-level listener tracking state.
@@ -228,36 +283,11 @@ export const purchaseUpdatedListener = (listener, options) => {
   const receiveDuplicateTransactionUpdatesIOS = Platform.OS === 'ios' && options?.dedupeTransactionIOS === false;
   const listeners = receiveDuplicateTransactionUpdatesIOS ? purchaseUpdateDuplicateJsListeners : purchaseUpdateJsListeners;
   listeners.add(listener);
-  if (!purchaseUpdateNativeAttached && !receiveDuplicateTransactionUpdatesIOS) {
-    try {
-      const token = IAP.instance.addPurchaseUpdatedListener(purchaseUpdateNativeHandler);
-      purchaseUpdateNativeToken = typeof token === 'number' ? token : null;
-      purchaseUpdateNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[purchaseUpdatedListener] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
-  }
-  if (!purchaseUpdateDuplicateNativeAttached && receiveDuplicateTransactionUpdatesIOS) {
-    try {
-      const nativeOptions = {
-        dedupeTransactionIOS: false
-      };
-      const token = IAP.instance.addPurchaseUpdatedListener(purchaseUpdateDuplicateNativeHandler, nativeOptions);
-      purchaseUpdateDuplicateNativeToken = typeof token === 'number' ? token : null;
-      purchaseUpdateDuplicateNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[purchaseUpdatedListener] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
+  try {
+    tryAttachPurchaseUpdateNative(receiveDuplicateTransactionUpdatesIOS);
+  } catch (error) {
+    listeners.delete(listener);
+    throw error;
   }
   let removed = false;
   return {
@@ -282,7 +312,7 @@ export const purchaseUpdatedListener = (listener, options) => {
         return;
       }
       try {
-        IAP.instance.removePurchaseUpdatedListener(token);
+        getRawIapInstance().removePurchaseUpdatedListener(token);
         if (receiveDuplicateTransactionUpdatesIOS) {
           purchaseUpdateDuplicateNativeToken = null;
           purchaseUpdateDuplicateNativeAttached = false;
@@ -298,18 +328,11 @@ export const purchaseUpdatedListener = (listener, options) => {
 };
 export const purchaseErrorListener = listener => {
   purchaseErrorJsListeners.add(listener);
-  if (!purchaseErrorNativeAttached) {
-    try {
-      IAP.instance.addPurchaseErrorListener(purchaseErrorNativeHandler);
-      purchaseErrorNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[purchaseErrorListener] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
+  try {
+    tryAttachPurchaseErrorNative();
+  } catch (error) {
+    purchaseErrorJsListeners.delete(listener);
+    throw error;
   }
   return {
     remove: () => {
@@ -327,7 +350,7 @@ export const purchaseErrorListener = listener => {
       }
       if (purchaseErrorNativeAttached) {
         try {
-          IAP.instance.removePurchaseErrorListener(purchaseErrorNativeHandler);
+          getRawIapInstance().removePurchaseErrorListener(purchaseErrorNativeHandler);
           purchaseErrorNativeAttached = false;
         } catch (e) {
           RnIapConsole.warn('[purchaseErrorListener] native remove failed:', e);
@@ -352,18 +375,11 @@ export const promotedProductListenerIOS = listener => {
     };
   }
   promotedProductJsListeners.add(listener);
-  if (!promotedProductNativeAttached) {
-    try {
-      IAP.instance.addPromotedProductListenerIOS(promotedProductNativeHandler);
-      promotedProductNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[promotedProductListenerIOS] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
+  try {
+    tryAttachPromotedProductNative();
+  } catch (error) {
+    promotedProductJsListeners.delete(listener);
+    throw error;
   }
   return {
     remove: () => {
@@ -388,7 +404,9 @@ export const promotedProductListenerIOS = listener => {
  *   console.log('External transaction token received; send it to your backend without logging it.');
  *
  *   // Send token to backend for Google Play reporting
- *   await reportToGooglePlay(details.externalTransactionToken);
+ *   void reportToGooglePlay(details.externalTransactionToken).catch((error) => {
+ *     console.warn('Alternative billing report failed', error);
+ *   });
  * });
  *
  * // Later, remove the listener
@@ -407,6 +425,13 @@ const userChoiceBillingNativeHandler = details => {
     }
   }
 };
+function tryAttachUserChoiceBillingNative() {
+  if (userChoiceBillingNativeAttached) return;
+  attachNativeListenerOrDefer('userChoiceBillingListenerAndroid', () => {
+    getRawIapInstance().addUserChoiceBillingListenerAndroid(userChoiceBillingNativeHandler);
+    userChoiceBillingNativeAttached = true;
+  });
+}
 export const userChoiceBillingListenerAndroid = listener => {
   if (Platform.OS !== 'android') {
     RnIapConsole.warn('userChoiceBillingListenerAndroid: This listener is only available on Android');
@@ -415,18 +440,11 @@ export const userChoiceBillingListenerAndroid = listener => {
     };
   }
   userChoiceBillingJsListeners.add(listener);
-  if (!userChoiceBillingNativeAttached) {
-    try {
-      IAP.instance.addUserChoiceBillingListenerAndroid(userChoiceBillingNativeHandler);
-      userChoiceBillingNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[userChoiceBillingListenerAndroid] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
+  try {
+    tryAttachUserChoiceBillingNative();
+  } catch (error) {
+    userChoiceBillingJsListeners.delete(listener);
+    throw error;
   }
   let removed = false;
   return {
@@ -438,7 +456,7 @@ export const userChoiceBillingListenerAndroid = listener => {
         return;
       }
       try {
-        IAP.instance.removeUserChoiceBillingListenerAndroid(userChoiceBillingNativeHandler);
+        getRawIapInstance().removeUserChoiceBillingListenerAndroid(userChoiceBillingNativeHandler);
         userChoiceBillingNativeAttached = false;
       } catch (e) {
         RnIapConsole.warn('[userChoiceBillingListenerAndroid] native remove failed:', e);
@@ -462,10 +480,11 @@ export const userChoiceBillingListenerAndroid = listener => {
  * @example
  * ```typescript
  * const subscription = developerProvidedBillingListenerAndroid((details) => {
- *   await processExternalPayment(details.products, details.linkUri);
- *   if (details.externalTransactionToken) {
- *     await reportToGooglePlay(details.externalTransactionToken);
- *   }
+ *   void processExternalPayment(details.products, details.linkUri)
+ *     .then(() => details.externalTransactionToken
+ *       ? reportToGooglePlay(details.externalTransactionToken)
+ *       : undefined)
+ *     .catch((error) => console.warn('Developer billing failed', error));
  * });
  *
  * // Later, remove the listener
@@ -484,6 +503,13 @@ const developerProvidedBillingNativeHandler = details => {
     }
   }
 };
+function tryAttachDeveloperProvidedBillingNative() {
+  if (developerProvidedBillingNativeAttached) return;
+  attachNativeListenerOrDefer('developerProvidedBillingListenerAndroid', () => {
+    getRawIapInstance().addDeveloperProvidedBillingListenerAndroid(developerProvidedBillingNativeHandler);
+    developerProvidedBillingNativeAttached = true;
+  });
+}
 export const developerProvidedBillingListenerAndroid = listener => {
   if (Platform.OS !== 'android') {
     RnIapConsole.warn('developerProvidedBillingListenerAndroid: This listener is only available on Android');
@@ -492,18 +518,11 @@ export const developerProvidedBillingListenerAndroid = listener => {
     };
   }
   developerProvidedBillingJsListeners.add(listener);
-  if (!developerProvidedBillingNativeAttached) {
-    try {
-      IAP.instance.addDeveloperProvidedBillingListenerAndroid(developerProvidedBillingNativeHandler);
-      developerProvidedBillingNativeAttached = true;
-    } catch (e) {
-      const msg = toErrorMessage(e);
-      if (msg.includes('Nitro runtime not installed')) {
-        RnIapConsole.warn('[developerProvidedBillingListenerAndroid] Nitro not ready yet; listener inert until initConnection()');
-      } else {
-        throw e;
-      }
-    }
+  try {
+    tryAttachDeveloperProvidedBillingNative();
+  } catch (error) {
+    developerProvidedBillingJsListeners.delete(listener);
+    throw error;
   }
   return {
     remove: () => {
@@ -555,17 +574,10 @@ const subscriptionBillingIssueNativeHandler = nitroPurchase => {
 };
 function tryAttachSubscriptionBillingIssueNative() {
   if (subscriptionBillingIssueNativeAttached) return;
-  try {
-    IAP.instance.addSubscriptionBillingIssueListener(subscriptionBillingIssueNativeHandler);
+  attachNativeListenerOrDefer('subscriptionBillingIssueListener', () => {
+    getRawIapInstance().addSubscriptionBillingIssueListener(subscriptionBillingIssueNativeHandler);
     subscriptionBillingIssueNativeAttached = true;
-  } catch (e) {
-    const msg = toErrorMessage(e);
-    if (msg.includes('Nitro runtime not installed')) {
-      RnIapConsole.warn('[subscriptionBillingIssueListener] Nitro not ready yet; will retry after initConnection()');
-    } else {
-      throw e;
-    }
-  }
+  });
 }
 export const subscriptionBillingIssueListener = listener => {
   subscriptionBillingIssueJsListeners.add(listener);
@@ -583,6 +595,29 @@ export const subscriptionBillingIssueListener = listener => {
     }
   };
 };
+function tryAttachPendingNativeListeners() {
+  if (purchaseUpdateJsListeners.size > 0) {
+    tryAttachPurchaseUpdateNative(false);
+  }
+  if (purchaseUpdateDuplicateJsListeners.size > 0) {
+    tryAttachPurchaseUpdateNative(true);
+  }
+  if (purchaseErrorJsListeners.size > 0) {
+    tryAttachPurchaseErrorNative();
+  }
+  if (promotedProductJsListeners.size > 0) {
+    tryAttachPromotedProductNative();
+  }
+  if (userChoiceBillingJsListeners.size > 0) {
+    tryAttachUserChoiceBillingNative();
+  }
+  if (developerProvidedBillingJsListeners.size > 0) {
+    tryAttachDeveloperProvidedBillingNative();
+  }
+  if (subscriptionBillingIssueJsListeners.size > 0) {
+    tryAttachSubscriptionBillingIssueNative();
+  }
+}
 
 // ------------------------------
 // Query API
@@ -852,8 +887,13 @@ export const getAppTransactionIOS = async () => {
     }
     return null;
   } catch (error) {
-    RnIapConsole.error('Failed to get app transaction:', error);
-    throw error;
+    const parsedError = parseErrorAndLogIfNeeded('Failed to get app transaction:', error);
+    throw createPurchaseError({
+      code: parsedError.code,
+      message: parsedError.message,
+      responseCode: parsedError.responseCode,
+      debugMessage: parsedError.debugMessage
+    });
   }
 };
 
@@ -1152,25 +1192,29 @@ export const getTransactionJwsIOS = async sku => {
  *
  * @example
  * ```ts
- * await initConnection();
- * await initConnection({ enableBillingProgramAndroid: 'external-offer' });
- * await initConnection({
- *   enableBillingProgramAndroid: 'billing-choice',
- *   billingChoiceScreenTypeAndroid: 'developer-rendered',
- * });
+ * // Choose exactly one connection call for the session.
+ * const connected = await initConnection();
+ * // Or replace the call above with one Android billing program:
+ * // const connected = await initConnection({
+ * //   enableBillingProgramAndroid: 'external-offer',
+ * // });
+ * // const connected = await initConnection({
+ * //   enableBillingProgramAndroid: 'billing-choice',
+ * //   billingChoiceScreenTypeAndroid: 'developer-rendered',
+ * // });
+ * if (!connected) throw new Error('Store connection failed');
  * ```
  *
- * @remarks When using `useIAP()`, connection is auto-managed on mount/unmount —
- *   pass options to the hook instead of calling this directly.
+ * @remarks When using `useIAP()`, the connection initializes on mount. On unmount,
+ *   React Native removes hook listeners but keeps the native connection open across
+ *   screens. Pass options to the hook instead of calling this directly.
  *
  * @see {@link https://openiap.dev/docs/apis/init-connection}
  */
 export const initConnection = async config => {
   try {
     const result = await IAP.instance.initConnection(config);
-    if (subscriptionBillingIssueJsListeners.size > 0) {
-      tryAttachSubscriptionBillingIssueNative();
-    }
+    tryAttachPendingNativeListeners();
     return result;
   } catch (error) {
     const parsedError = parseErrorAndLogIfNeeded('Failed to initialize IAP connection:', error);
@@ -1190,8 +1234,9 @@ export const initConnection = async config => {
  */
 export const endConnection = async () => {
   try {
-    if (!iapRef) return true;
-    return await IAP.instance.endConnection();
+    const result = iapRef ? await IAP.instance.endConnection() : true;
+    resetListenerState();
+    return result;
   } catch (error) {
     const parsedError = parseErrorAndLogIfNeeded('Failed to end IAP connection:', error);
     throw createPurchaseError({
@@ -1200,8 +1245,6 @@ export const endConnection = async () => {
       responseCode: parsedError.responseCode,
       debugMessage: parsedError.debugMessage
     });
-  } finally {
-    resetListenerState();
   }
 };
 
@@ -1245,10 +1288,14 @@ export const restorePurchases = async () => {
  *   - `type: 'in-app'` — pass `request.apple.sku` (iOS) and/or `request.google.skus` (Android).
  *   - `type: 'subs'`  — same shape, plus `request.google.subscriptionOffers: [{ sku, offerToken }]`.
  * @returns The dispatched purchase payload. **Do not rely on it** for the actual outcome.
- * @throws Synchronous rejection from the store (e.g. `E_NOT_PREPARED`, validation failure).
+ * @throws Invalid arguments or failures that prevent dispatch. Store outcomes are event-based;
+ *   on Android, `not-prepared` is delivered through `purchaseErrorListener`.
  *
  * @example
  * ```ts
+ * const connected = await initConnection();
+ * if (!connected) return;
+ *
  * await requestPurchase({
  *   request: {
  *     apple: { sku: 'com.app.premium' },
@@ -1301,7 +1348,9 @@ export const requestPurchase = async request => {
     } else {
       throw unsupportedPlatformError();
     }
-    const unifiedRequest = {};
+    const unifiedRequest = {
+      type: normalizedType
+    };
     if (Platform.OS === 'ios' && iosRequestSource) {
       const iosRequest = isSubs ? iosRequestSource : iosRequestSource;
       const iosPayload = {
@@ -1429,10 +1478,12 @@ export const requestPurchase = async request => {
  *
  * @example
  * ```ts
- * purchaseUpdatedListener(async (purchase) => {
- *   if (await verifyOnServer(purchase)) {
- *     await finishTransaction({ purchase, isConsumable: false });
- *   }
+ * purchaseUpdatedListener((purchase) => {
+ *   void verifyOnServer(purchase)
+ *     .then((verified) => verified
+ *       ? finishTransaction({ purchase, isConsumable: false })
+ *       : undefined)
+ *     .catch((error) => console.warn('Transaction finalization failed:', error));
  * });
  * ```
  *
@@ -1478,18 +1529,25 @@ export const finishTransaction = async args => {
     }
     return;
   } catch (error) {
+    const parsedError = parseErrorStringToJsonObj(error);
     // If iOS transaction has already been auto-finished natively, treat as success
     if (Platform.OS === 'ios') {
-      const err = parseErrorStringToJsonObj(error);
-      const msg = (err?.message || '').toString();
-      const code = (err?.code || '').toString();
+      const msg = (parsedError.message || '').toString();
+      const code = (parsedError.code || '').toString();
       if (msg.includes('Transaction not found') || code === 'E_ITEM_UNAVAILABLE') {
         // Consider already finished
         return;
       }
     }
-    RnIapConsole.error('Failed to finish transaction:', error);
-    throw error;
+    if (!isUserCancelledError(parsedError)) {
+      RnIapConsole.error('Failed to finish transaction:', error);
+    }
+    throw createPurchaseError({
+      code: parsedError.code,
+      message: parsedError.message,
+      responseCode: parsedError.responseCode,
+      debugMessage: parsedError.debugMessage
+    });
   }
 };
 
@@ -2060,18 +2118,13 @@ export const getActiveSubscriptions = async subscriptionIds => {
  *
  * @param subscriptionIds - Optional array of subscription IDs to check
  * @returns Promise<boolean> - True if there are active subscriptions
+ * @throws When the store cannot determine subscription status
  *
  * @see {@link https://openiap.dev/docs/apis/has-active-subscriptions}
  */
 export const hasActiveSubscriptions = async subscriptionIds => {
-  try {
-    const activeSubscriptions = await getActiveSubscriptions(subscriptionIds);
-    return activeSubscriptions.length > 0;
-  } catch (error) {
-    // If there's an error getting subscriptions, return false
-    RnIapConsole.warn('Error checking active subscriptions:', error);
-    return false;
-  }
+  const activeSubscriptions = await getActiveSubscriptions(subscriptionIds);
+  return activeSubscriptions.length > 0;
 };
 
 // Type conversion utilities
@@ -2128,7 +2181,8 @@ const normalizeProductQueryType = type => {
  * ```typescript
  * // Enable external offers before connecting
  * enableBillingProgramAndroid('external-offer');
- * await initConnection();
+ * const connected = await initConnection();
+ * if (!connected) throw new Error('Store connection failed');
  * ```
  */
 export const enableBillingProgramAndroid = program => {