@chipmobilesdk/rn-ai 0.2.0 → 0.3.0

package/src/core/aiClient.ts

@@ -1,281 +1,354 @@
-import {
-	BehaviorConfigManager,
-	type AiConfigCache,
-	type AppBehaviorConfig,
-	type BehaviorState,
-} from '../config/behaviorConfig';
-import { AiError, errorFromHttp } from '../diagnostics/errors';
-import { requestSse, type SseHandle } from '../transport/sseClient';
-import { DEFAULT_AI_TIMEOUTS, withTimeout, type AiTimeouts } from '../transport/timeouts';
-
-/** 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;
-	/** Overrides for the network time limits; see `AiTimeouts` for the defaults. */
-	timeouts?: Partial<AiTimeouts>;
-}
-
-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 timeouts: AiTimeouts = { ...DEFAULT_AI_TIMEOUTS, ...clientConfig.timeouts };
-	const configManager = new BehaviorConfigManager({
-		configUrl: clientConfig.configUrl,
-		appId: clientConfig.appId,
-		cache: clientConfig.storage,
-		fetchFn: clientConfig.fetchFn,
-		timeoutMs: timeouts.configMs,
-	});
-	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 settled = false;
-		let inner: SseHandle | undefined;
-
-		// Every callback to the app goes through here. Nothing is delivered after
-		// cancel() — an acquire() or config reload that failed after the user
-		// cancelled (or sent the next message) used to flip that screen to
-		// `error` — and exactly one terminal callback is delivered.
-		const emit = {
-			delta(text: string) {
-				if (!cancelled && !settled) handlers.onDelta(text);
-			},
-			done(result: { usage: Usage; quota?: QuotaSnapshot }) {
-				if (cancelled || settled) return;
-				settled = true;
-				handlers.onDone(result);
-			},
-			error(error: AiError) {
-				if (cancelled || settled) return;
-				settled = true;
-				inner?.cancel();
-				handlers.onError(error);
-			},
-		};
-
-		// Any exception on the way becomes a reported error. Each path used to end
-		// in `.catch(() => undefined)`, so a transport that threw (a bad URL from
-		// remote config, say) left the UI in `loading` with nothing to show.
-		const fail = (e: unknown) =>
-			emit.error(
-				e instanceof AiError
-					? e
-					: new AiError('internal', e instanceof Error ? e.message : String(e)),
-			);
-		const guarded =
-			<A extends unknown[]>(fn: (...args: A) => void) =>
-			(...args: A) => {
-				try {
-					fn(...args);
-				} catch (e) {
-					fail(e);
-				}
-			};
-
-		const attempt = async (state: { configReloads: number; authRetries: number }) => {
-			const { config, token } = await acquire();
-			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),
-					connectTimeoutMs: timeouts.connectMs,
-					idleTimeoutMs: timeouts.idleMs,
-				},
-				{
-					onData: guarded(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') {
-							emit.delta(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: guarded(() => {
-						if (streamErrorCode) {
-							emit.error(new AiError('upstream-error', 'the AI service failed mid-response'));
-						} else if (done) {
-							emit.done(done);
-						} else {
-							emit.error(new AiError('internal', 'stream ended without completion'));
-						}
-					}),
-					onError: guarded((status, bodyText) => {
-						if (cancelled) return;
-						if (status === 0 && bodyText === 'timeout') {
-							emit.error(
-								new AiError('upstream-error', 'the AI service stopped responding', {
-									recoverable: true,
-								}),
-							);
-							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(fail),
-								e =>
-									fail(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(fail);
-							return;
-						}
-						emit.error(errorFromHttp(status, bodyText));
-					}),
-				},
-			);
-		};
-
-		attempt({ configReloads: 0, authRetries: 0 }).catch(fail);
-		return {
-			cancel() {
-				cancelled = true;
-				inner?.cancel();
-			},
-		};
-	}
-
-	async function getQuota(): Promise<QuotaSnapshot> {
-		const { config, token } = await acquire();
-		return withTimeout(
-			timeouts.quotaMs,
-			async signal => {
-				const response = await fetchFn(
-					`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/quota`,
-					{ headers: { Authorization: `Bearer ${token}` }, signal },
-				);
-				if (!response.ok) {
-					throw errorFromHttp(response.status, await response.text());
-				}
-				return (await response.json()) as QuotaSnapshot;
-			},
-			() => new AiError('upstream-error', 'quota request timed out', { recoverable: true }),
-		);
-	}
-
-	return {
-		chat,
-		getQuota,
-		getBehaviorState: () => ({
-			config: configManager.state,
-			aiEnabled: lastConfig?.features.aiEnabled ?? true,
-		}),
-		reloadConfig: async () => {
-			lastConfig = await configManager.getConfig({ forceReload: true });
-		},
-	};
-}
+import {
+	createDiagnosticChannel,
+	createListenerSet,
+	realScheduler,
+	type Scheduler,
+} from '@chipmobilesdk/rn-core';
+
+import {
+	BehaviorConfigManager,
+	type AiConfigCache,
+	type AppBehaviorConfig,
+	type BehaviorState,
+} from '../config/behaviorConfig';
+import { AiError, errorFromHttp, type AiErrorCode } from '../diagnostics/errors';
+import { requestSse, type SseHandle } from '../transport/sseClient';
+import { DEFAULT_AI_TIMEOUTS, withTimeout, type AiTimeouts } from '../transport/timeouts';
+
+/** Every failure a caller receives also goes to the app's SDK sinks (CORE-08). */
+const channel = createDiagnosticChannel<AiErrorCode>('rn-ai');
+
+function report(operation: 'chat' | 'quota', error: AiError): void {
+	channel.emit(error.code, error.retryable ? 'warn' : 'error', {
+		operation,
+		retryable: error.retryable,
+	});
+}
+
+/** 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;
+	/** Overrides for the network time limits; see `AiTimeouts` for the defaults. */
+	timeouts?: Partial<AiTimeouts>;
+	/** Test seam: how the backoff before a silent retry is waited out. */
+	scheduler?: Scheduler;
+}
+
+/** Ceiling on one remote-configured backoff step, so a bad document cannot stall a chat. */
+const MAX_RETRY_BACKOFF_MS = 30_000;
+
+/** The wait before silent retry `index` (0-based); the last configured step repeats. */
+function backoffBefore(steps: readonly number[], index: number): number {
+	const step = steps[Math.min(index, steps.length - 1)] ?? 0;
+	return Math.min(Math.max(0, step), MAX_RETRY_BACKOFF_MS);
+}
+
+export interface AiClient {
+	chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle;
+	getQuota(): Promise<QuotaSnapshot>;
+	/** The current behavior state; the same object until it changes. */
+	getBehaviorState(): AiBehaviorState;
+	/**
+	 * Called whenever the behavior state changes (AI-09); returns the unsubscribe.
+	 * Optional so an app's own `AiClient` implementation keeps compiling.
+	 */
+	subscribe?(listener: () => void): () => void;
+	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 timeouts: AiTimeouts = { ...DEFAULT_AI_TIMEOUTS, ...clientConfig.timeouts };
+	const scheduler = clientConfig.scheduler ?? realScheduler;
+	const configManager = new BehaviorConfigManager({
+		configUrl: clientConfig.configUrl,
+		appId: clientConfig.appId,
+		cache: clientConfig.storage,
+		fetchFn: clientConfig.fetchFn,
+		timeoutMs: timeouts.configMs,
+	});
+	let lastConfig: AppBehaviorConfig | undefined;
+	const behaviorListeners = createListenerSet<[]>();
+	let snapshot: AiBehaviorState | undefined;
+
+	/** Rebuilt only when a field changes, so useSyncExternalStore sees a stable object. */
+	function behaviorState(): AiBehaviorState {
+		const config = configManager.state;
+		const aiEnabled = lastConfig?.features.aiEnabled ?? true;
+		if (!snapshot || snapshot.config !== config || snapshot.aiEnabled !== aiEnabled) {
+			snapshot = { config, aiEnabled };
+		}
+		return snapshot;
+	}
+
+	function setLastConfig(next: AppBehaviorConfig): void {
+		const wasEnabled = lastConfig?.features.aiEnabled ?? true;
+		lastConfig = next;
+		if (next.features.aiEnabled !== wasEnabled) behaviorListeners.notify();
+	}
+
+	async function acquire(): Promise<{ config: AppBehaviorConfig; token: string }> {
+		const config = await configManager.getConfig();
+		setLastConfig(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 settled = false;
+		let inner: SseHandle | undefined;
+
+		// Every callback to the app goes through here. Nothing is delivered after
+		// cancel() — an acquire() or config reload that failed after the user
+		// cancelled (or sent the next message) used to flip that screen to
+		// `error` — and exactly one terminal callback is delivered.
+		const emit = {
+			delta(text: string) {
+				if (!cancelled && !settled) handlers.onDelta(text);
+			},
+			done(result: { usage: Usage; quota?: QuotaSnapshot }) {
+				if (cancelled || settled) return;
+				settled = true;
+				handlers.onDone(result);
+			},
+			error(error: AiError) {
+				if (cancelled || settled) return;
+				settled = true;
+				inner?.cancel();
+				report('chat', error);
+				handlers.onError(error);
+			},
+		};
+
+		// Any exception on the way becomes a reported error. Each path used to end
+		// in `.catch(() => undefined)`, so a transport that threw (a bad URL from
+		// remote config, say) left the UI in `loading` with nothing to show.
+		const fail = (e: unknown) =>
+			emit.error(
+				e instanceof AiError
+					? e
+					: new AiError('internal', e instanceof Error ? e.message : String(e)),
+			);
+		const guarded =
+			<A extends unknown[]>(fn: (...args: A) => void) =>
+			(...args: A) => {
+				try {
+					fn(...args);
+				} catch (e) {
+					fail(e);
+				}
+			};
+
+		const attempt = async (state: { configReloads: number; authRetries: number }) => {
+			const { config, token } = await acquire();
+			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),
+					connectTimeoutMs: timeouts.connectMs,
+					idleTimeoutMs: timeouts.idleMs,
+				},
+				{
+					onData: guarded(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') {
+							emit.delta(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: guarded(() => {
+						if (streamErrorCode) {
+							emit.error(new AiError('upstream-error', 'the AI service failed mid-response'));
+						} else if (done) {
+							emit.done(done);
+						} else {
+							emit.error(new AiError('internal', 'stream ended without completion'));
+						}
+					}),
+					onError: guarded((status, bodyText) => {
+						if (cancelled) return;
+						if (status === 0 && bodyText === 'timeout') {
+							emit.error(
+								new AiError('upstream-error', 'the AI service stopped responding', {
+									recoverable: true,
+								}),
+							);
+							return;
+						}
+						// Designated config-stale signals → silent reload + retry once (FR-018).
+						if (
+							config.recovery.reloadOnHttpStatus.includes(status) &&
+							state.configReloads < config.recovery.maxSilentRetries
+						) {
+							// Waits `recovery.retryBackoffMs` first (AI-05): a gateway mid-rollout
+							// that answered 410 a moment ago may well answer it again at once.
+							const retryAfter = backoffBefore(config.recovery.retryBackoffMs, state.configReloads);
+							configManager.getConfig({ forceReload: true }).then(
+								() => {
+									scheduler.setTimeout(() => {
+										if (cancelled) return;
+										attempt({ ...state, configReloads: state.configReloads + 1 }).catch(fail);
+									}, retryAfter);
+								},
+								e => fail(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(fail);
+							return;
+						}
+						emit.error(errorFromHttp(status, bodyText));
+					}),
+				},
+			);
+		};
+
+		attempt({ configReloads: 0, authRetries: 0 }).catch(fail);
+		return {
+			cancel() {
+				cancelled = true;
+				inner?.cancel();
+			},
+		};
+	}
+
+	async function getQuota(): Promise<QuotaSnapshot> {
+		try {
+			return await fetchQuota();
+		} catch (error) {
+			if (error instanceof AiError) report('quota', error);
+			throw error;
+		}
+	}
+
+	async function fetchQuota(): Promise<QuotaSnapshot> {
+		const { config, token } = await acquire();
+		return withTimeout(
+			timeouts.quotaMs,
+			async signal => {
+				const response = await fetchFn(
+					`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/quota`,
+					{ headers: { Authorization: `Bearer ${token}` }, signal },
+				);
+				if (!response.ok) {
+					throw errorFromHttp(response.status, await response.text());
+				}
+				return (await response.json()) as QuotaSnapshot;
+			},
+			() => new AiError('upstream-error', 'quota request timed out', { recoverable: true }),
+		);
+	}
+
+	return {
+		chat,
+		getQuota,
+		getBehaviorState: () => behaviorState(),
+		subscribe: listener => {
+			const fromManager = configManager.subscribe(listener);
+			const fromClient = behaviorListeners.add(listener);
+			return () => {
+				fromManager();
+				fromClient();
+			};
+		},
+		reloadConfig: async () => {
+			setLastConfig(await configManager.getConfig({ forceReload: true }));
+		},
+	};
+}