@nosslabs/iap 8.0.0 → 8.1.0

package/dist/index.d.cts

@@ -64,6 +64,403 @@ declare class HttpClient {
     private fetchWithTimeout;
 }
 
+type ProductType = 'subscription' | 'product' | 'consumable';
+interface ConfiguredProduct {
+    id: string;
+    type: ProductType;
+    /**
+     * Required for Android subscriptions — the base plan identifier configured in
+     * Google Play Console. Ignored on iOS and for non-subscription products.
+     *
+     * Keep it in step with Play Console. When it matches no offer, the native
+     * plugin does **not** fail — it falls back to the first available base
+     * plan, so a stale value silently purchases a different plan. See
+     * `docs/guide/native-layer.md`.
+     */
+    androidPlanId?: string;
+}
+/** What kind of offer this is, as the store classifies it. */
+type SubscriptionOfferType = 'introductory' | 'promotional' | 'win-back' | 'unknown';
+/**
+ * How the offer is paid for.
+ *
+ * - `free-trial` — no charge for the offer period.
+ * - `pay-up-front` — one discounted charge covering the whole offer period.
+ * - `pay-as-you-go` — a discounted charge each period, for `periodCount`
+ *   periods.
+ */
+type SubscriptionOfferPayment = 'free-trial' | 'pay-up-front' | 'pay-as-you-go' | 'unknown';
+/**
+ * An introductory or promotional offer on a subscription, normalized across
+ * platforms.
+ *
+ * Render `priceString` as-is; it is the store's own localized string, in the
+ * store's currency and format. Never reconstruct a price from `priceMicros`
+ * for display — that is for arithmetic and comparison only.
+ */
+interface SubscriptionOffer {
+    /**
+     * The store's identifier for the offer. `null` for an offer the store does
+     * not name — typically an iOS introductory offer, or an Android base-plan
+     * intro phase (which has no offer id of its own).
+     */
+    id: string | null;
+    type: SubscriptionOfferType;
+    payment: SubscriptionOfferPayment;
+    /** Localized price string for the offer, e.g. "$0.00" or "₱49.00". */
+    priceString: string;
+    /** BigInt-safe string of micro-units, e.g. "0" or "49000000". */
+    priceMicros: string;
+    /** ISO 4217 code, e.g. "PHP". */
+    currency: string;
+    /**
+     * Offer period as an ISO 8601 duration, e.g. `"P1W"`. `null` if unknown.
+     *
+     * Single-component on Android: the native plugin's period parser keeps
+     * only the largest non-zero unit, so a Play period of `P1M15D` arrives
+     * as `P1M`.
+     */
+    period: string | null;
+    /**
+     * How many periods the offer applies for.
+     *
+     * On iOS: `1` for a free trial or a pay-up-front offer, higher for
+     * pay-as-you-go.
+     *
+     * **On Android this is usually `0`**, and that does not mean zero
+     * periods. It is Play's `getBillingCycleCount()`, which reports `0` for
+     * both a non-recurring phase and an infinitely recurring one — so a
+     * pay-up-front Android offer reports `0` too. Treat `0` as "the store
+     * did not say" and do not render it as a count.
+     */
+    periodCount: number;
+}
+/**
+ * Native product info merged with configured metadata.
+ * Library-public shape — kept stable across Capacitor versions.
+ */
+interface Product {
+    id: string;
+    type: ProductType;
+    title: string;
+    description: string;
+    /** Localized price string, e.g. "$4.99". Always render this — never hardcode. */
+    priceString: string;
+    /** BigInt as string to avoid precision loss, e.g. "4990000". */
+    priceMicros: string;
+    /** ISO 4217 code, e.g. "USD". */
+    currency: string;
+    /**
+     * The recurring billing period as an ISO 8601 duration, e.g. `"P1M"`.
+     *
+     * **iOS only.** `null` on Android: the native plugin collapses Play's
+     * pricing phases before exposing them and never surfaces a base plan's
+     * billing period, so it is not reachable. Where you need the cadence on
+     * both platforms, take it from your own product configuration — you chose
+     * the base plan's period in Play Console.
+     */
+    subscriptionPeriod?: string | null;
+    /**
+     * The subscription group this product belongs to. Products in one group are
+     * mutually exclusive, and on iOS introductory-offer eligibility is assessed
+     * per group rather than per product.
+     *
+     * **iOS only.** `null` on Android, which has no equivalent concept exposed.
+     */
+    subscriptionGroupId?: string | null;
+    /**
+     * The introductory offer on this subscription, or `null` when it has none.
+     *
+     * **Whether *this user* is eligible for it cannot be known on the device.**
+     * The native plugin exposes no eligibility query on either platform, so an
+     * offer being present here means "this product has one", not "this user
+     * will get it". The store's own purchase sheet applies eligibility at
+     * purchase time and is the authority. Write paywall copy that reads
+     * correctly either way, or confirm eligibility server-side.
+     */
+    introductoryOffer?: SubscriptionOffer | null;
+    /**
+     * Promotional and win-back offers on this subscription. Empty when there
+     * are none. Same eligibility caveat as {@link Product.introductoryOffer}.
+     *
+     * **On Android, do not render these as the offer's own terms.** The
+     * native plugin builds each promotional entry from the base plan's
+     * *standard* recurring pricing phase, not from the promotional phase —
+     * so a free-trial promo arrives as `payment: 'pay-as-you-go'` at the
+     * full price. Use them to know an offer exists and to identify it; take
+     * the terms from your backend or from Play Console. iOS reports the
+     * offer's real terms, and {@link Product.introductoryOffer} is
+     * unaffected on both platforms.
+     */
+    promotionalOffers?: SubscriptionOffer[];
+    /**
+     * Android: Play's token for the specific offer this entry describes, and
+     * the offer's id (`null` for a base plan with no offer).
+     *
+     * Exposed for identification and server-side reasoning only. A purchase
+     * **cannot** select an offer by token: the native plugin's purchase call
+     * takes a base plan id, and picks the offer itself. See
+     * `docs/guide/native-layer.md`.
+     */
+    androidOfferToken?: string | null;
+    androidOfferId?: string | null;
+    /**
+     * Android: the base plan this entry describes, as configured in Play
+     * Console. `null` on iOS, which has no base-plan concept — there a
+     * product id identifies the subscription directly.
+     *
+     * `id` is always the product id you configured, on both platforms, so it
+     * round-trips to `purchase({ productId })`. This is the extra level Play
+     * adds underneath it.
+     */
+    androidBasePlanId?: string | null;
+}
+
+/** Platform a transaction originated from. */
+type Platform = 'apple' | 'google';
+/**
+ * Where a subscription stands with the store, as the store reports it.
+ *
+ * iap passes these through; it does not interpret them. Deciding what counts
+ * as "entitled" — whether a grace period still grants access, say — is the
+ * consumer's business rule, and the authoritative answer comes from the
+ * backend (PLAN.md §14).
+ */
+type SubscriptionState = 'subscribed' | 'expired' | 'revoked' | 'in-grace-period' | 'in-billing-retry' | 'unknown';
+/**
+ * Renewal detail for an auto-renewing subscription, normalized from the
+ * store's own fields.
+ *
+ * **iOS only, in practice.** Every field is `null` on Android: the native
+ * plugin exposes neither `isAutoRenewing` nor a renewal date, and reports
+ * cancellation as always-null. On Android this information lives server-side
+ * (Google Play Developer API), so take it from your backend.
+ */
+interface SubscriptionRenewal {
+    state: SubscriptionState | null;
+    /**
+     * Whether the subscription renews at the end of the current period.
+     * `false` means the user cancelled but still has access until it expires.
+     */
+    autoRenewing: boolean | null;
+    /** When the next period begins, ISO 8601. */
+    renewsAt: string | null;
+    /**
+     * The product the subscription renews into — different from the current
+     * one after a plan change takes effect at the period boundary.
+     */
+    renewalProductId: string | null;
+    /** When the current period ends, ISO 8601. */
+    expiresAt: string | null;
+}
+/**
+ * Normalized native transaction handed to core flows.
+ * Plugin-version differences are translated by the adapter so this shape
+ * stays stable across Capacitor majors.
+ */
+interface NativeTransaction {
+    platform: Platform;
+    productId: string;
+    /**
+     * Apple: the StoreKit `transactionId` (numeric string) — **changes with
+     * every renewal**. Google: the `purchaseToken` from Play Billing.
+     *
+     * This is the handle for acknowledging *this* transaction. To store a
+     * reference to the purchase itself, use `purchaseReference` — which is
+     * what a consumer sees, as `StorePurchase.purchaseReference`.
+     */
+    token: string;
+    /**
+     * The stable reference to the purchase, which survives renewals — store
+     * this when you need to identify the subscription later.
+     *
+     * Apple: `originalTransactionId`, read from the signed `jwsRepresentation`
+     * payload (the plugin does not expose it as a field). Falls back to
+     * `token` when the JWS is absent or unreadable, so it is always set.
+     * Google: the `purchaseToken`, identical to `token`.
+     */
+    purchaseReference: string;
+    /** Google only — required by Attesto's `/v1/google/verify`. */
+    packageName?: string;
+    /** Product type the transaction was originally purchased as. */
+    productType: ProductType;
+    /**
+     * The binding this purchase was made with, read back off the transaction:
+     * `appAccountToken` on iOS, `obfuscatedAccountId` on Android. `null` when
+     * the purchase carried none.
+     *
+     * Use it to check what a purchase is bound to. iap never generates one —
+     * it is whatever was passed as `iap.purchase({ appUserId })`.
+     */
+    appUserId?: string | null;
+    /**
+     * Renewal detail for a subscription, or `null` for a non-subscription and
+     * on platforms that do not report it. See {@link SubscriptionRenewal}.
+     */
+    subscription?: SubscriptionRenewal | null;
+    /** Optional pass-through of plugin-native fields for backend hints. */
+    raw?: unknown;
+}
+/**
+ * Verified transaction returned by the consumer backend after Attesto check.
+ * Generic over the backend-defined transaction shape.
+ */
+interface VerifiedTransaction<TExtra = Record<string, unknown>> {
+    id: string;
+    productId: string;
+    expiresAt: string | null;
+    verifiedAt: string;
+    raw?: TExtra;
+}
+
+/**
+ * How strongly a purchase was checked. Exposed rather than hidden, because
+ * the two platforms genuinely differ and a consumer deciding what to unlock
+ * offline deserves to know which one it got.
+ *
+ * - `store-signed` — iOS. StoreKit 2 verified Apple's signature over the
+ *   transaction in native code before it ever reached the WebView; the
+ *   native layer resolves a purchase only for a `VerificationResult.verified`
+ *   and rejects anything else. So this is a cryptographic guarantee, made by
+ *   the platform rather than by iap.
+ * - `store-reported` — Android. The native layer exposes neither Play's
+ *   purchase signature nor the original JSON, so **no cryptographic check is
+ *   possible on the device**. This means "Play told this device it owns
+ *   this", which is a real answer and the one Play's own client APIs give —
+ *   but it is the store's say-so, not proof.
+ *
+ * Neither is a substitute for server-side validation against the store's
+ * API. A rooted device can lie to the app about both.
+ */
+type PurchaseAssurance = 'store-signed' | 'store-reported';
+/** Why a local check refused a purchase. Stable strings, safe to switch on. */
+type LocalVerificationError = 'PRODUCT_NOT_CONFIGURED' | 'BINDING_MISMATCH'
+/**
+ * The app binds purchases to an account, and there is no account to bind
+ * to right now — a signed-out session, or a `verification.appUserId`
+ * getter that threw. Raised by `LocalVerificationAdapter`, never by
+ * {@link verifyPurchaseOnDevice}, which is told the binding rather than
+ * resolving it.
+ */
+ | 'BINDING_UNAVAILABLE' | 'NOT_PURCHASED' | 'REVOKED' | 'SUBSCRIPTION_EXPIRED';
+/** A purchase that passed the on-device checks. */
+interface LocallyVerifiedPurchase {
+    productId: string;
+    platform: Platform;
+    /**
+     * What the purchase was bought as.
+     *
+     * Exposed because it changes what an entitlement *means*, and a mapper
+     * needs to know. In particular iOS's owned set retains **finished
+     * consumables**, so a mapper that grants on every verified purchase
+     * re-grants a consumable on every refresh, forever. A consumable's effect
+     * belongs in your own records, not in a standing entitlement.
+     */
+    productType: ProductType;
+    /** Stable across renewals. See `NativeTransaction.purchaseReference`. */
+    purchaseReference: string;
+    /** The binding the purchase carried, or `null`. */
+    appUserId: string | null;
+    /** ISO 8601 for a subscription; `null` for a non-expiring purchase. */
+    expiresAt: string | null;
+    subscription: SubscriptionRenewal | null;
+    /** How strongly this was checked. See {@link PurchaseAssurance}. */
+    assurance: PurchaseAssurance;
+}
+type LocalVerification = {
+    valid: true;
+    purchase: LocallyVerifiedPurchase;
+} | {
+    valid: false;
+    error: LocalVerificationError;
+    message: string;
+};
+interface LocalVerificationOptions {
+    /**
+     * Product ids the app sells. A transaction for anything else is refused —
+     * the store can report purchases from a previous version of the app, or
+     * from a product that has since been retired.
+     */
+    productIds: readonly string[];
+    /**
+     * When set, the purchase must carry this binding. Compared
+     * case-insensitively, because StoreKit returns an uppercase UUID string
+     * while callers deal in lowercase.
+     *
+     * `null` or omitted skips the check: a purchase made before the app
+     * started binding, or a flow with no user identity, carries none.
+     */
+    appUserId?: string | null;
+    /** Extra time past `expiresAt` during which a subscription still counts. */
+    graceMs?: number;
+    /** Injectable clock. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Whether an ISO 8601 expiry has passed, by the **device** clock.
+ *
+ * The device clock is the only clock available with no backend, and it can
+ * be wrong — a user can set it back and extend a subscription. That is the
+ * accepted cost of working offline, and the reason this is not a substitute
+ * for server-side validation.
+ *
+ * An unparseable or absent expiry is treated as "does not expire" rather
+ * than "expired": refusing a purchase because its expiry string was
+ * malformed would revoke access over a formatting problem.
+ *
+ * `expiresAt` must be ISO 8601. `Date.parse` is lenient and
+ * implementation-defined for anything else — `'10/26/2026'` parses as
+ * *local* time in V8 — so a non-ISO string may compare against the wrong
+ * instant. Everything iap produces is ISO 8601; this matters only for a
+ * value you supply. An exact boundary (`now === expiry`) reads as active.
+ */
+declare function isExpired(expiresAt: string | null | undefined, now: number, graceMs?: number): boolean;
+/**
+ * Check a purchase on the device, with no backend.
+ *
+ * This is the whole of what can be checked without a server, and it is
+ * deliberately a short list:
+ *
+ * 1. The product is one the app actually sells.
+ * 2. The binding matches, when one is expected.
+ * 3. On Android, the store calls the purchase purchased rather than pending.
+ * 4. The purchase has not been revoked or refunded, where the platform
+ *    says so locally (iOS does; Android does not).
+ * 5. A subscription has not expired by the device clock.
+ *
+ * What it does **not** do is verify a signature. On iOS it does not need to —
+ * the platform already did, natively, and {@link PurchaseAssurance}
+ * records that. On Android it cannot: the native layer exposes neither
+ * Play's purchase signature nor the original JSON it is computed over.
+ *
+ * So a passing result means "this device's store says it owns this, and the
+ * claim is internally consistent" — strong on iOS, the store's word on
+ * Android. For anything where being wrong is expensive, verify server-side.
+ */
+declare function verifyPurchaseOnDevice(transaction: NativeTransaction, options: LocalVerificationOptions): LocalVerification;
+
+declare const entitlementBaseSchema: z.ZodObject<{
+    key: z.ZodString;
+    productId: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    productId: string;
+    expiresAt: string | null;
+}, {
+    key: string;
+    productId: string;
+    expiresAt: string | null;
+}>;
+/**
+ * Minimum shape every entitlement returned by the backend must satisfy.
+ * Consumer-defined fields pass through unvalidated unless the consumer
+ * supplies their own schema via `config.backend.entitlementSchema`.
+ */
+type EntitlementBase = z.infer<typeof entitlementBaseSchema>;
+/** Default shape used when no `TEntitlement` type parameter is given. */
+type DefaultEntitlement = EntitlementBase;
+
 declare const backendConfigSchema: z.ZodEffects<z.ZodObject<{
     /**
      * Custom backend transport. If provided, all HTTP-specific fields below
@@ -200,22 +597,87 @@ declare const backendConfigSchema: z.ZodEffects<z.ZodObject<{
     timeoutMs?: number | undefined;
     retries?: number | undefined;
 }>;
+/**
+ * Verify purchases on the device instead of through a backend.
+ *
+ * For an app with no server at all. Every safety guarantee still applies —
+ * the purchase flow, the acknowledge-after-verify ordering and the
+ * unfinished-transaction recovery are all above the adapter boundary and do
+ * not know which mode they are in. What changes is who answers "is this
+ * purchase real", and how strong that answer is.
+ *
+ * Read `docs/guide/offline-and-no-backend.md` before choosing this: on
+ * Android no cryptographic check is possible on the device, so a passing
+ * verification there means "Play told this device it owns this".
+ */
+declare const verificationConfigSchema: z.ZodObject<{
+    mode: z.ZodLiteral<"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: z.ZodUnknown;
+    /**
+     * 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: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    mode: "local";
+    entitlements?: unknown;
+    appUserId?: unknown;
+}, {
+    mode: "local";
+    entitlements?: unknown;
+    appUserId?: unknown;
+}>;
 declare const storageConfigSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodEnum<["preferences", "memory", "custom"]>>;
     namespace: z.ZodDefault<z.ZodString>;
     adapter: z.ZodOptional<z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
-    type: "preferences" | "memory" | "custom";
+    type: "custom" | "preferences" | "memory";
     namespace: string;
     adapter?: unknown;
 }, {
-    type?: "preferences" | "memory" | "custom" | undefined;
+    type?: "custom" | "preferences" | "memory" | undefined;
     adapter?: unknown;
     namespace?: string | undefined;
 }>;
 declare const optionsConfigSchema: z.ZodObject<{
     refreshOnResume: z.ZodDefault<z.ZodBoolean>;
     entitlementCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
     recoverUnfinishedTransactions: z.ZodDefault<z.ZodBoolean>;
     /**
      * Cap on how many unfinished transactions recovery inspects per launch.
@@ -243,20 +705,22 @@ declare const optionsConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     refreshOnResume: boolean;
     entitlementCacheTtlMs: number;
+    entitlementGraceMs: number;
     recoverUnfinishedTransactions: boolean;
     recoveryMaxBatch: number;
     productPriceCacheTtlMs: number;
-    logLevel: "silent" | "error" | "warn" | "info" | "debug";
+    logLevel: "error" | "silent" | "warn" | "info" | "debug";
     permanentErrorCodes?: string[] | undefined;
     logger?: unknown;
 }, {
     refreshOnResume?: boolean | undefined;
     entitlementCacheTtlMs?: number | undefined;
+    entitlementGraceMs?: number | undefined;
     recoverUnfinishedTransactions?: boolean | undefined;
     recoveryMaxBatch?: number | undefined;
     permanentErrorCodes?: string[] | undefined;
     productPriceCacheTtlMs?: number | undefined;
-    logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+    logLevel?: "error" | "silent" | "warn" | "info" | "debug" | undefined;
     logger?: unknown;
 }>;
 declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
@@ -281,15 +745,20 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         androidPlanId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }, {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }>, "many">>;
-    backend: z.ZodEffects<z.ZodObject<{
+    /**
+     * 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: z.ZodOptional<z.ZodEffects<z.ZodObject<{
         /**
          * Custom backend transport. If provided, all HTTP-specific fields below
          * are ignored and the library uses this object directly for backend
@@ -424,23 +893,84 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         entitlementSchema?: unknown;
         timeoutMs?: number | undefined;
         retries?: number | undefined;
-    }>;
+    }>>;
+    /** On-device verification, for an app with no backend. */
+    verification: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodLiteral<"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: z.ZodUnknown;
+        /**
+         * 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: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    }, {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    }>>;
+    /** Android-specific settings. See {@link androidConfigSchema}. */
+    android: z.ZodDefault<z.ZodObject<{
+        packageName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        packageName?: string | undefined;
+    }, {
+        packageName?: string | undefined;
+    }>>;
     storage: z.ZodDefault<z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<["preferences", "memory", "custom"]>>;
         namespace: z.ZodDefault<z.ZodString>;
         adapter: z.ZodOptional<z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
-        type: "preferences" | "memory" | "custom";
+        type: "custom" | "preferences" | "memory";
         namespace: string;
         adapter?: unknown;
     }, {
-        type?: "preferences" | "memory" | "custom" | undefined;
+        type?: "custom" | "preferences" | "memory" | undefined;
         adapter?: unknown;
         namespace?: string | undefined;
     }>>;
     options: z.ZodDefault<z.ZodObject<{
         refreshOnResume: z.ZodDefault<z.ZodBoolean>;
         entitlementCacheTtlMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
         recoverUnfinishedTransactions: z.ZodDefault<z.ZodBoolean>;
         /**
          * Cap on how many unfinished transactions recovery inspects per launch.
@@ -468,62 +998,52 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         refreshOnResume: boolean;
         entitlementCacheTtlMs: number;
+        entitlementGraceMs: number;
         recoverUnfinishedTransactions: boolean;
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
-        logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        logLevel: "error" | "silent" | "warn" | "info" | "debug";
         permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     }, {
         refreshOnResume?: boolean | undefined;
         entitlementCacheTtlMs?: number | undefined;
+        entitlementGraceMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
         permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
-        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logLevel?: "error" | "silent" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
     }>>;
 }, "strip", z.ZodTypeAny, {
     options: {
         refreshOnResume: boolean;
         entitlementCacheTtlMs: number;
+        entitlementGraceMs: number;
         recoverUnfinishedTransactions: boolean;
         recoveryMaxBatch: number;
         productPriceCacheTtlMs: number;
-        logLevel: "silent" | "error" | "warn" | "info" | "debug";
+        logLevel: "error" | "silent" | "warn" | "info" | "debug";
         permanentErrorCodes?: string[] | undefined;
         logger?: unknown;
     };
-    backend: {
-        timeoutMs: number;
-        retries: number;
-        adapter?: unknown;
-        baseUrl?: string | undefined;
-        endpoints?: {
-            entitlements: string;
-            restore: string;
-            verifyApple?: string | undefined;
-            verifyGoogle?: string | undefined;
-            products?: string | undefined;
-        } | undefined;
-        getAuthHeaders?: unknown;
-        requestTransform?: unknown;
-        responseTransform?: unknown;
-        entitlementSchema?: unknown;
+    android: {
+        packageName?: string | undefined;
     };
     storage: {
-        type: "preferences" | "memory" | "custom";
+        type: "custom" | "preferences" | "memory";
         namespace: string;
         adapter?: unknown;
     };
     products?: {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }[] | undefined;
-}, {
-    backend: {
+    backend?: {
+        timeoutMs: number;
+        retries: number;
         adapter?: unknown;
         baseUrl?: string | undefined;
         endpoints?: {
@@ -537,43 +1057,30 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         requestTransform?: unknown;
         responseTransform?: unknown;
         entitlementSchema?: unknown;
-        timeoutMs?: number | undefined;
-        retries?: number | undefined;
-    };
+    } | undefined;
+    verification?: {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    } | undefined;
+}, {
     options?: {
         refreshOnResume?: boolean | undefined;
         entitlementCacheTtlMs?: number | undefined;
+        entitlementGraceMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
         permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
-        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logLevel?: "error" | "silent" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
     } | undefined;
     products?: {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }[] | undefined;
-    storage?: {
-        type?: "preferences" | "memory" | "custom" | undefined;
-        adapter?: unknown;
-        namespace?: string | undefined;
-    } | undefined;
-}>, {
-    options: {
-        refreshOnResume: boolean;
-        entitlementCacheTtlMs: number;
-        recoverUnfinishedTransactions: boolean;
-        recoveryMaxBatch: number;
-        productPriceCacheTtlMs: number;
-        logLevel: "silent" | "error" | "warn" | "info" | "debug";
-        permanentErrorCodes?: string[] | undefined;
-        logger?: unknown;
-    };
-    backend: {
-        timeoutMs: number;
-        retries: number;
+    backend?: {
         adapter?: unknown;
         baseUrl?: string | undefined;
         endpoints?: {
@@ -587,19 +1094,50 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         requestTransform?: unknown;
         responseTransform?: unknown;
         entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    } | undefined;
+    verification?: {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    } | undefined;
+    android?: {
+        packageName?: string | undefined;
+    } | undefined;
+    storage?: {
+        type?: "custom" | "preferences" | "memory" | undefined;
+        adapter?: unknown;
+        namespace?: string | undefined;
+    } | undefined;
+}>, {
+    options: {
+        refreshOnResume: boolean;
+        entitlementCacheTtlMs: number;
+        entitlementGraceMs: number;
+        recoverUnfinishedTransactions: boolean;
+        recoveryMaxBatch: number;
+        productPriceCacheTtlMs: number;
+        logLevel: "error" | "silent" | "warn" | "info" | "debug";
+        permanentErrorCodes?: string[] | undefined;
+        logger?: unknown;
+    };
+    android: {
+        packageName?: string | undefined;
     };
     storage: {
-        type: "preferences" | "memory" | "custom";
+        type: "custom" | "preferences" | "memory";
         namespace: string;
         adapter?: unknown;
     };
     products?: {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }[] | undefined;
-}, {
-    backend: {
+    backend?: {
+        timeoutMs: number;
+        retries: number;
         adapter?: unknown;
         baseUrl?: string | undefined;
         endpoints?: {
@@ -613,26 +1151,56 @@ declare const iapConfigSchema: z.ZodEffects<z.ZodObject<{
         requestTransform?: unknown;
         responseTransform?: unknown;
         entitlementSchema?: unknown;
-        timeoutMs?: number | undefined;
-        retries?: number | undefined;
-    };
+    } | undefined;
+    verification?: {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    } | undefined;
+}, {
     options?: {
         refreshOnResume?: boolean | undefined;
         entitlementCacheTtlMs?: number | undefined;
+        entitlementGraceMs?: number | undefined;
         recoverUnfinishedTransactions?: boolean | undefined;
         recoveryMaxBatch?: number | undefined;
         permanentErrorCodes?: string[] | undefined;
         productPriceCacheTtlMs?: number | undefined;
-        logLevel?: "silent" | "error" | "warn" | "info" | "debug" | undefined;
+        logLevel?: "error" | "silent" | "warn" | "info" | "debug" | undefined;
         logger?: unknown;
     } | undefined;
     products?: {
-        id: string;
         type: "subscription" | "product" | "consumable";
+        id: string;
         androidPlanId?: string | undefined;
     }[] | undefined;
+    backend?: {
+        adapter?: unknown;
+        baseUrl?: string | undefined;
+        endpoints?: {
+            entitlements: string;
+            restore: string;
+            verifyApple?: string | undefined;
+            verifyGoogle?: string | undefined;
+            products?: string | undefined;
+        } | undefined;
+        getAuthHeaders?: unknown;
+        requestTransform?: unknown;
+        responseTransform?: unknown;
+        entitlementSchema?: unknown;
+        timeoutMs?: number | undefined;
+        retries?: number | undefined;
+    } | undefined;
+    verification?: {
+        mode: "local";
+        entitlements?: unknown;
+        appUserId?: unknown;
+    } | undefined;
+    android?: {
+        packageName?: string | undefined;
+    } | undefined;
     storage?: {
-        type?: "preferences" | "memory" | "custom" | undefined;
+        type?: "custom" | "preferences" | "memory" | undefined;
         adapter?: unknown;
         namespace?: string | undefined;
     } | undefined;
@@ -659,37 +1227,34 @@ type BackendConfig = Omit<RawBackendConfig, 'getAuthHeaders' | 'requestTransform
 type BackendConfigInput = Omit<RawBackendConfigInput, 'getAuthHeaders' | 'requestTransform' | 'responseTransform'> & FunctionTypedBackendOverlay;
 type RawIAPConfig = z.infer<typeof iapConfigSchema>;
 type RawIAPConfigInput = z.input<typeof iapConfigSchema>;
-type IAPConfig = Omit<RawIAPConfig, 'backend'> & {
-    backend: BackendConfig;
+/**
+ * Replace the schema's `unknown` typing for the entitlement mapper with its
+ * real contract, the same way {@link BackendConfig} does for its functions.
+ *
+ * Generic over the consumer's entitlement shape. `LocallyVerifiedPurchase`
+ * carries what a mapper needs to decide: the product, the expiry, the
+ * binding, and how strongly the purchase was checked.
+ */
+type VerificationConfig<TEntitlement extends EntitlementBase = EntitlementBase> = Omit<z.infer<typeof verificationConfigSchema>, 'entitlements' | 'appUserId'> & {
+    entitlements: (purchase: LocallyVerifiedPurchase) => TEntitlement[];
+    /**
+     * The id, or a getter so the binding can follow the session. A getter
+     * returning `null` means "nobody signed in", and refuses rather than
+     * skipping the check.
+     */
+    appUserId?: string | (() => string | null);
 };
-type IAPConfigInput = Omit<RawIAPConfigInput, 'backend'> & {
-    backend: BackendConfigInput;
+type IAPConfig<TEntitlement extends EntitlementBase = EntitlementBase> = Omit<RawIAPConfig, 'backend' | 'verification'> & {
+    backend?: BackendConfig;
+    verification?: VerificationConfig<TEntitlement>;
+};
+type IAPConfigInput<TEntitlement extends EntitlementBase = EntitlementBase> = Omit<RawIAPConfigInput, 'backend' | 'verification'> & {
+    backend?: BackendConfigInput;
+    verification?: VerificationConfig<TEntitlement>;
 };
 type StorageConfig = z.infer<typeof storageConfigSchema>;
 type OptionsConfig = z.infer<typeof optionsConfigSchema>;
 
-declare const entitlementBaseSchema: z.ZodObject<{
-    key: z.ZodString;
-    productId: z.ZodString;
-    expiresAt: z.ZodNullable<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    key: string;
-    productId: string;
-    expiresAt: string | null;
-}, {
-    key: string;
-    productId: string;
-    expiresAt: string | null;
-}>;
-/**
- * Minimum shape every entitlement returned by the backend must satisfy.
- * Consumer-defined fields pass through unvalidated unless the consumer
- * supplies their own schema via `config.backend.entitlementSchema`.
- */
-type EntitlementBase = z.infer<typeof entitlementBaseSchema>;
-/** Default shape used when no `TEntitlement` type parameter is given. */
-type DefaultEntitlement = EntitlementBase;
-
 declare const IAPErrorCode: {
     readonly INVALID_CONFIG: "INVALID_CONFIG";
     readonly NOT_INITIALIZED: "NOT_INITIALIZED";
@@ -713,8 +1278,9 @@ declare const IAPErrorCode: {
     readonly STORAGE_ERROR: "STORAGE_ERROR";
     /**
      * 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.
      */
     readonly INVALID_APP_USER_ID: "INVALID_APP_USER_ID";
     /**
@@ -747,126 +1313,45 @@ declare class IAPError extends Error {
 }
 declare function isIAPError(error: unknown): error is IAPError;
 
-type ProductType = 'subscription' | 'product' | 'consumable';
-interface ConfiguredProduct {
-    id: string;
-    type: ProductType;
-    /**
-     * Required for Android subscriptions — the base plan identifier configured in
-     * Google Play Console. Ignored on iOS and for non-subscription products.
-     */
-    androidPlanId?: string;
-}
-/**
- * Native product info merged with configured metadata.
- * Library-public shape — kept stable across Capacitor versions.
- */
-interface Product {
-    id: string;
-    type: ProductType;
-    title: string;
-    description: string;
-    /** Localized price string, e.g. "$4.99". Always render this — never hardcode. */
-    priceString: string;
-    /** BigInt as string to avoid precision loss, e.g. "4990000". */
-    priceMicros: string;
-    /** ISO 4217 code, e.g. "USD". */
-    currency: string;
-}
-
-/** Platform a transaction originated from. */
-type Platform = 'apple' | 'google';
 /**
- * Normalized native transaction handed to core flows.
- * Plugin-version differences are translated by the adapter so this shape
- * stays stable across Capacitor majors.
+ * The **store's** view of a purchase, as reported by StoreKit or Play
+ * Billing — distinct from {@link VerifiedTransaction}, which is your
+ * backend's view after Attesto validated the receipt.
+ *
+ * Both appear on a successful purchase because they answer different
+ * questions. The backend's `transaction.id` identifies the receipt *it*
+ * recorded; `purchaseReference` identifies the purchase as the store sees
+ * it, which is what survives renewals and reinstalls.
  */
-interface NativeTransaction {
+interface StorePurchase {
     platform: Platform;
     productId: string;
     /**
-     * Apple: the StoreKit `transactionId` (numeric string).
-     * Google: the `purchaseToken` from Play Billing.
+     * The store's stable reference to this purchase: Apple's
+     * `originalTransactionId`, Google's `purchaseToken`. Unchanged across
+     * renewals, so this is what to persist if you need to recognise the
+     * subscription later — re-deriving a server-side token from it months
+     * after the purchase, for instance.
+     *
+     * Recoverable after a reinstall via `restorePurchases()`, which is the
+     * only route once the install that made the purchase is gone.
+     *
+     * Treat it as a receipt: useful for correlation, not something to leak.
      */
-    token: string;
-    /** Google only — required by Attesto's `/v1/google/verify`. */
-    packageName?: string;
-    /** Product type the transaction was originally purchased as. */
-    productType: ProductType;
-    /** Optional pass-through of plugin-native fields for backend hints. */
-    raw?: unknown;
-}
-/**
- * Verified transaction returned by the consumer backend after Attesto check.
- * Generic over the backend-defined transaction shape.
- */
-interface VerifiedTransaction<TExtra = Record<string, unknown>> {
-    id: string;
-    productId: string;
-    expiresAt: string | null;
-    verifiedAt: string;
-    raw?: TExtra;
-}
-
-/**
- * Map of event name → payload. Used by the typed event emitter so consumer
- * subscriptions are statically checked.
- */
-interface EventMap<TEntitlement extends EntitlementBase = EntitlementBase> {
-    ready: undefined;
-    'purchase-started': {
-        productId: string;
-    };
-    'purchase-success': {
-        productId: string;
-        transaction: VerifiedTransaction;
-    };
-    'purchase-cancelled': {
-        productId: string;
-    };
-    'purchase-pending': {
-        productId: string;
-    };
-    'purchase-failed': {
-        productId: string;
-        error: IAPError;
-    };
-    'verification-failed': {
-        productId: string;
-        error: IAPError;
-    };
-    'restore-started': undefined;
-    'restore-completed': {
-        restored: number;
-        entitlements: TEntitlement[];
-    };
-    'entitlements-changed': {
-        entitlements: TEntitlement[];
-        previous: TEntitlement[];
-    };
+    purchaseReference: string;
     /**
-     * Recovery classified an `unfinished_transactions` entry as permanently
-     * invalid (per `options.permanentErrorCodes`) and removed it from
-     * storage. Will not be retried on subsequent launches. Useful for ops
-     * logging / alerting on stuck-loop self-heal events.
-     *
-     * **Token is unmasked.** Receipt tokens (Apple `transactionId` /
-     * Google `purchaseToken`) are useful for correlation in debugging
-     * but are receipts you don't want to leak — treat as sensitive. Mask
-     * before forwarding to external analytics / logging services. iap's
-     * own internal logs use a masked form (see `lib/redact.ts`).
+     * The binding this purchase was made with — the value passed as
+     * `purchase({ appUserId })`, read back off the transaction. `null` when
+     * the purchase carried none. iap never generates one.
      */
-    'recovery-dropped-permanent': {
-        productId: string;
-        token: string;
-        error: string;
-        message?: string;
-    };
+    appUserId: string | null;
+    /**
+     * Renewal detail for a subscription, or `null` when the store reported
+     * none — which is always the case on Android. See
+     * {@link SubscriptionRenewal}.
+     */
+    subscription: SubscriptionRenewal | null;
 }
-type EventName<TEntitlement extends EntitlementBase = EntitlementBase> = keyof EventMap<TEntitlement>;
-type EventPayload<K extends EventName<TEntitlement>, TEntitlement extends EntitlementBase = EntitlementBase> = EventMap<TEntitlement>[K];
-type Unsubscribe = () => void;
-
 /**
  * Convenience context the library passes to a function-form
  * {@link AppUserId} fetcher. `authHeaders` is the result of awaiting
@@ -886,7 +1371,7 @@ interface AppUserIdFetcherContext {
     authHeaders: Record<string, string>;
 }
 /**
- * Value supplied to `iap.purchase({ appUserId })`. Either a UUID v4
+ * Value supplied to `iap.purchase({ appUserId })`. Either a UUID
  * string the caller already has (e.g. from local cache / app state) or
  * an async fetcher the library invokes once per purchase to retrieve
  * the UUID from the caller's backend (typical pattern: backend mints +
@@ -902,10 +1387,12 @@ interface AppUserIdFetcherContext {
  *   requests can be reused without redefining a helper. See
  *   {@link AppUserIdFetcherContext}.
  *
- * Either form is validated as UUID v4 before being forwarded to
- * StoreKit's `appAccountToken` (iOS) / Play Billing's
- * `obfuscatedAccountId` (Android). Non-UUID values throw
- * `IAPError(INVALID_APP_USER_ID)`. A throwing/rejecting fetcher
+ * Either form is validated as an RFC 9562 UUID — **any version**, so a
+ * deterministic UUIDv5 over a stable name works as well as a random v4 —
+ * before being forwarded to StoreKit's `appAccountToken` (iOS) / Play
+ * Billing's `obfuscatedAccountId` (Android). Non-UUID values throw
+ * `IAPError(INVALID_APP_USER_ID)`, as do the nil and max UUIDs, which
+ * carry no identity. A throwing/rejecting fetcher
  * surfaces as `IAPError(APP_USER_ID_FETCH_FAILED, cause: <original>)`.
  */
 type AppUserId = string | (() => Promise<string>) | ((ctx: AppUserIdFetcherContext) => Promise<string>);
@@ -928,7 +1415,10 @@ interface PurchaseOptions {
 type PurchaseResult<TEntitlement extends EntitlementBase = EntitlementBase> = {
     status: 'success';
     productId: string;
+    /** Your backend's view of the receipt, after Attesto validated it. */
     transaction: VerifiedTransaction;
+    /** The store's own view of the purchase. See {@link StorePurchase}. */
+    purchase: StorePurchase;
     entitlements: TEntitlement[];
 } | {
     status: 'cancelled';
@@ -948,7 +1438,114 @@ type PurchaseResult<TEntitlement extends EntitlementBase = EntitlementBase> = {
 interface RestoreResult<TEntitlement extends EntitlementBase = EntitlementBase> {
     restored: number;
     entitlements: TEntitlement[];
+    /**
+     * The store's view of every transaction the account currently owns — one
+     * entry per transaction submitted, in the order the store reported them.
+     * Empty when the store reports nothing owned.
+     *
+     * This is the route to a {@link StorePurchase.purchaseReference} after a
+     * reinstall or on a new device, where the install that made the purchase
+     * no longer exists to have kept it.
+     */
+    purchases: StorePurchase[];
+}
+
+/**
+ * Map of event name → payload. Used by the typed event emitter so consumer
+ * subscriptions are statically checked.
+ */
+interface EventMap<TEntitlement extends EntitlementBase = EntitlementBase> {
+    ready: undefined;
+    'purchase-started': {
+        productId: string;
+    };
+    'purchase-success': {
+        productId: string;
+        transaction: VerifiedTransaction;
+    };
+    'purchase-cancelled': {
+        productId: string;
+    };
+    'purchase-pending': {
+        productId: string;
+    };
+    /**
+     * A purchase previously reported as `purchase-pending` has resolved.
+     *
+     * `purchased` means it cleared and the entitlement is in place (the
+     * transaction has been verified and acknowledged by the time this fires).
+     * `cancelled` means the store no longer has it, either waiting or owned —
+     * the payment failed, expired, or the user abandoned it.
+     *
+     * **`cancelled` only fires where the platform can distinguish "gone" from
+     * "still waiting"** — Android, via Play's purchase state. On iOS a
+     * deferred purchase that is never approved produces no signal at all, so
+     * iap says nothing rather than guessing; the pending mark simply stays
+     * until a transaction arrives.
+     *
+     * Fires at most once per pending purchase. Use it to clear
+     * pending-state copy a paywall put up on `purchase-pending`.
+     */
+    'purchase-pending-resolved': {
+        productId: string;
+        status: 'purchased' | 'cancelled';
+    };
+    /**
+     * A transaction arrived outside a `purchase()` call — a renewal, a refund
+     * or revocation, an Ask-to-Buy approval, a pending purchase clearing.
+     *
+     * Fires before iap has verified it, so treat the payload as "the store
+     * says something happened", not as an entitlement change. The
+     * authoritative signal is `entitlements-changed`, which follows if the
+     * backend confirms it.
+     *
+     * iOS only in practice: the native layer feeds this from Apple's
+     * `Transaction.updates` and has no Android equivalent, where the same
+     * ground is covered by reconciliation at launch and on resume.
+     */
+    'transaction-updated': {
+        productId: string;
+        purchase: StorePurchase;
+    };
+    'purchase-failed': {
+        productId: string;
+        error: IAPError;
+    };
+    'verification-failed': {
+        productId: string;
+        error: IAPError;
+    };
+    'restore-started': undefined;
+    'restore-completed': {
+        restored: number;
+        entitlements: TEntitlement[];
+    };
+    'entitlements-changed': {
+        entitlements: TEntitlement[];
+        previous: TEntitlement[];
+    };
+    /**
+     * Recovery classified an `unfinished_transactions` entry as permanently
+     * invalid (per `options.permanentErrorCodes`) and removed it from
+     * storage. Will not be retried on subsequent launches. Useful for ops
+     * logging / alerting on stuck-loop self-heal events.
+     *
+     * **Token is unmasked.** Receipt tokens (Apple `transactionId` /
+     * Google `purchaseToken`) are useful for correlation in debugging
+     * but are receipts you don't want to leak — treat as sensitive. Mask
+     * before forwarding to external analytics / logging services. iap's
+     * own internal logs use a masked form (see `lib/redact.ts`).
+     */
+    'recovery-dropped-permanent': {
+        productId: string;
+        token: string;
+        error: string;
+        message?: string;
+    };
 }
+type EventName<TEntitlement extends EntitlementBase = EntitlementBase> = keyof EventMap<TEntitlement>;
+type EventPayload<K extends EventName<TEntitlement>, TEntitlement extends EntitlementBase = EntitlementBase> = EventMap<TEntitlement>[K];
+type Unsubscribe = () => void;
 
 /**
  * The user's App Store / Google Play storefront — i.e. the country their
@@ -1020,8 +1617,9 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
      * can render the right UI without try/catch gymnastics.
      *
      * `opts.appUserId` is optional. When provided (string or async fetcher
-     * returning a string), the resolved value is validated as a UUID v4
-     * and forwarded to StoreKit's `appAccountToken` (iOS) / Play
+     * returning a string), the resolved value is validated as an RFC 9562
+     * UUID of any version and forwarded to StoreKit's `appAccountToken`
+     * (iOS) / Play
      * Billing's `obfuscatedAccountId` (Android) — making it available on
      * Attesto's verify response and outbound webhook payload as
      * `appUserId` so backends can join on user identity directly. See
@@ -1082,14 +1680,64 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
      * signed storefront from your backend instead.
      */
     getStorefront(): Promise<Storefront | null>;
+    /**
+     * Whether an **active** entitlement with this key is held.
+     *
+     * Active means its `expiresAt` has not passed by the device clock, plus
+     * any `options.entitlementGraceMs`. An entitlement is never dropped
+     * because a refresh failed or the cache is old — only the store's own
+     * deadline, or an authoritative negative, takes one away.
+     */
     hasEntitlement(key: string): boolean;
-    /** Returns a defensive shallow copy. Each entitlement is frozen. */
+    /**
+     * The active entitlements, as a defensive shallow copy. Each is frozen.
+     * Expired ones are omitted — see {@link IAP.hasEntitlement}.
+     */
     getEntitlements(): TEntitlement[];
-    /** Returns a frozen entitlement reference, or null if missing. */
+    /** A frozen active entitlement, or null if missing or expired. */
     getEntitlement(key: string): TEntitlement | null;
+    /**
+     * When the entitlements were last confirmed by the verification source —
+     * your backend, or the device in local mode. ISO 8601, or `null` if they
+     * have never been confirmed on this install.
+     *
+     * Exposed so an app can decide for itself how much staleness it will
+     * tolerate. iap deliberately does not revoke on staleness: a cached
+     * entitlement stands until it expires, because a network error must never
+     * cost a paying user their access.
+     */
+    getEntitlementsVerifiedAt(): string | null;
+    /**
+     * Erase everything iap has stored on this device: the entitlement cache,
+     * the unfinished-transaction queue, and any pending-purchase marks.
+     *
+     * For a "delete everything" control. `destroy()` deliberately leaves the
+     * cache in place (a new instance should see the user's entitlements
+     * immediately); this is the opposite, and does not tear the instance down —
+     * the instance stays usable and a `refresh()` will repopulate from the
+     * verification source.
+     *
+     * Best-effort on storage: a failure to clear one key is logged and the
+     * rest is still cleared. Emits `entitlements-changed` with an empty list,
+     * so a reactive UI follows.
+     *
+     * Throws `ALREADY_IN_PROGRESS` if a `purchase()` is in flight. That
+     * purchase would re-populate the state and re-persist the cache moments
+     * after the wipe, and leave its unfinished entry behind, so the erase
+     * would look like it had silently failed. Await the purchase, then reset.
+     *
+     * A no-op after `destroy()`, rather than an error: a teardown racing a
+     * "delete my data" tap is a real sequence, not a programming mistake.
+     *
+     * It does **not** revoke the purchase. The store still owns it, and a
+     * restore will bring the entitlement back — which is correct: the user
+     * paid.
+     */
+    reset(): Promise<void>;
     on<K extends EventName<TEntitlement>>(event: K, handler: (payload: EventPayload<K, TEntitlement>) => void): Unsubscribe;
 }
-declare function createIAP<TEntitlement extends EntitlementBase = EntitlementBase>(input: IAPConfigInput): IAP<TEntitlement>;
+
+declare function createIAP<TEntitlement extends EntitlementBase = EntitlementBase>(input: IAPConfigInput<TEntitlement>): IAP<TEntitlement>;
 
 interface VerifyAppleRequest {
     productId: string;
@@ -1143,6 +1791,20 @@ type VerifyResponse<TEntitlement extends EntitlementBase = EntitlementBase> = {
 type RestoreResponse<TEntitlement extends EntitlementBase = EntitlementBase> = {
     valid: true;
     entitlements: TEntitlement[];
+    /**
+     * Optional: the tokens that were actually verified, when the
+     * adapter judged them individually.
+     *
+     * When present, only these are acknowledged. It exists because a
+     * single consolidated `valid: true` cannot say *which* of the
+     * submitted transactions passed — and acknowledging one that did
+     * not finalises a purchase the adapter just refused, waiving
+     * Play's refund window for it.
+     *
+     * A backend that validates the batch as a whole omits it, and
+     * every submitted transaction is acknowledged as before.
+     */
+    verifiedTokens?: string[];
 } | {
     valid: false;
     error: string;
@@ -1186,6 +1848,32 @@ interface BackendAdapter<TEntitlement extends EntitlementBase = EntitlementBase>
      * not a registration.
      */
     listProducts?(): Promise<ConfiguredProduct[]>;
+    /**
+     * Optional: verify a transaction **without** extracting it into the HTTP
+     * request shapes.
+     *
+     * `VerifyAppleRequest` and `VerifyGoogleRequest` carry what a server needs
+     * to look a receipt up — a product id and a token. An on-device check
+     * needs more than that: the binding, the subscription state, the expiry.
+     * Rather than widen the HTTP contract (and so change what gets sent over
+     * the wire), an adapter that can answer from the transaction itself
+     * implements this, and the router prefers it.
+     *
+     * Implemented by the built-in local-verification adapter. The HTTP path
+     * does not implement it and is unaffected.
+     */
+    verifyNative?(transaction: NativeTransaction): Promise<VerifyResponse<TEntitlement>>;
+    /**
+     * Optional counterpart to {@link verifyNative} for restore: the owned
+     * transactions, unextracted.
+     *
+     * Avoids two problems for an adapter that answers from the transaction.
+     * It needs the fields `RestoreRequestTransaction` drops; and building
+     * that request requires a `packageName` on every Google transaction,
+     * which such an adapter never reads — so a request it would discard
+     * could fail the restore outright.
+     */
+    restoreNative?(owned: NativeTransaction[]): Promise<RestoreResponse<TEntitlement>>;
 }
 
 /**
@@ -1270,4 +1958,4 @@ declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = Entitlem
     listProducts(): Promise<ConfiguredProduct[]>;
 }
 
-export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Storefront, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };
+export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LocalVerification, type LocalVerificationError, type LocalVerificationOptions, type LocallyVerifiedPurchase, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseAssurance, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type StorePurchase, type Storefront, type SubscriptionOffer, type SubscriptionOfferPayment, type SubscriptionOfferType, type SubscriptionRenewal, type SubscriptionState, type Unsubscribe, VERSION, type VerificationConfig, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isExpired, isIAPError, verifyPurchaseOnDevice };