react-native-iap 15.5.4 → 15.6.1

package/src/kit-api.ts

@@ -10,6 +10,21 @@ export type KitApiOptions = {
   // Optional fetch override for runtimes without a global (older RN
   // builds) or for injection in tests.
   fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Optional AsyncStorage-compatible persistent cache for direct client
+   * payload reads. Cache failures never change a successful API result. */
+  clientPayloadCache?: KitClientPayloadCache;
+};
+
+export type KitClientPayloadCache = {
+  getItem: (key: string) => Promise<string | null> | string | null;
+  setItem: (key: string, value: string) => Promise<void> | void;
+  removeItem?: (key: string) => Promise<void> | void;
+};
+
+export type KitClientPayloadOptions = {
+  /** Revalidate a cached payload with its scoped ETag. Without this flag,
+   * a valid persistent entry is returned without a network request. */
+  refresh?: boolean;
 };
 
 export type KitSubscription = {
@@ -85,19 +100,16 @@ export type KitProductsOptions = {
   platform?: KitProductPlatform;
   /** Include public client payload bodies in a bounded platform page. */
   includeClientPayload?: boolean;
-  /** Page size for payload-inclusive reads (default 25, maximum 50).
-   * Ignored by the legacy non-payload catalog path. */
+  /** Page size for every catalog read (default 25, maximum 50). */
   limit?: number;
-  /** Opaque cursor returned as `nextCursor` by the previous payload page.
-   * Ignored by the legacy non-payload catalog path. */
+  /** Opaque cursor returned as `nextCursor` by the previous page. */
   cursor?: string;
 };
 
 export type KitProductsResponse = {
   products: KitProduct[];
-  /** Present on payload-inclusive catalog pages. */
-  hasMore?: boolean;
-  /** Present when a payload-inclusive catalog page has another page. */
+  hasMore: boolean;
+  /** Present when a catalog page has another page. */
   nextCursor?: string;
 };
 
@@ -105,6 +117,10 @@ export type KitClientPayloadResponse = {
   clientPayload: KitProductClientPayload;
 };
 
+type CachedClientPayload = KitClientPayloadResponse & {
+  etag?: string;
+};
+
 const DEFAULT_BASE_URL = "https://kit.openiap.dev";
 
 // Merge caller-supplied headers with kit defaults (`accept`,
@@ -196,7 +212,7 @@ export function kitApi(options: KitApiOptions) {
       );
     })();
 
-  async function call<T>(path: string, init?: RequestInit): Promise<T> {
+  async function request(path: string, init?: RequestInit): Promise<Response> {
     // Normalize headers without depending on a global `Headers`
     // constructor: older React Native runtimes ship `fetch` (or a
     // polyfill via `fetchImpl`) without exposing `Headers` globally.
@@ -213,10 +229,16 @@ export function kitApi(options: KitApiOptions) {
     // 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}`, {
+    return fetchImpl(`${baseUrl}${normalizedPath}`, {
       ...init,
       headers,
     });
+  }
+
+  async function parseResponse<T>(
+    response: Response,
+    path: string,
+  ): Promise<T> {
     const text = await response.text();
     // Empty body normalizes to null so callers expecting JSON
     // (status / entitlements / list*) don't get a truthy ""
@@ -256,6 +278,75 @@ export function kitApi(options: KitApiOptions) {
     return parsed as T;
   }
 
+  async function call<T>(path: string, init?: RequestInit): Promise<T> {
+    return parseResponse<T>(await request(path, init), path);
+  }
+
+  function clientPayloadCacheKey(
+    productId: string,
+    platform: KitProductPlatform,
+  ): string {
+    return [
+      "iapkit-client-payload-v1",
+      baseUrl,
+      options.apiKey,
+      platform,
+      productId,
+    ]
+      .map(encodeURIComponent)
+      .join(":");
+  }
+
+  async function readCachedClientPayload(
+    cacheKey: string,
+  ): Promise<CachedClientPayload | null> {
+    if (!options.clientPayloadCache) return null;
+    try {
+      const raw = await options.clientPayloadCache.getItem(cacheKey);
+      if (!raw) return null;
+      const candidate = JSON.parse(raw) as Partial<CachedClientPayload>;
+      const payload = candidate.clientPayload;
+      if (
+        !payload ||
+        !["toml", "json", "text"].includes(payload.format) ||
+        typeof payload.body !== "string" ||
+        !Number.isSafeInteger(payload.version) ||
+        payload.version < 1 ||
+        typeof payload.updatedAt !== "number" ||
+        (candidate.etag !== undefined && typeof candidate.etag !== "string")
+      ) {
+        await options.clientPayloadCache.removeItem?.(cacheKey);
+        return null;
+      }
+      return candidate as CachedClientPayload;
+    } catch {
+      return null;
+    }
+  }
+
+  async function writeCachedClientPayload(
+    cacheKey: string,
+    value: CachedClientPayload,
+  ): Promise<void> {
+    try {
+      await options.clientPayloadCache?.setItem(
+        cacheKey,
+        JSON.stringify(value),
+      );
+    } catch {
+      // Persistence is an optimization. A device storage failure must not
+      // turn a successful IAPKit read into an application error.
+    }
+  }
+
+  async function removeCachedClientPayload(cacheKey: string): Promise<void> {
+    try {
+      await options.clientPayloadCache?.removeItem?.(cacheKey);
+    } catch {
+      // See writeCachedClientPayload: cache maintenance is best effort.
+    }
+  }
+
   return {
     apiKey: options.apiKey,
     baseUrl,
@@ -312,10 +403,42 @@ export function kitApi(options: KitApiOptions) {
 
     /** GET one public client payload by its store-specific natural key.
      * Payloads are app-facing data; never store secrets in them. */
-    clientPayload: (productId: string, platform: KitProductPlatform) =>
-      call<KitClientPayloadResponse>(
-        `/v1/products/${encodeURIComponent(options.apiKey)}/${encodeURIComponent(productId)}/client-payload?platform=${encodeURIComponent(platform)}`,
-      ),
+    clientPayload: async (
+      productId: string,
+      platform: KitProductPlatform,
+      payloadOptions: KitClientPayloadOptions = {},
+    ) => {
+      const path = `/v1/products/${encodeURIComponent(options.apiKey)}/${encodeURIComponent(productId)}/client-payload?platform=${encodeURIComponent(platform)}`;
+      const cacheKey = clientPayloadCacheKey(productId, platform);
+      const cached = await readCachedClientPayload(cacheKey);
+      if (cached && payloadOptions.refresh !== true) {
+        return { clientPayload: cached.clientPayload };
+      }
+      const response = await request(path, {
+        ...(cached?.etag ? { headers: { "If-None-Match": cached.etag } } : {}),
+      });
+      if (response.status === 304 && cached) {
+        return { clientPayload: cached.clientPayload };
+      }
+      try {
+        const result = await parseResponse<KitClientPayloadResponse>(
+          response,
+          path,
+        );
+        await writeCachedClientPayload(cacheKey, {
+          ...result,
+          ...(response.headers.get("etag")
+            ? { etag: response.headers.get("etag")! }
+            : {}),
+        });
+        return result;
+      } catch (error) {
+        if (error instanceof KitApiError && error.status === 404) {
+          await removeCachedClientPayload(cacheKey);
+        }
+        throw error;
+      }
+    },
 
     /** POST /v1/subscriptions/bind-user — call after a successful
      * verifyReceipt so kit knows which userId owns the verified

package/src/specs/RnIap.nitro.ts

@@ -256,7 +256,7 @@ export interface NitroRequestPurchaseAndroid {
    */
   offerToken?: string | null;
   subscriptionOffers?: AndroidSubscriptionOfferInput[] | null;
-  /** @deprecated Use subscriptionProductReplacementParams instead for item-level replacement (8.1.0+) */
+  /** @deprecated Use subscriptionProductReplacementParams instead for item-level replacement (8.1.0+). Scheduled for removal in react-native-iap 16.0.0. */
   replacementMode?: RequestSubscriptionAndroidProps['replacementMode'];
   purchaseToken?: RequestSubscriptionAndroidProps['purchaseToken'];
   /** Original external transaction ID for developer-billed subscription replacement (9.1.0+). */
@@ -271,9 +271,9 @@ export interface NitroRequestPurchaseAndroid {
 }
 
 export interface NitroPurchaseRequest {
-  /** @deprecated Use apple instead */
+  /** @deprecated Use apple instead. Scheduled for removal in react-native-iap 16.0.0. */
   ios?: NitroRequestPurchaseIos | null;
-  /** @deprecated Use google instead */
+  /** @deprecated Use google instead. Scheduled for removal in react-native-iap 16.0.0. */
   android?: NitroRequestPurchaseAndroid | null;
   /** Apple-specific purchase parameters */
   apple?: NitroRequestPurchaseIos | null;
@@ -609,12 +609,13 @@ export interface NitroOneTimePurchaseOfferDetail {
 
 export interface NitroPurchase {
   id: PurchaseCommon['id'];
+  transactionId?: string | null;
   productId: PurchaseCommon['productId'];
   transactionDate: PurchaseCommon['transactionDate'];
   purchaseToken?: PurchaseCommon['purchaseToken'];
   currentPlanId?: PurchaseCommon['currentPlanId'];
   ids?: PurchaseCommon['ids'];
-  /** @deprecated Use store instead */
+  /** @deprecated Use store instead. Scheduled for removal in react-native-iap 16.0.0. */
   platform: IapPlatform;
   /** Store where purchase was made */
   store: IapStore;
@@ -674,6 +675,7 @@ export interface NitroActiveSubscription {
   // iOS specific fields
   expirationDateIOS?: ActiveSubscription['expirationDateIOS'];
   environmentIOS?: ActiveSubscription['environmentIOS'];
+  /** @deprecated Use daysUntilExpirationIOS instead. Scheduled for removal in react-native-iap 16.0.0. */
   willExpireSoon?: ActiveSubscription['willExpireSoon'];
   daysUntilExpirationIOS?: ActiveSubscription['daysUntilExpirationIOS'];
   renewalInfoIOS?: NitroRenewalInfoIOS | null; // 🆕 Key field for upgrade/downgrade detection
@@ -720,7 +722,9 @@ export interface NitroProduct {
   isFamilyShareableIOS?: null | boolean;
   jsonRepresentationIOS?: string | null;
   pricingTermsIOS?: string | null;
+  /** @deprecated Use subscriptionOffers and subscriptionGroupIdIOS instead. Scheduled for removal in react-native-iap 16.0.0. */
   subscriptionInfoIOS?: string | null;
+  /** @deprecated Use subscriptionOffers instead. Scheduled for removal in react-native-iap 16.0.0. */
   discountsIOS?: string | null;
   introductoryPriceIOS?: string | null;
   introductoryPriceAsAmountIOS?: number | null;
@@ -744,7 +748,9 @@ export interface NitroProduct {
   introductoryPriceValueAndroid?: number | null;
   subscriptionPeriodAndroid?: string | null;
   freeTrialPeriodAndroid?: string | null;
+  /** @deprecated Use subscriptionOffers instead. Scheduled for removal in react-native-iap 16.0.0. */
   subscriptionOfferDetailsAndroid?: string | null;
+  /** @deprecated Use discountOffers instead. Scheduled for removal in react-native-iap 16.0.0. */
   oneTimePurchaseOfferDetailsAndroid?: NitroOneTimePurchaseOfferDetail[] | null;
   /**
    * Product-level status code indicating fetch result (Android 8.0+)
@@ -784,7 +790,7 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
   /**
    * Fetch products from the store
    * @param skus - Array of product SKUs to fetch
-   * @param type - Type of products: 'inapp' or 'subs'
+   * @param type - Type of products: 'in-app' or 'subs'
    * @returns Promise<NitroProduct[]> - Array of products from the store
    */
   fetchProducts(skus: string[], type: string): Promise<NitroProduct[]>;
@@ -905,6 +911,8 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
    * Request the promoted product from the App Store (iOS only)
    * @returns Promise<NitroProduct | null> - The promoted product or null if none available
    * @platform iOS
+   * @deprecated Use `getPromotedProductIOS` instead. This compatibility alias
+   * will be removed in react-native-iap 16.0.0.
    */
   requestPromotedProductIOS(): Promise<NitroProduct | null>;
 
@@ -1041,6 +1049,8 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
    *
    * @returns Promise<string> - Base64 encoded receipt data containing all app transactions
    * @platform iOS
+   * @deprecated Use `getReceiptDataIOS` instead. This compatibility alias will
+   * be removed in react-native-iap 16.0.0.
    * @see getReceiptDataIOS for full documentation
    * @see getTransactionJwsIOS for validating individual transactions (recommended)
    */
@@ -1095,7 +1105,8 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
 
   /**
    * Validate a receipt on the appropriate platform
-   * @deprecated Use `verifyPurchase` instead. This function will be removed in a future version.
+   * @deprecated Use `verifyPurchase` instead. This function will be removed in
+   * react-native-iap 16.0.0.
    * @param params - Receipt validation parameters including SKU and platform-specific options
    * @returns Promise<NitroReceiptValidationResultIOS | NitroReceiptValidationResultAndroid> - Platform-specific validation result
    */
@@ -1144,6 +1155,8 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
    * @returns Promise<boolean> - true if available, false otherwise
    * @throws Error if billing client not ready
    * @platform Android
+   * @deprecated Use `isBillingProgramAvailableAndroid('external-offer')`
+   * instead. Scheduled for removal in react-native-iap 16.0.0.
    */
   checkAlternativeBillingAvailabilityAndroid(): Promise<boolean>;
 
@@ -1155,6 +1168,8 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
    * @returns Promise<boolean> - true if user accepted, false if user canceled
    * @throws Error if billing client not ready
    * @platform Android
+   * @deprecated Use `launchExternalLinkAndroid` instead. Scheduled for removal in
+   * react-native-iap 16.0.0.
    */
   showAlternativeBillingDialogAndroid(): Promise<boolean>;
 
@@ -1168,6 +1183,9 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
    * @returns Promise<string | null> - Token string or null if creation failed
    * @throws Error if billing client not ready
    * @platform Android
+   * @deprecated Use
+   * `createBillingProgramReportingDetailsAndroid('external-offer')` instead.
+   * Scheduled for removal in react-native-iap 16.0.0.
    */
   createAlternativeBillingTokenAndroid(
     sku?: string | null,
@@ -1331,6 +1349,15 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
     params: NitroLaunchExternalLinkParamsAndroid,
   ): Promise<boolean>;
 
+  /**
+   * Open the platform offer-code redemption flow (Android only).
+   * Does not require a billing-client connection.
+   *
+   * @returns Promise<boolean> - true when the flow was launched
+   * @platform Android
+   */
+  openRedeemOfferCodeAndroid(): Promise<boolean>;
+
   // ╔════════════════════════════════════════════════════════════════════════╗
   // ║                EXTERNAL PURCHASE LINKS (iOS 16.0+)                     ║
   // ╚════════════════════════════════════════════════════════════════════════╝