@chipmobilesdk/rn-payment 0.3.0 → 0.4.0

package/README.md

@@ -112,7 +112,7 @@ Verified against this repository's toolchain, not assumed:
 | Node | >= 22.11.0 |
 | Android `minSdk` / `compileSdk` / `targetSdk` | 24 / 36 / 36 |
 | Kotlin | 2.1.20 |
-| `react-native-iap` | >= 16.6.1 < 17 |
+| `react-native-iap` | >= 16.7.3 < 17 (verified 16.7.3) |
 | `react-native-mmkv` | >= 4.0.0 |
 | `react-native-nitro-modules` | >= 0.36.5 |
 
@@ -120,16 +120,18 @@ Verified against this repository's toolchain, not assumed:
 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.
+> ⚠️ **Use `0.3.1` or later.** Up to `0.3.0` the Android adapter followed
+> `react-native-iap` 16.x as documented, not as installed, and on a device **no
+> purchase could complete**: the request used the pre-16.7 `android` key, which the
+> binding rejects before Play opens. `0.3.1` was checked call by call against the
+> installed 16.7.3 source, types its request with the binding's own
+> `RequestPurchaseProps` (a renamed key now fails to typecheck), and is tested
+> against a fake binding that behaves as 16.7.3 does. Still confirm one licence-tester
+> purchase 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.
+> Earlier, the same check of how a purchase's state is read 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.
 
 ---
 
@@ -572,7 +574,14 @@ 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.
+A hook that throws is treated as unavailable, never as an implicit approval. So is
+one that does not answer within `timeouts.validateMs` (default 15 s): the purchase
+result and the purchase lock never wait on your backend indefinitely.
+
+**Re-validation carries `transactionId`, not a payload.** Verification material is
+never persisted, so a queued transaction is re-checked with `verificationPayload: ''`.
+Every candidate carries `transactionId` (Play's order id) and `platform`, which is
+what your backend looks the purchase up by on that second call.
 
 This package calls **no endpoint** other than the platform's billing service. All
 other traffic is your own code, through this hook.

package/package.json

@@ -1,54 +1,54 @@
-{
-	"name": "@chipmobilesdk/rn-payment",
-	"version": "0.3.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/adapter",
-		"src/config",
-		"src/core",
-		"src/diagnostics",
-		"src/engine",
-		"src/entitlements",
-		"src/persistence",
-		"src/react",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-iap": ">=16.6.1 <17",
-		"react-native-mmkv": ">=4.0.0",
-		"react-native-nitro-modules": ">=0.36.5"
-	},
-	"keywords": [
-		"react-native",
-		"in-app-purchase",
-		"subscriptions",
-		"entitlements"
-	]
-}
+{
+	"name": "@chipmobilesdk/rn-payment",
+	"version": "0.4.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/adapter",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/engine",
+		"src/entitlements",
+		"src/persistence",
+		"src/react",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-iap": ">=16.7.3 <17",
+		"react-native-mmkv": ">=4.0.0",
+		"react-native-nitro-modules": ">=0.36.5"
+	},
+	"keywords": [
+		"react-native",
+		"in-app-purchase",
+		"subscriptions",
+		"entitlements"
+	]
+}

package/skills/sdk-rn-payment/SKILL.md

@@ -1,168 +1,174 @@
----
-name: sdk-rn-payment
-description: "In-app payments via @chipmobilesdk/rn-payment: Play Billing one-time/consumable/subscription behind a store-neutral contract, entitlement keys with a required unknown state, pending purchases visible across sessions, guaranteed transaction finalization, per-environment production-transaction blocking. Use when selling a feature, gating on an entitlement, showing a payment still pending after a restart, debugging a purchase that returns environment_blocked or an entitlement stuck at unknown, mapping Play products to entitlement keys, or answering a Data safety question about purchases."
-metadata:
-  package: "@chipmobilesdk/rn-payment"
-  packageVersion: "0.3.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-payment
-
-One-time, consumable and subscription purchases on Android via Google Play Billing,
-behind a contract that names no store. The app asks about **entitlement keys** it chose;
-the package owns the transaction. Consuming code never imports the billing library.
-
-## Use this when
-
-- Selling a feature, or gating one on an entitlement
-- Showing "payment pending" — in this session or after a restart — and withholding Buy
-- Mapping Play product ids to entitlement keys
-- Debugging a purchase that returns `environment_blocked`, or an entitlement stuck at
-  `unknown`
-- Wiring `no_ads` (or any entitlement) to another system
-- Answering a Data safety / Play policy question about purchases
-
-## Do not use this for
-
-- **Paywall UI, pricing strategy, or when to offer** — the package ships no paywall, no
-  price table and no purchase button, and chooses no moment.
-- **What an entitlement unlocks** — it reports `entitled`; the meaning is the app's.
-- **Cancellation UI** — platforms forbid a self-built one. Use
-  `openSubscriptionManagement()`, which opens the store's.
-- **Receipt verification** — `validateTransaction` is a hook for *your* backend; the
-  package calls no endpoint but the billing service.
-- iOS — contract only. `createStoreProvider()` returns an `unavailable` stub.
-
-## `unknown` is a real state, and collapsing it is the defect this package exists to prevent
-
-`getEntitlement()` returns `unknown | entitled | not_entitled`. On a cold start the answer
-is genuinely not known yet, and the package says so rather than guessing. Treat `unknown`
-as "wait", never as "unpaid":
-
-```tsx
-if (state.status === 'unknown') return <Loading />;   // not the unpaid branch
-```
-
-Collapse it and a paying user watches ads flash before they vanish, or sees a purchased
-feature locked for a second. It is also **re-entrant** — a cached answer returns to
-`unknown` past its staleness ceiling (7 days by default), so it is not merely a startup
-flicker. See `## The entitlement model`.
-
-## Pending is observable across sessions — never keep your own marker
-
-New in 0.2.0. `usePendingPurchases(productKeys?)` (or `getPendingPurchases()` /
-`subscribePendingPurchases()`) lists `{ productKey, since }` for payments still in flight,
-read from the persisted snapshot, so it survives an app kill and an offline restart. Same
-rule as entitlements: check `status` first — `unknown` is not "nothing pending". Show the
-existing `payment.state.pending` message key and withhold Buy while listed.
-`purchase_pending_resolved` (`settled` → then `entitlement_granted`, or `cancelled` /
-`expired`) fires once when it ends. On Android an unpaid end is always `cancelled`: Play
-does not say why. See `### A payment that stays pending` under `## Purchase flow`.
-
-## A debug build cannot buy anything, and that is the guard working
-
-`purchase()` returning `environment_blocked` in development is correct, not a bug. The
-rule: a chargeable purchase is permitted only when `environment: 'production'` **and**
-`isProductionBuild: true`. A non-production build declaring `production` throws
-`PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD` at construction and never connects.
-
-Consequence worth knowing before you plan device testing: **licence-tester purchases are
-real Play transactions**, so verifying them needs a release-configuration build
-(`isProductionBuild: !__DEV__`, `environment: 'production'`) installed from a Play track.
-Debug builds are structurally unable to reach the store. Drive every behaviour that is
-not "does Play accept this" through the fake store instead. See
-`## Environments and the production guard`.
-
-Unlike `@chipmobilesdk/rn-ads`, there is **no test-id substitution**: Play has no test
-*product* id, so blocking is the only honest option.
-
-## Two more things not to "fix"
-
-- **Finalization is not yours to call** for non-consumables. Google auto-refunds an
-  unacknowledged purchase after three days, so the package owns a persisted queue drained
-  at startup and on foreground. A **consumable** is the exception: call `consume()` after
-  *your* data records the item, because only you know it was banked.
-- **`renewalState: 'indeterminate'` on Android is honest.** Play returns a grace-period
-  subscription as active and stops returning a held one, so the two are not separable
-  client-side. The default policy (`grant` in grace, `withhold` on hold) is nonetheless
-  correct with no backend, because Play's own behaviour matches it. A *non-default* policy
-  needs server data through the validation hook.
-
-Call `handleForeground()` yourself on app resume — the package will not guess what
-"foreground" means for a host backgrounded by its own modal or the store's purchase sheet.
-
-## Public API (v0.3.0)
-
-Runtime: `createEngine` (throws `PaymentConfigError` on a bad catalog or an unsafe
-environment; everything else returns a typed result) · `createStoreProvider` ·
-`PaymentProvider`, `usePaymentEngine` · `useEntitlement`, `useEntitlements`,
-`usePendingPurchases`, `usePaymentStatus`, `usePurchase`, `useProducts`, `useSync` ·
-`PaymentError`,
-`PaymentConfigError`, `PAYMENT_ERROR_CODES` · `DEFAULT_MESSAGES`,
-`DEFAULT_USER_MESSAGES`, `DEFAULT_DEVELOPER_MESSAGES`, `USER_MESSAGE_KEYS`,
-`DEVELOPER_MESSAGE_KEYS`, `isUserMessageKey` · timeout/retry/cache defaults and bounds
-(`DEFAULT_STALE_AFTER_MS`, `DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS`, `STALE_AFTER_BOUNDS`, …)
-· `createFakeStore`, `makePurchase` from `@chipmobilesdk/rn-payment/testing` (test
-doubles only).
-
-Engine: `initialize`, `cleanup`, `getStatus`, `subscribeStatus`, `getEntitlement`,
-`getAllEntitlements`, `subscribeEntitlements`, `getPendingPurchases`,
-`subscribePendingPurchases`, `purchase`, `consume`, `getUnfinalized`,
-`getProducts`, `refreshProducts`, `changePlan`, `openSubscriptionManagement`,
-`confirmPriceChange`, `sync`, `restore`, `getLastSyncedAt`, `clearLocalData`,
-`handleForeground`, `subscribeEvents`.
-
-Types: `PaymentConfig`, `CatalogEntry`, `ProductType`, `StoreProductIds`,
-`EntitlementKey`, `ProductKey`, `EntitlementState`, `EntitlementStatus`,
-`EntitlementMap`, `SubscriptionDetail`, `RenewalState`, `PendingPurchase`,
-`PendingPurchasesState`, `PendingResolution`, `PurchaseResult`,
-`PurchaseOptions`, `TransactionRef`, `FinalizeResult`, `UnfinalizedSummary`,
-`ProductInfo`, `Offer`, `ProductQueryResult`, `MissingProduct`, `ProrationMode`,
-`PriceChangeResult`, `PaymentStatus`, `PaymentStatusKind`, `UnavailableReason`,
-`Environment`, `LapsePolicy`, `ValidationHook`, `ValidationCandidate`,
-`ValidationDecision`, `ValidationUnavailablePolicy`, `SyncOutcome`, `RestoreOutcome`,
-`InitOutcome`, `PaymentEvent`, `PaymentErrorCode`, `LoggerAdapter`, `Unsubscribe`.
-
-`cleanup()` is idempotent, and so is every `Unsubscribe`. After cleanup no event fires.
-
-## Upgrading 0.1.0 → 0.2.0
-
-One compile-time change: `PaymentEventType` gained `'purchase_pending_resolved'`, so an
-exhaustive `switch` needs the case or a `default`. A hand-written `PaymentEngine` mock
-needs the two pending methods. No storage migration (schema unchanged). Replace any
-app-side "pending since" marker with `usePendingPurchases`.
-
-**Require `0.2.1` or later.** Earlier versions opened MMKV with the v3 constructor, which
-react-native-mmkv v4 does not have, so on a device nothing persisted: owners read
-`unknown` after every cold start and pending payments vanished after a kill.
-
-**Upgrade before shipping on Android.** In `0.1.0` the adapter misread `react-native-iap`
-16.x's string purchase state, so on a device a pending purchase was granted. `0.2.0`
-reads it correctly, and an unrecognized (`unspecified`) state never grants or finalizes.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-payment/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Quick start` |
-| Catalog and Play Console product setup | `## Catalog and entitlement mapping` |
-| Entitlement states and staleness | `## The entitlement model` |
-| Every purchase outcome and how to handle it | `## Purchase flow` |
-| A payment pending across sessions, and how it ends | `### A payment that stays pending` |
-| Why acknowledgement is not yours | `## Finalization: the invariant you cannot opt out of` |
-| Consumables | `## Consumables` |
-| Grace/hold, plan change, cancellation | `## Subscriptions` |
-| Prices, offers, trial eligibility | `## Prices and offers` |
-| Restore, offline, logout, account switch | `## Sync, restore, and offline` |
-| `environment_blocked`, release config | `## Environments and the production guard` |
-| Backend verification | `## Server-side validation` |
-| Events, ordering, error codes | `## Events and errors` |
-| Wiring an entitlement to ads | `## Wiring an entitlement to another system` |
-| Tests and licence testers | `## Testing` |
-| Data safety, permissions | `## What is stored on the device`, `## Play policy checklist` |
-| Before release | `## Production release checklist` |
-| What is deferred | `## Known limitations`, `## Adding iOS later` |
+---
+name: sdk-rn-payment
+description: "In-app payments via @chipmobilesdk/rn-payment: Play Billing one-time/consumable/subscription behind a store-neutral contract, entitlement keys with a required unknown state, pending purchases visible across sessions, guaranteed transaction finalization, per-environment production-transaction blocking. Use when selling a feature, gating on an entitlement, showing a payment still pending after a restart, debugging a purchase that returns environment_blocked or an entitlement stuck at unknown, mapping Play products to entitlement keys, or answering a Data safety question about purchases."
+metadata:
+  package: "@chipmobilesdk/rn-payment"
+  packageVersion: "0.3.1"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-payment
+
+One-time, consumable and subscription purchases on Android via Google Play Billing,
+behind a contract that names no store. The app asks about **entitlement keys** it chose;
+the package owns the transaction. Consuming code never imports the billing library.
+
+## Use this when
+
+- Selling a feature, or gating one on an entitlement
+- Showing "payment pending" — in this session or after a restart — and withholding Buy
+- Mapping Play product ids to entitlement keys
+- Debugging a purchase that returns `environment_blocked`, or an entitlement stuck at
+  `unknown`
+- Wiring `no_ads` (or any entitlement) to another system
+- Answering a Data safety / Play policy question about purchases
+
+## Do not use this for
+
+- **Paywall UI, pricing strategy, or when to offer** — the package ships no paywall, no
+  price table and no purchase button, and chooses no moment.
+- **What an entitlement unlocks** — it reports `entitled`; the meaning is the app's.
+- **Cancellation UI** — platforms forbid a self-built one. Use
+  `openSubscriptionManagement()`, which opens the store's.
+- **Receipt verification** — `validateTransaction` is a hook for *your* backend; the
+  package calls no endpoint but the billing service.
+- iOS — contract only. `createStoreProvider()` returns an `unavailable` stub.
+
+## `unknown` is a real state, and collapsing it is the defect this package exists to prevent
+
+`getEntitlement()` returns `unknown | entitled | not_entitled`. On a cold start the answer
+is genuinely not known yet, and the package says so rather than guessing. Treat `unknown`
+as "wait", never as "unpaid":
+
+```tsx
+if (state.status === 'unknown') return <Loading />;   // not the unpaid branch
+```
+
+Collapse it and a paying user watches ads flash before they vanish, or sees a purchased
+feature locked for a second. It is also **re-entrant** — a cached answer returns to
+`unknown` past its staleness ceiling (7 days by default), so it is not merely a startup
+flicker. See `## The entitlement model`.
+
+## Pending is observable across sessions — never keep your own marker
+
+New in 0.2.0. `usePendingPurchases(productKeys?)` (or `getPendingPurchases()` /
+`subscribePendingPurchases()`) lists `{ productKey, since }` for payments still in flight,
+read from the persisted snapshot, so it survives an app kill and an offline restart. Same
+rule as entitlements: check `status` first — `unknown` is not "nothing pending". Show the
+existing `payment.state.pending` message key and withhold Buy while listed.
+`purchase_pending_resolved` (`settled` → then `entitlement_granted`, or `cancelled` /
+`expired`) fires once when it ends. On Android an unpaid end is always `cancelled`: Play
+does not say why. See `### A payment that stays pending` under `## Purchase flow`.
+
+## A debug build cannot buy anything, and that is the guard working
+
+`purchase()` returning `environment_blocked` in development is correct, not a bug. The
+rule: a chargeable purchase is permitted only when `environment: 'production'` **and**
+`isProductionBuild: true`. A non-production build declaring `production` throws
+`PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD` at construction and never connects.
+
+Consequence worth knowing before you plan device testing: **licence-tester purchases are
+real Play transactions**, so verifying them needs a release-configuration build
+(`isProductionBuild: !__DEV__`, `environment: 'production'`) installed from a Play track.
+Debug builds are structurally unable to reach the store. Drive every behaviour that is
+not "does Play accept this" through the fake store instead. See
+`## Environments and the production guard`.
+
+Unlike `@chipmobilesdk/rn-ads`, there is **no test-id substitution**: Play has no test
+*product* id, so blocking is the only honest option.
+
+## Two more things not to "fix"
+
+- **Finalization is not yours to call** for non-consumables. Google auto-refunds an
+  unacknowledged purchase after three days, so the package owns a persisted queue drained
+  at startup and on foreground. A **consumable** is the exception: call `consume()` after
+  *your* data records the item, because only you know it was banked.
+- **`renewalState: 'indeterminate'` on Android is honest.** Play returns a grace-period
+  subscription as active and stops returning a held one, so the two are not separable
+  client-side. The default policy (`grant` in grace, `withhold` on hold) is nonetheless
+  correct with no backend, because Play's own behaviour matches it. A *non-default* policy
+  needs server data through the validation hook.
+
+Call `handleForeground()` yourself on app resume — the package will not guess what
+"foreground" means for a host backgrounded by its own modal or the store's purchase sheet.
+
+## Public API (v0.4.0)
+
+Runtime: `createEngine` (throws `PaymentConfigError` on a bad catalog or an unsafe
+environment; everything else returns a typed result) · `createStoreProvider` ·
+`PaymentProvider`, `usePaymentEngine` · `useEntitlement`, `useEntitlements`,
+`usePendingPurchases`, `usePaymentStatus`, `usePurchase`, `useProducts`, `useSync` ·
+`PaymentError`,
+`PaymentConfigError`, `PAYMENT_ERROR_CODES` · `DEFAULT_MESSAGES`,
+`DEFAULT_USER_MESSAGES`, `DEFAULT_DEVELOPER_MESSAGES`, `USER_MESSAGE_KEYS`,
+`DEVELOPER_MESSAGE_KEYS`, `isUserMessageKey` · timeout/retry/cache defaults and bounds
+(`DEFAULT_STALE_AFTER_MS`, `DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS`, `STALE_AFTER_BOUNDS`, …)
+· `createFakeStore`, `makePurchase` from `@chipmobilesdk/rn-payment/testing` (test
+doubles only).
+
+Engine: `initialize`, `cleanup`, `getStatus`, `subscribeStatus`, `getEntitlement`,
+`getAllEntitlements`, `subscribeEntitlements`, `getPendingPurchases`,
+`subscribePendingPurchases`, `purchase`, `consume`, `getUnfinalized`,
+`getProducts`, `refreshProducts`, `changePlan`, `openSubscriptionManagement`,
+`confirmPriceChange`, `sync`, `restore`, `getLastSyncedAt`, `clearLocalData`,
+`handleForeground`, `subscribeEvents`.
+
+Types: `PaymentConfig`, `CatalogEntry`, `ProductType`, `StoreProductIds`,
+`EntitlementKey`, `ProductKey`, `EntitlementState`, `EntitlementStatus`,
+`EntitlementMap`, `SubscriptionDetail`, `RenewalState`, `PendingPurchase`,
+`PendingPurchasesState`, `PendingResolution`, `PurchaseResult`,
+`PurchaseOptions`, `TransactionRef`, `FinalizeResult`, `UnfinalizedSummary`,
+`ProductInfo`, `Offer`, `ProductQueryResult`, `MissingProduct`, `ProrationMode`,
+`PriceChangeResult`, `PaymentStatus`, `PaymentStatusKind`, `UnavailableReason`,
+`Environment`, `LapsePolicy`, `ValidationHook`, `ValidationCandidate`,
+`ValidationDecision`, `ValidationUnavailablePolicy`, `SyncOutcome`, `RestoreOutcome`,
+`InitOutcome`, `PaymentEvent`, `PaymentErrorCode`, `LoggerAdapter`, `Unsubscribe`.
+
+`cleanup()` is idempotent, and so is every `Unsubscribe`. After cleanup no event fires.
+
+## Upgrading 0.1.0 → 0.2.0
+
+One compile-time change: `PaymentEventType` gained `'purchase_pending_resolved'`, so an
+exhaustive `switch` needs the case or a `default`. A hand-written `PaymentEngine` mock
+needs the two pending methods. No storage migration (schema unchanged). Replace any
+app-side "pending since" marker with `usePendingPurchases`.
+
+**Require `0.3.1` or later on Android.** Up to `0.3.0` no purchase could complete on a
+device: the adapter sent `react-native-iap`'s pre-16.7 request key (`android`), rejected
+before Play opens, and read the binding's always-empty resolved value instead of its
+outcome events. `0.3.1` needs `react-native-iap` >= 16.7.3. If a purchase returns
+`store_error` at once, check the installed binding against that range first.
+
+**Require `0.2.1` or later.** Earlier versions opened MMKV with the v3 constructor, which
+react-native-mmkv v4 does not have, so on a device nothing persisted: owners read
+`unknown` after every cold start and pending payments vanished after a kill.
+
+**Upgrade before shipping on Android.** In `0.1.0` the adapter misread `react-native-iap`
+16.x's string purchase state, so on a device a pending purchase was granted. `0.2.0`
+reads it correctly, and an unrecognized (`unspecified`) state never grants or finalizes.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-payment/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Quick start` |
+| Catalog and Play Console product setup | `## Catalog and entitlement mapping` |
+| Entitlement states and staleness | `## The entitlement model` |
+| Every purchase outcome and how to handle it | `## Purchase flow` |
+| A payment pending across sessions, and how it ends | `### A payment that stays pending` |
+| Why acknowledgement is not yours | `## Finalization: the invariant you cannot opt out of` |
+| Consumables | `## Consumables` |
+| Grace/hold, plan change, cancellation | `## Subscriptions` |
+| Prices, offers, trial eligibility | `## Prices and offers` |
+| Restore, offline, logout, account switch | `## Sync, restore, and offline` |
+| `environment_blocked`, release config | `## Environments and the production guard` |
+| Backend verification | `## Server-side validation` |
+| Events, ordering, error codes | `## Events and errors` |
+| Wiring an entitlement to ads | `## Wiring an entitlement to another system` |
+| Tests and licence testers | `## Testing` |
+| Data safety, permissions | `## What is stored on the device`, `## Play policy checklist` |
+| Before release | `## Production release checklist` |
+| What is deferred | `## Known limitations`, `## Adding iOS later` |

package/src/adapter/createStoreProvider.ts

@@ -33,6 +33,7 @@ const UNSUPPORTED_CAPABILITIES: ProviderCapabilities = {
 	supportsExternalTransactions: false,
 	/** Nothing here can charge anyone, so the environment guard has nothing to block. */
 	createsRealTransactions: false,
+	purchaseOutcomeIncludesStoreTime: false,
 };
 
 /**