expo-iap 4.2.2 → 4.2.4

package/src/types.ts

@@ -585,118 +585,176 @@ export interface LimitedQuantityInfoAndroid {
 }
 
 export interface Mutation {
-  /** Acknowledge a non-consumable purchase or subscription */
+  /**
+   * Acknowledge a non-consumable purchase. Required within 3 days or Google auto-refunds.
+   * See: https://www.openiap.dev/docs/apis/android/acknowledge-purchase-android
+   */
   acknowledgePurchaseAndroid: Promise<boolean>;
-  /** Initiate a refund request for a product (iOS 15+) */
+  /**
+   * Present the refund request sheet (iOS 15+). See also Features → Refund.
+   * See: https://www.openiap.dev/docs/apis/ios/begin-refund-request-ios
+   */
   beginRefundRequestIOS?: Promise<(string | null)>;
   /**
-   * Check if alternative billing is available for this user/device
-   * Step 1 of alternative billing flow
+   * Check whether alternative billing is available for the user. Step 1 of the alternative billing flow.
    *
-   * Returns true if available, false otherwise
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Returns true if available, false otherwise.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/check-alternative-billing-availability-android
    */
   checkAlternativeBillingAvailabilityAndroid: Promise<boolean>;
-  /** Clear pending transactions from the StoreKit payment queue */
+  /**
+   * Clear pending transactions in the queue (sandbox helper).
+   * See: https://www.openiap.dev/docs/apis/ios/clear-transaction-ios
+   */
   clearTransactionIOS: Promise<boolean>;
-  /** Consume a purchase token so it can be repurchased */
+  /**
+   * Consume a consumable purchase so it can be re-bought.
+   * See: https://www.openiap.dev/docs/apis/android/consume-purchase-android
+   */
   consumePurchaseAndroid: Promise<boolean>;
   /**
-   * Create external transaction token for Google Play reporting
-   * Step 3 of alternative billing flow
-   * Must be called AFTER successful payment in your payment system
-   * Token must be reported to Google Play backend within 24 hours
+   * Create a reporting token for an alternative billing flow. Step 3 of the alternative billing flow.
+   * Must be called AFTER successful payment in your payment system.
+   * Token must be reported to Google Play backend within 24 hours.
    *
-   * Returns token string, or null if creation failed
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Returns token string, or null if creation failed.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/create-alternative-billing-token-android
    */
   createAlternativeBillingTokenAndroid?: Promise<(string | null)>;
   /**
-   * Create reporting details for a billing program
-   * Replaces the deprecated createExternalOfferReportingDetailsAsync API
+   * Create the reporting payload Google requires after a Developer-Provided Billing transaction (Play Billing 8.3.0+).
+   * Replaces the deprecated createExternalOfferReportingDetailsAsync API.
    *
-   * Available in Google Play Billing Library 8.2.0+
-   * Returns external transaction token needed for reporting external transactions
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Returns external transaction token needed for reporting external transactions.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/create-billing-program-reporting-details-android
    */
   createBillingProgramReportingDetailsAndroid: Promise<BillingProgramReportingDetailsAndroid>;
-  /** Open the native subscription management surface */
+  /**
+   * Open the platform's subscription management UI.
+   * See: https://www.openiap.dev/docs/apis/deep-link-to-subscriptions
+   */
   deepLinkToSubscriptions: Promise<void>;
-  /** Close the platform billing connection */
+  /**
+   * Close the store connection and release resources.
+   * See: https://www.openiap.dev/docs/apis/end-connection
+   */
   endConnection: Promise<boolean>;
-  /** Finish a transaction after validating receipts */
+  /**
+   * Complete a transaction after server-side verification. Required on Android within 3 days.
+   * See: https://www.openiap.dev/docs/apis/finish-transaction
+   */
   finishTransaction: Promise<void>;
-  /** Establish the platform billing connection */
+  /**
+   * Initialize the store connection. Call before any IAP API.
+   * See: https://www.openiap.dev/docs/apis/init-connection
+   */
   initConnection: Promise<boolean>;
   /**
-   * Check if a billing program is available for the current user
-   * Replaces the deprecated isExternalOfferAvailableAsync API
+   * Check whether a billing program (e.g., External Payments) is available for the current user.
+   * Replaces the deprecated isExternalOfferAvailableAsync API.
    *
-   * Available in Google Play Billing Library 8.2.0+
-   * Returns availability result with isAvailable flag
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Available in Google Play Billing Library 8.2.0+.
+   * Returns availability result with isAvailable flag.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/is-billing-program-available-android
    */
   isBillingProgramAvailableAndroid: Promise<BillingProgramAvailabilityResultAndroid>;
   /**
-   * Launch external link flow for external billing programs
-   * Replaces the deprecated showExternalOfferInformationDialog API
+   * Launch an external content/offer link from inside the Billing Programs flow (Play Billing 8.2.0+).
+   * Replaces the deprecated showExternalOfferInformationDialog API.
    *
-   * Available in Google Play Billing Library 8.2.0+
-   * Shows Play Store dialog and optionally launches external URL
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Shows Play Store dialog and optionally launches external URL.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/launch-external-link-android
    */
   launchExternalLinkAndroid: Promise<boolean>;
-  /** Present the App Store code redemption sheet */
+  /**
+   * Show the App Store offer code redemption sheet.
+   * See: https://www.openiap.dev/docs/apis/ios/present-code-redemption-sheet-ios
+   */
   presentCodeRedemptionSheetIOS: Promise<boolean>;
-  /** Present external purchase custom link with StoreKit UI */
+  /**
+   * Present an external purchase link, StoreKit External (iOS 16+).
+   * See: https://www.openiap.dev/docs/apis/ios/present-external-purchase-link-ios
+   */
   presentExternalPurchaseLinkIOS: Promise<ExternalPurchaseLinkResultIOS>;
   /**
-   * Present external purchase notice sheet (iOS 17.4+).
-   * Uses ExternalPurchase.presentNoticeSheet() which returns a token when user continues.
+   * Present the external purchase notice sheet (iOS 17.4+).
+   * Uses ExternalPurchase.presentNoticeSheet() which returns a token when the user continues.
    * Reference: https://developer.apple.com/documentation/storekit/externalpurchase/presentnoticesheet()
+   * See: https://www.openiap.dev/docs/apis/ios/present-external-purchase-notice-sheet-ios
    */
   presentExternalPurchaseNoticeSheetIOS: Promise<ExternalPurchaseNoticeResultIOS>;
-  /** Initiate a purchase flow; rely on events for final state */
+  /**
+   * Initiate a purchase or subscription flow; rely on events for final state.
+   * See: https://www.openiap.dev/docs/apis/request-purchase
+   */
   requestPurchase?: Promise<(Purchase | Purchase[] | null)>;
   /**
-   * Purchase the promoted product surfaced by the App Store.
+   * Buy the currently promoted product.
    *
    * @deprecated Use promotedProductListenerIOS to receive the productId,
    * then call requestPurchase with that SKU instead. In StoreKit 2,
    * promoted products can be purchased directly via the standard purchase flow.
+   * See: https://www.openiap.dev/docs/apis/ios/request-purchase-on-promoted-product-ios
    * @deprecated Use promotedProductListenerIOS + requestPurchase instead
    */
   requestPurchaseOnPromotedProductIOS: Promise<boolean>;
-  /** Restore completed purchases across platforms */
+  /**
+   * Restore non-consumable and active subscription purchases.
+   * See: https://www.openiap.dev/docs/apis/restore-purchases
+   */
   restorePurchases: Promise<void>;
   /**
-   * Show alternative billing information dialog to user
-   * Step 2 of alternative billing flow
-   * Must be called BEFORE processing payment in your payment system
+   * Display Google's alternative billing information dialog. Step 2 of the alternative billing flow.
+   * Must be called BEFORE processing payment in your payment system.
    *
-   * Returns true if user accepted, false if user canceled
-   * Throws OpenIapError.NotPrepared if billing client not ready
+   * Returns true if user accepted, false if user canceled.
+   * Throws OpenIapError.NotPrepared if billing client not ready.
+   * See: https://www.openiap.dev/docs/apis/android/show-alternative-billing-dialog-android
    */
   showAlternativeBillingDialogAndroid: Promise<boolean>;
   /**
-   * Show ExternalPurchaseCustomLink notice sheet (iOS 18.1+).
-   * Displays the system disclosure notice sheet for custom external purchase links.
+   * Present the disclosure sheet required before linking out via ExternalPurchaseCustomLink (iOS 18.1+).
    * Call this after a deliberate customer interaction before linking out to external purchases.
    * Reference: https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/shownotice(type:)
+   * See: https://www.openiap.dev/docs/apis/ios/show-external-purchase-custom-link-notice-ios
    */
   showExternalPurchaseCustomLinkNoticeIOS: Promise<ExternalPurchaseCustomLinkNoticeResultIOS>;
-  /** Open subscription management UI and return changed purchases (iOS 15+) */
+  /**
+   * Present the manage-subscriptions sheet and return changed purchases (iOS 15+).
+   * See: https://www.openiap.dev/docs/apis/ios/show-manage-subscriptions-ios
+   */
   showManageSubscriptionsIOS: Promise<PurchaseIOS[]>;
-  /** Force a StoreKit sync for transactions (iOS 15+) */
+  /**
+   * Force sync transactions with the App Store (iOS 15+).
+   * See: https://www.openiap.dev/docs/apis/ios/sync-ios
+   */
   syncIOS: Promise<boolean>;
   /**
-   * Validate purchase receipts with the configured providers
+   * Deprecated. Validate purchase receipts with the configured providers — use verifyPurchase instead.
+   * See: https://www.openiap.dev/docs/features/validation#verify-purchase
    * @deprecated Use verifyPurchase
    */
   validateReceipt: Promise<VerifyPurchaseResult>;
-  /** Verify purchases with the configured providers */
+  /**
+   * Verify a purchase against your own backend. Returns a platform-specific
+   * variant of VerifyPurchaseResult — VerifyPurchaseResultIOS exposes isValid
+   * + receipt/JWS metadata, VerifyPurchaseResultAndroid carries Play Store
+   * receipt fields (no isValid), and VerifyPurchaseResultHorizon uses success.
+   * Inspect the concrete variant before reading fields.
+   * See: https://www.openiap.dev/docs/features/validation#verify-purchase
+   */
   verifyPurchase: Promise<VerifyPurchaseResult>;
-  /** Verify purchases with a specific provider (e.g., IAPKit) */
+  /**
+   * Verify via a managed provider without standing up your own server. The
+   * PurchaseVerificationProvider enum currently exposes only IAPKit; platform
+   * availability may differ by implementation.
+   * See: https://www.openiap.dev/docs/features/validation#verify-purchase-with-provider
+   */
   verifyPurchaseWithProvider: Promise<VerifyPurchaseWithProviderResult>;
 }
 
@@ -1234,66 +1292,117 @@ export type PurchaseVerificationProvider = 'iapkit';
 
 export interface Query {
   /**
-   * Check if external purchase notice sheet can be presented (iOS 17.4+)
-   * Uses ExternalPurchase.canPresent
+   * Check eligibility for the external purchase notice sheet (iOS 17.4+).
+   * Uses ExternalPurchase.canPresent.
+   * See: https://www.openiap.dev/docs/apis/ios/can-present-external-purchase-notice-ios
    */
   canPresentExternalPurchaseNoticeIOS: Promise<boolean>;
-  /** Get current StoreKit 2 entitlements (iOS 15+) */
+  /**
+   * Get the user's current entitlement for a product, using StoreKit 2 (iOS 15+).
+   * See: https://www.openiap.dev/docs/apis/ios/current-entitlement-ios
+   */
   currentEntitlementIOS?: Promise<(PurchaseIOS | null)>;
-  /** Retrieve products or subscriptions from the store */
+  /**
+   * Fetch products or subscriptions from the store.
+   * See: https://www.openiap.dev/docs/apis/fetch-products
+   */
   fetchProducts: Promise<(ProductOrSubscription[] | Product[] | ProductSubscription[] | null)>;
-  /** Get active subscriptions (filters by subscriptionIds when provided) */
+  /**
+   * Get details of all currently active subscriptions (filters by subscriptionIds when provided).
+   * See: https://www.openiap.dev/docs/apis/get-active-subscriptions
+   */
   getActiveSubscriptions: Promise<ActiveSubscription[]>;
   /**
-   * Get the full StoreKit 2 transaction history as PurchaseIOS values.
+   * List every StoreKit transaction (finished + unfinished) for the current user.
    * Requires the SK2ConsumableTransactionHistory Info.plist key in the host app
    * for finished consumables to be included (iOS 18+).
    * Unlike getAvailablePurchases, always returns the iOS-specific PurchaseIOS shape.
+   * See: https://www.openiap.dev/docs/apis/ios/get-all-transactions-ios
    */
   getAllTransactionsIOS: Promise<PurchaseIOS[]>;
-  /** Fetch the current app transaction (iOS 16+) */
+  /**
+   * Fetch the app transaction (iOS 16+).
+   * See: https://www.openiap.dev/docs/apis/ios/get-app-transaction-ios
+   */
   getAppTransactionIOS?: Promise<(AppTransaction | null)>;
-  /** Get all available purchases for the current user */
+  /**
+   * List active purchases for the current user.
+   * See: https://www.openiap.dev/docs/apis/get-available-purchases
+   */
   getAvailablePurchases: Promise<Purchase[]>;
   /**
-   * Get external purchase token for reporting to Apple (iOS 18.1+).
-   * Use this token with Apple's External Purchase Server API to report transactions.
+   * Fetch a token for Apple's External Purchase Server reporting API (iOS 18.1+).
+   * Use this token to report transactions made through ExternalPurchaseCustomLink.
    * Reference: https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/token(for:)
+   * See: https://www.openiap.dev/docs/apis/ios/get-external-purchase-custom-link-token-ios
    */
   getExternalPurchaseCustomLinkTokenIOS: Promise<ExternalPurchaseCustomLinkTokenResultIOS>;
-  /** Retrieve all pending transactions in the StoreKit queue */
+  /**
+   * List unfinished StoreKit transactions in the queue.
+   * See: https://www.openiap.dev/docs/apis/ios/get-pending-transactions-ios
+   */
   getPendingTransactionsIOS: Promise<PurchaseIOS[]>;
-  /** Get the currently promoted product (iOS 11+) */
+  /**
+   * Read the App Store-promoted product, if any (iOS 11+).
+   * See: https://www.openiap.dev/docs/apis/ios/get-promoted-product-ios
+   */
   getPromotedProductIOS?: Promise<(ProductIOS | null)>;
-  /** Get base64-encoded receipt data for validation */
+  /**
+   * Get base64-encoded receipt data (legacy validation).
+   * See: https://www.openiap.dev/docs/apis/ios/get-receipt-data-ios
+   */
   getReceiptDataIOS?: Promise<(string | null)>;
-  /** Get the current storefront country code */
+  /**
+   * Return the user's storefront country code.
+   * See: https://www.openiap.dev/docs/apis/get-storefront
+   */
   getStorefront: Promise<string>;
   /**
-   * Get the current App Store storefront country code
+   * Deprecated. Get the current App Store storefront country code — use cross-platform getStorefront instead.
+   * See: https://www.openiap.dev/docs/apis/ios/get-storefront-ios
    * @deprecated Use getStorefront
    */
   getStorefrontIOS: Promise<string>;
-  /** Get the transaction JWS (StoreKit 2) */
+  /**
+   * Return the JWS string for a transaction (StoreKit 2).
+   * See: https://www.openiap.dev/docs/apis/ios/get-transaction-jws-ios
+   */
   getTransactionJwsIOS?: Promise<(string | null)>;
-  /** Check whether the user has active subscriptions */
+  /**
+   * Check whether the user has any active subscription.
+   * See: https://www.openiap.dev/docs/apis/has-active-subscriptions
+   */
   hasActiveSubscriptions: Promise<boolean>;
   /**
-   * Check if app is eligible for ExternalPurchaseCustomLink API (iOS 18.1+).
+   * Check eligibility for the custom-link variant of external purchase (iOS 18.1+).
    * Returns true if the app can use custom external purchase links.
    * Reference: https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/iseligible
+   * See: https://www.openiap.dev/docs/apis/ios/is-eligible-for-external-purchase-custom-link-ios
    */
   isEligibleForExternalPurchaseCustomLinkIOS: Promise<boolean>;
-  /** Check introductory offer eligibility for a subscription group */
+  /**
+   * Check intro-offer eligibility for a subscription group.
+   * See: https://www.openiap.dev/docs/apis/ios/is-eligible-for-intro-offer-ios
+   */
   isEligibleForIntroOfferIOS: Promise<boolean>;
-  /** Verify a StoreKit 2 transaction signature */
+  /**
+   * Check whether a transaction's JWS verification passed (StoreKit 2).
+   * See: https://www.openiap.dev/docs/apis/ios/is-transaction-verified-ios
+   */
   isTransactionVerifiedIOS: Promise<boolean>;
-  /** Get the latest transaction for a product using StoreKit 2 */
+  /**
+   * Get the latest verified transaction for a product, using StoreKit 2.
+   * See: https://www.openiap.dev/docs/apis/ios/latest-transaction-ios
+   */
   latestTransactionIOS?: Promise<(PurchaseIOS | null)>;
-  /** Get StoreKit 2 subscription status details (iOS 15+) */
+  /**
+   * Get subscription status objects from StoreKit 2 (iOS 15+).
+   * See: https://www.openiap.dev/docs/apis/ios/subscription-status-ios
+   */
   subscriptionStatusIOS: Promise<SubscriptionStatusIOS[]>;
   /**
-   * Validate a receipt for a specific product
+   * Deprecated. Legacy App Store receipt validation — use verifyPurchase instead.
+   * See: https://www.openiap.dev/docs/apis/ios/validate-receipt-ios
    * @deprecated Use verifyPurchase
    */
   validateReceiptIOS: Promise<VerifyPurchaseResultIOS>;
@@ -1787,6 +1896,8 @@ export interface SubscriptionProductReplacementParamsAndroid {
  */
 export type SubscriptionReplacementModeAndroid = 'unknown-replacement-mode' | 'with-time-proration' | 'charge-prorated-price' | 'charge-full-price' | 'without-proration' | 'deferred' | 'keep-existing';
 
+export type SubscriptionState = 'active' | 'expired' | 'in-billing-retry' | 'in-grace-period' | 'paused' | 'refunded' | 'revoked' | 'unknown';
+
 export interface SubscriptionStatusIOS {
   renewalInfo?: (RenewalInfoIOS | null);
   state: string;
@@ -1948,6 +2059,67 @@ export interface VerifyPurchaseWithProviderResult {
 
 export type VoidResult = void;
 
+export type WebhookCancellationReason = 'billing-error' | 'other' | 'price-increase-declined' | 'product-unavailable' | 'refunded' | 'user-canceled';
+
+export interface WebhookEvent {
+  /** Reason for cancellation, when applicable. */
+  cancellationReason?: (WebhookCancellationReason | null);
+  /** Localized currency code (ISO 4217) at event time, when available. */
+  currency?: (string | null);
+  environment: WebhookEventEnvironment;
+  /** When the current subscription period ends. Epoch milliseconds. */
+  expiresAt?: (number | null);
+  /**
+   * Stable identifier suitable for idempotency. Derived from the source notification
+   * UUID where the store provides one (ASN v2 `notificationUUID`, RTDN message id);
+   * otherwise hashed from the canonicalized payload.
+   */
+  id: string;
+  /** Time the underlying event occurred at the store. Epoch milliseconds. */
+  occurredAt: number;
+  platform: IapPlatform;
+  /**
+   * Price in micros (1/1,000,000 of the currency unit) at event time, when available.
+   * Matches Google Play's `priceAmountMicros` convention; iOS values are converted.
+   */
+  priceAmountMicros?: (number | null);
+  /** Product the event pertains to. May be null for account-level events. */
+  productId?: (string | null);
+  /** kit project that owns the subscription / purchase this event refers to. */
+  projectId: string;
+  /**
+   * Cross-platform purchase identity used to correlate this event with an existing
+   * purchase record. iOS: `originalTransactionId`. Android: `purchaseToken`.
+   * Null for `TestNotification` events (Apple ASN v2 / Google RTDN test
+   * payloads carry no transaction); always present for every other event type.
+   */
+  purchaseToken?: (string | null);
+  /**
+   * Original signed payload from the store. ASN v2 events expose the JWS string;
+   * RTDN events expose the base64-decoded Pub/Sub message JSON. Provided so that
+   * consumers can independently verify or extract platform-specific fields. kit
+   * always validates this payload before emitting the event.
+   */
+  rawSignedPayload?: (string | null);
+  /** Time kit ingested and normalized this event. Epoch milliseconds. */
+  receivedAt: number;
+  /** When auto-renewal will charge again. Epoch milliseconds. */
+  renewsAt?: (number | null);
+  source: WebhookEventSource;
+  /**
+   * Normalized subscription state at the time of event, when the event refers to
+   * a subscription. Null for one-time purchase events.
+   */
+  subscriptionState?: (SubscriptionState | null);
+  type: WebhookEventType;
+}
+
+export type WebhookEventEnvironment = 'production' | 'sandbox' | 'xcode';
+
+export type WebhookEventSource = 'apple-app-store-server-notifications-v2' | 'google-play-real-time-developer-notifications' | 'meta-horizon-reconciler';
+
+export type WebhookEventType = 'purchase-consumption-request' | 'purchase-refunded' | 'subscription-canceled' | 'subscription-expired' | 'subscription-in-billing-retry' | 'subscription-in-grace-period' | 'subscription-paused' | 'subscription-price-change' | 'subscription-product-changed' | 'subscription-recovered' | 'subscription-renewed' | 'subscription-resumed' | 'subscription-revoked' | 'subscription-started' | 'subscription-uncanceled' | 'test-notification';
+
 /**
  * Win-back offer input for iOS 18+ (StoreKit 2)
  * Win-back offers are used to re-engage churned subscribers.

package/src/useIAP.ts

@@ -252,6 +252,30 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     }
   }, []);
 
+  /**
+   * Retrieve products or subscriptions from the store by SKU.
+   *
+   * @param params `ProductRequest` — `skus` (string[]) and optional `type`
+   *   (`'in-app' | 'subs' | 'all'`, defaults to `'in-app'`).
+   * @returns Promise that resolves when the request is dispatched; results land in the
+   *   hook's reactive `products` / `subscriptions` state.
+   * @throws When the store rejects the request (empty `skus`, not connected,
+   *   network/store error). Unknown SKUs are simply omitted from the result, not thrown.
+   *
+   * @example
+   * ```ts
+   * const { fetchProducts, products } = useIAP();
+   * await fetchProducts({
+   *   skus: ['com.app.coins_100', 'com.app.premium'],
+   *   type: 'in-app',
+   * });
+   * ```
+   *
+   * @remarks This is a regular promise-based call. Don't confuse with `request*` APIs
+   *   (`requestPurchase`), which are event-based.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/fetch-products}
+   */
   const fetchProductsInternal = useCallback(
     async (params: {
       skus: string[];
@@ -349,6 +373,27 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     ],
   );
 
+  /**
+   * List the user's unfinished purchases — non-consumables, active subscriptions, and any
+   * pending transactions not yet finished.
+   *
+   * @param options Optional `PurchaseOptions`. iOS-only flags:
+   *   `alsoPublishToEventListenerIOS`, `onlyIncludeActiveItemsIOS`.
+   * @returns Promise that resolves when the request is dispatched; results land in the
+   *   hook's reactive `availablePurchases` state.
+   * @throws When the platform query fails.
+   *
+   * @example
+   * ```ts
+   * const { getAvailablePurchases, availablePurchases } = useIAP();
+   * await getAvailablePurchases();
+   * for (const p of availablePurchases) {
+   *   if (await verifyOnServer(p)) await finishTransaction({ purchase: p, isConsumable: false });
+   * }
+   * ```
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/get-available-purchases}
+   */
   const getAvailablePurchasesInternal = useCallback(
     async (options?: PurchaseOptions): Promise<void> => {
       try {
@@ -368,6 +413,11 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     [invokeOnError],
   );
 
+  /**
+   * Get details of all currently active subscriptions.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/get-active-subscriptions}
+   */
   const getActiveSubscriptionsInternal = useCallback(
     async (subscriptionIds?: string[]): Promise<void> => {
       try {
@@ -382,6 +432,11 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     [invokeOnError],
   );
 
+  /**
+   * Check whether the user has any active subscription.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/has-active-subscriptions}
+   */
   const hasActiveSubscriptionsInternal = useCallback(
     async (subscriptionIds?: string[]): Promise<boolean> => {
       try {
@@ -394,6 +449,29 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     [],
   );
 
+  /**
+   * Complete a purchase transaction. Call after server-side verification to remove it
+   * from the queue.
+   *
+   * @param args.purchase The `Purchase` to finalize.
+   * @param args.isConsumable `true` for consumables (consumes the token so the SKU can be
+   *   re-bought, e.g. coins); `false` (default) for non-consumables and subscriptions.
+   * @returns Promise that resolves once the platform finalizes the transaction.
+   * @throws When the platform finalize call fails.
+   *
+   * @example
+   * ```ts
+   * // Inside purchaseUpdatedListener:
+   * if (await verifyOnServer(purchase)) {
+   *   await finishTransaction({ purchase, isConsumable: false });
+   * }
+   * ```
+   *
+   * @remarks **Critical:** Android purchases must be finalized within 3 days or Google
+   *   auto-refunds. iOS unfinished transactions replay on every app launch.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/finish-transaction}
+   */
   const finishTransaction = useCallback(
     async ({
       purchase,
@@ -410,6 +488,33 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     [toPurchaseInput],
   );
 
+  /**
+   * Initiate a purchase or subscription flow. The result is delivered through
+   * `purchaseUpdatedListener` — NOT the return value.
+   *
+   * @param props `RequestPurchaseProps`, discriminated by `type`:
+   *   - `type: 'in-app'` — pass `request.apple.sku` (iOS) and/or `request.google.skus` (Android).
+   *   - `type: 'subs'`  — same shape, plus `request.google.subscriptionOffers: [{ sku, offerToken }]`.
+   * @returns Promise that resolves when the request is dispatched; the actual purchase
+   *   outcome lands in the hook's `onPurchaseSuccess` / `onPurchaseError` callbacks.
+   * @throws Synchronous rejection from the store (e.g. `E_NOT_PREPARED`, validation failure).
+   *
+   * @example
+   * ```ts
+   * await requestPurchase({
+   *   request: {
+   *     apple: { sku: 'com.app.premium' },
+   *     google: { skus: ['com.app.premium'] },
+   *   },
+   *   type: 'in-app',
+   * });
+   * ```
+   *
+   * @remarks Event-based. Listen for the result via {@link purchaseUpdatedListener} /
+   *   {@link purchaseErrorListener}, or use `useIAP({ onPurchaseSuccess, onPurchaseError })`.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/request-purchase}
+   */
   const requestPurchaseWithReset = useCallback(
     (requestObj: MutationRequestPurchaseArgs) => {
       return requestPurchaseInternal(requestObj);
@@ -436,9 +541,11 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     ],
   );
 
-  // Restore completed transactions with cross-platform behavior.
-  // iOS: best-effort sync (ignore sync errors) then fetch available purchases.
-  // Android: fetch available purchases directly.
+  /**
+   * Restore non-consumable and active subscription purchases.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/restore-purchases}
+   */
   const restorePurchasesInternal = useCallback(
     async (options?: PurchaseOptions): Promise<void> => {
       try {
@@ -463,14 +570,29 @@ export function useIAP(options?: UseIAPOptions): UseIap {
     [invokeOnError],
   );
 
+  /**
+   * Deprecated. Use verifyPurchase instead — same input/output shape.
+   *
+   * @see {@link https://www.openiap.dev/docs/apis/validate-receipt}
+   */
   const validateReceipt = useCallback(async (props: VerifyPurchaseProps) => {
     return validateReceiptInternal(props);
   }, []);
 
+  /**
+   * Verify a purchase against your own backend (returns isValid + raw store metadata).
+   *
+   * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase}
+   */
   const verifyPurchase = useCallback(async (props: VerifyPurchaseProps) => {
     return verifyPurchaseInternal(props);
   }, []);
 
+  /**
+   * Verify via a managed provider — currently only `iapkit` (IAPKit). The PurchaseVerificationProvider enum exposes no other provider literal today.
+   *
+   * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase-with-provider}
+   */
   const verifyPurchaseWithProvider = useCallback(
     async (props: VerifyPurchaseWithProviderProps) => {
       return verifyPurchaseWithProviderInternal(props);