react-native-iap 15.1.0 → 15.2.1

package/lib/module/index.js

@@ -39,7 +39,9 @@ const toErrorMessage = error => {
 
 // Export hooks
 export { useIAP } from "./hooks/useIAP.js";
-
+export { useWebhookEvents } from "./hooks/useWebhookEvents.js";
+export { connectWebhookStream, parseWebhookEventData } from "./webhook-client.js";
+export { kitApi, KitApiError } from "./kit-api.js";
 // Restore completed transactions (cross-platform)
 // Development utilities removed - use type bridge functions directly if needed
 
@@ -170,12 +172,14 @@ export const resetListenerState = () => {
   promotedProductNativeAttached = false;
   userChoiceBillingNativeAttached = false;
   developerProvidedBillingNativeAttached = false;
+  subscriptionBillingIssueNativeAttached = false;
   // Clear all JS listeners since native side clears them in endConnection
   purchaseUpdateJsListeners.clear();
   purchaseErrorJsListeners.clear();
   promotedProductJsListeners.clear();
   userChoiceBillingJsListeners.clear();
   developerProvidedBillingJsListeners.clear();
+  subscriptionBillingIssueJsListeners.clear();
 };
 export const purchaseUpdatedListener = listener => {
   purchaseUpdateJsListeners.add(listener);
@@ -388,25 +392,105 @@ export const developerProvidedBillingListenerAndroid = listener => {
   };
 };
 
+/**
+ * Listen for subscription billing-issue events (cross-platform).
+ *
+ * Fires when an active subscription enters a billing-issue state:
+ * - iOS 18+ / Mac Catalyst 18+: via StoreKit 2 `Message.Reason.billingIssue`.
+ * - Android (Play Billing 8.1+): when `isSuspendedAndroid === true` is observed.
+ * - Horizon / iOS 17 / older platforms: never fires.
+ *
+ * Recommended UX: on fire, call `deepLinkToSubscriptions()` so the user can
+ * update their payment method in the platform subscription center.
+ *
+ * @param listener - Function to call with the affected Purchase
+ * @returns EventSubscription with remove() method to unsubscribe
+ *
+ * @example
+ * ```typescript
+ * const subscription = subscriptionBillingIssueListener((purchase) => {
+ *   console.warn('Subscription needs attention:', purchase.productId);
+ *   deepLinkToSubscriptions({skuAndroid: purchase.productId, packageNameAndroid: 'com.example.app'});
+ * });
+ *
+ * subscription.remove();
+ * ```
+ */
+
+const subscriptionBillingIssueJsListeners = new Set();
+let subscriptionBillingIssueNativeAttached = false;
+const subscriptionBillingIssueNativeHandler = nitroPurchase => {
+  if (!validateNitroPurchase(nitroPurchase)) {
+    RnIapConsole.warn('[subscriptionBillingIssueListener] dropped malformed native payload');
+    return;
+  }
+  const purchase = convertNitroPurchaseToPurchase(nitroPurchase);
+  for (const listener of subscriptionBillingIssueJsListeners) {
+    try {
+      listener(purchase);
+    } catch (e) {
+      RnIapConsole.error('[subscriptionBillingIssueListener] callback threw:', e);
+    }
+  }
+};
+function tryAttachSubscriptionBillingIssueNative() {
+  if (subscriptionBillingIssueNativeAttached) return;
+  try {
+    IAP.instance.addSubscriptionBillingIssueListener(subscriptionBillingIssueNativeHandler);
+    subscriptionBillingIssueNativeAttached = true;
+  } catch (e) {
+    const msg = toErrorMessage(e);
+    if (msg.includes('Nitro runtime not installed')) {
+      RnIapConsole.warn('[subscriptionBillingIssueListener] Nitro not ready yet; will retry on next registration after initConnection()');
+    } else {
+      throw e;
+    }
+  }
+}
+export const subscriptionBillingIssueListener = listener => {
+  subscriptionBillingIssueJsListeners.add(listener);
+  // Retry attachment every call so a listener registered before initConnection()
+  // doesn't stay permanently inert once Nitro is ready.
+  try {
+    tryAttachSubscriptionBillingIssueNative();
+  } catch (error) {
+    subscriptionBillingIssueJsListeners.delete(listener);
+    throw error;
+  }
+  return {
+    remove: () => {
+      subscriptionBillingIssueJsListeners.delete(listener);
+    }
+  };
+};
+
 // ------------------------------
 // Query API
 // ------------------------------
 
 /**
- * Fetch products from the store
- * @param params - Product request configuration
- * @param params.skus - Array of product SKUs to fetch
- * @param params.type - Optional filter: 'in-app' (default) for products, 'subs' for subscriptions, or 'all' for both.
- * @returns Promise<Product[]> - Array of products from the store
+ * Retrieve products or subscriptions from the store by SKU.
  *
- * @example
- * ```typescript
- * // Regular products
- * const products = await fetchProducts({ skus: ['product1', 'product2'] });
+ * @param request `ProductRequest` — `skus` (string[]) and optional `type`
+ *   (`'in-app' | 'subs' | 'all'`, defaults to `'in-app'`).
+ * @returns Promise resolving to a `FetchProductsResult` union — `Product[]` for `'in-app'`,
+ *   `ProductSubscription[]` for `'subs'`, a mixed array for `'all'`, or `null`
+ *   (the schema retains the nullable branch for backwards compatibility).
+ * @throws When the store rejects the request (empty `skus`, not connected,
+ *   network/store error). Unknown SKUs are simply omitted from the result, not thrown.
  *
- * // Subscriptions
- * const subscriptions = await fetchProducts({ skus: ['sub1', 'sub2'], type: 'subs' });
+ * @example
+ * ```ts
+ * const products = 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}
  */
 export const fetchProducts = async request => {
   const {
@@ -480,22 +564,40 @@ export const fetchProducts = async request => {
     return convertedProducts;
   } catch (error) {
     RnIapConsole.error('[fetchProducts] Failed:', error);
-    throw error;
+    const parsedError = parseErrorStringToJsonObj(error);
+    throw createPurchaseError({
+      code: parsedError.code,
+      message: parsedError.message,
+      responseCode: parsedError.responseCode,
+      debugMessage: parsedError.debugMessage,
+      productId: parsedError.productId,
+      productIds: parsedError.productIds,
+      productType: parsedError.productType,
+      isEmptyProductList: parsedError.isEmptyProductList,
+      platform: Platform.OS === 'ios' ? 'ios' : 'android'
+    });
   }
 };
 
 /**
- * Get available purchases (purchased items not yet consumed/finished)
- * @param params - Options for getting available purchases
- * @param params.alsoPublishToEventListener - Whether to also publish to event listener
- * @param params.onlyIncludeActiveItems - Whether to only include active items
+ * List the user's unfinished purchases — non-consumables, active subscriptions, and any
+ * pending transactions not yet finished.
+ *
+ * @param options Optional `PurchaseOptions`.
+ *   - iOS: `alsoPublishToEventListenerIOS`, `onlyIncludeActiveItemsIOS`.
+ *   - Android: `includeSuspendedAndroid` (include subscriptions in a paused/grace state).
+ * @returns Promise resolving to an array of `Purchase` currently held by the store.
+ * @throws When the platform query fails.
  *
  * @example
- * ```typescript
- * const purchases = await getAvailablePurchases({
- *   onlyIncludeActiveItemsIOS: true
- * });
+ * ```ts
+ * const purchases = await getAvailablePurchases();
+ * for (const p of purchases) {
+ *   if (await verifyOnServer(p)) await finishTransaction({ purchase: p, isConsumable: false });
+ * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-available-purchases}
  */
 export const getAvailablePurchases = async options => {
   const alsoPublishToEventListenerIOS = Boolean(options?.alsoPublishToEventListenerIOS ?? false);
@@ -552,6 +654,8 @@ export const getAvailablePurchases = async options => {
  * Request the promoted product from the App Store (iOS only)
  * @returns Promise<Product | null> - The promoted product or null if none available
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-promoted-product-ios}
  */
 export const getPromotedProductIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -576,6 +680,20 @@ export const getPromotedProductIOS = async () => {
   }
 };
 export const requestPromotedProductIOS = getPromotedProductIOS;
+
+/**
+ * Get the storefront identifier for the user's App Store account (iOS only)
+ * @returns Promise<string> - The storefront identifier (e.g., 'USA' for United States)
+ * @platform iOS
+ *
+ * @example
+ * ```typescript
+ * const storefront = await getStorefrontIOS();
+ * console.log('User storefront:', storefront); // e.g., 'USA', 'GBR', 'KOR'
+ * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-storefront-ios}
+ */
 export const getStorefrontIOS = async () => {
   if (Platform.OS !== 'ios') {
     throw new Error('getStorefrontIOS is only available on iOS');
@@ -588,6 +706,12 @@ export const getStorefrontIOS = async () => {
     throw error;
   }
 };
+
+/**
+ * Return the user's storefront country code.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-storefront}
+ */
 export const getStorefront = async () => {
   if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
     RnIapConsole.warn('[getStorefront] Storefront lookup is only supported on iOS and Android.');
@@ -609,6 +733,28 @@ export const getStorefront = async () => {
     throw error;
   }
 };
+
+/**
+ * iOS only - Gets the original app transaction ID if the app was purchased from the App Store
+ * @platform iOS
+ * @description
+ * This function retrieves the original app transaction information if the app was purchased
+ * from the App Store. Returns null if the app was not purchased (e.g., free app or TestFlight).
+ *
+ * @returns {Promise<string | null>} The original app transaction ID or null
+ *
+ * @example
+ * ```typescript
+ * const appTransaction = await getAppTransactionIOS();
+ * if (appTransaction) {
+ *   console.log('App was purchased, transaction ID:', appTransaction);
+ * } else {
+ *   console.log('App was not purchased from App Store');
+ * }
+ * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-app-transaction-ios}
+ */
 export const getAppTransactionIOS = async () => {
   if (Platform.OS !== 'ios') {
     throw new Error('getAppTransactionIOS is only available on iOS');
@@ -634,6 +780,16 @@ export const getAppTransactionIOS = async () => {
     throw error;
   }
 };
+
+/**
+ * Get subscription status for a product (iOS only)
+ * @param sku - The product SKU
+ * @returns Promise<SubscriptionStatusIOS[]> - Array of subscription status objects
+ * @throws Error when called on non-iOS platforms or when IAP is not initialized
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/subscription-status-ios}
+ */
 export const subscriptionStatusIOS = async sku => {
   if (Platform.OS !== 'ios') {
     throw new Error('subscriptionStatusIOS is only available on iOS');
@@ -653,6 +809,15 @@ export const subscriptionStatusIOS = async sku => {
     });
   }
 };
+
+/**
+ * Get current entitlement for a product (iOS only)
+ * @param sku - The product SKU
+ * @returns Promise<Purchase | null> - Current entitlement or null
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/current-entitlement-ios}
+ */
 export const currentEntitlementIOS = async sku => {
   if (Platform.OS !== 'ios') {
     return null;
@@ -675,6 +840,15 @@ export const currentEntitlementIOS = async sku => {
     });
   }
 };
+
+/**
+ * Get latest transaction for a product (iOS only)
+ * @param sku - The product SKU
+ * @returns Promise<Purchase | null> - Latest transaction or null
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/latest-transaction-ios}
+ */
 export const latestTransactionIOS = async sku => {
   if (Platform.OS !== 'ios') {
     return null;
@@ -697,6 +871,14 @@ export const latestTransactionIOS = async sku => {
     });
   }
 };
+
+/**
+ * Get pending transactions (iOS only)
+ * @returns Promise<Purchase[]> - Array of pending transactions
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-pending-transactions-ios}
+ */
 export const getPendingTransactionsIOS = async () => {
   if (Platform.OS !== 'ios') {
     return [];
@@ -715,6 +897,38 @@ export const getPendingTransactionsIOS = async () => {
     });
   }
 };
+
+/**
+ * List every StoreKit transaction (finished + unfinished) for the current user.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-all-transactions-ios}
+ */
+export const getAllTransactionsIOS = async () => {
+  if (Platform.OS !== 'ios') {
+    return [];
+  }
+  try {
+    const nitroPurchases = await IAP.instance.getAllTransactionsIOS();
+    return nitroPurchases.map(convertNitroPurchaseToPurchase).filter(purchase => purchase.platform === 'ios');
+  } catch (error) {
+    RnIapConsole.error('[getAllTransactionsIOS] Failed:', error);
+    const parsedError = parseErrorStringToJsonObj(error);
+    throw createPurchaseError({
+      code: parsedError.code,
+      message: parsedError.message,
+      responseCode: parsedError.responseCode,
+      debugMessage: parsedError.debugMessage
+    });
+  }
+};
+
+/**
+ * Show manage subscriptions screen (iOS only)
+ * @returns Promise<Purchase[]> - Subscriptions where auto-renewal status changed
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/show-manage-subscriptions-ios}
+ */
 export const showManageSubscriptionsIOS = async () => {
   if (Platform.OS !== 'ios') {
     return [];
@@ -733,6 +947,15 @@ export const showManageSubscriptionsIOS = async () => {
     });
   }
 };
+
+/**
+ * Check if user is eligible for intro offer (iOS only)
+ * @param groupID - The subscription group ID
+ * @returns Promise<boolean> - Eligibility status
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-eligible-for-intro-offer-ios}
+ */
 export const isEligibleForIntroOfferIOS = async groupID => {
   if (Platform.OS !== 'ios') {
     return false;
@@ -750,6 +973,14 @@ export const isEligibleForIntroOfferIOS = async groupID => {
     });
   }
 };
+
+/**
+ * Get receipt data (iOS only)
+ * @returns Promise<string> - Base64 encoded receipt data
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-receipt-data-ios}
+ */
 export const getReceiptDataIOS = async () => {
   if (Platform.OS !== 'ios') {
     throw new Error('getReceiptDataIOS is only available on iOS');
@@ -810,6 +1041,15 @@ export const requestReceiptRefreshIOS = async () => {
     });
   }
 };
+
+/**
+ * Check if transaction is verified (iOS only)
+ * @param sku - The product SKU
+ * @returns Promise<boolean> - Verification status
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-transaction-verified-ios}
+ */
 export const isTransactionVerifiedIOS = async sku => {
   if (Platform.OS !== 'ios') {
     return false;
@@ -827,6 +1067,15 @@ export const isTransactionVerifiedIOS = async sku => {
     });
   }
 };
+
+/**
+ * Get transaction JWS representation (iOS only)
+ * @param sku - The product SKU
+ * @returns Promise<string | null> - JWS representation or null
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-transaction-jws-ios}
+ */
 export const getTransactionJwsIOS = async sku => {
   if (Platform.OS !== 'ios') {
     return null;
@@ -850,25 +1099,23 @@ export const getTransactionJwsIOS = async sku => {
 // ------------------------------
 
 /**
- * Initialize connection to the store
- * @param config - Optional configuration including alternative billing mode for Android
- * @param config.alternativeBillingModeAndroid - Alternative billing mode: 'none', 'user-choice', or 'alternative-only'
+ * Initialize the store connection. Must be called before any other IAP API.
+ *
+ * @param config Optional connection config. Use `enableBillingProgramAndroid` (Android,
+ *   Play Billing 8.2.0+) to opt into External Payments etc. iOS ignores Android-specific fields.
+ * @returns Promise resolving to `true` when the platform billing client is connected.
+ * @throws When the platform billing client fails to initialize.
  *
  * @example
- * ```typescript
- * // Standard billing (default)
+ * ```ts
  * await initConnection();
+ * await initConnection({ enableBillingProgramAndroid: 'external-offer' });
+ * ```
  *
- * // User choice billing (Android)
- * await initConnection({
- *   alternativeBillingModeAndroid: 'user-choice'
- * });
+ * @remarks When using `useIAP()`, connection is auto-managed on mount/unmount —
+ *   pass options to the hook instead of calling this directly.
  *
- * // Alternative billing only (Android)
- * await initConnection({
- *   alternativeBillingModeAndroid: 'alternative-only'
- * });
- * ```
+ * @see {@link https://www.openiap.dev/docs/apis/init-connection}
  */
 export const initConnection = async config => {
   try {
@@ -886,7 +1133,9 @@ export const initConnection = async config => {
 };
 
 /**
- * End connection to the store
+ * Close the store connection and release resources.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/end-connection}
  */
 export const endConnection = async () => {
   try {
@@ -905,6 +1154,12 @@ export const endConnection = async () => {
     });
   }
 };
+
+/**
+ * Restore non-consumable and active subscription purchases.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/restore-purchases}
+ */
 export const restorePurchases = async () => {
   try {
     if (Platform.OS === 'ios') {
@@ -927,9 +1182,30 @@ export const restorePurchases = async () => {
 };
 
 /**
- * Request a purchase for products or subscriptions
- * ⚠️ Important: This is an event-based operation, not promise-based.
- * Listen for events through purchaseUpdatedListener or purchaseErrorListener.
+ * Initiate a purchase or subscription flow. The result is delivered through
+ * `purchaseUpdatedListener` — NOT the return value.
+ *
+ * @param request `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 The dispatched purchase payload. **Do not rely on it** for the actual outcome.
+ * @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}
  */
 export const requestPurchase = async request => {
   try {
@@ -1043,19 +1319,28 @@ export const requestPurchase = async request => {
 };
 
 /**
- * Finish a transaction (consume or acknowledge)
- * @param params - Transaction finish parameters
- * @param params.purchase - The purchase to finish
- * @param params.isConsumable - Whether this is a consumable product (Android only)
- * @returns Promise<void> - Resolves when the transaction is successfully finished
+ * 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
- * ```typescript
- * await finishTransaction({
- *   purchase: myPurchase,
- *   isConsumable: true
+ * ```ts
+ * purchaseUpdatedListener(async (purchase) => {
+ *   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}
  */
 export const finishTransaction = async args => {
   const {
@@ -1118,6 +1403,8 @@ export const finishTransaction = async args => {
  * ```typescript
  * await acknowledgePurchaseAndroid('purchase_token_here');
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/acknowledge-purchase-android}
  */
 export const acknowledgePurchaseAndroid = async purchaseToken => {
   try {
@@ -1152,6 +1439,8 @@ export const acknowledgePurchaseAndroid = async purchaseToken => {
  * ```typescript
  * await consumePurchaseAndroid('purchase_token_here');
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/consume-purchase-android}
  */
 export const consumePurchaseAndroid = async purchaseToken => {
   try {
@@ -1204,6 +1493,8 @@ export const consumePurchaseAndroid = async purchaseToken => {
  *   }
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/validate-receipt}
  */
 export const validateReceipt = async options => {
   const {
@@ -1311,9 +1602,28 @@ export const validateReceipt = async options => {
  *
  * @param options - Receipt validation options containing the SKU
  * @returns Promise resolving to receipt validation result
+ *
+ * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase}
  */
 export const verifyPurchase = validateReceipt;
 
+/**
+ * iOS-only receipt validation alias.
+ *
+ * @deprecated Use `verifyPurchase` (or `validateReceipt`) instead. Kept so
+ * consumers who imported `validateReceiptIOS` — which is still declared on the
+ * OpenIAP Query interface — keep working. Throws on non-iOS platforms.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/validate-receipt-ios}
+ */
+export const validateReceiptIOS = async options => {
+  if (Platform.OS !== 'ios') {
+    throw new Error('validateReceiptIOS is only available on iOS');
+  }
+  const result = await validateReceipt(options);
+  return result;
+};
+
 /**
  * Verify purchase with a specific provider (e.g., IAPKit)
  *
@@ -1334,6 +1644,8 @@ export const verifyPurchase = validateReceipt;
  *   },
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/features/validation#verify-purchase-with-provider}
  */
 export const verifyPurchaseWithProvider = async options => {
   try {
@@ -1373,6 +1685,8 @@ export const verifyPurchaseWithProvider = async options => {
  * Sync iOS purchases with App Store (iOS only)
  * @returns Promise<boolean>
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/sync-ios}
  */
 export const syncIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -1397,6 +1711,8 @@ export const syncIOS = async () => {
  * Present the code redemption sheet for offer codes (iOS only)
  * @returns Promise<boolean> - Indicates whether the redemption sheet was presented
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-code-redemption-sheet-ios}
  */
 export const presentCodeRedemptionSheetIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -1436,6 +1752,8 @@ export const presentCodeRedemptionSheetIOS = async () => {
  *
  * @returns Promise<boolean> - true when the request triggers successfully
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/request-purchase-on-promoted-product-ios}
  */
 export const requestPurchaseOnPromotedProductIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -1469,6 +1787,8 @@ export const requestPurchaseOnPromotedProductIOS = async () => {
  * Clear unfinished transactions on iOS
  * @returns Promise<boolean>
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/clear-transaction-ios}
  */
 export const clearTransactionIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -1494,6 +1814,8 @@ export const clearTransactionIOS = async () => {
  * @param sku - The product SKU to refund
  * @returns Promise<string | null> - The refund status or null if not available
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/begin-refund-request-ios}
  */
 export const beginRefundRequestIOS = async sku => {
   if (Platform.OS !== 'ios') {
@@ -1514,72 +1836,11 @@ export const beginRefundRequestIOS = async sku => {
   }
 };
 
-/**
- * Get subscription status for a product (iOS only)
- * @param sku - The product SKU
- * @returns Promise<SubscriptionStatusIOS[]> - Array of subscription status objects
- * @throws Error when called on non-iOS platforms or when IAP is not initialized
- * @platform iOS
- */
-/**
- * Get current entitlement for a product (iOS only)
- * @param sku - The product SKU
- * @returns Promise<Purchase | null> - Current entitlement or null
- * @platform iOS
- */
-/**
- * Get latest transaction for a product (iOS only)
- * @param sku - The product SKU
- * @returns Promise<Purchase | null> - Latest transaction or null
- * @platform iOS
- */
-/**
- * Get pending transactions (iOS only)
- * @returns Promise<Purchase[]> - Array of pending transactions
- * @platform iOS
- */
-/**
- * Show manage subscriptions screen (iOS only)
- * @returns Promise<Purchase[]> - Subscriptions where auto-renewal status changed
- * @platform iOS
- */
-/**
- * Check if user is eligible for intro offer (iOS only)
- * @param groupID - The subscription group ID
- * @returns Promise<boolean> - Eligibility status
- * @platform iOS
- */
-/**
- * Get receipt data (iOS only)
- * @returns Promise<string> - Base64 encoded receipt data
- * @platform iOS
- */
-/**
- * Check if transaction is verified (iOS only)
- * @param sku - The product SKU
- * @returns Promise<boolean> - Verification status
- * @platform iOS
- */
-/**
- * Get transaction JWS representation (iOS only)
- * @param sku - The product SKU
- * @returns Promise<string | null> - JWS representation or null
- * @platform iOS
- */
-/**
- * Get the storefront identifier for the user's App Store account (iOS only)
- * @returns Promise<string> - The storefront identifier (e.g., 'USA' for United States)
- * @platform iOS
- *
- * @example
- * ```typescript
- * const storefront = await getStorefrontIOS();
- * console.log('User storefront:', storefront); // e.g., 'USA', 'GBR', 'KOR'
- * ```
- */
 /**
  * Deeplinks to native interface that allows users to manage their subscriptions
  * Cross-platform alias aligning with expo-iap
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/deep-link-to-subscriptions}
  */
 export const deepLinkToSubscriptions = async options => {
   const resolvedOptions = options ?? undefined;
@@ -1624,25 +1885,6 @@ export const deepLinkToSubscriptionsIOS = async () => {
   }
 };
 
-/**
- * iOS only - Gets the original app transaction ID if the app was purchased from the App Store
- * @platform iOS
- * @description
- * This function retrieves the original app transaction information if the app was purchased
- * from the App Store. Returns null if the app was not purchased (e.g., free app or TestFlight).
- *
- * @returns {Promise<string | null>} The original app transaction ID or null
- *
- * @example
- * ```typescript
- * const appTransaction = await getAppTransactionIOS();
- * if (appTransaction) {
- *   console.log('App was purchased, transaction ID:', appTransaction);
- * } else {
- *   console.log('App was not purchased from App Store');
- * }
- * ```
- */
 /**
  * Get all active subscriptions with detailed information (OpenIAP compliant)
  * Returns an array of active subscriptions. If subscriptionIds is not provided,
@@ -1655,6 +1897,8 @@ export const deepLinkToSubscriptionsIOS = async () => {
  *
  * @param subscriptionIds - Optional array of subscription IDs to filter by
  * @returns Promise<ActiveSubscription[]> - Array of active subscriptions
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/get-active-subscriptions}
  */
 export const getActiveSubscriptions = async subscriptionIds => {
   try {
@@ -1801,6 +2045,8 @@ export const getActiveSubscriptions_OLD: QueryField<
  *
  * @param subscriptionIds - Optional array of subscription IDs to check
  * @returns Promise<boolean> - True if there are active subscriptions
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/has-active-subscriptions}
  */
 export const hasActiveSubscriptions = async subscriptionIds => {
   try {
@@ -1903,6 +2149,8 @@ const normalizeProductQueryType = type => {
  *   // Proceed with alternative billing flow
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/check-alternative-billing-availability-android}
  */
 export const checkAlternativeBillingAvailabilityAndroid = async () => {
   if (Platform.OS !== 'android') {
@@ -1938,6 +2186,8 @@ export const checkAlternativeBillingAvailabilityAndroid = async () => {
  *   }
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/show-alternative-billing-dialog-android}
  */
 export const showAlternativeBillingDialogAndroid = async () => {
   if (Platform.OS !== 'android') {
@@ -1973,6 +2223,8 @@ export const showAlternativeBillingDialogAndroid = async () => {
  *   });
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/create-alternative-billing-token-android}
  */
 export const createAlternativeBillingTokenAndroid = async sku => {
   if (Platform.OS !== 'android') {
@@ -2040,6 +2292,8 @@ export const enableBillingProgramAndroid = program => {
  *   // External offers are available for this user
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/is-billing-program-available-android}
  */
 export const isBillingProgramAvailableAndroid = async program => {
   if (Platform.OS !== 'android') {
@@ -2075,6 +2329,8 @@ export const isBillingProgramAvailableAndroid = async program => {
  *   body: JSON.stringify({ token: details.externalTransactionToken })
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/create-billing-program-reporting-details-android}
  */
 export const createBillingProgramReportingDetailsAndroid = async program => {
   if (Platform.OS !== 'android') {
@@ -2112,6 +2368,8 @@ export const createBillingProgramReportingDetailsAndroid = async program => {
  *   console.log('User accepted external link');
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/launch-external-link-android}
  */
 export const launchExternalLinkAndroid = async params => {
   if (Platform.OS !== 'android') {
@@ -2135,7 +2393,11 @@ export const launchExternalLinkAndroid = async params => {
 // ------------------------------
 
 /**
- * Check if the device can present an external purchase notice sheet (iOS 18.2+).
+ * Check if the device can present an external purchase notice sheet (iOS 17.4+).
+ *
+ * Wraps `ExternalPurchase.canPresent`, which Apple introduced in iOS 17.4.
+ * Note: the notice sheet itself (`presentExternalPurchaseNoticeSheetIOS`)
+ * still requires iOS 18.2+; only the eligibility check is available earlier.
  *
  * @returns Promise<boolean> - true if notice sheet can be presented
  * @platform iOS
@@ -2148,6 +2410,8 @@ export const launchExternalLinkAndroid = async params => {
  *   const result = await presentExternalPurchaseNoticeSheetIOS();
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/can-present-external-purchase-notice-ios}
  */
 export const canPresentExternalPurchaseNoticeIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -2176,6 +2440,8 @@ export const canPresentExternalPurchaseNoticeIOS = async () => {
  *   await presentExternalPurchaseLinkIOS('https://your-website.com/purchase');
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-external-purchase-notice-sheet-ios}
  */
 export const presentExternalPurchaseNoticeSheetIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -2203,6 +2469,8 @@ export const presentExternalPurchaseNoticeSheetIOS = async () => {
  *   console.log('User completed external purchase');
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-external-purchase-link-ios}
  */
 export const presentExternalPurchaseLinkIOS = async url => {
   if (Platform.OS !== 'ios') {
@@ -2235,6 +2503,8 @@ export const presentExternalPurchaseLinkIOS = async url => {
  *   // App can use custom external purchase links
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-eligible-for-external-purchase-custom-link-ios}
  */
 export const isEligibleForExternalPurchaseCustomLinkIOS = async () => {
   if (Platform.OS !== 'ios') {
@@ -2266,6 +2536,8 @@ export const isEligibleForExternalPurchaseCustomLinkIOS = async () => {
  *   await reportToApple(result.token);
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-external-purchase-custom-link-token-ios}
  */
 export const getExternalPurchaseCustomLinkTokenIOS = async tokenType => {
   if (Platform.OS !== 'ios') {
@@ -2297,6 +2569,8 @@ export const getExternalPurchaseCustomLinkTokenIOS = async tokenType => {
  *   await Linking.openURL('https://your-store.com/checkout');
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/show-external-purchase-custom-link-notice-ios}
  */
 export const showExternalPurchaseCustomLinkNoticeIOS = async noticeType => {
   if (Platform.OS !== 'ios') {