react-native-iap 14.7.2 → 14.7.4

package/src/hooks/useIAP.ts

@@ -104,6 +104,8 @@ type UseIap = {
 export interface UseIapOptions {
   onPurchaseSuccess?: (purchase: Purchase) => void;
   onPurchaseError?: (error: PurchaseError) => void;
+  /** Callback for non-purchase errors (fetchProducts, getAvailablePurchases, etc.) */
+  onError?: (error: Error) => void;
   onPromotedProductIOS?: (product: Product) => void;
   onUserChoiceBillingAndroid?: (details: UserChoiceBillingDetails) => void;
   /**
@@ -180,6 +182,15 @@ export function useIAP(options?: UseIapOptions): UseIap {
     subscriptionsRefState.current = subscriptions;
   }, [subscriptions]);
 
+  // Helper function to invoke onError callback
+  const invokeOnError = useCallback((error: unknown) => {
+    if (optionsRef.current?.onError) {
+      optionsRef.current.onError(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }, []);
+
   const fetchProductsInternal = useCallback(
     async (params: {
       skus: string[];
@@ -253,9 +264,10 @@ export function useIAP(options?: UseIapOptions): UseIap {
         );
       } catch (error) {
         RnIapConsole.error('Error fetching products:', error);
+        invokeOnError(error);
       }
     },
-    [mergeWithDuplicateCheck],
+    [mergeWithDuplicateCheck, invokeOnError],
   );
 
   const getAvailablePurchasesInternal = useCallback(
@@ -268,9 +280,10 @@ export function useIAP(options?: UseIapOptions): UseIap {
         setAvailablePurchases(result);
       } catch (error) {
         RnIapConsole.error('Error fetching available purchases:', error);
+        invokeOnError(error);
       }
     },
-    [],
+    [invokeOnError],
   );
 
   const getActiveSubscriptionsInternal = useCallback(
@@ -281,12 +294,11 @@ export function useIAP(options?: UseIapOptions): UseIap {
         return result;
       } catch (error) {
         RnIapConsole.error('Error getting active subscriptions:', error);
-        // Don't clear existing activeSubscriptions on error - preserve current state
-        // This prevents the UI from showing empty state when there are temporary network issues
+        invokeOnError(error);
         return [];
       }
     },
-    [],
+    [invokeOnError],
   );
 
   const hasActiveSubscriptionsInternal = useCallback(
@@ -295,10 +307,11 @@ export function useIAP(options?: UseIapOptions): UseIap {
         return await hasActiveSubscriptions(subscriptionIds);
       } catch (error) {
         RnIapConsole.error('Error checking active subscriptions:', error);
+        invokeOnError(error);
         return false;
       }
     },
-    [],
+    [invokeOnError],
   );
 
   const finishTransaction = useCallback(
@@ -469,8 +482,9 @@ export function useIAP(options?: UseIapOptions): UseIap {
       try {
         await restorePurchasesTopLevel();
         await getAvailablePurchasesInternal();
-      } catch (e) {
-        RnIapConsole.warn('Failed to restore purchases:', e);
+      } catch (error) {
+        RnIapConsole.warn('Failed to restore purchases:', error);
+        invokeOnError(error);
       }
     },
     getPromotedProductIOS,

package/src/index.ts

@@ -1241,27 +1241,35 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
         skus: androidRequest.skus,
       };
 
-      if (androidRequest.obfuscatedAccountIdAndroid) {
-        androidPayload.obfuscatedAccountIdAndroid =
-          androidRequest.obfuscatedAccountIdAndroid;
+      if (androidRequest.obfuscatedAccountId) {
+        androidPayload.obfuscatedAccountId = androidRequest.obfuscatedAccountId;
       }
-      if (androidRequest.obfuscatedProfileIdAndroid) {
-        androidPayload.obfuscatedProfileIdAndroid =
-          androidRequest.obfuscatedProfileIdAndroid;
+      if (androidRequest.obfuscatedProfileId) {
+        androidPayload.obfuscatedProfileId = androidRequest.obfuscatedProfileId;
       }
       if (androidRequest.isOfferPersonalized != null) {
         androidPayload.isOfferPersonalized = androidRequest.isOfferPersonalized;
       }
 
+      // One-time purchase offerToken (Android 7.0+)
+      if (!isSubs) {
+        const purchaseRequest = androidRequest as RequestPurchaseAndroidProps;
+        if (purchaseRequest.offerToken) {
+          androidPayload.offerToken = purchaseRequest.offerToken;
+        }
+      }
+
       if (isSubs) {
         const subsRequest = androidRequest as RequestSubscriptionAndroidProps;
-        if (subsRequest.purchaseTokenAndroid) {
-          androidPayload.purchaseTokenAndroid =
-            subsRequest.purchaseTokenAndroid;
+        if (subsRequest.purchaseToken) {
+          androidPayload.purchaseToken = subsRequest.purchaseToken;
+        }
+        if (subsRequest.replacementMode != null) {
+          androidPayload.replacementMode = subsRequest.replacementMode;
         }
-        if (subsRequest.replacementModeAndroid != null) {
-          androidPayload.replacementModeAndroid =
-            subsRequest.replacementModeAndroid;
+        if (subsRequest.subscriptionProductReplacementParams) {
+          androidPayload.subscriptionProductReplacementParams =
+            subsRequest.subscriptionProductReplacementParams;
         }
         androidPayload.subscriptionOffers = (
           subsRequest.subscriptionOffers ?? []

package/src/specs/RnIap.nitro.ts

@@ -12,6 +12,7 @@ import type {
   ExternalPurchaseNoticeResultIOS,
   MutationFinishTransactionArgs,
   ProductCommon,
+  PromotionalOfferJwsInputIOS,
   PurchaseCommon,
   PurchaseOptions,
   VerifyPurchaseAppleOptions,
@@ -24,6 +25,7 @@ import type {
   UserChoiceBillingDetails,
   PaymentModeIOS,
   SubscriptionProductReplacementParamsAndroid,
+  WinBackOfferInputIOS,
 } from '../types';
 
 // Nitro-compatible enum types (Nitro doesn't support inline string unions from types.ts)
@@ -118,20 +120,47 @@ export interface NitroRequestPurchaseIos {
    * @platform iOS
    */
   advancedCommerceData?: RequestPurchaseIosProps['advancedCommerceData'];
+  /**
+   * Override introductory offer eligibility (iOS 15+, WWDC 2025).
+   * Set to true to indicate the user is eligible for introductory offer,
+   * or false to indicate they are not. When nil, the system determines eligibility.
+   * Back-deployed to iOS 15.
+   * @platform iOS
+   */
+  introductoryOfferEligibility?: boolean | null;
+  /**
+   * JWS promotional offer (iOS 15+, WWDC 2025).
+   * New signature format using compact JWS string for promotional offers.
+   * Back-deployed to iOS 15.
+   * @platform iOS
+   */
+  promotionalOfferJWS?: PromotionalOfferJwsInputIOS | null;
+  /**
+   * Win-back offer to apply (iOS 18+).
+   * Used to re-engage churned subscribers with a discount or free trial.
+   * @platform iOS
+   */
+  winBackOffer?: WinBackOfferInputIOS | null;
 }
 
 export interface NitroRequestPurchaseAndroid {
   skus: RequestSubscriptionAndroidProps['skus'];
-  obfuscatedAccountIdAndroid?: RequestSubscriptionAndroidProps['obfuscatedAccountIdAndroid'];
-  obfuscatedProfileIdAndroid?: RequestSubscriptionAndroidProps['obfuscatedProfileIdAndroid'];
+  obfuscatedAccountId?: RequestSubscriptionAndroidProps['obfuscatedAccountId'];
+  obfuscatedProfileId?: RequestSubscriptionAndroidProps['obfuscatedProfileId'];
   isOfferPersonalized?: RequestSubscriptionAndroidProps['isOfferPersonalized'];
+  /**
+   * Offer token for one-time purchase discounts (7.0+).
+   * Pass the offerToken from oneTimePurchaseOfferDetailsAndroid or discountOffers
+   * to apply a discount offer to the purchase.
+   */
+  offerToken?: string | null;
   subscriptionOffers?: AndroidSubscriptionOfferInput[] | null;
   /** @deprecated Use subscriptionProductReplacementParams instead for item-level replacement (8.1.0+) */
-  replacementModeAndroid?: RequestSubscriptionAndroidProps['replacementModeAndroid'];
-  purchaseTokenAndroid?: RequestSubscriptionAndroidProps['purchaseTokenAndroid'];
+  replacementMode?: RequestSubscriptionAndroidProps['replacementMode'];
+  purchaseToken?: RequestSubscriptionAndroidProps['purchaseToken'];
   /**
    * Product-level replacement parameters (8.1.0+)
-   * Use this instead of replacementModeAndroid for item-level replacement
+   * Use this instead of replacementMode for item-level replacement
    */
   subscriptionProductReplacementParams?: SubscriptionProductReplacementParamsAndroid | null;
 }
@@ -161,6 +190,13 @@ type NitroAvailablePurchasesAndroidType = 'inapp' | 'subs';
 
 export interface NitroAvailablePurchasesAndroidOptions {
   type?: NitroAvailablePurchasesAndroidType;
+  /**
+   * Include suspended subscriptions in the result (Android 8.1+).
+   * Suspended subscriptions have isSuspendedAndroid=true and should NOT be granted entitlements.
+   * Users should be directed to the subscription center to resolve payment issues.
+   * Default: false (only active subscriptions are returned)
+   */
+  includeSuspended?: boolean | null;
 }
 
 export interface NitroAvailablePurchasesOptions {
@@ -543,6 +579,14 @@ export interface NitroProduct {
   freeTrialPeriodAndroid?: string | null;
   subscriptionOfferDetailsAndroid?: string | null;
   oneTimePurchaseOfferDetailsAndroid?: NitroOneTimePurchaseOfferDetail[] | null;
+  /**
+   * Product-level status code indicating fetch result (Android 8.0+)
+   * OK = product fetched successfully
+   * NOT_FOUND = SKU doesn't exist
+   * NO_OFFERS_AVAILABLE = user not eligible for any offers
+   * Available in Google Play Billing Library 8.0.0+
+   */
+  productStatusAndroid?: string | null;
 }
 
 // ╔══════════════════════════════════════════════════════════════════════════╗

package/src/types.ts

@@ -99,6 +99,22 @@ export interface BillingProgramReportingDetailsAndroid {
   externalTransactionToken: string;
 }
 
+/**
+ * Extended billing result with sub-response code (Android)
+ * Available in Google Play Billing Library 8.0.0+
+ */
+export interface BillingResultAndroid {
+  /** Debug message from the billing library */
+  debugMessage?: (string | null);
+  /** The response code from the billing operation */
+  responseCode: number;
+  /**
+   * Sub-response code for more granular error information (8.0+).
+   * Provides additional context when responseCode indicates an error.
+   */
+  subResponseCode?: (SubResponseCodeAndroid | null);
+}
+
 export interface DeepLinkOptions {
   /** Android package name to target (required on Android) */
   packageNameAndroid?: (string | null);
@@ -525,7 +541,7 @@ export interface Mutation {
    * promoted products can be purchased directly via the standard purchase flow.
    * @deprecated Use promotedProductListenerIOS + requestPurchase instead
    */
-  requestPurchaseOnPromotedProductIOS: boolean;
+  requestPurchaseOnPromotedProductIOS: Promise<boolean>;
   /** Restore completed purchases across platforms */
   restorePurchases: Promise<void>;
   /**
@@ -664,6 +680,14 @@ export interface ProductAndroid extends ProductCommon {
   oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail[] | null);
   platform: 'android';
   price?: (number | null);
+  /**
+   * Product-level status code indicating fetch result (Android 8.0+)
+   * OK = product fetched successfully
+   * NOT_FOUND = SKU doesn't exist
+   * NO_OFFERS_AVAILABLE = user not eligible for any offers
+   * Available in Google Play Billing Library 8.0.0+
+   */
+  productStatusAndroid?: (ProductStatusAndroid | null);
   /**
    * @deprecated Use subscriptionOffers instead for cross-platform compatibility.
    * @deprecated Use subscriptionOffers instead
@@ -769,6 +793,14 @@ export interface ProductRequest {
   type?: (ProductQueryType | null);
 }
 
+/**
+ * Status code for individual products returned from queryProductDetailsAsync (Android)
+ * Prior to 8.0, products that couldn't be fetched were simply not returned.
+ * With 8.0+, these products are returned with a status code explaining why.
+ * Available in Google Play Billing Library 8.0.0+
+ */
+export type ProductStatusAndroid = 'ok' | 'not-found' | 'no-offers-available' | 'unknown';
+
 export type ProductSubscription = ProductSubscriptionAndroid | ProductSubscriptionIOS;
 
 export interface ProductSubscriptionAndroid extends ProductCommon {
@@ -794,6 +826,14 @@ export interface ProductSubscriptionAndroid extends ProductCommon {
   oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail[] | null);
   platform: 'android';
   price?: (number | null);
+  /**
+   * Product-level status code indicating fetch result (Android 8.0+)
+   * OK = product fetched successfully
+   * NOT_FOUND = SKU doesn't exist
+   * NO_OFFERS_AVAILABLE = user not eligible for any offers
+   * Available in Google Play Billing Library 8.0.0+
+   */
+  productStatusAndroid?: (ProductStatusAndroid | null);
   /**
    * @deprecated Use subscriptionOffers instead for cross-platform compatibility.
    * @deprecated Use subscriptionOffers instead
@@ -866,6 +906,23 @@ export type ProductType = 'in-app' | 'subs';
 
 export type ProductTypeIOS = 'consumable' | 'non-consumable' | 'auto-renewable-subscription' | 'non-renewing-subscription';
 
+/**
+ * JWS promotional offer input for iOS 15+ (StoreKit 2, WWDC 2025).
+ * New signature format using compact JWS string for promotional offers.
+ * This provides a simpler alternative to the legacy signature-based promotional offers.
+ * Back-deployed to iOS 15.
+ */
+export interface PromotionalOfferJwsInputIOS {
+  /**
+   * Compact JWS string signed by your server.
+   * The JWS should contain the promotional offer signature data.
+   * Format: header.payload.signature (base64url encoded)
+   */
+  jws: string;
+  /** The promotional offer identifier from App Store Connect */
+  offerId: string;
+}
+
 export type Purchase = PurchaseAndroid | PurchaseIOS;
 
 export interface PurchaseAndroid extends PurchaseCommon {
@@ -980,6 +1037,13 @@ export interface PurchaseOfferIOS {
 export interface PurchaseOptions {
   /** Also emit results through the iOS event listeners */
   alsoPublishToEventListenerIOS?: (boolean | null);
+  /**
+   * Include suspended subscriptions in the result (Android 8.1+).
+   * Suspended subscriptions have isSuspendedAndroid=true and should NOT be granted entitlements.
+   * Users should be directed to the subscription center to resolve payment issues.
+   * Default: false (only active subscriptions are returned)
+   */
+  includeSuspendedAndroid?: (boolean | null);
   /** Limit to currently active items on iOS */
   onlyIncludeActiveItemsIOS?: (boolean | null);
 }
@@ -1130,12 +1194,21 @@ export interface RequestPurchaseAndroidProps {
    * Google Play Billing and the developer's external payment option.
    */
   developerBillingOption?: (DeveloperBillingOptionParamsAndroid | null);
-  /** Personalized offer flag */
+  /**
+   * Personalized offer flag.
+   * When true, indicates the price was customized for this user.
+   */
   isOfferPersonalized?: (boolean | null);
   /** Obfuscated account ID */
-  obfuscatedAccountIdAndroid?: (string | null);
+  obfuscatedAccountId?: (string | null);
   /** Obfuscated profile ID */
-  obfuscatedProfileIdAndroid?: (string | null);
+  obfuscatedProfileId?: (string | null);
+  /**
+   * Offer token for one-time purchase discounts (7.0+).
+   * Pass the offerToken from oneTimePurchaseOfferDetailsAndroid or discountOffers
+   * to apply a discount offer to the purchase.
+   */
+  offerToken?: (string | null);
   /** List of product SKUs */
   skus: string[];
 }
@@ -1156,7 +1229,10 @@ export interface RequestPurchaseIosProps {
   quantity?: (number | null);
   /** Product SKU */
   sku: string;
-  /** Discount offer to apply */
+  /**
+   * Promotional offer to apply (subscriptions only, ignored for one-time purchases).
+   * iOS only supports promotional offers for auto-renewable subscriptions.
+   */
   withOffer?: (DiscountOfferInputIOS | null);
 }
 
@@ -1204,26 +1280,29 @@ export interface RequestSubscriptionAndroidProps {
    * Google Play Billing and the developer's external payment option.
    */
   developerBillingOption?: (DeveloperBillingOptionParamsAndroid | null);
-  /** Personalized offer flag */
+  /**
+   * Personalized offer flag.
+   * When true, indicates the price was customized for this user.
+   */
   isOfferPersonalized?: (boolean | null);
   /** Obfuscated account ID */
-  obfuscatedAccountIdAndroid?: (string | null);
+  obfuscatedAccountId?: (string | null);
   /** Obfuscated profile ID */
-  obfuscatedProfileIdAndroid?: (string | null);
+  obfuscatedProfileId?: (string | null);
   /** Purchase token for upgrades/downgrades */
-  purchaseTokenAndroid?: (string | null);
+  purchaseToken?: (string | null);
   /**
    * Replacement mode for subscription changes
    * @deprecated Use subscriptionProductReplacementParams instead for item-level replacement (8.1.0+)
    */
-  replacementModeAndroid?: (number | null);
+  replacementMode?: (number | null);
   /** List of subscription SKUs */
   skus: string[];
   /** Subscription offers */
   subscriptionOffers?: (AndroidSubscriptionOfferInput[] | null);
   /**
    * Product-level replacement parameters (8.1.0+)
-   * Use this instead of replacementModeAndroid for item-level replacement
+   * Use this instead of replacementMode for item-level replacement
    */
   subscriptionProductReplacementParams?: (SubscriptionProductReplacementParamsAndroid | null);
 }
@@ -1238,8 +1317,32 @@ export interface RequestSubscriptionIosProps {
   advancedCommerceData?: (string | null);
   andDangerouslyFinishTransactionAutomatically?: (boolean | null);
   appAccountToken?: (string | null);
+  /**
+   * Override introductory offer eligibility (iOS 15+, WWDC 2025).
+   * Set to true to indicate the user is eligible for introductory offer,
+   * or false to indicate they are not. When nil, the system determines eligibility.
+   * Back-deployed to iOS 15.
+   */
+  introductoryOfferEligibility?: (boolean | null);
+  /**
+   * JWS promotional offer (iOS 15+, WWDC 2025).
+   * New signature format using compact JWS string for promotional offers.
+   * Back-deployed to iOS 15.
+   */
+  promotionalOfferJWS?: (PromotionalOfferJwsInputIOS | null);
   quantity?: (number | null);
   sku: string;
+  /**
+   * Win-back offer to apply (iOS 18+)
+   * Used to re-engage churned subscribers with a discount or free trial.
+   * The offer is available when the customer is eligible and can be discovered
+   * via StoreKit Message (automatic) or subscription offer APIs.
+   */
+  winBackOffer?: (WinBackOfferInputIOS | null);
+  /**
+   * Promotional offer to apply for subscription purchases.
+   * Requires server-signed offer with nonce, timestamp, keyId, and signature.
+   */
   withOffer?: (DiscountOfferInputIOS | null);
 }
 
@@ -1295,6 +1398,12 @@ export interface RequestVerifyPurchaseWithIapkitResult {
   store: IapStore;
 }
 
+/**
+ * Sub-response codes for more granular purchase error information (Android)
+ * Available in Google Play Billing Library 8.0.0+
+ */
+export type SubResponseCodeAndroid = 'no-applicable-sub-response-code' | 'payment-declined-due-to-insufficient-funds' | 'user-ineligible';
+
 export interface Subscription {
   /**
    * Fires when a user selects developer billing in the External Payments flow (Android only)
@@ -1415,7 +1524,7 @@ export interface SubscriptionOfferIOS {
   type: SubscriptionOfferTypeIOS;
 }
 
-export type SubscriptionOfferTypeIOS = 'introductory' | 'promotional';
+export type SubscriptionOfferTypeIOS = 'introductory' | 'promotional' | 'win-back';
 
 /** Subscription period value combining unit and count. */
 export interface SubscriptionPeriod {
@@ -1615,6 +1724,16 @@ export interface VerifyPurchaseWithProviderResult {
 
 export type VoidResult = void;
 
+/**
+ * Win-back offer input for iOS 18+ (StoreKit 2)
+ * Win-back offers are used to re-engage churned subscribers.
+ * The offer is automatically presented via StoreKit Message when eligible,
+ * or can be applied programmatically during purchase.
+ */
+export interface WinBackOfferInputIOS {
+  /** The win-back offer ID from App Store Connect */
+  offerId: string;
+}
 // -- Query helper types (auto-generated)
 export type QueryArgsMap = {
   canPresentExternalPurchaseNoticeIOS: never;

package/src/utils/type-bridge.ts

@@ -312,6 +312,8 @@ export function convertNitroProductToProduct(
     subscriptionOfferDetailsAndroid: parseSubscriptionOffers(
       nitroProduct.subscriptionOfferDetailsAndroid,
     ),
+    // Product status (Billing Library 8.0+, OpenIAP 1.3.14+)
+    productStatusAndroid: nitroProduct.productStatusAndroid ?? null,
   };
 
   // Parse standardized subscriptionOffers (cross-platform, OpenIAP 1.3.10+)