@chipmobilesdk/rn-ai 0.3.0 → 0.4.0

package/src/diagnostics/errors.ts

@@ -1,8 +1,16 @@
 /** Typed client errors (contracts/rn-ai-public-api.md). */
 import { SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
 
+import {
+	RETRY_AFTER_HEADER,
+	type GatewayErrorBody,
+	type GatewayErrorCode,
+} from '../contract/gateway';
+
 export type AiErrorCode =
 	| 'auth-invalid'
+	/** The session itself ended: the user has to sign in again. */
+	| 'session-expired'
 	| 'not-entitled'
 	| 'user-blocked'
 	| 'app-unknown'
@@ -11,31 +19,45 @@ export type AiErrorCode =
 	| 'payload-too-large'
 	| 'modality-not-allowed'
 	| 'config-unavailable'
+	/** The request never reached the gateway: no connection, a timeout, a dropped stream. */
+	| 'network'
 	| 'upstream-error'
 	| 'internal';
 
 export interface AiErrorOptions {
 	retryAfterSeconds?: number | undefined;
-	/** Whether retrying can succeed. Defaults to true for `rate-limited` and `upstream-busy`. */
+	/** Whether retrying can succeed. Defaults by code; see `RETRYABLE_BY_DEFAULT`. */
 	retryable?: boolean | undefined;
 	/** @deprecated Use `retryable`; accepted as its alias. */
 	recoverable?: boolean | undefined;
+	/**
+	 * The code the layer underneath reported — an rn-auth `AuthErrorCode`, or the
+	 * gateway's own code. Kept so a screen can say *why* rather than only *what*.
+	 */
+	cause?: string | undefined;
 }
 
+/** Codes a retry can fix on its own. */
+const RETRYABLE_BY_DEFAULT: ReadonlySet<AiErrorCode> = new Set<AiErrorCode>([
+	'rate-limited',
+	'upstream-busy',
+	'network',
+]);
+
 /** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-ai'`. */
 export class AiError extends SdkError<AiErrorCode> {
 	readonly retryAfterSeconds?: number | undefined;
+	/** The underlying code, when one layer down had a name for the failure. */
+	readonly cause?: string | undefined;
 
 	constructor(code: AiErrorCode, message: string, options: AiErrorOptions = {}) {
 		super('rn-ai', code, {
 			message,
-			retryable:
-				options.retryable ??
-				options.recoverable ??
-				(code === 'rate-limited' || code === 'upstream-busy'),
+			retryable: options.retryable ?? options.recoverable ?? RETRYABLE_BY_DEFAULT.has(code),
 		});
 		this.name = 'AiError';
 		this.retryAfterSeconds = options.retryAfterSeconds;
+		this.cause = options.cause;
 	}
 
 	/** @deprecated Use `retryable`, the name every SDK package shares. */
@@ -48,42 +70,82 @@ export function isAiError(value: unknown): value is AiError {
 	return value instanceof AiError;
 }
 
-const HTTP_CODE_MAP: Record<string, AiErrorCode> = {
+/**
+ * Every gateway code, mapped. Typed as a total record, so a code added to the
+ * shared contract does not compile until the client says what it means (GW-13).
+ */
+const HTTP_CODE_MAP: Readonly<Record<GatewayErrorCode, AiErrorCode>> = {
+	BAD_REQUEST: 'internal',
 	AUTH_INVALID: 'auth-invalid',
 	NOT_ENTITLED: 'not-entitled',
 	USER_BLOCKED: 'user-blocked',
 	APP_UNKNOWN: 'app-unknown',
+	// The endpoint moved: the client's configuration is the stale part.
+	ENDPOINT_RETIRED: 'config-unavailable',
 	PAYLOAD_TOO_LARGE: 'payload-too-large',
 	MODALITY_NOT_ALLOWED: 'modality-not-allowed',
 	RATE_LIMITED: 'rate-limited',
 	UPSTREAM_BUSY: 'upstream-busy',
 	UPSTREAM_ERROR: 'upstream-error',
+	INTERNAL: 'internal',
 };
 
+function isGatewayCode(value: unknown): value is GatewayErrorCode {
+	return typeof value === 'string' && value in HTTP_CODE_MAP;
+}
+
+/** `Retry-After` in seconds, from either form the header may take. */
+export function parseRetryAfter(value: string | null | undefined): number | undefined {
+	if (!value) {
+		return undefined;
+	}
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) {
+		return seconds;
+	}
+	const date = Date.parse(value);
+	if (Number.isFinite(date)) {
+		return Math.max(0, Math.round((date - Date.now()) / 1000));
+	}
+	return undefined;
+}
+
+export interface HttpErrorContext {
+	/** The response headers, when the transport can read them. */
+	getHeader?: (name: string) => string | null | undefined;
+}
+
 /** Map a gateway error response (status + JSON body) to a typed AiError. */
-export function errorFromHttp(status: number, bodyText: string): AiError {
+export function errorFromHttp(
+	status: number,
+	bodyText: string,
+	context: HttpErrorContext = {},
+): AiError {
+	// Status 0 is not an answer at all: the request never arrived, or the
+	// connection dropped. That is a network failure a retry may well fix, not an
+	// upstream fault (AI-11).
+	if (status === 0) {
+		return new AiError(
+			'network',
+			bodyText === 'timeout' ? 'the request timed out' : 'no connection',
+		);
+	}
+
 	let code: AiErrorCode = status >= 500 ? 'upstream-error' : 'internal';
 	let message = `gateway responded ${status}`;
-	let retryAfterSeconds: number | undefined;
+	let gatewayCode: GatewayErrorCode | undefined;
+	let retryAfterSeconds = parseRetryAfter(context.getHeader?.(RETRY_AFTER_HEADER));
 	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];
+		const parsed = JSON.parse(bodyText) as Partial<GatewayErrorBody>;
+		if (isGatewayCode(parsed.error?.code)) {
+			gatewayCode = parsed.error.code;
+			code = HTTP_CODE_MAP[gatewayCode];
 		}
 		// 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;
+		retryAfterSeconds = parsed.error?.retryAfterSeconds ?? retryAfterSeconds;
 	} catch {
-		if (status === 0) {
-			code = 'upstream-error';
-			message = 'network failure';
-		}
+		// A body that is not the contract's: the status is all there is to go on.
 	}
-	// Status 0 is a dropped connection, which a retry may well fix.
-	return new AiError(code, message, {
-		retryAfterSeconds,
-		recoverable: status === 0 ? true : undefined,
-	});
+	return new AiError(code, message, { retryAfterSeconds, cause: gatewayCode });
 }

package/src/diagnostics/messageKeys.ts

@@ -27,6 +27,7 @@ export const aiMessageSet = defineMessages({
 		'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.offline': 'No connection. Check your network and try again.',
 		'ai.error.generic': 'Something went wrong. Please try again.',
 	},
 });
@@ -45,6 +46,8 @@ export function aiMessage(key: AiMessageKey): string {
  */
 const ERROR_MESSAGES: Record<AiErrorCode, AiMessageKey> = {
 	'auth-invalid': 'ai.error.signIn',
+	'session-expired': 'ai.error.signIn',
+	network: 'ai.error.offline',
 	'not-entitled': 'ai.error.premiumRequired',
 	'user-blocked': 'ai.error.blocked',
 	'app-unknown': 'ai.error.unavailable',

package/src/index.ts

@@ -10,6 +10,7 @@ export type {
 	AiClientConfig,
 	AiBehaviorState,
 	TokenProvider,
+	AccessTokenRequestOptions,
 	ChatRequest,
 	ChatMessage,
 	ContentPart,
@@ -20,10 +21,36 @@ export type {
 } from './core/aiClient';
 
 export type { AppBehaviorConfig, AiConfigCache, BehaviorState } from './config/behaviorConfig';
+export { configCacheFromKeyValue, SUPPORTED_SCHEMA_VERSION } from './config/behaviorConfig';
+
+// The gateway contract, shared with the service: error codes, quota headers and
+// stream events have one definition (GW-13).
+export type {
+	GatewayErrorCode,
+	GatewayErrorBody,
+	GatewayQuota,
+	GatewayStreamEvent,
+	GatewayUsage,
+	QuotaHeaderName,
+	QuotaHeaderNames,
+} from './contract/gateway';
+export { GATEWAY_ERROR_STATUS, QUOTA_HEADERS, SSE_DONE_SENTINEL } from './contract/gateway';
 
 export type { AiTimeouts } from './transport/timeouts';
+export type {
+	SseRequest,
+	SseHandlers,
+	SseHandle,
+	SseResponseInfo,
+	StreamTransport,
+} from './transport/sseClient';
 export { useAiBehaviorState, useAiChat, useAiQuota } from './react/hooks';
-export type { AiChatStatus, UseAiChatResult, UseAiQuotaResult } from './react/hooks';
+export type {
+	AiChatStatus,
+	UseAiChatOptions,
+	UseAiChatResult,
+	UseAiQuotaResult,
+} from './react/hooks';
 
 export { AiError, isAiError } from './diagnostics/errors';
 export type { AiErrorCode } from './diagnostics/errors';

package/src/react/hooks.ts

@@ -15,30 +15,74 @@ export interface UseAiChatResult {
 	send(request: ChatRequest): void;
 	cancel(): void;
 	status: AiChatStatus;
-	/** Accumulated streamed text (appends incrementally — PERF-002). */
+	/** Accumulated streamed text, flushed on an interval rather than per token. */
 	text: string;
 	error?: AiError;
 	retryAt?: Date;
 	quota?: QuotaSnapshot;
 }
 
-export function useAiChat(client: AiClient): UseAiChatResult {
+export interface UseAiChatOptions {
+	/**
+	 * How often the accumulated text reaches the screen, in milliseconds.
+	 *
+	 * A model streams 30–100 tokens a second, and a render per token is 30–100
+	 * renders of the whole transcript a second on the JS thread (PERF-12). At the
+	 * default a long answer costs about 20 renders a second instead, and the last
+	 * tokens are always flushed with the terminal state. `0` renders per token.
+	 */
+	flushIntervalMs?: number;
+}
+
+const DEFAULT_FLUSH_MS = 50;
+
+export function useAiChat(client: AiClient, options: UseAiChatOptions = {}): 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 fromClient = useAiQuotaValue(client);
+	// The figure this chat was told, for a client of the app's own that keeps none.
+	const [reported, setReported] = useState<QuotaSnapshot | undefined>();
+	const quota = fromClient ?? reported;
 	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);
 
+	// Deltas land here and reach React on a timer, so the transcript renders at a
+	// steady rate however fast the model answers.
+	const pending = useRef('');
+	const flushTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+	const flushMs = options.flushIntervalMs ?? DEFAULT_FLUSH_MS;
+
+	const stopFlushing = useCallback(() => {
+		if (flushTimer.current !== undefined) {
+			clearTimeout(flushTimer.current);
+			flushTimer.current = undefined;
+		}
+	}, []);
+
+	const flush = useCallback(() => {
+		flushTimer.current = undefined;
+		const buffered = pending.current;
+		if (buffered === '') {
+			return;
+		}
+		pending.current = '';
+		setText(previous => previous + buffered);
+	}, []);
+
+	useEffect(() => stopFlushing, [stopFlushing]);
+
 	const send = useCallback(
 		(request: ChatRequest) => {
 			handleRef.current?.cancel();
 			const id = ++requestRef.current;
 			const current = () => requestRef.current === id;
+			stopFlushing();
+			pending.current = '';
 			setText('');
 			setError(undefined);
 			setRetryAt(undefined);
@@ -46,16 +90,28 @@ export function useAiChat(client: AiClient): UseAiChatResult {
 			handleRef.current = client.chat(request, {
 				onDelta: delta => {
 					if (!current()) return;
-					setStatus('streaming');
-					setText(previous => previous + delta);
+					pending.current += delta;
+					if (flushMs <= 0) {
+						flush();
+					} else if (flushTimer.current === undefined) {
+						flushTimer.current = setTimeout(flush, flushMs);
+					}
+					// Only the first delta is a state change; the rest are text.
+					setStatus(previous => (previous === 'streaming' ? previous : 'streaming'));
 				},
 				onDone: result => {
 					if (!current()) return;
-					if (result.quota) setQuota(result.quota);
+					stopFlushing();
+					flush();
+					if (result.quota) setReported(result.quota);
 					setStatus('done');
 				},
 				onError: aiError => {
 					if (!current()) return;
+					stopFlushing();
+					// Whatever arrived before the failure is kept: a half-answer is
+					// still what the user was reading.
+					flush();
 					setError(aiError);
 					if (aiError.code === 'rate-limited') {
 						setStatus('rate-limited');
@@ -68,14 +124,15 @@ export function useAiChat(client: AiClient): UseAiChatResult {
 				},
 			});
 		},
-		[client],
+		[client, flush, flushMs, stopFlushing],
 	);
 
 	const cancel = useCallback(() => {
 		requestRef.current += 1;
+		stopFlushing();
 		handleRef.current?.cancel();
 		setStatus('idle');
-	}, []);
+	}, [stopFlushing]);
 
 	useEffect(
 		() => () => {
@@ -94,8 +151,25 @@ export interface UseAiQuotaResult {
 	refresh(): void;
 }
 
+const noSubscription = () => () => undefined;
+
+/**
+ * The quota the client last saw, from a chat's `done` event or from
+ * `getQuota()`. One source, so a figure on screen is not stale the moment a
+ * chat finishes (AI-13).
+ */
+function useAiQuotaValue(client: AiClient): QuotaSnapshot | undefined {
+	return useExternalStore(
+		client.subscribe ?? noSubscription,
+		client.lastQuota ?? (() => undefined),
+	);
+}
+
 export function useAiQuota(client: AiClient): UseAiQuotaResult {
-	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
+	const fromClient = useAiQuotaValue(client);
+	// A client of the app's own may not keep the last quota; then this is it.
+	const [fetched, setFetched] = useState<QuotaSnapshot | undefined>();
+	const quota = fromClient ?? fetched;
 	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
@@ -110,7 +184,7 @@ export function useAiQuota(client: AiClient): UseAiQuotaResult {
 			.getQuota()
 			.then(snapshot => {
 				if (!current()) return;
-				setQuota(snapshot);
+				setFetched(snapshot);
 				setStatus('ready');
 			})
 			.catch(() => {
@@ -126,7 +200,8 @@ export function useAiQuota(client: AiClient): UseAiQuotaResult {
 		};
 	}, [refresh]);
 
-	return { quota, status, refresh };
+	// A quota that arrived through a chat is an answer too: nothing is loading.
+	return { quota, status: status === 'loading' && quota ? 'ready' : status, refresh };
 }
 
 /**
@@ -136,6 +211,3 @@ export function useAiQuota(client: AiClient): UseAiQuotaResult {
 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;

package/src/transport/sseClient.ts

@@ -22,20 +22,42 @@ export interface SseRequest {
 	idleTimeoutMs?: number;
 }
 
+/** What the response said besides its body. Absent for a failure with no response. */
+export interface SseResponseInfo {
+	/** A response header, or null. `Retry-After` is the one this package reads. */
+	getHeader(name: string): string | null;
+}
+
 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;
+	onError(status: number, bodyText: string, response?: SseResponseInfo): void;
 }
 
 export interface SseHandle {
 	cancel(): void;
 }
 
-/** Parse complete `data:` events out of `text` starting at `fromIndex`. */
+/**
+ * The transport port: how this package makes a streaming request.
+ *
+ * A published port rather than `typeof requestSse`, so the default reader's
+ * own signature is not part of the public API (AI-18): an app may inject its
+ * own transport, and this package may change how `requestSse` is written
+ * without that being a breaking change.
+ */
+export type StreamTransport = (request: SseRequest, handlers: SseHandlers) => SseHandle;
+
+/**
+ * Parse complete `data:` events out of `text` starting at `fromIndex`.
+ *
+ * Both line endings are accepted. A proxy that normalises to CRLF — an API
+ * gateway or a corporate middlebox — used to make every event invisible until
+ * the stream closed, because only `\n\n` counted as a separator (AI-22).
+ */
 export function drainSseEvents(
 	text: string,
 	fromIndex: number,
@@ -43,15 +65,19 @@ export function drainSseEvents(
 ): 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 separator = /\r\n\r\n|\n\n|\r\r/.exec(text.slice(cursor));
+		if (!separator) {
+			return cursor; // incomplete event stays buffered
+		}
+		const rawEvent = text.slice(cursor, cursor + separator.index);
+		cursor += separator.index + separator[0].length;
 		const dataLines = rawEvent
-			.split('\n')
+			.split(/\r\n|\n|\r/)
 			.filter(line => line.startsWith('data:'))
 			.map(line => line.slice(5).trimStart());
-		if (dataLines.length > 0) emit(dataLines.join('\n'));
+		if (dataLines.length > 0) {
+			emit(dataLines.join('\n'));
+		}
 	}
 }
 
@@ -71,6 +97,18 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 		}
 	};
 
+	/** The response's own headers, for `Retry-After` on a 429 (AI-11). */
+	const response: SseResponseInfo = {
+		getHeader(name) {
+			try {
+				return xhr.getResponseHeader(name);
+			} catch {
+				// Headers are unavailable before they arrive, and on some polyfills.
+				return null;
+			}
+		},
+	};
+
 	const finish = (fn: () => void) => {
 		disarm();
 		if (!finished && !cancelled) {
@@ -96,10 +134,19 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 		if (ms && !finished && !cancelled) stallTimer = setTimeout(stalled, ms);
 	};
 
+	/**
+	 * Drains whatever has arrived. `onprogress` and `readyState === 3` both fire
+	 * for the same chunk, and which of the two fires at all has been platform
+	 * dependent, so both stay registered; the length check makes the second call
+	 * for one chunk free rather than another full `responseText` drain (AI-V1).
+	 */
+	let drained = -1;
 	const pump = () => {
 		if (xhr.status !== 200) return; // error path handled on load/error
-		arm(request.idleTimeoutMs);
 		const text: string = xhr.responseText ?? '';
+		if (text.length === drained) return;
+		drained = text.length;
+		arm(request.idleTimeoutMs);
 		seen = drainSseEvents(text, seen, handlers.onData);
 	};
 
@@ -112,7 +159,7 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 
 	xhr.onprogress = pump;
 	xhr.onreadystatechange = () => {
-		if (xhr.readyState === 2) arm(request.idleTimeoutMs); // HEADERS_RECEIVED
+		if (xhr.readyState === 2) arm(request.connectTimeoutMs); // HEADERS_RECEIVED
 		if (xhr.readyState === 3) pump(); // LOADING: incremental text
 	};
 	xhr.onload = () => {
@@ -120,7 +167,7 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 			pump();
 			finish(handlers.onEnd);
 		} else {
-			finish(() => handlers.onError(xhr.status, xhr.responseText ?? ''));
+			finish(() => handlers.onError(xhr.status, xhr.responseText ?? '', response));
 		}
 	};
 	xhr.onerror = () => finish(() => handlers.onError(0, 'network error'));