react-native-iap 14.7.1 → 14.7.3

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);
@@ -169,6 +185,11 @@ export interface DiscountDisplayInfoAndroid {
   percentageDiscount?: (number | null);
 }
 
+/**
+ * Discount information returned from the store.
+ * @deprecated Use the standardized SubscriptionOffer type instead for cross-platform compatibility.
+ * @see https://openiap.dev/docs/types#subscription-offer
+ */
 export interface DiscountIOS {
   identifier: string;
   localizedPrice?: (string | null);
@@ -180,6 +201,79 @@ export interface DiscountIOS {
   type: string;
 }
 
+/**
+ * Standardized one-time product discount offer.
+ * Provides a unified interface for one-time purchase discounts across platforms.
+ *
+ * Currently supported on Android (Google Play Billing 7.0+).
+ * iOS does not support one-time purchase discounts in the same way.
+ *
+ * @see https://openiap.dev/docs/features/discount
+ */
+export interface DiscountOffer {
+  /** Currency code (ISO 4217, e.g., "USD") */
+  currency: string;
+  /**
+   * [Android] Fixed discount amount in micro-units.
+   * Only present for fixed amount discounts.
+   */
+  discountAmountMicrosAndroid?: (string | null);
+  /** Formatted display price string (e.g., "$4.99") */
+  displayPrice: string;
+  /** [Android] Formatted discount amount string (e.g., "$5.00 OFF"). */
+  formattedDiscountAmountAndroid?: (string | null);
+  /**
+   * [Android] Original full price in micro-units before discount.
+   * Divide by 1,000,000 to get the actual price.
+   * Use for displaying strikethrough original price.
+   */
+  fullPriceMicrosAndroid?: (string | null);
+  /**
+   * Unique identifier for the offer.
+   * - iOS: Not applicable (one-time discounts not supported)
+   * - Android: offerId from ProductAndroidOneTimePurchaseOfferDetail
+   */
+  id?: (string | null);
+  /**
+   * [Android] Limited quantity information.
+   * Contains maximumQuantity and remainingQuantity.
+   */
+  limitedQuantityInfoAndroid?: (LimitedQuantityInfoAndroid | null);
+  /** [Android] List of tags associated with this offer. */
+  offerTagsAndroid?: (string[] | null);
+  /**
+   * [Android] Offer token required for purchase.
+   * Must be passed to requestPurchase() when purchasing with this offer.
+   */
+  offerTokenAndroid?: (string | null);
+  /**
+   * [Android] Percentage discount (e.g., 33 for 33% off).
+   * Only present for percentage-based discounts.
+   */
+  percentageDiscountAndroid?: (number | null);
+  /**
+   * [Android] Pre-order details if this is a pre-order offer.
+   * Available in Google Play Billing Library 8.1.0+
+   */
+  preorderDetailsAndroid?: (PreorderDetailsAndroid | null);
+  /** Numeric price value */
+  price: number;
+  /** [Android] Rental details if this is a rental offer. */
+  rentalDetailsAndroid?: (RentalDetailsAndroid | null);
+  /** Type of discount offer */
+  type: DiscountOfferType;
+  /**
+   * [Android] Valid time window for the offer.
+   * Contains startTimeMillis and endTimeMillis.
+   */
+  validTimeWindowAndroid?: (ValidTimeWindowAndroid | null);
+}
+
+/**
+ * iOS DiscountOffer (output type).
+ * @deprecated Use the standardized SubscriptionOffer type instead for cross-platform compatibility.
+ * @see https://openiap.dev/docs/types#subscription-offer
+ */
 export interface DiscountOfferIOS {
   /** Discount identifier */
   identifier: string;
@@ -206,6 +300,12 @@ export interface DiscountOfferInputIOS {
   timestamp: number;
 }
 
+/**
+ * Discount offer type enumeration.
+ * Categorizes the type of discount or promotional offer.
+ */
+export type DiscountOfferType = 'introductory' | 'promotional' | 'one-time';
+
 export interface EntitlementIOS {
   jsonRepresentation: string;
   sku: string;
@@ -441,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>;
   /**
@@ -517,6 +617,12 @@ export type MutationVerifyPurchaseArgs = VerifyPurchaseProps;
 
 export type MutationVerifyPurchaseWithProviderArgs = VerifyPurchaseWithProviderProps;
 
+/**
+ * Payment mode for subscription offers.
+ * Determines how the user pays during the offer period.
+ */
+export type PaymentMode = 'free-trial' | 'pay-as-you-go' | 'pay-up-front' | 'unknown';
+
 export type PaymentModeIOS = 'empty' | 'free-trial' | 'pay-as-you-go' | 'pay-up-front';
 
 /**
@@ -555,6 +661,12 @@ export interface ProductAndroid extends ProductCommon {
   currency: string;
   debugDescription?: (string | null);
   description: string;
+  /**
+   * Standardized discount offers for one-time products.
+   * Cross-platform type with Android-specific fields using suffix.
+   * @see https://openiap.dev/docs/types#discount-offer
+   */
+  discountOffers?: (DiscountOffer[] | null);
   displayName?: (string | null);
   displayPrice: string;
   id: string;
@@ -562,18 +674,40 @@ export interface ProductAndroid extends ProductCommon {
   /**
    * One-time purchase offer details including discounts (Android)
    * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+   * @deprecated Use discountOffers instead for cross-platform compatibility.
+   * @deprecated Use discountOffers instead
    */
   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
+   */
   subscriptionOfferDetailsAndroid?: (ProductSubscriptionAndroidOfferDetails[] | null);
+  /**
+   * Standardized subscription offers.
+   * Cross-platform type with Android-specific fields using suffix.
+   * @see https://openiap.dev/docs/types#subscription-offer
+   */
+  subscriptionOffers?: (SubscriptionOffer[] | null);
   title: string;
   type: 'in-app';
 }
 
 /**
- * One-time purchase offer details (Android)
+ * One-time purchase offer details (Android).
  * Available in Google Play Billing Library 7.0+
+ * @deprecated Use the standardized DiscountOffer type instead for cross-platform compatibility.
+ * @see https://openiap.dev/docs/types#discount-offer
  */
 export interface ProductAndroidOneTimePurchaseOfferDetail {
   /**
@@ -633,7 +767,18 @@ export interface ProductIOS extends ProductCommon {
   jsonRepresentationIOS: string;
   platform: 'ios';
   price?: (number | null);
+  /**
+   * @deprecated Use subscriptionOffers instead for cross-platform compatibility.
+   * @deprecated Use subscriptionOffers instead
+   */
   subscriptionInfoIOS?: (SubscriptionInfoIOS | null);
+  /**
+   * Standardized subscription offers.
+   * Cross-platform type with iOS-specific fields using suffix.
+   * Note: iOS does not support one-time product discounts.
+   * @see https://openiap.dev/docs/types#subscription-offer
+   */
+  subscriptionOffers?: (SubscriptionOffer[] | null);
   title: string;
   type: 'in-app';
   typeIOS: ProductTypeIOS;
@@ -648,12 +793,26 @@ 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 {
   currency: string;
   debugDescription?: (string | null);
   description: string;
+  /**
+   * Standardized discount offers for one-time products.
+   * Cross-platform type with Android-specific fields using suffix.
+   * @see https://openiap.dev/docs/types#discount-offer
+   */
+  discountOffers?: (DiscountOffer[] | null);
   displayName?: (string | null);
   displayPrice: string;
   id: string;
@@ -661,15 +820,40 @@ export interface ProductSubscriptionAndroid extends ProductCommon {
   /**
    * One-time purchase offer details including discounts (Android)
    * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+   * @deprecated Use discountOffers instead for cross-platform compatibility.
+   * @deprecated Use discountOffers instead
    */
   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
+   */
   subscriptionOfferDetailsAndroid: ProductSubscriptionAndroidOfferDetails[];
+  /**
+   * Standardized subscription offers.
+   * Cross-platform type with Android-specific fields using suffix.
+   * @see https://openiap.dev/docs/types#subscription-offer
+   */
+  subscriptionOffers: SubscriptionOffer[];
   title: string;
   type: 'subs';
 }
 
+/**
+ * Subscription offer details (Android).
+ * @deprecated Use the standardized SubscriptionOffer type instead for cross-platform compatibility.
+ * @see https://openiap.dev/docs/types#subscription-offer
+ */
 export interface ProductSubscriptionAndroidOfferDetails {
   basePlanId: string;
   offerId?: (string | null);
@@ -682,6 +866,10 @@ export interface ProductSubscriptionIOS extends ProductCommon {
   currency: string;
   debugDescription?: (string | null);
   description: string;
+  /**
+   * @deprecated Use subscriptionOffers instead for cross-platform compatibility.
+   * @deprecated Use subscriptionOffers instead
+   */
   discountsIOS?: (DiscountIOS[] | null);
   displayName?: (string | null);
   displayNameIOS: string;
@@ -696,7 +884,17 @@ export interface ProductSubscriptionIOS extends ProductCommon {
   jsonRepresentationIOS: string;
   platform: 'ios';
   price?: (number | null);
+  /**
+   * @deprecated Use subscriptionOffers instead for cross-platform compatibility.
+   * @deprecated Use subscriptionOffers instead
+   */
   subscriptionInfoIOS?: (SubscriptionInfoIOS | null);
+  /**
+   * Standardized subscription offers.
+   * Cross-platform type with iOS-specific fields using suffix.
+   * @see https://openiap.dev/docs/types#subscription-offer
+   */
+  subscriptionOffers?: (SubscriptionOffer[] | null);
   subscriptionPeriodNumberIOS?: (string | null);
   subscriptionPeriodUnitIOS?: (SubscriptionPeriodIOS | null);
   title: string;
@@ -708,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 {
@@ -822,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);
 }
@@ -998,7 +1220,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);
 }
 
@@ -1080,8 +1305,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);
 }
 
@@ -1137,6 +1386,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)
@@ -1167,6 +1422,86 @@ export interface SubscriptionInfoIOS {
   subscriptionPeriod: SubscriptionPeriodValueIOS;
 }
 
+/**
+ * Standardized subscription discount/promotional offer.
+ * Provides a unified interface for subscription offers across iOS and Android.
+ *
+ * Both platforms support subscription offers with different implementations:
+ * - iOS: Introductory offers, promotional offers with server-side signatures
+ * - Android: Offer tokens with pricing phases
+ *
+ * @see https://openiap.dev/docs/types/ios#discount-offer
+ * @see https://openiap.dev/docs/types/android#subscription-offer
+ */
+export interface SubscriptionOffer {
+  /**
+   * [Android] Base plan identifier.
+   * Identifies which base plan this offer belongs to.
+   */
+  basePlanIdAndroid?: (string | null);
+  /** Currency code (ISO 4217, e.g., "USD") */
+  currency?: (string | null);
+  /** Formatted display price string (e.g., "$9.99/month") */
+  displayPrice: string;
+  /**
+   * Unique identifier for the offer.
+   * - iOS: Discount identifier from App Store Connect
+   * - Android: offerId from ProductSubscriptionAndroidOfferDetails
+   */
+  id: string;
+  /**
+   * [iOS] Key identifier for signature validation.
+   * Used with server-side signature generation for promotional offers.
+   */
+  keyIdentifierIOS?: (string | null);
+  /** [iOS] Localized price string. */
+  localizedPriceIOS?: (string | null);
+  /**
+   * [iOS] Cryptographic nonce (UUID) for signature validation.
+   * Must be generated server-side for each purchase attempt.
+   */
+  nonceIOS?: (string | null);
+  /** [iOS] Number of billing periods for this discount. */
+  numberOfPeriodsIOS?: (number | null);
+  /** [Android] List of tags associated with this offer. */
+  offerTagsAndroid?: (string[] | null);
+  /**
+   * [Android] Offer token required for purchase.
+   * Must be passed to requestPurchase() when purchasing with this offer.
+   */
+  offerTokenAndroid?: (string | null);
+  /** Payment mode during the offer period */
+  paymentMode?: (PaymentMode | null);
+  /** Subscription period for this offer */
+  period?: (SubscriptionPeriod | null);
+  /** Number of periods the offer applies */
+  periodCount?: (number | null);
+  /** Numeric price value */
+  price: number;
+  /**
+   * [Android] Pricing phases for this subscription offer.
+   * Contains detailed pricing information for each phase (trial, intro, regular).
+   */
+  pricingPhasesAndroid?: (PricingPhasesAndroid | null);
+  /**
+   * [iOS] Server-generated signature for promotional offer validation.
+   * Required when applying promotional offers on iOS.
+   */
+  signatureIOS?: (string | null);
+  /**
+   * [iOS] Timestamp when the signature was generated.
+   * Used for signature validation.
+   */
+  timestampIOS?: (number | null);
+  /** Type of subscription offer (Introductory or Promotional) */
+  type: DiscountOfferType;
+}
+
+/**
+ * iOS subscription offer details.
+ * @deprecated Use the standardized SubscriptionOffer type instead for cross-platform compatibility.
+ * @see https://openiap.dev/docs/types#subscription-offer
+ */
 export interface SubscriptionOfferIOS {
   displayPrice: string;
   id: string;
@@ -1177,10 +1512,21 @@ 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 {
+  /** The period unit (day, week, month, year) */
+  unit: SubscriptionPeriodUnit;
+  /** The number of units (e.g., 1 for monthly, 3 for quarterly) */
+  value: number;
+}
 
 export type SubscriptionPeriodIOS = 'day' | 'week' | 'month' | 'year' | 'empty';
 
+/** Subscription period unit for cross-platform use. */
+export type SubscriptionPeriodUnit = 'day' | 'week' | 'month' | 'year' | 'unknown';
+
 export interface SubscriptionPeriodValueIOS {
   unit: SubscriptionPeriodIOS;
   value: number;
@@ -1366,6 +1712,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

@@ -277,6 +277,30 @@ export function convertNitroProductToProduct(
       iosProduct.discountsIOS = null;
     }
 
+    // Parse standardized subscriptionOffers (cross-platform, OpenIAP 1.3.10+)
+    if (nitroProduct.subscriptionOffers) {
+      try {
+        iosProduct.subscriptionOffers = JSON.parse(
+          nitroProduct.subscriptionOffers,
+        );
+      } catch {
+        iosProduct.subscriptionOffers = null;
+      }
+    } else {
+      iosProduct.subscriptionOffers = null;
+    }
+
+    // Parse standardized discountOffers (cross-platform, OpenIAP 1.3.10+)
+    if (nitroProduct.discountOffers) {
+      try {
+        iosProduct.discountOffers = JSON.parse(nitroProduct.discountOffers);
+      } catch {
+        iosProduct.discountOffers = null;
+      }
+    } else {
+      iosProduct.discountOffers = null;
+    }
+
     return iosProduct as Product;
   }
 
@@ -288,12 +312,43 @@ 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+)
+  if (nitroProduct.subscriptionOffers) {
+    try {
+      androidProduct.subscriptionOffers = JSON.parse(
+        nitroProduct.subscriptionOffers,
+      );
+    } catch {
+      androidProduct.subscriptionOffers = null;
+    }
+  } else {
+    androidProduct.subscriptionOffers = null;
+  }
+
+  // Parse standardized discountOffers (cross-platform, OpenIAP 1.3.10+)
+  if (nitroProduct.discountOffers) {
+    try {
+      androidProduct.discountOffers = JSON.parse(nitroProduct.discountOffers);
+    } catch {
+      androidProduct.discountOffers = null;
+    }
+  } else {
+    androidProduct.discountOffers = null;
+  }
+
   if (type === PRODUCT_TYPE_SUBS) {
+    // Ensure subscriptionOfferDetailsAndroid is always an array for subscriptions
     if (!Array.isArray(androidProduct.subscriptionOfferDetailsAndroid)) {
       androidProduct.subscriptionOfferDetailsAndroid = [];
     }
+    // Ensure subscriptionOffers is always an array for subscriptions (non-nullable in ProductSubscriptionAndroid)
+    if (!Array.isArray(androidProduct.subscriptionOffers)) {
+      androidProduct.subscriptionOffers = [];
+    }
   }
 
   return androidProduct as Product;