@askrjs/fetch 0.2.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 
 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.
+and Node.js 24 or newer.
 
 ## Install
 
@@ -46,6 +46,12 @@ if (result.ok) {
 Paths use OpenAPI-style `{name}` parameters. Colon parameters and wildcards are rejected. A path
 parameter declaration must exactly match the names in the path.
 
+Path values are runtime-validated or transformed only when their `.params()` entry includes a
+validator. The generic in `.params<T>()` is a compile-time contract and is erased at runtime; using
+`.params<T>()` without validators, or relying on auto-derived path parameters, only checks that
+required names are present. Supply a validator for every path value when runtime safety or coercion
+is required.
+
 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.
 
@@ -63,10 +69,25 @@ The built-in codecs are:
 - `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.
+For outbound bodies with more than one `content()` variant, pass
+`bodyMediaType` explicitly. Single-variant codecs select their only variant
+automatically:
+
+```ts
+await client.createDocument({
+  body: "plain text",
+  bodyMediaType: "text/plain",
+});
+```
+
+An omitted or unknown media type produces a `request` failure, so declaration
+order never selects a multi-variant request format.
+
+A validator only needs a `safeParse(value)` method whose failure result exposes either `error` or
+`issues`, so `@askrjs/schema` and other 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;
+the validator's `error` or `issues` value is preserved on failure.
 
 ```ts
 const positiveInteger = {
@@ -139,10 +160,12 @@ sequence is intentional. Logging redacts common credential names as well as arbi
 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. Cloneable request
-bodies are replayed with the original bytes and headers. `ReadableStream` bodies are explicitly
-single-attempt so retry does not buffer an unbounded stream. If an earlier middleware has already
-consumed any body, retry also sends it once and does not surface an incidental cloning error.
+`429`, `500`, `502`, `503`, and `504`. Valid `Retry-After` values are honored up to
+`maxRetryAfter` (60 seconds by default); malformed values use the normal backoff. Cloneable
+request bodies are replayed with the original bytes and headers. `ReadableStream` bodies are
+explicitly single-attempt so retry does not buffer an unbounded stream. If an earlier middleware
+has already consumed any body, retry also sends it once and does not surface an incidental cloning
+error.
 
 Do not include a status such as `401` in `retry()` when an upstream authentication middleware
 already handles that status. The outer authentication layer cannot react until retry's complete

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { AnyEndpointDescriptor, ApiDefinition, ClientOptions, Codec, EndpointDescriptor, FailureResult, FetchResult, HttpResult, InferCodec, ParameterMap, SuccessResult } from "./types.js";
 //#region src/client.d.ts
 /** A one-off, untyped request description accepted by {@link createFetch}'s returned function. */
-interface AdHocCall {
+export interface AdHocCall {
   url: string;
   method?: string;
   headers?: HeadersInit;
@@ -9,6 +9,8 @@ interface AdHocCall {
   querySpec?: ParameterMap;
   body?: unknown;
   bodyCodec?: Codec;
+  /** Explicit media type used to encode a request body with a multi-variant `content()` codec. */
+  bodyMediaType?: string;
   response?: Codec;
   responses?: Readonly<Record<number, Codec>>;
   errors?: Partial<Record<number | "default", Codec>>;
@@ -23,7 +25,7 @@ interface AdHocCall {
  * matching codec. Used internally by {@link createClient}, and usable directly for
  * requests without a full {@link EndpointDescriptor}.
  */
-declare function createFetch(options?: ClientOptions): (call: AdHocCall) => Promise<FetchResult>;
+export 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;
@@ -33,24 +35,25 @@ type InputParts<D> = D extends EndpointDescriptor<infer P, infer Q, infer H, inf
 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> & {
+  bodyMediaType?: string;
   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;
 /** The possible results of calling a typed client method for endpoint descriptor `D`. */
-type ClientResult<D extends AnyEndpointDescriptor> = Successes<D> | Errors<D> | FailureResult;
+export 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>>;
 /** A fully-typed client for an {@link ApiDefinition}, with one method per endpoint. */
-type ApiClient<A extends ApiDefinition> = Readonly<{ [K in keyof A["endpoints"]]: ClientMethod<A["endpoints"][K]>; }>;
+export type ApiClient<A extends ApiDefinition> = Readonly<{ [K in keyof A["endpoints"]]: ClientMethod<A["endpoints"][K]>; }>;
 /**
  * Builds a typed {@link ApiClient} from an {@link ApiDefinition}. Each endpoint becomes
  * a method that fills in the path, query, header, and body parameters, executes the
  * request via {@link createFetch}, and returns a {@link ClientResult}.
  */
-declare function createClient<A extends ApiDefinition>(api: A, options?: ClientOptions): ApiClient<A>;
+export declare function createClient<A extends ApiDefinition>(api: A, options?: ClientOptions): ApiClient<A>;
 /** An `Error` thrown by {@link unwrap} that wraps a failed (non-`ok`) {@link FetchResult}. */
-declare class FetchError extends Error {
+export declare class FetchError extends Error {
   readonly result: Exclude<FetchResult, {
     ok: true;
   }>;
@@ -62,6 +65,5 @@ declare class FetchError extends Error {
  * Returns the data of a successful {@link FetchResult}, or throws a {@link FetchError}
  * wrapping the result if it was not `ok`.
  */
-declare function unwrap<T>(result: FetchResult<T>): T;
-//#endregion
-export { AdHocCall, ApiClient, ClientResult, FetchError, createClient, createFetch, unwrap };
+export declare function unwrap<T>(result: FetchResult<T>): T;
+//#endregion

package/dist/client.js

@@ -1,6 +1,7 @@
 //#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"));
+const validationFailure = (result) => "error" in result ? result.error : result.issues;
 async function decode(response, codec) {
 	const type = media(response);
 	const selected = codec.kind === "content" ? codec.variants?.[type ?? ""] : codec;
@@ -33,15 +34,15 @@ async function decode(response, codec) {
 	}
 	if (selected.validator) {
 		const parsed = selected.validator.safeParse(value);
-		if (!parsed.success) throw parsed.error;
+		if (!parsed.success) throw validationFailure(parsed);
 		return parsed.data;
 	}
 	return value;
 }
-function encode(value, codec, headers) {
+function encode(value, codec, headers, requestedMediaType) {
 	if (codec.validator) {
 		const parsed = codec.validator.safeParse(value);
-		if (!parsed.success) throw parsed.error;
+		if (!parsed.success) throw validationFailure(parsed);
 		value = parsed.data;
 	}
 	switch (codec.kind) {
@@ -60,10 +61,14 @@ function encode(value, codec, headers) {
 		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 variants = Object.entries(codec.variants ?? {});
+			if (variants.length === 0) throw new TypeError("content() has no variants");
+			const type = requestedMediaType?.split(";", 1)[0]?.trim().toLowerCase();
+			const [selectedType, selected] = type ? [type, codec.variants?.[type]] : variants.length === 1 ? variants[0] : [];
+			if (type && !selected) throw new TypeError(`No content() request variant for media type ${type}`);
+			if (!selected) throw new TypeError("Multi-variant content() request bodies require bodyMediaType");
 			const body = encode(value, selected, headers);
-			if (selected.kind !== "multipart") headers.set("content-type", type);
+			if (selected.kind !== "multipart") headers.set("content-type", selectedType);
 			return body;
 		}
 	}
@@ -137,7 +142,7 @@ const parameterValue = (map, name, value) => {
 	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;
+	if (!parsed.success) throw validationFailure(parsed);
 	return parsed.data;
 };
 /**
@@ -163,7 +168,7 @@ function createFetch(options = {}) {
 		}
 		let body;
 		try {
-			if (call.bodyCodec) body = encode(call.body, call.bodyCodec, headers);
+			if (call.bodyCodec) body = encode(call.body, call.bodyCodec, headers, call.bodyMediaType);
 		} catch (error) {
 			return failure("request", error, url);
 		}
@@ -289,6 +294,7 @@ function createClient(api, options = {}) {
 			querySpec: endpoint.query,
 			body: input.body,
 			bodyCodec: endpoint.body,
+			bodyMediaType: input.bodyMediaType,
 			responses: endpoint.responses,
 			errors: endpoint.errors,
 			signal: input.signal,

package/dist/codecs.d.ts

@@ -1,27 +1,26 @@
-import { Codec, Validator } from "./types.js";
+import { Codec, InferValidator, Validator } from "./types.js";
 //#region src/codecs.d.ts
 /** Creates a JSON codec, matching `application/json` and `+json` suffixed media types. */
-declare function json<T = unknown>(): Codec<T>;
+export declare function json<T = unknown>(): Codec<T>;
 /** Creates a JSON codec that validates/parses the decoded value with the given schema. */
-declare function json<V extends Validator>(schema: V): Codec<V extends Validator<infer T> ? T : never>;
+export declare function json<V extends Validator>(schema: V): Codec<InferValidator<V>>;
 /** Creates a codec for plain text bodies (`text/*`), decoded as a string. */
-declare const text: () => Codec<string>;
+export declare const text: () => Codec<string>;
 /** Creates a codec for `application/x-www-form-urlencoded` bodies, decoded as `URLSearchParams`. */
-declare const urlEncoded: () => Codec<URLSearchParams>;
+export declare const urlEncoded: () => Codec<URLSearchParams>;
 /** Creates a codec for `multipart/form-data` bodies, decoded as `FormData`. */
-declare const multipart: () => Codec<FormData>;
+export declare const multipart: () => Codec<FormData>;
 /** Creates a codec that decodes any response body as a `Blob`. */
-declare const blob: () => Codec<Blob>;
+export declare const blob: () => Codec<Blob>;
 /** Creates a codec that decodes any response body as an `ArrayBuffer`. */
-declare const arrayBuffer: () => Codec<ArrayBuffer>;
+export declare const arrayBuffer: () => Codec<ArrayBuffer>;
 /** Creates a codec that exposes the raw response body as a `ReadableStream`, without buffering it. */
-declare const stream: () => Codec<ReadableStream<Uint8Array>>;
+export declare const stream: () => Codec<ReadableStream<Uint8Array>>;
 /** Creates a codec for bodies expected to be empty (e.g. 204 No Content), decoded as `undefined`. */
-declare const empty: () => Codec<undefined>;
+export declare const empty: () => Codec<undefined>;
 /**
  * Creates a content-negotiated codec that selects among `variants` by the response's
  * media type, decoding with whichever variant matches.
  */
-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 };
+export 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

package/dist/dsl.d.ts

@@ -6,7 +6,7 @@ import { AnyEndpointDescriptor, ApiDefinition, ApiMetadata, Codec, EndpointDescr
  * @throws {TypeError} If the path uses colon/wildcard syntax, has malformed
  * `{...}` placeholders, or contains a duplicate parameter name.
  */
-declare function pathNames(path: string): string[];
+export declare function pathNames(path: string): string[];
 type Responses = Record<number, Codec>;
 type Errors = Partial<Record<number | "default", Codec>>;
 type State = Omit<EndpointDescriptor, "responses" | "errors"> & {
@@ -20,8 +20,12 @@ declare const STATE: unique symbol;
  * returns a new builder reflecting the added configuration; the accumulated
  * state is finalized into an {@link EndpointDescriptor} by {@link defineApi}.
  */
-interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Responses = {}, E extends Errors = {}> {
+export interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Responses = {}, E extends Errors = {}> {
   readonly [STATE]: State;
+  /**
+   * Declares path parameter types and optional runtime validators. Generic types are erased;
+   * runtime validation occurs only for entries whose specification includes a validator.
+   */
   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>;
@@ -32,19 +36,19 @@ interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undef
   security(requirements: readonly Readonly<Record<string, readonly string[]>>[]): EndpointBuilder<P, Q, H, B, R, E>;
 }
 /** Starts building a GET endpoint at the given path. */
-declare const get: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const get: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building a POST endpoint at the given path. */
-declare const post: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const post: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building a PUT endpoint at the given path. */
-declare const put: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const put: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building a PATCH endpoint at the given path. */
-declare const patch: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const patch: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building a DELETE endpoint at the given path. */
-declare const del: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const del: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building a HEAD endpoint at the given path. */
-declare const head: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export declare const head: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 /** Starts building an OPTIONS endpoint at the given path. */
-declare const options: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+export 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]>; };
 /**
@@ -57,6 +61,5 @@ type Defined<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>>
  *   getUser: get("/users/{id}").returns(json()),
  * });
  */
-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 };
+export declare function defineApi<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>>(endpoints: E, metadata?: ApiMetadata): ApiDefinition<Defined<E>>;
+//#endregion

package/dist/middleware.d.ts

@@ -4,7 +4,7 @@ import { FetchResult, Middleware, RequestContext } from "./types.js";
  * Middleware that attaches an `Authorization: Bearer <token>` header to every request.
  * `token` may be a static string or a (possibly async) function resolved on each request.
  */
-declare const bearerAuth: ({ token }: {
+export declare const bearerAuth: ({ token }: {
   token: string | (() => string | Promise<string>);
 }) => Middleware;
 /**
@@ -13,13 +13,13 @@ declare const bearerAuth: ({ token }: {
  * async) function resolved on each request. The key is marked sensitive so the
  * {@link logging} middleware redacts it.
  */
-declare function apiKeyAuth({ key, value, in: location }: {
+export declare function apiKeyAuth({ key, value, in: location }: {
   key: string;
   value: string | (() => string | Promise<string>);
   in?: "header" | "query";
 }): Middleware;
 /** Options controlling the {@link retry} middleware's behavior. */
-interface RetryOptions {
+export interface RetryOptions {
   /** Maximum number of attempts, including the first. Defaults to 3. */
   attempts?: number;
   /** HTTP methods eligible for retry. Defaults to idempotent-by-convention methods. */
@@ -28,6 +28,8 @@ interface RetryOptions {
   statuses?: readonly number[];
   /** Computes the delay (ms) before the given retry attempt, if no `Retry-After` header is present. */
   delay?: (attempt: number) => number;
+  /** Maximum delay (ms) accepted from `Retry-After`. Defaults to 60 seconds. */
+  maxRetryAfter?: number;
 }
 /**
  * Middleware that retries failed requests. Retries eligible methods on network failures
@@ -36,18 +38,18 @@ interface RetryOptions {
  * is replayed only when it can be cloned before the first attempt; streaming, already-consumed,
  * or otherwise non-cloneable bodies are sent once without retrying.
  */
-declare function retry(options?: RetryOptions): Middleware;
+export declare function retry(options?: RetryOptions): Middleware;
 /**
  * Middleware that logs a `"request"` event before and a `"response"` event after each
  * request, via the given logger (defaults to `console`). Headers and query parameters
  * marked sensitive (e.g. by {@link apiKeyAuth}) or matching common sensitive-name
  * patterns (authorization, cookie, token, secret, password, api key) are redacted.
  */
-declare function logging(logger?: {
+export declare function logging(logger?: {
   log(event: Record<string, unknown>): void;
 }): Middleware;
 /** Hooks invoked by the {@link telemetry} middleware around each request. */
-interface TelemetryHooks {
+export interface TelemetryHooks {
   /** Called before the request proceeds; its return value (a "span") is passed to `end`/`error`. */
   start?(context: RequestContext): unknown;
   /** Called after the request completes successfully (from this middleware's perspective). */
@@ -59,6 +61,5 @@ interface TelemetryHooks {
  * Middleware that wraps each request with {@link TelemetryHooks}, calling `start` before
  * the request, `end` after it completes, and `error` (then rethrowing) if it throws.
  */
-declare function telemetry(hooks: TelemetryHooks): Middleware;
-//#endregion
-export { RetryOptions, TelemetryHooks, apiKeyAuth, bearerAuth, logging, retry, telemetry };
+export declare function telemetry(hooks: TelemetryHooks): Middleware;
+//#endregion

package/dist/middleware.js

@@ -72,6 +72,8 @@ function retry(options = {}) {
 		503,
 		504
 	];
+	const maxRetryAfter = options.maxRetryAfter ?? 6e4;
+	if (!Number.isFinite(maxRetryAfter) || maxRetryAfter < 0) throw new TypeError("maxRetryAfter must be a non-negative finite number");
 	return async (context, next) => {
 		if (!methods.includes(context.request.method)) return next(context);
 		if (context.replayableBody === false) return next(context);
@@ -84,8 +86,10 @@ function retry(options = {}) {
 		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;
+			const fallback = () => options.delay?.(attempt) ?? 100 * 2 ** (attempt - 2);
+			const parsedRetryAfter = retryAfter ? /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1e3 : Math.max(0, Date.parse(retryAfter) - Date.now()) : void 0;
+			const wait = parsedRetryAfter === void 0 || !Number.isFinite(parsedRetryAfter) ? fallback() : Math.min(parsedRetryAfter, maxRetryAfter);
+			if (context.deadline !== void 0 && Date.now() + wait >= context.deadline) break;
 			if (!await new Promise((resolve) => {
 				const onAbort = () => {
 					clearTimeout(timer);

package/dist/types.d.ts

@@ -1,25 +1,36 @@
 //#region src/types.d.ts
 /**
- * A minimal schema-validation contract, compatible with libraries such as Zod
- * that expose a `safeParse` method (e.g. via a thin adapter).
+ * A minimal schema-validation contract, compatible with `safeParse` methods
+ * that report failures through either `error` or `issues`.
  */
-interface Validator<T = unknown> {
+export interface Validator<T = unknown> {
   safeParse(value: unknown): {
-    success: true;
-    data: T;
+    readonly success: true;
+    readonly data: T;
   } | {
-    success: false;
-    error: unknown;
+    readonly success: false;
+    readonly error: unknown;
+    readonly issues?: unknown;
+  } | {
+    readonly success: false;
+    readonly error?: unknown;
+    readonly issues: unknown;
   };
 }
 /** Infers the parsed output type `T` from a {@link Validator}. */
-type InferValidator<V> = V extends Validator<infer T> ? T : never;
+export type InferValidator<V> = V extends {
+  safeParse(value: unknown): infer Result;
+} ? Extract<Result, {
+  readonly success: true;
+}> extends {
+  readonly data: infer T;
+} ? T : never : never;
 /**
  * Describes how a request or response body is serialized/deserialized:
  * which wire format (`kind`), which media types it matches, and optionally
  * a {@link Validator} to parse/validate the decoded value.
  */
-interface Codec<T = unknown> {
+export interface Codec<T = unknown> {
   readonly kind: "json" | "text" | "urlEncoded" | "multipart" | "blob" | "arrayBuffer" | "stream" | "empty" | "content";
   readonly mediaTypes: readonly string[];
   readonly validator?: Validator<T>;
@@ -27,13 +38,13 @@ interface Codec<T = unknown> {
   readonly variants?: Readonly<Record<string, Codec<unknown>>>;
 }
 /** Infers the decoded value type `T` from a {@link Codec}. */
-type InferCodec<C> = C extends Codec<infer T> ? T : never;
+export type InferCodec<C> = C extends Codec<infer T> ? T : never;
 /** The set of HTTP methods supported by endpoint descriptors. */
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 /** OpenAPI-style serialization styles for path, query, and header parameters. */
-type ParameterStyle = "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+export type ParameterStyle = "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
 /** Serialization and validation settings for a single path, query, or header parameter. */
-interface ParameterSpec<T = unknown> {
+export interface ParameterSpec<T = unknown> {
   readonly validator?: Validator<T>;
   readonly style?: ParameterStyle;
   readonly explode?: boolean;
@@ -42,9 +53,9 @@ interface ParameterSpec<T = unknown> {
  * Maps parameter names to either a bare {@link Validator} or a full
  * {@link ParameterSpec} describing serialization and validation.
  */
-type ParameterMap = Readonly<Record<string, Validator<unknown> | ParameterSpec | undefined>>;
+export type ParameterMap = Readonly<Record<string, Validator<unknown> | ParameterSpec | undefined>>;
 /** Describes a single API endpoint: its method, path, parameters, body, and possible responses. */
-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>>> {
+export 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;
@@ -63,9 +74,9 @@ interface EndpointDescriptor<P = undefined, Q = undefined, H = undefined, B = un
   };
 }
 /** An {@link EndpointDescriptor} with its type parameters erased, for use in generic contexts. */
-type AnyEndpointDescriptor = EndpointDescriptor<any, any, any, any, any, any>;
+export type AnyEndpointDescriptor = EndpointDescriptor<any, any, any, any, any, any>;
 /** API-level (rather than per-endpoint) metadata, such as servers and security schemes. */
-interface ApiMetadata {
+export interface ApiMetadata {
   readonly servers?: readonly (string | {
     readonly url: string;
   })[];
@@ -73,12 +84,12 @@ interface ApiMetadata {
   readonly securitySchemes?: Readonly<Record<string, unknown>>;
 }
 /** A named collection of endpoints plus optional API metadata, as produced by {@link defineApi}. */
-interface ApiDefinition<E extends Record<string, AnyEndpointDescriptor> = Record<string, AnyEndpointDescriptor>> {
+export interface ApiDefinition<E extends Record<string, AnyEndpointDescriptor> = Record<string, AnyEndpointDescriptor>> {
   readonly endpoints: E;
   readonly metadata?: ApiMetadata;
 }
 /** A successful (2xx) fetch outcome, carrying the decoded response data. */
-type SuccessResult<T = unknown, S extends number = number> = {
+export type SuccessResult<T = unknown, S extends number = number> = {
   ok: true;
   kind: "success";
   status: S;
@@ -89,7 +100,7 @@ type SuccessResult<T = unknown, S extends number = number> = {
   response: Response;
 };
 /** A non-2xx fetch outcome where the server responded with a decodable error body. */
-type HttpResult<T = unknown, S extends number = number> = {
+export type HttpResult<T = unknown, S extends number = number> = {
   ok: false;
   kind: "http";
   status: S;
@@ -100,9 +111,9 @@ type HttpResult<T = unknown, S extends number = number> = {
   response: Response;
 };
 /** Categorizes why a fetch could not produce an {@link HttpResult} or {@link SuccessResult}. */
-type FailureKind = "request" | "network" | "timeout" | "abort" | "decode" | "middleware";
+export type FailureKind = "request" | "network" | "timeout" | "abort" | "decode" | "middleware";
 /** A fetch outcome that failed before or independently of receiving a decodable HTTP response. */
-type FailureResult = {
+export type FailureResult = {
   ok: false;
   kind: FailureKind;
   status: number;
@@ -112,9 +123,9 @@ type FailureResult = {
   response?: Response;
 };
 /** The outcome of a fetch call: success, an HTTP-level error, or another kind of failure. */
-type FetchResult<T = unknown> = SuccessResult<T> | HttpResult<T> | FailureResult;
+export type FetchResult<T = unknown> = SuccessResult<T> | HttpResult<T> | FailureResult;
 /** The mutable-by-replacement state threaded through the middleware chain for a single request. */
-interface RequestContext {
+export interface RequestContext {
   readonly request: Request;
   readonly endpoint?: AnyEndpointDescriptor;
   readonly operationId?: string;
@@ -127,11 +138,11 @@ interface RequestContext {
   readonly deadline?: number;
 }
 /** Invokes the next middleware in the chain, optionally passing a replacement context. */
-type Next = (context?: RequestContext) => Promise<FetchResult>;
+export type Next = (context?: RequestContext) => Promise<FetchResult>;
 /** A function that can inspect/replace the request context and/or the result of calling `next`. */
-type Middleware = (context: RequestContext, next: Next) => Promise<FetchResult>;
+export type Middleware = (context: RequestContext, next: Next) => Promise<FetchResult>;
 /** Options controlling how a {@link createClient} or {@link createFetch} client makes requests. */
-interface ClientOptions {
+export interface ClientOptions {
   baseUrl?: string;
   /** Custom transport, defaulting to the global `fetch`. */
   fetch?: (request: Request) => Promise<Response>;
@@ -142,5 +153,4 @@ interface ClientOptions {
   /** Middleware chain applied to every request, in order. */
   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 };
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/fetch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Function-first typed HTTP contracts and clients for Askr.",
   "keywords": [
     "askr",
@@ -61,11 +61,12 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "publint": "^0.3.23",
+    "@askrjs/schema": "^0.3.0",
+    "@types/node": "^26.3.0",
+    "publint": "^0.3.24",
     "typescript": "^7.0.2",
-    "vite-plus": "^0.2.8",
-    "vitest": "^4.1.10"
+    "vite-plus": "^0.3.1",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=24.0.0"