@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/core/timers.ts

@@ -1,267 +1,272 @@
-/**
- * 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;
-/** The app's backend hook. A user is waiting on a purchase result behind it. */
-export const DEFAULT_VALIDATE_TIMEOUT_MS = 15_000;
-/**
- * The ceiling on a purchase flow whose outcome includes the user's own time in
- * the store UI, so is otherwise untimed (FR-035). Not a timeout on the user: it
- * exists only so a binding that never answers cannot hold the purchase lock for
- * the rest of the session. A purchase that completes later still arrives through
- * the store update channel and is granted then.
- */
-export const PURCHASE_FLOW_CEILING_MS = 10 * 60_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;
-export const VALIDATE_TIMEOUT_BOUNDS = { min: 3_000, max: 120_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;
-	validateMs: 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,
-		),
-		validateMs: requireInBounds(
-			'timeouts.validateMs',
-			config?.validateMs,
-			DEFAULT_VALIDATE_TIMEOUT_MS,
-			VALIDATE_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,
-	);
-}
+/**
+ * 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 { checkRange, type Range } from '@chipmobilesdk/rn-core';
+
+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;
+/** The app's backend hook. A user is waiting on a purchase result behind it. */
+export const DEFAULT_VALIDATE_TIMEOUT_MS = 15_000;
+/**
+ * The ceiling on a purchase flow whose outcome includes the user's own time in
+ * the store UI, so is otherwise untimed (FR-035). Not a timeout on the user: it
+ * exists only so a binding that never answers cannot hold the purchase lock for
+ * the rest of the session. A purchase that completes later still arrives through
+ * the store update channel and is granted then.
+ */
+export const PURCHASE_FLOW_CEILING_MS = 10 * 60_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;
+export const VALIDATE_TIMEOUT_BOUNDS = { min: 3_000, max: 120_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;
+/** A first retry sooner than this is a storm; later than this, the user has given up. */
+export const BACKOFF_INITIAL_DELAY_BOUNDS = { min: 100, max: 60_000 } as const;
+/** 1 is a constant delay; 0 or below would retry at once, forever (CORE-05). */
+export const BACKOFF_FACTOR_BOUNDS = { min: 1, max: 10 } as const;
+
+function invalidConfig(label: string) {
+	return (message: string) =>
+		new PaymentConfigError({
+			code: 'PAYMENT_INVALID_CONFIG',
+			message,
+			operation: 'configure',
+			offenders: [label],
+		});
+}
+
+function requireInBounds(
+	label: string,
+	value: number | undefined,
+	fallback: number,
+	bounds: Range,
+	unit = 'ms',
+): number {
+	return value === undefined
+		? fallback
+		: checkRange(label, value, bounds, invalidConfig(label), unit);
+}
+
+export interface ResolvedTimeouts {
+	connectMs: number;
+	productQueryMs: number;
+	syncMs: number;
+	purchaseLaunchMs: number;
+	finalizeAttemptMs: number;
+	validateMs: 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,
+		),
+		validateMs: requireInBounds(
+			'timeouts.validateMs',
+			config?.validateMs,
+			DEFAULT_VALIDATE_TIMEOUT_MS,
+			VALIDATE_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,
+		'',
+	);
+	const initialDelayMs = requireInBounds(
+		`${label}.initialDelayMs`,
+		config?.initialDelayMs,
+		fallback.initialDelayMs,
+		BACKOFF_INITIAL_DELAY_BOUNDS,
+	);
+	const factor = requireInBounds(
+		`${label}.factor`,
+		config?.factor,
+		fallback.factor,
+		BACKOFF_FACTOR_BOUNDS,
+		'',
+	);
+	if (initialDelayMs > maxDelayMs) {
+		throw invalidConfig(`${label}.initialDelayMs`)(
+			`${label}.initialDelayMs (${initialDelayMs}ms) exceeds ${label}.maxDelayMs (${maxDelayMs}ms)`,
+		);
+	}
+	return {
+		initialDelayMs,
+		maxDelayMs,
+		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,
+	);
+}