@rebilly/api 0.0.0 → 0.1.1

package/dist/core.d.ts

@@ -0,0 +1,5 @@
+export { createCoreClient, type CoreClient, type CoreClientOptions, } from './create-core-client.ts';
+export { apiServerUrl, type ClientOptions } from './api-client-options.ts';
+export * from './runtime/factory.ts';
+export type * from './core-client.ts';
+export { OPERATIONS } from './core-client.ts';

package/dist/core.js

@@ -0,0 +1,7 @@
+import { ApiError, TimeoutError } from "./runtime/errors.js";
+import { defaultRetryOn } from "./runtime/retry.js";
+import { createClient } from "./runtime/factory.js";
+import { OPERATIONS } from "./core-client.js";
+import { apiServerUrl } from "./api-client-options.js";
+import { createCoreClient } from "./create-core-client.js";
+export { ApiError, OPERATIONS, TimeoutError, apiServerUrl, createClient, createCoreClient, defaultRetryOn };

package/dist/create-core-client.d.ts

@@ -0,0 +1,8 @@
+import { createClient, Ops, OperationId, OperationPath, OperationTag } from './core-client.ts';
+import { ClientOptions } from './api-client-options.ts';
+import { OperationContext } from './runtime/types.ts';
+export type CoreClient = ReturnType<typeof createClient<Ops, OperationId, OperationPath, OperationTag>>;
+export type CoreClientOptions = ClientOptions<OperationContext<OperationId, OperationPath, OperationTag>> & {
+    apiKey?: string;
+};
+export declare function createCoreClient({ apiKey, ...options }: CoreClientOptions): CoreClient;

package/dist/create-core-client.js

@@ -0,0 +1,9 @@
+import { createClient } from "./runtime/factory.js";
+import { OPERATIONS } from "./core-client.js";
+import { clientConfig, secretKeyAuth } from "./api-client-options.js";
+//#region src/create-core-client.ts
+function createCoreClient({ apiKey, ...options }) {
+	return createClient(OPERATIONS, clientConfig(options, secretKeyAuth(apiKey)));
+}
+//#endregion
+export { createCoreClient };

package/dist/create-storefront-client.d.ts

@@ -0,0 +1,6 @@
+import { createClient, Ops, OperationId, OperationPath, OperationTag } from './storefront-client.ts';
+import { ClientOptions, StorefrontCredentials } from './api-client-options.ts';
+import { OperationContext } from './runtime/types.ts';
+export type StorefrontClient = ReturnType<typeof createClient<Ops, OperationId, OperationPath, OperationTag>>;
+export type StorefrontClientOptions = StorefrontCredentials & ClientOptions<OperationContext<OperationId, OperationPath, OperationTag>>;
+export declare function createStorefrontClient({ publishableKey, jwt, ...options }: StorefrontClientOptions): StorefrontClient;

package/dist/create-storefront-client.js

@@ -0,0 +1,12 @@
+import { createClient } from "./runtime/factory.js";
+import { clientConfig, storefrontAuth } from "./api-client-options.js";
+import { OPERATIONS } from "./storefront-client.js";
+//#region src/create-storefront-client.ts
+function createStorefrontClient({ publishableKey, jwt, ...options }) {
+	return createClient(OPERATIONS, clientConfig(options, storefrontAuth({
+		publishableKey,
+		jwt
+	})));
+}
+//#endregion
+export { createStorefrontClient };

package/dist/runtime/auth.d.ts

@@ -0,0 +1,14 @@
+import { ClientConfig, SecuritySpec } from './types.ts';
+/**
+ * Build the auth headers/query for one operation's `security` OR-alternatives from the
+ * instance credentials (`config.auth`) — capability module, wired into `createClient`.
+ * The first alternative whose schemes (an AND-set) are all configured is applied, so
+ * "bearer OR apiKey" works with either credential and never sends both. When none is
+ * fully configured, the first alternative's configured schemes are still sent (the
+ * server rejects the request, mirroring the previous behavior).
+ * Cookie-borne apiKeys fold into a single `Cookie` header joined with `; `.
+ */
+export declare function resolveAuth(security: readonly (readonly SecuritySpec[])[], config: ClientConfig): Promise<{
+    headers: Record<string, string>;
+    query: Record<string, string>;
+}>;

package/dist/runtime/auth.js

@@ -0,0 +1,53 @@
+//#region src/runtime/auth.ts
+/** Resolve a credential: a literal passes through; a function is awaited per request. */
+async function resolveToken(provider) {
+	return typeof provider === "function" ? await provider() : provider;
+}
+/** UTF-8-safe base64: bare `btoa` throws on non-Latin-1 credentials (RFC 7617 allows UTF-8). */
+function encodeBase64(text) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+/** Whether a credential for this scheme is configured on the instance. */
+function isConfigured(scheme, config) {
+	if (scheme.kind === "apiKey") return config.auth?.apiKey?.[scheme.scheme] !== void 0;
+	if (scheme.kind === "bearer") return config.auth?.bearer !== void 0;
+	return config.auth?.basic !== void 0;
+}
+/**
+* Build the auth headers/query for one operation's `security` OR-alternatives from the
+* instance credentials (`config.auth`) — capability module, wired into `createClient`.
+* The first alternative whose schemes (an AND-set) are all configured is applied, so
+* "bearer OR apiKey" works with either credential and never sends both. When none is
+* fully configured, the first alternative's configured schemes are still sent (the
+* server rejects the request, mirroring the previous behavior).
+* Cookie-borne apiKeys fold into a single `Cookie` header joined with `; `.
+*/
+async function resolveAuth(security, config) {
+	const alternative = security.find((schemes) => schemes.every((scheme) => isConfigured(scheme, config))) ?? security[0] ?? [];
+	const headers = {};
+	const query = {};
+	const cookies = [];
+	for (const scheme of alternative) if (scheme.kind === "apiKey") {
+		const provider = config.auth?.apiKey?.[scheme.scheme];
+		if (provider === void 0) continue;
+		const value = await resolveToken(provider);
+		if (scheme.in === "header") headers[scheme.name] = value;
+		else if (scheme.in === "query") query[scheme.name] = value;
+		else cookies.push(`${scheme.name}=${encodeURIComponent(value)}`);
+	} else if (scheme.kind === "bearer") {
+		const provider = config.auth?.bearer;
+		if (provider !== void 0) headers.Authorization = `Bearer ${await resolveToken(provider)}`;
+	} else {
+		const basic = config.auth?.basic;
+		if (basic !== void 0) headers.Authorization = `Basic ${encodeBase64(`${basic.username}:${basic.password}`)}`;
+	}
+	if (cookies.length > 0) headers.Cookie = cookies.join("; ");
+	return {
+		headers,
+		query
+	};
+}
+//#endregion
+export { resolveAuth };

package/dist/runtime/create-client.d.ts

@@ -0,0 +1,50 @@
+import { SendCapabilities } from './send.ts';
+import { Client, ClientConfig, OperationContext, OperationDescriptor, OpsShape, PaginationSpec, QueryValue, RequestOptions, SecuritySpec, ServerSentEvent, SseOptions } from './types.ts';
+/**
+ * The optional behaviors `createClientCore` can dispatch to but never statically
+ * imports. The package's public `createClient` wires the full set; the future
+ * inline-mode assembler wires only the capabilities a spec needs.
+ */
+export type Capabilities = SendCapabilities & {
+    resolveAuth?: (security: readonly (readonly SecuritySpec[])[], config: ClientConfig) => Promise<{
+        headers: Record<string, string>;
+        query: Record<string, string>;
+    }>;
+    sse?: (config: ClientConfig, op: OperationContext, prepare: () => Promise<{
+        url: string;
+        init: SseOptions;
+    }>, dataKind: 'json' | 'text') => AsyncGenerator<ServerSentEvent<unknown>>;
+    paginate?: {
+        pages: (call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>, spec: PaginationSpec, args?: OperationArgs, init?: RequestOptions) => AsyncGenerator<unknown>;
+        items: (call: (args?: OperationArgs, init?: RequestOptions) => Promise<unknown>, spec: PaginationSpec, args?: OperationArgs, init?: RequestOptions) => AsyncGenerator<unknown>;
+        pagesByLink: (call: (args?: OperationArgs, init?: RequestOptions) => Promise<{
+            page: unknown;
+            linkHeader: string | null;
+            url: string;
+        }>, spec: PaginationSpec, args?: OperationArgs, init?: RequestOptions) => AsyncGenerator<unknown>;
+        itemsByLink: (call: (args?: OperationArgs, init?: RequestOptions) => Promise<{
+            page: unknown;
+            linkHeader: string | null;
+            url: string;
+        }>, spec: PaginationSpec, args?: OperationArgs, init?: RequestOptions) => AsyncGenerator<unknown>;
+    };
+};
+/**
+ * One call's inputs, namespaced by transport layer. `argsStyle: 'flat'` clients accept the
+ * merged form instead (every parameter and body property at one level) — `namespaceArgs`
+ * converts it to this shape before anything downstream reads it.
+ */
+export type OperationArgs = {
+    path?: Record<string, unknown>;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    headers?: Record<string, unknown>;
+    cookies?: Record<string, unknown>;
+} & Record<string, unknown>;
+/**
+ * Build a typed instance client over operation descriptors: one real bound method per
+ * operation (attached by a construction-time loop — no Proxy), plus the core members
+ * (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name
+ * collision with an operation. All behavior dispatches through the capability seam.
+ */
+export declare function createClientCore<Ops extends OpsShape, Id extends string = string, Path extends string = string, Tag extends string = string>(operations: Record<string, OperationDescriptor>, initial?: ClientConfig<OperationContext<Id, Path, Tag>>, caps?: Capabilities): Client<Ops, OperationContext<Id, Path, Tag>>;

package/dist/runtime/create-client.js

@@ -0,0 +1,345 @@
+import { ApiError } from "./errors.js";
+import { parse, readError } from "./parse.js";
+import { middlewareChain, send, toHeaderRecord } from "./send.js";
+import { buildUrl, substitutePath } from "./url.js";
+//#region src/runtime/create-client.ts
+/** The five layer keys, and the only top-level keys a namespaced call may carry. */
+var LAYERS = [
+	"path",
+	"query",
+	"body",
+	"headers",
+	"cookies"
+];
+/** Where a declared parameter's `in` value puts it. */
+var LAYER_OF = {
+	path: "path",
+	query: "query",
+	header: "headers",
+	cookie: "cookies"
+};
+/**
+* Merged (`argsStyle: 'flat'`) args → the namespaced shape. A key that names a declared
+* parameter goes to that parameter's layer; anything else is a property of the request
+* body, which is how a flat call spells an object body. `body` stays reserved for the
+* operations a flat call cannot merge (an array, a scalar, or a binary body).
+*/
+function namespaceArgs(op, args) {
+	const layers = {};
+	let body;
+	let properties;
+	const layerOfParam = new Map((op.params ?? []).map((param) => [param.name, param.in]));
+	for (const [key, value] of Object.entries(args)) {
+		const layer = LAYER_OF[layerOfParam.get(key) ?? ""];
+		if (layer !== void 0) (layers[layer] ??= {})[key] = value;
+		else if (key === "body" && op.body !== void 0) body = value;
+		else if (op.body !== void 0) (properties ??= {})[key] = value;
+		else throw new TypeError(`Unknown argument "${key}" for operation "${op.id}": it names no declared parameter, and the operation takes no request body.`);
+	}
+	const namespaced = {};
+	if (layers.path) namespaced.path = layers.path;
+	if (layers.query) namespaced.query = layers.query;
+	if (layers.headers) namespaced.headers = layers.headers;
+	if (layers.cookies) namespaced.cookies = layers.cookies;
+	if (properties !== void 0) namespaced.body = properties;
+	else if (body !== void 0) namespaced.body = body;
+	return namespaced;
+}
+/** The response reader implied by the descriptor (before any per-call `parseAs` override). */
+/**
+* The `Accept` header matching how the response will be read — a blob/text operation
+* must not ask for `application/json` (a content-negotiating server would 406 or
+* answer with a JSON error body instead of the payload). Caller `init.headers` and
+* `config.headers` still override.
+*/
+function acceptFor(kind) {
+	if (kind === "text") return "text/*";
+	if (kind === "blob" || kind === "arrayBuffer" || kind === "stream" || kind === "formData") return "*/*";
+	return "application/json";
+}
+function kindFor(op) {
+	if (op.responseKind === "void" || op.responseKind === "blob" || op.responseKind === "text") return op.responseKind;
+	return "auto";
+}
+/**
+* The call's inputs in namespaced form, converting first on a flat-style client. An
+* operation the generator marked `argsStyle: 'grouped'` is already namespaced — its names
+* could not be merged, so its input type never offered the flat shape.
+*/
+function inputOf(op, args, config) {
+	return config.argsStyle === "flat" && op.argsStyle !== "grouped" ? namespaceArgs(op, args) : args;
+}
+/** Route the namespaced args to the request pieces. */
+function splitArgs(op, args) {
+	for (const key of Object.keys(args)) if (!LAYERS.includes(key)) throw new TypeError(`Unknown argument "${key}" for operation "${op.id}". Inputs are grouped by layer: ${LAYERS.join(", ")}.`);
+	return {
+		path: args.path ?? {},
+		query: args.query,
+		body: args.body,
+		headers: args.headers,
+		cookies: args.cookies
+	};
+}
+/**
+* The query-serialization hints for the descriptor's query params. A spec is built only
+* when the param deviates from the OpenAPI defaults (`form` + `explode: true`, encoded),
+* and always fully resolved — so `explode: false` or `allowReserved` alone (no `style`)
+* are honored, and an omitted `explode` keeps the exploded default.
+*/
+function queryStyles(op) {
+	let styles;
+	for (const param of op.params ?? []) {
+		if (param.in !== "query") continue;
+		if (!(param.style !== void 0 && param.style !== "form" || param.explode === false || param.allowReserved === true)) continue;
+		styles ??= {};
+		styles[param.name] = {
+			style: param.style ?? "form",
+			explode: param.explode ?? true,
+			allowReserved: param.allowReserved
+		};
+	}
+	return styles;
+}
+/** Stringify caller-supplied extra headers, skipping empty entries. */
+function stringHeaders(headers) {
+	const out = {};
+	for (const [key, value] of Object.entries(headers ?? {})) if (value !== void 0 && value !== null) out[key] = String(value);
+	return out;
+}
+/** Build the request pieces an attempt needs: the final URL and the merged per-call init. */
+async function prepareRequest(config, op, args, init, caps) {
+	const { path, query, body, headers, cookies } = splitArgs(op, args);
+	const authed = op.security?.length && caps.resolveAuth ? await caps.resolveAuth(op.security, config) : {
+		headers: {},
+		query: {}
+	};
+	const cookiePairs = Object.entries(cookies ?? {}).filter(([, value]) => value !== void 0 && value !== null).map(([cookieName, value]) => `${cookieName}=${encodeURIComponent(String(value))}`);
+	if (cookiePairs.length > 0) authed.headers.Cookie = [authed.headers.Cookie, ...cookiePairs].filter(Boolean).join("; ");
+	const fullQuery = {
+		...query,
+		...authed.query
+	};
+	return {
+		url: buildUrl(config.serverUrl ?? "", substitutePath(op.path, path), Object.keys(fullQuery).length > 0 ? fullQuery : void 0, queryStyles(op)),
+		init: {
+			...init,
+			method: op.method.toUpperCase(),
+			headers: {
+				...authed.headers,
+				...stringHeaders(headers),
+				...toHeaderRecord(init.headers)
+			}
+		},
+		body
+	};
+}
+/** Coerce a single declared response header value; omit when absent or unparsable. */
+function coerceResponseHeader(raw, type) {
+	if (raw === null) return void 0;
+	if (type === "number") {
+		if (raw.trim() === "") return void 0;
+		const value = Number(raw);
+		return Number.isFinite(value) ? value : void 0;
+	}
+	if (type === "boolean") {
+		const value = raw.trim().toLowerCase();
+		if (value === "true") return true;
+		if (value === "false") return false;
+		return;
+	}
+	return raw;
+}
+/** Build the camelCase declared-header bag for a throw-mode envelope. */
+function readEnvelopeHeaders(response, specs) {
+	const headers = {};
+	for (const spec of specs ?? []) {
+		const value = coerceResponseHeader(response.headers.get(spec.name), spec.type);
+		if (value !== void 0) headers[spec.key] = value;
+	}
+	return headers;
+}
+/** One non-SSE call: send, then branch on the configured error mode. */
+async function execute(config, op, args, init, caps) {
+	const prepared = await prepareRequest(config, op, args, init, caps);
+	const opCtx = {
+		id: op.id,
+		path: op.path,
+		tags: [...op.tags ?? []]
+	};
+	const { parseAs, envelope, ...sendInit } = prepared.init;
+	const readKind = parseAs ?? kindFor(op);
+	const { response, context } = await send(config, opCtx, prepared.url, sendInit, prepared.body, op.body, caps, acceptFor(readKind));
+	if (config.errorMode === "result") {
+		if (!response.ok) return {
+			data: void 0,
+			error: await readError(response),
+			response
+		};
+		return {
+			data: await parse(response, readKind),
+			error: void 0,
+			response
+		};
+	}
+	if (!response.ok) {
+		let error = new ApiError(context.url, response.status, response.statusText, await readError(response));
+		for (const mw of middlewareChain(config)) if (mw.onError) error = await mw.onError(error, context);
+		throw error;
+	}
+	const data = await parse(response, readKind);
+	if (envelope === true) return {
+		data,
+		headers: readEnvelopeHeaders(response, op.responseHeaders),
+		response
+	};
+	return data;
+}
+/** The paginate capability, or a descriptive throw when a paginated op is iterated unwired. */
+function paginateCapability(caps, op) {
+	if (!caps.paginate) throw new Error(`Pagination capability not wired: cannot iterate operation "${op.id}"`);
+	return caps.paginate;
+}
+/**
+* The per-page call the iterators drive: the method itself in throw mode; in result
+* mode a wrapper that unwraps the `{ data, error, response }` envelope — the page
+* pointers are data-rooted — rethrowing a failed page as `ApiError` (iteration is
+* error-mode-agnostic; the throw-mode-only `onError` middleware hook is not invoked).
+*/
+function pageCall(method, config) {
+	const callWithoutEnvelope = (args, init) => {
+		if (!init || init.envelope === void 0) return method(args, init);
+		const { envelope: _envelope, ...pageInit } = init;
+		return method(args, pageInit);
+	};
+	if (config.errorMode !== "result") return callWithoutEnvelope;
+	return async (args, init) => {
+		const envelope = await callWithoutEnvelope(args, init);
+		if (!envelope.response.ok) {
+			const { response } = envelope;
+			throw new ApiError(response.url, response.status, response.statusText, envelope.error);
+		}
+		return envelope.data;
+	};
+}
+/**
+* The per-page call the `link`-style iterators drive: like `execute`, but returning the
+* parsed page together with the raw `Link` header and the page's own URL (for resolving
+* a relative `rel="next"` target). Error-mode-agnostic like all iteration: a failed
+* page throws `ApiError` even on result-mode clients.
+*/
+function linkPageCall(config, op, caps) {
+	return async (args = {}, init = {}) => {
+		const prepared = await prepareRequest(config, op, args, init, caps);
+		const { parseAs, envelope: _envelope, ...sendInit } = prepared.init;
+		const readKind = parseAs ?? kindFor(op);
+		const opCtx = {
+			id: op.id,
+			path: op.path,
+			tags: [...op.tags ?? []]
+		};
+		const { response } = await send(config, opCtx, prepared.url, sendInit, prepared.body, op.body, caps, acceptFor(readKind));
+		if (!response.ok) throw new ApiError(prepared.url, response.status, response.statusText, await readError(response));
+		return {
+			page: await parse(response, readKind),
+			linkHeader: response.headers.get("link"),
+			url: response.url === "" ? prepared.url : response.url
+		};
+	};
+}
+/**
+* Build a typed instance client over operation descriptors: one real bound method per
+* operation (attached by a construction-time loop — no Proxy), plus the core members
+* (`configure`/`use`/`auth`), which are assigned AFTER the loop so they win any name
+* collision with an operation. All behavior dispatches through the capability seam.
+*/
+function createClientCore(operations, initial = {}, caps = {}) {
+	const given = initial;
+	const config = {
+		...given,
+		middleware: [...given.middleware ?? []]
+	};
+	const client = {};
+	for (const [name, op] of Object.entries(operations)) if (op.responseKind === "sse") {
+		const method = (given = {}, init = {}) => {
+			const args = inputOf(op, given, config);
+			if (!caps.sse) throw new Error(`SSE capability not wired: cannot stream operation "${op.id}"`);
+			const stream = caps.sse;
+			return (async function* () {
+				const opCtx = {
+					id: op.id,
+					path: op.path,
+					tags: [...op.tags ?? []]
+				};
+				const prepare = async () => {
+					const prepared = await prepareRequest(config, op, args, init, caps);
+					return {
+						url: prepared.url,
+						init: prepared.init,
+						body: prepared.body
+					};
+				};
+				yield* stream(config, opCtx, prepare, op.sseDataKind ?? "text");
+			})();
+		};
+		Object.defineProperty(method, "name", { value: name });
+		Object.defineProperty(method, "operationId", { value: op.id });
+		client[name] = method;
+	} else {
+		const raw = (args = {}, init = {}) => execute(config, op, args, init, caps);
+		const method = (args = {}, init = {}) => raw(inputOf(op, args, config), init);
+		Object.defineProperty(method, "name", { value: name });
+		Object.defineProperty(method, "operationId", { value: op.id });
+		const spec = op.pagination;
+		client[name] = spec === void 0 ? method : spec.style === "link" || spec.style === "body-link" ? Object.assign(method, {
+			pages: (args, init) => paginateCapability(caps, op).pagesByLink(linkPageCall(config, op, caps), spec, inputOf(op, args ?? {}, config), init),
+			items: (args, init) => paginateCapability(caps, op).itemsByLink(linkPageCall(config, op, caps), spec, inputOf(op, args ?? {}, config), init)
+		}) : Object.assign(method, {
+			pages: (args, init) => paginateCapability(caps, op).pages(pageCall(raw, config), spec, inputOf(op, args ?? {}, config), init),
+			items: (args, init) => paginateCapability(caps, op).items(pageCall(raw, config), spec, inputOf(op, args ?? {}, config), init)
+		});
+	}
+	client.configure = (next) => {
+		const { errorMode: _fixedMode, argsStyle: _fixedStyle, auth, ...rest } = next;
+		Object.assign(config, rest);
+		if (auth) config.auth = {
+			...config.auth,
+			...auth,
+			...auth.apiKey ? { apiKey: {
+				...config.auth?.apiKey,
+				...auth.apiKey
+			} } : {}
+		};
+	};
+	client.use = (...middleware) => {
+		config.middleware = [...config.middleware ?? [], ...middleware];
+	};
+	client.auth = {
+		bearer(token) {
+			config.auth = {
+				...config.auth,
+				bearer: token
+			};
+		},
+		basic(username, password) {
+			config.auth = {
+				...config.auth,
+				basic: {
+					username,
+					password
+				}
+			};
+		},
+		apiKey(scheme, value) {
+			config.auth = {
+				...config.auth,
+				apiKey: {
+					...config.auth?.apiKey,
+					[scheme]: value
+				}
+			};
+		}
+	};
+	return client;
+}
+//#endregion
+export { createClientCore };

package/dist/runtime/errors.d.ts

@@ -0,0 +1,18 @@
+/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */
+export declare class ApiError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(url: string, status: number, statusText: string, body: unknown);
+}
+/** The error thrown when a request attempt exceeds the configured `timeout` — carries
+ * the context a log line needs (which operation, what budget, which attempt). */
+export declare class TimeoutError extends Error {
+    readonly operationId: string;
+    readonly timeout: number;
+    readonly attempt: number;
+    constructor(operationId: string, timeout: number, attempt: number);
+}
+/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */
+export declare function abortError(signal: AbortSignal): globalThis.Error;

package/dist/runtime/errors.js

@@ -0,0 +1,38 @@
+//#region src/runtime/errors.ts
+/** The error thrown (throw mode) for a non-2xx response, carrying the decoded error body. */
+var ApiError = class extends Error {
+	url;
+	status;
+	statusText;
+	body;
+	constructor(url, status, statusText, body) {
+		super(`Request failed with status ${status}`);
+		this.name = "ApiError";
+		this.url = url;
+		this.status = status;
+		this.statusText = statusText;
+		this.body = body;
+	}
+};
+/** The error thrown when a request attempt exceeds the configured `timeout` — carries
+* the context a log line needs (which operation, what budget, which attempt). */
+var TimeoutError = class extends Error {
+	operationId;
+	timeout;
+	attempt;
+	constructor(operationId, timeout, attempt) {
+		super(`Request "${operationId}" timed out after ${timeout} ms (attempt ${attempt})`);
+		this.name = "TimeoutError";
+		this.operationId = operationId;
+		this.timeout = timeout;
+		this.attempt = attempt;
+	}
+};
+/** The error to throw for an aborted request: the caller's abort reason when it is an Error. */
+function abortError(signal) {
+	const reason = signal.reason;
+	if (reason instanceof Error) return reason;
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+//#endregion
+export { ApiError, TimeoutError, abortError };

package/dist/runtime/factory.d.ts

@@ -0,0 +1,11 @@
+import { Client, ClientConfig, OperationContext, OperationDescriptor, OpsShape } from './types.ts';
+/**
+ * The client factory: `createClientCore` wired with the capabilities this API needs.
+ * Exported so apps can build additional instances (per-tenant, per-environment) over
+ * the same `OPERATIONS`/`Ops`. The trailing string params carry the wiring's literal
+ * unions (`OperationId`/`OperationPath`/`OperationTag`) into `ctx.operation`.
+ */
+export declare function createClient<Ops extends OpsShape, Id extends string = string, Path extends string = string, Tag extends string = string>(operations: Record<string, OperationDescriptor>, config?: ClientConfig<OperationContext<Id, Path, Tag>>): Client<Ops, OperationContext<Id, Path, Tag>>;
+export { ApiError, TimeoutError } from './errors.ts';
+export { defaultRetryOn } from './retry.ts';
+export type * from './types.ts';

package/dist/runtime/factory.js

@@ -0,0 +1,16 @@
+import { ApiError, TimeoutError } from "./errors.js";
+import { defaultRetryOn } from "./retry.js";
+import { createClientCore } from "./create-client.js";
+import { resolveAuth } from "./auth.js";
+//#region src/runtime/factory.ts
+/**
+* The client factory: `createClientCore` wired with the capabilities this API needs.
+* Exported so apps can build additional instances (per-tenant, per-environment) over
+* the same `OPERATIONS`/`Ops`. The trailing string params carry the wiring's literal
+* unions (`OperationId`/`OperationPath`/`OperationTag`) into `ctx.operation`.
+*/
+function createClient(operations, config) {
+	return createClientCore(operations, config, { resolveAuth });
+}
+//#endregion
+export { ApiError, TimeoutError, createClient, defaultRetryOn };

package/dist/runtime/parse.d.ts

@@ -0,0 +1,12 @@
+import { ParseAs } from './types.ts';
+/**
+ * Read the response body per `kind`. `'auto'` negotiates from the content type
+ * (JSON, then `text/*`, then Blob); `204` responses read nothing. A `'void'`
+ * operation (no declared 2xx content) still returns a JSON body the server
+ * actually sends: the static type stays `void`, but silently dropping real data
+ * behind a spec gap is the worse failure — consumers can reach it with a cast
+ * while the API description catches up.
+ */
+export declare function parse(response: Response, kind: ParseAs | 'void'): Promise<unknown>;
+/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */
+export declare function readError(response: Response): Promise<unknown>;

package/dist/runtime/parse.js

@@ -0,0 +1,41 @@
+//#region src/runtime/parse.ts
+/**
+* Read the response body per `kind`. `'auto'` negotiates from the content type
+* (JSON, then `text/*`, then Blob); `204` responses read nothing. A `'void'`
+* operation (no declared 2xx content) still returns a JSON body the server
+* actually sends: the static type stays `void`, but silently dropping real data
+* behind a spec gap is the worse failure — consumers can reach it with a cast
+* while the API description catches up.
+*/
+async function parse(response, kind) {
+	if (kind === "void") {
+		if (response.status === 204 || response.status === 205 || response.status === 304) return;
+		if (!(response.headers.get("content-type") ?? "").toLowerCase().includes("json")) return void 0;
+		const text = await response.text().catch(() => "");
+		if (text === "") return void 0;
+		try {
+			return JSON.parse(text);
+		} catch {
+			return;
+		}
+	}
+	if (response.status === 204) return void 0;
+	if (kind === "stream") return response.body;
+	if (kind === "blob") return response.blob();
+	if (kind === "arrayBuffer") return response.arrayBuffer();
+	if (kind === "formData") return response.formData();
+	if (kind === "text") return response.text();
+	if (kind === "json") return response.json();
+	const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+	if (contentType.includes("json")) return response.json();
+	if (contentType.startsWith("text/")) return response.text();
+	const blob = await response.blob();
+	return blob.size > 0 ? blob : void 0;
+}
+/** Best-effort decode of a non-2xx body (JSON when declared, else text; undefined on failure). */
+async function readError(response) {
+	if ((response.headers.get("content-type") ?? "").toLowerCase().includes("json")) return response.json().catch(() => void 0);
+	return response.text().catch(() => void 0);
+}
+//#endregion
+export { parse, readError };