@chipmobilesdk/rn-ai 0.1.1 → 0.2.1

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,34 +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 { 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,113 +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);
-
-	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 };
-}
+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 };
+}

package/src/transport/sseClient.ts

@@ -1,106 +1,143 @@
-/**
- * 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
-			}
-		},
-	};
-}
+/**
+ * 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;
+	/** Hard limit on the whole request. Rarely right for a stream; prefer the two below. */
+	timeoutMs?: number;
+	/** Fails with `onError(0, 'timeout')` if response headers have not arrived by then. */
+	connectTimeoutMs?: number;
+	/** Fails with `onError(0, 'timeout')` when no chunk arrives for this long. Reset per chunk. */
+	idleTimeoutMs?: 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;
+
+	// One timer, re-armed as the request progresses: the connect limit until
+	// headers arrive, then the idle limit, restarted by every chunk.
+	let stallTimer: ReturnType<typeof setTimeout> | undefined;
+	const disarm = () => {
+		if (stallTimer !== undefined) {
+			clearTimeout(stallTimer);
+			stallTimer = undefined;
+		}
+	};
+
+	const finish = (fn: () => void) => {
+		disarm();
+		if (!finished && !cancelled) {
+			finished = true;
+			fn();
+		}
+	};
+
+	const stalled = () => {
+		stallTimer = undefined;
+		if (finished || cancelled) return;
+		finished = true;
+		try {
+			xhr.abort();
+		} catch {
+			// already settled
+		}
+		handlers.onError(0, 'timeout');
+	};
+
+	const arm = (ms: number | undefined) => {
+		disarm();
+		if (ms && !finished && !cancelled) stallTimer = setTimeout(stalled, ms);
+	};
+
+	const pump = () => {
+		if (xhr.status !== 200) return; // error path handled on load/error
+		arm(request.idleTimeoutMs);
+		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 === 2) arm(request.idleTimeoutMs); // HEADERS_RECEIVED
+		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);
+	arm(request.connectTimeoutMs);
+
+	return {
+		cancel() {
+			cancelled = true;
+			disarm();
+			try {
+				xhr.abort();
+			} catch {
+				// aborting a settled XHR is a no-op
+			}
+		},
+	};
+}