@chipmobilesdk/rn-payment 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @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

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.
@@ -551,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
@@ -751,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 |
@@ -845,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.
@@ -863,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 |
 |---|---|---|
@@ -890,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.5.0",
+	"version": "0.6.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",

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

package/src/adapter/iap-adapter.ts

@@ -41,11 +41,18 @@ import { createListenerSet, lazyPeer } from '@chipmobilesdk/rn-core';
 import type { RequestPurchaseProps, SubscriptionReplacementModeAndroid } from 'react-native-iap';
 
 import type { ProductType, Unsubscribe } from '../config/types';
+import {
+	mapErrorCode,
+	normalizeProduct,
+	normalizePurchase,
+	type RawProduct,
+	type RawPurchase,
+	type RawPurchaseError,
+} from './iapShapes';
 import { PaymentError, redact } from '../diagnostics/errors';
 import type {
 	ProviderCapabilities,
 	ProviderConnectOutcome,
-	ProviderFailureReason,
 	ProviderPort,
 	ProviderPriceChangeOutcome,
 	ProviderProduct,
@@ -56,6 +63,10 @@ import type {
 	StoreProductId,
 } from './port';
 
+// Translation lives in `iapShapes`; it is published from here, where every
+// consumer has always imported it from.
+export { toProviderPurchaseState } from './iapShapes';
+
 /**
  * Exactly what this adapter needs from the binding.
  *
@@ -78,67 +89,6 @@ interface IapModule {
 	deepLinkToSubscriptions?(params: { skuAndroid?: string }): Promise<void>;
 }
 
-interface RawProduct {
-	id?: string;
-	productId?: string;
-	title?: string;
-	name?: string;
-	description?: string;
-	displayPrice?: string;
-	localizedPrice?: string;
-	currency?: string;
-	currencyCode?: string;
-	price?: string | number;
-	oneTimePurchaseOfferDetails?: {
-		formattedPrice?: string;
-		priceAmountMicros?: string | number;
-		priceCurrencyCode?: string;
-	};
-	subscriptionOfferDetails?: RawSubscriptionOffer[];
-}
-
-interface RawSubscriptionOffer {
-	offerToken?: string;
-	offerId?: string;
-	basePlanId?: string;
-	pricingPhases?: {
-		pricingPhaseList?: Array<{
-			formattedPrice?: string;
-			priceAmountMicros?: string | number;
-			priceCurrencyCode?: string;
-			billingPeriod?: string;
-			recurrenceMode?: number;
-			billingCycleCount?: number;
-		}>;
-	};
-}
-
-interface RawPurchase {
-	id?: string;
-	transactionId?: string;
-	productId?: string;
-	ids?: string[];
-	purchaseToken?: string;
-	purchaseStateAndroid?: number | null;
-	/** A string in the 16.x binding: `'pending' | 'purchased' | 'unknown'`. */
-	purchaseState?: number | string;
-	transactionDate?: number;
-	isAcknowledgedAndroid?: boolean;
-	isAcknowledged?: boolean;
-	autoRenewingAndroid?: boolean;
-	isAutoRenewing?: boolean;
-	expirationDateAndroid?: number;
-	transactionReceipt?: string;
-	dataAndroid?: string;
-}
-
-/** What `purchaseErrorListener` delivers. */
-interface RawPurchaseError {
-	code?: string;
-	message?: string;
-	productId?: string | null;
-}
-
 /**
  * How long to wait for the outcome event after `requestPurchase` has resolved.
  * The binding emits the event before or as it resolves, so this only bounds the
@@ -193,12 +143,6 @@ export function toRequestProps(request: ProviderPurchaseRequest): RequestPurchas
 	};
 }
 
-/** Play's `PurchaseState`: 0 unspecified, 1 purchased, 2 pending. */
-const PLAY_STATE_PURCHASED = 1;
-const PLAY_STATE_PENDING = 2;
-
-// Required lazily (rn-core's lazy peer) so importing the package does not require
-// the native module.
 const iapPeer = lazyPeer('react-native-iap', () => {
 	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
 	try {
@@ -220,154 +164,6 @@ function loadModule(): IapModule {
 	);
 }
 
-function toMicros(value: string | number | undefined): number {
-	if (typeof value === 'number') {
-		return value;
-	}
-	if (typeof value === 'string') {
-		const parsed = Number.parseInt(value, 10);
-		return Number.isFinite(parsed) ? parsed : 0;
-	}
-	return 0;
-}
-
-function normalizeProduct(raw: RawProduct, productType: ProductType): ProviderProduct {
-	const oneTime = raw.oneTimePurchaseOfferDetails;
-	const currencyCode = oneTime?.priceCurrencyCode ?? raw.currencyCode ?? raw.currency ?? '';
-
-	return {
-		storeProductId: raw.id ?? raw.productId ?? '',
-		productType,
-		title: raw.title ?? raw.name ?? '',
-		description: raw.description ?? '',
-		// Store-formatted, never built here: only the store knows the right currency
-		// symbol, separator, and placement for the user's locale (FR-028).
-		formattedPrice: oneTime?.formattedPrice ?? raw.displayPrice ?? raw.localizedPrice ?? '',
-		currencyCode,
-		priceAmountMicros: toMicros(oneTime?.priceAmountMicros ?? raw.price),
-		offers: (raw.subscriptionOfferDetails ?? []).map(offer => normalizeOffer(offer, currencyCode)),
-	};
-}
-
-function normalizeOffer(
-	offer: RawSubscriptionOffer,
-	fallbackCurrency: string,
-): ProviderProduct['offers'][number] {
-	const phases = offer.pricingPhases?.pricingPhaseList ?? [];
-	// The last phase is the recurring price; earlier ones are trial or
-	// introductory. Play orders them that way.
-	const recurring = phases[phases.length - 1];
-	const intro = phases.length > 1 ? phases[0] : undefined;
-	const isFreeTrial = intro !== undefined && toMicros(intro.priceAmountMicros) === 0;
-
-	return {
-		offerKey: offer.offerToken ?? offer.offerId ?? offer.basePlanId ?? '',
-		billingPeriod: recurring?.billingPeriod ?? '',
-		formattedPrice: recurring?.formattedPrice ?? '',
-		priceAmountMicros: toMicros(recurring?.priceAmountMicros),
-		currencyCode: recurring?.priceCurrencyCode ?? fallbackCurrency,
-		trialPeriod: isFreeTrial ? intro?.billingPeriod : undefined,
-		introductoryPrice:
-			intro && !isFreeTrial
-				? {
-						formattedPrice: intro.formattedPrice ?? '',
-						period: intro.billingPeriod ?? '',
-						cycles: intro.billingCycleCount ?? 1,
-					}
-				: undefined,
-		// Play decides eligibility by only returning offers the user qualifies for,
-		// so forwarding `true` reports the store's determination rather than
-		// computing our own (FR-026).
-		isEligible: true,
-	};
-}
-
-/**
- * Reads the purchase state from whichever field the binding filled.
- *
- * Pending is preserved, never flattened to purchased: that distinction is what
- * stops an entitlement being granted for money that has not arrived (FR-037).
- * And an unrecognized or missing state is `unspecified`, never `purchased`.
- *
- * 0.1.0 read only Play's numeric state and treated anything else as purchased.
- * The 16.x binding hands JavaScript the *string* state and does not carry the
- * numeric one across, so on a device every pending purchase arrived as a string,
- * fell through to the default, and was granted. Unit tests could not see it: they
- * drive the fake store, which never passes through here.
- */
-export function toProviderPurchaseState(
-	raw: Pick<RawPurchase, 'purchaseStateAndroid' | 'purchaseState'>,
-): ProviderPurchase['state'] {
-	let numeric: number | undefined;
-	if (typeof raw.purchaseStateAndroid === 'number') {
-		numeric = raw.purchaseStateAndroid;
-	} else if (typeof raw.purchaseState === 'number') {
-		numeric = raw.purchaseState;
-	}
-	if (numeric !== undefined) {
-		if (numeric === PLAY_STATE_PENDING) {
-			return 'pending';
-		}
-		return numeric === PLAY_STATE_PURCHASED ? 'purchased' : 'unspecified';
-	}
-
-	switch (typeof raw.purchaseState === 'string' ? raw.purchaseState.toLowerCase() : '') {
-		case 'purchased':
-		case 'restored':
-			return 'purchased';
-		case 'pending':
-		case 'deferred':
-			return 'pending';
-		default:
-			return 'unspecified';
-	}
-}
-
-function normalizePurchase(raw: RawPurchase): ProviderPurchase {
-	return {
-		storeProductId: raw.productId ?? raw.ids?.[0] ?? '',
-		transactionId: raw.id ?? raw.transactionId ?? raw.purchaseToken ?? '',
-		token: raw.purchaseToken ?? '',
-		state: toProviderPurchaseState(raw),
-		purchasedAt: raw.transactionDate ?? Date.now(),
-		isAcknowledged: raw.isAcknowledgedAndroid ?? raw.isAcknowledged ?? false,
-		expiresAt: raw.expirationDateAndroid,
-		willAutoRenew: raw.autoRenewingAndroid ?? raw.isAutoRenewing,
-		// Opaque material for the app's backend. Carried here and handed to the
-		// validation hook only — never logged or put in an event (FR-074).
-		verificationPayload: raw.transactionReceipt ?? raw.dataAndroid,
-	};
-}
-
-/** Maps a binding error code onto the port's vocabulary, so no store code escapes. */
-function mapErrorCode(code: string | undefined): ProviderFailureReason {
-	switch (code) {
-		case 'E_USER_CANCELLED':
-		case 'user-cancelled':
-			return 'user_cancelled';
-		case 'E_ALREADY_OWNED':
-		case 'already-owned':
-		case 'item-already-owned':
-			return 'already_owned';
-		case 'E_ITEM_UNAVAILABLE':
-		case 'item-unavailable':
-		case 'sku-not-found':
-			return 'unknown_product';
-		case 'E_NOT_PREPARED':
-		case 'not-prepared':
-			return 'not_ready';
-		case 'E_NETWORK_ERROR':
-		case 'network-error':
-			return 'network_error';
-		case 'E_DEFERRED_PAYMENT':
-			// Not a failure — a pending purchase. The caller resolves it from the
-			// purchase update rather than from this error.
-			return 'store_error';
-		default:
-			return 'store_error';
-	}
-}
-
 const ANDROID_CAPABILITIES: ProviderCapabilities = {
 	supportsSubscriptions: true,
 	supportsPlanChange: true,