@chipmobilesdk/rn-payment 0.4.1 → 0.6.0

package/src/core/mutex.ts

@@ -14,113 +14,12 @@
  * expects.
  */
 
-/**
- * Joins concurrent callers onto one in-flight operation.
- *
- * Callers arriving during the flight receive the same promise. Once it settles
- * the slot clears, so a later call starts fresh — this is de-duplication, not
- * caching.
- */
-export function createSingleFlight<T>(): {
-	run(operation: () => Promise<T>): Promise<T>;
-	inFlight(): boolean;
-} {
-	let current: Promise<T> | undefined;
-
-	return {
-		run(operation: () => Promise<T>): Promise<T> {
-			if (current) {
-				return current;
-			}
-			const flight = operation().finally(() => {
-				if (current === flight) {
-					current = undefined;
-				}
-			});
-			current = flight;
-			return flight;
-		},
-		inFlight: () => current !== undefined,
-	};
-}
-
-/** Distinguishes "refused because busy" from any other failure, without throwing. */
-export type ExclusiveOutcome<T> = { acquired: true; value: T } | { acquired: false };
-
-/**
- * Admits one operation at a time and refuses the rest.
- *
- * Refusal is returned, not thrown, because for a purchase it is a normal
- * outcome the app reports to the user — not an error to be caught.
- */
-export function createExclusive(): {
-	run<T>(operation: () => Promise<T>): Promise<ExclusiveOutcome<T>>;
-	busy(): boolean;
-} {
-	let held = false;
-
-	return {
-		async run<T>(operation: () => Promise<T>): Promise<ExclusiveOutcome<T>> {
-			if (held) {
-				return { acquired: false };
-			}
-			held = true;
-			try {
-				return { acquired: true, value: await operation() };
-			} finally {
-				held = false;
-			}
-		},
-		busy: () => held,
-	};
-}
-
-/**
- * Rate limiter for automatic foreground sync (PERF-002).
- *
- * Rejects rather than defers: a skipped automatic sync costs nothing because the
- * next foreground event will try again, whereas a queue of deferred syncs would
- * fire a burst the moment the interval elapsed — the exact storm this prevents.
- */
-export function createRateLimiter(
-	minIntervalMs: number,
-	now: () => number = Date.now,
-): { tryAcquire(): boolean; reset(): void } {
-	let lastAt: number | undefined;
-
-	return {
-		tryAcquire(): boolean {
-			const at = now();
-			if (lastAt !== undefined && at - lastAt < minIntervalMs) {
-				return false;
-			}
-			lastAt = at;
-			return true;
-		},
-		reset(): void {
-			lastAt = undefined;
-		},
-	};
-}
-
-/**
- * Rejects with a `PAYMENT_TIMEOUT`-shaped error after `ms`.
- *
- * Always clears its timer, including on the success path: a package that leaks a
- * timer per operation fails the cleanup guarantee (FR-082, PERF-002).
- */
-export function withTimeout<T>(
-	promise: Promise<T>,
-	ms: number,
-	onTimeout: () => Error,
-): Promise<T> {
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const timeout = new Promise<never>((_, reject) => {
-		timer = setTimeout(() => reject(onTimeout()), ms);
-	});
-	return Promise.race([promise, timeout]).finally(() => {
-		if (timer !== undefined) {
-			clearTimeout(timer);
-		}
-	}) as Promise<T>;
-}
+// The primitives themselves are rn-core's; the reasoning above is why rn-payment
+// uses each where it does.
+export {
+	createExclusive,
+	createRateLimiter,
+	createSingleFlight,
+	withTimeout,
+	type ExclusiveOutcome,
+} from '@chipmobilesdk/rn-core';

package/src/core/retry.ts

@@ -9,10 +9,9 @@
  * schedule without burning real time.
  */
 
-import type { BackoffConfig } from '../config/types';
+import { computeBackoff } from '@chipmobilesdk/rn-core';
 
-/** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
-type TimerHandle = ReturnType<typeof setTimeout> | number;
+import type { BackoffConfig } from '../config/types';
 
 /**
  * Delay before `attempt` (1-based), capped and optionally jittered.
@@ -25,109 +24,15 @@ export function backoffDelayMs(
 	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;
+	return computeBackoff(attempt, toSpec(config), random);
 }
 
-/** 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);
-
+function toSpec(config: Required<BackoffConfig>) {
 	return {
-		cancel(): void {
-			cancelled = true;
-			if (pending !== undefined) {
-				clearTimeoutFn(pending);
-				pending = undefined;
-			}
-		},
-		attempts: () => attemptCount,
-		exhausted: () => attemptCount >= config.maxAttempts,
+		initialDelayMs: config.initialDelayMs,
+		maxDelayMs: config.maxDelayMs,
+		factor: config.factor,
+		jitter: config.jitter ? ('full' as const) : ('none' as const),
+		maxAttempts: config.maxAttempts,
 	};
 }

package/src/core/timers.ts

@@ -11,6 +11,8 @@
  * 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';
 
@@ -113,30 +115,31 @@ export const DEFAULT_FINALIZE_BACKOFF: Required<BackoffConfig> = {
 
 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;
 
-interface Bounds {
-	readonly min: number;
-	readonly max: number;
+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: Bounds,
+	bounds: Range,
+	unit = 'ms',
 ): 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;
+	return value === undefined
+		? fallback
+		: checkRange(label, value, bounds, invalidConfig(label), unit);
 }
 
 export interface ResolvedTimeouts {
@@ -205,11 +208,30 @@ function resolveBackoff(
 		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: config?.initialDelayMs ?? fallback.initialDelayMs,
+		initialDelayMs,
 		maxDelayMs,
-		factor: config?.factor ?? fallback.factor,
+		factor,
 		maxAttempts,
 		jitter: config?.jitter ?? fallback.jitter,
 	};

package/src/diagnostics/errors.ts

@@ -6,6 +6,10 @@
  * internal refactor and must never leak a store's own code.
  */
 
+import { REDACTED, SdkError, createRedactor } from '@chipmobilesdk/rn-core';
+
+const identifiers = createRedactor();
+
 export const PAYMENT_ERROR_CODES = [
 	'PAYMENT_NOT_CONFIGURED',
 	'PAYMENT_INVALID_CATALOG',
@@ -31,6 +35,11 @@ export const PAYMENT_ERROR_CODES = [
 	'PAYMENT_STORAGE_UNAVAILABLE',
 	/** `consume` on a transaction that is not a consumable, added in 0.3.2. */
 	'PAYMENT_NOT_CONSUMABLE',
+	/**
+	 * A timeout, backoff or interval outside its bounds, added in 0.5.0. These
+	 * used to be reported as `PAYMENT_INVALID_CATALOG`, which is about products.
+	 */
+	'PAYMENT_INVALID_CONFIG',
 ] as const;
 
 export type PaymentErrorCode = (typeof PAYMENT_ERROR_CODES)[number];
@@ -49,10 +58,9 @@ export type PaymentOperation =
 	| 'validate'
 	| 'persist';
 
-export class PaymentError extends Error {
-	readonly code: PaymentErrorCode;
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-payment'`. */
+export class PaymentError extends SdkError<PaymentErrorCode> {
 	readonly operation: PaymentOperation;
-	readonly retryable: boolean;
 	/** Redacted where appropriate — never a raw receipt, token, or store object (FR-074). */
 	readonly cause?: string;
 
@@ -63,11 +71,13 @@ export class PaymentError extends Error {
 		retryable?: boolean;
 		cause?: string;
 	}) {
-		super(init.message);
+		super('rn-payment', init.code, {
+			message: init.message,
+			retryable: init.retryable ?? false,
+			redactedCause: init.cause,
+		});
 		this.name = 'PaymentError';
-		this.code = init.code;
 		this.operation = init.operation;
-		this.retryable = init.retryable ?? false;
 		this.cause = init.cause;
 	}
 }
@@ -107,11 +117,8 @@ export class PaymentConfigError extends PaymentError {
  * purchase token or an account id and nothing here can tell which.
  */
 export function redact(value: unknown): string {
-	if (value instanceof PaymentError) {
-		return value.code;
-	}
-	if (value instanceof Error) {
-		return value.name;
-	}
-	return '[redacted]';
+	// An SDK error reduces to its code and any other Error to its class name
+	// (rn-core's identifier-only redactor). Strings never survive here, not even
+	// a leading constant: a store message is free text from a payments SDK.
+	return value instanceof Error ? identifiers.text(value) : REDACTED;
 }

package/src/diagnostics/events.ts

@@ -10,6 +10,16 @@
  * obfuscated account identifier, and the cache-scope token.
  */
 
+import {
+	createDiagnosticChannel,
+	createEmitter as createCoreEmitter,
+} from '@chipmobilesdk/rn-core';
+
+/** Every delivered event also goes to the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<PaymentEvent['type'] | 'listener_reporter_failed'>(
+	'rn-payment',
+);
+
 import { redact, type PaymentErrorCode, type PaymentOperation } from './errors';
 import type {
 	EntitlementKey,
@@ -188,49 +198,58 @@ export interface PaymentEmitter {
 export function createEmitter(
 	onListenerError?: (error: unknown, event: PaymentEvent) => void,
 ): PaymentEmitter {
-	const listeners = new Set<PaymentEventListener>();
+	// The event whose listeners are running, so a failure is reported against it.
+	let dispatching: PaymentEvent | null = null;
 	let isDisposed = false;
-
-	const emit = (event: PaymentEvent): void => {
-		if (isDisposed) {
-			return;
-		}
-		// Snapshot first: a listener that subscribes or unsubscribes during
-		// delivery must not mutate the set being iterated.
-		for (const listener of [...listeners]) {
+	// rn-core's emitter: a snapshot per emit, each listener isolated, idempotent
+	// unsubscribe. Even the error reporter is isolated: if it throws, rn-core
+	// rethrows that on a fresh task rather than into the emit.
+	const emitter = createCoreEmitter<PaymentEvent>({
+		onListenerError: error => {
+			if (!dispatching) return;
 			try {
-				listener(event);
-			} catch (error) {
-				try {
-					onListenerError?.(error, event);
-				} catch {
-					// Even the error reporter is not trusted to behave.
-				}
+				onListenerError?.(error, dispatching);
+			} catch {
+				// The app's own reporter failed: nothing in the app is left to tell, so
+				// the failure goes to the SDK sinks rather than becoming an uncaught
+				// error on some later tick (FR-080).
+				channel.emit('listener_reporter_failed', 'error', {
+					eventType: dispatching.type,
+				});
 			}
-		}
-	};
+		},
+	});
 
 	return {
-		emit,
-		subscribe(listener: PaymentEventListener): Unsubscribe {
+		emit(event) {
 			if (isDisposed) {
-				return () => undefined;
+				return;
 			}
-			listeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
+			const previous = dispatching;
+			dispatching = event;
+			try {
+				if (emitter.emit(event)) {
+					// The type and the cycle only: payment events carry product and
+					// entitlement keys an app may treat as personal.
+					channel.emit(
+						event.type,
+						/failed|error|blocked|rejected|revoked/.test(event.type) ? 'warn' : 'info',
+						undefined,
+						event.correlationId,
+					);
 				}
-				removed = true;
-				listeners.delete(listener);
-			};
+			} finally {
+				dispatching = previous;
+			}
+		},
+		subscribe(listener: PaymentEventListener): Unsubscribe {
+			return isDisposed ? () => undefined : emitter.subscribe(listener);
 		},
 		dispose(): void {
 			isDisposed = true;
-			listeners.clear();
+			emitter.dispose();
 		},
-		listenerCount: () => listeners.size,
+		listenerCount: () => emitter.listenerCount(),
 		disposed: () => isDisposed,
 	};
 }
@@ -238,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/diagnostics/messageKeys.ts

@@ -14,6 +14,8 @@
  */
 
 /** Copy an end user may reasonably be shown. */
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
 export interface PaymentUserMessageMap {
 	'payment.state.pending': string;
 	'payment.state.alreadyOwned': string;
@@ -68,20 +70,24 @@ export const DEFAULT_DEVELOPER_MESSAGES: PaymentDeveloperMessageMap = {
 		'Purchase blocked: this environment may not create a real transaction',
 };
 
-export const DEFAULT_MESSAGES: PaymentMessageMap = {
-	...DEFAULT_USER_MESSAGES,
-	...DEFAULT_DEVELOPER_MESSAGES,
-};
+/**
+ * The catalog as an rn-core message set. Register `paymentMessages.user` with
+ * rn-i18n to translate it like app copy; the developer copy stays out of bundles.
+ */
+export const paymentMessages = defineMessages({
+	user: DEFAULT_USER_MESSAGES,
+	developer: DEFAULT_DEVELOPER_MESSAGES,
+});
+
+export const DEFAULT_MESSAGES: PaymentMessageMap = paymentMessages.defaults;
 
 /** Every user-actionable key, for an app building its translation resource. */
-export const USER_MESSAGE_KEYS = Object.keys(DEFAULT_USER_MESSAGES) as PaymentUserMessageKey[];
+export const USER_MESSAGE_KEYS = paymentMessages.userKeys as PaymentUserMessageKey[];
 
 /** Every developer-facing key, so an app can exclude them from user-visible bundles. */
-export const DEVELOPER_MESSAGE_KEYS = Object.keys(
-	DEFAULT_DEVELOPER_MESSAGES,
-) as PaymentDeveloperMessageKey[];
+export const DEVELOPER_MESSAGE_KEYS = paymentMessages.developerKeys as PaymentDeveloperMessageKey[];
 
 /** True for keys safe to show an end user. Lets an app assert that at its boundary. */
 export function isUserMessageKey(key: PaymentMessageKey): key is PaymentUserMessageKey {
-	return key in DEFAULT_USER_MESSAGES;
+	return paymentMessages.audienceOf(key) === 'user';
 }