react-native-iap 16.2.4 → 16.3.1

package/nitrogen/generated/shared/c++/NitroVerifyPurchaseWithIapkitResult.hpp

@@ -51,6 +51,7 @@ namespace margelo::nitro::iap {
   struct NitroVerifyPurchaseWithIapkitResult final {
   public:
     std::optional<std::variant<nitro::NullType, NitroIapkitProductClientPayload>> clientPayload     SWIFT_PRIVATE;
+    std::optional<std::variant<nitro::NullType, std::string>> environment     SWIFT_PRIVATE;
     bool isValid     SWIFT_PRIVATE;
     std::optional<std::variant<nitro::NullType, std::string>> productId     SWIFT_PRIVATE;
     IapkitPurchaseState state     SWIFT_PRIVATE;
@@ -58,7 +59,7 @@ namespace margelo::nitro::iap {
 
   public:
     NitroVerifyPurchaseWithIapkitResult() = default;
-    explicit NitroVerifyPurchaseWithIapkitResult(std::optional<std::variant<nitro::NullType, NitroIapkitProductClientPayload>> clientPayload, bool isValid, std::optional<std::variant<nitro::NullType, std::string>> productId, IapkitPurchaseState state, IapStore store): clientPayload(clientPayload), isValid(isValid), productId(productId), state(state), store(store) {}
+    explicit NitroVerifyPurchaseWithIapkitResult(std::optional<std::variant<nitro::NullType, NitroIapkitProductClientPayload>> clientPayload, std::optional<std::variant<nitro::NullType, std::string>> environment, bool isValid, std::optional<std::variant<nitro::NullType, std::string>> productId, IapkitPurchaseState state, IapStore store): clientPayload(clientPayload), environment(environment), isValid(isValid), productId(productId), state(state), store(store) {}
 
   public:
     friend bool operator==(const NitroVerifyPurchaseWithIapkitResult& lhs, const NitroVerifyPurchaseWithIapkitResult& rhs) = default;
@@ -75,6 +76,7 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::iap::NitroVerifyPurchaseWithIapkitResult(
         JSIConverter<std::optional<std::variant<nitro::NullType, margelo::nitro::iap::NitroIapkitProductClientPayload>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "clientPayload"))),
+        JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "environment"))),
         JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isValid"))),
         JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "productId"))),
         JSIConverter<margelo::nitro::iap::IapkitPurchaseState>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "state"))),
@@ -84,6 +86,7 @@ namespace margelo::nitro {
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::iap::NitroVerifyPurchaseWithIapkitResult& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "clientPayload"), JSIConverter<std::optional<std::variant<nitro::NullType, margelo::nitro::iap::NitroIapkitProductClientPayload>>>::toJSI(runtime, arg.clientPayload));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "environment"), JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::toJSI(runtime, arg.environment));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "isValid"), JSIConverter<bool>::toJSI(runtime, arg.isValid));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "productId"), JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::toJSI(runtime, arg.productId));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "state"), JSIConverter<margelo::nitro::iap::IapkitPurchaseState>::toJSI(runtime, arg.state));
@@ -99,6 +102,7 @@ namespace margelo::nitro {
         return false;
       }
       if (!JSIConverter<std::optional<std::variant<nitro::NullType, margelo::nitro::iap::NitroIapkitProductClientPayload>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "clientPayload")))) return false;
+      if (!JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "environment")))) return false;
       if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isValid")))) return false;
       if (!JSIConverter<std::optional<std::variant<nitro::NullType, std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "productId")))) return false;
       if (!JSIConverter<margelo::nitro::iap::IapkitPurchaseState>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "state")))) return false;

package/openiap-versions.json

@@ -1,5 +1,5 @@
 {
-  "spec": "3.1.1",
-  "google": "3.2.3",
-  "apple": "3.1.1"
+  "spec": "3.2.1",
+  "google": "3.3.1",
+  "apple": "3.2.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-iap",
-  "version": "16.2.4",
+  "version": "16.3.1",
   "description": "React Native In-App Purchases module for iOS and Android using Nitro",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/index.kepler.ts

@@ -1,4 +1,5 @@
 import {getVegaIapModule} from './vega';
+import {ErrorCode} from './types';
 import type {
   MutationField,
   Product,
@@ -27,6 +28,7 @@ import {
   validateNitroPurchase,
 } from './utils/type-bridge';
 import {convertAndroidPurchasesOrThrow} from './utils/available-purchases';
+import {createPurchaseError} from './utils/errorMapping';
 
 export * from './types';
 export * from './utils/error';
@@ -129,13 +131,19 @@ export const fetchProducts = async (
   const normalizedType = normalizeProductQueryType(type);
   const nitroProducts = await getModule().fetchProducts(skus, normalizedType);
   return mapProducts(nitroProducts, normalizedType) as
-    | Product[]
-    | ProductSubscription[];
+    Product[] | ProductSubscription[];
 };
 
 export const requestPurchase: MutationField<'requestPurchase'> = async (
   request,
 ) => {
+  const type = normalizeProductQueryType(request.type);
+  if (type === 'all') {
+    throw createPurchaseError({
+      code: ErrorCode.DeveloperError,
+      message: 'Product type all is only supported for product queries.',
+    });
+  }
   const perPlatformRequest = request.request as
     | RequestPurchasePropsByPlatforms
     | RequestSubscriptionPropsByPlatforms

package/src/index.ts

@@ -9,6 +9,7 @@ import type {
   NitroPurchaseVerificationParams,
   NitroPurchaseVerificationResultIOS,
   NitroPurchaseVerificationResultAndroid,
+  NitroPurchaseVerificationResultHorizon,
   NitroPurchaseUpdatedListenerOptions,
   NitroSubscriptionStatus,
   RnIap,
@@ -41,6 +42,7 @@ import type {
   PurchaseIOS,
   QueryField,
   VerifyPurchaseResultAndroid,
+  VerifyPurchaseResultHorizon,
   VerifyPurchaseResultIOS,
   RequestPurchaseAndroidProps,
   RequestPurchaseIosProps,
@@ -884,7 +886,10 @@ export const fetchProducts: QueryField<'fetchProducts'> = async (request) => {
 
   try {
     if (!skus?.length) {
-      throw new Error('No SKUs provided');
+      throw createPurchaseError({
+        message: 'No SKUs provided',
+        code: ErrorCode.EmptySkuList,
+      });
     }
 
     const normalizedType = normalizeProductQueryType(type);
@@ -1673,6 +1678,12 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
   try {
     const {request: platformRequest, type} = request;
     const normalizedType = normalizeProductQueryType(type ?? 'in-app');
+    if (normalizedType === 'all') {
+      throw createPurchaseError({
+        code: ErrorCode.DeveloperError,
+        message: 'Product type all is only supported for product queries.',
+      });
+    }
     const isSubs = isSubscriptionQuery(normalizedType);
     const perPlatformRequest = platformRequest as
       | RequestPurchasePropsByPlatforms
@@ -1691,15 +1702,23 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
 
     if (Platform.OS === 'ios') {
       if (!iosRequestSource?.sku) {
-        throw new Error(
-          'Invalid request for iOS. The `sku` property is required.',
-        );
+        throw createPurchaseError({
+          message: 'Invalid request for iOS. The `sku` property is required.',
+          code: ErrorCode.EmptySkuList,
+        });
       }
     } else if (isAndroidStoreRuntime()) {
-      if (!androidRequestSource?.skus?.length) {
-        throw new Error(
-          'Invalid request for Android. The `skus` property is required and must be a non-empty array.',
-        );
+      const skus = androidRequestSource?.skus as unknown;
+      if (
+        !Array.isArray(skus) ||
+        skus.length === 0 ||
+        skus.some((sku) => typeof sku !== 'string' || sku.trim() === '')
+      ) {
+        throw createPurchaseError({
+          message:
+            'Invalid request for Android. The `skus` property must contain only non-empty strings.',
+          code: ErrorCode.EmptySkuList,
+        });
       }
     } else {
       throw unsupportedPlatformError();
@@ -1756,6 +1775,29 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
     }
 
     if (isAndroidStoreRuntime() && androidRequestSource) {
+      const rawAndroidRequest = androidRequestSource as unknown as Record<
+        string,
+        unknown
+      >;
+      const subscriptionOnlyFields = [
+        'subscriptionOffers',
+        'subscriptionProductReplacementParams',
+        'purchaseToken',
+        'originalExternalTransactionId',
+      ];
+      if (
+        (!isSubs &&
+          subscriptionOnlyFields.some(
+            (field) => rawAndroidRequest[field] != null,
+          )) ||
+        (isSubs && rawAndroidRequest.offerToken != null)
+      ) {
+        throw createPurchaseError({
+          message:
+            'Invalid request for Android. Purchase options must match the selected product type.',
+          code: ErrorCode.DeveloperError,
+        });
+      }
       const androidRequest = isSubs
         ? (androidRequestSource as RequestSubscriptionAndroidProps)
         : (androidRequestSource as RequestPurchaseAndroidProps);
@@ -1788,6 +1830,29 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
 
       if (isSubs) {
         const subsRequest = androidRequest as RequestSubscriptionAndroidProps;
+        const subscriptionOffers = subsRequest.subscriptionOffers as unknown;
+        if (
+          subscriptionOffers != null &&
+          (!Array.isArray(subscriptionOffers) ||
+            subscriptionOffers.some((offer) => {
+              if (offer == null || typeof offer !== 'object') {
+                return true;
+              }
+              const candidate = offer as Record<string, unknown>;
+              return (
+                typeof candidate.sku !== 'string' ||
+                candidate.sku.trim() === '' ||
+                typeof candidate.offerToken !== 'string' ||
+                candidate.offerToken.trim() === ''
+              );
+            }))
+        ) {
+          throw createPurchaseError({
+            message:
+              'Invalid request for Android. Every subscription offer must include non-empty `sku` and `offerToken` strings.',
+            code: ErrorCode.DeveloperError,
+          });
+        }
         if (subsRequest.purchaseToken) {
           androidPayload.purchaseToken = subsRequest.purchaseToken;
         }
@@ -1800,15 +1865,11 @@ export const requestPurchase: MutationField<'requestPurchase'> = async (
             subsRequest.subscriptionProductReplacementParams;
         }
         androidPayload.subscriptionOffers = (
-          subsRequest.subscriptionOffers ?? []
-        )
-          .filter(
-            (offer): offer is AndroidSubscriptionOfferInput => offer != null,
-          )
-          .map((offer) => ({
-            sku: offer.sku,
-            offerToken: offer.offerToken,
-          }));
+          (subscriptionOffers ?? []) as AndroidSubscriptionOfferInput[]
+        ).map((offer) => ({
+          sku: offer.sku,
+          offerToken: offer.offerToken,
+        }));
       }
 
       unifiedRequest.google = androidPayload;
@@ -2135,11 +2196,20 @@ export const verifyPurchase: MutationField<'verifyPurchase'> = async (
           : undefined,
       };
       return result;
+    } else if (params.horizon !== null) {
+      const horizonResult =
+        nitroResult as NitroPurchaseVerificationResultHorizon;
+      const result: VerifyPurchaseResultHorizon = {
+        isValid: horizonResult.isValid,
+        grantTime: horizonResult.grantTime,
+        success: horizonResult.success,
+      };
+      return result;
     } else {
-      // Android
       const androidResult =
         nitroResult as NitroPurchaseVerificationResultAndroid;
       const result: VerifyPurchaseResultAndroid = {
+        isValid: androidResult.isValid,
         autoRenewing: androidResult.autoRenewing,
         betaProduct: androidResult.betaProduct,
         cancelDate: androidResult.cancelDate,
@@ -2194,9 +2264,11 @@ export const verifyPurchase: MutationField<'verifyPurchase'> = async (
  *     // apple: { jws: purchase.purchaseToken },
  *     // google: { purchaseToken: purchase.purchaseToken },
  *     amazon: {
+ *       expectedProductId: purchase.productId,
  *       userId: amazonUserId,
  *       receiptId: purchase.purchaseToken,
- *       sandbox: __DEV__,
+ *       // Enable only for App Tester after the IAPKit project opt-in.
+ *       sandbox: amazonSandboxEnabled,
  *     },
  *   },
  * });
@@ -2226,6 +2298,9 @@ export const verifyPurchaseWithProvider: MutationField<
             ...(result.iapkit.clientPayload == null
               ? {}
               : {clientPayload: result.iapkit.clientPayload}),
+            ...(result.iapkit.environment == null
+              ? {}
+              : {environment: result.iapkit.environment}),
             isValid: result.iapkit.isValid,
             ...(result.iapkit.productId == null
               ? {}

package/src/kit-api.ts

@@ -31,7 +31,15 @@ export type KitSubscription = {
   id: string;
   productId: string;
   platform: "IOS" | "Android";
-  state: string;
+  state:
+    | "Active"
+    | "InGracePeriod"
+    | "InBillingRetry"
+    | "Expired"
+    | "Revoked"
+    | "Refunded"
+    | "Paused"
+    | "Unknown";
   expiresAt?: number;
   renewsAt?: number;
   willRenew?: boolean;
@@ -41,6 +49,7 @@ export type KitSubscription = {
   startedAt: number;
   updatedAt: number;
   purchaseToken: string;
+  originalTransactionId?: string;
   userId?: string;
 };
 
@@ -58,7 +67,8 @@ export type StatusResponse = {
 export type KitProductPlatform = "IOS" | "Android";
 
 export type KitProductClientPayload = {
-  format: "toml" | "json" | "text";
+  /** Current values are toml, json, and text; preserve unknown values. */
+  format: string;
   body: string;
   version: number;
   updatedAt: number;
@@ -84,6 +94,13 @@ export type KitProduct = {
   type: "Subscription" | "NonConsumable" | "Consumable";
   title: string;
   description?: string;
+  baseLocale?: string;
+  localizations?: Array<{
+    locale: string;
+    title: string;
+    description?: string;
+  }>;
+  regions?: "all" | string[];
   priceAmountMicros?: number;
   currency?: string;
   state: "Draft" | "Ready" | "Active" | "Removed";
@@ -113,6 +130,108 @@ export type KitProductsResponse = {
   nextCursor?: string;
 };
 
+export type KitSubscriptionsResponse = {
+  items: KitSubscription[];
+  total: number;
+};
+
+export type KitMrrCurrencyEntry = {
+  currency: string;
+  mrrMicros: number;
+};
+
+export type KitMetricsResponse = {
+  activeSubs: number;
+  inGracePeriod: number;
+  inBillingRetry: number;
+  refunded30d: number;
+  canceled30d: number;
+  mrrMicros: number;
+  currency: string;
+  reportingCurrency: string;
+  mrrByCurrency: KitMrrCurrencyEntry[];
+  excludedMrrByCurrency: KitMrrCurrencyEntry[];
+};
+
+export type KitRevenueMetricsResponse = {
+  days: Array<{
+    day: string;
+    currency: string;
+    productId: string;
+    platform: KitProductPlatform;
+    activeSubs: number;
+    newSubs: number;
+    renewals: number;
+    cancellations: number;
+    refunds: number;
+    revenueMicros: number;
+  }>;
+  currencies: string[];
+  productIds: string[];
+  platforms: KitProductPlatform[];
+  truncated: boolean;
+};
+
+export type KitProductUpsertResponse = { id: string; created: boolean };
+export type KitProductStateResponse = {
+  id: string;
+  state: KitProduct["state"];
+};
+export type KitClientPayloadStateResponse = {
+  expectedVersion: number;
+  clientPayload?: KitProductClientPayload;
+};
+export type KitSetClientPayloadResponse = {
+  id: string;
+  created: boolean;
+  changed: boolean;
+  version: number;
+  updatedAt: number;
+};
+export type KitRemoveClientPayloadResponse = { ok: boolean };
+export type KitProductSyncResponse = { jobId: string; deduped: boolean };
+export type KitProductSyncJobResponse = {
+  _id: string;
+  _creationTime: number;
+  projectId: string;
+  platform: KitProductPlatform;
+  direction: "pull" | "push" | "both" | "purge-local";
+  dryRun: boolean;
+  status: "queued" | "running" | "succeeded" | "failed";
+  progress: {
+    phase: string;
+    current?: number;
+    total?: number;
+    failuresCount?: number;
+  };
+  result?: {
+    pulled: number;
+    pushed: number;
+    deleted?: number;
+    failures: Array<{ productId: string; reason: string }>;
+    failuresTruncated?: boolean;
+    plannedWrites?: Array<{
+      productId: string;
+      step: string;
+      detail?: string;
+    }>;
+    plannedWritesTruncated?: boolean;
+    manualActions?: Array<{
+      productId: string;
+      code: string;
+      message: string;
+    }>;
+    manualActionsTruncated?: boolean;
+  };
+  error?: string;
+  cancelRequested?: boolean;
+  expectedDeadline?: number;
+  createdBy?: string;
+  startedAt?: number;
+  completedAt?: number;
+  createdAt: number;
+};
+
 export type KitClientPayloadResponse = {
   clientPayload: KitProductClientPayload;
 };
@@ -135,7 +254,7 @@ const DEFAULT_BASE_URL = "https://kit.openiap.dev";
 function mergeHeaders(
   callerHeaders: Record<string, string> | undefined,
   hasBody: boolean,
-): HeadersInit {
+): RequestInit["headers"] {
   if (typeof Headers === "function") {
     const merged = new Headers(callerHeaders);
     if (!merged.has("accept")) merged.set("accept", "application/json");
@@ -283,9 +402,11 @@ export function kitApi(options: KitApiOptions) {
       if (!raw) return null;
       const candidate = JSON.parse(raw) as Partial<CachedClientPayload>;
       const payload = candidate.clientPayload;
+      // Only the invariants the cache depends on. `format` is opaque: evicting
+      // on an unknown one would kill ETag revalidation and offline reads.
       if (
         !payload ||
-        !["toml", "json", "text"].includes(payload.format) ||
+        typeof payload.format !== "string" ||
         typeof payload.body !== "string" ||
         !Number.isSafeInteger(payload.version) ||
         payload.version < 1 ||

package/src/specs/RnIap.nitro.ts

@@ -55,6 +55,7 @@ import type {
   VerifyPurchaseGoogleOptions,
   VerifyPurchaseHorizonOptions,
   VerifyPurchaseResultAndroid,
+  VerifyPurchaseResultHorizon,
   RequestPurchaseIosProps,
   RequestPurchaseResult,
   RequestSubscriptionAndroidProps,
@@ -408,6 +409,7 @@ export interface NitroPurchaseVerificationResultIOS {
 }
 
 export interface NitroPurchaseVerificationResultAndroid {
+  isValid: VerifyPurchaseResultAndroid['isValid'];
   autoRenewing: VerifyPurchaseResultAndroid['autoRenewing'];
   betaProduct: VerifyPurchaseResultAndroid['betaProduct'];
   cancelDate: VerifyPurchaseResultAndroid['cancelDate'];
@@ -428,6 +430,12 @@ export interface NitroPurchaseVerificationResultAndroid {
   testTransaction: VerifyPurchaseResultAndroid['testTransaction'];
 }
 
+export interface NitroPurchaseVerificationResultHorizon {
+  isValid: VerifyPurchaseResultHorizon['isValid'];
+  grantTime?: VerifyPurchaseResultHorizon['grantTime'];
+  success: VerifyPurchaseResultHorizon['success'];
+}
+
 // VerifyPurchaseWithProvider types
 
 export interface NitroVerifyPurchaseWithIapkitAppleProps {
@@ -441,6 +449,8 @@ export interface NitroVerifyPurchaseWithIapkitGoogleProps {
 }
 
 export interface NitroVerifyPurchaseWithIapkitAmazonProps {
+  /** Available in OpenIAP Spec 3.2.0 / openiap-apple 3.2.0 / openiap-google 3.3.0. Optional Amazon product id that must match the product id verified by RVS. */
+  expectedProductId?: string | null;
   /** Amazon Appstore receipt id returned by PurchaseResponse.getReceipt().getReceiptId(). */
   receiptId: string;
   /** Use Amazon RVS Cloud Sandbox for App Tester receipts. */
@@ -475,6 +485,8 @@ export interface NitroVerifyPurchaseWithProviderProps {
 export interface NitroVerifyPurchaseWithIapkitResult {
   /** Available in OpenIAP Spec 2.4.0 / openiap-apple 2.4.1 / openiap-google 2.4.1. */
   clientPayload?: NitroIapkitProductClientPayload | null;
+  /** Available in OpenIAP Spec 3.2.0 / openiap-apple 3.2.0 / openiap-google 3.3.0. Amazon RVS environment selected by IAPKit. */
+  environment?: string | null;
   isValid: boolean;
   /** Available in OpenIAP Spec 2.4.0 / openiap-apple 2.4.1 / openiap-google 2.4.1. */
   productId?: string | null;
@@ -990,12 +1002,14 @@ export interface RnIap extends HybridObject<{ios: 'swift'; android: 'kotlin'}> {
   /**
    * Verify a purchase on the appropriate platform.
    * @param params - Purchase verification parameters including platform-specific options
-   * @returns Promise<NitroPurchaseVerificationResultIOS | NitroPurchaseVerificationResultAndroid>
+   * @returns Promise with the platform-specific verification result
    */
   verifyPurchase(
     params: NitroPurchaseVerificationParams,
   ): Promise<
-    NitroPurchaseVerificationResultIOS | NitroPurchaseVerificationResultAndroid
+    | NitroPurchaseVerificationResultIOS
+    | NitroPurchaseVerificationResultAndroid
+    | NitroPurchaseVerificationResultHorizon
   >;
 
   /**

package/src/types.ts

@@ -885,11 +885,11 @@ export interface Mutation {
    */
   syncIOS: Promise<boolean>;
   /**
-   * 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.
+   * Verify a purchase against your own backend. Every VerifyPurchaseResult
+   * variant exposes isValid, so entitlement can be gated without inspecting the
+   * concrete type. Variants add their own metadata on top: IOS carries
+   * receipt/JWS fields, Android carries Play Store receipt fields, and Horizon
+   * carries grantTime.
    * See: https://openiap.dev/docs/features/validation#verify-purchase
    */
   verifyPurchase: Promise<VerifyPurchaseResult>;
@@ -1791,6 +1791,11 @@ export interface RequestSubscriptionPropsByPlatforms {
 }
 
 export interface RequestVerifyPurchaseWithIapkitAmazonProps {
+  /**
+   * Available in OpenIAP Spec 3.2.0 / openiap-apple 3.2.0 / openiap-google 3.3.0.
+   * Optional Amazon product id that must match the product id verified by RVS.
+   */
+  expectedProductId?: (string | null);
   /** Amazon Appstore receipt id returned by PurchaseResponse.getReceipt().getReceiptId(). */
   receiptId: string;
   /** Use Amazon RVS Cloud Sandbox for App Tester receipts. */
@@ -1848,6 +1853,18 @@ export interface RequestVerifyPurchaseWithIapkitResult {
    * Apple or Google receipt is valid, and a payload exists for that product.
    */
   clientPayload?: (IapkitProductClientPayload | null);
+  /**
+   * Available in OpenIAP Spec 3.2.0 / openiap-apple 3.2.0 / openiap-google 3.3.0.
+   * Amazon RVS environment selected by IAPKit. Present as `Sandbox` or
+   * `Production` on handled Amazon verification results.
+   *
+   * Deliberately String, not an enum: the value space belongs to IAPKit and the
+   * stores behind it, and Apple's App Store Server alone also names `Xcode` and
+   * `LocalTesting`. SDKs must forward this value opaquely. Never reject a
+   * verification because the environment is unrecognised — that fails a purchase
+   * the store already confirmed.
+   */
+  environment?: (string | null);
   /**
    * True when the purchase is valid and actionable.
    * Only entitled, pending-acknowledgment, or ready-to-consume return true.
@@ -2176,7 +2193,7 @@ export interface VerifyPurchaseProps {
 
 export type VerifyPurchaseResult = VerifyPurchaseResultAndroid | VerifyPurchaseResultHorizon | VerifyPurchaseResultIOS;
 
-export interface VerifyPurchaseResultAndroid {
+export interface VerifyPurchaseResultAndroid extends VerifyPurchaseResultCommon {
   autoRenewing: boolean;
   betaProduct: boolean;
   cancelDate?: (number | null);
@@ -2185,6 +2202,11 @@ export interface VerifyPurchaseResultAndroid {
   deferredSku?: (string | null);
   freeTrialEndDate: number;
   gracePeriodEndDate: number;
+  /**
+   * Whether the purchase is valid. Uniform across every VerifyPurchaseResult
+   * variant so callers can gate entitlement without inspecting the concrete type.
+   */
+  isValid: boolean;
   parentProductId: string;
   productId: string;
   productType: string;
@@ -2197,18 +2219,32 @@ export interface VerifyPurchaseResultAndroid {
   testTransaction: boolean;
 }
 
+/** Validity shared by every store-specific purchase verification result. */
+export interface VerifyPurchaseResultCommon {
+  /** Whether the purchase is valid, without inspecting the concrete result variant. */
+  isValid: boolean;
+}
+
 /**
  * Result from Meta Horizon verify_entitlement API.
  * Returns verification status and grant time for the entitlement.
  */
-export interface VerifyPurchaseResultHorizon {
+export interface VerifyPurchaseResultHorizon extends VerifyPurchaseResultCommon {
   /** Unix timestamp (seconds) when the entitlement was granted. */
   grantTime?: (number | null);
-  /** Whether the entitlement verification succeeded. */
+  /**
+   * Whether the purchase is valid. Uniform across every VerifyPurchaseResult
+   * variant so callers can gate entitlement without inspecting the concrete type.
+   */
+  isValid: boolean;
+  /**
+   * Whether the entitlement verification succeeded.
+   * @deprecated Renamed to isValid so every VerifyPurchaseResult variant answers validity the same way. Scheduled for removal in OpenIAP 4.0.
+   */
   success: boolean;
 }
 
-export interface VerifyPurchaseResultIOS {
+export interface VerifyPurchaseResultIOS extends VerifyPurchaseResultCommon {
   /** Whether the receipt is valid */
   isValid: boolean;
   /** JWS representation */

package/src/vega-adapter.ts

@@ -1271,8 +1271,15 @@ export function createVegaIapModule(service: VegaPurchasingService): RnIap {
           `IAPKit returned malformed response (HTTP ${status}).`,
         );
       }
+      // Forwarded opaquely: `environment` is String in the spec.
+      const rawEnvironment = json.environment;
+      const environment =
+        typeof rawEnvironment === 'string' && rawEnvironment.length > 0
+          ? rawEnvironment
+          : undefined;
 
       return {
+        ...(environment == null ? {} : {environment}),
         isValid: json.isValid,
         ...(productId == null ? {} : {productId}),
         state: normalizeIapkitState(json.state),
@@ -1341,6 +1348,9 @@ export function createVegaIapModule(service: VegaPurchasingService): RnIap {
           store: 'amazon',
           userId,
           receiptId,
+          ...(amazon.expectedProductId == null
+            ? {}
+            : {expectedProductId: amazon.expectedProductId}),
           ...(amazon.sandbox == null ? {} : {sandbox: amazon.sandbox}),
         }),
         signal: controller.signal,