@chipmobilesdk/rn-ai 0.3.0 → 0.5.0

package/src/contract/gateway.ts

@@ -0,0 +1,91 @@
+/**
+ * The gateway↔client contract: error codes, quota headers, stream events.
+ *
+ * One definition, imported by both sides (GW-13). The gateway's own codes and
+ * the client's map of them were two hand-maintained lists, and they had already
+ * drifted: `BAD_REQUEST`, `ENDPOINT_RETIRED` and `INTERNAL` existed on the
+ * server and were unknown to the client, which fell back to a guess from the
+ * status. Adding a code now fails to compile on whichever side has not handled
+ * it.
+ *
+ * Types and plain constants only, and no import of anything: the gateway runs
+ * on Node and imports this file for its types alone.
+ */
+
+/** Every error the gateway answers with (`error.code` in the body). */
+export type GatewayErrorCode =
+	| 'BAD_REQUEST'
+	| 'AUTH_INVALID'
+	| 'NOT_ENTITLED'
+	| 'USER_BLOCKED'
+	| 'APP_UNKNOWN'
+	| 'ENDPOINT_RETIRED'
+	| 'PAYLOAD_TOO_LARGE'
+	| 'MODALITY_NOT_ALLOWED'
+	| 'RATE_LIMITED'
+	| 'UPSTREAM_BUSY'
+	| 'UPSTREAM_ERROR'
+	| 'INTERNAL';
+
+/** The HTTP status each code is sent with. */
+export const GATEWAY_ERROR_STATUS: Readonly<Record<GatewayErrorCode, number>> = {
+	BAD_REQUEST: 400,
+	AUTH_INVALID: 401,
+	NOT_ENTITLED: 403,
+	USER_BLOCKED: 403,
+	APP_UNKNOWN: 404,
+	ENDPOINT_RETIRED: 410,
+	PAYLOAD_TOO_LARGE: 413,
+	MODALITY_NOT_ALLOWED: 415,
+	RATE_LIMITED: 429,
+	UPSTREAM_BUSY: 429,
+	UPSTREAM_ERROR: 500,
+	INTERNAL: 500,
+};
+
+/** The error body. `message` is safe to log; it never carries upstream detail. */
+export interface GatewayErrorBody {
+	error: {
+		code: GatewayErrorCode;
+		message: string;
+		retryAfterSeconds?: number;
+	};
+}
+
+/** The quota headers, by name. A rename here breaks both sides' compile. */
+export const QUOTA_HEADERS = {
+	minuteRemaining: 'X-Quota-Minute-Remaining',
+	dayRemaining: 'X-Quota-Day-Remaining',
+	dayTokensRemaining: 'X-Quota-Day-Tokens-Remaining',
+} as const;
+
+/** The names field by field, so a side declaring its own literals is checked exactly. */
+export type QuotaHeaderNames = typeof QUOTA_HEADERS;
+export type QuotaHeaderName = QuotaHeaderNames[keyof QuotaHeaderNames];
+
+/** What is left of an app's allowance, as the gateway reports it. */
+export interface GatewayQuota {
+	minuteRemaining: number;
+	dayRemaining: number;
+	dayTokensRemaining: number;
+}
+
+/** What one answer cost. */
+export interface GatewayUsage {
+	promptTokens: number;
+	completionTokens: number;
+	totalTokens: number;
+}
+
+/** The `data:` payloads of a chat stream, before the `[DONE]` sentinel. */
+export type GatewayStreamEvent =
+	| { type: 'delta'; text: string }
+	| { type: 'done'; usage: GatewayUsage; quota?: GatewayQuota }
+	| { type: 'error'; code: GatewayErrorCode };
+
+/** The last `data:` line of a stream that completed. */
+export const SSE_DONE_SENTINEL = '[DONE]';
+export type SseDoneSentinel = typeof SSE_DONE_SENTINEL;
+
+/** The `Retry-After` header, which a 429 always carries. */
+export const RETRY_AFTER_HEADER = 'Retry-After';

package/src/core/aiClient.ts

@@ -11,9 +11,16 @@ import {
 	type AppBehaviorConfig,
 	type BehaviorState,
 } from '../config/behaviorConfig';
+import {
+	SSE_DONE_SENTINEL,
+	type GatewayQuota,
+	type GatewayStreamEvent,
+	type GatewayUsage,
+} from '../contract/gateway';
 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';
+import { requestSse, type SseResponseInfo, type StreamTransport } from '../transport/sseClient';
+import { createQuotaRequest, type RecoveryState } from './quotaRequest';
+import { DEFAULT_AI_TIMEOUTS, 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');
@@ -25,9 +32,21 @@ function report(operation: 'chat' | 'quota', error: AiError): void {
 	});
 }
 
+export interface AccessTokenRequestOptions {
+	/**
+	 * Skip the cached token and ask the provider for a new one. Set after a 401:
+	 * the cached token is valid by the clock and refused by the server, so asking
+	 * again without this re-sends the token that was just rejected (AI-01).
+	 */
+	forceRefresh?: boolean;
+}
+
 /** Minimal slice of the rn-auth `Auth` controller the client needs. */
 export interface TokenProvider {
-	requestAccessToken(resourceKey: string): Promise<{ status: string; token?: string }>;
+	requestAccessToken(
+		resourceKey: string,
+		options?: AccessTokenRequestOptions,
+	): Promise<{ status: string; token?: string; errorCode?: string }>;
 }
 
 export type ContentPart =
@@ -45,17 +64,11 @@ export interface ChatRequest {
 	options?: { temperature?: number; maxOutputTokens?: number };
 }
 
-export interface Usage {
-	promptTokens: number;
-	completionTokens: number;
-	totalTokens: number;
-}
+/** What one answer cost, as the gateway reports it. */
+export type Usage = GatewayUsage;
 
-export interface QuotaSnapshot {
-	minuteRemaining: number;
-	dayRemaining: number;
-	dayTokensRemaining: number;
-}
+/** What is left of the app's allowance. */
+export type QuotaSnapshot = GatewayQuota;
 
 export interface ChatStreamHandlers {
 	onDelta(text: string): void;
@@ -80,12 +93,18 @@ export interface AiClientConfig {
 	resourceKey?: string;
 	storage?: AiConfigCache;
 	fetchFn?: typeof fetch;
-	/** Test seam for the SSE transport. */
-	transport?: typeof requestSse;
+	/** The streaming transport. Injected in tests, or to replace the XHR reader. */
+	transport?: StreamTransport;
 	/** 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;
+	/**
+	 * Hosts the remote config's `api.baseUrl` may name. A config document decides
+	 * where this client sends its bearer token, so an app with a fixed deployment
+	 * can pin it (AI-07).
+	 */
+	allowedHosts?: readonly string[];
 }
 
 /** Ceiling on one remote-configured backoff step, so a bad document cannot stall a chat. */
@@ -100,27 +119,41 @@ function backoffBefore(steps: readonly number[], index: number): number {
 export interface AiClient {
 	chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle;
 	getQuota(): Promise<QuotaSnapshot>;
+	/**
+	 * The last quota this client saw, from a chat's `done` event or `getQuota`.
+	 * Optional so an app's own `AiClient` keeps compiling.
+	 */
+	lastQuota?(): QuotaSnapshot | undefined;
 	/** 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.
+	 * Called whenever the behavior state or the last quota changes (AI-09, AI-13);
+	 * returns the unsubscribe. Optional so an app's own `AiClient` keeps compiling.
 	 */
 	subscribe?(listener: () => void): () => void;
 	reloadConfig(): Promise<void>;
 }
 
-interface StreamEvent {
-	type?: string;
-	text?: string;
-	usage?: Usage;
-	quota?: QuotaSnapshot;
-	code?: string;
+/** A quota from the wire, or nothing: a malformed one is not displayed (AI-13). */
+function asQuota(value: unknown): QuotaSnapshot | undefined {
+	if (typeof value !== 'object' || value === null) {
+		return undefined;
+	}
+	const candidate = value as Partial<QuotaSnapshot>;
+	const fields = [candidate.minuteRemaining, candidate.dayRemaining, candidate.dayTokensRemaining];
+	if (!fields.every(field => typeof field === 'number' && Number.isFinite(field))) {
+		return undefined;
+	}
+	return {
+		minuteRemaining: candidate.minuteRemaining!,
+		dayRemaining: candidate.dayRemaining!,
+		dayTokensRemaining: candidate.dayTokensRemaining!,
+	};
 }
 
 export function createAiClient(clientConfig: AiClientConfig): AiClient {
 	const resourceKey = clientConfig.resourceKey ?? 'ai-gateway';
-	const transport = clientConfig.transport ?? requestSse;
+	const transport: StreamTransport = clientConfig.transport ?? requestSse;
 	const fetchFn = clientConfig.fetchFn ?? fetch;
 	const timeouts: AiTimeouts = { ...DEFAULT_AI_TIMEOUTS, ...clientConfig.timeouts };
 	const scheduler = clientConfig.scheduler ?? realScheduler;
@@ -130,10 +163,12 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 		cache: clientConfig.storage,
 		fetchFn: clientConfig.fetchFn,
 		timeoutMs: timeouts.configMs,
+		...(clientConfig.allowedHosts ? { allowedHosts: clientConfig.allowedHosts } : {}),
 	});
 	let lastConfig: AppBehaviorConfig | undefined;
 	const behaviorListeners = createListenerSet<[]>();
 	let snapshot: AiBehaviorState | undefined;
+	let quota: QuotaSnapshot | undefined;
 
 	/** Rebuilt only when a field changes, so useSyncExternalStore sees a stable object. */
 	function behaviorState(): AiBehaviorState {
@@ -151,7 +186,19 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 		if (next.features.aiEnabled !== wasEnabled) behaviorListeners.notify();
 	}
 
-	async function acquire(): Promise<{ config: AppBehaviorConfig; token: string }> {
+	/** One place records the quota, whichever call learned it (AI-13). */
+	function setQuota(next: QuotaSnapshot | undefined): void {
+		if (!next || (quota && shallowSameQuota(quota, next))) {
+			return;
+		}
+		quota = next;
+		behaviorListeners.notify();
+	}
+
+	async function acquire(options: { forceRefresh?: boolean } = {}): Promise<{
+		config: AppBehaviorConfig;
+		token: string;
+	}> {
 		const config = await configManager.getConfig();
 		setLastConfig(config);
 		if (!config.features.aiEnabled) {
@@ -159,20 +206,24 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 				recoverable: false,
 			});
 		}
-		const tokenResult = await clientConfig.auth.requestAccessToken(resourceKey);
+		const tokenResult = await clientConfig.auth.requestAccessToken(resourceKey, {
+			forceRefresh: options.forceRefresh === true,
+		});
 		if (tokenResult.status !== 'success' || !tokenResult.token) {
-			throw new AiError('auth-invalid', 'could not acquire an access token');
+			// What the auth layer called it, kept as the cause: a screen has to tell
+			// "sign in again" from "you are offline" (AI-11).
+			throw tokenError(tokenResult.status, tokenResult.errorCode);
 		}
 		return { config, token: tokenResult.token };
 	}
 
-	const chatUrl = (config: AppBehaviorConfig) =>
-		`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/chat`;
+	const endpoint = (config: AppBehaviorConfig, path: 'chat' | 'quota') =>
+		`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/${path}`;
 
 	function chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle {
 		let cancelled = false;
 		let settled = false;
-		let inner: SseHandle | undefined;
+		let inner: { cancel(): void } | undefined;
 
 		// Every callback to the app goes through here. Nothing is delivered after
 		// cancel() — an acquire() or config reload that failed after the user
@@ -185,6 +236,7 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 			done(result: { usage: Usage; quota?: QuotaSnapshot }) {
 				if (cancelled || settled) return;
 				settled = true;
+				setQuota(result.quota);
 				handlers.onDone(result);
 			},
 			error(error: AiError) {
@@ -215,15 +267,15 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 				}
 			};
 
-		const attempt = async (state: { configReloads: number; authRetries: number }) => {
-			const { config, token } = await acquire();
+		const attempt = async (state: RecoveryState) => {
+			const { config, token } = await acquire({ forceRefresh: state.authRetries > 0 });
 			if (cancelled) return;
 
 			let done: { usage: Usage; quota?: QuotaSnapshot } | undefined;
 			let streamErrorCode: string | undefined;
 			inner = transport(
 				{
-					url: chatUrl(config),
+					url: endpoint(config, 'chat'),
 					method: 'POST',
 					headers: {
 						Authorization: `Bearer ${token}`,
@@ -235,65 +287,48 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 				},
 				{
 					onData: guarded(payload => {
-						if (payload === '[DONE]') return;
-						let event: StreamEvent;
+						if (payload === SSE_DONE_SENTINEL) return;
+						let event: Partial<GatewayStreamEvent>;
 						try {
-							event = JSON.parse(payload) as StreamEvent;
+							event = JSON.parse(payload) as Partial<GatewayStreamEvent>;
 						} 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 };
+							done = { usage: event.usage, quota: asQuota(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'));
+							emit.error(
+								new AiError('upstream-error', 'the AI service failed mid-response', {
+									cause: streamErrorCode,
+								}),
+							);
 						} else if (done) {
 							emit.done(done);
 						} else {
-							emit.error(new AiError('internal', 'stream ended without completion'));
+							// Headers said 200 and the body stopped short: the connection
+							// dropped mid-answer, which is a network failure, not a fault
+							// of the service.
+							emit.error(new AiError('network', 'the stream ended before it completed'));
 						}
 					}),
-					onError: guarded((status, bodyText) => {
+					onError: guarded((status: number, bodyText: string, response?: SseResponseInfo) => {
 						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));
+						recover(
+							status,
+							bodyText,
+							state,
+							{ ...(response ? { getHeader: name => response.getHeader(name) } : {}) },
+							next => attempt(next).catch(fail),
+							fail,
+							emit.error,
+						);
 					}),
 				},
 			);
@@ -308,36 +343,66 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 		};
 	}
 
-	async function getQuota(): Promise<QuotaSnapshot> {
-		try {
-			return await fetchQuota();
-		} catch (error) {
-			if (error instanceof AiError) report('quota', error);
-			throw error;
+	/**
+	 * The two recoveries the contract promises, in one place so chat and quota
+	 * cannot drift (AI-13): a designated status reloads the configuration and
+	 * retries after the configured backoff, and a 401 retries once with a token
+	 * the provider had to fetch again.
+	 */
+	function recover(
+		status: number,
+		bodyText: string,
+		state: RecoveryState,
+		context: { getHeader?: (name: string) => string | null },
+		retry: (next: RecoveryState) => void,
+		onFailure: (error: unknown) => void,
+		onGiveUp: (error: AiError) => void,
+	): void {
+		const config = lastConfig;
+		if (
+			config &&
+			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(
+				reloaded => {
+					setLastConfig(reloaded);
+					scheduler.setTimeout(
+						() => retry({ ...state, configReloads: state.configReloads + 1 }),
+						retryAfter,
+					);
+				},
+				e => onFailure(e instanceof AiError ? e : new AiError('config-unavailable', String(e))),
+			);
+			return;
 		}
+		// Expired server-side session → one retry with a token the provider
+		// actually re-fetched.
+		if (status === 401 && state.authRetries < 1) {
+			retry({ ...state, authRetries: state.authRetries + 1 });
+			return;
+		}
+		onGiveUp(errorFromHttp(status, bodyText, context));
 	}
 
-	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 }),
-		);
-	}
+	const { getQuota } = createQuotaRequest({
+		fetchFn,
+		timeouts,
+		acquire,
+		endpoint,
+		asQuota,
+		recover,
+		report: error => report('quota', error),
+		setQuota,
+	});
 
 	return {
 		chat,
 		getQuota,
+		lastQuota: () => quota,
 		getBehaviorState: () => behaviorState(),
 		subscribe: listener => {
 			const fromManager = configManager.subscribe(listener);
@@ -352,3 +417,36 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 		},
 	};
 }
+
+function shallowSameQuota(a: QuotaSnapshot, b: QuotaSnapshot): boolean {
+	return (
+		a.minuteRemaining === b.minuteRemaining &&
+		a.dayRemaining === b.dayRemaining &&
+		a.dayTokensRemaining === b.dayTokensRemaining
+	);
+}
+
+/**
+ * What the auth layer's refusal means for a chat. The code rn-auth gave is kept
+ * as the cause, and it decides the copy: "sign in again" and "you are offline"
+ * are different answers, and both used to arrive as `auth-invalid` (AI-11).
+ */
+function tokenError(status: string, errorCode?: string): AiError {
+	const cause = errorCode ? { cause: errorCode } : {};
+	switch (errorCode) {
+		case 'session-expired':
+			return new AiError('session-expired', 'the session ended; sign in again', cause);
+		case 'network-unavailable':
+			return new AiError('network', 'no connection to the identity provider', cause);
+		case 'consent-denied':
+			return new AiError('not-entitled', 'access to the AI resource was denied', cause);
+		default:
+			return new AiError(
+				'auth-invalid',
+				status === 'denied'
+					? 'access to the AI resource was refused'
+					: 'could not acquire an access token',
+				cause,
+			);
+	}
+}

package/src/core/quotaRequest.ts

@@ -0,0 +1,125 @@
+/**
+ * The quota request, and the recovery it shares with a chat (AI-13).
+ *
+ * `getQuota` used to be the one call with no recovery at all: a gateway that
+ * had moved answered 404 for quota while chats silently re-routed, so the
+ * figure on screen failed while the feature worked. It now goes through the
+ * same `recover` the chat stream does — a designated status reloads the
+ * configuration and retries, a 401 retries once with a token the provider had
+ * to fetch again.
+ */
+import type { AppBehaviorConfig } from '../config/behaviorConfig';
+import { AiError } from '../diagnostics/errors';
+import { withTimeout, type AiTimeouts } from '../transport/timeouts';
+
+/** Where the quota request is in its recovery, shared with the chat path. */
+export interface RecoveryState {
+	configReloads: number;
+	authRetries: number;
+}
+
+export interface QuotaRequestDeps {
+	fetchFn: typeof fetch;
+	timeouts: AiTimeouts;
+	acquire: (options?: { forceRefresh?: boolean }) => Promise<{
+		config: AppBehaviorConfig;
+		token: string;
+	}>;
+	endpoint: (config: AppBehaviorConfig, path: 'chat' | 'quota') => string;
+	asQuota: (value: unknown) => QuotaSnapshot | undefined;
+	recover: (
+		status: number,
+		bodyText: string,
+		state: RecoveryState,
+		context: { getHeader?: (name: string) => string | null },
+		retry: (next: RecoveryState) => void,
+		onFailure: (error: unknown) => void,
+		onGiveUp: (error: AiError) => void,
+	) => void;
+	report: (error: AiError) => void;
+	setQuota: (next: QuotaSnapshot | undefined) => void;
+}
+
+/** What is left of the app's allowance. */
+export type QuotaSnapshot = {
+	minuteRemaining: number;
+	dayRemaining: number;
+	dayTokensRemaining: number;
+};
+
+export function createQuotaRequest(deps: QuotaRequestDeps) {
+	const { fetchFn, timeouts, endpoint, asQuota, recover, setQuota } = deps;
+	const acquire = deps.acquire;
+
+	async function getQuota(): Promise<QuotaSnapshot> {
+		try {
+			const snapshotValue = await fetchQuotaWithRecovery({ configReloads: 0, authRetries: 0 });
+			setQuota(snapshotValue);
+			return snapshotValue;
+		} catch (error) {
+			if (error instanceof AiError) deps.report(error);
+			throw error;
+		}
+	}
+
+	/** Same recovery as a chat: a retired endpoint reloads the config and retries. */
+	function fetchQuotaWithRecovery(state: RecoveryState): Promise<QuotaSnapshot> {
+		return new Promise<QuotaSnapshot>((resolve, reject) => {
+			fetchQuota(state).then(resolve, error => {
+				if (!(error instanceof HttpFailure)) {
+					reject(error);
+					return;
+				}
+				recover(
+					error.status,
+					error.bodyText,
+					state,
+					{ getHeader: name => error.getHeader(name) },
+					next => fetchQuotaWithRecovery(next).then(resolve, reject),
+					reject,
+					reject,
+				);
+			});
+		});
+	}
+
+	/** Carries the response so `recover` can decide; never reaches the caller. */
+	class HttpFailure extends Error {
+		constructor(
+			readonly status: number,
+			readonly bodyText: string,
+			private readonly headers?: Headers,
+		) {
+			super(`gateway responded ${status}`);
+			this.name = 'HttpFailure';
+		}
+		getHeader(name: string): string | null {
+			return this.headers?.get(name) ?? null;
+		}
+	}
+
+	async function fetchQuota(state: RecoveryState): Promise<QuotaSnapshot> {
+		const { config, token } = await acquire({ forceRefresh: state.authRetries > 0 });
+		return withTimeout(
+			timeouts.quotaMs,
+			async signal => {
+				const response = await fetchFn(endpoint(config, 'quota'), {
+					headers: { Authorization: `Bearer ${token}` },
+					signal,
+				});
+				if (!response.ok) {
+					throw new HttpFailure(response.status, await response.text(), response.headers);
+				}
+				const parsed = asQuota(await response.json());
+				if (!parsed) {
+					// A body that is not the contract's: better no figure than a wrong one.
+					throw new AiError('internal', 'quota response did not match the contract');
+				}
+				return parsed;
+			},
+			() => new AiError('network', 'quota request timed out'),
+		);
+	}
+
+	return { getQuota };
+}