react-native-iap 14.5.1-rc.1 → 14.6.0-rc.2

package/src/specs/RnIap.nitro.ts

@@ -14,8 +14,9 @@ import type {
   ProductCommon,
   PurchaseCommon,
   PurchaseOptions,
-  VerifyPurchaseAndroidOptions,
-  VerifyPurchaseProps,
+  VerifyPurchaseAppleOptions,
+  VerifyPurchaseGoogleOptions,
+  VerifyPurchaseHorizonOptions,
   VerifyPurchaseResultAndroid,
   RequestPurchaseIosProps,
   RequestPurchaseResult,
@@ -44,22 +45,50 @@ export type IapStore = 'unknown' | 'apple' | 'google' | 'horizon';
 // Note: Nitro requires at least 2 values for union types
 export type PurchaseVerificationProvider = 'iapkit' | 'none';
 
+// Billing Programs API types (Android 8.2.0+)
+export type BillingProgramAndroid =
+  | 'unspecified'
+  | 'external-content-link'
+  | 'external-offer';
+
+export type ExternalLinkLaunchModeAndroid =
+  | 'unspecified'
+  | 'launch-in-external-browser-or-app'
+  | 'caller-will-launch-link';
+
+export type ExternalLinkTypeAndroid =
+  | 'unspecified'
+  | 'link-to-digital-content-offer'
+  | 'link-to-app-download';
+
 // ╔══════════════════════════════════════════════════════════════════════════╗
 // ║                                  PARAMS                                  ║
 // ╚══════════════════════════════════════════════════════════════════════════╝
 
-// Receipt validation parameters
+// Receipt validation parameters (platform-specific)
 
-export interface NitroReceiptValidationAndroidOptions {
-  accessToken: VerifyPurchaseAndroidOptions['accessToken'];
-  isSub?: VerifyPurchaseAndroidOptions['isSub'];
-  packageName: VerifyPurchaseAndroidOptions['packageName'];
-  productToken: VerifyPurchaseAndroidOptions['productToken'];
+export interface NitroReceiptValidationAppleOptions {
+  sku: VerifyPurchaseAppleOptions['sku'];
+}
+
+export interface NitroReceiptValidationGoogleOptions {
+  accessToken: VerifyPurchaseGoogleOptions['accessToken'];
+  isSub?: VerifyPurchaseGoogleOptions['isSub'];
+  packageName: VerifyPurchaseGoogleOptions['packageName'];
+  purchaseToken: VerifyPurchaseGoogleOptions['purchaseToken'];
+  sku: VerifyPurchaseGoogleOptions['sku'];
+}
+
+export interface NitroReceiptValidationHorizonOptions {
+  accessToken: VerifyPurchaseHorizonOptions['accessToken'];
+  sku: VerifyPurchaseHorizonOptions['sku'];
+  userId: VerifyPurchaseHorizonOptions['userId'];
 }
 
 export interface NitroReceiptValidationParams {
-  sku: VerifyPurchaseProps['sku'];
-  androidOptions?: NitroReceiptValidationAndroidOptions | null;
+  apple?: NitroReceiptValidationAppleOptions | null;
+  google?: NitroReceiptValidationGoogleOptions | null;
+  horizon?: NitroReceiptValidationHorizonOptions | null;
 }
 
 // Purchase request parameters
@@ -147,6 +176,20 @@ export interface NitroDeepLinkOptionsAndroid {
   packageNameAndroid?: DeepLinkOptions['packageNameAndroid'];
 }
 
+/**
+ * Parameters for launching an external link (Android 8.2.0+)
+ */
+export interface NitroLaunchExternalLinkParamsAndroid {
+  /** The billing program (external-content-link or external-offer) */
+  billingProgram: BillingProgramAndroid;
+  /** The external link launch mode */
+  launchMode: ExternalLinkLaunchModeAndroid;
+  /** The type of the external link */
+  linkType: ExternalLinkTypeAndroid;
+  /** The URI where the content will be accessed from */
+  linkUri: string;
+}
+
 // ╔══════════════════════════════════════════════════════════════════════════╗
 // ║                                  TYPES                                   ║
 // ╚══════════════════════════════════════════════════════════════════════════╝
@@ -251,6 +294,26 @@ export interface NitroVerifyPurchaseWithProviderResult {
   provider: PurchaseVerificationProvider;
 }
 
+/**
+ * Result of checking billing program availability (Android 8.2.0+)
+ */
+export interface NitroBillingProgramAvailabilityResultAndroid {
+  /** The billing program that was checked */
+  billingProgram: BillingProgramAndroid;
+  /** Whether the billing program is available for the user */
+  isAvailable: boolean;
+}
+
+/**
+ * Reporting details for external transactions (Android 8.2.0+)
+ */
+export interface NitroBillingProgramReportingDetailsAndroid {
+  /** The billing program that the reporting details are associated with */
+  billingProgram: BillingProgramAndroid;
+  /** External transaction token used to report transactions to Google */
+  externalTransactionToken: string;
+}
+
 /**
  * Discount amount details for one-time purchase offers (Android)
  */
@@ -772,6 +835,7 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
 
   /**
    * Validate a receipt on the appropriate platform
+   * @deprecated Use `verifyPurchase` instead. This function will be removed in a future version.
    * @param params - Receipt validation parameters including SKU and platform-specific options
    * @returns Promise<NitroReceiptValidationResultIOS | NitroReceiptValidationResultAndroid> - Platform-specific validation result
    */
@@ -870,6 +934,57 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
     listener: (details: UserChoiceBillingDetails) => void,
   ): void;
 
+  // ╔════════════════════════════════════════════════════════════════════════╗
+  // ║                 BILLING PROGRAMS API (Android 8.2.0+)                  ║
+  // ╚════════════════════════════════════════════════════════════════════════╝
+
+  /**
+   * Enable a billing program before initConnection (Android only).
+   * Must be called BEFORE initConnection() to configure the BillingClient.
+   *
+   * @param program - The billing program to enable
+   * @platform Android
+   * @since Billing Library 8.2.0+
+   */
+  enableBillingProgramAndroid(program: BillingProgramAndroid): void;
+
+  /**
+   * Check if a billing program is available for this user/device (Android only).
+   *
+   * @param program - The billing program to check
+   * @returns Promise with availability result
+   * @platform Android
+   * @since Billing Library 8.2.0+
+   */
+  isBillingProgramAvailableAndroid(
+    program: BillingProgramAndroid,
+  ): Promise<NitroBillingProgramAvailabilityResultAndroid>;
+
+  /**
+   * Create billing program reporting details for external transactions (Android only).
+   * Used to get the external transaction token needed for reporting to Google.
+   *
+   * @param program - The billing program to create reporting details for
+   * @returns Promise with reporting details including external transaction token
+   * @platform Android
+   * @since Billing Library 8.2.0+
+   */
+  createBillingProgramReportingDetailsAndroid(
+    program: BillingProgramAndroid,
+  ): Promise<NitroBillingProgramReportingDetailsAndroid>;
+
+  /**
+   * Launch external link for external offers or app download (Android only).
+   *
+   * @param params - Parameters for launching the external link
+   * @returns Promise<boolean> - true if user accepted, false otherwise
+   * @platform Android
+   * @since Billing Library 8.2.0+
+   */
+  launchExternalLinkAndroid(
+    params: NitroLaunchExternalLinkParamsAndroid,
+  ): Promise<boolean>;
+
   // ╔════════════════════════════════════════════════════════════════════════╗
   // ║                EXTERNAL PURCHASE LINKS (iOS 16.0+)                     ║
   // ╚════════════════════════════════════════════════════════════════════════╝

package/src/types.ts

@@ -65,6 +65,38 @@ export interface AppTransaction {
   signedDate: number;
 }
 
+/**
+ * Billing program types for external content links and external offers (Android)
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export type BillingProgramAndroid = 'unspecified' | 'external-content-link' | 'external-offer';
+
+/**
+ * Result of checking billing program availability (Android)
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export interface BillingProgramAvailabilityResultAndroid {
+  /** The billing program that was checked */
+  billingProgram: BillingProgramAndroid;
+  /** Whether the billing program is available for the user */
+  isAvailable: boolean;
+}
+
+/**
+ * Reporting details for transactions made outside of Google Play Billing (Android)
+ * Contains the external transaction token needed for reporting
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export interface BillingProgramReportingDetailsAndroid {
+  /** The billing program that the reporting details are associated with */
+  billingProgram: BillingProgramAndroid;
+  /**
+   * External transaction token used to report transactions made outside of Google Play Billing.
+   * This token must be used when reporting the external transaction to Google.
+   */
+  externalTransactionToken: string;
+}
+
 export interface DeepLinkOptions {
   /** Android package name to target (required on Android) */
   packageNameAndroid?: (string | null);
@@ -183,6 +215,40 @@ export enum ErrorCode {
   UserError = 'user-error'
 }
 
+/**
+ * Launch mode for external link flow (Android)
+ * Determines how the external URL is launched
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export type ExternalLinkLaunchModeAndroid = 'unspecified' | 'launch-in-external-browser-or-app' | 'caller-will-launch-link';
+
+/**
+ * Link type for external link flow (Android)
+ * Specifies the type of external link destination
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export type ExternalLinkTypeAndroid = 'unspecified' | 'link-to-digital-content-offer' | 'link-to-app-download';
+
+/**
+ * External offer availability result (Android)
+ * @deprecated Use BillingProgramAvailabilityResultAndroid with isBillingProgramAvailableAsync instead
+ * Available in Google Play Billing Library 6.2.0+, deprecated in 8.2.0
+ */
+export interface ExternalOfferAvailabilityResultAndroid {
+  /** Whether external offers are available for the user */
+  isAvailable: boolean;
+}
+
+/**
+ * External offer reporting details (Android)
+ * @deprecated Use BillingProgramReportingDetailsAndroid with createBillingProgramReportingDetailsAsync instead
+ * Available in Google Play Billing Library 6.2.0+, deprecated in 8.2.0
+ */
+export interface ExternalOfferReportingDetailsAndroid {
+  /** External transaction token for reporting external offer transactions */
+  externalTransactionToken: string;
+}
+
 /** Result of presenting an external purchase link (iOS 18.2+) */
 export interface ExternalPurchaseLinkResultIOS {
   /** Optional error message if the presentation failed */
@@ -222,6 +288,22 @@ export interface InitConnectionConfig {
   alternativeBillingModeAndroid?: (AlternativeBillingModeAndroid | null);
 }
 
+/**
+ * Parameters for launching an external link (Android)
+ * Used with launchExternalLink to initiate external offer or app install flows
+ * Available in Google Play Billing Library 8.2.0+
+ */
+export interface LaunchExternalLinkParamsAndroid {
+  /** The billing program (EXTERNAL_CONTENT_LINK or EXTERNAL_OFFER) */
+  billingProgram: BillingProgramAndroid;
+  /** The external link launch mode */
+  launchMode: ExternalLinkLaunchModeAndroid;
+  /** The type of the external link */
+  linkType: ExternalLinkTypeAndroid;
+  /** The URI where the content will be accessed from */
+  linkUri: string;
+}
+
 /**
  * Limited quantity information for one-time purchase offers (Android)
  * Available in Google Play Billing Library 7.0+
@@ -835,6 +917,14 @@ export type RequestPurchaseProps =
       useAlternativeBilling?: boolean | null;
     };
 
+/**
+ * Platform-specific purchase request parameters.
+ *
+ * Note: "Platforms" refers to the SDK/OS level (apple, google), not the store.
+ * - apple: Always targets App Store
+ * - google: Targets Play Store by default, or Horizon when built with horizon flavor
+ *   (determined at build time, not runtime)
+ */
 export interface RequestPurchasePropsByPlatforms {
   /** @deprecated Use google instead */
   android?: (RequestPurchaseAndroidProps | null);
@@ -857,12 +947,20 @@ export interface RequestSubscriptionAndroidProps {
   obfuscatedProfileIdAndroid?: (string | null);
   /** Purchase token for upgrades/downgrades */
   purchaseTokenAndroid?: (string | null);
-  /** Replacement mode for subscription changes */
+  /**
+   * Replacement mode for subscription changes
+   * @deprecated Use subscriptionProductReplacementParams instead for item-level replacement (8.1.0+)
+   */
   replacementModeAndroid?: (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
+   */
+  subscriptionProductReplacementParams?: (SubscriptionProductReplacementParamsAndroid | null);
 }
 
 export interface RequestSubscriptionIosProps {
@@ -873,6 +971,14 @@ export interface RequestSubscriptionIosProps {
   withOffer?: (DiscountOfferInputIOS | null);
 }
 
+/**
+ * Platform-specific subscription request parameters.
+ *
+ * Note: "Platforms" refers to the SDK/OS level (apple, google), not the store.
+ * - apple: Always targets App Store
+ * - google: Targets Play Store by default, or Horizon when built with horizon flavor
+ *   (determined at build time, not runtime)
+ */
 export interface RequestSubscriptionPropsByPlatforms {
   /** @deprecated Use google instead */
   android?: (RequestSubscriptionAndroidProps | null);
@@ -894,12 +1000,18 @@ export interface RequestVerifyPurchaseWithIapkitGoogleProps {
   purchaseToken: string;
 }
 
+/**
+ * Platform-specific verification parameters for IAPKit.
+ *
+ * - apple: Verifies via App Store (JWS token)
+ * - google: Verifies via Play Store (purchase token)
+ */
 export interface RequestVerifyPurchaseWithIapkitProps {
   /** API key used for the Authorization header (Bearer {apiKey}). */
   apiKey?: (string | null);
-  /** Apple verification parameters. */
+  /** Apple App Store verification parameters. */
   apple?: (RequestVerifyPurchaseWithIapkitAppleProps | null);
-  /** Google verification parameters. */
+  /** Google Play Store verification parameters. */
   google?: (RequestVerifyPurchaseWithIapkitGoogleProps | null);
 }
 
@@ -952,6 +1064,25 @@ export interface SubscriptionPeriodValueIOS {
   value: number;
 }
 
+/**
+ * Product-level subscription replacement parameters (Android)
+ * Used with setSubscriptionProductReplacementParams in BillingFlowParams.ProductDetailsParams
+ * Available in Google Play Billing Library 8.1.0+
+ */
+export interface SubscriptionProductReplacementParamsAndroid {
+  /** The old product ID that needs to be replaced */
+  oldProductId: string;
+  /** The replacement mode for this product change */
+  replacementMode: SubscriptionReplacementModeAndroid;
+}
+
+/**
+ * Replacement mode for subscription changes (Android)
+ * These modes determine how the subscription replacement affects billing.
+ * Available in Google Play Billing Library 8.1.0+
+ */
+export type SubscriptionReplacementModeAndroid = 'unknown-replacement-mode' | 'with-time-proration' | 'charge-prorated-price' | 'charge-full-price' | 'without-proration' | 'deferred' | 'keep-existing';
+
 export interface SubscriptionStatusIOS {
   renewalInfo?: (RenewalInfoIOS | null);
   state: string;
@@ -979,21 +1110,76 @@ export interface ValidTimeWindowAndroid {
   startTimeMillis: string;
 }
 
-export interface VerifyPurchaseAndroidOptions {
+/**
+ * Apple App Store verification parameters.
+ * Used for server-side receipt validation via App Store Server API.
+ */
+export interface VerifyPurchaseAppleOptions {
+  /** Product SKU to validate */
+  sku: string;
+}
+
+/**
+ * Google Play Store verification parameters.
+ * Used for server-side receipt validation via Google Play Developer API.
+ *
+ * ⚠️ SECURITY: Contains sensitive tokens (accessToken, purchaseToken). Do not log or persist this data.
+ */
+export interface VerifyPurchaseGoogleOptions {
+  /**
+   * Google OAuth2 access token for API authentication.
+   * ⚠️ Sensitive: Do not log this value.
+   */
   accessToken: string;
+  /** Whether this is a subscription purchase (affects API endpoint used) */
   isSub?: (boolean | null);
+  /** Android package name (e.g., com.example.app) */
   packageName: string;
-  productToken: string;
+  /**
+   * Purchase token from the purchase response.
+   * ⚠️ Sensitive: Do not log this value.
+   */
+  purchaseToken: string;
+  /** Product SKU to validate */
+  sku: string;
 }
 
-export interface VerifyPurchaseProps {
-  /** Android-specific validation options */
-  androidOptions?: (VerifyPurchaseAndroidOptions | null);
-  /** Product SKU to validate */
+/**
+ * Meta Horizon (Quest) verification parameters.
+ * Used for server-side entitlement verification via Meta's S2S API.
+ * POST https://graph.oculus.com/$APP_ID/verify_entitlement
+ *
+ * ⚠️ SECURITY: Contains sensitive token (accessToken). Do not log or persist this data.
+ */
+export interface VerifyPurchaseHorizonOptions {
+  /**
+   * Access token for Meta API authentication (OC|$APP_ID|$APP_SECRET or User Access Token).
+   * ⚠️ Sensitive: Do not log this value.
+   */
+  accessToken: string;
+  /** The SKU for the add-on item, defined in Meta Developer Dashboard */
   sku: string;
+  /** The user ID of the user whose purchase you want to verify */
+  userId: string;
 }
 
-export type VerifyPurchaseResult = VerifyPurchaseResultAndroid | VerifyPurchaseResultIOS;
+/**
+ * Platform-specific purchase verification parameters.
+ *
+ * - apple: Verifies via App Store Server API
+ * - google: Verifies via Google Play Developer API
+ * - horizon: Verifies via Meta's S2S API (verify_entitlement endpoint)
+ */
+export interface VerifyPurchaseProps {
+  /** Apple App Store verification parameters. */
+  apple?: (VerifyPurchaseAppleOptions | null);
+  /** Google Play Store verification parameters. */
+  google?: (VerifyPurchaseGoogleOptions | null);
+  /** Meta Horizon (Quest) verification parameters. */
+  horizon?: (VerifyPurchaseHorizonOptions | null);
+}
+
+export type VerifyPurchaseResult = VerifyPurchaseResultAndroid | VerifyPurchaseResultHorizon | VerifyPurchaseResultIOS;
 
 export interface VerifyPurchaseResultAndroid {
   autoRenewing: boolean;
@@ -1016,6 +1202,17 @@ export interface VerifyPurchaseResultAndroid {
   testTransaction: boolean;
 }
 
+/**
+ * Result from Meta Horizon verify_entitlement API.
+ * Returns verification status and grant time for the entitlement.
+ */
+export interface VerifyPurchaseResultHorizon {
+  /** Unix timestamp (seconds) when the entitlement was granted. */
+  grantTime?: (number | null);
+  /** Whether the entitlement verification succeeded. */
+  success: boolean;
+}
+
 export interface VerifyPurchaseResultIOS {
   /** Whether the receipt is valid */
   isValid: boolean;