@chipmobilesdk/rn-ai 0.2.0 → 0.2.1

package/src/diagnostics/errors.ts

@@ -1,75 +1,74 @@
-/** 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). */
+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,
+	});
+}

package/src/diagnostics/messageKeys.ts

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

@@ -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 { 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

@@ -1,134 +1,123 @@
-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 { 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 };
+}