@chipmobilesdk/rn-ai 0.2.0 → 0.3.0

package/src/diagnostics/errors.ts

@@ -1,75 +1,89 @@
-/** Typed client errors (contracts/rn-ai-public-api.md). */
-export type AiErrorCode =
-	| 'auth-invalid'
-	| 'not-entitled'
-	| 'user-blocked'
-	| 'app-unknown'
-	| 'rate-limited'
-	| 'upstream-busy'
-	| 'payload-too-large'
-	| 'modality-not-allowed'
-	| 'config-unavailable'
-	| 'upstream-error'
-	| 'internal';
-
-export class AiError extends Error {
-	readonly code: AiErrorCode;
-	readonly retryAfterSeconds?: number;
-	readonly recoverable: boolean;
-
-	constructor(
-		code: AiErrorCode,
-		message: string,
-		options: { retryAfterSeconds?: number; recoverable?: boolean } = {},
-	) {
-		super(message);
-		this.name = 'AiError';
-		this.code = code;
-		this.retryAfterSeconds = options.retryAfterSeconds;
-		this.recoverable =
-			options.recoverable ?? (code === 'rate-limited' || code === 'upstream-busy');
-	}
-}
-
-export function isAiError(value: unknown): value is AiError {
-	return value instanceof AiError;
-}
-
-const HTTP_CODE_MAP: Record<string, AiErrorCode> = {
-	AUTH_INVALID: 'auth-invalid',
-	NOT_ENTITLED: 'not-entitled',
-	USER_BLOCKED: 'user-blocked',
-	APP_UNKNOWN: 'app-unknown',
-	PAYLOAD_TOO_LARGE: 'payload-too-large',
-	MODALITY_NOT_ALLOWED: 'modality-not-allowed',
-	RATE_LIMITED: 'rate-limited',
-	UPSTREAM_BUSY: 'upstream-busy',
-	UPSTREAM_ERROR: 'upstream-error',
-};
-
-/** Map a gateway error response (status + JSON body) to a typed AiError. */
-export function errorFromHttp(status: number, bodyText: string): AiError {
-	let code: AiErrorCode = status >= 500 ? 'upstream-error' : 'internal';
-	let message = `gateway responded ${status}`;
-	let retryAfterSeconds: number | undefined;
-	try {
-		const parsed = JSON.parse(bodyText) as {
-			error?: { code?: string; message?: string; retryAfterSeconds?: number };
-		};
-		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;
-		retryAfterSeconds = parsed.error?.retryAfterSeconds;
-	} catch {
-		if (status === 0) {
-			code = 'upstream-error';
-			message = 'network failure';
-		}
-	}
-	// Status 0 is a dropped connection, which a retry may well fix.
-	return new AiError(code, message, {
-		retryAfterSeconds,
-		recoverable: status === 0 ? true : undefined,
-	});
-}
+/** Typed client errors (contracts/rn-ai-public-api.md). */
+import { SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
+export type AiErrorCode =
+	| 'auth-invalid'
+	| 'not-entitled'
+	| 'user-blocked'
+	| 'app-unknown'
+	| 'rate-limited'
+	| 'upstream-busy'
+	| 'payload-too-large'
+	| 'modality-not-allowed'
+	| 'config-unavailable'
+	| 'upstream-error'
+	| 'internal';
+
+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: AiErrorOptions = {}) {
+		super('rn-ai', code, {
+			message,
+			retryable:
+				options.retryable ??
+				options.recoverable ??
+				(code === 'rate-limited' || code === 'upstream-busy'),
+		});
+		this.name = 'AiError';
+		this.retryAfterSeconds = options.retryAfterSeconds;
+	}
+
+	/** @deprecated Use `retryable`, the name every SDK package shares. */
+	get recoverable(): boolean {
+		return this.retryable;
+	}
+}
+
+export function isAiError(value: unknown): value is AiError {
+	return value instanceof AiError;
+}
+
+const HTTP_CODE_MAP: Record<string, AiErrorCode> = {
+	AUTH_INVALID: 'auth-invalid',
+	NOT_ENTITLED: 'not-entitled',
+	USER_BLOCKED: 'user-blocked',
+	APP_UNKNOWN: 'app-unknown',
+	PAYLOAD_TOO_LARGE: 'payload-too-large',
+	MODALITY_NOT_ALLOWED: 'modality-not-allowed',
+	RATE_LIMITED: 'rate-limited',
+	UPSTREAM_BUSY: 'upstream-busy',
+	UPSTREAM_ERROR: 'upstream-error',
+};
+
+/** Map a gateway error response (status + JSON body) to a typed AiError. */
+export function errorFromHttp(status: number, bodyText: string): AiError {
+	let code: AiErrorCode = status >= 500 ? 'upstream-error' : 'internal';
+	let message = `gateway responded ${status}`;
+	let retryAfterSeconds: number | undefined;
+	try {
+		const parsed = JSON.parse(bodyText) as {
+			error?: { code?: string; message?: string; retryAfterSeconds?: number };
+		};
+		if (parsed.error?.code && HTTP_CODE_MAP[parsed.error.code]) {
+			code = HTTP_CODE_MAP[parsed.error.code];
+		}
+		// 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) {
+			code = 'upstream-error';
+			message = 'network failure';
+		}
+	}
+	// Status 0 is a dropped connection, which a retry may well fix.
+	return new AiError(code, message, {
+		retryAfterSeconds,
+		recoverable: status === 0 ? true : undefined,
+	});
+}

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.
- */
-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;
-
-export type AiMessageKey = keyof typeof aiMessages;
-
-export function aiMessage(key: AiMessageKey): string {
-	return aiMessages[key];
-}
+/**
+ * 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.
+ */
+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

@@ -1,35 +1,31 @@
-/**
- * @chipmobilesdk/rn-ai — AI gateway client for ChipMobileSdk-family React
- * Native apps (feature 005). Single public entrypoint (LIB-003); modules
- * under `config/`, `transport/`, `core/`, `react/`, and `diagnostics/` are
- * private. Contract: specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md
- */
-export { createAiClient } from './core/aiClient';
-export type {
-	AiClient,
-	AiClientConfig,
-	AiBehaviorState,
-	TokenProvider,
-	ChatRequest,
-	ChatMessage,
-	ContentPart,
-	ChatStreamHandlers,
-	ChatHandle,
-	Usage,
-	QuotaSnapshot,
-} from './core/aiClient';
-
-export type {
-	AppBehaviorConfig,
-	AiConfigCache,
-	BehaviorState,
-} from './config/behaviorConfig';
-
-export type { AiTimeouts } from './transport/timeouts';
-export { 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 type { AiMessageKey } from './diagnostics/messageKeys';
+/**
+ * @chipmobilesdk/rn-ai — AI gateway client for ChipMobileSdk-family React
+ * Native apps (feature 005). Single public entrypoint (LIB-003); modules
+ * under `config/`, `transport/`, `core/`, `react/`, and `diagnostics/` are
+ * private. Contract: specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md
+ */
+export { createAiClient } from './core/aiClient';
+export type {
+	AiClient,
+	AiClientConfig,
+	AiBehaviorState,
+	TokenProvider,
+	ChatRequest,
+	ChatMessage,
+	ContentPart,
+	ChatStreamHandlers,
+	ChatHandle,
+	Usage,
+	QuotaSnapshot,
+} from './core/aiClient';
+
+export type { AppBehaviorConfig, AiConfigCache, BehaviorState } from './config/behaviorConfig';
+
+export type { AiTimeouts } from './transport/timeouts';
+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 { aiMessage, aiMessageSet, aiMessages, messageKeyForError } from './diagnostics/messageKeys';
+export type { AiMessageKey } from './diagnostics/messageKeys';

package/src/react/hooks.ts

@@ -1,134 +1,141 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import type {
-	AiClient,
-	ChatHandle,
-	ChatRequest,
-	QuotaSnapshot,
-} from '../core/aiClient';
-import type { AiError } from '../diagnostics/errors';
-
-export type AiChatStatus =
-	| 'idle'
-	| 'loading'
-	| 'streaming'
-	| 'done'
-	| 'error'
-	| 'rate-limited';
-
-export interface UseAiChatResult {
-	send(request: ChatRequest): void;
-	cancel(): void;
-	status: AiChatStatus;
-	/** Accumulated streamed text (appends incrementally — PERF-002). */
-	text: string;
-	error?: AiError;
-	retryAt?: Date;
-	quota?: QuotaSnapshot;
-}
-
-export function useAiChat(client: AiClient): UseAiChatResult {
-	const [status, setStatus] = useState<AiChatStatus>('idle');
-	const [text, setText] = useState('');
-	const [error, setError] = useState<AiError | undefined>();
-	const [retryAt, setRetryAt] = useState<Date | undefined>();
-	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
-	const handleRef = useRef<ChatHandle | null>(null);
-	// Bumped by every send, cancel and unmount. A callback from an older request
-	// is dropped, so it can never overwrite the state of the one on screen —
-	// defence in depth behind the client's own cancel guard.
-	const requestRef = useRef(0);
-
-	const send = useCallback(
-		(request: ChatRequest) => {
-			handleRef.current?.cancel();
-			const id = ++requestRef.current;
-			const current = () => requestRef.current === id;
-			setText('');
-			setError(undefined);
-			setRetryAt(undefined);
-			setStatus('loading');
-			handleRef.current = client.chat(request, {
-				onDelta: delta => {
-					if (!current()) return;
-					setStatus('streaming');
-					setText(previous => previous + delta);
-				},
-				onDone: result => {
-					if (!current()) return;
-					if (result.quota) setQuota(result.quota);
-					setStatus('done');
-				},
-				onError: aiError => {
-					if (!current()) return;
-					setError(aiError);
-					if (aiError.code === 'rate-limited') {
-						setStatus('rate-limited');
-						if (aiError.retryAfterSeconds !== undefined) {
-							setRetryAt(new Date(Date.now() + aiError.retryAfterSeconds * 1000));
-						}
-					} else {
-						setStatus('error');
-					}
-				},
-			});
-		},
-		[client],
-	);
-
-	const cancel = useCallback(() => {
-		requestRef.current += 1;
-		handleRef.current?.cancel();
-		setStatus('idle');
-	}, []);
-
-	useEffect(
-		() => () => {
-			requestRef.current += 1;
-			handleRef.current?.cancel();
-		},
-		[],
-	);
-
-	return { send, cancel, status, text, error, retryAt, quota };
-}
-
-export interface UseAiQuotaResult {
-	quota?: QuotaSnapshot;
-	status: 'loading' | 'ready' | 'error';
-	refresh(): void;
-}
-
-export function useAiQuota(client: AiClient): UseAiQuotaResult {
-	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
-	const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
-	const alive = useRef(true);
-	// Only the latest refresh may settle the state; an older, slower one that
-	// lands afterwards is stale.
-	const latest = useRef(0);
-
-	const refresh = useCallback(() => {
-		const id = ++latest.current;
-		const current = () => alive.current && latest.current === id;
-		setStatus('loading');
-		client
-			.getQuota()
-			.then(snapshot => {
-				if (!current()) return;
-				setQuota(snapshot);
-				setStatus('ready');
-			})
-			.catch(() => {
-				if (current()) setStatus('error');
-			});
-	}, [client]);
-
-	useEffect(() => {
-		alive.current = true;
-		refresh();
-		return () => {
-			alive.current = false;
-		};
-	}, [refresh]);
-
-	return { quota, status, refresh };
-}
+import { useExternalStore } from '@chipmobilesdk/rn-core/react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+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';
+
+export interface UseAiChatResult {
+	send(request: ChatRequest): void;
+	cancel(): void;
+	status: AiChatStatus;
+	/** Accumulated streamed text (appends incrementally — PERF-002). */
+	text: string;
+	error?: AiError;
+	retryAt?: Date;
+	quota?: QuotaSnapshot;
+}
+
+export function useAiChat(client: AiClient): UseAiChatResult {
+	const [status, setStatus] = useState<AiChatStatus>('idle');
+	const [text, setText] = useState('');
+	const [error, setError] = useState<AiError | undefined>();
+	const [retryAt, setRetryAt] = useState<Date | undefined>();
+	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
+	const handleRef = useRef<ChatHandle | null>(null);
+	// Bumped by every send, cancel and unmount. A callback from an older request
+	// is dropped, so it can never overwrite the state of the one on screen —
+	// defence in depth behind the client's own cancel guard.
+	const requestRef = useRef(0);
+
+	const send = useCallback(
+		(request: ChatRequest) => {
+			handleRef.current?.cancel();
+			const id = ++requestRef.current;
+			const current = () => requestRef.current === id;
+			setText('');
+			setError(undefined);
+			setRetryAt(undefined);
+			setStatus('loading');
+			handleRef.current = client.chat(request, {
+				onDelta: delta => {
+					if (!current()) return;
+					setStatus('streaming');
+					setText(previous => previous + delta);
+				},
+				onDone: result => {
+					if (!current()) return;
+					if (result.quota) setQuota(result.quota);
+					setStatus('done');
+				},
+				onError: aiError => {
+					if (!current()) return;
+					setError(aiError);
+					if (aiError.code === 'rate-limited') {
+						setStatus('rate-limited');
+						if (aiError.retryAfterSeconds !== undefined) {
+							setRetryAt(new Date(Date.now() + aiError.retryAfterSeconds * 1000));
+						}
+					} else {
+						setStatus('error');
+					}
+				},
+			});
+		},
+		[client],
+	);
+
+	const cancel = useCallback(() => {
+		requestRef.current += 1;
+		handleRef.current?.cancel();
+		setStatus('idle');
+	}, []);
+
+	useEffect(
+		() => () => {
+			requestRef.current += 1;
+			handleRef.current?.cancel();
+		},
+		[],
+	);
+
+	return { send, cancel, status, text, error, retryAt, quota };
+}
+
+export interface UseAiQuotaResult {
+	quota?: QuotaSnapshot;
+	status: 'loading' | 'ready' | 'error';
+	refresh(): void;
+}
+
+export function useAiQuota(client: AiClient): UseAiQuotaResult {
+	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
+	const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+	const alive = useRef(true);
+	// Only the latest refresh may settle the state; an older, slower one that
+	// lands afterwards is stale.
+	const latest = useRef(0);
+
+	const refresh = useCallback(() => {
+		const id = ++latest.current;
+		const current = () => alive.current && latest.current === id;
+		setStatus('loading');
+		client
+			.getQuota()
+			.then(snapshot => {
+				if (!current()) return;
+				setQuota(snapshot);
+				setStatus('ready');
+			})
+			.catch(() => {
+				if (current()) setStatus('error');
+			});
+	}, [client]);
+
+	useEffect(() => {
+		alive.current = true;
+		refresh();
+		return () => {
+			alive.current = false;
+		};
+	}, [refresh]);
+
+	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;