@chipmobilesdk/rn-payment 0.5.0 → 0.6.0

package/src/adapter/iapShapes.ts

@@ -0,0 +1,232 @@
+/**
+ * The binding's shapes, and their translation into the port's vocabulary
+ * (PAY-12).
+ *
+ * The binding speaks Google Play: prices as micros in strings, offer tokens,
+ * numeric purchase states, store error codes. The port speaks this package's
+ * own. Keeping the translation here, with no I/O, no listeners and no module
+ * loading, is what makes it checkable against recorded payloads — and leaves
+ * the adapter next door about the calls it actually makes.
+ *
+ * The raw types are declared narrowly on purpose: they document the coupling,
+ * and a binding upgrade that changes one of these shapes fails to typecheck
+ * here rather than failing silently on a user's device.
+ */
+import type { ProductType } from '../config/types';
+import type { ProviderFailureReason, ProviderProduct, ProviderPurchase } from './port';
+
+export 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[];
+}
+
+export interface RawSubscriptionOffer {
+	offerToken?: string;
+	offerId?: string;
+	basePlanId?: string;
+	pricingPhases?: {
+		pricingPhaseList?: Array<{
+			formattedPrice?: string;
+			priceAmountMicros?: string | number;
+			priceCurrencyCode?: string;
+			billingPeriod?: string;
+			recurrenceMode?: number;
+			billingCycleCount?: number;
+		}>;
+	};
+}
+
+export 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. */
+export interface RawPurchaseError {
+	code?: string;
+	message?: string;
+	productId?: string | null;
+}
+
+/** 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.
+
+export 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;
+}
+
+export 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)),
+	};
+}
+
+export 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';
+	}
+}
+
+export 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. */
+export 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';
+	}
+}

package/src/config/types.ts

@@ -130,6 +130,14 @@ export interface PaymentConfig {
 	 * proceed (FR-015).
 	 */
 	isProductionBuild: boolean;
+	/**
+	 * Lets a non-production build complete purchases through the real store, so a
+	 * Play license tester can buy on a debug build (PAY-16). Accepted only with
+	 * `environment: 'test'`; any other environment rejects it at startup. License
+	 * testers are not charged; any other account on the device would be, so keep
+	 * it out of builds that reach real users.
+	 */
+	allowStoreTestPurchases?: boolean;
 	/**
 	 * Global sell switch. When false, purchases report `disabled` but entitlements
 	 * already held stay readable — turning off selling is not the same as taking

package/src/config/validate.ts

@@ -199,6 +199,16 @@ export function validateConfig(
  * continuing silently is exactly the failure this package exists to prevent.
  */
 export function assertEnvironmentSafe(config: PaymentConfig): void {
+	if (config.allowStoreTestPurchases === true && config.environment !== 'test') {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CONFIG',
+			message:
+				`allowStoreTestPurchases is only accepted with environment "test", not ` +
+				`"${config.environment}": it exists for license testers, not for real users.`,
+			operation: 'configure',
+			offenders: ['allowStoreTestPurchases'],
+		});
+	}
 	if (config.environment === 'production' && !config.isProductionBuild) {
 		throw new PaymentConfigError({
 			code: 'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
@@ -213,12 +223,17 @@ export function assertEnvironmentSafe(config: PaymentConfig): void {
 }
 
 /**
- * Whether this configuration may hand a real purchase to a real store (FR-014).
+ * Whether this configuration may hand a purchase to a real store (FR-014).
  *
- * False outside production regardless of what else is configured. The engine
- * records each refusal in observable status so a test can assert the block
- * happened — the difference between a guarantee and a hope.
+ * True in a production build configured for production, and in a `test`
+ * environment that opted in with `allowStoreTestPurchases` (PAY-16). False
+ * everywhere else. The engine records each refusal in observable status so a
+ * test can assert the block happened — the difference between a guarantee and a
+ * hope.
  */
 export function mayCreateRealTransaction(config: PaymentConfig): boolean {
+	if (config.environment === 'test' && config.allowStoreTestPurchases === true) {
+		return true;
+	}
 	return config.environment === 'production' && config.isProductionBuild;
 }

package/src/core/retry.ts

@@ -9,17 +9,10 @@
  * schedule without burning real time.
  */
 
-import {
-	computeBackoff,
-	runWithRetry as runCoreRetry,
-	type RetryHandle,
-} from '@chipmobilesdk/rn-core';
+import { computeBackoff } from '@chipmobilesdk/rn-core';
 
 import type { BackoffConfig } from '../config/types';
 
-/** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
-type TimerHandle = ReturnType<typeof setTimeout> | number;
-
 /**
  * Delay before `attempt` (1-based), capped and optionally jittered.
  *
@@ -43,53 +36,3 @@ function toSpec(config: Required<BackoffConfig>) {
 		maxAttempts: config.maxAttempts,
 	};
 }
-
-/** The full schedule, for asserting a retry policy without waiting for it. */
-export function backoffSchedule(config: Required<BackoffConfig>): number[] {
-	const delays: number[] = [];
-	for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
-		delays.push(backoffDelayMs(attempt, config, () => 1));
-	}
-	return delays;
-}
-
-export type { RetryHandle } from '@chipmobilesdk/rn-core';
-
-export interface RetryRunnerOptions {
-	config: Required<BackoffConfig>;
-	/** Return true when the attempt succeeded and retrying should stop. */
-	attempt: (attemptNumber: number) => Promise<boolean>;
-	/** Called once the per-session budget is spent without success. */
-	onExhausted?: (attempts: number) => void;
-	/**
-	 * Injected so a test can run the whole schedule synchronously instead of
-	 * waiting minutes of real backoff. The handle is opaque, because a Node
-	 * `Timeout` and a browser numeric id are both valid here.
-	 */
-	setTimeoutFn?: (fn: () => void, ms: number) => TimerHandle;
-	clearTimeoutFn?: (handle: TimerHandle) => void;
-	random?: () => number;
-}
-
-/**
- * Runs `attempt` under the bounded schedule (rn-core's runner).
- *
- * Exhaustion is reported rather than thrown: for finalization, a spent session
- * budget is not a failure but a handoff to the next launch, and the caller is
- * the only one that knows which of the two it is. A throwing attempt is a failed
- * attempt, nothing more: letting it escape would silently drop a paid transaction.
- */
-export function runWithRetry(options: RetryRunnerOptions): RetryHandle {
-	const setTimeoutFn = options.setTimeoutFn ?? setTimeout;
-	const clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
-	return runCoreRetry({
-		spec: toSpec(options.config),
-		attempt: options.attempt,
-		onExhausted: options.onExhausted,
-		random: options.random,
-		scheduler: {
-			setTimeout: (callback, ms) => setTimeoutFn(callback, ms),
-			clearTimeout: handle => clearTimeoutFn(handle as TimerHandle),
-		},
-	});
-}

package/src/diagnostics/events.ts

@@ -257,7 +257,7 @@ export function createEmitter(
 /**
  * Fields that must never appear in an event payload.
  *
- * Used by `__tests__/redaction.test.ts` to walk every emitted event across the
+ * Used by `__tests__/diagnostics.test.ts` to walk every emitted event across the
  * whole suite. Enumerating the ban here rather than in the test keeps the rule
  * next to the type it constrains.
  */

package/src/engine/connection.ts

@@ -0,0 +1,194 @@
+/**
+ * The billing connection: connecting, watching it, and reconnecting with bounded
+ * backoff (FR-018 – FR-024, PAY-10).
+ *
+ * A reconnect is always a full teardown-then-connect cycle. The upstream
+ * binding's own `reconnect()` has reported success without rebuilding anything
+ * (openiap#408), so no shortcut is trusted here.
+ */
+import type { ProviderPurchase } from '../adapter/port';
+import type { Unsubscribe } from '../config/types';
+import { backoffDelayMs } from '../core/retry';
+import { withTimeout } from '../core/mutex';
+import { PaymentError } from '../diagnostics/errors';
+import type { EngineState } from './state';
+
+export type InitOutcome = { ok: true } | { ok: false; error: PaymentError };
+
+export interface Connection {
+	/** Connects and attaches the watchers; status follows the outcome. */
+	connect(): Promise<InitOutcome>;
+	/**
+	 * A fresh reconnect budget and one immediate attempt, when an earlier budget
+	 * ran out: a foreground return is when the network the app lost is usually
+	 * back.
+	 */
+	recover(): Promise<void>;
+	dispose(): void;
+}
+
+export function createConnection(
+	state: EngineState,
+	onPurchase: (purchase: ProviderPurchase) => void,
+): Connection {
+	const { provider, resolved } = state;
+	let connectionSub: Unsubscribe | undefined;
+	let purchaseSub: Unsubscribe | undefined;
+	let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+	let reconnectAttempts = 0;
+	/**
+	 * Set once a connection succeeded. Recovery after an exhausted budget is only
+	 * meaningful from there; a first connection that failed is the app's to retry
+	 * through `initialize`.
+	 */
+	let everConnected = false;
+
+	function scheduleReconnect(): void {
+		if (state.disposed) {
+			return;
+		}
+		if (reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+			// Out of budget for now, not for good: a retryable failure rather than a
+			// `connecting` that promised a reconnect nobody was going to make.
+			state.setStatus({ kind: 'failed', retryable: true, reconnectAttempts });
+			return;
+		}
+		const attempt = reconnectAttempts + 1;
+		reconnectTimer = setTimeout(
+			() => {
+				reconnectTimer = undefined;
+				if (state.disposed) {
+					return;
+				}
+				reconnectAttempts = attempt;
+				state.setStatus({ kind: 'connecting', reconnectAttempts });
+				reconnectOnce().catch(() => undefined);
+			},
+			backoffDelayMs(attempt, resolved.retry.reconnect),
+		);
+	}
+
+	async function reconnectOnce(): Promise<void> {
+		try {
+			await provider.disconnect();
+		} catch {
+			// Already down; nothing to tear down.
+		}
+		const outcome = await provider.connect();
+		if (state.disposed) {
+			return;
+		}
+		if (outcome.ok) {
+			reconnectAttempts = 0;
+			state.setStatus({ kind: 'ready', reconnectAttempts: 0 });
+		} else {
+			scheduleReconnect();
+		}
+	}
+
+	/** Replaced, never stacked: a second subscription would hear everything twice. */
+	function watch(): void {
+		connectionSub?.();
+		connectionSub = provider.observeConnection((connected, reason) => {
+			if (state.disposed) {
+				return;
+			}
+			state.emit({ type: 'connection_changed', connected, reason, attempt: reconnectAttempts });
+			if (!connected && state.status.kind === 'ready') {
+				state.setStatus({ kind: 'connecting' });
+				scheduleReconnect();
+			}
+		});
+		// Session-long: a pending purchase settling between sessions arrives here
+		// (FR-039), not only while a purchase is open.
+		purchaseSub?.();
+		purchaseSub = provider.observePurchases(purchase => {
+			if (!state.disposed) {
+				onPurchase(purchase);
+			}
+		});
+	}
+
+	return {
+		async connect() {
+			const outcome = await withTimeout(
+				provider.connect(),
+				resolved.timeouts.connectMs,
+				() =>
+					new PaymentError({
+						code: 'PAYMENT_TIMEOUT',
+						message: 'Connecting to the billing service timed out',
+						operation: 'initialize',
+						retryable: true,
+					}),
+			).catch((error: PaymentError) => ({
+				ok: false as const,
+				reason: 'store_error' as const,
+				retryable: error.retryable,
+			}));
+
+			if (!outcome.ok) {
+				if (outcome.reason === 'store_error') {
+					state.setStatus({ kind: 'failed', retryable: outcome.retryable });
+					return {
+						ok: false,
+						error: new PaymentError({
+							code: 'PAYMENT_STORE_ERROR',
+							message: 'Could not connect to the billing service',
+							operation: 'initialize',
+							retryable: outcome.retryable,
+						}),
+					};
+				}
+				// No billing service, an outdated one, or an unsupported platform: each
+				// distinguishable, and none of them may break the host app (FR-021, FR-023).
+				state.setStatus({
+					kind: 'unavailable',
+					unavailableReason: outcome.reason,
+					retryable: outcome.retryable,
+				});
+				return {
+					ok: false,
+					error: new PaymentError({
+						code:
+							outcome.reason === 'platform_unsupported'
+								? 'PAYMENT_UNSUPPORTED_PLATFORM'
+								: 'PAYMENT_UNAVAILABLE',
+						message: `Billing unavailable: ${outcome.reason}`,
+						operation: 'initialize',
+						retryable: outcome.retryable,
+					}),
+				};
+			}
+
+			watch();
+			everConnected = true;
+			state.setStatus({ kind: 'ready', reconnectAttempts: 0 });
+			return { ok: true };
+		},
+
+		async recover() {
+			if (
+				everConnected &&
+				!state.disposed &&
+				state.status.kind === 'failed' &&
+				reconnectTimer === undefined
+			) {
+				reconnectAttempts = 0;
+				state.setStatus({ kind: 'connecting', reconnectAttempts: 0 });
+				await reconnectOnce().catch(() => undefined);
+			}
+		},
+
+		dispose() {
+			connectionSub?.();
+			connectionSub = undefined;
+			purchaseSub?.();
+			purchaseSub = undefined;
+			if (reconnectTimer !== undefined) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = undefined;
+			}
+		},
+	};
+}