@chipmobilesdk/rn-payment 0.0.0-stage → 0.1.0

package/src/core/retry.ts

@@ -0,0 +1,133 @@
+/**
+ * Bounded backoff.
+ *
+ * "Bounded" is the whole point (FR-020, FR-045): an unbounded reconnect loop
+ * against a billing service that is down drains battery and hammers a system
+ * service, and an unbounded finalize loop hides a real failure behind noise.
+ *
+ * Delay computation is pure and separated from waiting so tests can assert the
+ * schedule without burning real time.
+ */
+
+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.
+ *
+ * Jitter is full jitter over [0, capped]: several devices that lost the billing
+ * connection at the same moment should not retry in lockstep.
+ */
+export function backoffDelayMs(
+	attempt: number,
+	config: Required<BackoffConfig>,
+	random: () => number = Math.random,
+): number {
+	const raw = config.initialDelayMs * Math.pow(config.factor, attempt - 1);
+	const capped = Math.min(raw, config.maxDelayMs);
+	return config.jitter ? Math.floor(capped * random()) : capped;
+}
+
+/** 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 interface RetryHandle {
+	/** Cancels any pending attempt. Idempotent, so cleanup can call it freely (FR-082). */
+	cancel(): void;
+	/** Attempts consumed so far, so a retry storm is observable rather than inferred. */
+	attempts(): number;
+	/** True once the per-session budget is spent. */
+	exhausted(): boolean;
+}
+
+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.
+ *
+ * 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.
+ */
+export function runWithRetry(options: RetryRunnerOptions): RetryHandle {
+	const {
+		config,
+		attempt,
+		onExhausted,
+		setTimeoutFn = setTimeout,
+		clearTimeoutFn = clearTimeout,
+		random = Math.random,
+	} = options;
+
+	let attemptCount = 0;
+	let cancelled = false;
+	let pending: TimerHandle | undefined;
+
+	const schedule = (delayMs: number): void => {
+		pending = setTimeoutFn(() => {
+			pending = undefined;
+			run().catch(() => undefined);
+		}, delayMs);
+	};
+
+	const run = async (): Promise<void> => {
+		if (cancelled) {
+			return;
+		}
+		attemptCount += 1;
+		let succeeded = false;
+		try {
+			succeeded = await attempt(attemptCount);
+		} catch {
+			// A throwing attempt is a failed attempt, nothing more. Letting it escape
+			// would abandon the schedule and, for finalization, silently drop a paid
+			// transaction.
+			succeeded = false;
+		}
+		if (cancelled || succeeded) {
+			return;
+		}
+		if (attemptCount >= config.maxAttempts) {
+			onExhausted?.(attemptCount);
+			return;
+		}
+		schedule(backoffDelayMs(attemptCount + 1, config, random));
+	};
+
+	// Fire the first attempt immediately; the schedule owns everything after it.
+	run().catch(() => undefined);
+
+	return {
+		cancel(): void {
+			cancelled = true;
+			if (pending !== undefined) {
+				clearTimeoutFn(pending);
+				pending = undefined;
+			}
+		},
+		attempts: () => attemptCount,
+		exhausted: () => attemptCount >= config.maxAttempts,
+	};
+}

package/src/core/timers.ts

@@ -0,0 +1,249 @@
+/**
+ * Timeout, retry, and cache policy.
+ *
+ * Defaults and bounds live here rather than at each call site so there is one
+ * place to read what the package will wait for, and so consumers can read the
+ * values they are bound by instead of discovering them from a timeout in
+ * production.
+ *
+ * Out-of-band values are a configuration error rather than being silently
+ * clamped: quietly turning a 1-second timeout into 3 seconds would tell the app
+ * it configured something it did not.
+ */
+
+import { PaymentConfigError } from '../diagnostics/errors';
+import type {
+	BackoffConfig,
+	RetryConfig,
+	TimeoutConfig,
+} from '../config/types';
+
+/** Local IPC to Play Services. Slower than this means unavailable, not busy. */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/** A network round trip; a paywall that hangs longer should show its error state. */
+export const DEFAULT_PRODUCT_QUERY_TIMEOUT_MS = 15_000;
+/** Runs at startup, so it must not hold the first render hostage. */
+export const DEFAULT_SYNC_TIMEOUT_MS = 20_000;
+/**
+ * Covers opening the store surface only.
+ *
+ * Time the user spends *inside* the store's own UI is deliberately excluded
+ * (FR-035): a user reading the terms, switching to their banking app for an OTP,
+ * or simply hesitating must never have their purchase cancelled by our clock.
+ */
+export const DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS = 30_000;
+/** Per finalize attempt, not per transaction — the queue owns overall persistence. */
+export const DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS = 15_000;
+
+export const CONNECT_TIMEOUT_BOUNDS = { min: 3_000, max: 60_000 } as const;
+export const PRODUCT_QUERY_TIMEOUT_BOUNDS = { min: 3_000, max: 60_000 } as const;
+export const SYNC_TIMEOUT_BOUNDS = { min: 5_000, max: 120_000 } as const;
+export const PURCHASE_LAUNCH_TIMEOUT_BOUNDS = {
+	min: 5_000,
+	max: 120_000,
+} as const;
+export const FINALIZE_ATTEMPT_TIMEOUT_BOUNDS = {
+	min: 3_000,
+	max: 60_000,
+} as const;
+
+/**
+ * Prices and offer eligibility are shown at the moment of purchase, so a short
+ * TTL with on-demand refresh beats a long one (FR-029).
+ */
+export const DEFAULT_PRODUCT_CACHE_TTL_MS = 900_000;
+export const PRODUCT_CACHE_TTL_BOUNDS = { min: 60_000, max: 86_400_000 } as const;
+
+/**
+ * How long a successful sync keeps entitlements trustworthy offline: **7 days**.
+ *
+ * Fixed by the specification (FR-055) after weighing both failure directions.
+ * The realistic offline cases — travel, poor coverage, a device left unused —
+ * resolve within days. Seven days covers a holiday without connectivity while
+ * bounding how long a refunded entitlement can outlive its refund to one week.
+ *
+ * Past this the entitlement becomes `unknown`, never `not_entitled` (FR-055a):
+ * the package stops asserting rather than telling a paying customer they did not
+ * pay.
+ */
+export const DEFAULT_STALE_AFTER_MS = 604_800_000;
+export const STALE_AFTER_BOUNDS = {
+	min: 3_600_000,
+	max: 7_776_000_000,
+} as const;
+
+/** Keeps rapid app switching from becoming a request storm (PERF-002). */
+export const DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS = 60_000;
+export const FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS = {
+	min: 0,
+	max: 3_600_000,
+} as const;
+
+/** Bounded so a dropped billing connection cannot become a retry storm (FR-020). */
+export const DEFAULT_RECONNECT_BACKOFF: Required<BackoffConfig> = {
+	initialDelayMs: 1_000,
+	maxDelayMs: 30_000,
+	factor: 2,
+	maxAttempts: 5,
+	jitter: true,
+};
+
+/**
+ * Finalize retry.
+ *
+ * Bounded **per session** but never permanently abandoned: Google auto-refunds
+ * an unacknowledged purchase after three days, so exhausting this session's
+ * attempts must leave the transaction queued for the next launch, not dropped
+ * (FR-045).
+ */
+export const DEFAULT_FINALIZE_BACKOFF: Required<BackoffConfig> = {
+	initialDelayMs: 2_000,
+	maxDelayMs: 60_000,
+	factor: 2,
+	maxAttempts: 5,
+	jitter: true,
+};
+
+export const BACKOFF_MAX_DELAY_BOUNDS = { min: 5_000, max: 600_000 } as const;
+export const BACKOFF_ATTEMPT_BOUNDS = { min: 1, max: 10 } as const;
+
+interface Bounds {
+	readonly min: number;
+	readonly max: number;
+}
+
+function requireInBounds(
+	label: string,
+	value: number | undefined,
+	fallback: number,
+	bounds: Bounds,
+): number {
+	if (value === undefined) {
+		return fallback;
+	}
+	if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
+		throw new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CATALOG',
+			message: `${label} must be between ${bounds.min} and ${bounds.max}ms, received ${value}`,
+			operation: 'configure',
+			offenders: [label],
+		});
+	}
+	return value;
+}
+
+export interface ResolvedTimeouts {
+	connectMs: number;
+	productQueryMs: number;
+	syncMs: number;
+	purchaseLaunchMs: number;
+	finalizeAttemptMs: number;
+}
+
+export function resolveTimeouts(config?: TimeoutConfig): ResolvedTimeouts {
+	return {
+		connectMs: requireInBounds(
+			'timeouts.connectMs',
+			config?.connectMs,
+			DEFAULT_CONNECT_TIMEOUT_MS,
+			CONNECT_TIMEOUT_BOUNDS,
+		),
+		productQueryMs: requireInBounds(
+			'timeouts.productQueryMs',
+			config?.productQueryMs,
+			DEFAULT_PRODUCT_QUERY_TIMEOUT_MS,
+			PRODUCT_QUERY_TIMEOUT_BOUNDS,
+		),
+		syncMs: requireInBounds(
+			'timeouts.syncMs',
+			config?.syncMs,
+			DEFAULT_SYNC_TIMEOUT_MS,
+			SYNC_TIMEOUT_BOUNDS,
+		),
+		purchaseLaunchMs: requireInBounds(
+			'timeouts.purchaseLaunchMs',
+			config?.purchaseLaunchMs,
+			DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS,
+			PURCHASE_LAUNCH_TIMEOUT_BOUNDS,
+		),
+		finalizeAttemptMs: requireInBounds(
+			'timeouts.finalizeAttemptMs',
+			config?.finalizeAttemptMs,
+			DEFAULT_FINALIZE_ATTEMPT_TIMEOUT_MS,
+			FINALIZE_ATTEMPT_TIMEOUT_BOUNDS,
+		),
+	};
+}
+
+function resolveBackoff(
+	label: string,
+	config: BackoffConfig | undefined,
+	fallback: Required<BackoffConfig>,
+): Required<BackoffConfig> {
+	const maxDelayMs = requireInBounds(
+		`${label}.maxDelayMs`,
+		config?.maxDelayMs,
+		fallback.maxDelayMs,
+		BACKOFF_MAX_DELAY_BOUNDS,
+	);
+	const maxAttempts = requireInBounds(
+		`${label}.maxAttempts`,
+		config?.maxAttempts,
+		fallback.maxAttempts,
+		BACKOFF_ATTEMPT_BOUNDS,
+	);
+	return {
+		initialDelayMs: config?.initialDelayMs ?? fallback.initialDelayMs,
+		maxDelayMs,
+		factor: config?.factor ?? fallback.factor,
+		maxAttempts,
+		jitter: config?.jitter ?? fallback.jitter,
+	};
+}
+
+export interface ResolvedRetry {
+	reconnect: Required<BackoffConfig>;
+	finalize: Required<BackoffConfig>;
+}
+
+export function resolveRetry(config?: RetryConfig): ResolvedRetry {
+	return {
+		reconnect: resolveBackoff(
+			'retry.reconnect',
+			config?.reconnect,
+			DEFAULT_RECONNECT_BACKOFF,
+		),
+		finalize: resolveBackoff(
+			'retry.finalize',
+			config?.finalize,
+			DEFAULT_FINALIZE_BACKOFF,
+		),
+	};
+}
+
+export function resolveStaleAfterMs(value?: number): number {
+	return requireInBounds(
+		'staleAfterMs',
+		value,
+		DEFAULT_STALE_AFTER_MS,
+		STALE_AFTER_BOUNDS,
+	);
+}
+
+export function resolveProductCacheTtlMs(value?: number): number {
+	return requireInBounds(
+		'productCacheTtlMs',
+		value,
+		DEFAULT_PRODUCT_CACHE_TTL_MS,
+		PRODUCT_CACHE_TTL_BOUNDS,
+	);
+}
+
+export function resolveForegroundSyncMinIntervalMs(value?: number): number {
+	return requireInBounds(
+		'foregroundSyncMinIntervalMs',
+		value,
+		DEFAULT_FOREGROUND_SYNC_MIN_INTERVAL_MS,
+		FOREGROUND_SYNC_MIN_INTERVAL_BOUNDS,
+	);
+}

package/src/diagnostics/errors.ts

@@ -0,0 +1,110 @@
+/**
+ * Normalized public errors.
+ *
+ * Error codes are **public API**: renaming one is a breaking change (FR-078,
+ * LIB-008). They are the vocabulary an app branches on, so they must outlive any
+ * internal refactor and must never leak a store's own code.
+ */
+
+export const PAYMENT_ERROR_CODES = [
+	'PAYMENT_NOT_CONFIGURED',
+	'PAYMENT_INVALID_CATALOG',
+	'PAYMENT_NOT_READY',
+	'PAYMENT_DISABLED',
+	'PAYMENT_UNAVAILABLE',
+	'PAYMENT_UNSUPPORTED_PLATFORM',
+	'PAYMENT_ENVIRONMENT_BLOCKED',
+	'PAYMENT_PRODUCTION_CONFIG_IN_NON_PRODUCTION_BUILD',
+	'PAYMENT_PURCHASE_IN_PROGRESS',
+	'PAYMENT_USER_CANCELLED',
+	'PAYMENT_PENDING',
+	'PAYMENT_ALREADY_OWNED',
+	'PAYMENT_INELIGIBLE',
+	'PAYMENT_UNKNOWN_PRODUCT',
+	'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION',
+	'PAYMENT_TIMEOUT',
+	'PAYMENT_NETWORK_ERROR',
+	'PAYMENT_STORE_ERROR',
+	'PAYMENT_FINALIZE_FAILED',
+	'PAYMENT_VALIDATION_REJECTED',
+	'PAYMENT_VALIDATION_UNAVAILABLE',
+	'PAYMENT_STORAGE_UNAVAILABLE',
+] as const;
+
+export type PaymentErrorCode = (typeof PAYMENT_ERROR_CODES)[number];
+
+/** Which operation produced an error. Part of the public error shape (FR-078). */
+export type PaymentOperation =
+	| 'configure'
+	| 'initialize'
+	| 'getProducts'
+	| 'purchase'
+	| 'finalize'
+	| 'consume'
+	| 'sync'
+	| 'restore'
+	| 'changePlan'
+	| 'validate'
+	| 'persist';
+
+export class PaymentError extends Error {
+	readonly code: PaymentErrorCode;
+	readonly operation: PaymentOperation;
+	readonly retryable: boolean;
+	/** Redacted where appropriate — never a raw receipt, token, or store object (FR-074). */
+	readonly cause?: string;
+
+	constructor(init: {
+		code: PaymentErrorCode;
+		message: string;
+		operation: PaymentOperation;
+		retryable?: boolean;
+		cause?: string;
+	}) {
+		super(init.message);
+		this.name = 'PaymentError';
+		this.code = init.code;
+		this.operation = init.operation;
+		this.retryable = init.retryable ?? false;
+		this.cause = init.cause;
+	}
+}
+
+/**
+ * A configuration problem the app can act on.
+ *
+ * Separate from `PaymentError` because configuration faults are developer-facing
+ * and must never be shown to an end user — the message-key map keeps that
+ * separation explicit (FR-085).
+ */
+export class PaymentConfigError extends PaymentError {
+	/** The offending catalog entries or entitlement keys, named (FR-011). */
+	readonly offenders: string[];
+
+	constructor(init: {
+		code: PaymentErrorCode;
+		message: string;
+		operation: PaymentOperation;
+		offenders?: string[];
+	}) {
+		super({ ...init, retryable: false });
+		this.name = 'PaymentConfigError';
+		this.offenders = init.offenders ?? [];
+	}
+}
+
+/**
+ * Strips anything that must never reach a log or event.
+ *
+ * Applied at the boundary rather than trusted to call sites: a single forgotten
+ * interpolation is how receipts end up in logs (NFR-006).
+ */
+export function redact(value: unknown): string {
+	if (value instanceof Error) {
+		return value.message;
+	}
+	if (typeof value === 'string') {
+		return value;
+	}
+	return '[redacted]';
+}