@chipmobilesdk/rn-ai 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @chipmobilesdk/rn-ai
 
+## 0.3.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.
+
+- 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.
+
+### 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.2.1
 
 ### Patch Changes

package/README.md

@@ -77,8 +77,12 @@ send({
   request. A fresh cache entry is used immediately; a stale entry is used
   immediately and revalidated in the background with its ETag. With no cache,
   the first operation waits for the config request, for at most `configMs`.
-  Designated `404`/`410`
-  responses invalidate config and retry against the refreshed endpoint.
+  Concurrent calls share one config request, so a cold start that asks for a
+  chat and the quota together fetches the config once. Designated `404`/`410`
+  responses invalidate config and retry against the refreshed endpoint, after
+  waiting `recovery.retryBackoffMs[n]` (the last step repeats, each capped at
+  30 s), at most `recovery.maxSilentRetries` times. A chat cancelled during the
+  wait is not retried.
 - **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
   on `401`, reacquires a token and retries once.
 - **Timeouts**: every network call is bounded. Override any of them with
@@ -86,14 +90,14 @@ send({
 
   | | Default | Fails with |
   |---|---|---|
-  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
-  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
+  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `retryable: true` |
+  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `retryable: true` |
   | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
-  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
+  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `retryable: true` |
 
   The gateway sends headers only after the model answers, so `connectMs` also
   covers time to first token. A dropped connection (HTTP status 0) is likewise
-  `upstream-error` with `recoverable: true`.
+  `upstream-error` with `retryable: true`.
 - **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
   and nothing after `cancel()`. An unexpected exception anywhere on the way
   (including in your own `onDelta`) is reported as `internal`, never dropped.
@@ -115,10 +119,14 @@ Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
   `ChatHandle`, `Usage`
 - Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
   `AiConfigCache`, `QuotaSnapshot`
-- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
-  `UseAiQuotaResult`
+- React: `useAiChat`, `useAiQuota`, `useAiBehaviorState`, `AiChatStatus`,
+  `UseAiChatResult`, `UseAiQuotaResult`. `useAiBehaviorState(client)` re-renders when
+  the config loads or the `aiEnabled` kill switch flips; `client.subscribe` and
+  `client.getBehaviorState()` give the same outside React.
 - Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
-  `aiMessage`, `AiMessageKey`
+  `aiMessage`, `AiMessageKey`, `aiMessageSet` (the same catalog as an rn-core message
+  set), `messageKeyForError(error)` (the copy to show for any error code). Register the
+  copy with rn-i18n in one line: `runtimeEntriesFromCatalog(aiMessageSet.user)`.
 
 ## App responsibilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-ai",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -21,9 +21,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": {
 		"@chipmobilesdk/rn-auth": ">=0.2.0",
 		"react": ">=19",

package/src/config/behaviorConfig.ts

@@ -1,3 +1,5 @@
+import { createListenerSet, createSingleFlight } from '@chipmobilesdk/rn-core';
+
 import { AiError } from '../diagnostics/errors';
 import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
 
@@ -106,7 +108,30 @@ export class BehaviorConfigManager {
 	private fetchFn: typeof fetch;
 	private now: () => number;
 	private current?: { config: AppBehaviorConfig; envelope: CacheEnvelope };
-	state: BehaviorState = 'unloaded';
+	/**
+	 * One cache read and one network fetch at a time (AI-08): a cold start makes a
+	 * chat and a quota call together, and each used to fetch the config itself.
+	 */
+	private readonly cacheRead = createSingleFlight<void>();
+	private readonly networkFetch = createSingleFlight<AppBehaviorConfig | undefined>();
+	private currentState: BehaviorState = 'unloaded';
+	private readonly stateListeners = createListenerSet<[]>();
+
+	/** Where the config came from, or why there is none. */
+	get state(): BehaviorState {
+		return this.currentState;
+	}
+
+	/** Called whenever `state` changes (AI-09). */
+	subscribe(listener: () => void): () => void {
+		return this.stateListeners.add(listener);
+	}
+
+	private setState(next: BehaviorState): void {
+		if (next === this.currentState) return;
+		this.currentState = next;
+		this.stateListeners.notify();
+	}
 
 	constructor(private deps: BehaviorConfigDeps) {
 		this.cacheKey = `rn-ai:config:${deps.appId}`;
@@ -119,20 +144,28 @@ export class BehaviorConfigManager {
 		return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
 	}
 
-	private async loadFromCache(): Promise<void> {
+	private loadFromCache(): Promise<void> {
+		return this.current ? Promise.resolve() : this.cacheRead.run(() => this.readCache());
+	}
+
+	private async readCache(): Promise<void> {
 		if (this.current) return;
 		const stored = await this.cache.get(this.cacheKey).catch(() => null);
 		if (!stored) return;
 		try {
 			const envelope = JSON.parse(stored) as CacheEnvelope;
 			this.current = { config: parseBehaviorConfig(envelope.configJson), envelope };
-			this.state = 'ready-cache';
+			this.setState('ready-cache');
 		} catch {
 			// corrupted cache entries are ignored, not fatal
 		}
 	}
 
-	private async fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+	private fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+		return this.networkFetch.run(() => this.fetchFromNetwork());
+	}
+
+	private async fetchFromNetwork(): Promise<AppBehaviorConfig | undefined> {
 		const headers: Record<string, string> = {};
 		if (this.current?.envelope.etag) {
 			headers['If-None-Match'] = this.current.envelope.etag;
@@ -149,7 +182,7 @@ export class BehaviorConfigManager {
 		if (response.status === 304 && this.current) {
 			this.current.envelope.fetchedAt = this.now();
 			await this.persist(this.current.envelope);
-			this.state = 'ready-network';
+			this.setState('ready-network');
 			return this.current.config;
 		}
 		if (!response.ok) {
@@ -163,7 +196,7 @@ export class BehaviorConfigManager {
 		};
 		this.current = { config, envelope };
 		await this.persist(envelope);
-		this.state = 'ready-network';
+		this.setState('ready-network');
 		return config;
 	}
 
@@ -189,12 +222,12 @@ export class BehaviorConfigManager {
 			if (fetched) return fetched;
 		} catch (e) {
 			if (this.current) return this.current.config; // stale beats broken
-			this.state = 'unavailable';
+			this.setState('unavailable');
 			throw e instanceof AiError ? e : new AiError('config-unavailable', String(e));
 		}
 		// fetchNetwork only returns undefined when a 304 raced an empty cache.
 		if (this.current) return (this.current as { config: AppBehaviorConfig }).config;
-		this.state = 'unavailable';
+		this.setState('unavailable');
 		throw new AiError('config-unavailable', 'no configuration available');
 	}
 }

package/src/core/aiClient.ts

@@ -1,13 +1,30 @@
+import {
+	createDiagnosticChannel,
+	createListenerSet,
+	realScheduler,
+	type Scheduler,
+} from '@chipmobilesdk/rn-core';
+
 import {
 	BehaviorConfigManager,
 	type AiConfigCache,
 	type AppBehaviorConfig,
 	type BehaviorState,
 } from '../config/behaviorConfig';
-import { AiError, errorFromHttp } from '../diagnostics/errors';
+import { AiError, errorFromHttp, type AiErrorCode } from '../diagnostics/errors';
 import { requestSse, type SseHandle } from '../transport/sseClient';
 import { DEFAULT_AI_TIMEOUTS, withTimeout, type AiTimeouts } from '../transport/timeouts';
 
+/** Every failure a caller receives also goes to the app's SDK sinks (CORE-08). */
+const channel = createDiagnosticChannel<AiErrorCode>('rn-ai');
+
+function report(operation: 'chat' | 'quota', error: AiError): void {
+	channel.emit(error.code, error.retryable ? 'warn' : 'error', {
+		operation,
+		retryable: error.retryable,
+	});
+}
+
 /** Minimal slice of the rn-auth `Auth` controller the client needs. */
 export interface TokenProvider {
 	requestAccessToken(resourceKey: string): Promise<{ status: string; token?: string }>;
@@ -67,12 +84,29 @@ export interface AiClientConfig {
 	transport?: typeof requestSse;
 	/** Overrides for the network time limits; see `AiTimeouts` for the defaults. */
 	timeouts?: Partial<AiTimeouts>;
+	/** Test seam: how the backoff before a silent retry is waited out. */
+	scheduler?: Scheduler;
+}
+
+/** Ceiling on one remote-configured backoff step, so a bad document cannot stall a chat. */
+const MAX_RETRY_BACKOFF_MS = 30_000;
+
+/** The wait before silent retry `index` (0-based); the last configured step repeats. */
+function backoffBefore(steps: readonly number[], index: number): number {
+	const step = steps[Math.min(index, steps.length - 1)] ?? 0;
+	return Math.min(Math.max(0, step), MAX_RETRY_BACKOFF_MS);
 }
 
 export interface AiClient {
 	chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle;
 	getQuota(): Promise<QuotaSnapshot>;
+	/** The current behavior state; the same object until it changes. */
 	getBehaviorState(): AiBehaviorState;
+	/**
+	 * Called whenever the behavior state changes (AI-09); returns the unsubscribe.
+	 * Optional so an app's own `AiClient` implementation keeps compiling.
+	 */
+	subscribe?(listener: () => void): () => void;
 	reloadConfig(): Promise<void>;
 }
 
@@ -89,6 +123,7 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 	const transport = clientConfig.transport ?? requestSse;
 	const fetchFn = clientConfig.fetchFn ?? fetch;
 	const timeouts: AiTimeouts = { ...DEFAULT_AI_TIMEOUTS, ...clientConfig.timeouts };
+	const scheduler = clientConfig.scheduler ?? realScheduler;
 	const configManager = new BehaviorConfigManager({
 		configUrl: clientConfig.configUrl,
 		appId: clientConfig.appId,
@@ -97,10 +132,28 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 		timeoutMs: timeouts.configMs,
 	});
 	let lastConfig: AppBehaviorConfig | undefined;
+	const behaviorListeners = createListenerSet<[]>();
+	let snapshot: AiBehaviorState | undefined;
+
+	/** Rebuilt only when a field changes, so useSyncExternalStore sees a stable object. */
+	function behaviorState(): AiBehaviorState {
+		const config = configManager.state;
+		const aiEnabled = lastConfig?.features.aiEnabled ?? true;
+		if (!snapshot || snapshot.config !== config || snapshot.aiEnabled !== aiEnabled) {
+			snapshot = { config, aiEnabled };
+		}
+		return snapshot;
+	}
+
+	function setLastConfig(next: AppBehaviorConfig): void {
+		const wasEnabled = lastConfig?.features.aiEnabled ?? true;
+		lastConfig = next;
+		if (next.features.aiEnabled !== wasEnabled) behaviorListeners.notify();
+	}
 
 	async function acquire(): Promise<{ config: AppBehaviorConfig; token: string }> {
 		const config = await configManager.getConfig();
-		lastConfig = config;
+		setLastConfig(config);
 		if (!config.features.aiEnabled) {
 			throw new AiError('config-unavailable', 'AI is disabled for this app', {
 				recoverable: false,
@@ -138,6 +191,7 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 				if (cancelled || settled) return;
 				settled = true;
 				inner?.cancel();
+				report('chat', error);
 				handlers.onError(error);
 			},
 		};
@@ -220,8 +274,16 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 							config.recovery.reloadOnHttpStatus.includes(status) &&
 							state.configReloads < config.recovery.maxSilentRetries
 						) {
+							// Waits `recovery.retryBackoffMs` first (AI-05): a gateway mid-rollout
+							// that answered 410 a moment ago may well answer it again at once.
+							const retryAfter = backoffBefore(config.recovery.retryBackoffMs, state.configReloads);
 							configManager.getConfig({ forceReload: true }).then(
-								() => attempt({ ...state, configReloads: state.configReloads + 1 }).catch(fail),
+								() => {
+									scheduler.setTimeout(() => {
+										if (cancelled) return;
+										attempt({ ...state, configReloads: state.configReloads + 1 }).catch(fail);
+									}, retryAfter);
+								},
 								e => fail(e instanceof AiError ? e : new AiError('config-unavailable', String(e))),
 							);
 							return;
@@ -247,6 +309,15 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 	}
 
 	async function getQuota(): Promise<QuotaSnapshot> {
+		try {
+			return await fetchQuota();
+		} catch (error) {
+			if (error instanceof AiError) report('quota', error);
+			throw error;
+		}
+	}
+
+	async function fetchQuota(): Promise<QuotaSnapshot> {
 		const { config, token } = await acquire();
 		return withTimeout(
 			timeouts.quotaMs,
@@ -267,12 +338,17 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 	return {
 		chat,
 		getQuota,
-		getBehaviorState: () => ({
-			config: configManager.state,
-			aiEnabled: lastConfig?.features.aiEnabled ?? true,
-		}),
+		getBehaviorState: () => behaviorState(),
+		subscribe: listener => {
+			const fromManager = configManager.subscribe(listener);
+			const fromClient = behaviorListeners.add(listener);
+			return () => {
+				fromManager();
+				fromClient();
+			};
+		},
 		reloadConfig: async () => {
-			lastConfig = await configManager.getConfig({ forceReload: true });
+			setLastConfig(await configManager.getConfig({ forceReload: true }));
 		},
 	};
 }

package/src/diagnostics/errors.ts

@@ -1,4 +1,6 @@
 /** Typed client errors (contracts/rn-ai-public-api.md). */
+import { SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
 export type AiErrorCode =
 	| 'auth-invalid'
 	| 'not-entitled'
@@ -12,21 +14,33 @@ export type AiErrorCode =
 	| 'upstream-error'
 	| 'internal';
 
-export class AiError extends Error {
-	readonly code: AiErrorCode;
-	readonly retryAfterSeconds?: number;
-	readonly recoverable: boolean;
+export interface AiErrorOptions {
+	retryAfterSeconds?: number | undefined;
+	/** Whether retrying can succeed. Defaults to true for `rate-limited` and `upstream-busy`. */
+	retryable?: boolean | undefined;
+	/** @deprecated Use `retryable`; accepted as its alias. */
+	recoverable?: boolean | undefined;
+}
+
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-ai'`. */
+export class AiError extends SdkError<AiErrorCode> {
+	readonly retryAfterSeconds?: number | undefined;
 
-	constructor(
-		code: AiErrorCode,
-		message: string,
-		options: { retryAfterSeconds?: number; recoverable?: boolean } = {},
-	) {
-		super(message);
+	constructor(code: AiErrorCode, message: string, options: AiErrorOptions = {}) {
+		super('rn-ai', code, {
+			message,
+			retryable:
+				options.retryable ??
+				options.recoverable ??
+				(code === 'rate-limited' || code === 'upstream-busy'),
+		});
 		this.name = 'AiError';
-		this.code = code;
 		this.retryAfterSeconds = options.retryAfterSeconds;
-		this.recoverable = options.recoverable ?? (code === 'rate-limited' || code === 'upstream-busy');
+	}
+
+	/** @deprecated Use `retryable`, the name every SDK package shares. */
+	get recoverable(): boolean {
+		return this.retryable;
 	}
 }
 
@@ -58,7 +72,8 @@ export function errorFromHttp(status: number, bodyText: string): AiError {
 		if (parsed.error?.code && HTTP_CODE_MAP[parsed.error.code]) {
 			code = HTTP_CODE_MAP[parsed.error.code];
 		}
-		if (parsed.error?.message) message = parsed.error.message;
+		// The gateway's text can quote upstream detail; keep it readable but shaped.
+		if (parsed.error?.message) message = redactPatterns(parsed.error.message);
 		retryAfterSeconds = parsed.error?.retryAfterSeconds;
 	} catch {
 		if (status === 0) {

package/src/diagnostics/messageKeys.ts

@@ -1,27 +1,63 @@
 /**
- * User-facing copy keys (UX-002/003), mirroring the rn-auth diagnostics
- * pattern: apps may localize via rn-i18n; these are the defaults.
+ * User-facing copy keys (UX-002/003) and their English defaults, as an rn-core
+ * message catalog: apps translate them through rn-i18n
+ * (`runtimeEntriesFromCatalog(aiMessages)`) or override them directly.
  */
-export const aiMessages = {
-	'ai.state.loading': 'Thinking…',
-	'ai.state.streaming': 'Answering…',
-	'ai.input.placeholder': 'Ask about your scan…',
-	'ai.action.send': 'Send',
-	'ai.action.cancel': 'Cancel',
-	'ai.action.retry': 'Try again',
-	'ai.action.retryAt': 'You can try again at {time}',
-	'ai.quota.remaining': '{count} requests left today',
-	'ai.error.rateLimited': 'You have reached your usage limit.',
-	'ai.error.premiumRequired': 'AI features require a premium subscription for this app.',
-	'ai.error.blocked': 'AI access is suspended for this account.',
-	'ai.error.payloadTooLarge': 'That attachment is too large to send.',
-	'ai.error.modality': 'This kind of content is not supported here.',
-	'ai.error.busy': 'The AI service is busy. Please try again shortly.',
-	'ai.error.unavailable': 'AI features are currently unavailable.',
-} as const;
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
+import type { AiErrorCode } from './errors';
+import type { AiError } from './errors';
+
+export const aiMessageSet = defineMessages({
+	user: {
+		'ai.state.loading': 'Thinking…',
+		'ai.state.streaming': 'Answering…',
+		// Neutral copy: the app names its own feature (AI-16).
+		'ai.input.placeholder': 'Type a message…',
+		'ai.action.send': 'Send',
+		'ai.action.cancel': 'Cancel',
+		'ai.action.retry': 'Try again',
+		'ai.action.retryAt': 'You can try again at {time}',
+		'ai.quota.remaining': '{count} requests left today',
+		'ai.error.rateLimited': 'You have reached your usage limit.',
+		'ai.error.premiumRequired': 'AI features require a premium subscription for this app.',
+		'ai.error.blocked': 'AI access is suspended for this account.',
+		'ai.error.payloadTooLarge': 'That attachment is too large to send.',
+		'ai.error.modality': 'This kind of content is not supported here.',
+		'ai.error.busy': 'The AI service is busy. Please try again shortly.',
+		'ai.error.unavailable': 'AI features are currently unavailable.',
+		'ai.error.signIn': 'Please sign in again to continue.',
+		'ai.error.generic': 'Something went wrong. Please try again.',
+	},
+});
+
+export const aiMessages = aiMessageSet.defaults;
 
 export type AiMessageKey = keyof typeof aiMessages;
 
 export function aiMessage(key: AiMessageKey): string {
 	return aiMessages[key];
 }
+
+/**
+ * The copy for each error code. A `Record` over the whole code union, so adding a
+ * code without choosing its copy fails to compile (AI-16).
+ */
+const ERROR_MESSAGES: Record<AiErrorCode, AiMessageKey> = {
+	'auth-invalid': 'ai.error.signIn',
+	'not-entitled': 'ai.error.premiumRequired',
+	'user-blocked': 'ai.error.blocked',
+	'app-unknown': 'ai.error.unavailable',
+	'rate-limited': 'ai.error.rateLimited',
+	'upstream-busy': 'ai.error.busy',
+	'payload-too-large': 'ai.error.payloadTooLarge',
+	'modality-not-allowed': 'ai.error.modality',
+	'config-unavailable': 'ai.error.unavailable',
+	'upstream-error': 'ai.error.generic',
+	internal: 'ai.error.generic',
+};
+
+/** The message key to show a user for an error. */
+export function messageKeyForError(error: AiError): AiMessageKey {
+	return ERROR_MESSAGES[error.code];
+}

package/src/index.ts

@@ -22,10 +22,10 @@ export type {
 export type { AppBehaviorConfig, AiConfigCache, BehaviorState } from './config/behaviorConfig';
 
 export type { AiTimeouts } from './transport/timeouts';
-export { useAiChat, useAiQuota } from './react/hooks';
+export { useAiBehaviorState, useAiChat, useAiQuota } from './react/hooks';
 export type { AiChatStatus, UseAiChatResult, UseAiQuotaResult } from './react/hooks';
 
 export { AiError, isAiError } from './diagnostics/errors';
 export type { AiErrorCode } from './diagnostics/errors';
-export { aiMessages, aiMessage } from './diagnostics/messageKeys';
+export { aiMessage, aiMessageSet, aiMessages, messageKeyForError } from './diagnostics/messageKeys';
 export type { AiMessageKey } from './diagnostics/messageKeys';

package/src/react/hooks.ts

@@ -1,5 +1,12 @@
+import { useExternalStore } from '@chipmobilesdk/rn-core/react';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { AiClient, ChatHandle, ChatRequest, QuotaSnapshot } from '../core/aiClient';
+import type {
+	AiBehaviorState,
+	AiClient,
+	ChatHandle,
+	ChatRequest,
+	QuotaSnapshot,
+} from '../core/aiClient';
 import type { AiError } from '../diagnostics/errors';
 
 export type AiChatStatus = 'idle' | 'loading' | 'streaming' | 'done' | 'error' | 'rate-limited';
@@ -121,3 +128,14 @@ export function useAiQuota(client: AiClient): UseAiQuotaResult {
 
 	return { quota, status, refresh };
 }
+
+/**
+ * The client's behavior state (config source and whether AI is enabled), live:
+ * re-renders when the kill switch flips or the config state moves (AI-09).
+ */
+export function useAiBehaviorState(client: AiClient): AiBehaviorState {
+	return useExternalStore(client.subscribe ?? noSubscription, client.getBehaviorState);
+}
+
+/** For a client without `subscribe`: its state is read once per render. */
+const noSubscription = () => () => undefined;