expo-iap 4.2.2 → 4.2.4

package/src/kit-api.ts

@@ -0,0 +1,229 @@
+// Tiny fetch wrapper around kit's `/v1` HTTP surface for use by the JS
+// SDK consumers (react-native-iap + expo-iap). Mirrors the shape of
+// `packages/mcp-server/src/kit-client.ts` so the same operations are
+// reachable from both LLM tools and end-user apps without each
+// duplicating the URL layout.
+
+export type KitApiOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  // Optional fetch override for runtimes without a global (older RN
+  // builds) or for injection in tests.
+  fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>;
+};
+
+export type KitSubscription = {
+  id: string;
+  productId: string;
+  platform: 'IOS' | 'Android';
+  state: string;
+  expiresAt?: number;
+  renewsAt?: number;
+  willRenew?: boolean;
+  cancellationReason?: string;
+  currency?: string;
+  priceAmountMicros?: number;
+  startedAt: number;
+  updatedAt: number;
+  purchaseToken: string;
+  userId?: string;
+};
+
+export type EntitlementsResponse = {
+  userId: string;
+  productIds: string[];
+  subscriptions: KitSubscription[];
+};
+
+export type StatusResponse = {
+  active: boolean;
+  subscription: KitSubscription | null;
+};
+
+const DEFAULT_BASE_URL = 'https://kit.openiap.dev';
+
+// Merge caller-supplied headers with kit defaults (`accept`,
+// optionally `content-type`). When the runtime exposes a global
+// `Headers` constructor we use it directly so callers passing a
+// `Headers` instance (a `HeadersInit`) keep that exact instance's
+// values. When `Headers` is missing — older React Native builds where
+// the operator wires up `fetchImpl` without a `Headers` polyfill —
+// we fall back to a case-insensitive merge into a plain record so
+// the request still goes through. Either way, caller-set values take
+// precedence over kit defaults.
+function mergeHeaders(
+  callerHeaders: HeadersInit | undefined,
+  hasBody: boolean,
+): HeadersInit {
+  if (typeof Headers === 'function') {
+    const merged = new Headers(callerHeaders);
+    if (!merged.has('accept')) merged.set('accept', 'application/json');
+    if (hasBody && !merged.has('content-type')) {
+      merged.set('content-type', 'application/json');
+    }
+    return merged;
+  }
+  // Plain-object fallback path. Build a case-insensitive name map
+  // from whatever the caller passed (Headers-shaped, array-of-pairs,
+  // or plain record) and re-emit as a record `fetchImpl` accepts.
+  const lower = new Map<string, {name: string; value: string}>();
+  const setIfAbsent = (name: string, value: string) => {
+    const key = name.toLowerCase();
+    if (!lower.has(key)) lower.set(key, {name, value});
+  };
+  const setForce = (name: string, value: string) => {
+    const key = name.toLowerCase();
+    lower.set(key, {name, value});
+  };
+  if (callerHeaders) {
+    if (Array.isArray(callerHeaders)) {
+      for (const [name, value] of callerHeaders) setForce(name, value);
+    } else if (
+      typeof (callerHeaders as {forEach?: unknown}).forEach === 'function'
+    ) {
+      // `Headers`-like (without being our `typeof Headers === "function"`
+      // global). RN polyfills sometimes attach `Headers` only to
+      // request/response instances rather than the global scope.
+      // Standard signature is `forEach((value, key, parent))`; we
+      // bind the first two positionally so a polyfill that omits
+      // the third argument still works. `key` is the header name.
+      (
+        callerHeaders as {
+          forEach: (cb: (value: string, key: string) => void) => void;
+        }
+      ).forEach((value, key) => setForce(key, value));
+    } else {
+      for (const [name, value] of Object.entries(
+        callerHeaders as Record<string, string>,
+      )) {
+        setForce(name, value);
+      }
+    }
+  }
+  setIfAbsent('accept', 'application/json');
+  if (hasBody) setIfAbsent('content-type', 'application/json');
+  const out: Record<string, string> = {};
+  for (const {name, value} of lower.values()) out[name] = value;
+  return out;
+}
+
+export class KitApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly body: unknown,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'KitApiError';
+  }
+}
+
+export function kitApi(options: KitApiOptions) {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+  const fetchImpl: (input: string, init?: RequestInit) => Promise<Response> =
+    (() => {
+      if (options.fetchImpl) return options.fetchImpl;
+      if (typeof fetch === 'function') {
+        return (input: string, init?: RequestInit) => fetch(input, init);
+      }
+      throw new Error(
+        'kitApi requires a fetch implementation. Pass `fetchImpl` for runtimes without a global fetch.',
+      );
+    })();
+
+  async function call<T>(path: string, init?: RequestInit): Promise<T> {
+    // Normalize headers without depending on a global `Headers`
+    // constructor: older React Native runtimes ship `fetch` (or a
+    // polyfill via `fetchImpl`) without exposing `Headers` globally.
+    // The prior implementation crashed before the first request on
+    // those runtimes. We use `new Headers()` when available (preserves
+    // caller-supplied `Headers` instances exactly), and otherwise fall
+    // back to a small case-insensitive merge into a plain record.
+    // Either way, kit defaults only apply when the caller hasn't set
+    // the same name.
+    const headers = mergeHeaders(init?.headers, init?.body != null);
+    // Prepend a leading slash if `path` is missing one. Today's
+    // call sites all hard-code the leading "/", but normalizing here
+    // makes the helper safe for future additions and matches the
+    // already-stripped `baseUrl` (PR #124
+    // (https://github.com/hyodotdev/openiap/pull/124) review).
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const response = await fetchImpl(`${baseUrl}${normalizedPath}`, {
+      ...init,
+      headers,
+    });
+    const text = await response.text();
+    // Empty body normalizes to null so callers expecting JSON
+    // (status / entitlements / list*) don't get a truthy ""
+    // and crash on property access.
+    let parsed: unknown = null;
+    let parseError: unknown = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch (error) {
+        // Non-JSON body (a misconfigured proxy returning HTML, a
+        // CDN-injected error page, etc.) on a 2xx response would
+        // otherwise reach the caller as `parsed = text` and crash
+        // on property access via `parsed as T`. Throw a structured
+        // KitApiError instead so callers see a typed failure.
+        parseError = error;
+      }
+    }
+    if (!response.ok) {
+      // Surface the raw body (text or parsed) on the error path so
+      // operators can read the upstream error message verbatim.
+      throw new KitApiError(
+        response.status,
+        parsed ?? text,
+        `kit ${path} returned ${response.status}`,
+      );
+    }
+    if (parseError) {
+      throw new KitApiError(
+        response.status,
+        text,
+        `kit ${path} returned a non-JSON ${response.status} body (${
+          parseError instanceof Error ? parseError.message : String(parseError)
+        })`,
+      );
+    }
+    return parsed as T;
+  }
+
+  return {
+    apiKey: options.apiKey,
+    baseUrl,
+
+    /** GET /v1/subscriptions/status — the `active` boolean is the
+     * fastest gate for "is this user paying?". */
+    status: (userId: string) =>
+      call<StatusResponse>(
+        `/v1/subscriptions/status/${encodeURIComponent(
+          options.apiKey,
+        )}?userId=${encodeURIComponent(userId)}`,
+      ),
+
+    /** GET /v1/subscriptions/entitlements — every productId the user
+     * is entitled to. Use this when feature gating depends on which
+     * specific tier the user owns. */
+    entitlements: (userId: string) =>
+      call<EntitlementsResponse>(
+        `/v1/subscriptions/entitlements/${encodeURIComponent(
+          options.apiKey,
+        )}?userId=${encodeURIComponent(userId)}`,
+      ),
+
+    /** POST /v1/subscriptions/bind-user — call after a successful
+     * verifyReceipt so kit knows which userId owns the verified
+     * `purchaseToken`. Idempotent. */
+    bindUser: (purchaseToken: string, userId: string) =>
+      call<{ok: boolean; bound: boolean}>(
+        `/v1/subscriptions/bind-user/${encodeURIComponent(options.apiKey)}`,
+        {
+          method: 'POST',
+          body: JSON.stringify({purchaseToken, userId}),
+        },
+      ),
+  };
+}

package/src/modules/android.ts

@@ -127,11 +127,46 @@ export const validateReceiptAndroid = async ({
   return response.json();
 };
 
+/**
+ * Consume a purchase token so the user can purchase the same product again
+ * (Android consumable products). Prefer using `finishTransaction` with
+ * `isConsumable: true`, which dispatches to this under the hood.
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/consume-purchase-android}
+ */
+export const consumePurchaseAndroid: MutationField<
+  'consumePurchaseAndroid'
+> = async (purchaseToken) => {
+  const result = await ExpoIapModule.consumePurchaseAndroid(purchaseToken);
+
+  if (typeof result === 'boolean') {
+    return result;
+  }
+
+  if (result && typeof result === 'object') {
+    const record = result as Record<string, unknown>;
+    if (typeof record.success === 'boolean') {
+      return record.success;
+    }
+    if (typeof record.responseCode === 'number') {
+      return record.responseCode === 0;
+    }
+  }
+
+  throw new Error(
+    `consumePurchaseAndroid returned an unexpected response payload: ${JSON.stringify(
+      result,
+    )}`,
+  );
+};
+
 /**
  * Acknowledge a product (on Android.) No-op on iOS.
  * @param {Object} params - The parameters object
  * @param {string} params.token - The product's token (on Android)
  * @returns {Promise<VoidResult | void>}
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/acknowledge-purchase-android}
  */
 export const acknowledgePurchaseAndroid: MutationField<
   'acknowledgePurchaseAndroid'
@@ -182,6 +217,8 @@ export const openRedeemOfferCodeAndroid = async (): Promise<void> => {
  *   // Proceed with alternative billing flow
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/check-alternative-billing-availability-android}
  */
 export const checkAlternativeBillingAvailabilityAndroid: MutationField<
   'checkAlternativeBillingAvailabilityAndroid'
@@ -212,6 +249,8 @@ export const checkAlternativeBillingAvailabilityAndroid: MutationField<
  *   }
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/show-alternative-billing-dialog-android}
  */
 export const showAlternativeBillingDialogAndroid: MutationField<
   'showAlternativeBillingDialogAndroid'
@@ -242,6 +281,8 @@ export const showAlternativeBillingDialogAndroid: MutationField<
  *   });
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/create-alternative-billing-token-android}
  */
 export const createAlternativeBillingTokenAndroid: MutationField<
   'createAlternativeBillingTokenAndroid'
@@ -267,6 +308,8 @@ export const createAlternativeBillingTokenAndroid: MutationField<
  *   // Proceed with billing program flow
  * }
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/is-billing-program-available-android}
  */
 export const isBillingProgramAvailableAndroid: MutationField<
   'isBillingProgramAvailableAndroid'
@@ -290,6 +333,8 @@ export const isBillingProgramAvailableAndroid: MutationField<
  *   linkUri: 'https://your-payment-site.com',
  * });
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/launch-external-link-android}
  */
 export const launchExternalLinkAndroid: MutationField<
   'launchExternalLinkAndroid'
@@ -313,6 +358,8 @@ export const launchExternalLinkAndroid: MutationField<
  * // Report details.externalTransactionToken to Google Play within 24 hours
  * await reportToGooglePlay(details.externalTransactionToken);
  * ```
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/android/create-billing-program-reporting-details-android}
  */
 export const createBillingProgramReportingDetailsAndroid: MutationField<
   'createBillingProgramReportingDetailsAndroid'

package/src/modules/ios.ts

@@ -53,6 +53,8 @@ export function isProductIOS<T extends {platform?: string}>(
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/sync-ios}
  */
 export const syncIOS: MutationField<'syncIOS'> = async () => {
   return !!(await ExpoIapModule.syncIOS());
@@ -66,6 +68,8 @@ export const syncIOS: MutationField<'syncIOS'> = async () => {
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-eligible-for-intro-offer-ios}
  */
 export const isEligibleForIntroOfferIOS: QueryField<
   'isEligibleForIntroOfferIOS'
@@ -84,6 +88,8 @@ export const isEligibleForIntroOfferIOS: QueryField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/subscription-status-ios}
  */
 export const subscriptionStatusIOS: QueryField<
   'subscriptionStatusIOS'
@@ -103,6 +109,8 @@ export const subscriptionStatusIOS: QueryField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/current-entitlement-ios}
  */
 export const currentEntitlementIOS: QueryField<
   'currentEntitlementIOS'
@@ -122,6 +130,8 @@ export const currentEntitlementIOS: QueryField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/latest-transaction-ios}
  */
 export const latestTransactionIOS: QueryField<'latestTransactionIOS'> = async (
   sku,
@@ -141,6 +151,8 @@ export const latestTransactionIOS: QueryField<'latestTransactionIOS'> = async (
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/begin-refund-request-ios}
  */
 export const beginRefundRequestIOS: MutationField<
   'beginRefundRequestIOS'
@@ -160,6 +172,8 @@ export const beginRefundRequestIOS: MutationField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/show-manage-subscriptions-ios}
  */
 export const showManageSubscriptionsIOS: MutationField<
   'showManageSubscriptionsIOS'
@@ -177,6 +191,8 @@ export const showManageSubscriptionsIOS: MutationField<
  * Apple's verifyReceipt endpoint, not directly from the app.
  *
  * @returns {Promise<string>} Base64 encoded receipt data
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-receipt-data-ios}
  */
 export const getReceiptDataIOS: QueryField<'getReceiptDataIOS'> = async () => {
   return ExpoIapModule.getReceiptDataIOS();
@@ -184,6 +200,24 @@ export const getReceiptDataIOS: QueryField<'getReceiptDataIOS'> = async () => {
 
 export const getReceiptIOS = getReceiptDataIOS;
 
+/**
+ * Get the current App Store storefront country code on iOS.
+ *
+ * @deprecated Use cross-platform `getStorefront` from the main index instead.
+ *   The native module exposes a single `getStorefront` AsyncFunction that already
+ *   resolves to the iOS storefront on iOS. This helper is kept as an iOS-only
+ *   alias so consumers who previously imported `getStorefrontIOS` do not break.
+ *
+ * @returns {Promise<string>} ISO 3166-1 alpha-2 country code (e.g. "US")
+ *
+ * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-storefront-ios}
+ */
+export const getStorefrontIOS: QueryField<'getStorefrontIOS'> = async () => {
+  return ExpoIapModule.getStorefront();
+};
+
 /**
  * Refresh the receipt data from Apple's servers and return the updated receipt.
  * This calls AppStore.sync() before reading the receipt, ensuring the latest
@@ -208,6 +242,8 @@ export const requestReceiptRefreshIOS = async (): Promise<string> => {
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-transaction-verified-ios}
  */
 export const isTransactionVerifiedIOS: QueryField<
   'isTransactionVerifiedIOS'
@@ -227,6 +263,8 @@ export const isTransactionVerifiedIOS: QueryField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-transaction-jws-ios}
  */
 export const getTransactionJwsIOS: QueryField<'getTransactionJwsIOS'> = async (
   sku,
@@ -253,6 +291,8 @@ export const getTransactionJwsIOS: QueryField<'getTransactionJwsIOS'> = async (
  *   jwsRepresentation: string;
  *   latestTransaction?: Purchase;
  * }>}
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/validate-receipt-ios}
  */
 const validateReceiptIOSImpl = async (props: VerifyPurchaseProps | string) => {
   const sku =
@@ -282,6 +322,8 @@ export const validateReceiptIOS =
  * @throws Error if called on non-iOS platform or tvOS
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-code-redemption-sheet-ios}
  */
 export const presentCodeRedemptionSheetIOS: MutationField<
   'presentCodeRedemptionSheetIOS'
@@ -302,6 +344,8 @@ export const presentCodeRedemptionSheetIOS: MutationField<
  *
  * @platform iOS
  * @since iOS 16.0
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-app-transaction-ios}
  */
 export const getAppTransactionIOS: QueryField<
   'getAppTransactionIOS'
@@ -318,6 +362,8 @@ export const getAppTransactionIOS: QueryField<
  * @throws Error if called on non-iOS platform
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-promoted-product-ios}
  */
 export const getPromotedProductIOS: QueryField<
   'getPromotedProductIOS'
@@ -337,6 +383,8 @@ export const getPromotedProductIOS: QueryField<
  * @throws Error if called on non-iOS platform or no promoted product is available
  *
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/request-purchase-on-promoted-product-ios}
  */
 export const requestPurchaseOnPromotedProductIOS =
   async (): Promise<boolean> => {
@@ -349,6 +397,8 @@ export const requestPurchaseOnPromotedProductIOS =
  *
  * @returns Promise resolving to array of pending transactions
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-pending-transactions-ios}
  */
 export const getPendingTransactionsIOS: QueryField<
   'getPendingTransactionsIOS'
@@ -357,6 +407,11 @@ export const getPendingTransactionsIOS: QueryField<
   return (transactions ?? []) as PurchaseIOS[];
 };
 
+/**
+ * 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: QueryField<
   'getAllTransactionsIOS'
 > = async () => {
@@ -369,6 +424,8 @@ export const getAllTransactionsIOS: QueryField<
  *
  * @returns Promise resolving when transaction is cleared
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/clear-transaction-ios}
  */
 export const clearTransactionIOS: MutationField<
   'clearTransactionIOS'
@@ -386,10 +443,16 @@ export const deepLinkToSubscriptionsIOS = (): Promise<void> =>
   Linking.openURL('https://apps.apple.com/account/subscriptions');
 
 /**
- * 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 resolving to true if the notice sheet can be presented
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/can-present-external-purchase-notice-ios}
  */
 export const canPresentExternalPurchaseNoticeIOS: QueryField<
   'canPresentExternalPurchaseNoticeIOS'
@@ -404,6 +467,8 @@ export const canPresentExternalPurchaseNoticeIOS: QueryField<
  *
  * @returns Promise resolving to the result with action, token, and error if any
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-external-purchase-notice-sheet-ios}
  */
 export const presentExternalPurchaseNoticeSheetIOS =
   async (): Promise<ExternalPurchaseNoticeResultIOS> => {
@@ -417,6 +482,8 @@ export const presentExternalPurchaseNoticeSheetIOS =
  * @param url - The external purchase URL to open
  * @returns Promise resolving to the result with success status and error if any
  * @platform iOS
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/present-external-purchase-link-ios}
  */
 export const presentExternalPurchaseLinkIOS: MutationField<
   'presentExternalPurchaseLinkIOS'
@@ -432,6 +499,8 @@ export const presentExternalPurchaseLinkIOS: MutationField<
  * @returns Promise resolving to true if eligible
  * @platform iOS
  * @see https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/iseligible
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/is-eligible-for-external-purchase-custom-link-ios}
  */
 export const isEligibleForExternalPurchaseCustomLinkIOS =
   async (): Promise<boolean> => {
@@ -446,6 +515,8 @@ export const isEligibleForExternalPurchaseCustomLinkIOS =
  * @returns Promise resolving to the token result with token string or error
  * @platform iOS
  * @see https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/token(for:)
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/get-external-purchase-custom-link-token-ios}
  */
 export const getExternalPurchaseCustomLinkTokenIOS = async (
   tokenType: ExternalPurchaseCustomLinkTokenTypeIOS,
@@ -470,6 +541,8 @@ export const getExternalPurchaseCustomLinkTokenIOS = async (
  * @returns Promise resolving to the result with continued status and error if any
  * @platform iOS
  * @see https://developer.apple.com/documentation/storekit/externalpurchasecustomlink/shownotice(type:)
+ *
+ * @see {@link https://www.openiap.dev/docs/apis/ios/show-external-purchase-custom-link-notice-ios}
  */
 export const showExternalPurchaseCustomLinkNoticeIOS = async (
   noticeType: ExternalPurchaseCustomLinkNoticeTypeIOS,