@chipmobilesdk/rn-ai 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog — @chipmobilesdk/rn-ai
+
+## 0.1.0 — 2026-07-05
+
+Initial release (feature `005-azure-ai-gateway`).
+
+- `createAiClient` — config-driven gateway client: cache-first app behavior
+  config (ETag/TTL), token acquisition via `@chipmobilesdk/rn-auth`
+  (`resourceKey`), SSE streaming over zero-dependency XHR transport.
+- Multimodal chat requests: `text`, `image` (base64), `audio` (wav/mp3).
+- Silent endpoint re-route on designated `404`/`410` signals (max 1 retry);
+  one automatic fresh-token retry on `401`; no automatic retry on `429`.
+- `useAiChat` (idle/loading/streaming/done/error/rate-limited + accumulated
+  text + `retryAt`) and `useAiQuota` hooks.
+- Typed `AiError` codes and `ai.*` message keys with English defaults.
+- Per-app kill switch honored (`features.aiEnabled`).
+
+Adoption: additive — no changes required in existing apps. Requires an
+`ai-gateway` resource entry in the rn-auth config and a registered app on the
+gateway platform.

package/README.md

@@ -0,0 +1,134 @@
+# @chipmobilesdk/rn-ai
+
+AI gateway client for ChipMobileSdk-family React Native apps. Streams
+multimodal (text + image + audio in, text out) AI responses through the
+platform gateway with per-user rate limiting — apps never talk to Azure
+OpenAI directly and hold no AI credentials.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.1.0`
+- **Entrypoint**: `@chipmobilesdk/rn-ai`
+- **Native code**: none
+
+- Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
+- Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
+- Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
+
+## Install
+
+```bash
+npm install @chipmobilesdk/rn-ai @chipmobilesdk/rn-auth
+```
+
+Peers: `react >=19`, `react-native >=0.85`, `@chipmobilesdk/rn-auth >=0.2.0`.
+**Zero runtime dependencies**; streaming uses React Native's standard
+`XMLHttpRequest` (no native code, Hermes-compatible, iOS + Android).
+
+## Setup
+
+1. Add the gateway resource to your rn-auth config:
+
+```ts
+resources: [
+  { key: 'ai-gateway', scopes: ['api://aiapp-gateway/AI.Access'] },
+]
+```
+
+2. Create the client (one per app):
+
+```ts
+import { createAiClient } from '@chipmobilesdk/rn-ai';
+import { auth } from './auth/setup';
+
+export const aiClient = createAiClient({
+  appId: 'scan-food',
+  configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
+  resourceKey: 'ai-gateway',
+  auth,
+  // storage: inject a persistent AiConfigCache for offline launches
+});
+```
+
+3. Use the hooks:
+
+```tsx
+import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
+import { aiClient } from './ai/setup';
+
+const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
+const { quota } = useAiQuota(aiClient);
+
+send({
+  messages: [{
+    role: 'user',
+    content: [
+      { type: 'text', text: 'What dish is this? Estimate calories.' },
+      { type: 'image', mimeType: 'image/jpeg', dataBase64: photoBase64 },
+    ],
+  }],
+});
+```
+
+## Runtime behavior
+
+- **Config-driven endpoint**: resolved lazily on the first quota or chat
+  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. Designated `404`/`410`
+  responses invalidate config and retry against the refreshed endpoint.
+- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
+  on `401`, reacquires a token and retries once.
+- **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
+  the SDK never hammers and never enforces limits locally (display only).
+- **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
+  `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
+  `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
+  `upstream-error`, `internal`.
+- **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
+
+## Public API
+
+Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
+`transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
+
+- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
+- Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
+  `ChatHandle`, `Usage`
+- Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
+  `AiConfigCache`, `QuotaSnapshot`
+- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
+  `UseAiQuotaResult`
+- Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
+  `aiMessage`, `AiMessageKey`
+
+## App responsibilities
+
+- **AI disclosure (store policy)**: user text/images/audio are processed by
+  the platform's AI service. Update your privacy policy, Apple App Privacy,
+  and Google Play Data Safety before shipping, and disclose AI processing
+  in-app (POL-005/006 in the feature spec).
+- Camera/microphone permissions for capture UIs are yours; the SDK only
+  accepts already-captured data and adds no permissions.
+- Respect `payload-too-large` (default cap 10 MB/request) by resizing images
+  and bounding audio length.
+
+## Compatibility
+
+React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
+tooling.
+
+The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
+The current demo sidebar does not expose that screen yet, so it must be wired
+into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
+
+## Validation
+
+Run from the repository root:
+
+```bash
+npm run typecheck:ai
+npm run pack:ai
+npm run validate:ai
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@chipmobilesdk/rn-ai",
+	"version": "0.1.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/transport",
+		"src/core",
+		"src/react",
+		"src/diagnostics",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@chipmobilesdk/rn-auth": ">=0.2.0",
+		"react": ">=19",
+		"react-native": ">=0.85"
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/src/config/behaviorConfig.ts

@@ -0,0 +1,183 @@
+import { AiError } from '../diagnostics/errors';
+
+/** App behavior configuration (contracts/app-behavior-config.md). */
+export interface AppBehaviorConfig {
+	schemaVersion: number;
+	appId: string;
+	configVersion: number;
+	refreshTtlSeconds: number;
+	api: { baseUrl: string; scopes: string[]; supportsStreaming: boolean };
+	limitsDisplay?: { requestsPerDay?: number; tokensPerDay?: number };
+	recovery: {
+		reloadOnHttpStatus: number[];
+		maxSilentRetries: number;
+		retryBackoffMs: number[];
+	};
+	features: { aiEnabled: boolean };
+}
+
+/** Persistence port; default is in-memory (inject a durable store for offline launch). */
+export interface AiConfigCache {
+	get(key: string): Promise<string | null>;
+	set(key: string, value: string): Promise<void>;
+}
+
+export class MemoryConfigCache implements AiConfigCache {
+	private map = new Map<string, string>();
+	async get(key: string): Promise<string | null> {
+		return this.map.get(key) ?? null;
+	}
+	async set(key: string, value: string): Promise<void> {
+		this.map.set(key, value);
+	}
+}
+
+export type BehaviorState = 'unloaded' | 'ready-network' | 'ready-cache' | 'unavailable';
+
+/** Parse + validate; unknown fields ignored (forward compatibility). */
+export function parseBehaviorConfig(json: string): AppBehaviorConfig {
+	let raw: Record<string, unknown>;
+	try {
+		raw = JSON.parse(json) as Record<string, unknown>;
+	} catch {
+		throw new AiError('config-unavailable', 'behavior config is not valid JSON');
+	}
+	const api = raw.api as Partial<AppBehaviorConfig['api']> | undefined;
+	if (
+		typeof raw.appId !== 'string' ||
+		typeof api?.baseUrl !== 'string' ||
+		!Array.isArray(api.scopes)
+	) {
+		throw new AiError('config-unavailable', 'behavior config is missing required fields');
+	}
+	const recovery = (raw.recovery ?? {}) as Partial<AppBehaviorConfig['recovery']>;
+	const features = (raw.features ?? {}) as Partial<AppBehaviorConfig['features']>;
+	return {
+		schemaVersion: Number(raw.schemaVersion ?? 1),
+		appId: raw.appId,
+		configVersion: Number(raw.configVersion ?? 0),
+		refreshTtlSeconds: Number(raw.refreshTtlSeconds ?? 21600),
+		api: {
+			baseUrl: api.baseUrl.replace(/\/$/, ''),
+			scopes: api.scopes.filter((s): s is string => typeof s === 'string'),
+			supportsStreaming: api.supportsStreaming !== false,
+		},
+		limitsDisplay: raw.limitsDisplay as AppBehaviorConfig['limitsDisplay'],
+		recovery: {
+			reloadOnHttpStatus: recovery.reloadOnHttpStatus ?? [404, 410],
+			maxSilentRetries: recovery.maxSilentRetries ?? 1,
+			retryBackoffMs: recovery.retryBackoffMs ?? [500, 2000],
+		},
+		features: { aiEnabled: features.aiEnabled !== false },
+	};
+}
+
+interface CacheEnvelope {
+	configJson: string;
+	etag?: string;
+	fetchedAt: number;
+}
+
+export interface BehaviorConfigDeps {
+	configUrl: string;
+	appId: string;
+	cache?: AiConfigCache;
+	fetchFn?: typeof fetch;
+	now?: () => number;
+}
+
+/**
+ * Cache-first behavior config (FR-018): launch never blocks on the network;
+ * TTL revalidation uses ETag; designated errors force a reload.
+ */
+export class BehaviorConfigManager {
+	private cacheKey: string;
+	private cache: AiConfigCache;
+	private fetchFn: typeof fetch;
+	private now: () => number;
+	private current?: { config: AppBehaviorConfig; envelope: CacheEnvelope };
+	state: BehaviorState = 'unloaded';
+
+	constructor(private deps: BehaviorConfigDeps) {
+		this.cacheKey = `rn-ai:config:${deps.appId}`;
+		this.cache = deps.cache ?? new MemoryConfigCache();
+		this.fetchFn = deps.fetchFn ?? fetch;
+		this.now = deps.now ?? Date.now;
+	}
+
+	private isFresh(envelope: CacheEnvelope, config: AppBehaviorConfig): boolean {
+		return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
+	}
+
+	private async loadFromCache(): 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';
+		} catch {
+			// corrupted cache entries are ignored, not fatal
+		}
+	}
+
+	private async fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+		const headers: Record<string, string> = {};
+		if (this.current?.envelope.etag) {
+			headers['If-None-Match'] = this.current.envelope.etag;
+		}
+		const response = await this.fetchFn(this.deps.configUrl, { headers });
+		if (response.status === 304 && this.current) {
+			this.current.envelope.fetchedAt = this.now();
+			await this.persist(this.current.envelope);
+			this.state = 'ready-network';
+			return this.current.config;
+		}
+		if (!response.ok) {
+			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
+		}
+		const configJson = await response.text();
+		const config = parseBehaviorConfig(configJson);
+		const envelope: CacheEnvelope = {
+			configJson,
+			etag: response.headers.get('etag') ?? undefined,
+			fetchedAt: this.now(),
+		};
+		this.current = { config, envelope };
+		await this.persist(envelope);
+		this.state = 'ready-network';
+		return config;
+	}
+
+	private async persist(envelope: CacheEnvelope): Promise<void> {
+		await this.cache.set(this.cacheKey, JSON.stringify(envelope)).catch(() => undefined);
+	}
+
+	/**
+	 * Cache-first read. Fresh cache returns immediately; stale cache returns
+	 * immediately too while a background revalidation runs; no cache at all
+	 * falls through to the network (or `config-unavailable`).
+	 */
+	async getConfig(options: { forceReload?: boolean } = {}): Promise<AppBehaviorConfig> {
+		await this.loadFromCache();
+		if (!options.forceReload && this.current) {
+			if (!this.isFresh(this.current.envelope, this.current.config)) {
+				this.fetchNetwork().catch(() => undefined); // background revalidate
+			}
+			return this.current.config;
+		}
+		try {
+			const fetched = await this.fetchNetwork();
+			if (fetched) return fetched;
+		} catch (e) {
+			if (this.current) return this.current.config; // stale beats broken
+			this.state = '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';
+		throw new AiError('config-unavailable', 'no configuration available');
+	}
+}

package/src/core/aiClient.ts

@@ -0,0 +1,230 @@
+import {
+	BehaviorConfigManager,
+	type AiConfigCache,
+	type AppBehaviorConfig,
+	type BehaviorState,
+} from '../config/behaviorConfig';
+import { AiError, errorFromHttp } from '../diagnostics/errors';
+import { requestSse, type SseHandle } from '../transport/sseClient';
+
+/** Minimal slice of the rn-auth `Auth` controller the client needs. */
+export interface TokenProvider {
+	requestAccessToken(
+		resourceKey: string,
+	): Promise<{ status: string; token?: string }>;
+}
+
+export type ContentPart =
+	| { type: 'text'; text: string }
+	| { type: 'image'; mimeType: string; dataBase64: string }
+	| { type: 'audio'; format: 'wav' | 'mp3'; dataBase64: string };
+
+export interface ChatMessage {
+	role: 'system' | 'user' | 'assistant';
+	content: ContentPart[];
+}
+
+export interface ChatRequest {
+	messages: ChatMessage[];
+	options?: { temperature?: number; maxOutputTokens?: number };
+}
+
+export interface Usage {
+	promptTokens: number;
+	completionTokens: number;
+	totalTokens: number;
+}
+
+export interface QuotaSnapshot {
+	minuteRemaining: number;
+	dayRemaining: number;
+	dayTokensRemaining: number;
+}
+
+export interface ChatStreamHandlers {
+	onDelta(text: string): void;
+	onDone(result: { usage: Usage; quota?: QuotaSnapshot }): void;
+	onError(error: AiError): void;
+}
+
+export interface ChatHandle {
+	cancel(): void;
+}
+
+export interface AiBehaviorState {
+	config: BehaviorState;
+	aiEnabled: boolean;
+}
+
+export interface AiClientConfig {
+	appId: string;
+	configUrl: string;
+	auth: TokenProvider;
+	/** rn-auth resource key configured for the gateway API scope. */
+	resourceKey?: string;
+	storage?: AiConfigCache;
+	fetchFn?: typeof fetch;
+	/** Test seam for the SSE transport. */
+	transport?: typeof requestSse;
+}
+
+export interface AiClient {
+	chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle;
+	getQuota(): Promise<QuotaSnapshot>;
+	getBehaviorState(): AiBehaviorState;
+	reloadConfig(): Promise<void>;
+}
+
+interface StreamEvent {
+	type?: string;
+	text?: string;
+	usage?: Usage;
+	quota?: QuotaSnapshot;
+	code?: string;
+}
+
+export function createAiClient(clientConfig: AiClientConfig): AiClient {
+	const resourceKey = clientConfig.resourceKey ?? 'ai-gateway';
+	const transport = clientConfig.transport ?? requestSse;
+	const fetchFn = clientConfig.fetchFn ?? fetch;
+	const configManager = new BehaviorConfigManager({
+		configUrl: clientConfig.configUrl,
+		appId: clientConfig.appId,
+		cache: clientConfig.storage,
+		fetchFn: clientConfig.fetchFn,
+	});
+	let lastConfig: AppBehaviorConfig | undefined;
+
+	async function acquire(): Promise<{ config: AppBehaviorConfig; token: string }> {
+		const config = await configManager.getConfig();
+		lastConfig = config;
+		if (!config.features.aiEnabled) {
+			throw new AiError('config-unavailable', 'AI is disabled for this app', {
+				recoverable: false,
+			});
+		}
+		const tokenResult = await clientConfig.auth.requestAccessToken(resourceKey);
+		if (tokenResult.status !== 'success' || !tokenResult.token) {
+			throw new AiError('auth-invalid', 'could not acquire an access token');
+		}
+		return { config, token: tokenResult.token };
+	}
+
+	const chatUrl = (config: AppBehaviorConfig) =>
+		`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/chat`;
+
+	function chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle {
+		let cancelled = false;
+		let inner: SseHandle | undefined;
+
+		const attempt = async (state: { configReloads: number; authRetries: number }) => {
+			let config: AppBehaviorConfig;
+			let token: string;
+			try {
+				({ config, token } = await acquire());
+			} catch (e) {
+				handlers.onError(e instanceof AiError ? e : new AiError('internal', String(e)));
+				return;
+			}
+			if (cancelled) return;
+
+			let done: { usage: Usage; quota?: QuotaSnapshot } | undefined;
+			let streamErrorCode: string | undefined;
+			inner = transport(
+				{
+					url: chatUrl(config),
+					method: 'POST',
+					headers: {
+						Authorization: `Bearer ${token}`,
+						'Content-Type': 'application/json',
+					},
+					body: JSON.stringify(request),
+				},
+				{
+					onData: payload => {
+						if (payload === '[DONE]') return;
+						let event: StreamEvent;
+						try {
+							event = JSON.parse(payload) as StreamEvent;
+						} catch {
+							return;
+						}
+						if (event.type === 'delta' && typeof event.text === 'string') {
+							handlers.onDelta(event.text);
+						} else if (event.type === 'done' && event.usage) {
+							done = { usage: event.usage, quota: event.quota };
+						} else if (event.type === 'error') {
+							streamErrorCode = event.code ?? 'UPSTREAM_ERROR';
+						}
+					},
+					onEnd: () => {
+						if (cancelled) return;
+						if (streamErrorCode) {
+							handlers.onError(new AiError('upstream-error', 'the AI service failed mid-response'));
+						} else if (done) {
+							handlers.onDone(done);
+						} else {
+							handlers.onError(new AiError('internal', 'stream ended without completion'));
+						}
+					},
+					onError: (status, bodyText) => {
+						if (cancelled) return;
+						// Designated config-stale signals → silent reload + retry once (FR-018).
+						if (
+							config.recovery.reloadOnHttpStatus.includes(status) &&
+							state.configReloads < config.recovery.maxSilentRetries
+						) {
+							configManager
+								.getConfig({ forceReload: true })
+								.then(() => attempt({ ...state, configReloads: state.configReloads + 1 }))
+								.catch(e =>
+									handlers.onError(
+										e instanceof AiError ? e : new AiError('config-unavailable', String(e)),
+									),
+								);
+							return;
+						}
+						// Expired server-side session → one fresh-token retry.
+						if (status === 401 && state.authRetries < 1) {
+							attempt({ ...state, authRetries: state.authRetries + 1 }).catch(() => undefined);
+							return;
+						}
+						handlers.onError(errorFromHttp(status, bodyText));
+					},
+				},
+			);
+		};
+
+		attempt({ configReloads: 0, authRetries: 0 }).catch(() => undefined);
+		return {
+			cancel() {
+				cancelled = true;
+				inner?.cancel();
+			},
+		};
+	}
+
+	async function getQuota(): Promise<QuotaSnapshot> {
+		const { config, token } = await acquire();
+		const response = await fetchFn(
+			`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/quota`,
+			{ headers: { Authorization: `Bearer ${token}` } },
+		);
+		if (!response.ok) {
+			throw errorFromHttp(response.status, await response.text());
+		}
+		return (await response.json()) as QuotaSnapshot;
+	}
+
+	return {
+		chat,
+		getQuota,
+		getBehaviorState: () => ({
+			config: configManager.state,
+			aiEnabled: lastConfig?.features.aiEnabled ?? true,
+		}),
+		reloadConfig: async () => {
+			lastConfig = await configManager.getConfig({ forceReload: true });
+		},
+	};
+}

package/src/diagnostics/errors.ts

@@ -0,0 +1,71 @@
+/** 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';
+		}
+	}
+	return new AiError(code, message, { retryAfterSeconds });
+}

package/src/diagnostics/messageKeys.ts

@@ -0,0 +1,27 @@
+/**
+ * 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];
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 { 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';

package/src/react/hooks.ts

@@ -0,0 +1,113 @@
+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);
+
+	const send = useCallback(
+		(request: ChatRequest) => {
+			handleRef.current?.cancel();
+			setText('');
+			setError(undefined);
+			setRetryAt(undefined);
+			setStatus('loading');
+			handleRef.current = client.chat(request, {
+				onDelta: delta => {
+					setStatus('streaming');
+					setText(previous => previous + delta);
+				},
+				onDone: result => {
+					if (result.quota) setQuota(result.quota);
+					setStatus('done');
+				},
+				onError: aiError => {
+					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(() => {
+		handleRef.current?.cancel();
+		setStatus('idle');
+	}, []);
+
+	useEffect(() => () => 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);
+
+	const refresh = useCallback(() => {
+		setStatus('loading');
+		client
+			.getQuota()
+			.then(snapshot => {
+				if (!alive.current) return;
+				setQuota(snapshot);
+				setStatus('ready');
+			})
+			.catch(() => {
+				if (alive.current) setStatus('error');
+			});
+	}, [client]);
+
+	useEffect(() => {
+		alive.current = true;
+		refresh();
+		return () => {
+			alive.current = false;
+		};
+	}, [refresh]);
+
+	return { quota, status, refresh };
+}

package/src/transport/sseClient.ts

@@ -0,0 +1,106 @@
+/**
+ * Minimal SSE reader over XMLHttpRequest (research R2).
+ *
+ * React Native's fetch does not reliably expose ReadableStream on Hermes, so
+ * we use XHR incremental text delivery (readyState LOADING + onprogress) —
+ * the same mechanism community SSE libraries use — with zero dependencies.
+ * The gateway never compresses SSE responses (contract), which keeps
+ * incremental delivery intact on both platforms.
+ */
+
+export interface SseRequest {
+	url: string;
+	method?: 'GET' | 'POST';
+	headers?: Record<string, string>;
+	/** JSON string body for POST requests. */
+	body?: string;
+	timeoutMs?: number;
+}
+
+export interface SseHandlers {
+	/** One call per `data:` event payload (raw string, already de-framed). */
+	onData(payload: string): void;
+	/** Stream closed normally (transport level; `[DONE]` handling is the caller's). */
+	onEnd(): void;
+	/** Transport or HTTP error. `status` is 0 for network failures. */
+	onError(status: number, bodyText: string): void;
+}
+
+export interface SseHandle {
+	cancel(): void;
+}
+
+/** Parse complete `data:` events out of `text` starting at `fromIndex`. */
+export function drainSseEvents(
+	text: string,
+	fromIndex: number,
+	emit: (payload: string) => void,
+): number {
+	let cursor = fromIndex;
+	for (;;) {
+		const sep = text.indexOf('\n\n', cursor);
+		if (sep === -1) return cursor; // incomplete event stays buffered
+		const rawEvent = text.slice(cursor, sep);
+		cursor = sep + 2;
+		const dataLines = rawEvent
+			.split('\n')
+			.filter(line => line.startsWith('data:'))
+			.map(line => line.slice(5).trimStart());
+		if (dataLines.length > 0) emit(dataLines.join('\n'));
+	}
+}
+
+export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandle {
+	const xhr = new XMLHttpRequest();
+	let seen = 0;
+	let finished = false;
+	let cancelled = false;
+
+	const finish = (fn: () => void) => {
+		if (!finished && !cancelled) {
+			finished = true;
+			fn();
+		}
+	};
+
+	const pump = () => {
+		if (xhr.status !== 200) return; // error path handled on load/error
+		const text: string = xhr.responseText ?? '';
+		seen = drainSseEvents(text, seen, handlers.onData);
+	};
+
+	xhr.open(request.method ?? 'POST', request.url, true);
+	for (const [k, v] of Object.entries(request.headers ?? {})) {
+		xhr.setRequestHeader(k, v);
+	}
+	xhr.setRequestHeader('Accept', 'text/event-stream');
+	if (request.timeoutMs) xhr.timeout = request.timeoutMs;
+
+	xhr.onprogress = pump;
+	xhr.onreadystatechange = () => {
+		if (xhr.readyState === 3) pump(); // LOADING: incremental text
+	};
+	xhr.onload = () => {
+		if (xhr.status === 200) {
+			pump();
+			finish(handlers.onEnd);
+		} else {
+			finish(() => handlers.onError(xhr.status, xhr.responseText ?? ''));
+		}
+	};
+	xhr.onerror = () => finish(() => handlers.onError(0, 'network error'));
+	xhr.ontimeout = () => finish(() => handlers.onError(0, 'timeout'));
+
+	xhr.send(request.body);
+
+	return {
+		cancel() {
+			cancelled = true;
+			try {
+				xhr.abort();
+			} catch {
+				// aborting a settled XHR is a no-op
+			}
+		},
+	};
+}