@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,54 @@
 {
-  "name": "@chipmobilesdk/rn-payment",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@chipmobilesdk/rn-payment",
+	"version": "0.2.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"
+	]
+}

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

@@ -0,0 +1,164 @@
+---
+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.2.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.2.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 — `0.1.0` already persisted pending
+records. Replace any app-side "pending since" marker with `usePendingPurchases`.
+
+**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

@@ -0,0 +1,117 @@
+/**
+ * Platform selection for the store adapter.
+ *
+ * This exists so the public surface never names a store. An app writes
+ * `createStoreProvider()`, not `createIapAdapter()` — the same call will pick the
+ * StoreKit adapter once iOS exists, and no consumer line changes (FR-002, FR-004,
+ * FR-007).
+ *
+ * On a platform with no adapter the result is a stub that reports
+ * `platform_unsupported` rather than throwing. That is what lets a host app start
+ * and run normally where selling is impossible, losing only the ability to sell
+ * (FR-021, FR-023).
+ */
+
+import { Platform } from 'react-native';
+import type { ProductType, Unsubscribe } from '../config/types';
+import { createIapAdapter } from './iap-adapter';
+import type {
+	ProviderCapabilities,
+	ProviderConnectOutcome,
+	ProviderPort,
+	ProviderPriceChangeOutcome,
+	ProviderProduct,
+	ProviderPurchase,
+	ProviderPurchaseOutcome,
+} from './port';
+
+const UNSUPPORTED_CAPABILITIES: ProviderCapabilities = {
+	supportsSubscriptions: false,
+	supportsPlanChange: false,
+	supportsPriceChangeConfirmation: false,
+	reportsGraceAndHoldDistinctly: false,
+	supportsExternalTransactions: false,
+	/** Nothing here can charge anyone, so the environment guard has nothing to block. */
+	createsRealTransactions: false,
+};
+
+/**
+ * The no-adapter stub.
+ *
+ * Every operation fails safely and predictably. Notably `queryOwned` returns an
+ * empty list rather than throwing: the engine then computes `not_entitled` after a
+ * successful-but-empty sync, which is honest — on a platform with no store, the
+ * user genuinely holds nothing this package can verify.
+ */
+function createUnsupportedProvider(): ProviderPort {
+	return {
+		async connect(): Promise<ProviderConnectOutcome> {
+			return { ok: false, reason: 'platform_unsupported', retryable: false };
+		},
+		async disconnect(): Promise<void> {
+			// Nothing was ever connected.
+		},
+		observeConnection(): Unsubscribe {
+			return () => undefined;
+		},
+		async queryProducts(): Promise<ProviderProduct[]> {
+			return [];
+		},
+		async queryOwned(): Promise<ProviderPurchase[]> {
+			return [];
+		},
+		async launchPurchase(): Promise<ProviderPurchaseOutcome> {
+			return { ok: false, reason: 'not_ready', detail: 'platform_unsupported' };
+		},
+		observePurchases(): Unsubscribe {
+			return () => undefined;
+		},
+		async acknowledge(): Promise<void> {
+			// No transaction can exist to acknowledge.
+		},
+		async consume(): Promise<void> {
+			// As above.
+		},
+		async openSubscriptionManagement(): Promise<void> {
+			// No store screen to open.
+		},
+		async confirmPriceChange(): Promise<ProviderPriceChangeOutcome> {
+			return { ok: false, reason: 'not_ready' };
+		},
+		capabilities: () => UNSUPPORTED_CAPABILITIES,
+	};
+}
+
+export interface StoreProviderOptions {
+	/**
+	 * Force the unsupported stub regardless of platform.
+	 *
+	 * Useful for an app that wants to ship one build with selling switched off at
+	 * the provider level rather than through the `enabled` flag.
+	 */
+	forceUnsupported?: boolean;
+}
+
+/**
+ * The platform's store adapter.
+ *
+ * iOS deliberately returns the stub today rather than throwing: the contract is
+ * prepared for StoreKit, the implementation is not, and an app running on iOS
+ * should degrade to "cannot sell here" instead of crashing.
+ */
+export function createStoreProvider(
+	options: StoreProviderOptions = {},
+): ProviderPort {
+	if (options.forceUnsupported) {
+		return createUnsupportedProvider();
+	}
+	if (Platform.OS === 'android') {
+		return createIapAdapter();
+	}
+	return createUnsupportedProvider();
+}
+
+/** Exported for a test or a screen that needs the stub explicitly. */
+export { createUnsupportedProvider };
+
+export type { ProductType };