@chipmobilesdk/rn-payment 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,207 @@
 # @chipmobilesdk/rn-payment
 
+## 0.6.0
+
+### Minor Changes
+
+- The engine is split by responsibility, and its internals are off the public type. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - `PaymentEngine` no longer has `resolvedConfig`, `nextCorrelationId`, `emitter`,
+    `snapshot`, `commitSnapshot`, `mayCreateRealTransaction` or `recordBlockedOperation`.
+    They were documented as internal, but any consumer could call `commitSnapshot` and
+    grant itself an entitlement the store never sold, and a hand-written engine double had
+    to implement all of them.
+  - `entitlement_revoked` now carries the real reason: `validation_rejected` when your
+    backend said no, `consumed` for a consumed item, `expired` for a lapsed subscription,
+    and `revoked_by_store` only when the store stopped reporting the purchase. Before, every
+    revocation said `revoked_by_store`.
+  - `clearLocalData()` also drops cached product prices.
+  - A `not_ready` purchase result reports the engine's actual status instead of always
+    `connecting`. `usePurchase().purchase` takes a `ProductKey`, as it always accepted.
+  - Local storage moves to schema version 2: the never-written `entitlements` map and
+    `finalized` purchase state are gone. A version 1 record is migrated in place on first
+    load, so nothing needs to be done.
+  - Internally, `engine.ts` is 346 lines (was 921): state, connection and sync are their
+    own modules, and sync and the purchase flow build purchase records with one function.
+    The unused `runWithRetry`, `backoffSchedule`, `sourcesFor` and `entitlementsCoveredBy`
+    helpers are gone.
+
+- The provider keeps one engine, stored records are checked one by one, and product
+  queries run in parallel. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  - `PaymentProvider` builds its engine once and keeps it across renders. Inline
+    `config` and `deps` objects no longer reconnect to the store on every render of your
+    root. A new engine is built only when the new `engineKey` prop changes (default:
+    `config.scopeToken`). It now works under React StrictMode, where it used to be left
+    holding a cleaned-up engine that never became ready. Pass `engine` to share an engine
+    you created and own; the provider then neither initializes nor cleans it up.
+  - `initialize()` on a cleaned-up engine reports `PAYMENT_NOT_CONFIGURED` even if the
+    engine had been ready, instead of answering `ok`.
+  - Every stored purchase record is checked field by field when read. A damaged one is
+    dropped and comes back with the next sync, rather than being trusted or taking the
+    rest down with it. Only a `purchased` record grants an entitlement; a state this
+    version does not know never does.
+  - A failed write to local storage is reported as an `internal_error` with
+    `PAYMENT_STORAGE_UNAVAILABLE` and operation `persist`, instead of being swallowed.
+    A custom `SnapshotStore.save` may return `false` to report one.
+  - One-time and subscription products are queried in parallel, identical requests in
+    flight share one store call, and `useProducts` never lets an older answer overwrite a
+    newer one. `status.blockedOperations` keeps the 20 most recent.
+
+- `allowStoreTestPurchases` lets a debug build buy through the real store for Play
+  license testers. It is accepted only with `environment: 'test'`; any other environment
+  rejects it at startup with `PAYMENT_INVALID_CONFIG`. Without it, non-production
+  purchases are still refused as `environment_blocked`, as before. The README no longer
+  says the billing library is uninstalled or the adapter unverified, and describes what
+  adding iOS actually involves. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+### Patch Changes
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
+## 0.5.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -91,12 +91,9 @@ npm install react-native-iap react-native-mmkv react-native-nitro-modules
 > 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:
+> **Check your merged manifest** once `react-native-iap` is installed: it should
+> contain exactly one `com.android.vending.BILLING` entry, added by the billing
+> library, and no new runtime permission:
 >
 > ```bash
 > # After a debug build, inspect the merge report:
@@ -164,9 +161,13 @@ const config = {
   isProductionBuild: true,
 };
 
+// Created once, outside the component: the store adapter holds the billing
+// connection.
+const deps = { provider: createStoreProvider() };
+
 export function App() {
   return (
-    <PaymentProvider config={config} deps={{ provider: createStoreProvider() }}>
+    <PaymentProvider config={config} deps={deps}>
       <YourApp />
     </PaymentProvider>
   );
@@ -182,6 +183,13 @@ function AdSlot() {
 }
 ```
 
+The provider builds its engine once and keeps it across renders; `config` and `deps`
+are read when it is built. It builds a new one when `engineKey` changes (by default
+`config.scopeToken`, so switching accounts gets a fresh engine), and it survives React
+StrictMode in development. To own the engine yourself — create it at startup, share it
+with code outside React — pass it instead: `<PaymentProvider engine={engine}>`. The
+provider then neither initializes nor cleans it up.
+
 `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.
@@ -192,6 +200,13 @@ 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.
 
+If "back from the background" is what you mean, opt in instead of wiring `AppState`:
+`<PaymentProvider syncOnForeground>` or `syncOnForeground(engine)` (returns an
+unsubscribe). Both listen through rn-core's shared lifecycle port, so they add no
+native subscription of their own, and a trip through `inactive` alone does not count.
+On Android the Play purchase sheet does background the app, so a purchase is followed
+by one rate-limited sync.
+
 ---
 
 ## Catalog and entitlement mapping
@@ -544,6 +559,20 @@ Two layers:
    recorded in `getStatus().blockedOperations`, and emitted as
    `environment_blocked` — observable in state, so a test can assert it rather
    than scraping logs.
+3. **License testing, opted in.** `environment: 'test'` with
+   `allowStoreTestPurchases: true` lets a debug build buy through the real store,
+   so a Play license tester can check a purchase without a release build from a
+   track. Any other environment rejects the option at construction. License
+   testers are not charged; anyone else signed in on the device would be.
+
+```ts
+const config = {
+  // ...
+  environment: 'test',
+  isProductionBuild: false,
+  allowStoreTestPurchases: true, // license testers only
+};
+```
 
 > **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
@@ -604,7 +633,9 @@ import { DEFAULT_USER_MESSAGES, USER_MESSAGE_KEYS, isUserMessageKey } from '@chi
 
 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.
+lets you assert that at your own boundary. `paymentMessages` is the same catalog as
+an rn-core message set; register the user copy with rn-i18n in one line:
+`runtimeEntriesFromCatalog(paymentMessages.user)`.
 
 Message keys are public API; renaming one is a breaking change.
 
@@ -612,6 +643,9 @@ Message keys are public API; renaming one is a breaking change.
 
 ## Events and errors
 
+Every error is a `PaymentError` (or `PaymentConfigError`) with a stable `code`, the
+`operation` and a `retryable` flag. `PaymentError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
 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
@@ -647,6 +681,11 @@ 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.
 
+A timeout, backoff or interval outside its bounds throws `PaymentConfigError` with
+`PAYMENT_INVALID_CONFIG`, naming the field in `offenders`. Backoff checks every
+field: `initialDelayMs` 100 ms to 60 s and not above `maxDelayMs`, `factor` 1 to
+10, `maxDelayMs` 5 s to 10 min, `maxAttempts` 1 to 10.
+
 ---
 
 ## Wiring an entitlement to another system
@@ -710,6 +749,12 @@ store.pushPurchaseUpdate(...);  // deliver a settlement with no sync
 `./testing` is a separate entrypoint so test doubles cannot reach a production
 bundle.
 
+`runProviderPortConformance(harness)` holds the checks every store adapter must pass:
+connection and a dropped service, products with the store's own price, pending
+purchases flagged rather than filtered, a bought and a cancelled flow, and
+finalization that is safe twice. The package runs it against the fake store and the
+Play adapter; an iOS adapter, or a device run from a demo screen, uses the same suite.
+
 ### Licence testers, for device verification
 
 1. Play Console → **Setup → Licence testing**, add tester accounts.
@@ -728,10 +773,8 @@ 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 |
+| Purchase records (transaction id, product key, product type, token, purchase time, store state, finalize state and attempt count, backend validation state) | So entitlements are readable offline and a paid purchase is never lost to an app kill. Entitlements themselves are derived from these, never stored |
+| Subscription expiry and renewal status, on the purchase record | So lifecycle is readable offline |
 | 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 |
@@ -822,9 +865,11 @@ Your obligations as the app owner — this package cannot discharge them for you
    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).
+3. **Debug builds do not reach the store unless you opt in.** Outside production a
+   purchase reports `environment_blocked`. For a license tester on a debug build,
+   set `environment: 'test'` and `allowStoreTestPurchases: true`; only license
+   testers are not charged. See [Compatibility](#compatibility) for the devices and
+   binding the Android adapter was verified with.
 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.
@@ -840,7 +885,12 @@ Your obligations as the app owner — this package cannot discharge them for you
 
 ## Adding iOS later
 
-Implement `ProviderPort` for StoreKit. Nothing else changes.
+Implement `ProviderPort` for StoreKit and return it from `createStoreProvider()` on
+iOS. Your entitlement checks, hooks and purchase calls do not change. What an iOS
+release adds: `storeProductIds.ios` in each catalog entry, the adapter's own
+`capabilities()` (StoreKit can tell grace period from account hold, and supports
+externally initiated purchases, so some states Android reports as `indeterminate`
+become distinct), and its conformance run (`runProviderPortConformance`).
 
 | Play concept | Port concept | StoreKit |
 |---|---|---|
@@ -867,6 +917,10 @@ 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`.
 
+Schema version 2 (0.6.0) drops two things version 1 stored and never used: an
+empty `entitlements` map and a `finalized` purchase state nothing set. A version 1
+record is migrated in place on first load.
+
 ### Migrating `0.1.0` to `0.2.0`
 
 **One union gained a member**, so an exhaustive `switch` over it needs the new

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-payment",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",
@@ -27,9 +27,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -68,10 +68,10 @@ rule: a chargeable purchase is permitted only when `environment: 'production'` *
 `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
+real Play transactions**. A debug build reaches the store only with `environment: 'test'`
+and `allowStoreTestPurchases: true` (licence testers are not charged; anyone else would
+be); otherwise it gets `environment_blocked`. 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
@@ -91,6 +91,8 @@ Unlike `@chipmobilesdk/rn-ads`, there is **no test-id substitution**: Play has n
 
 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.
+When a return from the background is enough, opt in with `<PaymentProvider
+syncOnForeground>` or `syncOnForeground(engine)` (rn-core's shared lifecycle port).
 
 ## Public API
 
@@ -103,8 +105,8 @@ environment; everything else returns a typed result) · `createStoreProvider` ·
 `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).
+· `createFakeStore`, `makePurchase`, `runProviderPortConformance` from
+`@chipmobilesdk/rn-payment/testing` (test doubles and the store-adapter suite only).
 
 Engine: `initialize`, `cleanup`, `getStatus`, `subscribeStatus`, `getEntitlement`,
 `getAllEntitlements`, `subscribeEntitlements`, `getPendingPurchases`,