expo-iap 3.1.38 → 3.2.1

package/build/types.d.ts

@@ -56,12 +56,67 @@ export interface AppTransaction {
     preorderDate?: (number | null);
     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);
     /** Android SKU to open (required on Android) */
     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);
@@ -140,6 +195,36 @@ export declare enum ErrorCode {
     UserCancelled = "user-cancelled",
     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 */
@@ -159,9 +244,9 @@ export interface ExternalPurchaseNoticeResultIOS {
 export type FetchProductsResult = ProductOrSubscription[] | Product[] | ProductSubscription[] | null;
 export type IapEvent = 'purchase-updated' | 'purchase-error' | 'promoted-product-ios' | 'user-choice-billing-android';
 export type IapPlatform = 'ios' | 'android';
+export type IapStore = 'unknown' | 'apple' | 'google' | 'horizon';
 /** Unified purchase states from IAPKit verification response. */
 export type IapkitPurchaseState = 'entitled' | 'pending-acknowledgment' | 'pending' | 'canceled' | 'expired' | 'ready-to-consume' | 'consumed' | 'unknown' | 'inauthentic';
-export type IapkitStore = 'apple' | 'google';
 /** Connection initialization configuration */
 export interface InitConnectionConfig {
     /**
@@ -170,6 +255,31 @@ 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>;
@@ -267,6 +377,22 @@ export type MutationValidateReceiptArgs = VerifyPurchaseProps;
 export type MutationVerifyPurchaseArgs = VerifyPurchaseProps;
 export type MutationVerifyPurchaseWithProviderArgs = VerifyPurchaseWithProviderProps;
 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;
@@ -287,17 +413,52 @@ 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);
     title: string;
     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 {
     currency: string;
@@ -343,7 +504,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[];
@@ -394,15 +559,26 @@ 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 */
     platform: IapPlatform;
     productId: string;
     purchaseState: PurchaseState;
     purchaseToken?: (string | null);
     quantity: number;
     signatureAndroid?: (string | null);
+    /** Store where purchase was made */
+    store: IapStore;
     transactionDate: number;
     transactionId?: (string | null);
 }
@@ -417,12 +593,15 @@ export interface PurchaseCommon {
     id: string;
     ids?: (string[] | null);
     isAutoRenewing: boolean;
+    /** @deprecated Use store instead */
     platform: IapPlatform;
     productId: string;
     purchaseState: PurchaseState;
     /** Unified purchase token (iOS JWS, Android purchaseToken) */
     purchaseToken?: (string | null);
     quantity: number;
+    /** Store where purchase was made */
+    store: IapStore;
     transactionDate: number;
 }
 export interface PurchaseError {
@@ -447,6 +626,7 @@ export interface PurchaseIOS extends PurchaseCommon {
     originalTransactionDateIOS?: (number | null);
     originalTransactionIdentifierIOS?: (string | null);
     ownershipTypeIOS?: (string | null);
+    /** @deprecated Use store instead */
     platform: IapPlatform;
     productId: string;
     purchaseState: PurchaseState;
@@ -458,6 +638,8 @@ export interface PurchaseIOS extends PurchaseCommon {
     renewalInfoIOS?: (RenewalInfoIOS | null);
     revocationDateIOS?: (number | null);
     revocationReasonIOS?: (string | null);
+    /** Store where purchase was made */
+    store: IapStore;
     storefrontCountryCodeIOS?: (string | null);
     subscriptionGroupIdIOS?: (string | null);
     transactionDate: number;
@@ -584,6 +766,19 @@ export interface RenewalInfoIOS {
     renewalOfferType?: (string | null);
     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);
@@ -619,10 +814,22 @@ export type RequestPurchaseProps = {
     /** Use alternative billing (Google Play alternative billing, Apple external purchase link) */
     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 {
-    /** Android-specific purchase parameters */
+    /** @deprecated Use google instead */
     android?: (RequestPurchaseAndroidProps | null);
-    /** iOS-specific purchase parameters */
+    /** Apple-specific purchase parameters */
+    apple?: (RequestPurchaseIosProps | null);
+    /** Google-specific purchase parameters */
+    google?: (RequestPurchaseAndroidProps | null);
+    /** @deprecated Use apple instead */
     ios?: (RequestPurchaseIosProps | null);
 }
 export type RequestPurchaseResult = Purchase | Purchase[] | null;
@@ -635,12 +842,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 {
     andDangerouslyFinishTransactionAutomatically?: (boolean | null);
@@ -649,10 +864,22 @@ export interface RequestSubscriptionIosProps {
     sku: string;
     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 {
-    /** Android-specific subscription parameters */
+    /** @deprecated Use google instead */
     android?: (RequestSubscriptionAndroidProps | null);
-    /** iOS-specific subscription parameters */
+    /** Apple-specific subscription parameters */
+    apple?: (RequestSubscriptionIosProps | null);
+    /** Google-specific subscription parameters */
+    google?: (RequestSubscriptionAndroidProps | null);
+    /** @deprecated Use apple instead */
     ios?: (RequestSubscriptionIosProps | null);
 }
 export interface RequestVerifyPurchaseWithIapkitAppleProps {
@@ -663,12 +890,18 @@ export interface RequestVerifyPurchaseWithIapkitGoogleProps {
     /** The token provided to the user's device when the product or subscription was purchased. */
     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);
 }
 export interface RequestVerifyPurchaseWithIapkitResult {
@@ -676,7 +909,7 @@ export interface RequestVerifyPurchaseWithIapkitResult {
     isValid: boolean;
     /** The current state of the purchase. */
     state: IapkitPurchaseState;
-    store: IapkitStore;
+    store: IapStore;
 }
 export interface Subscription {
     /** Fires when the App Store surfaces a promoted product (iOS only) */
@@ -712,6 +945,23 @@ export interface SubscriptionPeriodValueIOS {
     unit: SubscriptionPeriodIOS;
     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;
@@ -726,19 +976,82 @@ export interface UserChoiceBillingDetails {
     /** List of product IDs selected by the user */
     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;
-}
-export interface VerifyPurchaseProps {
-    /** Android-specific validation options */
-    androidOptions?: (VerifyPurchaseAndroidOptions | null);
+    /**
+     * Purchase token from the purchase response.
+     * ⚠️ Sensitive: Do not log this value.
+     */
+    purchaseToken: string;
     /** Product SKU to validate */
     sku: string;
 }
-export type VerifyPurchaseResult = VerifyPurchaseResultAndroid | VerifyPurchaseResultIOS;
+/**
+ * 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;
+}
+/**
+ * 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;
     betaProduct: boolean;
@@ -759,6 +1072,16 @@ export interface VerifyPurchaseResultAndroid {
     termSku: string;
     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;
@@ -769,13 +1092,19 @@ export interface VerifyPurchaseResultIOS {
     /** Receipt data string */
     receiptData: string;
 }
+export interface VerifyPurchaseWithProviderError {
+    code?: (string | null);
+    message: string;
+}
 export interface VerifyPurchaseWithProviderProps {
     iapkit?: (RequestVerifyPurchaseWithIapkitProps | null);
     provider: PurchaseVerificationProvider;
 }
 export interface VerifyPurchaseWithProviderResult {
-    /** IAPKit verification results (can include Apple and Google entries) */
-    iapkit: RequestVerifyPurchaseWithIapkitResult[];
+    /** Error details if verification failed */
+    errors?: (VerifyPurchaseWithProviderError[] | null);
+    /** IAPKit verification result */
+    iapkit?: (RequestVerifyPurchaseWithIapkitResult | null);
     provider: PurchaseVerificationProvider;
 }
 export type VoidResult = void;