react-native-iap 15.1.0 → 15.2.0

package/src/hooks/useIAP.ts

@@ -25,6 +25,7 @@ import {
   showAlternativeBillingDialogAndroid,
   createAlternativeBillingTokenAndroid,
   userChoiceBillingListenerAndroid,
+  subscriptionBillingIssueListener,
   isStandardIOS,
 } from '../';
 
@@ -112,6 +113,16 @@ export interface UseIapOptions {
   onError?: (error: Error) => void;
   onPromotedProductIOS?: (product: Product) => void;
   onUserChoiceBillingAndroid?: (details: UserChoiceBillingDetails) => void;
+  /**
+   * Fires when an active subscription enters a billing-issue state
+   * (StoreKit 2 Message.billingIssue on iOS 18+, Purchase.isSuspended on
+   * Play Billing 8.1+). Not invoked on Meta Horizon.
+   *
+   * Recommended: call deepLinkToSubscriptions on the returned purchase so
+   * the user can update their payment method in the platform subscription
+   * center.
+   */
+  onSubscriptionBillingIssue?: (purchase: Purchase) => void;
   /**
    * @deprecated Use enableBillingProgramAndroid instead.
    * - 'user-choice' → 'user-choice-billing'
@@ -178,6 +189,7 @@ export function useIAP(options?: UseIapOptions): UseIap {
     purchaseError?: EventSubscription;
     promotedProductIOS?: EventSubscription;
     userChoiceBillingAndroid?: EventSubscription;
+    subscriptionBillingIssue?: EventSubscription;
   }>({});
 
   // Track if component is mounted to prevent listener leaks on early unmount
@@ -463,6 +475,15 @@ export function useIAP(options?: UseIapOptions): UseIap {
           }
         });
     }
+
+    // Always attach so callers that supply `onSubscriptionBillingIssue` later
+    // (after the hook has already set up listeners) still receive events.
+    if (!subscriptionsRef.current.subscriptionBillingIssue) {
+      subscriptionsRef.current.subscriptionBillingIssue =
+        subscriptionBillingIssueListener((purchase: Purchase) => {
+          optionsRef.current?.onSubscriptionBillingIssue?.(purchase);
+        });
+    }
   }, [getActiveSubscriptionsInternal, getAvailablePurchasesInternal]);
 
   // Shared helper: clean up all listeners
@@ -471,10 +492,12 @@ export function useIAP(options?: UseIapOptions): UseIap {
     subscriptionsRef.current.purchaseError?.remove();
     subscriptionsRef.current.promotedProductIOS?.remove();
     subscriptionsRef.current.userChoiceBillingAndroid?.remove();
+    subscriptionsRef.current.subscriptionBillingIssue?.remove();
     subscriptionsRef.current.purchaseUpdate = undefined;
     subscriptionsRef.current.purchaseError = undefined;
     subscriptionsRef.current.promotedProductIOS = undefined;
     subscriptionsRef.current.userChoiceBillingAndroid = undefined;
+    subscriptionsRef.current.subscriptionBillingIssue = undefined;
   }, []);
 
   const initIapWithSubscriptions = useCallback(async (): Promise<void> => {

package/src/index.ts

@@ -279,12 +279,14 @@ export const resetListenerState = (): void => {
   promotedProductNativeAttached = false;
   userChoiceBillingNativeAttached = false;
   developerProvidedBillingNativeAttached = false;
+  subscriptionBillingIssueNativeAttached = false;
   // Clear all JS listeners since native side clears them in endConnection
   purchaseUpdateJsListeners.clear();
   purchaseErrorJsListeners.clear();
   promotedProductJsListeners.clear();
   userChoiceBillingJsListeners.clear();
   developerProvidedBillingJsListeners.clear();
+  subscriptionBillingIssueJsListeners.clear();
 };
 
 export const purchaseUpdatedListener = (
@@ -565,6 +567,96 @@ export const developerProvidedBillingListenerAndroid = (
   };
 };
 
+/**
+ * Listen for subscription billing-issue events (cross-platform).
+ *
+ * Fires when an active subscription enters a billing-issue state:
+ * - iOS 18+ / Mac Catalyst 18+: via StoreKit 2 `Message.Reason.billingIssue`.
+ * - Android (Play Billing 8.1+): when `isSuspendedAndroid === true` is observed.
+ * - Horizon / iOS 17 / older platforms: never fires.
+ *
+ * Recommended UX: on fire, call `deepLinkToSubscriptions()` so the user can
+ * update their payment method in the platform subscription center.
+ *
+ * @param listener - Function to call with the affected Purchase
+ * @returns EventSubscription with remove() method to unsubscribe
+ *
+ * @example
+ * ```typescript
+ * const subscription = subscriptionBillingIssueListener((purchase) => {
+ *   console.warn('Subscription needs attention:', purchase.productId);
+ *   deepLinkToSubscriptions({skuAndroid: purchase.productId, packageNameAndroid: 'com.example.app'});
+ * });
+ *
+ * subscription.remove();
+ * ```
+ */
+type NitroSubscriptionBillingIssueListener = Parameters<
+  RnIap['addSubscriptionBillingIssueListener']
+>[0];
+
+const subscriptionBillingIssueJsListeners = new Set<(purchase: Purchase) => void>();
+let subscriptionBillingIssueNativeAttached = false;
+const subscriptionBillingIssueNativeHandler: NitroSubscriptionBillingIssueListener =
+  (nitroPurchase) => {
+    if (!validateNitroPurchase(nitroPurchase)) {
+      RnIapConsole.warn(
+        '[subscriptionBillingIssueListener] dropped malformed native payload',
+      );
+      return;
+    }
+    const purchase = convertNitroPurchaseToPurchase(nitroPurchase);
+    for (const listener of subscriptionBillingIssueJsListeners) {
+      try {
+        listener(purchase);
+      } catch (e) {
+        RnIapConsole.error(
+          '[subscriptionBillingIssueListener] callback threw:',
+          e,
+        );
+      }
+    }
+  };
+
+function tryAttachSubscriptionBillingIssueNative(): void {
+  if (subscriptionBillingIssueNativeAttached) return;
+  try {
+    IAP.instance.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 on next registration after initConnection()',
+      );
+    } else {
+      throw e;
+    }
+  }
+}
+
+export const subscriptionBillingIssueListener = (
+  listener: (purchase: Purchase) => void,
+): EventSubscription => {
+  subscriptionBillingIssueJsListeners.add(listener);
+  // Retry attachment every call so a listener registered before initConnection()
+  // doesn't stay permanently inert once Nitro is ready.
+  try {
+    tryAttachSubscriptionBillingIssueNative();
+  } catch (error) {
+    subscriptionBillingIssueJsListeners.delete(listener);
+    throw error;
+  }
+
+  return {
+    remove: () => {
+      subscriptionBillingIssueJsListeners.delete(listener);
+    },
+  };
+};
+
 // ------------------------------
 // Query API
 // ------------------------------

package/src/specs/RnIap.nitro.ts

@@ -1095,6 +1095,29 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
     listener: (details: DeveloperProvidedBillingDetailsAndroid) => void,
   ): void;
 
+  /**
+   * Add a listener for subscription billing-issue events (cross-platform).
+   *
+   * Fires when a user's active subscription enters a state that needs attention
+   * (payment method failed, card expired, etc.). Unifies:
+   * - StoreKit 2 `Message.Reason.billingIssue` (iOS 18+ / Mac Catalyst 18+)
+   * - Google Play Billing `Purchase.isSuspended` (Play Billing 8.1+)
+   *
+   * NOT fired on Meta Horizon (Billing 7.0 compat SDK lacks the suspended signal).
+   *
+   * @param listener - Called with the affected Purchase
+   */
+  addSubscriptionBillingIssueListener(
+    listener: (purchase: NitroPurchase) => void,
+  ): void;
+
+  /**
+   * Remove a subscription billing-issue listener.
+   */
+  removeSubscriptionBillingIssueListener(
+    listener: (purchase: NitroPurchase) => void,
+  ): void;
+
   // ╔════════════════════════════════════════════════════════════════════════╗
   // ║                 BILLING PROGRAMS API (Android 8.2.0+)                  ║
   // ╚════════════════════════════════════════════════════════════════════════╝

package/src/types.ts

@@ -457,7 +457,7 @@ export interface ExternalPurchaseNoticeResultIOS {
 
 export type FetchProductsResult = ProductOrSubscription[] | Product[] | ProductSubscription[] | null;
 
-export type IapEvent = 'purchase-updated' | 'purchase-error' | 'promoted-product-ios' | 'user-choice-billing-android' | 'developer-provided-billing-android';
+export type IapEvent = 'purchase-updated' | 'purchase-error' | 'promoted-product-ios' | 'user-choice-billing-android' | 'developer-provided-billing-android' | 'subscription-billing-issue';
 
 export type IapPlatform = 'ios' | 'android';
 
@@ -1560,6 +1560,20 @@ export interface Subscription {
   purchaseError: PurchaseError;
   /** Fires when a purchase completes successfully or a pending purchase resolves */
   purchaseUpdated: Purchase;
+  /**
+   * Fires when an active subscription enters a billing-issue state that needs user action
+   * (payment method failed, card expired, etc.). Cross-platform unification:
+   *
+   * - iOS 18+: delivered via StoreKit 2 `Message.Reason.billingIssue`.
+   * - Android (Play flavor, Billing 8.1+): emitted when `isSuspended == true` is first detected
+   *   on a previously healthy subscription. Requires Google Play Billing Library 8.1.0 or newer.
+   * - Android (Horizon flavor): NOT emitted. The Horizon Billing Compatibility SDK implements
+   *   the Play Billing 7.0 API surface which does not expose a suspended-subscription signal.
+   *
+   * Listeners should not assume the event will fire on every store. Direct users to the
+   * platform subscription management UI (`deepLinkToSubscriptions`) to resolve the issue.
+   */
+  subscriptionBillingIssue: Purchase;
   /**
    * Fires when a user selects alternative billing in the User Choice Billing dialog (Android only)
    * Only triggered when the user selects alternative billing instead of Google Play billing
@@ -1965,6 +1979,7 @@ export type SubscriptionArgsMap = {
   promotedProductIOS: never;
   purchaseError: never;
   purchaseUpdated: never;
+  subscriptionBillingIssue: never;
   userChoiceBillingAndroid: never;
 };