@nosslabs/iap 8.0.0 → 8.2.0

package/dist/index.cjs

@@ -3,7 +3,6 @@
 var core = require('@capacitor/core');
 var nativePurchases = require('@capgo/native-purchases');
 var zod = require('zod');
-var preferences = require('@capacitor/preferences');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -62,8 +61,9 @@ var init_errors = __esm({
       // appUserId pre-attach
       /**
        * The supplied `appUserId` (literal or fetcher-returned) is not a valid
-       * UUID v4. Apple requires a UUID for `appAccountToken`; we enforce the
-       * same constraint cross-platform for a consistent contract.
+       * RFC 9562 UUID. Apple requires a UUID for `appAccountToken`; we enforce
+       * the same constraint cross-platform for a consistent contract. Any
+       * version is accepted — see `isValidUuid` for what is still refused.
        */
       INVALID_APP_USER_ID: "INVALID_APP_USER_ID",
       /**
@@ -103,7 +103,7 @@ var init_errors = __esm({
       // Storage
       STORAGE_ERROR: "Capacitor Preferences write failed. Check device storage availability; the in-memory state is still updated, only persistence failed.",
       // appUserId pre-attach
-      INVALID_APP_USER_ID: "appUserId must be a UUID v4 (e.g. crypto.randomUUID()). Apple requires this for appAccountToken; we enforce the same on Android for consistency.",
+      INVALID_APP_USER_ID: "appUserId must be an RFC 9562 UUID of any version (e.g. crypto.randomUUID(), or a UUIDv5 over a stable name). Apple requires a UUID for appAccountToken; we enforce the same on Android for consistency. Refused: the nil and max UUIDs, and non-RFC version/variant nibbles \u2014 so an id that merely looks like a UUID (a hyphen-formatted hash) will not pass.",
       APP_USER_ID_FETCH_FAILED: "The async appUserId fetcher threw or rejected. Inspect the cause field for the underlying error (network failure, backend non-2xx, parse failure)."
     };
     exports.IAPError = class _IAPError extends Error {
@@ -139,6 +139,280 @@ var init_platform = __esm({
   }
 });
 
+// src/adapters/native/capgo/map-purchase-error.ts
+function mapPurchaseError(error, productId) {
+  if (error instanceof exports.IAPError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+  if (lower.includes("cancel")) {
+    return new exports.IAPError({
+      code: exports.IAPErrorCode.USER_CANCELLED,
+      message: `Purchase of "${productId}" was cancelled.`,
+      cause: error
+    });
+  }
+  if (lower.includes("pending")) {
+    return new exports.IAPError({
+      code: exports.IAPErrorCode.PURCHASE_PENDING,
+      message: `Purchase of "${productId}" is pending external clearance.`,
+      cause: error
+    });
+  }
+  if (lower.includes("product not found") || lower.includes("cannot find product")) {
+    return new exports.IAPError({
+      code: exports.IAPErrorCode.PRODUCT_NOT_FOUND,
+      message: `Product "${productId}" was not found in the store catalog.`,
+      cause: error
+    });
+  }
+  return new exports.IAPError({
+    code: exports.IAPErrorCode.STORE_ERROR,
+    message: `Native purchase of "${productId}" failed.`,
+    cause: error
+  });
+}
+var init_map_purchase_error = __esm({
+  "src/adapters/native/capgo/map-purchase-error.ts"() {
+    init_errors();
+  }
+});
+
+// src/lib/subscription-period.ts
+function toIso8601Duration(period) {
+  if (!period || typeof period !== "object" || Array.isArray(period)) return null;
+  const { numberOfUnits, unit, unitString } = period;
+  if (typeof numberOfUnits !== "number" || !Number.isInteger(numberOfUnits) || numberOfUnits <= 0) {
+    return null;
+  }
+  const designator = (typeof unitString === "string" ? UNIT_BY_NAME.get(unitString) : void 0) ?? (typeof unit === "number" ? UNIT_BY_INT.get(unit) : void 0);
+  if (!designator) return null;
+  return `P${numberOfUnits}${designator}`;
+}
+var UNIT_BY_INT, UNIT_BY_NAME;
+var init_subscription_period = __esm({
+  "src/lib/subscription-period.ts"() {
+    UNIT_BY_INT = /* @__PURE__ */ new Map([
+      [0, "D"],
+      [1, "W"],
+      [2, "M"],
+      [3, "Y"]
+    ]);
+    UNIT_BY_NAME = /* @__PURE__ */ new Map([
+      ["day", "D"],
+      ["week", "W"],
+      ["month", "M"],
+      ["year", "Y"]
+    ]);
+  }
+});
+
+// src/adapters/native/capgo/normalize-product.ts
+function resolveProducts(payloads, requests) {
+  const products = [];
+  for (const request of requests) {
+    const candidates = payloads.filter((payload) => {
+      const p = payload;
+      return p.identifier === request.id || p.planIdentifier === request.id;
+    });
+    if (candidates.length === 0) continue;
+    products.push(normalizeProduct(pickCandidate(candidates, request.androidPlanId), request));
+  }
+  return products;
+}
+function pickCandidate(candidates, androidPlanId) {
+  const named = androidPlanId !== void 0 ? candidates.find((c) => c.identifier === androidPlanId) : void 0;
+  const basePlan = candidates.find((c) => (c.offerId ?? null) === null);
+  return named ?? basePlan ?? candidates[0];
+}
+function normalizeProduct(raw, request) {
+  const p = raw;
+  return {
+    // The id the consumer configured, so a Product round-trips to
+    // `purchase({ productId })`. On Android `p.identifier` is a base plan,
+    // which is reported separately as `androidBasePlanId`.
+    id: request.id,
+    type: request.type,
+    title: p.title,
+    description: p.description,
+    priceString: p.priceString,
+    priceMicros: toMicros(p.price),
+    currency: p.currencyCode,
+    // `toIso8601Duration` returns null for the `{ numberOfUnits: 0, unit: 0 }`
+    // placeholder a non-subscription carries, and for Android's absent value.
+    subscriptionPeriod: toIso8601Duration(p.subscriptionPeriod),
+    // capgo sends "" rather than null for a product with no group.
+    subscriptionGroupId: p.subscriptionGroupIdentifier || null,
+    introductoryOffer: p.introductoryPrice ? normalizeOffer(p.introductoryPrice) : null,
+    promotionalOffers: (p.discounts ?? []).map(normalizeOffer),
+    androidOfferToken: p.offerToken ?? null,
+    androidOfferId: p.offerId ?? null,
+    // Android only: the base plan this entry describes. Null on iOS, where
+    // `identifier` is the product id and there is no base-plan concept.
+    androidBasePlanId: p.planIdentifier !== void 0 ? p.identifier : null
+  };
+}
+function toMicros(price) {
+  if (typeof price !== "number" || !Number.isFinite(price)) return "0";
+  return Math.round(price * 1e6).toString();
+}
+function normalizeOffer(discount) {
+  return {
+    // An iOS introductory offer and an Android base-plan intro phase both
+    // arrive with an empty identifier; neither is named by its store.
+    id: discount.identifier || null,
+    type: mapOfferType(discount.type),
+    payment: mapOfferPayment(discount.paymentMode),
+    priceString: discount.priceString,
+    priceMicros: toMicros(discount.price),
+    currency: discount.currencyCode,
+    period: toIso8601Duration(discount.subscriptionPeriod),
+    periodCount: discount.numberOfPeriods
+  };
+}
+function mapOfferType(type) {
+  switch (type) {
+    case 0:
+      return "introductory";
+    case 1:
+      return "promotional";
+    case 2:
+      return "win-back";
+    default:
+      return "unknown";
+  }
+}
+function mapOfferPayment(paymentMode) {
+  switch (paymentMode) {
+    case 0:
+      return "free-trial";
+    case 1:
+      return "pay-up-front";
+    case 2:
+      return "pay-as-you-go";
+    default:
+      return "unknown";
+  }
+}
+var init_normalize_product = __esm({
+  "src/adapters/native/capgo/normalize-product.ts"() {
+    init_subscription_period();
+  }
+});
+
+// src/lib/jws.ts
+function decodeBase64UrlSegment(segment) {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+  let binary;
+  try {
+    binary = atob(padded);
+  } catch {
+    return null;
+  }
+  try {
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function readJwsClaims(jws) {
+  if (typeof jws !== "string" || jws.length === 0) return null;
+  const segments = jws.split(".");
+  if (segments.length !== 3) return null;
+  const payload = segments[1];
+  if (!payload) return null;
+  const json = decodeBase64UrlSegment(payload);
+  if (json === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  return parsed;
+}
+var init_jws = __esm({
+  "src/lib/jws.ts"() {
+  }
+});
+
+// src/adapters/native/capgo/normalize-transaction.ts
+function normalizeTransaction(tx, productType, packageName) {
+  const platform = inferPlatform(tx);
+  const token = platform === "google" ? tx.purchaseToken ?? tx.transactionId : tx.transactionId;
+  const native = {
+    platform,
+    productId: tx.productIdentifier,
+    token,
+    purchaseReference: purchaseReferenceFor(tx, platform, token),
+    productType,
+    // Lower-cased so it compares equal to what the caller supplied:
+    // StoreKit returns `UUID.uuidString`, which Swift renders uppercase,
+    // while `crypto.randomUUID()` and iap's case-insensitive validator both
+    // deal in lowercase. Returned raw, the binding would never `===` the
+    // value that was sent — the one comparison this field exists for.
+    appUserId: tx.appAccountToken?.toLowerCase() ?? null,
+    subscription: normalizeSubscription(tx, productType),
+    raw: tx
+  };
+  if (native.platform === "google" && packageName) {
+    native.packageName = packageName;
+  }
+  return native;
+}
+function purchaseReferenceFor(tx, platform, token) {
+  if (platform === "google" || !tx.jwsRepresentation) return token;
+  const claims = readJwsClaims(tx.jwsRepresentation);
+  const original = claims?.originalTransactionId;
+  return typeof original === "string" && original.length > 0 ? original : token;
+}
+function normalizeSubscription(tx, productType) {
+  if (productType !== "subscription") return null;
+  const renewalInfo = tx.renewalInfo;
+  const state = tx.subscriptionState ? SUBSCRIPTION_STATES.get(tx.subscriptionState) ?? "unknown" : null;
+  const autoRenewing = renewalInfo?.willAutoRenew ?? (typeof tx.willCancel === "boolean" ? !tx.willCancel : null);
+  const renewal = {
+    state,
+    autoRenewing,
+    renewsAt: renewalInfo?.renewalDate ?? null,
+    renewalProductId: renewalInfo?.autoRenewProductId ?? null,
+    expiresAt: tx.expirationDate ?? null
+  };
+  const reportedNothing = renewal.state === null && renewal.autoRenewing === null && renewal.renewsAt === null && renewal.renewalProductId === null && renewal.expiresAt === null;
+  return reportedNothing ? null : renewal;
+}
+function inferPlatform(tx) {
+  if (tx.purchaseToken !== void 0 || tx.purchaseState !== void 0 || tx.orderId !== void 0) {
+    return "google";
+  }
+  if (tx.receipt !== void 0 || tx.jwsRepresentation !== void 0) {
+    return "apple";
+  }
+  return getPlatform() === "android" ? "google" : "apple";
+}
+function inferProductType(tx, configured) {
+  if (tx.productType === "subs") return "subscription";
+  const declared = configured?.find((p) => p.id === tx.productIdentifier)?.type;
+  return declared === "consumable" ? "consumable" : "product";
+}
+var SUBSCRIPTION_STATES;
+var init_normalize_transaction = __esm({
+  "src/adapters/native/capgo/normalize-transaction.ts"() {
+    init_jws();
+    init_platform();
+    SUBSCRIPTION_STATES = /* @__PURE__ */ new Map([
+      ["subscribed", "subscribed"],
+      ["expired", "expired"],
+      ["revoked", "revoked"],
+      ["inGracePeriod", "in-grace-period"],
+      ["inBillingRetryPeriod", "in-billing-retry"],
+      ["unknown", "unknown"]
+    ]);
+  }
+});
+
 // src/lib/iso-country.ts
 function toAlpha2(code) {
   if (!code) return null;
@@ -403,12 +677,6 @@ var init_iso_country = __esm({
     };
   }
 });
-
-// src/adapters/native/capgo/native-adapter.ts
-var native_adapter_exports = {};
-__export(native_adapter_exports, {
-  CapgoNativeAdapter: () => CapgoNativeAdapter
-});
 function nativeStorefrontRegistered() {
   const headers = core.Capacitor.PluginHeaders;
   return headers?.find((h) => h.name === "NativePurchases")?.methods?.some((m) => m.name === "getStorefront") ?? false;
@@ -426,84 +694,139 @@ function normalizeStorefront(raw) {
     platform
   };
 }
-function normalizeProduct(p, type) {
-  const priceMicros = Math.round(p.price * 1e6).toString();
-  return {
-    id: p.identifier,
-    type,
-    title: p.title,
-    description: p.description,
-    priceString: p.priceString,
-    priceMicros,
-    currency: p.currencyCode
-  };
-}
-function normalizeTransaction(tx, productType) {
-  const platform = inferPlatform(tx);
-  const token = platform === "google" ? tx.purchaseToken ?? tx.transactionId : tx.transactionId;
-  const native = {
-    platform,
-    productId: tx.productIdentifier,
-    token,
-    productType,
-    raw: tx
-  };
-  return native;
+async function readStorefront() {
+  if (!nativeStorefrontRegistered()) return null;
+  const np = nativePurchases.NativePurchases;
+  try {
+    const raw = await np.getStorefront?.();
+    return raw ? normalizeStorefront(raw) : null;
+  } catch {
+    return null;
+  }
 }
-function inferPlatform(tx) {
-  if (tx.purchaseToken !== void 0 || tx.purchaseState !== void 0 || tx.orderId !== void 0) {
-    return "google";
+var init_storefront = __esm({
+  "src/adapters/native/capgo/storefront.ts"() {
+    init_iso_country();
+    init_platform();
   }
-  if (tx.receipt !== void 0 || tx.jwsRepresentation !== void 0) {
-    return "apple";
+});
+async function watchCapgoTransactions(onUpdate, logger, packageName, getConfiguredProducts) {
+  const handles = [];
+  try {
+    handles.push(
+      await nativePurchases.NativePurchases.addListener("transactionUpdated", (tx) => {
+        try {
+          onUpdate(
+            normalizeTransaction(tx, inferProductType(tx, getConfiguredProducts?.()), packageName)
+          );
+        } catch (error) {
+          logger.warn("transactionUpdated handler threw; ignoring the update.", error);
+        }
+      })
+    );
+  } catch (error) {
+    logger.warn(
+      "Could not subscribe to native transaction updates; renewals and refunds will be picked up at the next launch or resume instead.",
+      error
+    );
+    return null;
   }
-  return getPlatform() === "android" ? "google" : "apple";
+  try {
+    handles.push(
+      await nativePurchases.NativePurchases.addListener("transactionVerificationFailed", (payload) => {
+        logger.warn(
+          `The store reported a transaction that failed Apple's verification; ignoring it. Reason: ${payload.error}`
+        );
+      })
+    );
+  } catch (error) {
+    logger.debug("Could not subscribe to transactionVerificationFailed.", error);
+  }
+  return {
+    async remove() {
+      for (const handle of handles) {
+        try {
+          await handle.remove();
+        } catch (error) {
+          logger.warn("Failed to remove a native transaction listener.", error);
+        }
+      }
+    }
+  };
 }
-function inferProductType(tx) {
-  if (tx.productType === "subs") return "subscription";
-  return "product";
+async function getCapgoPendingProductIds(logger) {
+  if (getPlatform() !== "android") return null;
+  try {
+    const result = await nativePurchases.NativePurchases.getPurchases();
+    return result.purchases.filter((tx) => tx.purchaseState !== void 0 && tx.purchaseState !== "1").map((tx) => tx.productIdentifier);
+  } catch (error) {
+    logger.warn("Could not read pending purchases from the store.", error);
+    return null;
+  }
 }
+var init_watch_transactions = __esm({
+  "src/adapters/native/capgo/watch-transactions.ts"() {
+    init_platform();
+    init_normalize_transaction();
+  }
+});
+
+// src/adapters/native/capgo/native-adapter.ts
+var native_adapter_exports = {};
+__export(native_adapter_exports, {
+  CapgoNativeAdapter: () => CapgoNativeAdapter
+});
 function mapToPluginPurchaseType(type) {
   return type === "subscription" ? nativePurchases.PURCHASE_TYPE.SUBS : nativePurchases.PURCHASE_TYPE.INAPP;
 }
-function mapPurchaseError(error, productId) {
-  if (error instanceof exports.IAPError) return error;
-  const message = error instanceof Error ? error.message : String(error);
-  const lower = message.toLowerCase();
-  if (lower.includes("cancel")) {
-    return new exports.IAPError({
-      code: exports.IAPErrorCode.USER_CANCELLED,
-      message: `Purchase of "${productId}" was cancelled.`,
-      cause: error
-    });
-  }
-  if (lower.includes("pending")) {
-    return new exports.IAPError({
-      code: exports.IAPErrorCode.PURCHASE_PENDING,
-      message: `Purchase of "${productId}" is pending external clearance.`,
-      cause: error
-    });
-  }
-  if (lower.includes("product not found") || lower.includes("cannot find product")) {
-    return new exports.IAPError({
-      code: exports.IAPErrorCode.PRODUCT_NOT_FOUND,
-      message: `Product "${productId}" was not found in the store catalog.`,
-      cause: error
-    });
-  }
-  return new exports.IAPError({
-    code: exports.IAPErrorCode.STORE_ERROR,
-    message: `Native purchase of "${productId}" failed.`,
-    cause: error
-  });
-}
 var CapgoNativeAdapter;
 var init_native_adapter = __esm({
   "src/adapters/native/capgo/native-adapter.ts"() {
     init_errors();
-    init_iso_country();
-    init_platform();
+    init_map_purchase_error();
+    init_normalize_product();
+    init_normalize_transaction();
+    init_storefront();
+    init_watch_transactions();
     CapgoNativeAdapter = class {
+      /**
+       * @param logger used by the best-effort paths that swallow their failures.
+       * @param packageName the app's Android applicationId, from
+       *   `config.android.packageName`. Stamped onto every Google transaction
+       *   because the plugin does not report it and Google's verification
+       *   APIs are keyed on it.
+       * @param getConfiguredProducts the catalog, for typing a transaction the
+       *   store reported — the plugin's payload cannot distinguish a consumable
+       *   from a one-time purchase, since Play calls both `'inapp'`.
+       */
+      constructor(logger, packageName, getConfiguredProducts) {
+        this.logger = logger;
+        this.packageName = packageName;
+        this.getConfiguredProducts = getConfiguredProducts;
+      }
+      logger;
+      packageName;
+      getConfiguredProducts;
+      /**
+       * The configured catalog, for typing a transaction the store reported.
+       *
+       * An empty one is not benign: every store-reported consumable would type
+       * as `'product'`, be acknowledged rather than consumed, and stay owned —
+       * which is the bug the catalog exists to prevent, reachable by
+       * misconfiguration rather than by code. Warned once, since
+       * `getOwnedTransactions` runs on every refresh.
+       */
+      configured() {
+        const products = this.getConfiguredProducts?.() ?? [];
+        if (products.length === 0 && !this.warnedAboutEmptyCatalog) {
+          this.warnedAboutEmptyCatalog = true;
+          this.logger.warn(
+            "The native adapter has no configured products, so a purchase the store reports cannot be recognised as a consumable and will be acknowledged rather than consumed \u2014 leaving it owned and unbuyable. This is a wiring problem inside iap; please report it."
+          );
+        }
+        return products;
+      }
+      warnedAboutEmptyCatalog = false;
       async isAvailable() {
         try {
           const result = await nativePurchases.NativePurchases.isBillingSupported();
@@ -516,9 +839,7 @@ var init_native_adapter = __esm({
         if (requests.length === 0) return [];
         const inappIds = [];
         const subsIds = [];
-        const requestById = /* @__PURE__ */ new Map();
         for (const req of requests) {
-          requestById.set(req.id, req.type);
           if (req.type === "subscription") {
             subsIds.push(req.id);
           } else {
@@ -536,11 +857,10 @@ var init_native_adapter = __esm({
           }) : Promise.resolve({ products: [] })
         ]);
         const all = [...inapp.products, ...subs.products];
-        return all.map((p) => normalizeProduct(p, requestById.get(p.identifier) ?? "product"));
+        return resolveProducts(all, requests);
       }
       async purchaseProduct(opts) {
         const purchaseType = mapToPluginPurchaseType(opts.productType);
-        const isConsumable = opts.productType === "consumable";
         let tx;
         try {
           tx = await nativePurchases.NativePurchases.purchaseProduct({
@@ -548,17 +868,35 @@ var init_native_adapter = __esm({
             productType: purchaseType,
             planIdentifier: opts.androidPlanId,
             appAccountToken: opts.appAccountToken,
-            isConsumable,
+            // `false` even for a consumable, and this is load-bearing.
+            //
+            // `autoAcknowledgePurchases: false` does **not** cover the
+            // consumable case: the plugin's `PurchaseActionDecider` returns
+            // CONSUME whenever `isConsumable` is set, and its caller consumes
+            // without consulting `autoAcknowledgePurchases` — that flag is only
+            // read on the ACKNOWLEDGE branch. (Checked in the plugin's Java,
+            // not its docs, and guarded by a test in
+            // `tests/unit/native-plugin-contract.test.ts`.)
+            //
+            // So passing `true` here would have the plugin consume inside the
+            // purchase callback, before iap has verified anything — breaking
+            // acknowledge-only-after-verification for exactly the product type
+            // where it cannot be undone, since Billing 8.x drops a consumed
+            // purchase from `getPurchases()` entirely. iap consumes itself,
+            // after verification, via {@link CapgoNativeAdapter.consume}.
+            isConsumable: false,
             autoAcknowledgePurchases: false
           });
         } catch (error) {
           throw mapPurchaseError(error, opts.productId);
         }
-        return normalizeTransaction(tx, opts.productType);
+        return normalizeTransaction(tx, opts.productType, this.packageName);
       }
       async getOwnedTransactions() {
         const result = await nativePurchases.NativePurchases.getPurchases();
-        return result.purchases.filter((tx) => tx.purchaseState === void 0 || tx.purchaseState === "1").map((tx) => normalizeTransaction(tx, inferProductType(tx)));
+        return result.purchases.filter((tx) => tx.purchaseState === void 0 || tx.purchaseState === "1").map(
+          (tx) => normalizeTransaction(tx, inferProductType(tx, this.configured()), this.packageName)
+        );
       }
       async acknowledge(transaction) {
         try {
@@ -574,6 +912,31 @@ var init_native_adapter = __esm({
           });
         }
       }
+      /**
+       * Consume an Android consumable, releasing ownership so it can be bought
+       * again. See {@link NativeAdapter.consume} for why acknowledging is not
+       * enough.
+       *
+       * The plugin rejects this on iOS and web, so the core calls it only for
+       * Google transactions.
+       */
+      async consume(transaction) {
+        try {
+          await nativePurchases.NativePurchases.consumePurchase({
+            purchaseToken: transaction.token
+          });
+        } catch (error) {
+          throw new exports.IAPError({
+            code: exports.IAPErrorCode.STORE_ERROR,
+            message: `Failed to consume transaction for ${transaction.productId}.`,
+            cause: error,
+            // Retried by the recovery loop like a failed acknowledge: until it
+            // succeeds, Play still reports the product owned and the user
+            // cannot buy it again.
+            recoverable: true
+          });
+        }
+      }
       async manageSubscriptions() {
         try {
           await nativePurchases.NativePurchases.manageSubscriptions();
@@ -594,14 +957,20 @@ var init_native_adapter = __esm({
        * rejection, or empty country — resolves to `null` rather than throwing.
        */
       async getStorefront() {
-        if (!nativeStorefrontRegistered()) return null;
-        const np = nativePurchases.NativePurchases;
-        try {
-          const raw = await np.getStorefront?.();
-          return raw ? normalizeStorefront(raw) : null;
-        } catch {
-          return null;
-        }
+        return readStorefront();
+      }
+      /**
+       * Subscribe to Apple's `Transaction.updates`. See
+       * {@link watchCapgoTransactions} — iOS only in practice, and silent
+       * about its own failures, since a missing listener degrades to
+       * reconciliation rather than breaking anything.
+       */
+      async watchTransactions(onUpdate) {
+        return watchCapgoTransactions(onUpdate, this.logger, this.packageName, () => this.configured());
+      }
+      /** Android only; `null` on iOS. See {@link getCapgoPendingProductIds}. */
+      async getPendingProductIds() {
+        return getCapgoPendingProductIds(this.logger);
       }
       async dispose() {
       }
@@ -791,6 +1160,14 @@ var HttpClient = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+// src/lib/uuid.ts
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isValidUuid(value) {
+  return typeof value === "string" && UUID_REGEX.test(value);
+}
+
+// src/types/config.ts
 var productTypeSchema = zod.z.enum(["subscription", "product", "consumable"]);
 var configuredProductSchema = zod.z.object({
   id: zod.z.string().min(1),
@@ -890,6 +1267,38 @@ var backendConfigSchema = zod.z.object({
     });
   }
 });
+var verificationConfigSchema = zod.z.object({
+  mode: zod.z.literal("local"),
+  /**
+   * Maps a verified purchase to the entitlements it grants. Required: iap
+   * does not know what a product entitles anyone to, and in local mode
+   * there is no backend to ask. Type is checked at runtime via a shape
+   * guard, not zod — see {@link VerificationConfig}.
+   */
+  entitlements: zod.z.unknown(),
+  /**
+   * The binding every purchase must carry, as passed to
+   * `purchase({ appUserId })`. A purchase bound to something else is
+   * refused. Omit it if the app does not bind purchases.
+   *
+   * Either the id itself, or a function returning it — in which case it is
+   * read **at the time of each check**, so the binding follows the session.
+   * A fixed string is captured at `createIAP()` time and cannot track a
+   * login change, which in a multi-user app means every purchase after a
+   * switch is refused as the previous user's.
+   *
+   * The function may return `null` for "nobody is signed in right now".
+   * That is **not** the same as using no binding: iap refuses the purchase
+   * rather than dropping the check. See `LocalVerificationAdapter`.
+   *
+   * Typed via the overlay on {@link VerificationConfig}; validated in the
+   * schema's `superRefine`, the same way the backend's functions are.
+   */
+  appUserId: zod.z.unknown().optional()
+});
+var androidConfigSchema = zod.z.object({
+  packageName: zod.z.string().min(1).optional()
+});
 var storageConfigSchema = zod.z.object({
   type: zod.z.enum(["preferences", "memory", "custom"]).default("preferences"),
   namespace: zod.z.string().min(1).default("nosslabs_iap"),
@@ -898,6 +1307,21 @@ var storageConfigSchema = zod.z.object({
 var optionsConfigSchema = zod.z.object({
   refreshOnResume: zod.z.boolean().default(true),
   entitlementCacheTtlMs: zod.z.number().int().positive().default(60 * 60 * 1e3),
+  /**
+   * Extra time past an entitlement's `expiresAt` during which it still
+   * counts as active, by the **device** clock.
+   *
+   * Exists because a renewal is not instantaneous: a subscription that
+   * renews at midnight may not have a fresh receipt on the device for
+   * minutes or hours, and locking the user out in that window is a worse
+   * error than letting a lapsed subscription run slightly long. Store
+   * grace periods and billing retry can stretch much further — on Android
+   * those are server-side only, so a backendless app cannot see them at all
+   * and this window is the only cushion it has.
+   *
+   * Defaults to 0: no grace, which is the strict reading of `expiresAt`.
+   */
+  entitlementGraceMs: zod.z.number().int().nonnegative().default(0),
   recoverUnfinishedTransactions: zod.z.boolean().default(true),
   /**
    * Cap on how many unfinished transactions recovery inspects per launch.
@@ -931,7 +1355,16 @@ var iapConfigSchema = zod.z.object({
    * without either path throw `INVALID_CONFIG` at parse time.
    */
   products: zod.z.array(configuredProductSchema).min(1).optional(),
-  backend: backendConfigSchema,
+  /**
+   * The consumer's backend, which calls Attesto. Optional **only** when
+   * `verification` is set instead — one of the two has to answer
+   * whether a purchase is real.
+   */
+  backend: backendConfigSchema.optional(),
+  /** On-device verification, for an app with no backend. */
+  verification: verificationConfigSchema.optional(),
+  /** Android-specific settings. See {@link androidConfigSchema}. */
+  android: androidConfigSchema.default({}),
   storage: storageConfigSchema.default({ type: "preferences", namespace: "nosslabs_iap" }),
   options: optionsConfigSchema.default({
     refreshOnResume: true,
@@ -942,10 +1375,49 @@ var iapConfigSchema = zod.z.object({
     logLevel: "info"
   })
 }).superRefine((data, ctx) => {
+  if (data.backend && data.verification) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "Set either backend or verification, not both \u2014 they are two answers to the same question.",
+      path: []
+    });
+  }
+  if (!data.backend && !data.verification) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: 'One of backend or verification is required: something has to verify a purchase before an entitlement is granted. Use verification: { mode: "local", entitlements } for an app with no backend.',
+      path: []
+    });
+  }
+  if (data.verification && typeof data.verification.entitlements !== "function") {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "verification.entitlements must be a function ((purchase) => TEntitlement[]) \u2014 iap cannot know what a product entitles a user to.",
+      path: ["verification", "entitlements"]
+    });
+  }
+  const binding = data.verification?.appUserId;
+  if (data.verification && binding !== void 0 && typeof binding !== "function" && !(typeof binding === "string" && isValidUuid(binding))) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "verification.appUserId must be an RFC 9562 UUID, or a function returning one (or null when nobody is signed in) \u2014 the same constraint purchase({ appUserId }) enforces.",
+      path: ["verification", "appUserId"]
+    });
+  }
+  if (data.verification && data.products === void 0) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "products is required in local verification mode: there is no backend to supply the manifest.",
+      path: ["products"]
+    });
+  }
   if (data.products !== void 0) return;
-  const adapter = data.backend.adapter;
+  if (data.verification) return;
+  const backend = data.backend;
+  if (!backend) return;
+  const adapter = backend.adapter;
   const adapterCanList = adapter && typeof adapter.listProducts === "function";
-  const httpCanList = !data.backend.adapter && data.backend.endpoints?.products;
+  const httpCanList = !backend.adapter && backend.endpoints?.products;
   if (!adapterCanList && !httpCanList) {
     ctx.addIssue({
       code: zod.z.ZodIssueCode.custom,
@@ -986,7 +1458,8 @@ var verifyResponseSchema = zod.z.discriminatedUnion("valid", [
 ]);
 var restoreSuccessSchema = zod.z.object({
   valid: zod.z.literal(true),
-  entitlements: zod.z.array(passthroughEntitlementSchema)
+  entitlements: zod.z.array(passthroughEntitlementSchema),
+  verifiedTokens: zod.z.array(zod.z.string()).optional()
 }).passthrough();
 var restoreResponseSchema = zod.z.discriminatedUnion("valid", [
   restoreSuccessSchema,
@@ -997,7 +1470,10 @@ var productManifestResponseSchema = zod.z.object({ products: configuredProductsA
 function isBackendAdapter(value) {
   if (!value || typeof value !== "object") return false;
   const candidate = value;
-  return typeof candidate.verifyApple === "function" && typeof candidate.verifyGoogle === "function" && typeof candidate.getEntitlements === "function" && typeof candidate.restore === "function";
+  if (typeof candidate.getEntitlements !== "function") return false;
+  const hasExtracted = typeof candidate.verifyApple === "function" && typeof candidate.verifyGoogle === "function" && typeof candidate.restore === "function";
+  const hasNative = typeof candidate.verifyNative === "function" && (typeof candidate.restore === "function" || typeof candidate.restoreNative === "function");
+  return hasExtracted || hasNative;
 }
 
 // src/adapters/backend/http-adapter.ts
@@ -1073,9 +1549,373 @@ var HttpBackendAdapter = class {
   }
 };
 
+// src/core/local-verification.ts
+function isExpired(expiresAt, now, graceMs = 0) {
+  if (!expiresAt) return false;
+  const expiry = Date.parse(expiresAt);
+  if (Number.isNaN(expiry)) return false;
+  const grace = Number.isFinite(graceMs) ? graceMs : 0;
+  return now > expiry + grace;
+}
+function verifyPurchaseOnDevice(transaction, options) {
+  const now = (options.now ?? Date.now)();
+  if (!options.productIds.includes(transaction.productId)) {
+    return {
+      valid: false,
+      error: "PRODUCT_NOT_CONFIGURED",
+      message: `The store reported a purchase of "${transaction.productId}", which is not in the configured product list.`
+    };
+  }
+  const expected = options.appUserId;
+  if (expected) {
+    const actual = transaction.appUserId ?? null;
+    if (actual === null || actual.toLowerCase() !== expected.toLowerCase()) {
+      return {
+        valid: false,
+        error: "BINDING_MISMATCH",
+        message: `The purchase of "${transaction.productId}" is not bound to the expected account.`
+      };
+    }
+  }
+  if (transaction.platform === "google") {
+    const state = transaction.raw?.purchaseState;
+    if (state !== void 0 && state !== null && String(state) !== "1") {
+      return {
+        valid: false,
+        error: "NOT_PURCHASED",
+        message: `The purchase of "${transaction.productId}" is not in Play's purchased state.`
+      };
+    }
+  }
+  const revocationDate = transaction.raw?.revocationDate;
+  if (transaction.subscription?.state === "revoked" || typeof revocationDate === "string") {
+    return {
+      valid: false,
+      error: "REVOKED",
+      message: `The purchase of "${transaction.productId}" has been revoked or refunded.`
+    };
+  }
+  const expiresAt = transaction.subscription?.expiresAt ?? null;
+  if (isExpired(expiresAt, now, options.graceMs)) {
+    return {
+      valid: false,
+      error: "SUBSCRIPTION_EXPIRED",
+      message: `The subscription "${transaction.productId}" expired at ${expiresAt}.`
+    };
+  }
+  return {
+    valid: true,
+    purchase: {
+      productId: transaction.productId,
+      platform: transaction.platform,
+      productType: transaction.productType,
+      purchaseReference: transaction.purchaseReference,
+      appUserId: transaction.appUserId ?? null,
+      expiresAt,
+      subscription: transaction.subscription ?? null,
+      // iOS transactions are signature-checked by StoreKit in native code
+      // before they cross the bridge; Android has no equivalent available.
+      assurance: transaction.platform === "apple" ? "store-signed" : "store-reported"
+    }
+  };
+}
+
+// src/adapters/backend/local-adapter.ts
+init_errors();
+var LocalVerificationAdapter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /**
+   * The whole transaction, not the extracted fields the HTTP contract sends.
+   *
+   * A local check needs the binding, the subscription state and the expiry,
+   * and `VerifyAppleRequest` carries none of them — it is shaped for what a
+   * server needs to look a receipt up. The router prefers this method when
+   * an adapter has it, so the HTTP path is unaffected.
+   */
+  async verifyNative(transaction) {
+    const checked = this.check(transaction);
+    if (!checked.valid) return checked;
+    return {
+      valid: true,
+      entitlements: await this.consolidated(checked.purchase),
+      transaction: checked.transaction
+    };
+  }
+  /**
+   * Unreachable in practice: the router prefers {@link verifyNative}. Kept
+   * because `BackendAdapter` requires them, and failing loudly is better
+   * than silently granting if a future caller bypasses the router.
+   */
+  async verifyApple() {
+    throw this.unsupported("verifyApple");
+  }
+  async verifyGoogle() {
+    throw this.unsupported("verifyGoogle");
+  }
+  /**
+   * In local mode the store **is** the source of truth, so a refresh asks
+   * it what it owns and re-derives entitlements from that.
+   *
+   * This is why `refreshOnResume` keeps working with no network: there is
+   * nothing to reach. A purchase that expired while the app was backgrounded
+   * drops out here, which is the only downgrade local mode performs.
+   */
+  async getEntitlements() {
+    const binding = this.binding();
+    if (!binding.ok) {
+      this.opts.logger.debug(
+        `Keeping the current entitlements: ${binding.error}. ${binding.message}`
+      );
+      return this.opts.getCurrentEntitlements();
+    }
+    const owned = await this.ownedTransactions();
+    if (owned.length === 0) {
+      const current = this.opts.getCurrentEntitlements();
+      if (current.length > 0) {
+        this.opts.logger.debug(
+          "The store reported nothing owned. Keeping the current entitlements, since an empty answer is indistinguishable from a failed query."
+        );
+      }
+      return current;
+    }
+    return this.consolidated();
+  }
+  /**
+   * Restore is the same question as a refresh here — "what does this store
+   * account own" — answered from the transactions the orchestrator already
+   * read, so the store is not asked twice.
+   */
+  async restoreNative(owned) {
+    const binding = this.binding();
+    if (!binding.ok) {
+      return { valid: false, error: binding.error, message: binding.message };
+    }
+    const { entitlements, verifiedTokens } = this.evaluate(owned);
+    if (verifiedTokens.length === 0) {
+      return {
+        valid: false,
+        error: "NO_VERIFIED_PURCHASES",
+        message: "The store reported purchases, but none passed the on-device checks."
+      };
+    }
+    return { valid: true, entitlements, verifiedTokens };
+  }
+  /**
+   * Unreachable via the orchestrator, which prefers {@link restoreNative}.
+   * Kept so the adapter satisfies a consumer holding it as a plain
+   * `BackendAdapter`; it re-reads the store rather than trusting an
+   * extracted request a local check cannot verify from.
+   */
+  async restore(_req) {
+    return this.restoreNative(await this.ownedTransactions());
+  }
+  /**
+   * The binding to check against, or a refusal.
+   *
+   * Read per check rather than once at construction, because a
+   * `verification.appUserId` getter exists precisely so the binding can
+   * follow the session: in a multi-user app a value captured at
+   * `createIAP()` time is the previous user's after a switch, and every
+   * purchase is then refused as a mismatch.
+   *
+   * The thing it will not do is treat "no account right now" as "this app
+   * uses no binding". That would turn a signed-out session into an
+   * unguarded one, accepting a purchase bound to **someone else** — a
+   * weaker check than the app asked for, silently. Refusing is the safe
+   * direction: the purchase stays unacknowledged and the store retries it.
+   */
+  binding() {
+    const resolve = this.opts.getAppUserId;
+    if (!resolve) return { ok: true, appUserId: null };
+    let value;
+    try {
+      value = resolve();
+    } catch (error) {
+      this.opts.logger.warn(
+        "verification.appUserId threw. Refusing purchases rather than dropping the binding check.",
+        error
+      );
+      return {
+        ok: false,
+        error: "BINDING_UNAVAILABLE",
+        message: "The expected account binding could not be read."
+      };
+    }
+    if (value === null || value === void 0 || value === "") {
+      return {
+        ok: false,
+        error: "BINDING_UNAVAILABLE",
+        message: "This app binds purchases to an account, and verification.appUserId resolved to none. Nothing can be verified until someone is signed in."
+      };
+    }
+    if (!isValidUuid(value) && !this.warnedAboutBinding) {
+      this.warnedAboutBinding = true;
+      this.opts.logger.warn(
+        "verification.appUserId returned a value that is not an RFC 9562 UUID. purchase({ appUserId }) only accepts UUIDs, so no purchase can ever match it."
+      );
+    }
+    return { ok: true, appUserId: value };
+  }
+  /** Warned once per instance, not once per check — a refresh runs this. */
+  warnedAboutBinding = false;
+  checkOptions(appUserId) {
+    return {
+      productIds: this.opts.getProducts().map((p) => p.id),
+      appUserId,
+      graceMs: this.opts.graceMs
+    };
+  }
+  check(transaction) {
+    const binding = this.binding();
+    if (!binding.ok) {
+      this.opts.logger.debug(
+        `Local verification refused "${transaction.productId}": ${binding.error}.`
+      );
+      return { valid: false, error: binding.error, message: binding.message };
+    }
+    const result = verifyPurchaseOnDevice(transaction, this.checkOptions(binding.appUserId));
+    if (!result.valid) {
+      this.opts.logger.debug(
+        `Local verification refused "${transaction.productId}": ${result.error}.`
+      );
+      return { valid: false, error: result.error, message: result.message };
+    }
+    return {
+      valid: true,
+      purchase: result.purchase,
+      transaction: {
+        // The purchase's own identity, not a server-assigned id — there is
+        // no server to assign one. Note it is stable across renewals, so it
+        // is not a per-transaction key.
+        id: result.purchase.purchaseReference,
+        productId: result.purchase.productId,
+        expiresAt: result.purchase.expiresAt
+      }
+    };
+  }
+  /**
+   * Run the consumer's mapper and validate what it returns.
+   *
+   * Unlike a backend response, this value never went through a schema — it
+   * comes straight from consumer code into iap's state and cache. An
+   * unvalidated mapper could cache an object with no `key` (so
+   * `hasEntitlement` could never match it, and the next launch would drop it
+   * from the cache, making entitlements differ between sessions), or return
+   * a non-array and throw a raw `TypeError` out of `purchase()` *after* the
+   * transaction was acknowledged.
+   */
+  map(purchase) {
+    let mapped;
+    try {
+      mapped = this.opts.entitlements(purchase);
+    } catch (error) {
+      this.opts.logger.warn(
+        `verification.entitlements threw for "${purchase.productId}"; granting nothing for it.`,
+        error
+      );
+      return [];
+    }
+    const parsed = zod.z.array(entitlementBaseSchema.passthrough()).safeParse(mapped);
+    if (!parsed.success) {
+      this.opts.logger.warn(
+        `verification.entitlements returned something that is not a list of entitlements for "${purchase.productId}"; granting nothing for it. Each entry needs a key, a productId and an expiresAt (which may be null).`
+      );
+      return [];
+    }
+    return parsed.data;
+  }
+  /** The consolidated entitlements, optionally merging a just-verified purchase. */
+  async consolidated(extra) {
+    const owned = await this.ownedTransactions();
+    const { entitlements } = this.evaluate(owned, extra);
+    return entitlements;
+  }
+  /**
+   * Evaluate an owned set: which transactions passed, and what they grant.
+   *
+   * Returns the tokens that passed as well as the entitlements, because the
+   * caller needs to know *which* transactions may be acknowledged — a
+   * single consolidated list cannot say.
+   */
+  evaluate(owned, extra) {
+    const binding = this.binding();
+    if (!binding.ok) return { entitlements: [], verifiedTokens: [] };
+    const options = this.checkOptions(binding.appUserId);
+    const verifiedTokens = [];
+    const byKey = /* @__PURE__ */ new Map();
+    const absorb = (purchase) => {
+      for (const entitlement of this.map(purchase)) {
+        const existing = byKey.get(entitlement.key);
+        if (!existing || outlasts(entitlement.expiresAt, existing.expiresAt)) {
+          byKey.set(entitlement.key, entitlement);
+        }
+      }
+    };
+    for (const transaction of owned) {
+      const result = verifyPurchaseOnDevice(transaction, options);
+      if (!result.valid) {
+        this.opts.logger.debug(
+          `Local verification refused "${transaction.productId}": ${result.error}.`
+        );
+        continue;
+      }
+      verifiedTokens.push(transaction.token);
+      absorb(result.purchase);
+    }
+    if (extra) absorb(extra);
+    return { entitlements: [...byKey.values()], verifiedTokens };
+  }
+  async ownedTransactions() {
+    const native = this.opts.getNativeAdapter();
+    if (!native) {
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.NOT_INITIALIZED,
+        message: "Local verification needs the native adapter; call iap.initialize() first."
+      });
+    }
+    return native.getOwnedTransactions();
+  }
+  unsupported(method) {
+    return new exports.IAPError({
+      code: exports.IAPErrorCode.INVALID_CONFIG,
+      message: `${method}() cannot verify locally: it receives only the extracted request fields, and an on-device check needs the binding, the subscription state and the expiry. Call verifyNative(transaction) instead \u2014 which is what iap's own router does.`
+    });
+  }
+};
+function outlasts(a, b) {
+  if (a === null) return true;
+  if (b === null) return false;
+  return Date.parse(a) > Date.parse(b);
+}
+
 // src/adapters/backend/index.ts
 function selectBackendAdapter(options) {
-  const { config, logger, fetch: fetchImpl } = options;
+  const { config: iapConfig, logger, fetch: fetchImpl } = options;
+  if (iapConfig.verification) {
+    const verification = iapConfig.verification;
+    return new LocalVerificationAdapter({
+      getNativeAdapter: options.getNativeAdapter ?? (() => null),
+      getProducts: options.getProducts ?? (() => iapConfig.products ?? []),
+      entitlements: verification.entitlements,
+      // Passed only when the app actually binds purchases: the adapter
+      // reads "no resolver" as "no binding required", and a resolver
+      // returning null as "required, but nobody is signed in".
+      ...verification.appUserId === void 0 ? {} : { getAppUserId: resolveAppUserId(verification.appUserId) },
+      getCurrentEntitlements: () => options.getCurrentEntitlements?.() ?? [],
+      graceMs: iapConfig.options.entitlementGraceMs,
+      logger
+    });
+  }
+  const config = iapConfig.backend;
+  if (!config) {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.INVALID_CONFIG,
+      message: "Neither backend nor verification is configured; the schema should have caught this. This is a library bug."
+    });
+  }
   if (config.adapter !== void 0) {
     if (!isBackendAdapter(config.adapter)) {
       throw new exports.IAPError({
@@ -1103,49 +1943,8 @@ function selectBackendAdapter(options) {
     ...fetchImpl ? { fetch: fetchImpl } : {}
   });
 }
-
-// src/adapters/native/index.ts
-init_platform();
-
-// src/adapters/native/web/web-stub.ts
-init_errors();
-var WebStubAdapter = class {
-  async isAvailable() {
-    return false;
-  }
-  async getProducts(_requests) {
-    return [];
-  }
-  async purchaseProduct(_opts) {
-    throw new exports.IAPError({
-      code: exports.IAPErrorCode.PLATFORM_NOT_SUPPORTED,
-      message: "In-app purchases are not supported on the web platform."
-    });
-  }
-  async getOwnedTransactions() {
-    return [];
-  }
-  async acknowledge(_transaction) {
-  }
-  async manageSubscriptions() {
-    throw new exports.IAPError({
-      code: exports.IAPErrorCode.PLATFORM_NOT_SUPPORTED,
-      message: "Subscription management is not supported on the web platform."
-    });
-  }
-  async getStorefront() {
-    return null;
-  }
-};
-
-// src/adapters/native/index.ts
-async function selectNativeAdapter() {
-  const platform = getPlatform();
-  if (platform === "ios" || platform === "android") {
-    const mod = await Promise.resolve().then(() => (init_native_adapter(), native_adapter_exports));
-    return new mod.CapgoNativeAdapter();
-  }
-  return new WebStubAdapter();
+function resolveAppUserId(appUserId) {
+  return typeof appUserId === "function" ? appUserId : () => appUserId;
 }
 
 // src/adapters/storage/index.ts
@@ -1179,39 +1978,122 @@ init_errors();
 var PreferencesAdapter = class {
   prefix;
   knownKeys = /* @__PURE__ */ new Set();
+  /**
+   * Boxed, and that is not incidental — see {@link PreferencesAdapter.preferences}.
+   */
+  plugin = null;
   constructor(namespace) {
     this.prefix = `${namespace}.`;
   }
+  /**
+   * The plugin, inside a box.
+   *
+   * The box is load-bearing. `registerPlugin()` hands back a **Proxy** that
+   * answers any property, `then` included — so resolving a promise *with*
+   * the plugin makes it look like a thenable, and promise assimilation
+   * calls `Preferences.then()`. On web that rejects with
+   * `"Preferences.then()" is not implemented on web`, from inside
+   * `await this.preferences()`, for every storage operation.
+   *
+   * Wrapping it in a plain object means the promise resolves with something
+   * that has no `then`, so nothing is assimilated.
+   */
+  preferences() {
+    this.plugin ??= import('@capacitor/preferences').then((mod) => ({ preferences: mod.Preferences })).catch((cause) => {
+      if (isModuleNotFound(cause)) throw notInstalled(cause);
+      this.plugin = null;
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.STORAGE_ERROR,
+        message: "Could not load @capacitor/preferences. The package is installed, so this is most likely a chunk that failed to load; it is worth retrying.",
+        cause,
+        recoverable: true
+      });
+    });
+    return this.plugin;
+  }
+  /**
+   * Resolve the plugin now, so a missing one is reported at `initialize()`.
+   *
+   * See the note on lazy loading above for why this is not left to the first
+   * `get()`.
+   */
+  async ensureAvailable() {
+    await this.preferences();
+  }
   async get(key) {
+    const { preferences } = await this.preferences();
     try {
-      const result = await preferences.Preferences.get({ key: this.prefix + key });
+      const result = await preferences.get({ key: this.prefix + key });
       return result.value;
     } catch (cause) {
       throw wrap(cause, `Preferences.get failed for "${key}".`);
     }
   }
   async set(key, value) {
+    const { preferences } = await this.preferences();
     try {
-      await preferences.Preferences.set({ key: this.prefix + key, value });
+      await preferences.set({ key: this.prefix + key, value });
       this.knownKeys.add(key);
     } catch (cause) {
       throw wrap(cause, `Preferences.set failed for "${key}".`);
     }
   }
   async remove(key) {
+    const { preferences } = await this.preferences();
     try {
-      await preferences.Preferences.remove({ key: this.prefix + key });
+      await preferences.remove({ key: this.prefix + key });
       this.knownKeys.delete(key);
     } catch (cause) {
       throw wrap(cause, `Preferences.remove failed for "${key}".`);
     }
   }
   async clear() {
+    const { preferences } = await this.preferences();
     const keys = [...this.knownKeys];
-    this.knownKeys.clear();
-    await Promise.all(keys.map((k) => preferences.Preferences.remove({ key: this.prefix + k })));
+    const failed = [];
+    const errors = [];
+    await Promise.all(
+      keys.map(async (key) => {
+        try {
+          await preferences.remove({ key: this.prefix + key });
+          this.knownKeys.delete(key);
+        } catch (cause) {
+          failed.push(key);
+          errors.push(cause);
+        }
+      })
+    );
+    if (failed.length > 0) {
+      throw wrap(errors[0], `Preferences.clear failed for ${failed.length} key(s).`);
+    }
   }
 };
+function isModuleNotFound(cause) {
+  let current = cause;
+  for (let depth = 0; depth < 5 && current; depth += 1) {
+    const code = current.code;
+    if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") return true;
+    const message = current instanceof Error ? current.message : String(current);
+    if (/cannot find (module|package)|could not resolve|failed to resolve/i.test(message)) {
+      return true;
+    }
+    const next = current.cause;
+    if (next === current) break;
+    current = next;
+  }
+  return false;
+}
+function notInstalled(cause) {
+  return new exports.IAPError({
+    code: exports.IAPErrorCode.INVALID_CONFIG,
+    message: 'storage.type is "preferences" (the default) but @capacitor/preferences is not installed. Install it (npm i @capacitor/preferences && npx cap sync), or choose storage that needs no plugin: storage.type "memory", or "custom" with your own adapter.',
+    // The per-code hint for INVALID_CONFIG sends the reader to check field
+    // paths against the config schema. There are none to check, and no
+    // config change fixes this — the message above already says what to do.
+    includeHint: false,
+    cause
+  });
+}
 function wrap(cause, message) {
   return new exports.IAPError({
     code: exports.IAPErrorCode.STORAGE_ERROR,
@@ -1243,51 +2125,28 @@ function isStorageAdapter(value) {
   return typeof candidate.get === "function" && typeof candidate.set === "function" && typeof candidate.remove === "function" && typeof candidate.clear === "function";
 }
 
-// src/core/app-resume-listener.ts
-async function attachAppResumeListener(opts) {
-  let mod;
-  try {
-    mod = await import('@capacitor/app');
-  } catch (error) {
-    opts.logger.warn(
-      "refreshOnResume requested but @capacitor/app is not installed; resume listener disabled.",
-      error
-    );
-    return null;
-  }
-  let handle;
-  try {
-    handle = await mod.App.addListener("appStateChange", ({ isActive }) => {
-      if (!isActive) return;
-      void Promise.resolve(opts.onResume()).catch((error) => {
-        opts.logger.warn("refreshOnResume handler threw.", error);
-      });
-    });
-  } catch (error) {
-    opts.logger.warn(
-      "Failed to attach App appStateChange listener; resume refresh disabled.",
-      error
-    );
-    return null;
-  }
-  return {
-    async remove() {
-      try {
-        await handle.remove();
-      } catch (error) {
-        opts.logger.warn("Failed to remove App appStateChange listener.", error);
-      }
-    }
-  };
-}
-
-// src/core/entitlement-cache.ts
-init_errors();
-var ENTITLEMENTS_KEY = "entitlements";
-var EntitlementCache = class {
-  constructor(storage, logger) {
-    this.storage = storage;
-    this.logger = logger;
+// src/core/entitlement-cache.ts
+init_errors();
+
+// src/core/storage-keys.ts
+var IAP_STORAGE_KEYS = {
+  /** The entitlement cache envelope. See `EntitlementCache`. */
+  entitlements: "entitlements",
+  /** Purchases awaiting backend confirmation. See `UnfinishedTransactionsStore`. */
+  unfinishedTransactions: "unfinished_transactions",
+  /** Products reported as awaiting clearance. See `PendingPurchasesStore`. */
+  pendingPurchases: "pending_purchases"
+};
+var ALL_IAP_STORAGE_KEYS = Object.freeze(
+  Object.values(IAP_STORAGE_KEYS)
+);
+
+// src/core/entitlement-cache.ts
+var ENTITLEMENTS_KEY = IAP_STORAGE_KEYS.entitlements;
+var EntitlementCache = class {
+  constructor(storage, logger) {
+    this.storage = storage;
+    this.logger = logger;
   }
   storage;
   logger;
@@ -1335,12 +2194,7 @@ var EntitlementCache = class {
     try {
       await this.storage.set(ENTITLEMENTS_KEY, JSON.stringify(envelope));
     } catch (cause) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.STORAGE_ERROR,
-        message: "Failed to persist entitlement cache.",
-        cause,
-        recoverable: true
-      });
+      throw toIAPError(cause, "Failed to persist entitlement cache.", exports.IAPErrorCode.STORAGE_ERROR);
     }
     return cachedAt;
   }
@@ -1355,6 +2209,9 @@ var EntitlementCache = class {
     }
   }
 };
+function activeEntitlements(entitlements, now, graceMs = 0) {
+  return entitlements.filter((entitlement) => !isExpired(entitlement.expiresAt, now, graceMs));
+}
 function entitlementsEqual(a, b) {
   if (a === b) return true;
   if (a.length !== b.length) return false;
@@ -1369,18 +2226,195 @@ function entitlementsEqual(a, b) {
   return true;
 }
 
+// src/core/iap-state.ts
+init_errors();
+function freezeAll(items) {
+  return items.map((item) => Object.freeze({ ...item }));
+}
+function ensureUniqueProductIds(products) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const product of products) {
+    if (seen.has(product.id)) {
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.INVALID_CONFIG,
+        message: `Duplicate product id "${product.id}" in product manifest.`
+      });
+    }
+    seen.add(product.id);
+  }
+}
+function requireInitialized(state) {
+  if (!state.initialized) {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.NOT_INITIALIZED,
+      message: "Call iap.initialize() before this method."
+    });
+  }
+}
+
+// src/adapters/native/index.ts
+init_platform();
+
+// src/adapters/native/web/web-stub.ts
+init_errors();
+var WebStubAdapter = class {
+  async isAvailable() {
+    return false;
+  }
+  async getProducts(_requests) {
+    return [];
+  }
+  async purchaseProduct(_opts) {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.PLATFORM_NOT_SUPPORTED,
+      message: "In-app purchases are not supported on the web platform."
+    });
+  }
+  async getOwnedTransactions() {
+    return [];
+  }
+  async acknowledge(_transaction) {
+  }
+  async manageSubscriptions() {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.PLATFORM_NOT_SUPPORTED,
+      message: "Subscription management is not supported on the web platform."
+    });
+  }
+  async getStorefront() {
+    return null;
+  }
+};
+
+// src/adapters/native/index.ts
+async function selectNativeAdapter(logger, packageName, getConfiguredProducts) {
+  const platform = getPlatform();
+  if (platform === "ios" || platform === "android") {
+    const mod = await Promise.resolve().then(() => (init_native_adapter(), native_adapter_exports));
+    return new mod.CapgoNativeAdapter(logger, packageName, getConfiguredProducts);
+  }
+  return new WebStubAdapter();
+}
+
+// src/core/initialize.ts
+init_errors();
+init_platform();
+
+// src/core/app-resume-listener.ts
+async function attachAppResumeListener(opts) {
+  let mod;
+  try {
+    mod = await import('@capacitor/app');
+  } catch (error) {
+    opts.logger.warn(
+      "refreshOnResume requested but @capacitor/app is not installed; resume listener disabled.",
+      error
+    );
+    return null;
+  }
+  let handle;
+  try {
+    handle = await mod.App.addListener("appStateChange", ({ isActive }) => {
+      if (!isActive) return;
+      void Promise.resolve(opts.onResume()).catch((error) => {
+        opts.logger.warn("refreshOnResume handler threw.", error);
+      });
+    });
+  } catch (error) {
+    opts.logger.warn(
+      "Failed to attach App appStateChange listener; resume refresh disabled.",
+      error
+    );
+    return null;
+  }
+  return {
+    async remove() {
+      try {
+        await handle.remove();
+      } catch (error) {
+        opts.logger.warn("Failed to remove App appStateChange listener.", error);
+      }
+    }
+  };
+}
+
+// src/core/attach-transaction-watch.ts
+async function attachTransactionWatch(opts) {
+  const { adapter, updates, logger } = opts;
+  let handle;
+  try {
+    handle = await adapter.watchTransactions?.((transaction) => {
+      void updates.handle(transaction);
+    }) ?? null;
+  } catch (error) {
+    logger.warn(
+      "Failed to subscribe to native transaction updates; renewals and refunds will be picked up at the next launch or resume instead.",
+      error
+    );
+    return null;
+  }
+  if (handle === null) {
+    logger.debug(
+      "No native transaction feed on this platform; relying on recovery at launch and refresh on resume."
+    );
+  }
+  return handle;
+}
+
 // src/core/purchase-flow.ts
 init_errors();
 
-// src/lib/uuid.ts
-var UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-function isValidUuidV4(value) {
-  return UUID_V4_REGEX.test(value);
+// src/core/finalize-transaction.ts
+async function finalizeTransaction(opts) {
+  const { nativeAdapter, transaction, logger } = opts;
+  if (transaction.platform !== "google" || transaction.productType !== "consumable") {
+    await nativeAdapter.acknowledge(transaction);
+    return;
+  }
+  if (!nativeAdapter.consume) {
+    logger.warn(
+      `The native adapter cannot consume, so "${transaction.productId}" was only acknowledged. Google will keep reporting it owned, and buying it again will fail with ALREADY_PURCHASED.`
+    );
+    await nativeAdapter.acknowledge(transaction);
+    return;
+  }
+  try {
+    await nativeAdapter.consume(transaction);
+  } catch (error) {
+    try {
+      await nativeAdapter.acknowledge(transaction);
+      logger.debug(
+        `Consuming "${transaction.productId}" failed; acknowledged it instead so Google does not auto-refund, and the consume will be retried.`
+      );
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/core/resolve-pending.ts
+async function resolvePendingPurchase(deps, productId, status) {
+  if (!await deps.pending.takeIfPresent(productId)) return;
+  deps.emitter.emit("purchase-pending-resolved", { productId, status });
+}
+
+// src/core/store-purchase.ts
+function toStorePurchase(tx) {
+  return {
+    platform: tx.platform,
+    productId: tx.productId,
+    purchaseReference: tx.purchaseReference,
+    appUserId: tx.appUserId ?? null,
+    subscription: tx.subscription ?? null
+  };
 }
 
 // src/core/verify-helpers.ts
 init_errors();
 async function verifyNativeTransaction(backend, tx) {
+  if (typeof backend.verifyNative === "function") {
+    return backend.verifyNative(tx);
+  }
   if (tx.platform === "apple") {
     return backend.verifyApple({
       productId: tx.productId,
@@ -1391,7 +2425,7 @@ async function verifyNativeTransaction(backend, tx) {
   if (!tx.packageName) {
     throw new exports.IAPError({
       code: exports.IAPErrorCode.STORE_ERROR,
-      message: `Google transaction for "${tx.productId}" has no packageName; cannot verify.`
+      message: `Google transaction for "${tx.productId}" has no packageName; cannot verify. Set config.android.packageName to your app's applicationId \u2014 the native plugin does not report it, so iap cannot derive it from the purchase.`
     });
   }
   return backend.verifyGoogle({
@@ -1409,6 +2443,35 @@ var PurchaseOrchestrator = class {
   }
   deps;
   inFlight = /* @__PURE__ */ new Set();
+  /**
+   * Whether this orchestrator is currently handling `productId`.
+   *
+   * Read by the transaction-update orchestrator: StoreKit delivers the
+   * transaction a purchase produced to `Transaction.updates` as well, and
+   * whichever path started it owns settling it.
+   */
+  isInFlight(productId) {
+    return this.inFlight.has(productId);
+  }
+  /**
+   * The products currently being purchased.
+   *
+   * Read by `reset()`, which refuses to run while one is in flight. The
+   * reason is the unfinished-transaction entry, not the cache: that entry is
+   * written *before* verification precisely so a purchase survives a crash,
+   * and deleting it mid-flight leaves a purchase that is neither
+   * acknowledged nor tracked — which Play auto-refunds in three days. The
+   * cache coming back is harmless by comparison, since `reset()` is not a
+   * revocation.
+   *
+   * Marked from the moment the purchase is committed to running, before any
+   * consumer-supplied `appUserId` fetcher is awaited — that await is a
+   * network round-trip, and a window in which this said "nothing in flight"
+   * while a purchase was already under way.
+   */
+  inFlightProducts() {
+    return [...this.inFlight];
+  }
   async purchase(opts) {
     const { productId, appUserId } = opts;
     if (this.inFlight.has(productId)) {
@@ -1424,14 +2487,14 @@ var PurchaseOrchestrator = class {
         message: `Product "${productId}" is not in the configured catalog.`
       });
     }
-    let resolvedAppUserId;
-    if (appUserId !== void 0) {
-      const ctx = typeof appUserId === "function" ? { authHeaders: await this.deps.getAuthHeaders() } : { authHeaders: {} };
-      resolvedAppUserId = await resolveAppUserId(appUserId, ctx);
-    }
     this.inFlight.add(productId);
-    this.deps.emitter.emit("purchase-started", { productId });
     try {
+      let resolvedAppUserId;
+      if (appUserId !== void 0) {
+        const ctx = typeof appUserId === "function" ? { authHeaders: await this.deps.getAuthHeaders() } : { authHeaders: {} };
+        resolvedAppUserId = await resolveAppUserId2(appUserId, ctx);
+      }
+      this.deps.emitter.emit("purchase-started", { productId });
       return await this.runFlow(product, resolvedAppUserId);
     } finally {
       this.inFlight.delete(productId);
@@ -1473,10 +2536,15 @@ var PurchaseOrchestrator = class {
     const { nativeAdapter, cache, unfinished, emitter, logger } = this.deps;
     const transaction = response.transaction;
     const entitlements = response.entitlements;
+    let acknowledged = true;
     try {
-      await nativeAdapter.acknowledge(nativeTx);
+      await finalizeTransaction({ nativeAdapter, transaction: nativeTx, logger });
     } catch (error) {
-      logger.warn(`acknowledge() failed for "${productId}"; entitlements still updated.`, error);
+      acknowledged = false;
+      logger.warn(
+        `Settling "${nativeTx.productId}" with the store failed; the entitlement is granted, and the transaction is retained for recovery to retry on the next launch.`,
+        error
+      );
     }
     const previous = this.deps.getCurrentEntitlements();
     try {
@@ -1489,14 +2557,17 @@ var PurchaseOrchestrator = class {
       );
     }
     this.deps.setEntitlements(entitlements);
-    try {
-      await unfinished.remove(nativeTx.token);
-    } catch (error) {
-      logger.warn(
-        `Failed to remove "${productId}" from unfinished list; will be skipped on next recovery.`,
-        error
-      );
+    if (acknowledged) {
+      try {
+        await unfinished.remove(nativeTx.token);
+      } catch (error) {
+        logger.warn(
+          `Failed to remove "${productId}" from unfinished list; will be skipped on next recovery.`,
+          error
+        );
+      }
     }
+    await resolvePendingPurchase(this.deps, productId, "purchased");
     emitter.emit("purchase-success", { productId, transaction });
     emitter.emit("entitlements-changed", {
       entitlements: this.deps.getCurrentEntitlements(),
@@ -1506,6 +2577,7 @@ var PurchaseOrchestrator = class {
       status: "success",
       productId,
       transaction,
+      purchase: toStorePurchase(nativeTx),
       entitlements: this.deps.getCurrentEntitlements()
     };
   }
@@ -1518,7 +2590,7 @@ var PurchaseOrchestrator = class {
     this.deps.emitter.emit("verification-failed", { productId, error });
     return { status: "verification_failed", productId, error };
   }
-  handleNativeError(productId, error) {
+  async handleNativeError(productId, error) {
     const iapError = toIAPError(
       error,
       `Native purchase of "${productId}" failed.`,
@@ -1529,6 +2601,7 @@ var PurchaseOrchestrator = class {
       return { status: "cancelled", productId };
     }
     if (iapError.code === exports.IAPErrorCode.PURCHASE_PENDING) {
+      await this.deps.pending.add(productId);
       this.deps.emitter.emit("purchase-pending", { productId });
       return { status: "pending", productId };
     }
@@ -1545,7 +2618,7 @@ var PurchaseOrchestrator = class {
     return { status: "verification_failed", productId, error: iapError };
   }
 };
-async function resolveAppUserId(supply, ctx) {
+async function resolveAppUserId2(supply, ctx) {
   let resolved;
   if (typeof supply === "function") {
     try {
@@ -1560,10 +2633,10 @@ async function resolveAppUserId(supply, ctx) {
   } else {
     resolved = supply;
   }
-  if (typeof resolved !== "string" || !isValidUuidV4(resolved)) {
+  if (!isValidUuid(resolved)) {
     throw new exports.IAPError({
       code: exports.IAPErrorCode.INVALID_APP_USER_ID,
-      message: `appUserId must be a UUID v4; received ${typeof resolved === "string" ? `"${resolved}"` : typeof resolved}.`
+      message: `appUserId must be an RFC 9562 UUID (any version); received ${typeof resolved === "string" ? `"${resolved}"` : typeof resolved}.`
     });
   }
   return resolved;
@@ -1620,67 +2693,148 @@ var RecoveryOrchestrator = class {
     );
     return { recovered, failures, droppedPermanent, inspected: entries.length };
   }
+  /**
+   * Verify, acknowledge and settle one transaction that arrived outside a
+   * `purchase()` call — a renewal, a refund, an Ask-to-Buy approval, a
+   * pending Play purchase that cleared.
+   *
+   * Routed through the same path recovery uses, deliberately: persisted
+   * before verification so app death cannot lose it, and left in the store
+   * to retry if anything fails. A second settlement path would be a second
+   * place for those to drift.
+   *
+   * **One invariant does not carry over, and it is worth being exact about.**
+   * On the iOS update feed the native plugin calls `transaction.finish()`
+   * *before* it notifies listeners, so by the time iap sees the transaction
+   * the platform has already finished it. "Acknowledged only after the
+   * backend confirms" therefore describes the purchase flow, not this path —
+   * iap has no say in the ordering here. The consequence is that persisting
+   * first matters *more*, not less: StoreKit will not redeliver a finished
+   * transaction, so the `unfinished` entry is the only remaining handle on
+   * it. Callers on that path pass `alreadyFinished`.
+   */
+  /**
+   * Whether an Android consumable's purchase has left the store's owned set,
+   * which makes a failed consume terminal rather than retryable.
+   *
+   * The sequence this exists for: the consume succeeds on Play, then the
+   * bridge reply or the `unfinished.remove` that follows fails. Play has
+   * already dropped the purchase — Billing 8.x stops returning consumed
+   * purchases from `getPurchases()` — so every later consume of that token
+   * rejects, the entry is retained, and recovery retries it at every launch
+   * forever, burning a `recoveryMaxBatch` slot and a verify each time. The
+   * unfinished store has no age-based eviction to catch that.
+   *
+   * Acknowledging had no such trap: the purchase stayed owned, so a retry
+   * eventually worked. So this asks the store a positive question — is the
+   * purchase still there — rather than trying to read a meaning out of the
+   * error, which would mean matching on Play's message text.
+   *
+   * Only for Google consumables, only on the failure path, and `false` on
+   * any doubt: a store that cannot answer must not be taken to have said
+   * "gone", or a genuinely retryable failure would be dropped.
+   */
+  async alreadyGone(tx) {
+    if (tx.platform !== "google" || tx.productType !== "consumable") return false;
+    try {
+      const owned = await this.deps.nativeAdapter.getOwnedTransactions();
+      return !owned.some((candidate) => candidate.token === tx.token);
+    } catch (error) {
+      this.deps.logger.debug(
+        `Recovery: could not re-read the owned set for productId=${tx.productId}; treating the settle failure as retryable.`,
+        error
+      );
+      return false;
+    }
+  }
+  async settleTransaction(tx, opts = {}) {
+    if (opts.persist !== false) {
+      try {
+        await this.deps.unfinished.add(tx);
+      } catch (error) {
+        this.deps.logger.warn(
+          `Transaction update: failed to persist unfinished entry for "${tx.productId}"; verifying anyway.`,
+          error
+        );
+      }
+    }
+    const result = await this.processTransaction(tx, opts);
+    if (result.kind === "recovered") {
+      await this.applyEntitlements(result.entitlements);
+      return "settled";
+    }
+    return result.kind === "dropped-permanent" ? "dropped-permanent" : "failed";
+  }
   async processEntry(entry) {
+    return this.processTransaction(entryToNativeTransaction(entry));
+  }
+  async processTransaction(tx, opts = {}) {
     const { nativeAdapter, unfinished, logger, emitter, permanentErrorCodes } = this.deps;
-    const tx = entryToNativeTransaction(entry);
-    const tokenLabel = maskToken(entry.token);
+    const tokenLabel = maskToken(tx.token);
     try {
       const response = await verifyNativeTransaction(this.deps.backend, tx);
       if (!response.valid) {
         if (permanentErrorCodes.has(response.error)) {
           logger.info(
-            `Recovery: dropping permanently-invalid token=${tokenLabel} productId=${entry.productId} (${response.error}).`
+            `Recovery: dropping permanently-invalid token=${tokenLabel} productId=${tx.productId} (${response.error}).`
           );
           try {
             await nativeAdapter.acknowledge(tx);
           } catch (error) {
             logger.warn(
-              `Recovery: best-effort acknowledge() failed for productId=${entry.productId}; proceeding with removal anyway.`,
+              `Recovery: best-effort acknowledge() failed for productId=${tx.productId}; proceeding with removal anyway.`,
               error
             );
           }
           try {
-            await unfinished.remove(entry.token);
+            await unfinished.remove(tx.token);
           } catch (error) {
             logger.warn(
-              `Recovery: unfinished.remove() failed for productId=${entry.productId} after permanent classification; will dedupe on next launch.`,
+              `Recovery: unfinished.remove() failed for productId=${tx.productId} after permanent classification; will dedupe on next launch.`,
               error
             );
           }
           emitter.emit("recovery-dropped-permanent", {
-            productId: entry.productId,
-            token: entry.token,
+            productId: tx.productId,
+            token: tx.token,
             error: response.error,
             ...response.message !== void 0 ? { message: response.message } : {}
           });
           return { kind: "dropped-permanent" };
         }
         logger.debug(
-          `Recovery: backend rejected token=${tokenLabel} productId=${entry.productId} (${response.error}); leaving in list for retry.`
+          `Recovery: backend rejected token=${tokenLabel} productId=${tx.productId} (${response.error}); leaving in list for retry.`
         );
         return { kind: "failed" };
       }
       try {
-        await nativeAdapter.acknowledge(tx);
+        await finalizeTransaction({ nativeAdapter, transaction: tx, logger });
       } catch (error) {
-        logger.warn(
-          `Recovery: acknowledge() failed for productId=${entry.productId}; entry retained for next launch.`,
-          error
-        );
-        return { kind: "failed" };
+        if (opts.alreadyFinished || await this.alreadyGone(tx)) {
+          logger.debug(
+            `Recovery: settling productId=${tx.productId} failed, but the store no longer has the purchase; treating as settled.`
+          );
+        } else {
+          logger.warn(
+            `Recovery: settling productId=${tx.productId} with the store failed; entry retained for next launch.`,
+            error
+          );
+          return { kind: "failed" };
+        }
       }
       try {
-        await unfinished.remove(entry.token);
+        await unfinished.remove(tx.token);
       } catch (error) {
         logger.warn(
-          `Recovery: unfinished.remove() failed for productId=${entry.productId}; will dedupe on next launch.`,
+          `Recovery: unfinished.remove() failed for productId=${tx.productId}; will dedupe on next launch.`,
           error
         );
       }
+      await resolvePendingPurchase(this.deps, tx.productId, "purchased");
       return { kind: "recovered", entitlements: response.entitlements };
     } catch (error) {
       logger.warn(
-        `Recovery: verify failed for productId=${entry.productId}; will retry next launch.`,
+        `Recovery: verify failed for productId=${tx.productId}; will retry next launch.`,
         error
       );
       return { kind: "failed" };
@@ -1703,127 +2857,656 @@ var RecoveryOrchestrator = class {
       previous
     });
   }
-};
-function entryToNativeTransaction(entry) {
-  const tx = {
-    platform: entry.platform,
-    productId: entry.productId,
-    token: entry.token,
-    productType: entry.productType
+};
+function entryToNativeTransaction(entry) {
+  const tx = {
+    platform: entry.platform,
+    productId: entry.productId,
+    token: entry.token,
+    // Entries persisted before `purchaseReference` existed carry only the
+    // token; on Android the two are the same value anyway, and on iOS the
+    // token is the right fallback (see `NativeTransaction`).
+    // `||`, not `??`: a stored empty string is as unusable as an absent one.
+    purchaseReference: entry.purchaseReference || entry.token,
+    productType: entry.productType
+  };
+  if (entry.appUserId) tx.appUserId = entry.appUserId;
+  if (entry.expiresAt) {
+    tx.subscription = {
+      state: null,
+      autoRenewing: null,
+      renewsAt: null,
+      renewalProductId: null,
+      expiresAt: entry.expiresAt
+    };
+  }
+  if (entry.purchaseState) {
+    tx.raw = { purchaseState: entry.purchaseState };
+  }
+  if (entry.packageName) tx.packageName = entry.packageName;
+  return tx;
+}
+
+// src/core/restore-flow.ts
+init_errors();
+var RestoreOrchestrator = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  async restorePurchases() {
+    const { nativeAdapter, backend, cache, unfinished, emitter, logger } = this.deps;
+    emitter.emit("restore-started", void 0);
+    let owned;
+    try {
+      owned = await nativeAdapter.getOwnedTransactions();
+    } catch (cause) {
+      throw toIAPError(cause, "Failed to fetch owned transactions.", exports.IAPErrorCode.STORE_ERROR);
+    }
+    if (owned.length === 0) {
+      const entitlements2 = this.deps.getCurrentEntitlements();
+      emitter.emit("restore-completed", { restored: 0, entitlements: entitlements2 });
+      return { restored: 0, entitlements: entitlements2, purchases: [] };
+    }
+    let response;
+    try {
+      response = backend.restoreNative ? await backend.restoreNative(owned) : await backend.restore({ transactions: owned.map((tx) => this.toRestoreEntry(tx)) });
+    } catch (cause) {
+      throw toIAPError(cause, "Backend restore call failed.", exports.IAPErrorCode.BACKEND_UNAVAILABLE);
+    }
+    if (!response.valid) {
+      const detail = response.message ? `${response.message} [${response.error}]` : `Backend rejected restore (${response.error}).`;
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.VERIFICATION_REJECTED,
+        message: detail
+      });
+    }
+    const ackable = response.verifiedTokens === void 0 ? owned : owned.filter((tx) => response.verifiedTokens?.includes(tx.token));
+    if (ackable.length !== owned.length) {
+      logger.debug(
+        `Restore: settling ${ackable.length} of ${owned.length} owned transaction(s); the rest were not verified.`
+      );
+    }
+    const settled = [];
+    for (const tx of ackable) {
+      try {
+        await finalizeTransaction({ nativeAdapter, transaction: tx, logger });
+        settled.push(tx);
+      } catch (error) {
+        logger.warn(`Settling "${tx.productId}" with the store failed during restore.`, error);
+      }
+    }
+    const entitlements = response.entitlements;
+    const previous = this.deps.getCurrentEntitlements();
+    try {
+      const cachedAt = await cache.save(entitlements);
+      this.deps.setCachePersisted(cachedAt);
+    } catch (error) {
+      logger.warn(
+        "Failed to persist entitlements after restore; in-memory state still updated.",
+        error
+      );
+    }
+    this.deps.setEntitlements(entitlements);
+    for (const tx of settled) {
+      try {
+        await unfinished.remove(tx.token);
+      } catch (error) {
+        logger.warn(
+          `Failed to remove "${tx.productId}" from unfinished list during restore.`,
+          error
+        );
+      }
+    }
+    for (const tx of settled) {
+      try {
+        await resolvePendingPurchase(this.deps, tx.productId, "purchased");
+      } catch (error) {
+        logger.warn(
+          `Failed to clear the pending mark for "${tx.productId}" during restore.`,
+          error
+        );
+      }
+    }
+    const next = this.deps.getCurrentEntitlements();
+    emitter.emit("restore-completed", { restored: owned.length, entitlements: next });
+    if (!entitlementsEqual(previous, next)) {
+      emitter.emit("entitlements-changed", { entitlements: next, previous });
+    }
+    return {
+      restored: owned.length,
+      entitlements: next,
+      purchases: owned.map(toStorePurchase)
+    };
+  }
+  toRestoreEntry(tx) {
+    if (tx.platform === "apple") {
+      return {
+        platform: "apple",
+        productId: tx.productId,
+        transactionId: tx.token
+      };
+    }
+    if (!tx.packageName) {
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.STORE_ERROR,
+        message: `Google owned transaction for "${tx.productId}" has no packageName; cannot restore. Set config.android.packageName to your app's applicationId \u2014 the native plugin does not report it, so iap cannot derive it from the purchase.`
+      });
+    }
+    return {
+      platform: "google",
+      productId: tx.productId,
+      purchaseToken: tx.token,
+      packageName: tx.packageName
+    };
+  }
+};
+
+// src/core/transaction-updates.ts
+var TransactionUpdateOrchestrator = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /**
+   * Tokens currently being settled, so two paths cannot settle the same
+   * transaction at once.
+   *
+   * The listener is fire-and-forget and reconciliation runs on resume, so
+   * they genuinely overlap. Without this, both verify and both acknowledge —
+   * and on Android a second `acknowledge` of an already-acked token errors,
+   * which the settle path reads as a failure and retains the entry for.
+   */
+  settling = /* @__PURE__ */ new Set();
+  /** The in-flight reconciliation pass, so concurrent callers join it. */
+  reconciling = null;
+  /** Settle a transaction pushed by the platform. Never throws. */
+  async handle(transaction) {
+    const { logger, emitter, isPurchaseInFlight } = this.deps;
+    try {
+      if (!this.deps.isActive()) {
+        logger.debug("Transaction update arrived after teardown; ignoring.");
+        return;
+      }
+      if (isPurchaseInFlight(transaction.productId)) {
+        logger.debug(
+          `Transaction update for "${transaction.productId}" arrived while a purchase is in flight; leaving it to the purchase flow.`
+        );
+        return;
+      }
+      emitter.emit("transaction-updated", {
+        productId: transaction.productId,
+        purchase: toStorePurchase(transaction)
+      });
+      const isRevocation = transaction.subscription?.state === "revoked";
+      const outcome = await this.settleOnce(transaction, {
+        persist: !isRevocation,
+        alreadyFinished: transaction.platform === "apple"
+      });
+      if (outcome !== "settled") {
+        logger.debug(
+          `Transaction update for "${transaction.productId}" did not settle (${outcome}).`
+        );
+      }
+    } catch (error) {
+      logger.warn(
+        `Transaction update handling threw for "${transaction.productId}"; ignoring.`,
+        error
+      );
+    }
+  }
+  /**
+   * Ask the store what became of the purchases iap reported as pending.
+   *
+   * Call at `initialize()` and on resume. Does nothing when nothing is
+   * tracked, so the common case costs no native calls. Never throws.
+   */
+  async reconcilePending() {
+    if (this.reconciling) return this.reconciling;
+    this.reconciling = this.runReconcile().finally(() => {
+      this.reconciling = null;
+    });
+    return this.reconciling;
+  }
+  async runReconcile() {
+    const { nativeAdapter, logger, pending } = this.deps;
+    try {
+      if (!this.deps.isActive()) return;
+      const tracked = await pending.list();
+      if (tracked.length === 0) return;
+      const stillPending = await nativeAdapter.getPendingProductIds?.() ?? null;
+      const owned = await nativeAdapter.getOwnedTransactions();
+      const ownedByProduct = new Map(owned.map((tx) => [tx.productId, tx]));
+      for (const productId of tracked) {
+        if (this.deps.isPurchaseInFlight(productId)) {
+          logger.debug(
+            `Pending purchase "${productId}" is being purchased right now; leaving it to the purchase flow.`
+          );
+          continue;
+        }
+        const ownedTx = ownedByProduct.get(productId);
+        if (ownedTx) {
+          const outcome = await this.settleOnce(ownedTx);
+          if (outcome !== "settled") {
+            logger.debug(
+              `Pending purchase "${productId}" is owned but did not settle (${outcome}); keeping it pending.`
+            );
+          }
+          continue;
+        }
+        if (stillPending === null) {
+          logger.debug(
+            `Pending purchase "${productId}" is not owned, but this platform cannot report pending state; keeping it pending.`
+          );
+          continue;
+        }
+        if (stillPending.includes(productId)) continue;
+        await this.resolvePending(productId, "cancelled");
+      }
+    } catch (error) {
+      logger.warn("Reconciling pending purchases failed; markers kept for the next pass.", error);
+    }
+  }
+  /**
+   * Settle a transaction, unless it is already being settled.
+   *
+   * Keyed on the token, not the product: two different transactions for one
+   * product (an iOS subscription has a token per renewal) should both
+   * settle, while the same transaction reaching both paths should not.
+   */
+  async settleOnce(tx, opts = {}) {
+    if (this.settling.has(tx.token)) return "already-settling";
+    this.settling.add(tx.token);
+    try {
+      return await this.deps.recoverer.settleTransaction(tx, opts);
+    } finally {
+      this.settling.delete(tx.token);
+    }
+  }
+  /** Announce how a pending purchase ended. See `resolve-pending.ts`. */
+  async resolvePending(productId, status) {
+    await resolvePendingPurchase(this.deps, productId, status);
+  }
+};
+
+// src/core/initialize.ts
+async function initializeIap(state, refreshEntitlements) {
+  if (state.destroyed) {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.NOT_INITIALIZED,
+      message: "IAP instance has been destroyed; create a new one with createIAP()."
+    });
+  }
+  if (state.initialized) {
+    state.logger.debug("initialize() called more than once; ignoring.");
+    return;
+  }
+  await state.storage.ensureAvailable?.();
+  const platform = getPlatform();
+  if (!isNative()) {
+    state.logger.info("Native purchases unavailable on web; entitlement queries still functional.");
+  } else {
+    state.logger.debug(`Initializing on platform=${platform}`);
+  }
+  if (!state.config.products) {
+    if (typeof state.backend.listProducts !== "function") {
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.INVALID_CONFIG,
+        message: "config.products is omitted but backend adapter does not implement listProducts(). This is a library bug; the schema should have caught it."
+      });
+    }
+    const fetched = await state.backend.listProducts();
+    const validated = configuredProductsArraySchema.safeParse(fetched);
+    if (!validated.success) {
+      throw new exports.IAPError({
+        code: exports.IAPErrorCode.BACKEND_BAD_RESPONSE,
+        message: `backend.listProducts() returned an invalid manifest: ${validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`,
+        cause: validated.error
+      });
+    }
+    ensureUniqueProductIds(validated.data);
+    state.products = Object.freeze([...validated.data]);
+    state.logger.debug(`Resolved ${validated.data.length} product(s) from backend manifest.`);
+  }
+  state.adapter = await selectNativeAdapter(
+    state.logger,
+    state.config.android.packageName,
+    () => state.products
+  );
+  const configGetAuthHeaders = state.config.backend?.getAuthHeaders;
+  const getAuthHeaders = configGetAuthHeaders ? async () => configGetAuthHeaders() : async () => ({});
+  const sharedDeps = {
+    nativeAdapter: state.adapter,
+    backend: state.backend,
+    cache: state.cache,
+    unfinished: state.unfinished,
+    emitter: state.emitter,
+    logger: state.logger,
+    getCurrentEntitlements: () => state.entitlements,
+    setEntitlements: (next) => {
+      state.entitlements = freezeAll(next);
+    },
+    setCachePersisted: (cachedAt) => {
+      state.cachedAt = cachedAt;
+    },
+    getAuthHeaders
+  };
+  state.orchestrator = new PurchaseOrchestrator({
+    ...sharedDeps,
+    products: state.products,
+    pending: state.pending
+  });
+  state.restorer = new RestoreOrchestrator({ ...sharedDeps, pending: state.pending });
+  state.recoverer = new RecoveryOrchestrator({
+    ...sharedDeps,
+    pending: state.pending,
+    maxBatch: state.config.options.recoveryMaxBatch,
+    permanentErrorCodes: new Set(
+      state.config.options.permanentErrorCodes ?? DEFAULT_PERMANENT_ERROR_CODES
+    )
+  });
+  state.updates = new TransactionUpdateOrchestrator({
+    nativeAdapter: state.adapter,
+    recoverer: state.recoverer,
+    pending: state.pending,
+    emitter: state.emitter,
+    logger: state.logger,
+    isPurchaseInFlight: (productId) => state.orchestrator?.isInFlight(productId) ?? false,
+    isActive: () => state.initialized && !state.destroyed
+  });
+  if (platform === "android" && !state.config.android.packageName) {
+    state.logger.warn(
+      "config.android.packageName is not set. Google verification and restore requests cannot be built without it, so purchases will fail with STORE_ERROR. Set it to your app's applicationId."
+    );
+  }
+  try {
+    await state.adapter.isAvailable();
+  } catch (error) {
+    state.logger.warn("Native adapter availability check threw; continuing.", error);
+  }
+  const cached = await state.cache.load();
+  if (cached) {
+    state.entitlements = freezeAll(cached.entitlements);
+    state.cachedAt = cached.cachedAt;
+    state.logger.debug(
+      `Loaded ${cached.entitlements.length} cached entitlement(s) from ${new Date(cached.cachedAt).toISOString()}.`
+    );
+  }
+  if (state.config.options.recoverUnfinishedTransactions && isNative()) {
+    try {
+      const result = await state.recoverer.recoverUnfinishedTransactions();
+      if (result.inspected > 0) {
+        state.logger.info(
+          `Recovery inspected ${result.inspected} unfinished transaction(s): ${result.recovered} recovered, ${result.failures} retained.`
+        );
+      }
+    } catch (error) {
+      state.logger.warn("Recovery threw unexpectedly; continuing initialize.", error);
+    }
+  }
+  if (isNative()) {
+    state.txWatch = await attachTransactionWatch({
+      adapter: state.adapter,
+      updates: state.updates,
+      logger: state.logger
+    });
+  }
+  if (state.config.options.refreshOnResume && isNative()) {
+    state.resumeListener = await attachAppResumeListener({
+      logger: state.logger,
+      onResume: async () => {
+        try {
+          await refreshEntitlements();
+        } catch (error) {
+          state.logger.warn("refreshOnResume: refresh() failed.", error);
+        }
+        await state.updates?.reconcilePending();
+      }
+    });
+  }
+  if (state.cachedAt !== null && Date.now() - state.cachedAt > state.config.options.entitlementCacheTtlMs) {
+    state.logger.debug("Cache exceeds TTL; scheduling background refresh.");
+    queueMicrotask(() => {
+      if (!state.initialized || state.destroyed) return;
+      refreshEntitlements().catch((error) => {
+        state.logger.warn("TTL background refresh failed.", error);
+      });
+    });
+  }
+  state.initialized = true;
+  state.emitter.emit("ready", void 0);
+  if (isNative()) {
+    queueMicrotask(() => {
+      if (!state.initialized || state.destroyed) return;
+      void state.updates?.reconcilePending();
+    });
+  }
+}
+
+// src/core/mutation-lock.ts
+function createMutationLock() {
+  let tail = Promise.resolve();
+  return async function runExclusive(fn) {
+    const previous = tail;
+    let release;
+    tail = new Promise((resolve) => {
+      release = resolve;
+    });
+    try {
+      await previous;
+      return await fn();
+    } finally {
+      release();
+    }
   };
-  if (entry.packageName) tx.packageName = entry.packageName;
-  return tx;
 }
 
-// src/core/restore-flow.ts
-init_errors();
-var RestoreOrchestrator = class {
-  constructor(deps) {
-    this.deps = deps;
+// src/core/pending-purchases.ts
+var STORE_KEY = IAP_STORAGE_KEYS.pendingPurchases;
+var pendingEntrySchema = zod.z.union([
+  zod.z.object({ productId: zod.z.string().min(1), recordedAt: zod.z.string().min(1) }),
+  zod.z.string().min(1).transform((productId) => ({ productId, recordedAt: "" }))
+]);
+var pendingListSchema = zod.z.array(pendingEntrySchema);
+var MAX_PENDING_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+var PendingPurchasesStore = class {
+  constructor(storage, logger) {
+    this.storage = storage;
+    this.logger = logger;
   }
-  deps;
-  async restorePurchases() {
-    const { nativeAdapter, backend, cache, unfinished, emitter, logger } = this.deps;
-    emitter.emit("restore-started", void 0);
-    let owned;
+  storage;
+  logger;
+  runExclusive = createMutationLock();
+  /** Product ids currently marked pending, or `[]` if empty / corrupt. */
+  async list() {
+    return (await this.readLive()).map((entry) => entry.productId);
+  }
+  /** Live entries, with anything past {@link MAX_PENDING_AGE_MS} dropped. */
+  async readLive() {
+    let raw;
     try {
-      owned = await nativeAdapter.getOwnedTransactions();
+      raw = await this.storage.get(STORE_KEY);
     } catch (cause) {
-      throw toIAPError(cause, "Failed to fetch owned transactions.", exports.IAPErrorCode.STORE_ERROR);
-    }
-    if (owned.length === 0) {
-      const entitlements2 = this.deps.getCurrentEntitlements();
-      emitter.emit("restore-completed", { restored: 0, entitlements: entitlements2 });
-      return { restored: 0, entitlements: entitlements2 };
+      this.logger.warn("Storage read failed; treating pending list as empty.", cause);
+      return [];
     }
-    const request = {
-      transactions: owned.map((tx) => this.toRestoreEntry(tx))
-    };
-    let response;
+    if (!raw) return [];
+    let parsed;
     try {
-      response = await backend.restore(request);
+      parsed = JSON.parse(raw);
     } catch (cause) {
-      throw toIAPError(cause, "Backend restore call failed.", exports.IAPErrorCode.BACKEND_UNAVAILABLE);
-    }
-    if (!response.valid) {
-      const detail = response.message ? `${response.message} [${response.error}]` : `Backend rejected restore (${response.error}).`;
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.VERIFICATION_REJECTED,
-        message: detail
-      });
+      this.logger.warn("pending_purchases payload is not valid JSON; clearing.", cause);
+      await this.safeRemove();
+      return [];
     }
-    for (const tx of owned) {
-      try {
-        await nativeAdapter.acknowledge(tx);
-      } catch (error) {
-        logger.warn(`acknowledge() failed for "${tx.productId}" during restore.`, error);
-      }
+    const result = pendingListSchema.safeParse(parsed);
+    if (!result.success) {
+      this.logger.warn("pending_purchases has unexpected shape; clearing.", result.error);
+      await this.safeRemove();
+      return [];
     }
-    const entitlements = response.entitlements;
-    const previous = this.deps.getCurrentEntitlements();
-    try {
-      const cachedAt = await cache.save(entitlements);
-      this.deps.setCachePersisted(cachedAt);
-    } catch (error) {
-      logger.warn(
-        "Failed to persist entitlements after restore; in-memory state still updated.",
-        error
+    const now = Date.now();
+    const live = result.data.filter((entry) => {
+      if (entry.recordedAt === "") return true;
+      const marked = Date.parse(entry.recordedAt);
+      if (Number.isNaN(marked)) return false;
+      return now - marked < MAX_PENDING_AGE_MS;
+    });
+    if (live.length !== result.data.length) {
+      this.logger.debug(
+        `Dropping ${result.data.length - live.length} pending mark(s) past the age limit.`
       );
+      await this.persist(live);
     }
-    this.deps.setEntitlements(entitlements);
-    for (const tx of owned) {
-      try {
-        await unfinished.remove(tx.token);
-      } catch (error) {
-        logger.warn(
-          `Failed to remove "${tx.productId}" from unfinished list during restore.`,
-          error
-        );
-      }
-    }
-    const next = this.deps.getCurrentEntitlements();
-    emitter.emit("restore-completed", { restored: owned.length, entitlements: next });
-    if (!entitlementsEqual(previous, next)) {
-      emitter.emit("entitlements-changed", { entitlements: next, previous });
-    }
-    return { restored: owned.length, entitlements: next };
+    return live;
   }
-  toRestoreEntry(tx) {
-    if (tx.platform === "apple") {
-      return {
-        platform: "apple",
-        productId: tx.productId,
-        transactionId: tx.token
-      };
+  async has(productId) {
+    return (await this.list()).includes(productId);
+  }
+  /**
+   * Remove a product's pending mark and report whether it was there.
+   *
+   * The atomic form of `has()` then `remove()`, and the reason it exists:
+   * `purchase-pending-resolved` promises to fire at most once per pending
+   * purchase, and the two callers that resolve one can run concurrently —
+   * the iOS transaction listener is fire-and-forget, so it can interleave
+   * with the reconciliation that runs on resume. Checked and removed
+   * separately, both would observe the mark and both would emit.
+   */
+  async takeIfPresent(productId) {
+    return this.runExclusive(async () => {
+      const current = await this.readLive();
+      if (!current.some((entry) => entry.productId === productId)) return false;
+      await this.persist(current.filter((entry) => entry.productId !== productId));
+      return true;
+    });
+  }
+  /** Mark a product pending. Idempotent — re-marking does not reset the age. */
+  async add(productId) {
+    return this.runExclusive(async () => {
+      const current = await this.readLive();
+      if (current.some((entry) => entry.productId === productId)) return;
+      await this.persist([...current, { productId, recordedAt: (/* @__PURE__ */ new Date()).toISOString() }]);
+    });
+  }
+  /** Clear a product's pending mark. No-op if absent. */
+  async remove(productId) {
+    return this.runExclusive(async () => {
+      const current = await this.readLive();
+      const next = current.filter((entry) => entry.productId !== productId);
+      if (next.length === current.length) return;
+      await this.persist(next);
+    });
+  }
+  /** Drop every pending mark. Used by `iap.reset()`. */
+  async clear() {
+    return this.runExclusive(() => this.safeRemove());
+  }
+  async persist(entries) {
+    try {
+      await this.storage.set(STORE_KEY, JSON.stringify(entries));
+    } catch (cause) {
+      this.logger.warn("Failed to persist pending_purchases; pending state may be lost.", cause);
     }
-    if (!tx.packageName) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.STORE_ERROR,
-        message: `Google owned transaction for "${tx.productId}" has no packageName; cannot restore.`
-      });
+  }
+  async safeRemove() {
+    try {
+      await this.storage.remove(STORE_KEY);
+    } catch (cause) {
+      this.logger.warn("Failed to clear pending_purchases key.", cause);
     }
-    return {
-      platform: "google",
-      productId: tx.productId,
-      purchaseToken: tx.token,
-      packageName: tx.packageName
-    };
   }
 };
 
+// src/core/reset.ts
+init_errors();
+async function resetIap(state) {
+  const inFlight = state.orchestrator?.inFlightProducts() ?? [];
+  if (inFlight.length > 0) {
+    throw new exports.IAPError({
+      code: exports.IAPErrorCode.ALREADY_IN_PROGRESS,
+      message: `Cannot reset while a purchase of ${inFlight.map((id) => `"${id}"`).join(", ")} is in progress: its unfinished-transaction record is still needed. Await the purchase, then reset.`,
+      // The per-code hint is written for the other caller of this code — a
+      // double `purchase()` of one product — and would tell a consumer
+      // debugging a failed reset that they double-called `purchase()`.
+      includeHint: false,
+      // It is recoverable, whatever the code's default says: await the
+      // purchase and try again.
+      recoverable: true
+    });
+  }
+  await state.storage.ensureAvailable?.();
+  const previous = state.entitlements;
+  state.entitlements = [];
+  state.cachedAt = null;
+  await state.cache.clear();
+  await state.unfinished.clear();
+  await state.pending.clear();
+  for (const key of ALL_IAP_STORAGE_KEYS) {
+    try {
+      await state.storage.remove(key);
+    } catch (error) {
+      state.logger.warn(`reset(): failed to remove the "${key}" key.`, error);
+    }
+  }
+  try {
+    await state.storage.clear();
+  } catch (error) {
+    state.logger.warn("reset(): failed to clear the storage namespace.", error);
+  }
+  if (previous.length > 0) {
+    state.emitter.emit("entitlements-changed", {
+      entitlements: [...state.entitlements],
+      previous
+    });
+  }
+}
+function activeNow(state) {
+  if (!state.config.verification) return [...state.entitlements];
+  return activeEntitlements(
+    state.entitlements,
+    Date.now(),
+    state.config.options.entitlementGraceMs
+  );
+}
+
 // src/core/unfinished-transactions.ts
 init_errors();
-var STORE_KEY = "unfinished_transactions";
+var STORE_KEY2 = IAP_STORAGE_KEYS.unfinishedTransactions;
 var unfinishedEntrySchema = zod.z.object({
   platform: zod.z.enum(["apple", "google"]),
   productId: zod.z.string().min(1),
   token: zod.z.string().min(1),
   productType: productTypeSchema,
   packageName: zod.z.string().optional(),
+  /**
+   * The renewal-stable purchase reference. Optional, and deliberately
+   * unconstrained beyond its type: entries written before it existed are
+   * still valid, and readers fall back to `token`. A `min(1)` here would
+   * make an empty string fail the whole entry's parse — rejecting a
+   * recoverable purchase over a field recovery does not even read.
+   */
+  purchaseReference: zod.z.string().optional(),
+  /**
+   * The fields a verification needs that the extracted request shapes do
+   * not carry. All optional, so entries written before they existed still
+   * parse.
+   *
+   * These exist because recovery re-verifies from the **stored entry**, not
+   * from a live transaction. Without them a rebuilt transaction has no
+   * binding, no expiry and no purchase state — so an on-device check sees
+   * an amputated object and answers differently than it did at purchase
+   * time: an expired subscription verifies as non-expiring and is granted,
+   * and a purchase with a binding fails `BINDING_MISMATCH` forever and is
+   * never acknowledged (which on Android means Google refunds it).
+   */
+  appUserId: zod.z.string().optional(),
+  expiresAt: zod.z.string().optional(),
+  purchaseState: zod.z.string().optional(),
   /** ISO 8601 timestamp the entry was first persisted. */
   recordedAt: zod.z.string()
 });
-var envelopeSchema = zod.z.array(unfinishedEntrySchema);
+var entryListSchema = zod.z.array(zod.z.unknown());
 var UnfinishedTransactionsStore = class {
   constructor(storage, logger) {
     this.storage = storage;
@@ -1838,12 +3521,12 @@ var UnfinishedTransactionsStore = class {
    * could each `list()` the same snapshot and overwrite each other's
    * `persist()`.
    */
-  mutationLock = Promise.resolve();
+  runExclusive = createMutationLock();
   /** Returns the current list, or `[]` if empty / corrupt. */
   async list() {
     let raw;
     try {
-      raw = await this.storage.get(STORE_KEY);
+      raw = await this.storage.get(STORE_KEY2);
     } catch (cause) {
       this.logger.warn("Storage read failed; treating unfinished list as empty.", cause);
       return [];
@@ -1857,18 +3540,39 @@ var UnfinishedTransactionsStore = class {
       await this.safeClear();
       return [];
     }
-    const result = envelopeSchema.safeParse(parsed);
-    if (!result.success) {
-      this.logger.warn("unfinished_transactions has unexpected shape; clearing.", result.error);
+    const list = entryListSchema.safeParse(parsed);
+    if (!list.success) {
+      this.logger.warn("unfinished_transactions is not a list; clearing.", list.error);
       await this.safeClear();
       return [];
     }
-    return result.data;
+    const entries = [];
+    let dropped = 0;
+    for (const candidate of list.data) {
+      const entry = unfinishedEntrySchema.safeParse(candidate);
+      if (entry.success) {
+        entries.push(entry.data);
+      } else {
+        dropped++;
+      }
+    }
+    if (dropped > 0) {
+      this.logger.warn(
+        `Dropped ${dropped} unreadable unfinished-transaction entry/entries; kept ${entries.length}.`
+      );
+    }
+    return entries;
   }
   /**
    * Append a transaction to the list. Idempotent: if a same-token entry
    * already exists, this is a no-op (avoids dupes when restore + active
    * purchase race for the same StoreKit replay).
+   *
+   * **Keyed on `token`, deliberately — not on `purchaseReference`.** The
+   * token is what acknowledges one transaction, and on iOS a subscription
+   * has a separate token per renewal while sharing one reference. Keying
+   * on the reference would collapse several unacknowledged renewals into
+   * one entry and leave the rest unfinished.
    */
   async add(tx) {
     return this.runExclusive(async () => {
@@ -1880,6 +3584,12 @@ var UnfinishedTransactionsStore = class {
         token: tx.token,
         productType: tx.productType,
         ...tx.packageName ? { packageName: tx.packageName } : {},
+        ...tx.purchaseReference ? { purchaseReference: tx.purchaseReference } : {},
+        ...tx.appUserId ? { appUserId: tx.appUserId } : {},
+        ...tx.subscription?.expiresAt ? { expiresAt: tx.subscription.expiresAt } : {},
+        ...typeof tx.raw?.purchaseState === "string" || typeof tx.raw?.purchaseState === "number" ? {
+          purchaseState: String(tx.raw.purchaseState)
+        } : {},
         recordedAt: (/* @__PURE__ */ new Date()).toISOString()
       };
       await this.persist([...current, entry]);
@@ -1898,40 +3608,20 @@ var UnfinishedTransactionsStore = class {
   async clear() {
     return this.runExclusive(() => this.safeClear());
   }
-  /**
-   * Run `fn` with exclusive access to the storage key. Implements a simple
-   * promise chain — every mutation awaits the previous one's completion.
-   * Reads (`list()`) are NOT serialized because they're tolerant of stale
-   * snapshots (callers either compose or accept the read-once semantic).
-   */
-  async runExclusive(fn) {
-    const prev = this.mutationLock;
-    let release;
-    this.mutationLock = new Promise((resolve) => {
-      release = resolve;
-    });
-    try {
-      await prev;
-      return await fn();
-    } finally {
-      release();
-    }
-  }
   async persist(entries) {
     try {
-      await this.storage.set(STORE_KEY, JSON.stringify(entries));
+      await this.storage.set(STORE_KEY2, JSON.stringify(entries));
     } catch (cause) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.STORAGE_ERROR,
-        message: "Failed to persist unfinished transactions list.",
+      throw toIAPError(
         cause,
-        recoverable: true
-      });
+        "Failed to persist unfinished transactions list.",
+        exports.IAPErrorCode.STORAGE_ERROR
+      );
     }
   }
   async safeClear() {
     try {
-      await this.storage.remove(STORE_KEY);
+      await this.storage.remove(STORE_KEY2);
     } catch (cause) {
       this.logger.warn("Failed to clear unfinished_transactions key.", cause);
     }
@@ -2010,14 +3700,20 @@ function isLogger(value) {
 }
 
 // src/createIAP.ts
-init_platform();
 function createIAP(input) {
   const config = parseConfig(input);
   const logger = resolveLogger(config.options.logLevel, config.options.logger);
   const storage = selectStorageAdapter(config.storage);
   const cache = new EntitlementCache(storage, logger);
   const unfinished = new UnfinishedTransactionsStore(storage, logger);
-  const backend = selectBackendAdapter({ config: config.backend, logger });
+  const pending = new PendingPurchasesStore(storage, logger);
+  const backend = selectBackendAdapter({
+    config,
+    logger,
+    getNativeAdapter: () => state.adapter,
+    getProducts: () => state.products,
+    getCurrentEntitlements: () => state.entitlements
+  });
   const emitter = new TypedEventEmitter();
   if (config.products) {
     ensureUniqueProductIds(config.products);
@@ -2029,9 +3725,12 @@ function createIAP(input) {
     storage,
     cache,
     unfinished,
+    pending,
     orchestrator: null,
     restorer: null,
     recoverer: null,
+    updates: null,
+    txWatch: null,
     resumeListener: null,
     emitter,
     logger,
@@ -2061,123 +3760,7 @@ function createIAP(input) {
   }
   return {
     async initialize() {
-      if (state.destroyed) {
-        throw new exports.IAPError({
-          code: exports.IAPErrorCode.NOT_INITIALIZED,
-          message: "IAP instance has been destroyed; create a new one with createIAP()."
-        });
-      }
-      if (state.initialized) {
-        state.logger.debug("initialize() called more than once; ignoring.");
-        return;
-      }
-      const platform = getPlatform();
-      if (!isNative()) {
-        state.logger.info(
-          "Native purchases unavailable on web; entitlement queries still functional."
-        );
-      } else {
-        state.logger.debug(`Initializing on platform=${platform}`);
-      }
-      if (!state.config.products) {
-        if (typeof state.backend.listProducts !== "function") {
-          throw new exports.IAPError({
-            code: exports.IAPErrorCode.INVALID_CONFIG,
-            message: "config.products is omitted but backend adapter does not implement listProducts(). This is a library bug; the schema should have caught it."
-          });
-        }
-        const fetched = await state.backend.listProducts();
-        const validated = configuredProductsArraySchema.safeParse(fetched);
-        if (!validated.success) {
-          throw new exports.IAPError({
-            code: exports.IAPErrorCode.BACKEND_BAD_RESPONSE,
-            message: `backend.listProducts() returned an invalid manifest: ${validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`,
-            cause: validated.error
-          });
-        }
-        ensureUniqueProductIds(validated.data);
-        state.products = Object.freeze([...validated.data]);
-        state.logger.debug(`Resolved ${validated.data.length} product(s) from backend manifest.`);
-      }
-      state.adapter = await selectNativeAdapter();
-      const configGetAuthHeaders = state.config.backend.getAuthHeaders;
-      const getAuthHeaders = configGetAuthHeaders ? async () => configGetAuthHeaders() : async () => ({});
-      const sharedDeps = {
-        nativeAdapter: state.adapter,
-        backend: state.backend,
-        cache: state.cache,
-        unfinished: state.unfinished,
-        emitter: state.emitter,
-        logger: state.logger,
-        getCurrentEntitlements: () => state.entitlements,
-        setEntitlements: (next) => {
-          state.entitlements = freezeAll(next);
-        },
-        setCachePersisted: (cachedAt) => {
-          state.cachedAt = cachedAt;
-        },
-        getAuthHeaders
-      };
-      state.orchestrator = new PurchaseOrchestrator({
-        ...sharedDeps,
-        products: state.products
-      });
-      state.restorer = new RestoreOrchestrator(sharedDeps);
-      state.recoverer = new RecoveryOrchestrator({
-        ...sharedDeps,
-        maxBatch: state.config.options.recoveryMaxBatch,
-        permanentErrorCodes: new Set(
-          state.config.options.permanentErrorCodes ?? DEFAULT_PERMANENT_ERROR_CODES
-        )
-      });
-      try {
-        await state.adapter.isAvailable();
-      } catch (error) {
-        state.logger.warn("Native adapter availability check threw; continuing.", error);
-      }
-      const cached = await state.cache.load();
-      if (cached) {
-        state.entitlements = freezeAll(cached.entitlements);
-        state.cachedAt = cached.cachedAt;
-        state.logger.debug(
-          `Loaded ${cached.entitlements.length} cached entitlement(s) from ${new Date(cached.cachedAt).toISOString()}.`
-        );
-      }
-      if (state.config.options.recoverUnfinishedTransactions && isNative()) {
-        try {
-          const result = await state.recoverer.recoverUnfinishedTransactions();
-          if (result.inspected > 0) {
-            state.logger.info(
-              `Recovery inspected ${result.inspected} unfinished transaction(s): ${result.recovered} recovered, ${result.failures} retained.`
-            );
-          }
-        } catch (error) {
-          state.logger.warn("Recovery threw unexpectedly; continuing initialize.", error);
-        }
-      }
-      if (state.config.options.refreshOnResume && isNative()) {
-        state.resumeListener = await attachAppResumeListener({
-          logger: state.logger,
-          onResume: async () => {
-            try {
-              await refreshEntitlements();
-            } catch (error) {
-              state.logger.warn("refreshOnResume: refresh() failed.", error);
-            }
-          }
-        });
-      }
-      if (state.cachedAt !== null && Date.now() - state.cachedAt > state.config.options.entitlementCacheTtlMs) {
-        state.logger.debug("Cache exceeds TTL; scheduling background refresh.");
-        queueMicrotask(() => {
-          if (!state.initialized || state.destroyed) return;
-          refreshEntitlements().catch((error) => {
-            state.logger.warn("TTL background refresh failed.", error);
-          });
-        });
-      }
-      state.initialized = true;
-      state.emitter.emit("ready", void 0);
+      return initializeIap(state, refreshEntitlements);
     },
     refresh: refreshEntitlements,
     async destroy() {
@@ -2195,6 +3778,14 @@ function createIAP(input) {
         }
         state.resumeListener = null;
       }
+      if (state.txWatch) {
+        try {
+          await state.txWatch.remove();
+        } catch (error) {
+          state.logger.warn("Transaction listener remove threw; continuing teardown.", error);
+        }
+        state.txWatch = null;
+      }
       if (state.adapter?.dispose) {
         try {
           await state.adapter.dispose();
@@ -2206,6 +3797,7 @@ function createIAP(input) {
       state.orchestrator = null;
       state.restorer = null;
       state.recoverer = null;
+      state.updates = null;
     },
     async purchase(opts) {
       requireInitialized(state);
@@ -2235,29 +3827,32 @@ function createIAP(input) {
           message: "Native adapter not constructed; this is a library bug."
         });
       }
-      return state.adapter.getProducts(state.products.map((p) => ({ id: p.id, type: p.type })));
+      return state.adapter.getProducts([...state.products]);
     },
     async getStorefront() {
       requireInitialized(state);
       return state.adapter?.getStorefront?.() ?? null;
     },
     hasEntitlement(key) {
-      return state.entitlements.some((e) => e.key === key);
+      return activeNow(state).some((e) => e.key === key);
     },
     getEntitlements() {
-      return [...state.entitlements];
+      return activeNow(state);
     },
     getEntitlement(key) {
-      return state.entitlements.find((e) => e.key === key) ?? null;
+      return activeNow(state).find((e) => e.key === key) ?? null;
+    },
+    getEntitlementsVerifiedAt() {
+      return state.cachedAt === null ? null : new Date(state.cachedAt).toISOString();
+    },
+    async reset() {
+      return resetIap(state);
     },
     on(event, handler) {
       return state.emitter.on(event, handler);
     }
   };
 }
-function freezeAll(items) {
-  return items.map((item) => Object.freeze({ ...item }));
-}
 function parseConfig(input) {
   try {
     const parsed = iapConfigSchema.parse(input);
@@ -2275,36 +3870,16 @@ ${issues}`,
     throw error;
   }
 }
-function ensureUniqueProductIds(products) {
-  const seen = /* @__PURE__ */ new Set();
-  for (const product of products) {
-    if (seen.has(product.id)) {
-      throw new exports.IAPError({
-        code: exports.IAPErrorCode.INVALID_CONFIG,
-        message: `Duplicate product id "${product.id}" in product manifest.`
-      });
-    }
-    seen.add(product.id);
-  }
-}
 function resolveLogger(level, candidate) {
   if (isLogger(candidate)) return candidate;
   return createDefaultLogger(level);
 }
-function requireInitialized(state) {
-  if (!state.initialized) {
-    throw new exports.IAPError({
-      code: exports.IAPErrorCode.NOT_INITIALIZED,
-      message: "Call iap.initialize() before this method."
-    });
-  }
-}
 
 // src/index.ts
 init_errors();
 
 // src/version.ts
-var VERSION = "8.0.0";
+var VERSION = "8.2.0";
 
 exports.DEFAULT_PERMANENT_ERROR_CODES = DEFAULT_PERMANENT_ERROR_CODES;
 exports.HttpBackendAdapter = HttpBackendAdapter;
@@ -2312,6 +3887,8 @@ exports.HttpClient = HttpClient;
 exports.VERSION = VERSION;
 exports.createIAP = createIAP;
 exports.errorHint = errorHint;
+exports.isExpired = isExpired;
 exports.isIAPError = isIAPError;
+exports.verifyPurchaseOnDevice = verifyPurchaseOnDevice;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map