@nosslabs/iap 8.0.0 → 8.2.0

package/CHANGELOG.md

@@ -3,7 +3,539 @@
 All notable changes to `@nosslabs/iap` will be documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [8.2.0] — 2026-10-27
+
+### Changed
+
+- **`@capacitor/preferences` is now an optional peer, loaded only when it is used.** It was a
+  required peer reached through a *static* import, so it ended up in the bundle's top-level
+  imports and every consumer shipped the native plugin — including one passing
+  `storage.type: 'custom'` with its own storage, which never calls Preferences at all.
+
+  `PreferencesAdapter` now reaches the plugin through `await import()`, memoised per instance,
+  the way the resume listener reaches `@capacitor/app`. Neither `dist/index.js` nor
+  `dist/index.cjs` names it at the top level any more, asserted on the built artifact by a new
+  `npm run verify:bundle` step in CI and before publish — a static import behaves identically
+  at runtime and differs only in what the bundler hoists, so no unit test can see it.
+
+  Choosing `storage.type: 'preferences'` (still the default) without the plugin installed now
+  fails at `initialize()` with `INVALID_CONFIG`, naming what to install and the two
+  alternatives that need no plugin. It is reported there, via the new optional
+  `StorageAdapter.ensureAvailable()`, rather than at the first cache read: that read treats any
+  failure as "nothing cached", so a missing plugin would have looked like a cold start while
+  iap silently persisted nothing.
+
+  **If you use `storage.type: 'preferences'`, keep the plugin installed** — but check it is in
+  your *own* `dependencies`. npm 7+ installs a required peer into the tree without listing it
+  in your `package.json`; now that it is optional, a fresh install or a regenerated lockfile
+  can drop it, and `npx cap sync` with it.
+
+  If you pass your own adapter or use `'memory'`, you can uninstall it — and then you must
+  **externalise it in your bundler**, because a dynamic `import()` is still resolved at build
+  time: without it Vite/Rollup fails with `failed to resolve import "@capacitor/preferences"`.
+  The installation guide has the one-line config. (This is not new to this release — the
+  optional `@capacitor/app` has always behaved the same way — but it is now worth stating.)
+
+- **Developed and tested against `@capgo/native-purchases@8.9.6`** (was `8.6.5`). The peer
+  range is unchanged at `^8.2.0`. Nothing in iap broke, and two of the plugin's documented
+  gaps closed — both caught by the inverted contract guards rather than by reading release
+  notes:
+
+  - **Purchase tokens no longer reach logcat.** Through `8.6.5` the Android plugin logged them
+    in the clear with no debug gate, which [the native-layer
+    page](https://iap.nossdev.com/guide/native-layer) warned about. Every Android log now goes
+    through a `NativePurchasesLog` wrapper gated on `BuildConfig.DEBUG` or an explicit
+    `debugLogging` config, and the purchase summary it emits carries no token. Verified by
+    asserting that no `android.util.Log` call survives outside the wrapper, so a regression
+    fails CI; the warning is off the page.
+  - **`purchaseProduct()` accepts an `offerToken`.** Choosing a specific offer within a base
+    plan is now possible at the native layer. iap does not forward one yet — `purchase()` has
+    no way to name an offer — so this is recorded as a feature to build rather than a gap to
+    live with.
+
+  The plugin also moved to **Play Billing Library 9.1.0** (from 8.3.0), a native major. It
+  changes nothing iap relies on, and that was checked against the 9.1.0 artifact rather than
+  assumed: `Purchase.PurchaseState` still reads `UNSPECIFIED_STATE = 0, PURCHASED = 1,
+  PENDING = 2`, and `consumeAsync`, `acknowledgePurchase` and `queryPurchasesAsync` keep their
+  signatures — the three facts the Android purchase-state check and the consumable path are
+  built on.
+
+## [8.1.0] — 2026-10-27
+
+### Changed
+
+- **`peerDependencies` now require `@capgo/native-purchases` `^8.2.0`**, up from `^8.0.0`.
+  `consumePurchase()` landed in 8.2.0, and the consumable path above needs it: on 8.0.x/8.1.x
+  the call would reject at the bridge and be retried forever rather than degrading.
+
+### Added
+
+- **Local verification — iap works with no backend at all.** `verification: { mode: 'local',
+  entitlements }` replaces the `backend` block and verifies purchases on the device. Exactly
+  one of the two is required; both is a config error.
+
+  Implemented as a `BackendAdapter`, which is the whole design: everything above that boundary
+  is **untouched**. The purchase flow, the acknowledge-only-after-verification ordering, the
+  at-least-once write before verifying, and the unfinished-transaction recovery all behave
+  identically and do not know which mode they are in. There is no second purchase path to keep
+  in step, and a purchase whose local check fails is never acknowledged — so the store keeps it
+  and recovery retries, which on Android is what prevents the 3-day auto-refund.
+
+  `refresh()` and `restorePurchases()` both ask the store what it owns, so they keep working
+  with no network.
+
+  **Be clear about the strength.** Every verified purchase carries an `assurance`:
+  `store-signed` on iOS, where StoreKit verified Apple's signature in native code before the
+  transaction reached the WebView, and `store-reported` on Android, where **no cryptographic
+  check is possible** — the native layer exposes neither Play's purchase signature nor the JSON
+  it is computed over, so the answer is the store's word. Neither resists a lying device.
+  Local mode is for an app whose alternative is no verification at all; it is not a substitute
+  for a server where being wrong is expensive.
+
+  The checks are exported as `verifyPurchaseOnDevice` for consumers who would rather write
+  their own adapter around them.
+
+- **Offline semantics, written down as guarantees** — [Offline and no-backend
+  use](https://iap.nossdev.com/guide/offline-and-no-backend). Most of this was already the
+  behaviour; it was never stated, so it could not be relied on.
+
+- **`options.entitlementGraceMs`** — extra time past `expiresAt` during which an entitlement
+  still counts. Defaults to `0`. Set it because a renewal is not instantaneous: a subscription
+  renewing at midnight may not have a fresh receipt for hours, and locking a paying user out in
+  that window is the worse error. On Android store-side grace and billing retry are
+  server-side only, so a backendless app cannot see them and this is its only cushion.
+
+- **`iap.getEntitlementsVerifiedAt()`** — when the entitlements were last confirmed, ISO 8601
+  or `null`. iap deliberately does not revoke on staleness, so this is for an app that wants to
+  be stricter than iap is.
+
+- **`iap.reset()`** — erase the entitlement cache, the unfinished-transaction queue and the
+  pending-purchase marks. For a "delete everything" control. Not `destroy()`, which keeps the
+  cache so the next instance reads it immediately; and not a revocation — the store still owns
+  the purchase, and a restore brings the entitlement back, which is correct because the user
+  paid.
+
+  Every key comes from one registry, so a store added in a later version cannot quietly survive
+  a wipe, and each is removed **by name** as well as through its store — the Preferences adapter
+  can only clear keys it has seen this session, so clearing the namespace alone is a no-op on a
+  fresh launch.
+
+  It throws `ALREADY_IN_PROGRESS` (as `recoverable`) while a `purchase()` is in flight: that
+  purchase's unfinished-transaction record is written before verification precisely so it
+  survives a crash, and deleting it mid-flight would leave a purchase neither acknowledged nor
+  tracked — which Google auto-refunds after three days. Await the purchase, then reset. After
+  `destroy()` it still wipes and does not throw; that is the safest moment, since no
+  orchestrator is left to re-persist.
+
+- **`verification.appUserId` accepts a getter**, `string | (() => string | null)`, read at the
+  time of each check so the binding follows the session. A fixed string is captured at
+  `createIAP()` time, so in a multi-user app it is the previous user's after a login change and
+  every purchase made afterwards is refused as a mismatch, with no recovery short of rebuilding
+  the instance.
+
+  A getter returning `null` means "nobody is signed in", which is **not** the same as using no
+  binding: purchases and restores are refused (`BINDING_UNAVAILABLE`) rather than falling back
+  to an unguarded check, since the alternative is accepting a purchase bound to someone else. A
+  refresh in that state keeps the current entitlements instead of revoking them — a multi-user
+  app restores its session asynchronously, and "I cannot tell you" must never read as "you own
+  nothing".
+
+- **Android consumables are consumed, not just acknowledged, so they can be bought again.**
+  Play treats acknowledging and consuming as different things, and only consuming releases
+  ownership. A consumable that cleared out of band — a restore, or launch recovery — was
+  acknowledged and then stayed owned forever, so `purchase()` of it failed `ALREADY_PURCHASED`
+  permanently. With a backend the entitlement was unaffected and only the product was
+  unbuyable; in local mode a mapper that granted something for a consumable kept granting it
+  on every refresh, since the purchase never left the store's owned set.
+
+  Three parts. `NativeAdapter` gains an optional **`consume(transaction)`** (capgo's
+  `consumePurchase()`); a custom adapter without it falls back to acknowledging and logs that
+  the product will stay owned. All four settle paths now go through one `finalizeTransaction`
+  step that decides acknowledge-vs-consume. And a store-reported transaction is typed from
+  **your configured catalog**, because Play reports a consumable and a one-time purchase both
+  as `'inapp'` — the plugin's payload cannot tell them apart. The catalog only *refines* the
+  store's answer: it can turn `'inapp'` into `'consumable'`, and never contradicts a `'subs'`,
+  so one wrong `type` in a config or a stale `backend.listProducts()` manifest cannot strip a
+  subscription's expiry and have it granted forever.
+
+  iap also no longer passes the plugin's `isConsumable` flag. The plugin consumes on that flag
+  inside the purchase callback **regardless of `autoAcknowledgePurchases`**, which contradicts
+  that option's own documentation and would have finalised a purchase before iap verified it —
+  unrecoverably, since Billing 8.x drops a consumed purchase from `getPurchases()`. Found by
+  reading the plugin's Java rather than its docs, and now guarded by a test so that if capgo
+  closes the gap iap can stop working around it.
+
+  Two things to know if you sell consumables. A consumed purchase leaves `getPurchases()` for
+  good in Billing 8, so **in local mode an entitlement derived from a consumable now
+  disappears at the next refresh** — which is what `LocallyVerifiedPurchase.productType` has
+  always warned about, but it used to be masked. Keep a consumable's effect in your own
+  records, not in a standing entitlement. And `restorePurchases()` now clears a pending mark
+  it settles, which it never did: harmless while a purchase stayed owned for the next
+  reconcile to find, but a consumed one is gone, and the reconcile would otherwise have
+  reported a succeeded purchase as `cancelled`.
+
+- **`LocalVerificationError` gains `BINDING_UNAVAILABLE`.** Additive, but it widens a public
+  union, so an exhaustive `switch` over it will need the new arm.
+
+- **`BackendAdapter.verifyNative`**, optional. An adapter that can answer from the whole
+  transaction gets it whole, rather than the extracted `{ productId, token, type }` the HTTP
+  contract sends — an on-device check needs the binding, the subscription state and the expiry,
+  none of which survive that extraction. The HTTP adapter does not implement it, so nothing
+  about what goes over the wire changes.
+
+### Changed
+
+- **In local mode, `hasEntitlement()`, `getEntitlement()` and `getEntitlements()` return only
+  *active* entitlements** — ones whose `expiresAt` has not passed by the device clock, plus any
+  `entitlementGraceMs`. With no backend to re-ask, the deadline is the only thing that can
+  revoke anything, so enforcing it locally is the point.
+
+  **With a backend they do not filter**, deliberately: the backend is the authority on what is
+  granted, and it may return an entitlement whose `expiresAt` has passed on purpose — that is
+  what a store-side grace period or billing retry looks like. Second-guessing it against the
+  device clock would have iap perform a downgrade the backend did not ask for, and a device
+  with a fast clock would lock out a paying user even with the backend reachable. So this is
+  **not** a behaviour change for existing backend-mode consumers.
+
+  In neither mode is an entitlement dropped because a refresh failed or the cache is old.
+
+- **`backend` is now optional in `IAPConfig`**, since `verification` can take its place. Code
+  that reads `config.backend` needs a null check; code that passes one is unaffected.
+
+- **Introductory and promotional offers on `getProducts()`.** Each subscription now carries
+  `introductoryOffer` and `promotionalOffers` as typed `SubscriptionOffer`s — offer type,
+  payment mode (`free-trial` / `pay-up-front` / `pay-as-you-go`), the store's own localized
+  price string plus micros, the period as an ISO 8601 duration, and the cycle count. Build
+  paywall copy from these rather than hardcoding a price. `subscriptionPeriod`,
+  `subscriptionGroupId`, `androidOfferToken` and `androidOfferId` come along too.
+
+  **Eligibility is not among them, and cannot be.** The native layer exposes no eligibility
+  query on either platform, so an offer being present means "this product has one", not
+  "this user will get it" — the store's purchase sheet decides at purchase time. Write copy
+  that reads correctly either way, or confirm server-side.
+
+- **Transactions that happen outside a purchase now reach the consumer.** iap subscribes to
+  Apple's `Transaction.updates` from `initialize()`, so a renewal, a refund or revocation, an
+  Ask-to-Buy approval, or a pending purchase clearing is verified, acknowledged and reflected
+  in entitlements while the app is running — previously none of that surfaced until the next
+  launch. Two new events: `transaction-updated` (the store says something happened, before
+  verification) and the authoritative `entitlements-changed` that follows.
+
+  **iOS only, because that is the only feed that exists**: the native layer has no Android
+  equivalent. On Android the same ground is covered by reconciliation at launch and on resume,
+  which is what the previous behaviour already relied on for both platforms.
+
+  An arriving transaction goes through the same path recovery uses — persisted before
+  verification, acknowledged only after the backend confirms — rather than a second settlement
+  path that could drift from it. One that arrives while `purchase()` is handling the same
+  product is left to the purchase flow, since StoreKit delivers it to both and settling twice
+  would verify twice, acknowledge twice and emit a spurious change.
+
+- **`purchase-pending-resolved` — pending purchases now close out.** `purchase-pending` had no
+  counterpart, so a paywall that put up "waiting for payment" had nothing to take it back down
+  with. The new event reports `purchased` (cleared, and the entitlement is already in place) or
+  `cancelled`, at most once per pending purchase.
+
+  Pending purchases are remembered across launches, because that is when they resolve — a Play
+  e-wallet payment can take hours with the app closed. The mark is checked at `initialize()`
+  and on every resume, so the event can arrive in a much later session than the purchase.
+
+  **`cancelled` is Android-only, deliberately.** It fires only where the platform can tell
+  "gone" from "still waiting" — 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 and clearing a
+  paywall's pending copy while a parent is still deciding. A mark iap cannot resolve is dropped
+  after 30 days, silently and with no event: by then it is iap's unanswered question rather
+  than a purchase in progress, and keeping it would make every foreground re-query the store
+  for the life of the install.
+
+  Known limitation, documented rather than half-fixed: a **consumable** that clears out of band
+  is acknowledged but not *consumed*, so Play keeps reporting it owned and it cannot be
+  rebought. Entitlement is unaffected. Closing it needs a consume path in the native adapter.
+
+- **`appUserId` accepts any RFC 9562 UUID, not only v4.** A deterministic identifier is often
+  the better choice: a UUIDv5 over a stable name gives the same binding on every device with
+  nothing to persist or keep in step, and v7 is the current recommendation for time-ordered
+  ids. Restricting to v4 forced consumers who already had a deterministic identity to mint a
+  second one.
+
+  Still refused: anything that is not a canonical UUID, non-RFC variant nibbles (which Apple
+  rejects anyway), and the nil and max UUIDs — both are valid RFC 9562 constructs that
+  deliberately carry no identity, so accepting one would bind a purchase to nothing while
+  looking well-formed.
+
+- **`StorePurchase`, on `purchase()` and `restorePurchases()` — the store's own view of a
+  purchase.** `result.purchase` on a successful purchase, and `result.purchases` on a restore.
+  It carries `purchaseReference`, `appUserId` and `subscription`, which is what makes the
+  three fields below reachable: `purchase()` hands back a `VerifiedTransaction` (your
+  backend's view of the receipt) and `NativeTransaction` is internal, so without this the
+  normalized fields would have been computed and never readable by anyone.
+
+  `restorePurchases()` is the route that matters for a reference you need *later*: after a
+  reinstall or on a new device, the install that made the purchase is gone and cannot have
+  kept it.
+
+- **`NativeTransaction.purchaseReference` — the reference that survives renewals.** `token`
+  is the handle for acknowledging *this* transaction, and on Apple it is a different value
+  after every renewal; `purchaseReference` is the identity of the purchase itself, so it is
+  what to store to recognise a subscription later. Google's `purchaseToken` already is one.
+  Apple's `originalTransactionId` is not exposed as a plugin field, so iap reads it from the
+  signed `jwsRepresentation` payload — **for its data, with no signature check**, which is
+  sound only because the native layer resolves a purchase solely for an already-verified
+  StoreKit 2 result. It falls back to `token` when the JWS is absent or unreadable, so it is
+  always set, and a malformed JWS can never fail a purchase.
+
+  It is persisted with the unfinished-transaction entry so recovery keeps it across launches.
+  Entries written before this release carry only a token and still load, falling back to it.
+
+- **`NativeTransaction.subscription` — typed renewal detail.** `state` (including
+  `in-grace-period` and `in-billing-retry`), `autoRenewing`, `renewsAt`, `renewalProductId`
+  and `expiresAt`, previously reachable only untyped on `raw`. iap passes these through and
+  does not interpret them — no subscription state machine (PLAN.md §14).
+
+  `null` on Android, where the plugin exposes no state, no renewal date and no auto-renew
+  flag: a renewal object full of nulls would be worse than none, and `null` correctly says
+  "ask the server".
+
+- **`NativeTransaction.appUserId`** — the binding a purchase was made with, read back off the
+  transaction (`appAccountToken` / `obfuscatedAccountId`), so a consumer can check what a
+  purchase is bound to.
+
+- **`Product.androidBasePlanId`** — the base plan an Android entry describes, reported
+  separately now that `Product.id` is always the product id you configured. `null` on iOS.
+
+- New exported types: `StorePurchase`, `SubscriptionOffer`, `SubscriptionOfferType`,
+  `SubscriptionOfferPayment`, `SubscriptionRenewal`, `SubscriptionState`.
+
+### Fixed
+
+- **Free trials were going to be reported as pay-as-you-go.** `@capgo/native-purchases`
+  labels its `paymentMode` integers "SKProductDiscount.PaymentMode-compatible: freeTrial=0,
+  payUpFront=1, payAsYouGo=2", but Apple's actual order is payAsYouGo=0, payUpFront=1,
+  freeTrial=2 — the comment is wrong about Apple, and both of capgo's platforms use capgo's
+  own order. iap maps from the emitted values, with a test pinning the legend so nobody
+  "corrects" it to Apple's — and, because a unit test can only pin iap against iap's own
+  mocks, a second guard reads capgo's shipped Swift and Java so a change *there* fails CI too.
+  Caught before shipping; no released version was affected.
+
+- **Android subscriptions were reported as one-time products, under the wrong id.** capgo sets
+  a product payload's `identifier` to the **base plan** id and `planIdentifier` to the Play
+  **product** id, while iap queries by product id — so the type lookup missed on every Android
+  subscription, fell through to `'product'`, and returned a `Product` whose `id` was a base
+  plan the consumer never configured. `getProducts().find(p => p.id === configuredId)` could
+  not match it. `Product.id` and `type` are now always what you configured, with the base plan
+  reported as `androidBasePlanId`.
+
+  Relatedly, capgo emits **one payload per offer** on a base plan, and only the base-plan entry
+  carries the offers — so `getProducts()` could return several products sharing one id, most
+  with no offers. Those are now collapsed to one per configured product, preferring the base
+  plan named by `androidPlanId` and the entry that actually has the offers. A payload matching
+  no configured product is dropped rather than mistyped.
+
+- **One unreadable entry in the unfinished-transaction store wiped the whole list.** Entries
+  were validated as a single array, so one malformed record failed the parse and cleared every
+  pending recovery with it — abandoning purchases that were paid for and never acknowledged,
+  which on Android Google refunds after three days. Entries are now validated individually:
+  the bad one is dropped and logged, its neighbours survive.
+
+- **`appUserId` never compared equal to what was passed in, on iOS.** StoreKit returns
+  `UUID.uuidString`, which Swift renders uppercase, while `crypto.randomUUID()` and iap's
+  case-insensitive validator both deal in lowercase. The binding is now lower-cased, so
+  `purchase.appUserId === suppliedAppUserId` holds — the one comparison the field exists for.
+
+- **Two lookup tables resolved inherited object properties.** `subscriptionState` and a
+  subscription period's `unitString` arrive as strings off a native bridge and were looked up
+  in plain object literals, so a value of `"constructor"` returned a function rather than
+  missing: `state` could be a function at runtime while typed as a string union, and a period
+  could render as `"P1function Object() { [native code] }"`. Both are `Map`s now. Not
+  reachable from the store's own enums — but both functions are documented as total, and were
+  not.
+
+- **A price the store did not send became the string `"NaN"`.** `priceMicros` is `"0"` for a
+  non-finite price now; `priceString` remains the value to display.
+
+- **The installation guide said `@capgo/native-purchases` is MIT-licensed. It is MPL-2.0.**
+  Corrected on both the `8.x` and the archived `v7` installation pages, which were the first
+  place a consumer would have read it. iap uses the plugin unmodified, so the correction
+  changes no obligation — but the stated licence is now the actual one. The stale
+  `Cap-go/native-purchases` repository links were refreshed to
+  `Cap-go/capacitor-native-purchases` on the same lines.
+
+- **The configuration guide told you to do something that throws.** It said to register one
+  Play subscription product's several base plans as separate `ConfiguredProduct` entries
+  "with the same `id`" — which `createIAP()` rejects with `INVALID_CONFIG: Duplicate product
+  id`. It now describes what actually works: one Play product per cadence, or one entry
+  addressing one base plan via `androidPlanId`.
+
+- **Documented Android limitations that were silently wrong rather than absent.**
+  `promotionalOffers` on Android reports the base plan's *standard recurring* price, not the
+  promotion's — so a free-trial promo arrives as `pay-as-you-go` at full price, and the docs
+  now say not to render those terms there. `periodCount` is usually `0` on Android for any
+  offer, because Play reports `getBillingCycleCount()` as `0` for both non-recurring and
+  infinitely recurring phases. A period is single-component on Android (`P1M15D` → `P1M`).
+
+- **The installation guide said `@capgo/native-purchases` is MIT-licensed. It is MPL-2.0.**
+  Corrected on both the `8.x` and the archived `v7` installation pages, which were the first
+  place a consumer would have read it. iap uses the plugin unmodified, so the correction
+  changes no obligation — but the stated licence is now the actual one. The stale
+  `Cap-go/native-purchases` repository links were refreshed to
+  `Cap-go/capacitor-native-purchases` on the same lines.
+
+### Fixed
+
+- **Android purchases could never verify, and `restorePurchases()` always threw.** Google's
+  verification APIs are keyed on the app's package name, and the native layer does not report
+  it — so `verifyNativeTransaction` and the restore request builder both threw `STORE_ERROR`
+  for *every* Google transaction. Every Android purchase returned `verification_failed` and
+  every restore rejected.
+
+  This predates this release and shipped: it was never caught because every Google test
+  fixture hand-set the `packageName` field the real adapter never sets. Set
+  `config.android.packageName` to your applicationId; `initialize()` warns on Android when it
+  is missing, and the error messages now name the setting.
+
+- **A purchase whose acknowledgement failed stopped being tracked.** `purchase()` removed the
+  unfinished-transaction entry even when `acknowledge()` threw, on the reasoning that "a later
+  restore()/refresh() re-acks it" — but only `restore()` acknowledges, and nothing calls it
+  automatically. So a paid-for purchase was granted, left unacknowledged, and forgotten, right
+  up to Google's silent 3-day auto-refund. The entry is now retained for recovery to retry.
+
+- **Android would have reported every pending purchase as `cancelled` while it was still
+  processing.** The pending-state check looked for Play `purchaseState === '0'`, following the
+  plugin's own type declarations, which document `"0": Payment pending`. That is wrong: Play's
+  `Purchase.PurchaseState` is `UNSPECIFIED_STATE = 0, PURCHASED = 1, PENDING = 2`, and
+  `getPurchaseState()` only ever returns 1 or 2 — so the filter matched nothing and every
+  tracked pending purchase read as vanished. Worse, the marker was then cleared, so when the
+  payment really cleared the `purchased` event never fired either.
+
+  Now expressed as "the store has it but does not call it owned", so `UNSPECIFIED_STATE` and
+  any state Play adds later also read as not-yet-granted. Erring towards "still pending"
+  self-corrects on the next pass; erring towards "cancelled" is permanent. A contract test
+  pins that the plugin still passes Play's own integer through rather than translating it.
+
+- **`purchase-pending-resolved` could fire twice, with two verifies and two acknowledges.**
+  The resolution did a read-then-write across an `await`, and reconciliation had no
+  re-entrancy guard — and both overlaps are reachable: the transaction listener is
+  fire-and-forget, and the resume listener does not debounce, so two foreground events ran two
+  reconciliations. On Android the second acknowledge of an already-acked token errors, which
+  the settle path reads as a failure and retains the entry for. Now a single atomic
+  take-if-present, a single-flight reconciliation, and a per-token settle guard.
+
+- **A pending purchase settled by any other path was later reported `cancelled`.** Only the
+  update orchestrator cleared the marker, so a purchase finished by a `purchase()` retry, by
+  `restore()`, or by launch recovery left it behind — and the next reconcile found it neither
+  owned nor pending and announced that it had failed. Resolution now happens inside the
+  settle path itself, so every route to a settled transaction clears the mark.
+
+- **An out-of-band transaction could never be acknowledged on iOS, and never resolve.** The
+  native layer calls `transaction.finish()` *before* notifying listeners, and its
+  `acknowledgePurchase` then looks the transaction up in `Transaction.all` and rejects
+  "already finished" — which `Transaction.all` guarantees for a finished consumable. That read
+  as a settlement failure. An already-finished acknowledge is now success **on that path
+  only**; a real acknowledge failure on Android is still a failure.
+
+- **Refunds and revocations accumulated in the recovery store forever.** They verify
+  `valid:false` with a code no permanent-error list knows, so they were retained and
+  re-verified at every launch, eating the recovery batch that entries which can still succeed
+  need. A revocation is no longer persisted — there is nothing to recover from.
+
+- **Reconciliation could report `cancelled` for a purchase that had just cleared.** The owned
+  and pending snapshots are two separate native round-trips, and reading owned first meant a
+  purchase that cleared in between appeared in neither. Pending is read first now, so that
+  window resolves to "still pending".
+
+- **A transaction arriving during or after `destroy()` repopulated the torn-down instance**,
+  writing through the shared state closures and the entitlement cache after teardown.
+
+- **`reconcilePending()` ran inside `initialize()`**, so a tracked pending purchase delayed
+  `ready` by a store round-trip plus a backend verify, uncapped. It runs just after `ready`
+  now.
+
+The local-verification work in this release went through a review pass that found six ways it
+could grant or revoke wrongly. All are fixed, and all are worth naming because three of them
+broke the invariant this release advertises as untouched:
+
+- **Restore acknowledged transactions the local check had refused.** The adapter reported a
+  single consolidated `valid: true`, so the orchestrator acknowledged the whole owned set —
+  including purchases just declared invalid, which on Android finalises them and waives Play's
+  refund window. `RestoreResponse` gained an optional `verifiedTokens`, and only those are
+  acknowledged.
+
+- **Recovery re-granted exactly what a purchase had refused.** Recovery re-verifies from the
+  *stored entry*, which kept no binding, no expiry and no purchase state — so an on-device
+  check saw an amputated transaction and answered differently than it had at purchase time. A
+  refused expired subscription came back one launch later and was granted as *never
+  expiring*. The mirror case was as bad: with `verification.appUserId` set, a legitimate
+  purchase failed `BINDING_MISMATCH` forever, was never acknowledged, and Google refunded it.
+  The entry now persists what a verification needs.
+
+- **A successful purchase replaced the whole entitlement set with that one purchase's.** The
+  flows treat a verify response as consolidated, as a backend's is. Buying a consumable
+  silently revoked a subscription, in memory and on disk, until the next refresh. Local mode
+  now returns the consolidated set.
+
+- **An empty answer from the store wiped everything.** Play resolves its owned-purchases query
+  with an empty array when the query *fails* — disconnected service, signed-out account — so
+  "owns nothing" and "could not tell you" are identical. `refresh()` treated it as
+  authoritative and overwrote the cache, while stamping the entitlements as freshly confirmed.
+  Local mode now keeps the current set; a downgrade needs an expiry or an explicit revocation.
+
+- **iOS refunds and revocations passed the check.** `Transaction.all` retains revoked
+  transactions and the platform reports the fact locally — so a refunded non-expiring purchase
+  granted forever, having no expiry to fall back on. Now refused, with a `REVOKED` reason.
+
+- **The entitlement mapper's output was trusted blindly.** Unlike a backend response it went
+  through no schema, so a mapper returning a malformed object cached an entitlement that
+  `hasEntitlement` could never match and the next launch silently dropped — and one returning a
+  non-array threw a raw `TypeError` out of `purchase()` *after* acknowledging. Validated now;
+  a bad mapping grants nothing and logs.
+
+Smaller ones from the same pass: a duplicated entitlement key kept the first derived rather
+than the longest-lasting, so a live renewal lost to an older one inside the grace window; two
+lookup tables resolved inherited object properties; a numeric Play purchase state skipped its
+check; `reset()` emitted an empty `previous` on the one event that removes everything, and
+emitted at all when there was nothing to remove.
+
+### Changed
+
+- **`NativeAdapter` gained two optional methods**, `watchTransactions` and
+  `getPendingProductIds`. Internal contract; both are optional, so an adapter that omits them
+  degrades to reconciliation. `selectNativeAdapter()` now takes a logger, which the capgo
+  adapter uses for the best-effort paths that swallow their own failures.
+
+- **`NativeTransaction` gained a required field.** No consumer can produce one — there is no
+  config hook for a custom native adapter, and nothing public returns the type — so this is
+  additive for anything that only reads one. It is exported, though, so code that *constructs*
+  a `NativeTransaction` (a hand-rolled test double, a cast target) needs `purchaseReference`
+  added. Prefer `StorePurchase` for anything consumer-facing.
+
+- **`NativeAdapter.getProducts()` now takes whole `ConfiguredProduct` entries** rather than
+  `{ id, type }` pairs, because `androidPlanId` is what picks a base plan on Android. Internal
+  contract; no public surface changes.
+
+### Documentation
+
+- **A documented audit of the native layer** — [The native layer](https://iap.nossdev.com/guide/native-layer)
+  records what `@capgo/native-purchases` guarantees and what it does not, so the boundary
+  that caps iap's feature set is written down rather than rediscovered. Audited against
+  `8.6.5`: Play Billing Library **8.3.0** (ahead of Google's Billing-8 requirement, so
+  nothing to upgrade), licence **MPL-2.0** used unmodified (no copyleft obligation
+  propagates to iap or its consumers), and **no device or advertising identifiers** in
+  either platform's native source, with an empty `AndroidManifest.xml` that declares no
+  permissions of its own.
+
+  Two caveats the page documents because a clean bill of health would have hidden them:
+  the Android plugin **writes purchase tokens to logcat in the clear**, ungated (it redacts
+  the account identifier, so this reads as an oversight) — iap masks tokens in its own logs,
+  but that rule stops at the bridge; and when `androidPlanId` matches no offer, the plugin
+  **falls back to the first available base plan instead of failing**, so a stale plan id
+  silently purchases something else.
+- **Regression guards over the installed plugin** (`tests/unit/native-plugin-contract.test.ts`).
+  They read the plugin's own Gradle file, `package.json`, native sources and type
+  declarations, so a bump that invalidates a documented guarantee fails CI instead of
+  quietly making the docs wrong. The known gaps — no Play purchase signature, no
+  `originalTransactionId` field, no intro-offer eligibility query — are asserted
+  *inverted*, so capgo adding one of them also fails, as the signal to light up the
+  matching iap capability.
 
 ## [8.0.0] — 2026-09-04
 

package/README.md

@@ -64,6 +64,8 @@ await iap.purchase({
 - [Getting started](https://iap.nossdev.com/guide/getting-started) — first purchase in 30 minutes
 - [Backend contract](https://iap.nossdev.com/guide/backend-contract) — four endpoints your backend implements
 - [Architecture](https://iap.nossdev.com/guide/architecture) — three-tier model
+- [The native layer](https://iap.nossdev.com/guide/native-layer) — what `@capgo/native-purchases` exposes, its licence, its privacy audit
+- [Offline and no-backend use](https://iap.nossdev.com/guide/offline-and-no-backend) — on-device verification, offline guarantees, privacy
 - [Vue + Quasar recipe](https://iap.nossdev.com/recipes/vue-quasar) / [React recipe](https://iap.nossdev.com/recipes/react)
 
 ## Why this library
@@ -71,31 +73,52 @@ await iap.purchase({
 `@nosslabs/iap` does **one thing**: orchestrate the purchase flow on the client. It
 
 - wraps [`@capgo/native-purchases`](https://github.com/Cap-go/native-purchases) for native purchase + restore,
-- POSTs to **your** backend (which calls Attesto) for receipt validation,
+- POSTs to **your** backend (which calls Attesto) for receipt validation — or [verifies on the device](https://iap.nossdev.com/guide/offline-and-no-backend) when you have no backend at all,
 - acknowledges native transactions only **after** the backend confirms — `autoAcknowledgePurchases: false` defers finishing on **both** iOS and Android, so there's no phantom grant and no iOS finish-before-verify race,
 - caches entitlements locally for instant, reactive UI reads,
 - recovers unfinished transactions across app launches.
 
-It does **not**: talk to Attesto directly, define entitlement business logic, manage user auth, or ship paywall UI. Those belong to your app and your backend.
+It does **not**: talk to Attesto directly, manage user auth, or ship paywall UI. Those belong to your app and your backend. It does not define entitlement business logic either — except in local mode, where you supply the mapping in config because there is no backend to ask.
 
 ## Capacitor support matrix
 
 | `@nosslabs/iap` | Capacitor | Native plugin | dist-tag | Status |
 |---|---|---|---|---|
-| 8.x | 8.x | `@capgo/native-purchases ^8` | `@latest`, `@latest-8` | **Current** — `8.0.0` |
+| 8.x | 8.x | `@capgo/native-purchases ^8.2` | `@latest`, `@latest-8` | **Current** — `8.2.0` |
 | 7.x | 7.x | `@capgo/native-purchases@lts-v7` | `@latest-7` (pin via `^7`) | Maintenance |
 | 5.x | 5.x | `cordova-plugin-purchase ^13.x` | `@latest-5` (pin via `^5`) | Maintenance |
 
-## Optional peer dependency
+## Optional peer dependencies
 
-If you want auto-refresh on app resume (default behavior):
+Both are reached through a lazy `import()`, so an app that does not use them never loads them
+and keeps them out of its bundle. If you *uninstall* one, externalise it in your bundler
+(`build.rollupOptions.external` in Vite) — a dynamic import is still resolved at build time.
+See the [installation guide](https://iap.nossdev.com/guide/installation).
+
+**`@capacitor/app`** — auto-refresh on app resume (the default behaviour):
 
 ```bash
 npm install @capacitor/app
 npx cap sync
 ```
 
-Or disable the listener with `options.refreshOnResume: false`. See [installation guide](https://iap.nossdev.com/guide/installation#optional-app-resume-listener).
+Or disable the listener with `options.refreshOnResume: false`.
+
+**`@capacitor/preferences`** — the entitlement cache and unfinished-transaction storage, under
+the default `storage.type: 'preferences'`:
+
+```bash
+npm install @capacitor/preferences
+npx cap sync
+```
+
+Skip it if you set `storage.type` to `'custom'` (your own adapter) or `'memory'`. Choosing
+`'preferences'` without it fails at `initialize()` with a message saying so, rather than
+silently persisting nothing.
+
+If you use the default `'preferences'` and never declared the package yourself, add it to your
+`dependencies` now: npm installed it for you while it was a *required* peer, and that will stop
+happening.
 
 ## Development
 
@@ -112,3 +135,8 @@ npm run docs:dev    # vitepress dev (http://localhost:5173)
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+The native layer, [`@capgo/native-purchases`](https://github.com/Cap-go/capacitor-native-purchases),
+is **MPL-2.0** and is used **unmodified**, so its file-level copyleft imposes no obligation on
+iap or on your app's source. [The native layer](https://iap.nossdev.com/guide/native-layer)
+has the full note, with the Play Billing version and the device-identifier audit.