@chipmobilesdk/rn-payment 0.1.0 → 0.2.1

package/README.md

@@ -1,761 +1,885 @@
-# @chipmobilesdk/rn-payment
-
-Reusable in-app payment and entitlement capability for ChipMobileSdk-family React
-Native apps. Android only in 0.1.0, via Google Play Billing, behind a contract
-that is neutral with respect to platform and store.
-
-**The package owns capability. Your app owns policy.** The package gives you a
-safe, consistent way to sell, finalize, restore, and report entitlements. What you
-sell, at what price, on which screen, at which moment, what each entitlement
-unlocks, and how generous your grace policy is — all yours. There is no product
-identifier, no screen name, and no business rule in this package.
-
----
-
-## Contents
-
-- [The one idea that matters](#the-one-idea-that-matters)
-- [Install](#install)
-- [Compatibility](#compatibility)
-- [Quick start](#quick-start)
-- [Catalog and entitlement mapping](#catalog-and-entitlement-mapping)
-- [The entitlement model](#the-entitlement-model)
-- [Purchase flow](#purchase-flow)
-- [Finalization: the invariant you cannot opt out of](#finalization-the-invariant-you-cannot-opt-out-of)
-- [Consumables](#consumables)
-- [Subscriptions](#subscriptions)
-- [Prices and offers](#prices-and-offers)
-- [Sync, restore, and offline](#sync-restore-and-offline)
-- [Environments and the production guard](#environments-and-the-production-guard)
-- [Server-side validation](#server-side-validation)
-- [Localizable copy](#localizable-copy)
-- [Events and errors](#events-and-errors)
-- [Wiring an entitlement to another system](#wiring-an-entitlement-to-another-system)
-- [Testing](#testing)
-- [What is stored on the device](#what-is-stored-on-the-device)
-- [Trust boundary](#trust-boundary)
-- [Play Console checklist](#play-console-checklist)
-- [Play policy checklist](#play-policy-checklist)
-- [Production release checklist](#production-release-checklist)
-- [Known limitations](#known-limitations)
-- [Adding iOS later](#adding-ios-later)
-- [Versioning](#versioning)
-
----
-
-## The one idea that matters
-
-Your business logic asks about **entitlement keys** you chose — `no_ads`,
-`pro_features` — and never about store product ids, product types, or which store
-sold the thing.
-
-```ts
-const { status } = useEntitlement('no_ads');
-```
-
-`status` is `'unknown' | 'entitled' | 'not_entitled'`. The third state is why this
-package exists: on a cold start we do not yet know whether this user paid, and
-saying so is strictly better than guessing. If you collapse `unknown` into
-`not_entitled`, a paying user watches ads flash before they vanish, or sees a
-purchased feature locked for a second. Render a loading treatment for `unknown`.
-
----
-
-## Install
-
-```bash
-npm install @chipmobilesdk/rn-payment
-```
-
-Peer dependencies you must install yourself:
-
-```bash
-npm install react-native-iap react-native-mmkv react-native-nitro-modules
-```
-
-- `react-native-iap` — the Play Billing binding. Reached only through this
-  package's Android adapter; you never import it.
-- `react-native-mmkv` — synchronous local storage. Required: it is what lets
-  entitlement reads be synchronous on a render path. Without it entitlements do
-  not survive a cold start and read `unknown` until the first sync, which is safe
-  but degraded.
-- `react-native-nitro-modules` — transitive requirement of `react-native-iap`.
-
-> **Android manifest.** `com.android.vending.BILLING` is declared by the billing
-> library's own `AndroidManifest.xml` and merged into your app automatically. You
-> do **not** add it yourself. No runtime permission is requested and no sensitive
-> API is touched, so there is no permission prompt and no denial path to handle.
->
-> **Verified state in this repository:** the app manifest at
-> `android/app/src/main/AndroidManifest.xml` declares `INTERNET`, `CAMERA`, and
-> notification permissions, and **no** `BILLING` entry — correct, because the
-> billing library is not installed yet. Once it is, confirm the merged manifest
-> contains exactly one `com.android.vending.BILLING` entry and no new runtime
-> permission:
->
-> ```bash
-> # After a debug build, inspect the merge report:
-> cat android/app/build/outputs/logs/manifest-merger-debug-report.txt | grep -i billing
-> ```
-
----
-
-## Compatibility
-
-Verified against this repository's toolchain, not assumed:
-
-| Item | Supported |
-|---|---|
-| React | >= 19 (verified 19.2.3) |
-| React Native | >= 0.85 (verified 0.85.3), New Architecture only |
-| TypeScript | >= 5.8 |
-| Node | >= 22.11.0 |
-| Android `minSdk` / `compileSdk` / `targetSdk` | 24 / 36 / 36 |
-| Kotlin | 2.1.20 |
-| `react-native-iap` | >= 16.6.1 < 17 |
-| `react-native-mmkv` | >= 4.0.0 |
-| `react-native-nitro-modules` | >= 0.36.5 |
-
-**Why the `react-native-iap` ceiling is the next major.** Both the Nitro peer
-requirement and the bundled Play Billing version move on majors, so a major bump
-needs re-verification rather than silent adoption.
-
-> ⚠️ **The Android adapter is written but not yet verified against an installed
-> binding.** Its call shapes follow `react-native-iap` 16.x as documented, and the
-> surface it depends on is declared explicitly in a local `IapModule` interface so
-> a mismatch fails at typecheck rather than at runtime on a user's device. Verify
-> it on a device before shipping.
-
----
-
-## Quick start
-
-```tsx
-import {
-  PaymentProvider,
-  createStoreProvider,
-  useEntitlement,
-  usePurchase,
-} from '@chipmobilesdk/rn-payment';
-
-const config = {
-  catalog: [
-    {
-      productKey: 'remove_ads',
-      productType: 'one_time_permanent',
-      storeProductIds: { android: 'com.yourapp.remove_ads' },
-      grants: ['no_ads'],
-    },
-  ],
-  entitlements: ['no_ads'],
-  environment: 'production',
-  isProductionBuild: true,
-};
-
-export function App() {
-  return (
-    <PaymentProvider config={config} deps={{ provider: createStoreProvider() }}>
-      <YourApp />
-    </PaymentProvider>
-  );
-}
-
-function AdSlot() {
-  const noAds = useEntitlement('no_ads');
-
-  // Hold while unknown. Do not guess.
-  if (noAds.status === 'unknown') return null;
-  if (noAds.status === 'entitled') return null;
-  return <YourBanner />;
-}
-```
-
-`createStoreProvider()` picks the platform adapter. On a platform with no adapter
-it returns a stub that reports `unavailable` instead of throwing, so your app
-still starts and runs — it only loses the ability to sell.
-
-**Call `handleForeground()` when your app returns to the foreground.** It is left
-to you rather than subscribed internally, because this package must not decide
-what "foreground" means for an app that may be backgrounded by its own modal, a
-biometric prompt, or the store's own purchase sheet. It is rate-limited
-regardless, so calling it liberally is safe.
-
----
-
-## Catalog and entitlement mapping
-
-The catalog is the whole of your product configuration, and the only place a store
-product id appears.
-
-```ts
-catalog: [
-  {
-    productKey: 'premium_monthly',          // yours
-    productType: 'subscription',
-    storeProductIds: {
-      android: 'com.yourapp.premium.monthly', // Play Console
-      ios: 'com.yourapp.premium.monthly',     // optional, additive
-    },
-    grants: ['no_ads', 'pro_features'],     // yours
-  },
-]
-```
-
-**The mapping is many-to-many.** Several products may grant one entitlement — a
-monthly plan, a yearly plan, and a lifetime unlock all granting `no_ads` — and one
-product may grant several. An entitlement stays valid while **any** granting
-product remains valid, so losing one source does not revoke it.
-
-Validation runs at configure time, before anything connects, and names the
-offending entry. It catches duplicate product keys, a missing store id for the
-current platform, an invalid product type, a product granting nothing, two
-products sharing a store id, an entitlement no product grants, and an entitlement
-granted but never declared. All problems are reported in one pass.
-
-### Creating the products in Play Console
-
-1. Create each product with the exact id you put in `storeProductIds.android`.
-2. One-time products go under **In-app products**; consumables are also in-app
-   products — the *package* decides consumable behaviour via `productType`, not
-   Play.
-3. Subscriptions need a **base plan**, and an **offer** if you want a trial or
-   introductory price.
-4. Activate each product. An inactive product is reported as
-   `not_available_from_store`, distinctly from a network error.
-
----
-
-## The entitlement model
-
-```ts
-const state = engine.getEntitlement('no_ads');
-// { key, status, sources, subscription?, lastSyncedAt?, isStale }
-```
-
-| Status | Meaning | What to render |
-|---|---|---|
-| `unknown` | Not yet known, or the cached answer went stale | A loading or held treatment |
-| `entitled` | At least one valid source grants it | The paid experience |
-| `not_entitled` | Synced, fresh, and nothing grants it | The unpaid experience |
-
-`unknown` is **re-entrant**, not just an initial state: it returns when cached
-data passes its staleness ceiling. Handle it as a real state, not a startup
-flicker.
-
-`sources` names *your* product keys, so you can show "You're on the yearly plan"
-without touching a transaction record.
-
-Changes are pushed. You never poll.
-
----
-
-## Purchase flow
-
-```ts
-const result = await engine.purchase('premium_monthly', {
-  // Optional. Passed straight to the store for fraud prevention and never
-  // generated, inferred, or persisted by this package.
-  obfuscatedAccountId: yourOpaqueAccountId,
-  offerKey: selectedOffer.offerKey,
-});
-```
-
-`result.kind` is a discriminated union, and the distinctions matter:
-
-| Kind | What it means | Suggested handling |
-|---|---|---|
-| `success` | Paid and granted | Show the unlocked state |
-| `pending` | Slow payment method; **not granted** | Show a waiting notice |
-| `user_cancelled` | Normal. Not an error | Say nothing |
-| `already_owned` | Store says they own it; a re-sync was triggered | Show the unlocked state |
-| `ineligible` | Not eligible for this offer | Offer an alternative |
-| `unknown_product` | Not in your catalog | Developer bug |
-| `product_unavailable_in_region` | Not sold where they are | Explain |
-| `disabled` | Your global flag is off | Hide the entry point |
-| `not_ready` | Not initialized or connecting | Retry later |
-| `purchase_in_progress` | Another flow is open | Ignore the second tap |
-| `environment_blocked` | Non-production build refused a real charge | Developer-facing |
-| `validation_rejected` | Your backend said no | Explain |
-| `timeout` / `network_error` / `store_error` | Transient or store-side | Offer retry |
-
-**Never report `user_cancelled` as a failure.** Showing an error banner to someone
-who simply changed their mind is the most common paywall bug this union exists to
-prevent.
-
-The purchase surface is rendered by the store. This package neither controls,
-customizes, nor can verify its accessibility — it only reports what happened.
-
----
-
-## Finalization: the invariant you cannot opt out of
-
-Google **auto-refunds and revokes** a purchase that is not acknowledged within
-three days. So acknowledgement is not a step you can forget here: the package
-owns it.
-
-The ordering that makes it safe is: the intent to finalize is written to local
-storage **before** the store call is attempted. A crash before the write leaves
-the purchase still owned, so the next sync re-queues it. A crash after the write
-leaves a queue record, so the next startup drains it. There is no window where a
-paid transaction is forgotten.
-
-Failed attempts retry under bounded backoff. Exhausting a session's budget is
-**not** giving up — the record stays queued and the next launch tries again, which
-is how the package stays inside the three-day window without hammering a store
-that is currently refusing.
-
-```ts
-// Observable rather than swallowed.
-engine.getUnfinalized(); // [{ productKey, transactionId, attempts, purchasedAt }]
-```
-
-Entitlement is granted **before** finalization completes, deliberately: a store
-hiccup must never withhold something already paid for.
-
----
-
-## Consumables
-
-For a consumable, **you** decide when it counts as consumed, because only you know
-whether the item was actually banked in your own data.
-
-```ts
-const result = await engine.purchase('coin_pack_100');
-if (result.kind === 'success') {
-  await yourDatabase.addCoins(100);   // bank it first
-  await engine.consume(result.transaction); // then tell the store
-}
-```
-
-Until you call `consume`, the store will not allow a repurchase. Consuming twice,
-or concurrently, grants the item exactly once. A consumable never becomes a
-permanent entitlement.
-
----
-
-## Subscriptions
-
-```ts
-const state = engine.getEntitlement('pro_features');
-state.subscription;
-// { expiresAt?, willAutoRenew, isCancelledButValid, renewalState }
-```
-
-A successful renewal changes nothing, so it emits **no** event — change signals
-come from a diff, which makes that structural rather than a special case.
-
-### Grace and hold policy
-
-```ts
-gracePolicy: 'grant',    // default
-holdPolicy: 'withhold',  // default
-```
-
-A **grace period** means the store is still retrying a payment method that failed
-for reasons usually outside the user's control. Revoking immediately punishes a
-paying customer for a billing hiccup. **Account hold** means the store has given
-up retrying; the subscription is effectively unpaid.
-
-> **Android cannot separate these client-side.** Play returns a grace-period
-> subscription as active and stops returning a held one — making hold
-> indistinguishable from expired, cancelled, or refunded. So `renewalState`
-> reports `indeterminate` rather than inventing the distinction.
->
-> **The defaults still work with no backend**, because Play's own behaviour
-> matches them: a grace-period purchase keeps being returned (so the entitlement
-> holds) and a held one stops being returned (so it lapses at the next sync). Only
-> a *non-default* policy needs server data, through the validation hook.
-
-### Plan changes
-
-```ts
-await engine.changePlan('premium_monthly', 'premium_yearly', 'immediate_with_time_proration');
-```
-
-| Mode | Effect |
-|---|---|
-| `immediate_with_time_proration` | Switch now, credit unused time. Usual upgrade. |
-| `immediate_and_charge_full_price` | Switch now, charge full price, restart the period. |
-| `immediate_and_charge_prorated_price` | Switch now, charge the difference. |
-| `deferred` | Keep the current plan until it expires. Usual downgrade. |
-
-A plan change goes through the normal purchase flow, so it inherits the
-single-flight lock, the environment guard, validation, and the finalization queue.
-
-### Cancellation
-
-```ts
-await engine.openSubscriptionManagement('premium_monthly');
-```
-
-This opens the **store's** screen. Platforms forbid an app presenting its own
-cancellation screen, so there is deliberately no alternative in this package.
-
----
-
-## Prices and offers
-
-```ts
-const { products, missing } = await engine.getProducts(['premium_monthly']);
-```
-
-**Render `formattedPrice`. Never build a price string.** Only the store knows the
-right currency symbol, its placement, the decimal separator, and the grouping for
-the user's locale — `1.990 ₫` and `$19.90` are not the same shape. The
-`priceAmountMicros` field exists for sorting and comparison only.
-
-Offer eligibility is **the store's verdict**. Computing it locally would promise a
-trial the store then refuses at checkout.
-
-`missing` separates `not_in_catalog` (your configuration) from
-`not_available_from_store` (unapproved, or not sold in this country), and neither
-is conflated with a network error — so you can explain an absent row instead of
-rendering a blank.
-
-Results are cached in memory for 15 minutes by default, never persisted, and
-`refreshProducts` bypasses the cache.
-
----
-
-## Sync, restore, and offline
-
-Sync runs automatically at initialization and when you call `handleForeground()`,
-rate-limited to once a minute by default.
-
-```ts
-const outcome = await engine.restore();
-if (outcome.ok && outcome.restored) { /* purchases came back */ }
-else if (outcome.ok) { /* nothing found — say that, not "success" */ }
-```
-
-**"Nothing found" is a distinct success.** Telling a user their purchases were
-restored when none existed is a support ticket.
-
-Entitlements are readable offline from the last successful sync. Past the
-staleness ceiling — **7 days** by default — they become `unknown`, never
-`not_entitled`. Seven days covers a holiday without connectivity while bounding
-how long a refunded entitlement can outlive its refund.
-
-When the store stops reporting a transaction, the entitlement is revoked at the
-next sync. The cache never resurrects it.
-
-### Logout and account switching
-
-```ts
-await engine.clearLocalData();
-```
-
-If your app has its own accounts, also supply a `scopeToken`:
-
-```ts
-scopeToken: opaqueHashOfYourUserId,
-```
-
-Cached entitlements are partitioned by it, so a second user cannot inherit the
-first user's entitlements even if you forget to call `clearLocalData`. The token is
-a cache-partition key — never interpreted, transmitted, or attached to a
-transaction — and is distinct from `obfuscatedAccountId`.
-
----
-
-## Environments and the production guard
-
-```ts
-environment: 'development' | 'test' | 'production',
-isProductionBuild: boolean,  // you supply this; only you know how you built
-```
-
-Two layers:
-
-1. **Fail closed at construction.** A non-production build declaring `production`
-   throws `PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD` and never connects.
-2. **Runtime block.** Outside production, any chargeable purchase is refused,
-   recorded in `getStatus().blockedOperations`, and emitted as
-   `environment_blocked` — observable in state, so a test can assert it rather
-   than scraping logs.
-
-> **Why this blocks where `@chipmobilesdk/rn-ads` substitutes.** The ads package
-> swaps in Google's official *test ad units* when a non-production build supplies
-> production ones, keeping the app working. Play has no equivalent test **product**
-> id — testing uses licence-tester *accounts* against real product ids — so
-> substitution is impossible here. Blocking with an observable refusal is the only
-> honest option, and the asymmetry is deliberate rather than an inconsistency.
-
----
-
-## Server-side validation
-
-Optional. Without it the package is fully functional client-side.
-
-```ts
-validateTransaction: async candidate => {
-  const verdict = await fetch('https://your.api/verify', {
-    method: 'POST',
-    body: JSON.stringify(candidate),
-  }).then(r => r.json());
-  return { approved: verdict.ok, reason: verdict.reason };
-},
-onValidationUnavailable: 'grant_and_queue', // default
-```
-
-**The hook runs for newly completed purchases only.** Purchases seen during sync
-or restore are not resubmitted — which is what keeps restore and foreground sync
-working while your backend is down. Revocation still flows from the store.
-
-**When the backend is unreachable, the default grants and queues.** The store has
-already confirmed payment, so withholding would punish a paying user for your
-outage. The queued transaction is re-validated on a later sync, and a rejection
-then revokes — which bounds the exposure this default accepts. Choose `'withhold'`
-if your threat model requires it.
-
-A hook that throws is treated as unavailable, never as an implicit approval.
-
-This package calls **no endpoint** other than the platform's billing service. All
-other traffic is your own code, through this hook.
-
----
-
-## Localizable copy
-
-The package exports message keys with English defaults and takes no i18n runtime
-dependency.
-
-```ts
-import { DEFAULT_USER_MESSAGES, USER_MESSAGE_KEYS, isUserMessageKey } from '@chipmobilesdk/rn-payment';
-```
-
-User-actionable and developer copy are **separate maps**, so you cannot
-accidentally show "Payment catalog is invalid" to a customer. `isUserMessageKey()`
-lets you assert that at your own boundary.
-
-Message keys are public API; renaming one is a breaking change.
-
----
-
-## Events and errors
-
-19 event types, each carrying a timestamp and — within a purchase cycle — one
-`correlationId`. The bar is that the event stream **alone** is enough to
-reconstruct a transaction's lifecycle, so "the user says they paid but has no
-entitlement" can be investigated from logs without a reproduction.
-
-Ordering for a successful purchase:
-
-```text
-purchase_started → purchase_succeeded → [validation_decided] → entitlement_granted → transaction_finalized
-```
-
-Exactly-once guarantees: one grant per transition (not per source), one revocation
-per transition, no event for a renewal that changed nothing, one finalize per
-transaction however many times it is retried, and **nothing at all after
-cleanup**.
-
-**Never present in an event payload**: store objects, raw receipts, verification
-payloads, backend tokens, payment details, the obfuscated account id, or the cache
-scope token.
-
-A listener that throws cannot corrupt the state machine or stop other listeners.
-The failure goes to your `logger`, not back into the event stream.
-
-Errors carry a stable `code`, a log-safe `message`, the `operation`, a `retryable`
-flag, and a redacted `cause`. Error codes are public API.
-
----
-
-## Wiring an entitlement to another system
-
-**This is your job, and that is the point.** This package references no
-advertising package, and no advertising package references it.
-
-```ts
-// Your app. The whole integration.
-function enablementForEntitlement(status) {
-  if (status === 'entitled') return 'disabled';   // they paid not to see ads
-  if (status === 'not_entitled') return 'enabled'; // confirmed unpaid
-  return 'undecided';                              // not yet known — hold
-}
-
-engine.subscribeEntitlements(map => {
-  ads.setEnabled(enablementForEntitlement(map.no_ads.status));
-});
-```
-
-The middle line is why `unknown` exists. Enabling while waiting flashes an ad at
-someone who paid not to see one; disabling while waiting costs revenue on every
-other user's first screen. Holding is a deliberate choice made with real
-information.
-
-A worked version is in the demo app at `src/payment/adsWiring.ts`.
-
----
-
-## Testing
-
-```ts
-import { createFakeStore, makePurchase } from '@chipmobilesdk/rn-payment/testing';
-
-const store = createFakeStore();
-const engine = createEngine(config, { provider: store });
-
-store.scriptPurchaseSuccess({ storeProductId: 'com.yourapp.remove_ads' });
-await engine.purchase('remove_ads');
-```
-
-The fake store drives every purchase outcome, both callback orderings, pending
-settlement across sessions, connection loss and recovery, refunds, failing
-acknowledgement, and an app-kill simulation (drop memory, keep the snapshot,
-restart). No device, no network, no store account, no real money.
-
-`./testing` is a separate entrypoint so test doubles cannot reach a production
-bundle.
-
-### Licence testers, for device verification
-
-1. Play Console → **Setup → Licence testing**, add tester accounts.
-2. Publish to at least one testing track. **In-app products do not work at all
-   for a build that has never been uploaded to Play.**
-3. Sign in on the device with a licence tester account.
-4. Use a shortened subscription renewal cycle to observe the lifecycle.
-
-Never use a production transaction as a verification step.
-
----
-
-## What is stored on the device
-
-Exhaustively, for your Data safety declaration:
-
-| Stored | Why |
-|---|---|
-| Entitlement keys and their states | So entitlements are readable offline |
-| Granting product keys | So you can show the current plan |
-| Subscription expiry and renewal status | So lifecycle is readable offline |
-| Unfinished-transaction records (transaction id, product key, token, attempt count) | So a paid purchase is never lost to an app kill |
-| Last successful sync time | So data age is observable |
-| Schema version | So the record can be migrated |
-| Your `scopeToken`, if you supply one | Solely to partition the record |
-
-**Not stored**: payment details, card data, billing addresses, user identity, raw
-receipts, verification payloads, backend tokens.
-
-Stored in MMKV under the instance id `chipmobilesdk.payment`. `clearLocalData()`
-erases all of it. On Android, declare backup exclusion in your app's
-`data_extraction_rules.xml` if you do not want the record restored to a new
-device — the snapshot is rebuilt from the store anyway.
-
----
-
-## Trust boundary
-
-**Client-side entitlement data can be tampered with on a compromised device.** A
-rooted user can edit local storage. This package does not claim otherwise, and it
-does not pretend encryption would help: anything the device can decrypt, its owner
-can decrypt.
-
-**Only server-side validation is a real defence.** If your product can be
-meaningfully abused, use the validation hook with a backend that verifies receipts
-against the Play Developer API.
-
----
-
-## Play Console checklist
-
-- [ ] Developer account **payments profile** completed — without it nothing is
-      sellable.
-- [ ] Each in-app product created with the exact id from your catalog, and
-      **activated**.
-- [ ] Subscriptions have a base plan, and an offer if you want a trial.
-- [ ] Prices set per country; tax settings configured.
-- [ ] Licence testers added.
-- [ ] App published to at least one testing track.
-- [ ] Shortened renewal cycles enabled for lifecycle testing.
-- [ ] Review notes describe how a reviewer reaches purchasable content.
-- [ ] A demo account supplied if your paywall sits behind a login.
-- [ ] Real-time developer notifications configured, if you have a backend.
-
----
-
-## Play policy checklist
-
-Your obligations as the app owner — this package cannot discharge them for you:
-
-- [ ] In-app digital goods use Play's billing system. This package provides **no
-      route** to alternative billing, user-choice billing, or an external purchase
-      call to action.
-- [ ] Price, billing period, renewal terms, trial conditions, and how to cancel
-      are disclosed **before** payment, where the user can see them.
-- [ ] A route to the store's subscription management screen is reachable in-app.
-- [ ] A "Restore purchases" control is reachable in-app.
-- [ ] Data safety declaration reflects the stored-data list above plus the billing
-      library's own behaviour.
-- [ ] Privacy policy and terms of sale are valid and current.
-- [ ] Refund requests handled per platform policy.
-- [ ] Auto-renewal legal requirements met for each market you sell in.
-
----
-
-## Production release checklist
-
-- [ ] `environment: 'production'` and `isProductionBuild: true` only in release
-      builds.
-- [ ] `npm pack --dry-run` output contains no store product id, credential, or
-      secret.
-- [ ] The Android adapter verified against the installed `react-native-iap`
-      version.
-- [ ] All three product types purchased on a device with a licence tester.
-- [ ] A pending purchase settled via a slow test payment method.
-- [ ] Restore verified after uninstall and reinstall.
-- [ ] Subscription lifecycle observed on shortened cycles.
-- [ ] Entitlements readable in airplane mode.
-- [ ] App starts and runs on a device without Play services.
-- [ ] Store-side records show **zero** production transactions from
-      development/test builds. Retain as release evidence.
-
----
-
-## Known limitations
-
-1. **Grace period and account hold are not separable on Android** client-side. See
-   [Subscriptions](#subscriptions). The defaults work with no backend; a
-   non-default policy needs server data.
-2. **iOS is contract-only.** `createStoreProvider()` returns an `unavailable` stub
-   on iOS; the host app still starts and runs.
-3. **The Android adapter is unverified** against an installed binding. See
-   [Compatibility](#compatibility).
-4. **Price-change confirmation is unsupported on Android.** Play notifies the user
-   itself and offers no client-side flow, so `confirmPriceChange` reports
-   `unsupported` rather than faking a confirmation.
-5. **Client-side entitlement is forgeable.** See
-   [Trust boundary](#trust-boundary).
-6. **Cross-platform entitlement sync is out of scope.** One user with an Android
-   and an iOS device is a backend problem, not a client one.
-
----
-
-## Adding iOS later
-
-Implement `ProviderPort` for StoreKit. Nothing else changes.
-
-| Play concept | Port concept | StoreKit |
-|---|---|---|
-| `acknowledge` | `acknowledge` | `Transaction.finish()` |
-| `consume` | `consume` | `Transaction.finish()` on a consumable |
-| base plan / offer | `ProviderOffer` | subscription group / offer |
-| pending purchase | pending `ProviderPurchase` | parental-approval pending transaction |
-| — | `supportsExternalTransactions: true` | externally-initiated purchase |
-
-Consumers add `storeProductIds.ios` to their catalog entries. No product key,
-entitlement key, event name, error code, state value, or message key changes —
-which is the entire point of the boundary.
-
----
-
-## Versioning
-
-Semantic versioning. **Breaking** means any of these changes: the public API
-shape, a product key or entitlement key contract, an error code, an event name, a
-state value, a message key, or the local storage format without a migration.
-
-Local storage carries a schema version and a forward migration chain. A record
-that cannot be migrated is discarded and rebuilt from the store — safe, because
-discarding yields `unknown`, never a false `not_entitled`.
+# @chipmobilesdk/rn-payment
+
+Reusable in-app payment and entitlement capability for ChipMobileSdk-family React
+Native apps. Android only in 0.2.0, via Google Play Billing, behind a contract
+that is neutral with respect to platform and store.
+
+**The package owns capability. Your app owns policy.** The package gives you a
+safe, consistent way to sell, finalize, restore, and report entitlements. What you
+sell, at what price, on which screen, at which moment, what each entitlement
+unlocks, and how generous your grace policy is — all yours. There is no product
+identifier, no screen name, and no business rule in this package.
+
+---
+
+## Contents
+
+- [The one idea that matters](#the-one-idea-that-matters)
+- [Install](#install)
+- [Compatibility](#compatibility)
+- [Quick start](#quick-start)
+- [Catalog and entitlement mapping](#catalog-and-entitlement-mapping)
+- [The entitlement model](#the-entitlement-model)
+- [Purchase flow](#purchase-flow)
+- [Finalization: the invariant you cannot opt out of](#finalization-the-invariant-you-cannot-opt-out-of)
+- [Consumables](#consumables)
+- [Subscriptions](#subscriptions)
+- [Prices and offers](#prices-and-offers)
+- [Sync, restore, and offline](#sync-restore-and-offline)
+- [Environments and the production guard](#environments-and-the-production-guard)
+- [Server-side validation](#server-side-validation)
+- [Localizable copy](#localizable-copy)
+- [Events and errors](#events-and-errors)
+- [Wiring an entitlement to another system](#wiring-an-entitlement-to-another-system)
+- [Testing](#testing)
+- [What is stored on the device](#what-is-stored-on-the-device)
+- [Trust boundary](#trust-boundary)
+- [Play Console checklist](#play-console-checklist)
+- [Play policy checklist](#play-policy-checklist)
+- [Production release checklist](#production-release-checklist)
+- [Known limitations](#known-limitations)
+- [Adding iOS later](#adding-ios-later)
+- [Versioning](#versioning)
+
+---
+
+## The one idea that matters
+
+Your business logic asks about **entitlement keys** you chose — `no_ads`,
+`pro_features` — and never about store product ids, product types, or which store
+sold the thing.
+
+```ts
+const { status } = useEntitlement('no_ads');
+```
+
+`status` is `'unknown' | 'entitled' | 'not_entitled'`. The third state is why this
+package exists: on a cold start we do not yet know whether this user paid, and
+saying so is strictly better than guessing. If you collapse `unknown` into
+`not_entitled`, a paying user watches ads flash before they vanish, or sees a
+purchased feature locked for a second. Render a loading treatment for `unknown`.
+
+---
+
+## Install
+
+```bash
+npm install @chipmobilesdk/rn-payment
+```
+
+Peer dependencies you must install yourself:
+
+```bash
+npm install react-native-iap react-native-mmkv react-native-nitro-modules
+```
+
+- `react-native-iap` — the Play Billing binding. Reached only through this
+  package's Android adapter; you never import it.
+- `react-native-mmkv` — synchronous local storage. Required: it is what lets
+  entitlement reads be synchronous on a render path. Without it entitlements do
+  not survive a cold start and read `unknown` until the first sync, which is safe
+  but degraded.
+- `react-native-nitro-modules` — transitive requirement of `react-native-iap`.
+
+> **Android manifest.** `com.android.vending.BILLING` is declared by the billing
+> library's own `AndroidManifest.xml` and merged into your app automatically. You
+> do **not** add it yourself. No runtime permission is requested and no sensitive
+> API is touched, so there is no permission prompt and no denial path to handle.
+>
+> **Verified state in this repository:** the app manifest at
+> `android/app/src/main/AndroidManifest.xml` declares `INTERNET`, `CAMERA`, and
+> notification permissions, and **no** `BILLING` entry — correct, because the
+> billing library is not installed yet. Once it is, confirm the merged manifest
+> contains exactly one `com.android.vending.BILLING` entry and no new runtime
+> permission:
+>
+> ```bash
+> # After a debug build, inspect the merge report:
+> cat android/app/build/outputs/logs/manifest-merger-debug-report.txt | grep -i billing
+> ```
+
+---
+
+## Compatibility
+
+Verified against this repository's toolchain, not assumed:
+
+| Item | Supported |
+|---|---|
+| React | >= 19 (verified 19.2.3) |
+| React Native | >= 0.85 (verified 0.85.3), New Architecture only |
+| TypeScript | >= 5.8 |
+| Node | >= 22.11.0 |
+| Android `minSdk` / `compileSdk` / `targetSdk` | 24 / 36 / 36 |
+| Kotlin | 2.1.20 |
+| `react-native-iap` | >= 16.6.1 < 17 |
+| `react-native-mmkv` | >= 4.0.0 |
+| `react-native-nitro-modules` | >= 0.36.5 |
+
+**Why the `react-native-iap` ceiling is the next major.** Both the Nitro peer
+requirement and the bundled Play Billing version move on majors, so a major bump
+needs re-verification rather than silent adoption.
+
+> ⚠️ **The Android adapter is written but not yet verified on a device.** Its call
+> shapes follow `react-native-iap` 16.x as documented, and the surface it depends on
+> is declared explicitly in a local `IapModule` interface so a mismatch fails at
+> typecheck rather than at runtime on a user's device. Verify it on a device before
+> shipping.
+>
+> One part *has* been checked against an installed binding (16.7.3): how a purchase's
+> state is read. That check found a defect in `0.1.0` — the binding sends the state as
+> a string, the adapter expected a number, and a pending purchase was granted. Fixed
+> in `0.2.0`; see the changelog.
+
+---
+
+## Quick start
+
+```tsx
+import {
+  PaymentProvider,
+  createStoreProvider,
+  useEntitlement,
+  usePurchase,
+} from '@chipmobilesdk/rn-payment';
+
+const config = {
+  catalog: [
+    {
+      productKey: 'remove_ads',
+      productType: 'one_time_permanent',
+      storeProductIds: { android: 'com.yourapp.remove_ads' },
+      grants: ['no_ads'],
+    },
+  ],
+  entitlements: ['no_ads'],
+  environment: 'production',
+  isProductionBuild: true,
+};
+
+export function App() {
+  return (
+    <PaymentProvider config={config} deps={{ provider: createStoreProvider() }}>
+      <YourApp />
+    </PaymentProvider>
+  );
+}
+
+function AdSlot() {
+  const noAds = useEntitlement('no_ads');
+
+  // Hold while unknown. Do not guess.
+  if (noAds.status === 'unknown') return null;
+  if (noAds.status === 'entitled') return null;
+  return <YourBanner />;
+}
+```
+
+`createStoreProvider()` picks the platform adapter. On a platform with no adapter
+it returns a stub that reports `unavailable` instead of throwing, so your app
+still starts and runs — it only loses the ability to sell.
+
+**Call `handleForeground()` when your app returns to the foreground.** It is left
+to you rather than subscribed internally, because this package must not decide
+what "foreground" means for an app that may be backgrounded by its own modal, a
+biometric prompt, or the store's own purchase sheet. It is rate-limited
+regardless, so calling it liberally is safe.
+
+---
+
+## Catalog and entitlement mapping
+
+The catalog is the whole of your product configuration, and the only place a store
+product id appears.
+
+```ts
+catalog: [
+  {
+    productKey: 'premium_monthly',          // yours
+    productType: 'subscription',
+    storeProductIds: {
+      android: 'com.yourapp.premium.monthly', // Play Console
+      ios: 'com.yourapp.premium.monthly',     // optional, additive
+    },
+    grants: ['no_ads', 'pro_features'],     // yours
+  },
+]
+```
+
+**The mapping is many-to-many.** Several products may grant one entitlement — a
+monthly plan, a yearly plan, and a lifetime unlock all granting `no_ads` — and one
+product may grant several. An entitlement stays valid while **any** granting
+product remains valid, so losing one source does not revoke it.
+
+Validation runs at configure time, before anything connects, and names the
+offending entry. It catches duplicate product keys, a missing store id for the
+current platform, an invalid product type, a product granting nothing, two
+products sharing a store id, an entitlement no product grants, and an entitlement
+granted but never declared. All problems are reported in one pass.
+
+### Creating the products in Play Console
+
+1. Create each product with the exact id you put in `storeProductIds.android`.
+2. One-time products go under **In-app products**; consumables are also in-app
+   products — the *package* decides consumable behaviour via `productType`, not
+   Play.
+3. Subscriptions need a **base plan**, and an **offer** if you want a trial or
+   introductory price.
+4. Activate each product. An inactive product is reported as
+   `not_available_from_store`, distinctly from a network error.
+
+---
+
+## The entitlement model
+
+```ts
+const state = engine.getEntitlement('no_ads');
+// { key, status, sources, subscription?, lastSyncedAt?, isStale }
+```
+
+| Status | Meaning | What to render |
+|---|---|---|
+| `unknown` | Not yet known, or the cached answer went stale | A loading or held treatment |
+| `entitled` | At least one valid source grants it | The paid experience |
+| `not_entitled` | Synced, fresh, and nothing grants it | The unpaid experience |
+
+`unknown` is **re-entrant**, not just an initial state: it returns when cached
+data passes its staleness ceiling. Handle it as a real state, not a startup
+flicker.
+
+`sources` names *your* product keys, so you can show "You're on the yearly plan"
+without touching a transaction record.
+
+Changes are pushed. You never poll.
+
+---
+
+## Purchase flow
+
+```ts
+const result = await engine.purchase('premium_monthly', {
+  // Optional. Passed straight to the store for fraud prevention and never
+  // generated, inferred, or persisted by this package.
+  obfuscatedAccountId: yourOpaqueAccountId,
+  offerKey: selectedOffer.offerKey,
+});
+```
+
+`result.kind` is a discriminated union, and the distinctions matter:
+
+| Kind | What it means | Suggested handling |
+|---|---|---|
+| `success` | Paid and granted | Show the unlocked state |
+| `pending` | Slow payment method; **not granted** | Show a waiting notice, and keep showing it — see [A payment that stays pending](#a-payment-that-stays-pending) |
+| `user_cancelled` | Normal. Not an error | Say nothing |
+| `already_owned` | Store says they own it; a re-sync was triggered | Show the unlocked state |
+| `ineligible` | Not eligible for this offer | Offer an alternative |
+| `unknown_product` | Not in your catalog | Developer bug |
+| `product_unavailable_in_region` | Not sold where they are | Explain |
+| `disabled` | Your global flag is off | Hide the entry point |
+| `not_ready` | Not initialized or connecting | Retry later |
+| `purchase_in_progress` | Another flow is open | Ignore the second tap |
+| `environment_blocked` | Non-production build refused a real charge | Developer-facing |
+| `validation_rejected` | Your backend said no | Explain |
+| `timeout` / `network_error` / `store_error` | Transient or store-side | Offer retry |
+
+**Never report `user_cancelled` as a failure.** Showing an error banner to someone
+who simply changed their mind is the most common paywall bug this union exists to
+prevent.
+
+The purchase surface is rendered by the store. This package neither controls,
+customizes, nor can verify its accessibility — it only reports what happened.
+
+### A payment that stays pending
+
+**New in `0.2.0`.** A slow payment method — cash at a shop, a bank transfer — can
+stay pending for days, long past the session that started it. `purchase()`
+returning `pending` tells you once; the **pending set** keeps telling you, in this
+session and every later one, until the store says how it ended.
+
+```ts
+const pending = engine.getPendingPurchases();         // synchronous, in memory
+engine.subscribePendingPurchases(next => { /* ... */ }); // pushed, never polled
+
+// In React, narrowed to what this screen sells:
+const { status, purchases } = usePendingPurchases(['remove_ads']);
+
+if (status === 'unknown') {
+  // Not known yet, or the snapshot is stale. Do not offer Buy on this.
+} else if (purchases.length > 0) {
+  // Show "payment pending" — the `payment.state.pending` message key —
+  // and withhold Buy, so the user is not charged twice.
+}
+```
+
+Each entry is `{ productKey, since }`: one per product, `since` being when the
+store reports the purchase was made. No transaction id, token, or store object.
+
+**Read `status` before the list.** `unknown` follows the entitlement rule exactly:
+never synced, or synced more than `staleAfterMs` ago. Under `unknown`, `purchases`
+still holds what the last good sync saw, but an empty list there is **not**
+"nothing pending", for the same reason an `unknown` entitlement is not
+`not_entitled`.
+
+**What ends it** — one `purchase_pending_resolved` event per pending transaction,
+carrying `productKey` and an `outcome`:
+
+| Outcome | What happened | What follows |
+|---|---|---|
+| `settled` | The money arrived | `entitlement_granted`, **after** this event, if the product confers one |
+| `cancelled` | It ended without payment: declined, abandoned, or the store gave no reason | Nothing; Buy can come back |
+| `expired` | The store reported the pending window ran out | Nothing; Buy can come back |
+
+On Android you will only ever see `settled` and `cancelled`. Play does not say why
+a pending purchase ended; it simply stops reporting it. So a declined payment and
+an expired one both arrive as `cancelled`, and the package does not guess between
+them from elapsed time. `expired` is there for a store that does report it.
+
+The event fires at the sync, or the store push, that first sees the change: never
+twice for one transaction, never for a sync that changed nothing, and never for
+`clearLocalData()`, which discards records rather than ending them.
+
+Pending still **never grants**, under any configuration. The pending set only
+lets you see it.
+
+---
+
+## Finalization: the invariant you cannot opt out of
+
+Google **auto-refunds and revokes** a purchase that is not acknowledged within
+three days. So acknowledgement is not a step you can forget here: the package
+owns it.
+
+The ordering that makes it safe is: the intent to finalize is written to local
+storage **before** the store call is attempted. A crash before the write leaves
+the purchase still owned, so the next sync re-queues it. A crash after the write
+leaves a queue record, so the next startup drains it. There is no window where a
+paid transaction is forgotten.
+
+Failed attempts retry under bounded backoff. Exhausting a session's budget is
+**not** giving up — the record stays queued and the next launch tries again, which
+is how the package stays inside the three-day window without hammering a store
+that is currently refusing.
+
+```ts
+// Observable rather than swallowed.
+engine.getUnfinalized(); // [{ productKey, transactionId, attempts, purchasedAt }]
+```
+
+Entitlement is granted **before** finalization completes, deliberately: a store
+hiccup must never withhold something already paid for.
+
+---
+
+## Consumables
+
+For a consumable, **you** decide when it counts as consumed, because only you know
+whether the item was actually banked in your own data.
+
+```ts
+const result = await engine.purchase('coin_pack_100');
+if (result.kind === 'success') {
+  await yourDatabase.addCoins(100);   // bank it first
+  await engine.consume(result.transaction); // then tell the store
+}
+```
+
+Until you call `consume`, the store will not allow a repurchase. Consuming twice,
+or concurrently, grants the item exactly once. A consumable never becomes a
+permanent entitlement.
+
+---
+
+## Subscriptions
+
+```ts
+const state = engine.getEntitlement('pro_features');
+state.subscription;
+// { expiresAt?, willAutoRenew, isCancelledButValid, renewalState }
+```
+
+A successful renewal changes nothing, so it emits **no** event — change signals
+come from a diff, which makes that structural rather than a special case.
+
+### Grace and hold policy
+
+```ts
+gracePolicy: 'grant',    // default
+holdPolicy: 'withhold',  // default
+```
+
+A **grace period** means the store is still retrying a payment method that failed
+for reasons usually outside the user's control. Revoking immediately punishes a
+paying customer for a billing hiccup. **Account hold** means the store has given
+up retrying; the subscription is effectively unpaid.
+
+> **Android cannot separate these client-side.** Play returns a grace-period
+> subscription as active and stops returning a held one — making hold
+> indistinguishable from expired, cancelled, or refunded. So `renewalState`
+> reports `indeterminate` rather than inventing the distinction.
+>
+> **The defaults still work with no backend**, because Play's own behaviour
+> matches them: a grace-period purchase keeps being returned (so the entitlement
+> holds) and a held one stops being returned (so it lapses at the next sync). Only
+> a *non-default* policy needs server data, through the validation hook.
+
+### Plan changes
+
+```ts
+await engine.changePlan('premium_monthly', 'premium_yearly', 'immediate_with_time_proration');
+```
+
+| Mode | Effect |
+|---|---|
+| `immediate_with_time_proration` | Switch now, credit unused time. Usual upgrade. |
+| `immediate_and_charge_full_price` | Switch now, charge full price, restart the period. |
+| `immediate_and_charge_prorated_price` | Switch now, charge the difference. |
+| `deferred` | Keep the current plan until it expires. Usual downgrade. |
+
+A plan change goes through the normal purchase flow, so it inherits the
+single-flight lock, the environment guard, validation, and the finalization queue.
+
+### Cancellation
+
+```ts
+await engine.openSubscriptionManagement('premium_monthly');
+```
+
+This opens the **store's** screen. Platforms forbid an app presenting its own
+cancellation screen, so there is deliberately no alternative in this package.
+
+---
+
+## Prices and offers
+
+```ts
+const { products, missing } = await engine.getProducts(['premium_monthly']);
+```
+
+**Render `formattedPrice`. Never build a price string.** Only the store knows the
+right currency symbol, its placement, the decimal separator, and the grouping for
+the user's locale — `1.990 ₫` and `$19.90` are not the same shape. The
+`priceAmountMicros` field exists for sorting and comparison only.
+
+Offer eligibility is **the store's verdict**. Computing it locally would promise a
+trial the store then refuses at checkout.
+
+`missing` separates `not_in_catalog` (your configuration) from
+`not_available_from_store` (unapproved, or not sold in this country), and neither
+is conflated with a network error — so you can explain an absent row instead of
+rendering a blank.
+
+Results are cached in memory for 15 minutes by default, never persisted, and
+`refreshProducts` bypasses the cache.
+
+---
+
+## Sync, restore, and offline
+
+Sync runs automatically at initialization and when you call `handleForeground()`,
+rate-limited to once a minute by default.
+
+```ts
+const outcome = await engine.restore();
+if (outcome.ok && outcome.restored) { /* purchases came back */ }
+else if (outcome.ok) { /* nothing found — say that, not "success" */ }
+```
+
+**"Nothing found" is a distinct success.** Telling a user their purchases were
+restored when none existed is a support ticket.
+
+Entitlements are readable offline from the last successful sync. Past the
+staleness ceiling — **7 days** by default — they become `unknown`, never
+`not_entitled`. Seven days covers a holiday without connectivity while bounding
+how long a refunded entitlement can outlive its refund.
+
+When the store stops reporting a transaction, the entitlement is revoked at the
+next sync. The cache never resurrects it.
+
+**Pending purchases follow the same rules.** They are part of the persisted
+snapshot, so after an app kill — even an offline restart — `getPendingPurchases()`
+still lists them, and past the staleness ceiling it reports `unknown`, never an
+empty "nothing pending". The sync that finds a pending purchase settled, or gone,
+emits `purchase_pending_resolved`. See
+[A payment that stays pending](#a-payment-that-stays-pending).
+
+### Logout and account switching
+
+```ts
+await engine.clearLocalData();
+```
+
+If your app has its own accounts, also supply a `scopeToken`:
+
+```ts
+scopeToken: opaqueHashOfYourUserId,
+```
+
+Cached entitlements are partitioned by it, so a second user cannot inherit the
+first user's entitlements even if you forget to call `clearLocalData`. The token is
+a cache-partition key — never interpreted, transmitted, or attached to a
+transaction — and is distinct from `obfuscatedAccountId`.
+
+---
+
+## Environments and the production guard
+
+```ts
+environment: 'development' | 'test' | 'production',
+isProductionBuild: boolean,  // you supply this; only you know how you built
+```
+
+Two layers:
+
+1. **Fail closed at construction.** A non-production build declaring `production`
+   throws `PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD` and never connects.
+2. **Runtime block.** Outside production, any chargeable purchase is refused,
+   recorded in `getStatus().blockedOperations`, and emitted as
+   `environment_blocked` — observable in state, so a test can assert it rather
+   than scraping logs.
+
+> **Why this blocks where `@chipmobilesdk/rn-ads` substitutes.** The ads package
+> swaps in Google's official *test ad units* when a non-production build supplies
+> production ones, keeping the app working. Play has no equivalent test **product**
+> id — testing uses licence-tester *accounts* against real product ids — so
+> substitution is impossible here. Blocking with an observable refusal is the only
+> honest option, and the asymmetry is deliberate rather than an inconsistency.
+
+---
+
+## Server-side validation
+
+Optional. Without it the package is fully functional client-side.
+
+```ts
+validateTransaction: async candidate => {
+  const verdict = await fetch('https://your.api/verify', {
+    method: 'POST',
+    body: JSON.stringify(candidate),
+  }).then(r => r.json());
+  return { approved: verdict.ok, reason: verdict.reason };
+},
+onValidationUnavailable: 'grant_and_queue', // default
+```
+
+**The hook runs for newly completed purchases only.** Purchases seen during sync
+or restore are not resubmitted — which is what keeps restore and foreground sync
+working while your backend is down. Revocation still flows from the store.
+
+**When the backend is unreachable, the default grants and queues.** The store has
+already confirmed payment, so withholding would punish a paying user for your
+outage. The queued transaction is re-validated on a later sync, and a rejection
+then revokes — which bounds the exposure this default accepts. Choose `'withhold'`
+if your threat model requires it.
+
+A hook that throws is treated as unavailable, never as an implicit approval.
+
+This package calls **no endpoint** other than the platform's billing service. All
+other traffic is your own code, through this hook.
+
+---
+
+## Localizable copy
+
+The package exports message keys with English defaults and takes no i18n runtime
+dependency.
+
+```ts
+import { DEFAULT_USER_MESSAGES, USER_MESSAGE_KEYS, isUserMessageKey } from '@chipmobilesdk/rn-payment';
+```
+
+User-actionable and developer copy are **separate maps**, so you cannot
+accidentally show "Payment catalog is invalid" to a customer. `isUserMessageKey()`
+lets you assert that at your own boundary.
+
+Message keys are public API; renaming one is a breaking change.
+
+---
+
+## Events and errors
+
+20 event types, each carrying a timestamp and — within a purchase cycle — one
+`correlationId`. The bar is that the event stream **alone** is enough to
+reconstruct a transaction's lifecycle, so "the user says they paid but has no
+entitlement" can be investigated from logs without a reproduction.
+
+Ordering for a successful purchase:
+
+```text
+purchase_started → purchase_succeeded → [validation_decided] → entitlement_granted → transaction_finalized
+```
+
+And for one that goes pending, possibly across sessions:
+
+```text
+purchase_started → purchase_pending
+  … later …
+purchase_pending_resolved (settled) → [validation_decided] → entitlement_granted → transaction_finalized
+purchase_pending_resolved (cancelled | expired)
+```
+
+Exactly-once guarantees: one grant per transition (not per source), one revocation
+per transition, no event for a renewal that changed nothing, one finalize per
+transaction however many times it is retried, one resolution per pending
+transaction, and **nothing at all after cleanup**.
+
+**Never present in an event payload**: store objects, raw receipts, verification
+payloads, backend tokens, payment details, the obfuscated account id, or the cache
+scope token.
+
+A listener that throws cannot corrupt the state machine or stop other listeners.
+The failure goes to your `logger`, not back into the event stream.
+
+Errors carry a stable `code`, a log-safe `message`, the `operation`, a `retryable`
+flag, and a redacted `cause`. Error codes are public API.
+
+---
+
+## Wiring an entitlement to another system
+
+**This is your job, and that is the point.** This package references no
+advertising package, and no advertising package references it.
+
+```ts
+// Your app. The whole integration.
+function enablementForEntitlement(status) {
+  if (status === 'entitled') return 'disabled';   // they paid not to see ads
+  if (status === 'not_entitled') return 'enabled'; // confirmed unpaid
+  return 'undecided';                              // not yet known — hold
+}
+
+engine.subscribeEntitlements(map => {
+  ads.setEnabled(enablementForEntitlement(map.no_ads.status));
+});
+```
+
+The middle line is why `unknown` exists. Enabling while waiting flashes an ad at
+someone who paid not to see one; disabling while waiting costs revenue on every
+other user's first screen. Holding is a deliberate choice made with real
+information.
+
+A worked version is in the demo app at `src/payment/adsWiring.ts`.
+
+---
+
+## Testing
+
+```ts
+import { createFakeStore, makePurchase } from '@chipmobilesdk/rn-payment/testing';
+
+const store = createFakeStore();
+const engine = createEngine(config, { provider: store });
+
+store.scriptPurchaseSuccess({ storeProductId: 'com.yourapp.remove_ads' });
+await engine.purchase('remove_ads');
+```
+
+The fake store drives every purchase outcome, both callback orderings, pending
+settlement across sessions, connection loss and recovery, refunds, failing
+acknowledgement, and an app-kill simulation (drop memory, keep the snapshot,
+restart). No device, no network, no store account, no real money.
+
+Ending a pending purchase changes store-side state only, as the real store does,
+so the engine sees it at its next sync — in this session or after a simulated
+app kill:
+
+```ts
+store.scriptPurchasePending({ transactionId: 'txn_1' });
+await engine.purchase('remove_ads');       // pending
+
+store.settlePending('txn_1');   // the money arrives        → settled
+store.cancelPending('txn_1');   // declined or abandoned     → cancelled
+store.expirePending('txn_1');   // the window ran out        → expired
+store.pushPurchaseUpdate(...);  // deliver a settlement with no sync
+```
+
+`./testing` is a separate entrypoint so test doubles cannot reach a production
+bundle.
+
+### Licence testers, for device verification
+
+1. Play Console → **Setup → Licence testing**, add tester accounts.
+2. Publish to at least one testing track. **In-app products do not work at all
+   for a build that has never been uploaded to Play.**
+3. Sign in on the device with a licence tester account.
+4. Use a shortened subscription renewal cycle to observe the lifecycle.
+
+Never use a production transaction as a verification step.
+
+---
+
+## What is stored on the device
+
+Exhaustively, for your Data safety declaration:
+
+| Stored | Why |
+|---|---|
+| Entitlement keys and their states | So entitlements are readable offline |
+| Granting product keys | So you can show the current plan |
+| Subscription expiry and renewal status | So lifecycle is readable offline |
+| Unfinished-transaction records (transaction id, product key, token, attempt count) | So a paid purchase is never lost to an app kill |
+| Pending-purchase records (the same fields, plus the time the store reports the purchase was made) | So a payment still in flight is visible after an app kill. Unchanged since `0.1.0`; `0.2.0` only reads them |
+| Last successful sync time | So data age is observable |
+| Schema version | So the record can be migrated |
+| Your `scopeToken`, if you supply one | Solely to partition the record |
+
+**Not stored**: payment details, card data, billing addresses, user identity, raw
+receipts, verification payloads, backend tokens.
+
+Stored in MMKV under the instance id `chipmobilesdk.payment`. `clearLocalData()`
+erases all of it. On Android, declare backup exclusion in your app's
+`data_extraction_rules.xml` if you do not want the record restored to a new
+device — the snapshot is rebuilt from the store anyway.
+
+---
+
+## Trust boundary
+
+**Client-side entitlement data can be tampered with on a compromised device.** A
+rooted user can edit local storage. This package does not claim otherwise, and it
+does not pretend encryption would help: anything the device can decrypt, its owner
+can decrypt.
+
+**Only server-side validation is a real defence.** If your product can be
+meaningfully abused, use the validation hook with a backend that verifies receipts
+against the Play Developer API.
+
+---
+
+## Play Console checklist
+
+- [ ] Developer account **payments profile** completed — without it nothing is
+      sellable.
+- [ ] Each in-app product created with the exact id from your catalog, and
+      **activated**.
+- [ ] Subscriptions have a base plan, and an offer if you want a trial.
+- [ ] Prices set per country; tax settings configured.
+- [ ] Licence testers added.
+- [ ] App published to at least one testing track.
+- [ ] Shortened renewal cycles enabled for lifecycle testing.
+- [ ] Review notes describe how a reviewer reaches purchasable content.
+- [ ] A demo account supplied if your paywall sits behind a login.
+- [ ] Real-time developer notifications configured, if you have a backend.
+
+---
+
+## Play policy checklist
+
+Your obligations as the app owner — this package cannot discharge them for you:
+
+- [ ] In-app digital goods use Play's billing system. This package provides **no
+      route** to alternative billing, user-choice billing, or an external purchase
+      call to action.
+- [ ] Price, billing period, renewal terms, trial conditions, and how to cancel
+      are disclosed **before** payment, where the user can see them.
+- [ ] A route to the store's subscription management screen is reachable in-app.
+- [ ] A "Restore purchases" control is reachable in-app.
+- [ ] Data safety declaration reflects the stored-data list above plus the billing
+      library's own behaviour.
+- [ ] Privacy policy and terms of sale are valid and current.
+- [ ] Refund requests handled per platform policy.
+- [ ] Auto-renewal legal requirements met for each market you sell in.
+
+---
+
+## Production release checklist
+
+- [ ] `environment: 'production'` and `isProductionBuild: true` only in release
+      builds.
+- [ ] `npm pack --dry-run` output contains no store product id, credential, or
+      secret.
+- [ ] The Android adapter verified against the installed `react-native-iap`
+      version.
+- [ ] All three product types purchased on a device with a licence tester.
+- [ ] A pending purchase settled via a slow test payment method.
+- [ ] Restore verified after uninstall and reinstall.
+- [ ] Subscription lifecycle observed on shortened cycles.
+- [ ] Entitlements readable in airplane mode.
+- [ ] App starts and runs on a device without Play services.
+- [ ] Store-side records show **zero** production transactions from
+      development/test builds. Retain as release evidence.
+
+---
+
+## Known limitations
+
+1. **Grace period and account hold are not separable on Android** client-side. See
+   [Subscriptions](#subscriptions). The defaults work with no backend; a
+   non-default policy needs server data.
+2. **iOS is contract-only.** `createStoreProvider()` returns an `unavailable` stub
+   on iOS; the host app still starts and runs.
+3. **The Android adapter is unverified on a device.** Only its purchase-state
+   mapping has been checked against an installed binding. See
+   [Compatibility](#compatibility).
+4. **Price-change confirmation is unsupported on Android.** Play notifies the user
+   itself and offers no client-side flow, so `confirmPriceChange` reports
+   `unsupported` rather than faking a confirmation.
+5. **Client-side entitlement is forgeable.** See
+   [Trust boundary](#trust-boundary).
+6. **Cross-platform entitlement sync is out of scope.** One user with an Android
+   and an iOS device is a backend problem, not a client one.
+7. **On Android, an unpaid pending purchase always ends as `cancelled`.** Play does
+   not report whether it was declined or expired, and the package will not guess
+   from elapsed time. See [A payment that stays pending](#a-payment-that-stays-pending).
+
+---
+
+## Adding iOS later
+
+Implement `ProviderPort` for StoreKit. Nothing else changes.
+
+| Play concept | Port concept | StoreKit |
+|---|---|---|
+| `acknowledge` | `acknowledge` | `Transaction.finish()` |
+| `consume` | `consume` | `Transaction.finish()` on a consumable |
+| base plan / offer | `ProviderOffer` | subscription group / offer |
+| pending purchase | pending `ProviderPurchase` | parental-approval pending transaction |
+| — (not reported) | `pendingEndReason` (optional) | why a pending transaction ended, if StoreKit says |
+| — | `supportsExternalTransactions: true` | externally-initiated purchase |
+
+Consumers add `storeProductIds.ios` to their catalog entries. No product key,
+entitlement key, event name, error code, state value, or message key changes —
+which is the entire point of the boundary.
+
+---
+
+## Versioning
+
+Semantic versioning. **Breaking** means any of these changes: the public API
+shape, a product key or entitlement key contract, an error code, an event name, a
+state value, a message key, or the local storage format without a migration.
+
+Local storage carries a schema version and a forward migration chain. A record
+that cannot be migrated is discarded and rebuilt from the store — safe, because
+discarding yields `unknown`, never a false `not_entitled`.
+
+### Migrating `0.1.0` to `0.2.0`
+
+**One union gained a member**, so an exhaustive `switch` over it needs the new
+case or a `default`:
+
+| Union | New member |
+|---|---|
+| `PaymentEventType` / `PaymentEvent` | `'purchase_pending_resolved'`, carrying `{ productKey, outcome }` |
+
+Everything else is additive, and `0.1.0` call sites compile and behave unchanged:
+
+| Addition | Kind |
+|---|---|
+| `PaymentEngine.getPendingPurchases()`, `subscribePendingPurchases()` | new methods |
+| `usePendingPurchases(productKeys?)` | new hook |
+| `PendingPurchase`, `PendingPurchasesState`, `PendingResolution` | new types |
+| Fake store (`./testing`): `settlePending`, `cancelPending`, `expirePending` | new methods |
+
+A hand-written `PaymentEngine` implementation, typically a test mock, needs the two
+new methods.
+
+**No storage migration.** The schema stays at version 1: pending records were
+already persisted by `0.1.0`, and `0.2.0` only reads them. A device upgrading with
+a payment in flight sees it in the pending set at first launch.
+
+**Replacing an app-side workaround.** If you kept your own "pending since" marker
+because `0.1.0` could not show a pending payment in a later session, drop it for
+`usePendingPurchases`. The marker had to guess when to give up, so a declined
+payment kept showing "pending" until it expired. The pending set clears at the
+sync that sees the payment end.