@chipmobilesdk/rn-payment 0.1.0 → 0.2.1

package/package.json

@@ -1,54 +1,54 @@
-{
-	"name": "@chipmobilesdk/rn-payment",
-	"version": "0.1.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.2.1",
+	"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

@@ -1,9 +1,9 @@
 ---
 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, guaranteed transaction finalization, per-environment production-transaction blocking. Use when selling a feature, gating on an entitlement, 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."
+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.1.0"
+  packageVersion: "0.2.1"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -17,6 +17,7 @@ the package owns the transaction. Consuming code never imports the billing libra
 ## 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`
@@ -49,6 +50,17 @@ feature locked for a second. It is also **re-entrant** — a cached answer retur
 `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
@@ -81,12 +93,13 @@ 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.
 
-## Public API (v0.1.0)
+## 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`,
-`usePaymentStatus`, `usePurchase`, `useProducts`, `useSync` · `PaymentError`,
+`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
@@ -95,14 +108,16 @@ environment; everything else returns a typed result) · `createStoreProvider` ·
 doubles only).
 
 Engine: `initialize`, `cleanup`, `getStatus`, `subscribeStatus`, `getEntitlement`,
-`getAllEntitlements`, `subscribeEntitlements`, `purchase`, `consume`, `getUnfinalized`,
+`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`, `PurchaseResult`,
+`EntitlementMap`, `SubscriptionDetail`, `RenewalState`, `PendingPurchase`,
+`PendingPurchasesState`, `PendingResolution`, `PurchaseResult`,
 `PurchaseOptions`, `TransactionRef`, `FinalizeResult`, `UnfinalizedSummary`,
 `ProductInfo`, `Offer`, `ProductQueryResult`, `MissingProduct`, `ProrationMode`,
 `PriceChangeResult`, `PaymentStatus`, `PaymentStatusKind`, `UnavailableReason`,
@@ -112,6 +127,17 @@ Types: `PaymentConfig`, `CatalogEntry`, `ProductType`, `StoreProductIds`,
 
 `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`:
@@ -122,6 +148,7 @@ Read one section of `node_modules/@chipmobilesdk/rn-payment/README.md`:
 | 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` |

package/src/adapter/createStoreProvider.ts

@@ -1,117 +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 };
+/**
+ * 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 };