@chipmobilesdk/rn-ai 0.2.0 → 0.3.0

package/skills/sdk-rn-ai/SKILL.md

@@ -1,57 +1,56 @@
----
-name: sdk-rn-ai
-description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
-metadata:
-  package: "@chipmobilesdk/rn-ai"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ai
-
-Client and React hooks for AI chat backed by the gateway, including quota reporting
-and a typed error model.
-
-## Use this when
-
-- Adding an AI chat screen or message composer
-- Displaying remaining quota
-- Handling AI request failure, cancellation, or streaming state
-- Localising AI-related user messages
-
-## The app owns more than you expect
-
-This package deliberately does not handle everything. The README has an
-`## App responsibilities` section listing what the consuming app must implement —
-read it before assuming a behaviour is built in.
-
-## Cancellation is required, not optional
-
-`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
-screen unmounts, otherwise the response resolves against a dead component. Verify
-teardown on every screen that uses it.
-
-## Public API (v0.2.0)
-
-Runtime:
-
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
-- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
-
-Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Setup` |
-| Streaming, retries, timeouts | `## Runtime behavior` |
-| Full export list | `## Public API` |
-| What the app must implement | `## App responsibilities` |
-| Version/peer constraints | `## Compatibility` |
+---
+name: sdk-rn-ai
+description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
+metadata:
+  package: "@chipmobilesdk/rn-ai"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ai
+
+Client and React hooks for AI chat backed by the gateway, including quota reporting
+and a typed error model.
+
+## Use this when
+
+- Adding an AI chat screen or message composer
+- Displaying remaining quota
+- Handling AI request failure, cancellation, or streaming state
+- Localising AI-related user messages
+
+## The app owns more than you expect
+
+This package deliberately does not handle everything. The README has an
+`## App responsibilities` section listing what the consuming app must implement —
+read it before assuming a behaviour is built in.
+
+## Cancellation is required, not optional
+
+`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
+screen unmounts, otherwise the response resolves against a dead component. Verify
+teardown on every screen that uses it.
+
+## Public API
+
+Runtime:
+
+- `createAiClient(...)` — transport-level client
+- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`
+- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
+- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+
+Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Setup` |
+| Streaming, retries, timeouts | `## Runtime behavior` |
+| Full export list | `## Public API` |
+| What the app must implement | `## App responsibilities` |
+| Version/peer constraints | `## Compatibility` |

package/src/config/behaviorConfig.ts

@@ -1,200 +1,233 @@
-import { AiError } from '../diagnostics/errors';
-import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
-
-/** 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';
-
-const numbers = (value: unknown): number[] | undefined =>
-	Array.isArray(value) ? value.filter((n): n is number => Number.isFinite(n)) : undefined;
-
-/** 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'],
-		// Typed here, once: a remote document with `reloadOnHttpStatus: "404"` used to
-		// throw a TypeError inside the XHR error callback, where nothing caught it.
-		recovery: {
-			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
-			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
-				? Number(recovery.maxSilentRetries)
-				: 1,
-			retryBackoffMs: numbers(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;
-	/** Limit on one config fetch, body included. Defaults to 10 s. */
-	timeoutMs?: 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;
-		}
-		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
-		const { response, configJson } = await withTimeout(
-			this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs,
-			async signal => {
-				const res = await this.fetchFn(this.deps.configUrl, { headers, signal });
-				return { response: res, configJson: res.ok && res.status !== 304 ? await res.text() : '' };
-			},
-			() => new AiError('config-unavailable', 'config fetch timed out'),
-		);
-		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 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');
-	}
-}
+import { createListenerSet, createSingleFlight } from '@chipmobilesdk/rn-core';
+
+import { AiError } from '../diagnostics/errors';
+import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
+
+/** 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';
+
+const numbers = (value: unknown): number[] | undefined =>
+	Array.isArray(value) ? value.filter((n): n is number => Number.isFinite(n)) : undefined;
+
+/** 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'],
+		// Typed here, once: a remote document with `reloadOnHttpStatus: "404"` used to
+		// throw a TypeError inside the XHR error callback, where nothing caught it.
+		recovery: {
+			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
+			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
+				? Number(recovery.maxSilentRetries)
+				: 1,
+			retryBackoffMs: numbers(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;
+	/** Limit on one config fetch, body included. Defaults to 10 s. */
+	timeoutMs?: 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 };
+	/**
+	 * One cache read and one network fetch at a time (AI-08): a cold start makes a
+	 * chat and a quota call together, and each used to fetch the config itself.
+	 */
+	private readonly cacheRead = createSingleFlight<void>();
+	private readonly networkFetch = createSingleFlight<AppBehaviorConfig | undefined>();
+	private currentState: BehaviorState = 'unloaded';
+	private readonly stateListeners = createListenerSet<[]>();
+
+	/** Where the config came from, or why there is none. */
+	get state(): BehaviorState {
+		return this.currentState;
+	}
+
+	/** Called whenever `state` changes (AI-09). */
+	subscribe(listener: () => void): () => void {
+		return this.stateListeners.add(listener);
+	}
+
+	private setState(next: BehaviorState): void {
+		if (next === this.currentState) return;
+		this.currentState = next;
+		this.stateListeners.notify();
+	}
+
+	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 loadFromCache(): Promise<void> {
+		return this.current ? Promise.resolve() : this.cacheRead.run(() => this.readCache());
+	}
+
+	private async readCache(): 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.setState('ready-cache');
+		} catch {
+			// corrupted cache entries are ignored, not fatal
+		}
+	}
+
+	private fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+		return this.networkFetch.run(() => this.fetchFromNetwork());
+	}
+
+	private async fetchFromNetwork(): Promise<AppBehaviorConfig | undefined> {
+		const headers: Record<string, string> = {};
+		if (this.current?.envelope.etag) {
+			headers['If-None-Match'] = this.current.envelope.etag;
+		}
+		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
+		const { response, configJson } = await withTimeout(
+			this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs,
+			async signal => {
+				const res = await this.fetchFn(this.deps.configUrl, { headers, signal });
+				return { response: res, configJson: res.ok && res.status !== 304 ? await res.text() : '' };
+			},
+			() => new AiError('config-unavailable', 'config fetch timed out'),
+		);
+		if (response.status === 304 && this.current) {
+			this.current.envelope.fetchedAt = this.now();
+			await this.persist(this.current.envelope);
+			this.setState('ready-network');
+			return this.current.config;
+		}
+		if (!response.ok) {
+			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
+		}
+		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.setState('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.setState('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.setState('unavailable');
+		throw new AiError('config-unavailable', 'no configuration available');
+	}
+}