@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,334 +1,482 @@
-# 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.
+# @chipmobilesdk/rn-payment
+
+## 0.5.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Packaging fixes; no code change. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+  - `react-native-nitro-modules` is no longer a peer dependency. The package never
+    imports it; `react-native-iap` declares it as its own peer, and the README still
+    tells apps to install it.
+  - `react-native-mmkv` is now `>=4.0.0 <5`. The store is written against v4's
+    `createMMKV`; there is no v5 yet, so no app is affected.
+  - `publishConfig` declares public access on npmjs, like every other package. It
+    had none, so it only published publicly because publishing was done by hand.
+
+## [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.