@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,761 @@
-# Temporary Holding Version
+# @chipmobilesdk/rn-payment
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`.