@chipmobilesdk/rn-payment 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,146 @@
 # @chipmobilesdk/rn-payment
 
+## 0.5.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -192,6 +192,13 @@ what "foreground" means for an app that may be backgrounded by its own modal, a
 biometric prompt, or the store's own purchase sheet. It is rate-limited
 regardless, so calling it liberally is safe.
 
+If "back from the background" is what you mean, opt in instead of wiring `AppState`:
+`<PaymentProvider syncOnForeground>` or `syncOnForeground(engine)` (returns an
+unsubscribe). Both listen through rn-core's shared lifecycle port, so they add no
+native subscription of their own, and a trip through `inactive` alone does not count.
+On Android the Play purchase sheet does background the app, so a purchase is followed
+by one rate-limited sync.
+
 ---
 
 ## Catalog and entitlement mapping
@@ -604,7 +611,9 @@ import { DEFAULT_USER_MESSAGES, USER_MESSAGE_KEYS, isUserMessageKey } from '@chi
 
 User-actionable and developer copy are **separate maps**, so you cannot
 accidentally show "Payment catalog is invalid" to a customer. `isUserMessageKey()`
-lets you assert that at your own boundary.
+lets you assert that at your own boundary. `paymentMessages` is the same catalog as
+an rn-core message set; register the user copy with rn-i18n in one line:
+`runtimeEntriesFromCatalog(paymentMessages.user)`.
 
 Message keys are public API; renaming one is a breaking change.
 
@@ -612,6 +621,9 @@ Message keys are public API; renaming one is a breaking change.
 
 ## Events and errors
 
+Every error is a `PaymentError` (or `PaymentConfigError`) with a stable `code`, the
+`operation` and a `retryable` flag. `PaymentError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
 20 event types, each carrying a timestamp and — within a purchase cycle — one
 `correlationId`. The bar is that the event stream **alone** is enough to
 reconstruct a transaction's lifecycle, so "the user says they paid but has no
@@ -647,6 +659,11 @@ The failure goes to your `logger`, not back into the event stream.
 Errors carry a stable `code`, a log-safe `message`, the `operation`, a `retryable`
 flag, and a redacted `cause`. Error codes are public API.
 
+A timeout, backoff or interval outside its bounds throws `PaymentConfigError` with
+`PAYMENT_INVALID_CONFIG`, naming the field in `offenders`. Backoff checks every
+field: `initialDelayMs` 100 ms to 60 s and not above `maxDelayMs`, `factor` 1 to
+10, `maxDelayMs` 5 s to 10 min, `maxAttempts` 1 to 10.
+
 ---
 
 ## Wiring an entitlement to another system
@@ -710,6 +727,12 @@ store.pushPurchaseUpdate(...);  // deliver a settlement with no sync
 `./testing` is a separate entrypoint so test doubles cannot reach a production
 bundle.
 
+`runProviderPortConformance(harness)` holds the checks every store adapter must pass:
+connection and a dropped service, products with the store's own price, pending
+purchases flagged rather than filtered, a bought and a cancelled flow, and
+finalization that is safe twice. The package runs it against the fake store and the
+Play adapter; an iOS adapter, or a device run from a demo screen, uses the same suite.
+
 ### Licence testers, for device verification
 
 1. Play Console → **Setup → Licence testing**, add tester accounts.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-payment",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"description": "Reusable in-app payment and entitlement capability for ChipMobileSdk React Native apps",
@@ -27,9 +27,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

package/skills/sdk-rn-payment/SKILL.md

@@ -91,6 +91,8 @@ 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.
+When a return from the background is enough, opt in with `<PaymentProvider
+syncOnForeground>` or `syncOnForeground(engine)` (rn-core's shared lifecycle port).
 
 ## Public API
 
@@ -103,8 +105,8 @@ environment; everything else returns a typed result) · `createStoreProvider` ·
 `DEFAULT_USER_MESSAGES`, `DEFAULT_DEVELOPER_MESSAGES`, `USER_MESSAGE_KEYS`,
 `DEVELOPER_MESSAGE_KEYS`, `isUserMessageKey` · timeout/retry/cache defaults and bounds
 (`DEFAULT_STALE_AFTER_MS`, `DEFAULT_PURCHASE_LAUNCH_TIMEOUT_MS`, `STALE_AFTER_BOUNDS`, …)
-· `createFakeStore`, `makePurchase` from `@chipmobilesdk/rn-payment/testing` (test
-doubles only).
+· `createFakeStore`, `makePurchase`, `runProviderPortConformance` from
+`@chipmobilesdk/rn-payment/testing` (test doubles and the store-adapter suite only).
 
 Engine: `initialize`, `cleanup`, `getStatus`, `subscribeStatus`, `getEntitlement`,
 `getAllEntitlements`, `subscribeEntitlements`, `getPendingPurchases`,

package/src/adapter/iap-adapter.ts

@@ -36,9 +36,12 @@
  * shortcut.
  */
 
+import { createListenerSet, lazyPeer } from '@chipmobilesdk/rn-core';
+
 import type { RequestPurchaseProps, SubscriptionReplacementModeAndroid } from 'react-native-iap';
 
 import type { ProductType, Unsubscribe } from '../config/types';
+import { PaymentError, redact } from '../diagnostics/errors';
 import type {
 	ProviderCapabilities,
 	ProviderConnectOutcome,
@@ -194,10 +197,27 @@ export function toRequestProps(request: ProviderPurchaseRequest): RequestPurchas
 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.
+const iapPeer = lazyPeer('react-native-iap', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-iap') as IapModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
 function loadModule(): IapModule {
-	// Required lazily so importing the package does not require the native module.
-	const mod = require('react-native-iap') as IapModule;
-	return mod;
+	return iapPeer.require(
+		(peer, cause) =>
+			new PaymentError({
+				code: 'PAYMENT_UNAVAILABLE',
+				message: `${peer} is not installed or its native module is not linked`,
+				operation: 'initialize',
+				cause: redact(cause),
+			}),
+	);
 }
 
 function toMicros(value: string | number | undefined): number {
@@ -380,10 +400,10 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 	/** Tracked here, never read from the binding — see the openiap#408 note above. */
 	let connected = false;
 
-	const connectionListeners = new Set<(connected: boolean, reason?: string) => void>();
-	const purchaseListeners = new Set<(purchase: ProviderPurchase) => void>();
+	const connectionListeners = createListenerSet<[boolean, string | undefined]>();
+	const purchaseListeners = createListenerSet<[ProviderPurchase]>();
 	/** Only an in-flight `launchPurchase` listens here; see there. */
-	const purchaseErrorListeners = new Set<(error: RawPurchaseError) => void>();
+	const purchaseErrorListeners = createListenerSet<[RawPurchaseError]>();
 	let updateSub: { remove(): void } | undefined;
 	let errorSub: { remove(): void } | undefined;
 
@@ -399,9 +419,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			return;
 		}
 		connected = next;
-		for (const listener of connectionListeners) {
-			listener(next, reason);
-		}
+		connectionListeners.notify(next, reason);
 	};
 
 	const attachListeners = (): void => {
@@ -411,10 +429,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		detachListeners();
 		const mod = module();
 		updateSub = mod.purchaseUpdatedListener(raw => {
-			const purchase = normalizePurchase(raw);
-			for (const listener of purchaseListeners) {
-				listener(purchase);
-			}
+			purchaseListeners.notify(normalizePurchase(raw));
 		});
 		errorSub = mod.purchaseErrorListener(error => {
 			// A `not-prepared` error is the one signal the binding gives that the
@@ -423,9 +438,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 			if (mapErrorCode(error.code) === 'not_ready') {
 				notifyConnection(false, 'not_prepared');
 			}
-			for (const listener of purchaseErrorListeners) {
-				listener(error);
-			}
+			purchaseErrorListeners.notify(error);
 		});
 	};
 
@@ -486,15 +499,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		},
 
 		observeConnection(listener): Unsubscribe {
-			connectionListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				connectionListeners.delete(listener);
-			};
+			return connectionListeners.add(listener);
 		},
 
 		async queryProducts(
@@ -551,13 +556,13 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 					}
 					settled = true;
 					clearTimeout(grace);
-					purchaseListeners.delete(onPurchase);
-					purchaseErrorListeners.delete(onError);
+					stopPurchase();
+					stopError();
 					resolve(outcome);
 				}
 
-				purchaseListeners.add(onPurchase);
-				purchaseErrorListeners.add(onError);
+				const stopPurchase = purchaseListeners.add(onPurchase);
+				const stopError = purchaseErrorListeners.add(onError);
 				try {
 					module()
 						.requestPurchase(toRequestProps(request))
@@ -581,15 +586,7 @@ export function createIapAdapter(options: IapAdapterOptions = {}): ProviderPort
 		},
 
 		observePurchases(listener): Unsubscribe {
-			purchaseListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				purchaseListeners.delete(listener);
-			};
+			return purchaseListeners.add(listener);
 		},
 
 		async acknowledge(token: ProviderToken): Promise<void> {

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,6 +9,12 @@
  * schedule without burning real time.
  */
 
+import {
+	computeBackoff,
+	runWithRetry as runCoreRetry,
+	type RetryHandle,
+} from '@chipmobilesdk/rn-core';
+
 import type { BackoffConfig } from '../config/types';
 
 /** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
@@ -25,9 +31,17 @@ 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);
+}
+
+function toSpec(config: Required<BackoffConfig>) {
+	return {
+		initialDelayMs: config.initialDelayMs,
+		maxDelayMs: config.maxDelayMs,
+		factor: config.factor,
+		jitter: config.jitter ? ('full' as const) : ('none' as const),
+		maxAttempts: config.maxAttempts,
+	};
 }
 
 /** The full schedule, for asserting a retry policy without waiting for it. */
@@ -39,14 +53,7 @@ export function backoffSchedule(config: Required<BackoffConfig>): number[] {
 	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 type { RetryHandle } from '@chipmobilesdk/rn-core';
 
 export interface RetryRunnerOptions {
 	config: Required<BackoffConfig>;
@@ -65,69 +72,24 @@ export interface RetryRunnerOptions {
 }
 
 /**
- * Runs `attempt` under the bounded schedule.
+ * 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.
+ * 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 {
-		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;
-			}
+	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),
 		},
-		attempts: () => attemptCount,
-		exhausted: () => attemptCount >= config.maxAttempts,
-	};
+	});
 }