@askrjs/fetch 0.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 Jeffrey Repanich
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

package/README.md

@@ -0,0 +1,167 @@
+# @askrjs/fetch
+
+Function-first HTTP contracts, typed clients, codecs, and middleware for Askr. The package is
+ESM-only, has no runtime dependencies, and works with the standard Fetch APIs in modern browsers
+and Node.js 20.19 or newer.
+
+## Install
+
+```sh
+npm install @askrjs/fetch
+```
+
+## Define and call an API
+
+```ts
+import { createClient, defineApi, get, json } from "@askrjs/fetch";
+
+const api = defineApi({
+  getUser: get("/users/{id}")
+    .params<{ id: string }>()
+    .query<{ include?: string[] }>({
+      include: { style: "form", explode: true },
+    })
+    .returns(200, json<{ id: string; name: string }>())
+    .errors({ 404: json<{ title: string }>() }),
+});
+
+const client = createClient(api, { baseUrl: "https://api.example.com" });
+const result = await client.getUser({
+  params: { id: "user-1" },
+  query: { include: ["teams", "roles"] },
+});
+
+if (result.ok) {
+  console.log(result.status, result.data.name);
+} else if (result.kind === "http") {
+  console.error(result.status, result.error);
+} else {
+  console.error(result.kind, result.error);
+}
+```
+
+Paths use OpenAPI-style `{name}` parameters. Colon parameters and wildcards are rejected. A path
+parameter declaration must exactly match the names in the path.
+
+Every call returns a discriminated result instead of throwing for request, transport, HTTP, or
+decode failures. Use `unwrap(result)` when exception-based control flow is more convenient.
+
+## Codecs and validation
+
+The built-in codecs are:
+
+- `json(schema?)`
+- `text()`
+- `urlEncoded()`
+- `multipart()`
+- `blob()`
+- `arrayBuffer()`
+- `stream()`
+- `empty()`
+- `content({ mediaType: codec })`
+
+A validator only needs a `safeParse(value)` method, so schema libraries with that contract can be
+used without an adapter. Validators run for request bodies, path parameters, query parameters,
+headers, and decoded response bodies. Successful validator transformations are used for
+serialization and returned data.
+
+```ts
+const positiveInteger = {
+  safeParse(value: unknown) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0
+      ? { success: true as const, data: parsed }
+      : { success: false as const, error: new TypeError("Expected a positive integer") };
+  },
+};
+
+const api = defineApi({
+  getJob: get("/jobs/{id}")
+    .params<{ id: number }>({ id: positiveInteger })
+    .returns(json<{ id: number }>()),
+});
+```
+
+Responses are decoded against the codec registered for the actual HTTP status and content type.
+Missing status codecs, incompatible media types, invalid payloads, and unexpected non-empty bodies
+for `empty()` produce a `decode` failure. `204`, `205`, and `HEAD` responses must use `empty()`.
+
+## Parameter serialization
+
+Descriptors support the OpenAPI serialization styles used by generated clients:
+
+- Path: `simple`, `label`, and `matrix`
+- Query: `form`, `spaceDelimited`, `pipeDelimited`, and `deepObject`
+- Header: `simple`
+
+Use a parameter specification to combine serialization metadata with validation:
+
+```ts
+get("/search")
+  .query<{ tags: string[]; filter: { state: string } }>({
+    tags: { style: "pipeDelimited", explode: false },
+    filter: { style: "deepObject", explode: true },
+  })
+  .returns(json());
+```
+
+## Middleware
+
+Import middleware from the dedicated subpath:
+
+```ts
+import { createClient } from "@askrjs/fetch";
+import { bearerAuth, logging, retry, telemetry } from "@askrjs/fetch/middleware";
+
+const client = createClient(api, {
+  baseUrl: "https://api.example.com",
+  middleware: [
+    bearerAuth({ token: () => session.accessToken }),
+    logging(),
+    telemetry(hooks),
+    retry({ attempts: 3 }),
+  ],
+});
+```
+
+Middleware runs outward in declaration order. The package includes bearer and API-key auth,
+idempotent-method retries, redacted structured logging, and telemetry hooks. Logging redacts common
+credential names as well as arbitrary header or query names added by `apiKeyAuth()`.
+
+Retries default to `GET`, `HEAD`, `PUT`, `DELETE`, and `OPTIONS`, and to statuses `408`, `425`,
+`429`, `500`, `502`, `503`, and `504`. `Retry-After` is honored when present. Requests with bodies
+are not retried automatically.
+
+## Cancellation and timeouts
+
+Set a default timeout on the client or override it for one call. A caller `AbortSignal` is composed
+with the timeout signal. Timeouts return `kind: "timeout"`; caller cancellation returns
+`kind: "abort"`.
+
+```ts
+const controller = new AbortController();
+const pending = client.getUser({
+  params: { id: "user-1" },
+  signal: controller.signal,
+  timeout: 5_000,
+});
+
+controller.abort();
+const result = await pending;
+```
+
+## Lower-level requests
+
+`createFetch(options)` exposes the same result, codec, middleware, timeout, and cancellation
+contracts without an API descriptor. Supply either an absolute URL or a `baseUrl` plus a rooted
+path.
+
+```ts
+import { createFetch, json } from "@askrjs/fetch";
+
+const execute = createFetch({ baseUrl: "https://api.example.com" });
+const result = await execute({
+  url: "/health",
+  response: json<{ status: "ok" }>(),
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import { AnyEndpointDescriptor, ApiDefinition, ClientOptions, Codec, EndpointDescriptor, FailureResult, FetchResult, HttpResult, InferCodec, ParameterMap, SuccessResult } from "./types.js";
+//#region src/client.d.ts
+interface AdHocCall {
+  url: string;
+  method?: string;
+  headers?: HeadersInit;
+  query?: Record<string, unknown>;
+  querySpec?: ParameterMap;
+  body?: unknown;
+  bodyCodec?: Codec;
+  response?: Codec;
+  responses?: Readonly<Record<number, Codec>>;
+  errors?: Partial<Record<number | "default", Codec>>;
+  signal?: AbortSignal;
+  timeout?: number;
+  endpoint?: EndpointDescriptor;
+  operationId?: string;
+}
+declare function createFetch(options?: ClientOptions): (call: AdHocCall) => Promise<FetchResult>;
+type InputParts<D> = D extends EndpointDescriptor<infer P, infer Q, infer H, infer B, any, any> ? {
+  params: P;
+  query: Q;
+  headers: H;
+  body: B;
+} : never;
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K; }[keyof T];
+type Container<K extends string, T, Always extends boolean = false> = [T] extends [undefined] ? {} : Always extends true ? { [P in K]: T; } : RequiredKeys<T> extends never ? { [P in K]?: T; } : { [P in K]: T; };
+type EndpointInput<D extends AnyEndpointDescriptor> = Container<"params", InputParts<D>["params"], true> & Container<"query", InputParts<D>["query"]> & Container<"headers", InputParts<D>["headers"]> & Container<"body", InputParts<D>["body"], true> & {
+  signal?: AbortSignal;
+  timeout?: number;
+};
+type Successes<D> = D extends EndpointDescriptor<any, any, any, any, infer R, any> ? { [S in keyof R & number]: SuccessResult<InferCodec<R[S]>, S>; }[keyof R & number] : never;
+type Errors<D> = D extends EndpointDescriptor<any, any, any, any, any, infer E> ? { [S in Exclude<keyof E, "default"> & number]: HttpResult<InferCodec<NonNullable<E[S]>>, S>; }[Exclude<keyof E, "default"> & number] | ("default" extends keyof E ? HttpResult<InferCodec<NonNullable<E["default"]>>, number> : never) : never;
+type ClientResult<D extends AnyEndpointDescriptor> = Successes<D> | Errors<D> | FailureResult;
+type ClientMethod<D extends AnyEndpointDescriptor> = RequiredKeys<EndpointInput<D>> extends never ? (input?: EndpointInput<D>) => Promise<ClientResult<D>> : (input: EndpointInput<D>) => Promise<ClientResult<D>>;
+type ApiClient<A extends ApiDefinition> = Readonly<{ [K in keyof A["endpoints"]]: ClientMethod<A["endpoints"][K]>; }>;
+declare function createClient<A extends ApiDefinition>(api: A, options?: ClientOptions): ApiClient<A>;
+declare class FetchError extends Error {
+  readonly result: Exclude<FetchResult, {
+    ok: true;
+  }>;
+  constructor(result: Exclude<FetchResult, {
+    ok: true;
+  }>);
+}
+declare function unwrap<T>(result: FetchResult<T>): T;
+//#endregion
+export { AdHocCall, ApiClient, ClientResult, FetchError, createClient, createFetch, unwrap };

package/dist/client.js

@@ -0,0 +1,299 @@
+//#region src/client.ts
+const media = (response) => response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? null;
+const compatible = (codec, type) => codec.kind === "empty" || codec.kind === "blob" || codec.kind === "arrayBuffer" || codec.kind === "stream" || !!type && codec.mediaTypes.some((expected) => expected === "*/*" || expected === type || expected === "text/*" && type.startsWith("text/") || expected === "+json" && type.endsWith("+json"));
+async function decode(response, codec) {
+	const type = media(response);
+	const selected = codec.kind === "content" ? codec.variants?.[type ?? ""] : codec;
+	if (!selected || !compatible(selected, type)) throw new TypeError(`Cannot decode ${type ?? "missing content type"} as ${codec.mediaTypes.join(", ") || "empty"}`);
+	let value;
+	switch (selected.kind) {
+		case "empty":
+			if ((await response.clone().arrayBuffer()).byteLength) throw new TypeError("Expected an empty response body");
+			return;
+		case "json":
+			value = await response.json();
+			break;
+		case "text":
+			value = await response.text();
+			break;
+		case "urlEncoded":
+			value = new URLSearchParams(await response.text());
+			break;
+		case "multipart":
+			value = await response.formData();
+			break;
+		case "blob":
+			value = await response.blob();
+			break;
+		case "arrayBuffer":
+			value = await response.arrayBuffer();
+			break;
+		case "stream": return response.body;
+		default: throw new TypeError("Invalid codec");
+	}
+	if (selected.validator) {
+		const parsed = selected.validator.safeParse(value);
+		if (!parsed.success) throw parsed.error;
+		return parsed.data;
+	}
+	return value;
+}
+function encode(value, codec, headers) {
+	if (codec.validator) {
+		const parsed = codec.validator.safeParse(value);
+		if (!parsed.success) throw parsed.error;
+		value = parsed.data;
+	}
+	switch (codec.kind) {
+		case "empty": return;
+		case "json":
+			headers.set("content-type", "application/json");
+			return JSON.stringify(value);
+		case "text":
+			headers.set("content-type", "text/plain;charset=UTF-8");
+			return String(value);
+		case "urlEncoded":
+			headers.set("content-type", "application/x-www-form-urlencoded;charset=UTF-8");
+			return value;
+		case "multipart": return value;
+		case "blob":
+		case "arrayBuffer":
+		case "stream": return value;
+		case "content": {
+			const [type, selected] = Object.entries(codec.variants ?? {})[0] ?? [];
+			if (!selected) throw new TypeError("content() has no variants");
+			const body = encode(value, selected, headers);
+			if (selected.kind !== "multipart") headers.set("content-type", type);
+			return body;
+		}
+	}
+}
+const failure = (kind, error, url, response) => ({
+	ok: false,
+	kind,
+	status: response?.status ?? 0,
+	error,
+	headers: response?.headers ?? new Headers(),
+	url,
+	...response ? { response } : {}
+});
+const entries = (value) => value && typeof value === "object" && !Array.isArray(value) ? Object.entries(value) : [];
+const values = (value) => Array.isArray(value) ? value : [value];
+const encoded = (value) => encodeURIComponent(String(value));
+function pathParameter(name, value, spec = {}) {
+	const style = spec.style ?? "simple";
+	const explode = spec.explode ?? false;
+	const object = entries(value);
+	const array = Array.isArray(value);
+	if (style === "label") return `.${(object.length ? object.flatMap(([k, v]) => explode ? [`${encoded(k)}=${encoded(v)}`] : [encoded(k), encoded(v)]) : values(value).map(encoded)).join(explode ? "." : ",")}`;
+	if (style === "matrix") {
+		if (object.length) return explode ? object.map(([k, v]) => `;${encoded(k)}=${encoded(v)}`).join("") : `;${encoded(name)}=${object.flatMap(([k, v]) => [encoded(k), encoded(v)]).join(",")}`;
+		if (array && explode) return values(value).map((v) => `;${encoded(name)}=${encoded(v)}`).join("");
+		return `;${encoded(name)}=${values(value).map(encoded).join(",")}`;
+	}
+	if (style !== "simple") throw new TypeError(`Unsupported path parameter style: ${style}`);
+	if (object.length) return object.flatMap(([k, v]) => explode ? [`${encoded(k)}=${encoded(v)}`] : [encoded(k), encoded(v)]).join(",");
+	return values(value).map(encoded).join(",");
+}
+function queryParameter(output, name, value, spec = {}) {
+	const style = spec.style ?? "form";
+	const explode = spec.explode ?? true;
+	const object = entries(value);
+	const array = Array.isArray(value);
+	const append = (key, item) => output.append(key, String(item));
+	if (style === "deepObject") {
+		if (!object.length) throw new TypeError(`deepObject query parameter ${name} must be an object`);
+		for (const [key, item] of object) append(`${name}[${key}]`, item);
+		return;
+	}
+	if (style === "spaceDelimited" || style === "pipeDelimited") {
+		if (!array) throw new TypeError(`${style} query parameter ${name} must be an array`);
+		append(name, values(value).join(style === "spaceDelimited" ? " " : "|"));
+		return;
+	}
+	if (style !== "form") throw new TypeError(`Unsupported query parameter style: ${style}`);
+	if (object.length) {
+		if (explode) for (const [key, item] of object) append(key, item);
+		else append(name, object.flatMap(([key, item]) => [key, item]).join(","));
+		return;
+	}
+	if (array && explode) for (const item of values(value)) append(name, item);
+	else append(name, values(value).join(","));
+}
+function headerParameter(value, spec = {}) {
+	if ((spec.style ?? "simple") !== "simple") throw new TypeError(`Unsupported header parameter style: ${spec.style}`);
+	const object = entries(value);
+	if (object.length) return object.flatMap(([key, item]) => spec.explode ? [`${key}=${String(item)}`] : [key, item]).join(",");
+	return values(value).join(",");
+}
+const parameterSpec = (map, name) => {
+	const value = map?.[name];
+	return value && typeof value === "object" && !("safeParse" in value) ? value : {};
+};
+const parameterValue = (map, name, value) => {
+	const definition = map?.[name];
+	const validator = definition && typeof definition === "object" && "safeParse" in definition ? definition : definition?.validator;
+	if (!validator) return value;
+	const parsed = validator.safeParse(value);
+	if (!parsed.success) throw parsed.error;
+	return parsed.data;
+};
+function createFetch(options = {}) {
+	return async (call) => {
+		let url = `${options.baseUrl?.replace(/\/$/, "") ?? ""}${call.url}`;
+		const headers = new Headers(options.headers);
+		new Headers(call.headers).forEach((v, k) => headers.set(k, v));
+		try {
+			if (call.query) {
+				const query = new URLSearchParams();
+				for (const [key, value] of Object.entries(call.query)) if (value !== void 0) queryParameter(query, key, parameterValue(call.querySpec, key, value), parameterSpec(call.querySpec, key));
+				const rendered = query.toString();
+				if (rendered) url += `${url.includes("?") ? "&" : "?"}${rendered}`;
+			}
+		} catch (error) {
+			return failure("request", error, url);
+		}
+		let body;
+		try {
+			if (call.bodyCodec) body = encode(call.body, call.bodyCodec, headers);
+		} catch (error) {
+			return failure("request", error, url);
+		}
+		const timeout = call.timeout ?? options.timeout;
+		const controller = new AbortController();
+		let timedOut = false;
+		let timer;
+		const abort = () => controller.abort(call.signal?.reason);
+		call.signal?.addEventListener("abort", abort, { once: true });
+		if (call.signal?.aborted) abort();
+		if (timeout !== void 0) timer = setTimeout(() => {
+			timedOut = true;
+			controller.abort(new DOMException("Timed out", "TimeoutError"));
+		}, timeout);
+		const cleanup = () => {
+			if (timer) clearTimeout(timer);
+			call.signal?.removeEventListener("abort", abort);
+		};
+		if (controller.signal.aborted) {
+			cleanup();
+			return failure("abort", controller.signal.reason, url);
+		}
+		let request;
+		try {
+			request = new Request(url, {
+				method: call.method ?? "GET",
+				headers,
+				body,
+				credentials: options.credentials,
+				signal: controller.signal,
+				...body instanceof ReadableStream ? { duplex: "half" } : {}
+			});
+		} catch (error) {
+			cleanup();
+			return failure("request", error, url);
+		}
+		const transport = options.fetch ?? globalThis.fetch;
+		const terminal = async (context) => {
+			let response;
+			try {
+				response = await transport(context.request);
+			} catch (error) {
+				return failure(timedOut ? "timeout" : call.signal?.aborted ? "abort" : "network", error, url);
+			}
+			const codec = response.ok ? call.responses?.[response.status] ?? call.response : call.errors?.[response.status] ?? call.errors?.default;
+			if (!codec) return failure("decode", /* @__PURE__ */ new TypeError(`No codec for status ${response.status}`), url, response);
+			try {
+				const data = await decode(response.clone(), codec);
+				return response.ok ? {
+					ok: true,
+					kind: "success",
+					status: response.status,
+					data,
+					mediaType: media(response),
+					headers: response.headers,
+					url: response.url || url,
+					response
+				} : {
+					ok: false,
+					kind: "http",
+					status: response.status,
+					error: data,
+					mediaType: media(response),
+					headers: response.headers,
+					url: response.url || url,
+					response
+				};
+			} catch (error) {
+				return failure("decode", error, url, response);
+			}
+		};
+		const middleware = options.middleware ?? [];
+		const dispatch = (index, context) => index === middleware.length ? terminal(context) : Promise.resolve().then(() => middleware[index](context, (next = context) => dispatch(index + 1, next))).catch((error) => failure("middleware", error, url));
+		try {
+			return await dispatch(0, Object.freeze({
+				request,
+				endpoint: call.endpoint,
+				operationId: call.operationId,
+				security: call.endpoint?.security,
+				attempt: 1,
+				...timeout === void 0 ? {} : { deadline: Date.now() + timeout }
+			}));
+		} finally {
+			cleanup();
+		}
+	};
+}
+function createClient(api, options = {}) {
+	const execute = createFetch(options);
+	const methods = Object.fromEntries(Object.entries(api.endpoints).map(([id, endpoint]) => [id, async (input = {}) => {
+		let path = endpoint.path;
+		try {
+			for (const name of path.matchAll(/\{([^}]+)\}/g)) {
+				const key = name[1];
+				const value = input.params?.[key];
+				if (value === void 0) return failure("request", /* @__PURE__ */ new TypeError(`Missing path parameter: ${key}`), path);
+				path = path.replace(name[0], pathParameter(key, parameterValue(endpoint.params, key, value), parameterSpec(endpoint.params, key)));
+			}
+		} catch (error) {
+			return failure("request", error, path);
+		}
+		const extras = Object.keys(input.params ?? {}).filter((key) => !endpoint.path.includes(`{${key}}`));
+		if (extras.length) return failure("request", /* @__PURE__ */ new TypeError(`Unexpected path parameter: ${extras[0]}`), path);
+		const headers = new Headers();
+		try {
+			for (const [key, value] of Object.entries(input.headers ?? {})) if (value !== void 0) headers.set(key, headerParameter(parameterValue(endpoint.headers, key, value), parameterSpec(endpoint.headers, key)));
+		} catch (error) {
+			return failure("request", error, path);
+		}
+		return execute({
+			url: path,
+			method: endpoint.method,
+			headers,
+			query: input.query,
+			querySpec: endpoint.query,
+			body: input.body,
+			bodyCodec: endpoint.body,
+			responses: endpoint.responses,
+			errors: endpoint.errors,
+			signal: input.signal,
+			timeout: input.timeout,
+			endpoint,
+			operationId: id
+		});
+	}]));
+	return Object.freeze(methods);
+}
+var FetchError = class extends Error {
+	result;
+	constructor(result) {
+		super(`Fetch failed: ${result.kind}`);
+		this.result = result;
+		this.name = "FetchError";
+	}
+};
+function unwrap(result) {
+	if (!result.ok) throw new FetchError(result);
+	return result.data;
+}
+//#endregion
+export { FetchError, createClient, createFetch, unwrap };

package/dist/codecs.d.ts

@@ -0,0 +1,14 @@
+import { Codec, Validator } from "./types.js";
+//#region src/codecs.d.ts
+declare function json<T = unknown>(): Codec<T>;
+declare function json<V extends Validator>(schema: V): Codec<V extends Validator<infer T> ? T : never>;
+declare const text: () => Codec<string>;
+declare const urlEncoded: () => Codec<URLSearchParams>;
+declare const multipart: () => Codec<FormData>;
+declare const blob: () => Codec<Blob>;
+declare const arrayBuffer: () => Codec<ArrayBuffer>;
+declare const stream: () => Codec<ReadableStream<Uint8Array>>;
+declare const empty: () => Codec<undefined>;
+declare const content: <T extends Record<string, Codec>>(variants: T) => Codec<{ [K in keyof T]: T[K] extends Codec<infer V> ? V : never; }[keyof T]>;
+//#endregion
+export { arrayBuffer, blob, content, empty, json, multipart, stream, text, urlEncoded };

package/dist/codecs.js

@@ -0,0 +1,23 @@
+//#region src/codecs.ts
+const codec = (kind, mediaTypes, validator) => Object.freeze({
+	kind,
+	mediaTypes: Object.freeze(mediaTypes),
+	validator
+});
+function json(schema) {
+	return codec("json", ["application/json", "+json"], schema);
+}
+const text = () => codec("text", ["text/*"]);
+const urlEncoded = () => codec("urlEncoded", ["application/x-www-form-urlencoded"]);
+const multipart = () => codec("multipart", ["multipart/form-data"]);
+const blob = () => codec("blob", ["*/*"]);
+const arrayBuffer = () => codec("arrayBuffer", ["*/*"]);
+const stream = () => codec("stream", ["*/*"]);
+const empty = () => codec("empty", []);
+const content = (variants) => Object.freeze({
+	kind: "content",
+	mediaTypes: Object.freeze(Object.keys(variants).sort()),
+	variants: Object.freeze({ ...variants })
+});
+//#endregion
+export { arrayBuffer, blob, content, empty, json, multipart, stream, text, urlEncoded };

package/dist/dsl.d.ts

@@ -0,0 +1,33 @@
+import { AnyEndpointDescriptor, ApiDefinition, ApiMetadata, Codec, EndpointDescriptor, ParameterMap } from "./types.js";
+//#region src/dsl.d.ts
+declare function pathNames(path: string): string[];
+type Responses = Record<number, Codec>;
+type Errors = Partial<Record<number | "default", Codec>>;
+type State = Omit<EndpointDescriptor, "responses" | "errors"> & {
+  responses: Responses;
+  errors: Errors;
+};
+declare const STATE: unique symbol;
+interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Responses = {}, E extends Errors = {}> {
+  readonly [STATE]: State;
+  params<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<T, Q, H, B, R, E>;
+  query<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<P, T, H, B, R, E>;
+  headers<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<P, Q, T, B, R, E>;
+  body<C extends Codec>(codec: C): EndpointBuilder<P, Q, H, C extends Codec<infer T> ? T : never, R, E>;
+  returns<C extends Codec>(codec: C): EndpointBuilder<P, Q, H, B, R & Record<200, C>, E>;
+  returns<S extends number, C extends Codec>(status: S, codec: C): EndpointBuilder<P, Q, H, B, R & Record<S, C>, E>;
+  errors<T extends Errors>(spec: T): EndpointBuilder<P, Q, H, B, R, E & T>;
+  security(requirements: readonly Readonly<Record<string, readonly string[]>>[]): EndpointBuilder<P, Q, H, B, R, E>;
+}
+declare const get: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const post: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const put: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const patch: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const del: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const head: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+declare const options: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+type DescriptorOf<T> = T extends EndpointBuilder<infer P, infer Q, infer H, infer B, infer R, infer E> ? EndpointDescriptor<P, Q, H, B, R, E> : T extends AnyEndpointDescriptor ? T : never;
+type Defined<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>> = { [K in keyof E]: DescriptorOf<E[K]>; };
+declare function defineApi<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>>(endpoints: E, metadata?: ApiMetadata): ApiDefinition<Defined<E>>;
+//#endregion
+export { EndpointBuilder, defineApi, del, get, head, options, patch, pathNames, post, put };

package/dist/dsl.js

@@ -0,0 +1,107 @@
+//#region src/dsl.ts
+const PATH_NAME = /^[A-Za-z_$][\w$]*$/;
+function pathNames(path) {
+	if (path.includes(":") || path.includes("*")) throw new TypeError(`Invalid path syntax: ${path}`);
+	const names = [];
+	let index = 0;
+	for (const match of path.matchAll(/\{([^{}]*)\}/g)) {
+		const literal = path.slice(index, match.index);
+		if (literal.includes("{") || literal.includes("}") || !PATH_NAME.test(match[1])) throw new TypeError(`Malformed path parameter in ${path}`);
+		if (names.includes(match[1])) throw new TypeError(`Duplicate path parameter: ${match[1]}`);
+		names.push(match[1]);
+		index = (match.index ?? 0) + match[0].length;
+	}
+	if (path.slice(index).includes("{") || path.slice(index).includes("}")) throw new TypeError(`Malformed path parameter in ${path}`);
+	return names;
+}
+const STATE = Symbol("endpoint-state");
+const needsEmpty = (state, status) => status === 204 || status === 205 || state.method === "HEAD";
+function build(state) {
+	const update = (next) => build({
+		...state,
+		...next
+	});
+	return Object.freeze({
+		[STATE]: state,
+		params(spec) {
+			const names = pathNames(state.path);
+			if (spec && (Object.keys(spec).some((k) => !names.includes(k)) || names.some((k) => !(k in spec)))) throw new TypeError(`Path params must exactly match ${names.join(", ")}`);
+			return update({ params: spec ?? Object.fromEntries(names.map((name) => [name, void 0])) });
+		},
+		query(spec = {}) {
+			return update({ query: spec });
+		},
+		headers(spec = {}) {
+			return update({ headers: spec });
+		},
+		body(value) {
+			return update({ body: value });
+		},
+		returns(statusOrCodec, maybeCodec) {
+			const status = typeof statusOrCodec === "number" ? statusOrCodec : 200;
+			const responseCodec = typeof statusOrCodec === "number" ? maybeCodec : statusOrCodec;
+			if (status < 200 || status > 299) throw new TypeError("returns() accepts only 2xx statuses");
+			if (needsEmpty(state, status) && responseCodec.kind !== "empty") throw new TypeError(`${state.method} ${status} requires empty()`);
+			return update({ responses: {
+				...state.responses,
+				[status]: responseCodec
+			} });
+		},
+		errors(spec) {
+			for (const key of Object.keys(spec)) if (key !== "default" && Number(key) >= 200 && Number(key) <= 299) throw new TypeError("errors() accepts only non-2xx statuses or default");
+			return update({ errors: {
+				...state.errors,
+				...spec
+			} });
+		},
+		security(security) {
+			return update({ security });
+		}
+	});
+}
+const method = (value) => (path) => {
+	const names = pathNames(path);
+	return build({
+		method: value,
+		path,
+		params: names.length ? Object.fromEntries(names.map((name) => [name, void 0])) : void 0,
+		responses: {},
+		errors: {}
+	});
+};
+const get = method("GET");
+const post = method("POST");
+const put = method("PUT");
+const patch = method("PATCH");
+const del = method("DELETE");
+const head = method("HEAD");
+const options = method("OPTIONS");
+const snapshotParameters = (parameters) => parameters ? Object.freeze(Object.fromEntries(Object.entries(parameters).map(([name, definition]) => [name, definition && typeof definition === "object" && !("safeParse" in definition) ? Object.freeze({ ...definition }) : definition]))) : void 0;
+const snapshotSecurity = (security) => security ? Object.freeze(security.map((requirement) => Object.freeze(Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [name, Object.freeze([...scopes])]))))) : void 0;
+const snapshotMetadata = (metadata) => Object.freeze({
+	...metadata,
+	...metadata.servers ? { servers: Object.freeze(metadata.servers.map((server) => typeof server === "string" ? server : Object.freeze({ ...server }))) } : {},
+	...metadata.tags ? { tags: Object.freeze([...metadata.tags]) } : {},
+	...metadata.securitySchemes ? { securitySchemes: Object.freeze({ ...metadata.securitySchemes }) } : {}
+});
+function defineApi(endpoints, metadata) {
+	const frozen = Object.fromEntries(Object.entries(endpoints).map(([id, value]) => {
+		const endpoint = STATE in value ? value[STATE] : value;
+		return [id, Object.freeze({
+			...endpoint,
+			operationId: id,
+			params: snapshotParameters(endpoint.params),
+			query: snapshotParameters(endpoint.query),
+			headers: snapshotParameters(endpoint.headers),
+			security: snapshotSecurity(endpoint.security),
+			responses: Object.freeze({ ...endpoint.responses }),
+			errors: Object.freeze({ ...endpoint.errors })
+		})];
+	}));
+	return Object.freeze({
+		endpoints: Object.freeze(frozen),
+		...metadata ? { metadata: snapshotMetadata(metadata) } : {}
+	});
+}
+//#endregion
+export { defineApi, del, get, head, options, patch, pathNames, post, put };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { AnyEndpointDescriptor, ApiDefinition, ApiMetadata, ClientOptions, Codec, EndpointDescriptor, FailureKind, FailureResult, FetchResult, HttpMethod, HttpResult, InferCodec, InferValidator, Middleware, Next, ParameterMap, ParameterSpec, ParameterStyle, RequestContext, SuccessResult, Validator } from "./types.js";
+import { arrayBuffer, blob, content, empty, json, multipart, stream, text, urlEncoded } from "./codecs.js";
+import { EndpointBuilder, defineApi, del, get, head, options, patch, pathNames, post, put } from "./dsl.js";
+import { AdHocCall, ApiClient, ClientResult, FetchError, createClient, createFetch, unwrap } from "./client.js";
+export { AdHocCall, AnyEndpointDescriptor, ApiClient, ApiDefinition, ApiMetadata, ClientOptions, ClientResult, Codec, EndpointBuilder, EndpointDescriptor, FailureKind, FailureResult, FetchError, FetchResult, HttpMethod, HttpResult, InferCodec, InferValidator, Middleware, Next, ParameterMap, ParameterSpec, ParameterStyle, RequestContext, SuccessResult, Validator, arrayBuffer, blob, content, createClient, createFetch, defineApi, del, empty, get, head, json, multipart, options, patch, pathNames, post, put, stream, text, unwrap, urlEncoded };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { arrayBuffer, blob, content, empty, json, multipart, stream, text, urlEncoded } from "./codecs.js";
+import { defineApi, del, get, head, options, patch, pathNames, post, put } from "./dsl.js";
+import { FetchError, createClient, createFetch, unwrap } from "./client.js";
+export { FetchError, arrayBuffer, blob, content, createClient, createFetch, defineApi, del, empty, get, head, json, multipart, options, patch, pathNames, post, put, stream, text, unwrap, urlEncoded };

package/dist/middleware.d.ts

@@ -0,0 +1,28 @@
+import { FetchResult, Middleware, RequestContext } from "./types.js";
+//#region src/middleware.d.ts
+declare const bearerAuth: ({ token }: {
+  token: string | (() => string | Promise<string>);
+}) => Middleware;
+declare function apiKeyAuth({ key, value, in: location }: {
+  key: string;
+  value: string | (() => string | Promise<string>);
+  in?: "header" | "query";
+}): Middleware;
+interface RetryOptions {
+  attempts?: number;
+  methods?: readonly string[];
+  statuses?: readonly number[];
+  delay?: (attempt: number) => number;
+}
+declare function retry(options?: RetryOptions): Middleware;
+declare function logging(logger?: {
+  log(event: Record<string, unknown>): void;
+}): Middleware;
+interface TelemetryHooks {
+  start?(context: RequestContext): unknown;
+  end?(span: unknown, result: FetchResult): void;
+  error?(span: unknown, error: unknown): void;
+}
+declare function telemetry(hooks: TelemetryHooks): Middleware;
+//#endregion
+export { RetryOptions, TelemetryHooks, apiKeyAuth, bearerAuth, logging, retry, telemetry };

package/dist/middleware.js

@@ -0,0 +1,140 @@
+//#region src/middleware.ts
+const SENSITIVE = Symbol("askr-fetch-sensitive-fields");
+const markSensitive = (context, location, name) => {
+	const current = context[SENSITIVE] ?? {
+		headers: [],
+		query: []
+	};
+	return Object.freeze({
+		...context,
+		[SENSITIVE]: Object.freeze({
+			...current,
+			[location]: Object.freeze([.../* @__PURE__ */ new Set([...current[location], name.toLowerCase()])])
+		})
+	});
+};
+const replaceHeaders = (context, mutate) => {
+	const headers = new Headers(context.request.headers);
+	mutate(headers);
+	return Object.freeze({
+		...context,
+		request: new Request(context.request, { headers })
+	});
+};
+const bearerAuth = ({ token }) => async (context, next) => {
+	const resolved = typeof token === "function" ? await token() : token;
+	return next(replaceHeaders(context, (headers) => headers.set("authorization", `Bearer ${resolved}`)));
+};
+function apiKeyAuth({ key, value, in: location = "header" }) {
+	return async (context, next) => {
+		const resolved = typeof value === "function" ? await value() : value;
+		if (location === "header") return next(markSensitive(replaceHeaders(context, (headers) => headers.set(key, resolved)), "headers", key));
+		const url = new URL(context.request.url);
+		url.searchParams.set(key, resolved);
+		return next(markSensitive(Object.freeze({
+			...context,
+			request: new Request(url, context.request)
+		}), "query", key));
+	};
+}
+function retry(options = {}) {
+	const attempts = options.attempts ?? 3;
+	const methods = options.methods ?? [
+		"GET",
+		"HEAD",
+		"PUT",
+		"DELETE",
+		"OPTIONS"
+	];
+	const statuses = options.statuses ?? [
+		408,
+		425,
+		429,
+		500,
+		502,
+		503,
+		504
+	];
+	return async (context, next) => {
+		if (!methods.includes(context.request.method) || context.request.body) return next(context);
+		let result = await next(context);
+		for (let attempt = 2; attempt <= attempts && !result.ok && (result.kind === "network" || result.response !== void 0 && statuses.includes(result.status)); attempt++) {
+			const retryAfter = "response" in result ? result.response?.headers.get("retry-after") : null;
+			const wait = retryAfter ? /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1e3 : Math.max(0, Date.parse(retryAfter) - Date.now()) : options.delay?.(attempt) ?? 100 * 2 ** (attempt - 2);
+			if (context.deadline && Date.now() + wait >= context.deadline) break;
+			if (!await new Promise((resolve) => {
+				const onAbort = () => {
+					clearTimeout(timer);
+					resolve(false);
+				};
+				const timer = setTimeout(() => {
+					context.request.signal.removeEventListener("abort", onAbort);
+					resolve(true);
+				}, wait);
+				if (context.request.signal.aborted) onAbort();
+				else context.request.signal.addEventListener("abort", onAbort, { once: true });
+			})) return {
+				ok: false,
+				kind: "abort",
+				status: 0,
+				error: context.request.signal.reason,
+				headers: new Headers(),
+				url: context.request.url
+			};
+			result = await next(Object.freeze({
+				...context,
+				attempt,
+				request: context.request.clone()
+			}));
+		}
+		return result;
+	};
+}
+const SENSITIVE_NAME = /(?:^|[-_])(authorization|cookie|token|secret|password|api[-_]?key)(?:$|[-_])/i;
+const redacted = (headers, names = []) => Object.fromEntries([...headers].map(([key, value]) => [key, SENSITIVE_NAME.test(key) || names.includes(key.toLowerCase()) ? "[REDACTED]" : value]));
+const redactedUrl = (value, names = []) => {
+	const url = new URL(value);
+	for (const key of new Set(url.searchParams.keys())) if (SENSITIVE_NAME.test(key) || names.includes(key.toLowerCase())) {
+		const count = url.searchParams.getAll(key).length;
+		url.searchParams.delete(key);
+		for (let index = 0; index < count; index++) url.searchParams.append(key, "[REDACTED]");
+	}
+	return url.toString();
+};
+function logging(logger = console) {
+	return async (context, next) => {
+		const sensitive = context[SENSITIVE];
+		logger.log({
+			phase: "request",
+			operationId: context.operationId,
+			method: context.request.method,
+			url: redactedUrl(context.request.url, sensitive?.query),
+			headers: redacted(context.request.headers, sensitive?.headers),
+			attempt: context.attempt
+		});
+		const result = await next(context);
+		logger.log({
+			phase: "response",
+			operationId: context.operationId,
+			kind: result.kind,
+			status: result.status,
+			attempt: context.attempt
+		});
+		return result;
+	};
+}
+function telemetry(hooks) {
+	return async (context, next) => {
+		const span = hooks.start?.(context);
+		try {
+			const result = await next(context);
+			hooks.end?.(span, result);
+			return result;
+		} catch (error) {
+			hooks.error?.(span, error);
+			throw error;
+		}
+	};
+}
+//#endregion
+export { apiKeyAuth, bearerAuth, logging, retry, telemetry };

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+//#region src/types.d.ts
+interface Validator<T = unknown> {
+  safeParse(value: unknown): {
+    success: true;
+    data: T;
+  } | {
+    success: false;
+    error: unknown;
+  };
+}
+type InferValidator<V> = V extends Validator<infer T> ? T : never;
+interface Codec<T = unknown> {
+  readonly kind: "json" | "text" | "urlEncoded" | "multipart" | "blob" | "arrayBuffer" | "stream" | "empty" | "content";
+  readonly mediaTypes: readonly string[];
+  readonly validator?: Validator<T>;
+  readonly variants?: Readonly<Record<string, Codec<unknown>>>;
+}
+type InferCodec<C> = C extends Codec<infer T> ? T : never;
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+type ParameterStyle = "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+interface ParameterSpec<T = unknown> {
+  readonly validator?: Validator<T>;
+  readonly style?: ParameterStyle;
+  readonly explode?: boolean;
+}
+type ParameterMap = Readonly<Record<string, Validator<unknown> | ParameterSpec | undefined>>;
+interface EndpointDescriptor<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Record<number, Codec> = Record<number, Codec>, E extends Partial<Record<number | "default", Codec>> = Partial<Record<number | "default", Codec>>> {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly params?: ParameterMap;
+  readonly query?: ParameterMap;
+  readonly headers?: ParameterMap;
+  readonly body?: Codec;
+  readonly responses: Readonly<R>;
+  readonly errors: Readonly<E>;
+  readonly security?: readonly Readonly<Record<string, readonly string[]>>[];
+  readonly operationId?: string;
+  readonly __input?: {
+    params: P;
+    query: Q;
+    headers: H;
+    body: B;
+  };
+}
+type AnyEndpointDescriptor = EndpointDescriptor<any, any, any, any, any, any>;
+interface ApiMetadata {
+  readonly servers?: readonly (string | {
+    readonly url: string;
+  })[];
+  readonly tags?: readonly unknown[];
+  readonly securitySchemes?: Readonly<Record<string, unknown>>;
+}
+interface ApiDefinition<E extends Record<string, AnyEndpointDescriptor> = Record<string, AnyEndpointDescriptor>> {
+  readonly endpoints: E;
+  readonly metadata?: ApiMetadata;
+}
+type SuccessResult<T = unknown, S extends number = number> = {
+  ok: true;
+  kind: "success";
+  status: S;
+  data: T;
+  mediaType: string | null;
+  headers: Headers;
+  url: string;
+  response: Response;
+};
+type HttpResult<T = unknown, S extends number = number> = {
+  ok: false;
+  kind: "http";
+  status: S;
+  error: T;
+  mediaType: string | null;
+  headers: Headers;
+  url: string;
+  response: Response;
+};
+type FailureKind = "request" | "network" | "timeout" | "abort" | "decode" | "middleware";
+type FailureResult = {
+  ok: false;
+  kind: FailureKind;
+  status: number;
+  error: unknown;
+  headers: Headers;
+  url: string;
+  response?: Response;
+};
+type FetchResult<T = unknown> = SuccessResult<T> | HttpResult<T> | FailureResult;
+interface RequestContext {
+  readonly request: Request;
+  readonly endpoint?: AnyEndpointDescriptor;
+  readonly operationId?: string;
+  readonly security?: AnyEndpointDescriptor["security"];
+  readonly attempt: number;
+  readonly deadline?: number;
+}
+type Next = (context?: RequestContext) => Promise<FetchResult>;
+type Middleware = (context: RequestContext, next: Next) => Promise<FetchResult>;
+interface ClientOptions {
+  baseUrl?: string;
+  fetch?: (request: Request) => Promise<Response>;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  timeout?: number;
+  middleware?: readonly Middleware[];
+}
+//#endregion
+export { AnyEndpointDescriptor, ApiDefinition, ApiMetadata, ClientOptions, Codec, EndpointDescriptor, FailureKind, FailureResult, FetchResult, HttpMethod, HttpResult, InferCodec, InferValidator, Middleware, Next, ParameterMap, ParameterSpec, ParameterStyle, RequestContext, SuccessResult, Validator };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@askrjs/fetch",
+  "version": "0.0.1",
+  "description": "Function-first typed HTTP contracts and clients for Askr.",
+  "keywords": [
+    "askr",
+    "fetch",
+    "http",
+    "typescript"
+  ],
+  "homepage": "https://github.com/askrjs/askr-fetch#readme",
+  "bugs": {
+    "url": "https://github.com/askrjs/askr-fetch/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "askrjs",
+    "url": "https://github.com/askrjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/askrjs/askr-fetch.git"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "fmt": "vp fmt .",
+    "lint": "vp lint src tests vite.config.ts && npm run typecheck",
+    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false",
+    "test": "vp test run",
+    "test:installed": "node tests/installed-smoke.mjs",
+    "test:publint": "publint",
+    "pack:check": "npm pack --ignore-scripts --dry-run --json",
+    "check": "npm run lint && npm test && npm run build && npm run test:installed && npm run test:publint && npm run pack:check",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.2.4",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "packageManager": "npm@12.0.1"
+}