react-native-iap 16.4.1 → 16.5.1

package/src/index.ts

@@ -80,7 +80,7 @@ import {getVegaIapModule, isVegaOS} from './vega';
 // ------------------------------
 
 // BillingProgramAndroid, ExternalLinkLaunchModeAndroid, and ExternalLinkTypeAndroid
-// are exported from './types' (auto-generated from openiap-gql).
+// are exported from './types' (generated from the OpenIAP client spec).
 
 // Export all types
 export type {
@@ -170,6 +170,7 @@ export type {
 
 // Create the RnIap HybridObject instance lazily to avoid early JSI crashes
 let iapRef: RnIap | null = null;
+let attachingPendingNativeListeners = false;
 
 /**
  * Check if Nitro runtime is ready for IAP operations.
@@ -220,39 +221,52 @@ const isAndroidStoreRuntime = (): boolean => {
   return Platform.OS === 'android' || isVegaOS();
 };
 
-const IAP = {
-  get instance(): RnIap {
-    if (iapRef) return iapRef;
+function getRawIapInstance(): RnIap {
+  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;
+  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>('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>('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(): RnIap {
+    const instance = getRawIapInstance();
+    if (!attachingPendingNativeListeners) {
+      attachingPendingNativeListeners = true;
+      try {
+        tryAttachPendingNativeListeners();
+      } finally {
+        attachingPendingNativeListeners = false;
       }
-      throw e;
     }
-    return iapRef;
+    return instance;
   },
 };
 
@@ -264,6 +278,20 @@ const IAP = {
 // hyodotdev/openiap#382.
 // ============================================================================
 
+function attachNativeListenerOrDefer(label: string, attach: () => void): void {
+  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<(purchase: Purchase) => void>();
 const purchaseUpdateDuplicateJsListeners = new Set<
   (purchase: Purchase) => void
@@ -304,6 +332,38 @@ const purchaseUpdateDuplicateNativeHandler: NitroPurchaseListener = (
   );
 };
 
+function tryAttachPurchaseUpdateNative(
+  receiveDuplicateTransactionUpdatesIOS: boolean,
+): void {
+  const alreadyAttached = receiveDuplicateTransactionUpdatesIOS
+    ? purchaseUpdateDuplicateNativeAttached
+    : purchaseUpdateNativeAttached;
+  if (alreadyAttached) return;
+
+  attachNativeListenerOrDefer('purchaseUpdatedListener', () => {
+    const nativeOptions:
+      | (NitroPurchaseUpdatedListenerOptions &
+          NitroPurchaseUpdatedListenerOptionsParam)
+      | undefined = 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<(error: PurchaseError) => void>();
 let purchaseErrorNativeAttached = false;
 const purchaseErrorNativeHandler: NitroPurchaseErrorListener = (error) => {
@@ -334,6 +394,14 @@ const purchaseErrorNativeHandler: NitroPurchaseErrorListener = (error) => {
   }
 };
 
+function tryAttachPurchaseErrorNative(): void {
+  if (purchaseErrorNativeAttached) return;
+  attachNativeListenerOrDefer('purchaseErrorListener', () => {
+    getRawIapInstance().addPurchaseErrorListener(purchaseErrorNativeHandler);
+    purchaseErrorNativeAttached = true;
+  });
+}
+
 const promotedProductJsListeners = new Set<(product: Product) => void>();
 let promotedProductNativeAttached = false;
 const promotedProductNativeHandler: NitroPromotedProductListener = (
@@ -356,6 +424,16 @@ const promotedProductNativeHandler: NitroPromotedProductListener = (
   }
 };
 
+function tryAttachPromotedProductNative(): void {
+  if (promotedProductNativeAttached) return;
+  attachNativeListenerOrDefer('promotedProductListenerIOS', () => {
+    getRawIapInstance().addPromotedProductListenerIOS(
+      promotedProductNativeHandler,
+    );
+    promotedProductNativeAttached = true;
+  });
+}
+
 /**
  * Reset all JS-level listener tracking state.
  * Called during endConnection to ensure clean re-registration on next initConnection.
@@ -391,52 +469,11 @@ export const purchaseUpdatedListener = (
     : 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: NitroPurchaseUpdatedListenerOptions &
-        NitroPurchaseUpdatedListenerOptionsParam = {
-        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;
@@ -466,7 +503,7 @@ export const purchaseUpdatedListener = (
       }
 
       try {
-        IAP.instance.removePurchaseUpdatedListener(token);
+        getRawIapInstance().removePurchaseUpdatedListener(token);
         if (receiveDuplicateTransactionUpdatesIOS) {
           purchaseUpdateDuplicateNativeToken = null;
           purchaseUpdateDuplicateNativeAttached = false;
@@ -485,21 +522,11 @@ export const purchaseErrorListener = (
   listener: (error: PurchaseError) => void,
 ): EventSubscription => {
   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 {
@@ -519,7 +546,9 @@ export const purchaseErrorListener = (
 
       if (purchaseErrorNativeAttached) {
         try {
-          IAP.instance.removePurchaseErrorListener(purchaseErrorNativeHandler);
+          getRawIapInstance().removePurchaseErrorListener(
+            purchaseErrorNativeHandler,
+          );
           purchaseErrorNativeAttached = false;
         } catch (e) {
           RnIapConsole.warn('[purchaseErrorListener] native remove failed:', e);
@@ -548,21 +577,11 @@ export const promotedProductListenerIOS = (
   }
 
   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 {
@@ -588,7 +607,9 @@ export const promotedProductListenerIOS = (
  *   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
@@ -618,6 +639,16 @@ const userChoiceBillingNativeHandler: NitroUserChoiceBillingListener = (
   }
 };
 
+function tryAttachUserChoiceBillingNative(): void {
+  if (userChoiceBillingNativeAttached) return;
+  attachNativeListenerOrDefer('userChoiceBillingListenerAndroid', () => {
+    getRawIapInstance().addUserChoiceBillingListenerAndroid(
+      userChoiceBillingNativeHandler,
+    );
+    userChoiceBillingNativeAttached = true;
+  });
+}
+
 export const userChoiceBillingListenerAndroid = (
   listener: (details: UserChoiceBillingDetails) => void,
 ): EventSubscription => {
@@ -629,23 +660,11 @@ export const userChoiceBillingListenerAndroid = (
   }
 
   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;
@@ -661,7 +680,7 @@ export const userChoiceBillingListenerAndroid = (
         return;
       }
       try {
-        IAP.instance.removeUserChoiceBillingListenerAndroid(
+        getRawIapInstance().removeUserChoiceBillingListenerAndroid(
           userChoiceBillingNativeHandler,
         );
         userChoiceBillingNativeAttached = false;
@@ -690,10 +709,11 @@ export const userChoiceBillingListenerAndroid = (
  * @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
@@ -722,6 +742,16 @@ const developerProvidedBillingNativeHandler: NitroDeveloperProvidedBillingListen
     }
   };
 
+function tryAttachDeveloperProvidedBillingNative(): void {
+  if (developerProvidedBillingNativeAttached) return;
+  attachNativeListenerOrDefer('developerProvidedBillingListenerAndroid', () => {
+    getRawIapInstance().addDeveloperProvidedBillingListenerAndroid(
+      developerProvidedBillingNativeHandler,
+    );
+    developerProvidedBillingNativeAttached = true;
+  });
+}
+
 export const developerProvidedBillingListenerAndroid = (
   listener: (details: DeveloperProvidedBillingDetailsAndroid) => void,
 ): EventSubscription => {
@@ -733,23 +763,11 @@ export const developerProvidedBillingListenerAndroid = (
   }
 
   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 {
@@ -814,21 +832,12 @@ const subscriptionBillingIssueNativeHandler: NitroSubscriptionBillingIssueListen
 
 function tryAttachSubscriptionBillingIssueNative(): void {
   if (subscriptionBillingIssueNativeAttached) return;
-  try {
-    IAP.instance.addSubscriptionBillingIssueListener(
+  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 = (
@@ -851,6 +860,30 @@ export const subscriptionBillingIssueListener = (
   };
 };
 
+function tryAttachPendingNativeListeners(): void {
+  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
 // ------------------------------
@@ -1170,8 +1203,16 @@ export const getAppTransactionIOS: QueryField<
 
     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,
+    });
   }
 };
 
@@ -1545,16 +1586,22 @@ export const getTransactionJwsIOS: QueryField<'getTransactionJwsIOS'> = async (
  *
  * @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}
  */
@@ -1565,9 +1612,7 @@ export const initConnection: MutationField<'initConnection'> = async (
     const result = await IAP.instance.initConnection(
       config as Record<string, unknown> | undefined,
     );
-    if (subscriptionBillingIssueJsListeners.size > 0) {
-      tryAttachSubscriptionBillingIssueNative();
-    }
+    tryAttachPendingNativeListeners();
     return result;
   } catch (error) {
     const parsedError = parseErrorAndLogIfNeeded(
@@ -1590,8 +1635,9 @@ export const initConnection: MutationField<'initConnection'> = async (
  */
 export const endConnection: MutationField<'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:',
@@ -1603,8 +1649,6 @@ export const endConnection: MutationField<'endConnection'> = async () => {
       responseCode: parsedError.responseCode,
       debugMessage: parsedError.debugMessage,
     });
-  } finally {
-    resetListenerState();
   }
 };
 
@@ -1652,10 +1696,14 @@ export const restorePurchases: MutationField<'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' },
@@ -1722,7 +1770,7 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
       throw unsupportedPlatformError();
     }
 
-    const unifiedRequest: NitroPurchaseRequest = {};
+    const unifiedRequest: NitroPurchaseRequest = {type: normalizedType};
 
     if (Platform.OS === 'ios' && iosRequestSource) {
       const iosRequest = isSubs
@@ -1901,10 +1949,12 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
  *
  * @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));
  * });
  * ```
  *
@@ -1952,11 +2002,11 @@ export const finishTransaction: MutationField<'finishTransaction'> = async (
     }
     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'
@@ -1965,8 +2015,15 @@ export const finishTransaction: MutationField<'finishTransaction'> = async (
         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,
+    });
   }
 };
 
@@ -2638,20 +2695,15 @@ export const getActiveSubscriptions: QueryField<
  *
  * @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: QueryField<
   '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
@@ -2735,7 +2787,8 @@ const normalizeProductQueryType = (
  * ```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 = (