@chipmobilesdk/rn-payment 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,241 +1,334 @@
-# Changelog
-
-All notable changes to `@chipmobilesdk/rn-payment` are recorded here.
-
-This package follows semantic versioning. **Entitlement keys are yours**, but
-product keys, error codes, event names, state values, message keys, and the
-public API shape are this package's contract: renaming any of them is a breaking
-change.
-
-## [0.3.0] — 2026-10-13
-
-Documentation release: the README and the agent skill now match the code `0.2.1` shipped.
-**No code, API, storage or behaviour change** — upgrading from `0.2.1` changes nothing at
-runtime. Released as its own version so the skill a consuming app syncs (`packageVersion`)
-always matches the package it came from.
-
-### Changed
-
-- README `### Migrating 0.1.0 to 0.2.0`: no longer claims `0.1.0` persisted pending records.
-  On a device nothing persisted before `0.2.1`; the section now says to use `0.2.1` or
-  later and what a device first running it does (empty record, `unknown` until the first
-  sync, never a false `not_entitled`).
-- README intro: "Android only for now" instead of a version-pinned phrase.
-- Skill: "Require `0.2.1` or later" under the upgrade notes, with the reason; the public
-  API heading names `v0.3.0` (the surface is unchanged since `0.2.0`).
-
-## [0.2.1] — 2026-10-12
-
-Patch release. **Upgrade before shipping**: on a device, `0.2.0` and earlier persisted
-nothing.
-
-### Fixed
-
-- **The purchase snapshot never reached the device's storage.** The store opened MMKV
-  with `new MMKV()`, the react-native-mmkv **v3** constructor. In v4 — the only major the
-  peer range (`>=4.0.0`) allows — `MMKV` is a type, not a value, so the call threw and the
-  store fell back to memory on every device. Consequences: entitlements read `unknown`
-  after every cold start until a sync, an owner with no connection stayed `unknown`, and a
-  pending purchase was forgotten after an app kill. The store now uses v4's `createMMKV`
-  and `remove`. Found on an emulator: the app's `files/mmkv` held no
-  `chipmobilesdk.payment` instance.
-- The engine did report the fallback, as a `config_warning` ("Local storage
-  unavailable"), but nothing in the tests could trigger it: the repository's test double
-  exported a v3 `MMKV` class. The double now mirrors v4 exactly, and the persistence suite
-  fails against the old code.
-
-No API, storage format or behaviour change otherwise. Records written by a working
-install are read as before; there were none from `0.2.0` on a device to migrate.
-
-## [0.2.0] — 2026-10-12
-
-Additive minor release closing one gap that surfaced when `0.1.0` met an app that
-must show a pending payment after a restart. It is a **capability** gap: `0.1.0`'s
-engine refused to grant a pending purchase, but an app could only *see* one in the
-session that started it. Reconstructing the pending set meant importing the billing
-library, which this package exists to prevent.
-
-It also fixes a **serious defect on Android devices**: a pending purchase was
-granted. See [Fixed](#fixed). **Upgrade from `0.1.0` before shipping.**
-
-**Upgrading requires one change, compile-time only:** `PaymentEventType` gained a
-member. See [Migration](#migration).
-
-### Added
-
-**Pending purchases, visible across sessions**
-
-- `getPendingPurchases()` and `subscribePendingPurchases(listener)` on the engine,
-  and `usePendingPurchases(productKeys?)` in React. They return a
-  `PendingPurchasesState`: a `status` (`known` | `unknown`), an `isStale` flag, and
-  `purchases`, one `{ productKey, since }` per product. No transaction id, token or
-  store object.
-- Read from the persisted snapshot, so the set survives an app kill and an offline
-  restart. It is judged by the **same staleness rule as entitlements**, now shared
-  code rather than a parallel copy: never synced, or older than `staleAfterMs`,
-  reports `unknown`, never an empty "nothing pending".
-- Pushed only when the set, its status, or its staleness changes. A sync that finds
-  nothing new re-renders nothing.
-
-**How a pending purchase ended**
-
-- `purchase_pending_resolved` event, `{ productKey, outcome }`, with `outcome`
-  `settled` | `cancelled` | `expired`, emitted once per pending transaction.
-  `settled` precedes the `entitlement_granted` it leads to.
-- Detected from the snapshot commit itself, so it is exactly-once by construction:
-  a store push and a sync racing on one settlement emit one event, a sync that
-  changed nothing emits none, and `clearLocalData()` emits none, because discarding
-  a record locally is not the store ending it.
-- **On Android every unpaid end is `cancelled`.** Play does not say whether a pending
-  purchase was declined or expired; it stops reporting it. The package does not
-  guess from elapsed time. `expired` is reported only by a store that says so,
-  through a new optional `pendingEndReason` on the internal provider port.
-
-**Testing**
-
-- Fake store: `settlePending`, `cancelPending` and `expirePending` change store-side
-  state the way the real store does, so the engine sees the change at its next sync,
-  in the same session or after a simulated app kill.
-
-### Fixed
-
-- **On a device, a pending purchase was granted.** The Android adapter read only
-  Play's numeric purchase state and treated anything else as purchased. The
-  `react-native-iap` 16.x binding hands JavaScript the state as a **string**
-  (`'pending' | 'purchased' | 'unknown'`) and does not carry the numeric one across,
-  so every pending purchase fell through to "purchased": entitlement granted, and an
-  acknowledgement attempted, for money that had not arrived. The engine's own
-  "pending never grants" rule was intact; the adapter fed it the wrong state. No
-  test could see it, because tests drive the fake store, which bypasses the adapter.
-  The adapter now reads either form, and anything it does not recognize is
-  `unspecified`, never purchased. Checked against the installed 16.7.3 declarations
-  and its JavaScript bridge.
-- **An `unspecified` purchase state is never treated as paid.** `0.1.0` persisted
-  Play's unknown state as `purchased`, granting it and queuing an acknowledgement.
-  Now a new transaction in that state is left out until the store says what it is,
-  a known one keeps what the package already knew (uncertainty is neither a grant nor
-  a refund), a store push in that state is ignored, and `purchase()` returning one
-  answers `store_error`, retryable: if the money did move, a retry gets
-  `already_owned`, which re-syncs and grants.
-
-### Unchanged, deliberately
-
-- **Pending never grants**, under any configuration. The new surface is read-only.
-- **No storage migration.** The schema stays at version 1. `0.1.0` already persisted
-  pending records; `0.2.0` only reads them.
-- `purchase()` still returns `pending`, and `purchase_pending` still fires, exactly
-  as before.
-
-### Migration
-
-| Union | New member |
-|---|---|
-| `PaymentEventType` / `PaymentEvent` | `'purchase_pending_resolved'` |
-
-An exhaustive `switch` over either needs the new case or a `default`. A
-hand-written `PaymentEngine`, typically a test mock, needs `getPendingPurchases` and
-`subscribePendingPurchases`. Nothing else changes.
-
-## [0.1.0] — 2026-10-06
-
-First version. Android only, via Google Play Billing.
-
-### Added
-
-**Entitlements**
-
-- `getEntitlement`, `getAllEntitlements`, `subscribeEntitlements` — synchronous,
-  in-memory reads safe to call on a render path.
-- Three states: `unknown`, `entitled`, `not_entitled`. `unknown` is both the
-  initial state and re-entrant, so a long-offline paying user is never reported
-  as unpaid.
-- Many-to-many product↔entitlement mapping. An entitlement stays valid while any
-  granting product remains.
-- Source attribution: which of *your* product keys currently grants an
-  entitlement.
-
-**Selling**
-
-- `purchase` with a typed outcome covering success, pending, user cancellation,
-  already-owned, ineligible, unknown product, region unavailability, disabled,
-  not-ready, unsupported, timeout, network error, store error, environment block,
-  and validation rejection.
-- One purchase flow at a time. A second request is refused, never queued.
-- `already_owned` triggers a re-sync, which is how a reinstall repairs itself.
-- Consumables with app-controlled consumption via `consume`.
-- Subscriptions with expiry, auto-renew, and cancelled-but-valid reporting.
-- `changePlan` with four proration modes; `openSubscriptionManagement`;
-  `confirmPriceChange`.
-
-**Finalization**
-
-- A persisted queue drained at startup, on foreground, and after each purchase.
-  A purchase survives the app being killed between payment and acknowledgement.
-- Idempotent finalization and consumption.
-- Bounded per-session retry that resumes in the next session rather than
-  abandoning a paid transaction.
-- `getUnfinalized()` so "paid but not settled" is observable.
-
-**Products and pricing**
-
-- `getProducts` / `refreshProducts` returning store-formatted prices, currency
-  codes, numeric prices for comparison, billing periods, trials, and
-  introductory pricing.
-- Offer eligibility as the store determined it.
-- In-memory cache with a configurable TTL, defaulting to 15 minutes.
-
-**Sync, restore, and offline**
-
-- Automatic sync at initialization and on foreground, rate-limited.
-- `restore` distinguishing "restored" from "nothing found".
-- Revocation on the next sync when the store stops reporting a transaction.
-- Offline reads from the last successful sync, expiring to `unknown` after a
-  configurable ceiling (7 days by default).
-- `clearLocalData` and optional cache-scope partitioning.
-
-**Safety**
-
-- Fail-closed initialization when a non-production build declares `production`.
-- Runtime block on any chargeable purchase outside production, recorded in
-  observable state.
-- No exported way to grant an arbitrary entitlement.
-
-**Optional server validation**
-
-- A hook that decides entitlement for newly completed purchases.
-- Configurable fallback when the backend is unreachable, defaulting to grant and
-  queue for re-validation.
-
-**React**
-
-- `PaymentProvider`, `useEntitlement`, `useEntitlements`, `usePaymentStatus`,
-  `usePurchase`, `useProducts`, `useSync`.
-
-**Diagnostics**
-
-- 19 typed event types with correlation ids, sufficient to reconstruct a
-  transaction's lifecycle from logs alone.
-- 22 stable error codes.
-- A localizable message-key map with English defaults and no i18n dependency.
-
-**Testing**
-
-- A fake store behind `@chipmobilesdk/rn-payment/testing` driving every outcome,
-  both callback orderings, connection loss, refunds, and crash-then-recover
-  finalization.
-
-### Known limitations
-
-- **Grace period and account hold are not separable on Android.** Play returns a
-  grace-period subscription as active and stops returning a held one, so
-  `renewalState` reports `indeterminate` rather than inventing a distinction. The
-  default policy still behaves correctly with no backend; a non-default policy
-  needs server data through the validation hook.
-- **iOS is contract-only.** `createStoreProvider()` returns a stub that reports
-  `unavailable` on iOS. The host app still starts and runs.
-- **The Android adapter is unverified against an installed binding.** See the
-  README's compatibility section.
-
-### Migration
-
-None — this is a new package.
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-payment` are recorded here.
+
+This package follows semantic versioning. **Entitlement keys are yours**, but
+product keys, error codes, event names, state values, message keys, and the
+public API shape are this package's contract: renaming any of them is a breaking
+change.
+
+## [0.4.0] — 2026-11-01
+
+Minor release hardening the settlement path. **Upgrading requires no code change**;
+the API additions are optional, and the error-code union gains a member
+(`PAYMENT_NOT_CONSUMABLE`), so an exhaustive `switch` over it needs one more case.
+
+### Fixed
+
+- **A purchase on Android is settled once.** The Play binding delivers a launched
+  purchase both to the launch and to the session-long update listener, and both paths
+  settled it: the validation hook ran twice and `purchase_pending` fired twice.
+  Settlement is now single-flight per transaction, and the pending signal fires once
+  per transaction.
+- **Nothing that never answers can wedge the engine.** `timeouts.finalizeAttemptMs`
+  was validated but never applied; acknowledge and consume now honour it, and a
+  timed-out attempt is retried. The validation hook is bounded by the new
+  `timeouts.validateMs` and treated as unavailable when it runs out. Finalize drain and
+  re-validation run after the sync flight rather than inside it, so a stuck call no
+  longer makes every later sync join it. A store-timed purchase flow gets a
+  ten-minute ceiling so the purchase lock is always released.
+- **`consume` refuses what it must not consume.** A subscription or permanent unlock
+  returns `{ kind: 'failed', code: 'PAYMENT_NOT_CONSUMABLE' }`, a pending purchase
+  `PAYMENT_PENDING`, and no store call is made. A failed consume is now retried by
+  consuming; it was retried through the acknowledge path, which skips consumables.
+- **A second `initialize()` after success is a no-op.** It reconnected and left a
+  second set of native listeners behind, so every update was ingested twice. The Play
+  adapter also removes its previous native listeners on every connect.
+- **An exhausted reconnect budget is recoverable.** The engine stayed at `connecting`
+  forever. It now reports `{ kind: 'failed', retryable: true }`, and
+  `handleForeground()` starts a fresh budget with one immediate attempt.
+- **Re-validation identifies the transaction.** It sent an empty payload and no
+  identifier, so a backend could not tell which purchase it was asked about.
+- **The logger no longer receives raw error text.** `redact` passed `Error` messages
+  and strings through verbatim; it now keeps only a `PaymentError` code or an error's
+  class name.
+
+### Added
+
+- `ValidationCandidate.transactionId` and `ValidationCandidate.platform`.
+- `TimeoutConfig.validateMs` (3–120 s, default 15 s).
+- Error code `PAYMENT_NOT_CONSUMABLE`.
+- `./testing`: `createFakeStore({ mode: 'android-16.7' })`, which delivers a launched
+  purchase through `observePurchases` as the Play binding does and reports Android's
+  capabilities.
+
+## [0.3.1] — 2026-10-25
+
+Patch release. **Upgrade before shipping on Android**: with `0.3.0` no purchase could
+complete on a device. Found on a Galaxy S25 Ultra with a licence-tester account, in the
+first app to buy through this package (Task Manager, internal testing track).
+
+### Fixed
+
+- **Every purchase failed before Play opened.** The adapter sent
+  `request: { android: { skus, obfuscatedAccountIdAndroid } }`, the request shape from
+  `react-native-iap`'s documentation before 16.7. The 16.7 binding reads
+  `request.google` and rejected the call with `empty-sku-list`; the app saw a store
+  error. The request now uses `google` and `obfuscatedAccountId`, and is typed with the
+  binding's own `RequestPurchaseProps`, so a renamed key fails to typecheck.
+- **A completed purchase would have been reported as a store error.** On Android
+  `requestPurchase` resolves with an empty list when the flow ends, whatever happened;
+  the outcome arrives only through `purchaseUpdatedListener` / `purchaseErrorListener`.
+  The adapter read the resolved value, so it would have reported `store_error` for
+  every purchase, while Play delivered the purchase separately. `launchPurchase` now
+  settles on the first outcome event for the product (bought, pending, or an error).
+- **"Already owned" was a generic store error.** The adapter matched
+  `item-already-owned`; 16.7 sends `already-owned`. A reinstall that taps Buy again
+  now gets `already_owned` and the self-repairing sync (FR-033). `sku-not-found` now
+  maps to `unknown_product`.
+- **The launch timeout cut into the user's time in Play (FR-035).** Because the
+  binding reports nothing until the flow ends, the 30-second "opening the store
+  surface" timeout covered the time the user spends choosing a payment method. The
+  engine no longer applies it to a provider whose outcome includes that time (the Play
+  adapter); the binding always ends the flow with an event, so the call cannot hang.
+- **Plan changes sent the removed 16.6 fields.** A plan change now sends the replaced
+  purchase's token as `purchaseToken` and, with a proration mode,
+  `subscriptionProductReplacementParams` (old product id + replacement mode).
+
+### Changed
+
+- Peer `react-native-iap` is now `>=16.7.3 <17`, the version this adapter was verified
+  against (was `>=16.6.1 <17`, never verified).
+- Internal: `ProviderPurchaseRequest.replaceStoreProductId` now holds the replaced
+  product's id and the token moved to `replacePurchaseToken` (it held the token before);
+  `ProviderCapabilities` gained `purchaseOutcomeIncludesStoreTime`. Neither type is
+  public API. The fake store keeps `false`, so launch-timeout tests behave as before.
+
+### Added
+
+- `__tests__/iap-adapter.test.ts`: the adapter against a fake binding that validates
+  and resolves as 16.7.3 does — request shape, event-based outcomes, error mapping, the
+  no-event fallback.
+
+## [0.3.0] — 2026-10-13
+
+Documentation release: the README and the agent skill now match the code `0.2.1` shipped.
+**No code, API, storage or behaviour change** — upgrading from `0.2.1` changes nothing at
+runtime. Released as its own version so the skill a consuming app syncs (`packageVersion`)
+always matches the package it came from.
+
+### Changed
+
+- README `### Migrating 0.1.0 to 0.2.0`: no longer claims `0.1.0` persisted pending records.
+  On a device nothing persisted before `0.2.1`; the section now says to use `0.2.1` or
+  later and what a device first running it does (empty record, `unknown` until the first
+  sync, never a false `not_entitled`).
+- README intro: "Android only for now" instead of a version-pinned phrase.
+- Skill: "Require `0.2.1` or later" under the upgrade notes, with the reason; the public
+  API heading names `v0.3.0` (the surface is unchanged since `0.2.0`).
+
+## [0.2.1] — 2026-10-12
+
+Patch release. **Upgrade before shipping**: on a device, `0.2.0` and earlier persisted
+nothing.
+
+### Fixed
+
+- **The purchase snapshot never reached the device's storage.** The store opened MMKV
+  with `new MMKV()`, the react-native-mmkv **v3** constructor. In v4 — the only major the
+  peer range (`>=4.0.0`) allows — `MMKV` is a type, not a value, so the call threw and the
+  store fell back to memory on every device. Consequences: entitlements read `unknown`
+  after every cold start until a sync, an owner with no connection stayed `unknown`, and a
+  pending purchase was forgotten after an app kill. The store now uses v4's `createMMKV`
+  and `remove`. Found on an emulator: the app's `files/mmkv` held no
+  `chipmobilesdk.payment` instance.
+- The engine did report the fallback, as a `config_warning` ("Local storage
+  unavailable"), but nothing in the tests could trigger it: the repository's test double
+  exported a v3 `MMKV` class. The double now mirrors v4 exactly, and the persistence suite
+  fails against the old code.
+
+No API, storage format or behaviour change otherwise. Records written by a working
+install are read as before; there were none from `0.2.0` on a device to migrate.
+
+## [0.2.0] — 2026-10-12
+
+Additive minor release closing one gap that surfaced when `0.1.0` met an app that
+must show a pending payment after a restart. It is a **capability** gap: `0.1.0`'s
+engine refused to grant a pending purchase, but an app could only *see* one in the
+session that started it. Reconstructing the pending set meant importing the billing
+library, which this package exists to prevent.
+
+It also fixes a **serious defect on Android devices**: a pending purchase was
+granted. See [Fixed](#fixed). **Upgrade from `0.1.0` before shipping.**
+
+**Upgrading requires one change, compile-time only:** `PaymentEventType` gained a
+member. See [Migration](#migration).
+
+### Added
+
+**Pending purchases, visible across sessions**
+
+- `getPendingPurchases()` and `subscribePendingPurchases(listener)` on the engine,
+  and `usePendingPurchases(productKeys?)` in React. They return a
+  `PendingPurchasesState`: a `status` (`known` | `unknown`), an `isStale` flag, and
+  `purchases`, one `{ productKey, since }` per product. No transaction id, token or
+  store object.
+- Read from the persisted snapshot, so the set survives an app kill and an offline
+  restart. It is judged by the **same staleness rule as entitlements**, now shared
+  code rather than a parallel copy: never synced, or older than `staleAfterMs`,
+  reports `unknown`, never an empty "nothing pending".
+- Pushed only when the set, its status, or its staleness changes. A sync that finds
+  nothing new re-renders nothing.
+
+**How a pending purchase ended**
+
+- `purchase_pending_resolved` event, `{ productKey, outcome }`, with `outcome`
+  `settled` | `cancelled` | `expired`, emitted once per pending transaction.
+  `settled` precedes the `entitlement_granted` it leads to.
+- Detected from the snapshot commit itself, so it is exactly-once by construction:
+  a store push and a sync racing on one settlement emit one event, a sync that
+  changed nothing emits none, and `clearLocalData()` emits none, because discarding
+  a record locally is not the store ending it.
+- **On Android every unpaid end is `cancelled`.** Play does not say whether a pending
+  purchase was declined or expired; it stops reporting it. The package does not
+  guess from elapsed time. `expired` is reported only by a store that says so,
+  through a new optional `pendingEndReason` on the internal provider port.
+
+**Testing**
+
+- Fake store: `settlePending`, `cancelPending` and `expirePending` change store-side
+  state the way the real store does, so the engine sees the change at its next sync,
+  in the same session or after a simulated app kill.
+
+### Fixed
+
+- **On a device, a pending purchase was granted.** The Android adapter read only
+  Play's numeric purchase state and treated anything else as purchased. The
+  `react-native-iap` 16.x binding hands JavaScript the state as a **string**
+  (`'pending' | 'purchased' | 'unknown'`) and does not carry the numeric one across,
+  so every pending purchase fell through to "purchased": entitlement granted, and an
+  acknowledgement attempted, for money that had not arrived. The engine's own
+  "pending never grants" rule was intact; the adapter fed it the wrong state. No
+  test could see it, because tests drive the fake store, which bypasses the adapter.
+  The adapter now reads either form, and anything it does not recognize is
+  `unspecified`, never purchased. Checked against the installed 16.7.3 declarations
+  and its JavaScript bridge.
+- **An `unspecified` purchase state is never treated as paid.** `0.1.0` persisted
+  Play's unknown state as `purchased`, granting it and queuing an acknowledgement.
+  Now a new transaction in that state is left out until the store says what it is,
+  a known one keeps what the package already knew (uncertainty is neither a grant nor
+  a refund), a store push in that state is ignored, and `purchase()` returning one
+  answers `store_error`, retryable: if the money did move, a retry gets
+  `already_owned`, which re-syncs and grants.
+
+### Unchanged, deliberately
+
+- **Pending never grants**, under any configuration. The new surface is read-only.
+- **No storage migration.** The schema stays at version 1. `0.1.0` already persisted
+  pending records; `0.2.0` only reads them.
+- `purchase()` still returns `pending`, and `purchase_pending` still fires, exactly
+  as before.
+
+### Migration
+
+| Union | New member |
+|---|---|
+| `PaymentEventType` / `PaymentEvent` | `'purchase_pending_resolved'` |
+
+An exhaustive `switch` over either needs the new case or a `default`. A
+hand-written `PaymentEngine`, typically a test mock, needs `getPendingPurchases` and
+`subscribePendingPurchases`. Nothing else changes.
+
+## [0.1.0] — 2026-10-06
+
+First version. Android only, via Google Play Billing.
+
+### Added
+
+**Entitlements**
+
+- `getEntitlement`, `getAllEntitlements`, `subscribeEntitlements` — synchronous,
+  in-memory reads safe to call on a render path.
+- Three states: `unknown`, `entitled`, `not_entitled`. `unknown` is both the
+  initial state and re-entrant, so a long-offline paying user is never reported
+  as unpaid.
+- Many-to-many product↔entitlement mapping. An entitlement stays valid while any
+  granting product remains.
+- Source attribution: which of *your* product keys currently grants an
+  entitlement.
+
+**Selling**
+
+- `purchase` with a typed outcome covering success, pending, user cancellation,
+  already-owned, ineligible, unknown product, region unavailability, disabled,
+  not-ready, unsupported, timeout, network error, store error, environment block,
+  and validation rejection.
+- One purchase flow at a time. A second request is refused, never queued.
+- `already_owned` triggers a re-sync, which is how a reinstall repairs itself.
+- Consumables with app-controlled consumption via `consume`.
+- Subscriptions with expiry, auto-renew, and cancelled-but-valid reporting.
+- `changePlan` with four proration modes; `openSubscriptionManagement`;
+  `confirmPriceChange`.
+
+**Finalization**
+
+- A persisted queue drained at startup, on foreground, and after each purchase.
+  A purchase survives the app being killed between payment and acknowledgement.
+- Idempotent finalization and consumption.
+- Bounded per-session retry that resumes in the next session rather than
+  abandoning a paid transaction.
+- `getUnfinalized()` so "paid but not settled" is observable.
+
+**Products and pricing**
+
+- `getProducts` / `refreshProducts` returning store-formatted prices, currency
+  codes, numeric prices for comparison, billing periods, trials, and
+  introductory pricing.
+- Offer eligibility as the store determined it.
+- In-memory cache with a configurable TTL, defaulting to 15 minutes.
+
+**Sync, restore, and offline**
+
+- Automatic sync at initialization and on foreground, rate-limited.
+- `restore` distinguishing "restored" from "nothing found".
+- Revocation on the next sync when the store stops reporting a transaction.
+- Offline reads from the last successful sync, expiring to `unknown` after a
+  configurable ceiling (7 days by default).
+- `clearLocalData` and optional cache-scope partitioning.
+
+**Safety**
+
+- Fail-closed initialization when a non-production build declares `production`.
+- Runtime block on any chargeable purchase outside production, recorded in
+  observable state.
+- No exported way to grant an arbitrary entitlement.
+
+**Optional server validation**
+
+- A hook that decides entitlement for newly completed purchases.
+- Configurable fallback when the backend is unreachable, defaulting to grant and
+  queue for re-validation.
+
+**React**
+
+- `PaymentProvider`, `useEntitlement`, `useEntitlements`, `usePaymentStatus`,
+  `usePurchase`, `useProducts`, `useSync`.
+
+**Diagnostics**
+
+- 19 typed event types with correlation ids, sufficient to reconstruct a
+  transaction's lifecycle from logs alone.
+- 22 stable error codes.
+- A localizable message-key map with English defaults and no i18n dependency.
+
+**Testing**
+
+- A fake store behind `@chipmobilesdk/rn-payment/testing` driving every outcome,
+  both callback orderings, connection loss, refunds, and crash-then-recover
+  finalization.
+
+### Known limitations
+
+- **Grace period and account hold are not separable on Android.** Play returns a
+  grace-period subscription as active and stops returning a held one, so
+  `renewalState` reports `indeterminate` rather than inventing a distinction. The
+  default policy still behaves correctly with no backend; a non-default policy
+  needs server data through the validation hook.
+- **iOS is contract-only.** `createStoreProvider()` returns a stub that reports
+  `unavailable` on iOS. The host app still starts and runs.
+- **The Android adapter is unverified against an installed binding.** See the
+  README's compatibility section.
+
+### Migration
+
+None — this is a new package.