expo-iap 3.2.0 → 3.2.2

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);
@@ -72,6 +104,34 @@ export interface DeepLinkOptions {
   skuAndroid?: (string | null);
 }
 
+/**
+ * Discount amount details for one-time purchase offers (Android)
+ * Available in Google Play Billing Library 7.0+
+ */
+export interface DiscountAmountAndroid {
+  /** Discount amount in micro-units (1,000,000 = 1 unit of currency) */
+  discountAmountMicros: string;
+  /** Formatted discount amount with currency sign (e.g., "$4.99") */
+  formattedDiscountAmount: string;
+}
+
+/**
+ * Discount display information for one-time purchase offers (Android)
+ * Available in Google Play Billing Library 7.0+
+ */
+export interface DiscountDisplayInfoAndroid {
+  /**
+   * Absolute discount amount details
+   * Only returned for fixed amount discounts
+   */
+  discountAmount?: (DiscountAmountAndroid | null);
+  /**
+   * Percentage discount (e.g., 33 for 33% off)
+   * Only returned for percentage-based discounts
+   */
+  percentageDiscount?: (number | null);
+}
+
 export interface DiscountIOS {
   identifier: string;
   localizedPrice?: (string | null);
@@ -155,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 */
@@ -194,6 +288,33 @@ 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+
+ */
+export interface LimitedQuantityInfoAndroid {
+  /** Maximum quantity a user can purchase */
+  maximumQuantity: number;
+  /** Remaining quantity the user can still purchase */
+  remainingQuantity: number;
+}
+
 export interface Mutation {
   /** Acknowledge a non-consumable purchase or subscription */
   acknowledgePurchaseAndroid: Promise<boolean>;
@@ -310,6 +431,23 @@ export type MutationVerifyPurchaseWithProviderArgs = VerifyPurchaseWithProviderP
 
 export type PaymentModeIOS = 'empty' | 'free-trial' | 'pay-as-you-go' | 'pay-up-front';
 
+/**
+ * Pre-order details for one-time purchase products (Android)
+ * Available in Google Play Billing Library 8.1.0+
+ */
+export interface PreorderDetailsAndroid {
+  /**
+   * Pre-order presale end time in milliseconds since epoch.
+   * This is when the presale period ends and the product will be released.
+   */
+  preorderPresaleEndTimeMillis: string;
+  /**
+   * Pre-order release time in milliseconds since epoch.
+   * This is when the product will be available to users who pre-ordered.
+   */
+  preorderReleaseTimeMillis: string;
+}
+
 export interface PricingPhaseAndroid {
   billingCycleCount: number;
   billingPeriod: string;
@@ -333,7 +471,11 @@ export interface ProductAndroid extends ProductCommon {
   displayPrice: string;
   id: string;
   nameAndroid: string;
-  oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail | null);
+  /**
+   * One-time purchase offer details including discounts (Android)
+   * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+   */
+  oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail[] | null);
   platform: 'android';
   price?: (number | null);
   subscriptionOfferDetailsAndroid?: (ProductSubscriptionAndroidOfferDetails[] | null);
@@ -341,10 +483,41 @@ export interface ProductAndroid extends ProductCommon {
   type: 'in-app';
 }
 
+/**
+ * One-time purchase offer details (Android)
+ * Available in Google Play Billing Library 7.0+
+ */
 export interface ProductAndroidOneTimePurchaseOfferDetail {
+  /**
+   * Discount display information
+   * Only available for discounted offers
+   */
+  discountDisplayInfo?: (DiscountDisplayInfoAndroid | null);
   formattedPrice: string;
+  /**
+   * Full (non-discounted) price in micro-units
+   * Only available for discounted offers
+   */
+  fullPriceMicros?: (string | null);
+  /** Limited quantity information */
+  limitedQuantityInfo?: (LimitedQuantityInfoAndroid | null);
+  /** Offer ID */
+  offerId?: (string | null);
+  /** List of offer tags */
+  offerTags: string[];
+  /** Offer token for use in BillingFlowParams when purchasing */
+  offerToken: string;
+  /**
+   * Pre-order details for products available for pre-order
+   * Available in Google Play Billing Library 8.1.0+
+   */
+  preorderDetailsAndroid?: (PreorderDetailsAndroid | null);
   priceAmountMicros: string;
   priceCurrencyCode: string;
+  /** Rental details for rental offers */
+  rentalDetailsAndroid?: (RentalDetailsAndroid | null);
+  /** Valid time window for the offer */
+  validTimeWindow?: (ValidTimeWindowAndroid | null);
 }
 
 export interface ProductCommon {
@@ -397,7 +570,11 @@ export interface ProductSubscriptionAndroid extends ProductCommon {
   displayPrice: string;
   id: string;
   nameAndroid: string;
-  oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail | null);
+  /**
+   * One-time purchase offer details including discounts (Android)
+   * Returns all eligible offers. Available in Google Play Billing Library 7.0+
+   */
+  oneTimePurchaseOfferDetailsAndroid?: (ProductAndroidOneTimePurchaseOfferDetail[] | null);
   platform: 'android';
   price?: (number | null);
   subscriptionOfferDetailsAndroid: ProductSubscriptionAndroidOfferDetails[];
@@ -454,13 +631,18 @@ export interface PurchaseAndroid extends PurchaseCommon {
   ids?: (string[] | null);
   isAcknowledgedAndroid?: (boolean | null);
   isAutoRenewing: boolean;
+  /**
+   * Whether the subscription is suspended (Android)
+   * A suspended subscription means the user's payment method failed and they need to fix it.
+   * Users should be directed to the subscription center to resolve the issue.
+   * Do NOT grant entitlements for suspended subscriptions.
+   * Available in Google Play Billing Library 8.1.0+
+   */
+  isSuspendedAndroid?: (boolean | null);
   obfuscatedAccountIdAndroid?: (string | null);
   obfuscatedProfileIdAndroid?: (string | null);
   packageNameAndroid?: (string | null);
-  /**
-   * @deprecated Use store instead
-   * @deprecated Use store instead
-   */
+  /** @deprecated Use store instead */
   platform: IapPlatform;
   productId: string;
   purchaseState: PurchaseState;
@@ -484,10 +666,7 @@ export interface PurchaseCommon {
   id: string;
   ids?: (string[] | null);
   isAutoRenewing: boolean;
-  /**
-   * @deprecated Use store instead
-   * @deprecated Use store instead
-   */
+  /** @deprecated Use store instead */
   platform: IapPlatform;
   productId: string;
   purchaseState: PurchaseState;
@@ -522,10 +701,7 @@ export interface PurchaseIOS extends PurchaseCommon {
   originalTransactionDateIOS?: (number | null);
   originalTransactionIdentifierIOS?: (string | null);
   ownershipTypeIOS?: (string | null);
-  /**
-   * @deprecated Use store instead
-   * @deprecated Use store instead
-   */
+  /** @deprecated Use store instead */
   platform: IapPlatform;
   productId: string;
   purchaseState: PurchaseState;
@@ -687,6 +863,20 @@ export interface RenewalInfoIOS {
   willAutoRenew: boolean;
 }
 
+/**
+ * Rental details for one-time purchase products that can be rented (Android)
+ * Available in Google Play Billing Library 7.0+
+ */
+export interface RentalDetailsAndroid {
+  /**
+   * Rental expiration period in ISO 8601 format
+   * Time after rental period ends when user can still extend
+   */
+  rentalExpirationPeriod?: (string | null);
+  /** Rental period in ISO 8601 format (e.g., P7D for 7 days) */
+  rentalPeriod: string;
+}
+
 export interface RequestPurchaseAndroidProps {
   /** Personalized offer flag */
   isOfferPersonalized?: (boolean | null);
@@ -727,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);
@@ -749,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 {
@@ -765,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);
@@ -786,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);
 }
 
@@ -844,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;
@@ -860,21 +1099,87 @@ export interface UserChoiceBillingDetails {
   products: string[];
 }
 
-export interface VerifyPurchaseAndroidOptions {
+/**
+ * Valid time window for when an offer is available (Android)
+ * Available in Google Play Billing Library 7.0+
+ */
+export interface ValidTimeWindowAndroid {
+  /** End time in milliseconds since epoch */
+  endTimeMillis: string;
+  /** Start time in milliseconds since epoch */
+  startTimeMillis: string;
+}
+
+/**
+ * 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;
@@ -897,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;