arthron 1.2.0 → 2.1.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as redactUrl, a as cancellationError, c as responseError, d as runtimeStreamsRequestBody, f as serializeBody, g as leavesBase, h as fillPath, i as logging$1, m as isArthronError, n as timeout$1, o as isCancellation, p as ArthronError, r as retry$1, s as networkError, u as isReadableStream, v as redactUrlIn, y as resolveUrl } from "./plugins-CHCMxtAE.mjs";
+import { C as redactUrlIn, S as redactUrl, T as withoutSecrets, _ as httpOrigin, a as redactErrorUrl, d as runtimeStreamsRequestBody, f as serializeBody, g as fillPath, h as isArthronError, i as networkError, m as ArthronError, n as isCancellation, o as responseError, p as tagOf, t as cancellationError, u as isReadableStream, w as resolveUrl, x as originSet, y as leavesBase } from "./shared.mjs";
 //#region src/request/headers.ts
 const isPlainRecord = (headers) => !Array.isArray(headers) && Object.prototype.toString.call(headers) !== "[object Headers]";
 /**
@@ -23,22 +23,31 @@ function toHeaderRecord(headers) {
 }
 //#endregion
 //#region src/pipeline/pipeline.ts
-/** The mutable body kinds an interceptor can `append` to; anything else is shared as is. */
+/**
+* The mutable body kinds an interceptor can `append` to; anything else is
+* shared as is. Known by type tag, as serializeBody knows them, and copied
+* into their own class — a polyfill's (formdata-node) or another realm's
+* holds values the global one may not take.
+*/
 function cloneBody(body) {
-	if (typeof FormData !== "undefined" && body instanceof FormData) {
-		const copy = new FormData();
+	const tag = tagOf(body);
+	if (tag !== "FormData" && tag !== "URLSearchParams") return body;
+	const Own = body.constructor;
+	try {
+		if (tag === "URLSearchParams") return new Own(String(body));
+		const copy = new Own();
 		for (const [name, value] of body) copy.append(name, value);
 		return copy;
+	} catch {
+		return body;
 	}
-	if (body instanceof URLSearchParams) return new URLSearchParams(body);
-	return body;
 }
 /**
 * Interceptors mutate the context in place. A middleware that calls `next`
 * again (retry) must not see the previous attempt's changes, so every attempt
 * starts from a fresh copy of the headers and of a FormData/URLSearchParams body.
 */
-function cloneContext({ url, init, meta, fetch }) {
+function cloneContext({ url, init, meta, fetchFn }) {
 	const copy = {
 		...init,
 		headers: toHeaderRecord(init.headers)
@@ -49,7 +58,7 @@ function cloneContext({ url, init, meta, fetch }) {
 		init: copy,
 		meta: { ...meta }
 	};
-	if (fetch) out.fetch = fetch;
+	if (fetchFn) out.fetchFn = fetchFn;
 	return out;
 }
 /**
@@ -66,11 +75,20 @@ function normalize(ctx, previous) {
 		},
 		meta: ctx.meta ?? previous.meta
 	};
-	const fetch = ctx.fetch ?? previous.fetch;
-	if (fetch) out.fetch = fetch;
+	const fetchFn = ctx.fetchFn ?? previous.fetchFn;
+	if (fetchFn) out.fetchFn = fetchFn;
 	return out;
 }
 /**
+* The 1.x name of `fetchFn`. TypeScript does not flag it on a spread
+* (`{ ...ctx, fetch }`), and ignored, a test's mock would be passed over for
+* the real network.
+*/
+function refuseFetchField(ctx, problem, fix) {
+	if (ctx.fetch === void 0) return;
+	throw new TypeError(`arthron: ${problem}, which is requestContext.fetchFn since 2.0 — ${fix} { ...requestContext, fetchFn }`);
+}
+/**
 * A plugin written in JS (or with a cast) that forgets to return would hand
 * `undefined` on — and an error interceptor's would be what the caller
 * catches. Name the plugin slot instead.
@@ -80,7 +98,9 @@ function returned(value, who, what, cause, verb = "returned") {
 	throw new TypeError(`arthron: ${who} ${verb} ${value} — return ${what}`, cause === void 0 ? void 0 : { cause });
 }
 /**
-* Owns the order of one request.
+* Owns the order of every request a client sends. The plugins are sorted
+* into their slots once, when the client is created — a client's plugins
+* never change.
 *
 * Middleware wraps the whole call, outermost first in registration order.
 * Each attempt below it runs request interceptors → `send` → response
@@ -88,56 +108,61 @@ function returned(value, who, what, cause, verb = "returned") {
 * they return is thrown. Anything else that is thrown — cancellation, a bug
 * in a plugin — propagates untouched.
 */
-async function runPipeline(plugins, ctx, send) {
+function createPipeline(plugins) {
 	const middlewares = [];
-	const request = [];
-	const response = [];
-	const error = [];
+	const requestInterceptors = [];
+	const responseInterceptors = [];
+	const errorInterceptors = [];
 	for (const plugin of plugins) {
 		if (plugin.middleware) middlewares.push(plugin.middleware);
-		if (plugin.request) request.push(plugin.request);
-		if (plugin.response) response.push(plugin.response);
-		if (plugin.error) error.push(plugin.error);
+		if (plugin.requestInterceptor) requestInterceptors.push(plugin.requestInterceptor);
+		if (plugin.responseInterceptor) responseInterceptors.push(plugin.responseInterceptor);
+		if (plugin.errorInterceptor) errorInterceptors.push(plugin.errorInterceptor);
 	}
-	const attempt = async (input) => {
+	const attempt = async (input, send) => {
 		let current = cloneContext(input);
-		for (const interceptor of request) current = normalize(returned(await interceptor(current), "a request interceptor", "the context (ctx or a changed copy)"), current);
+		for (const interceptor of requestInterceptors) {
+			const changed = returned(await interceptor(current), "a request interceptor", "the context (requestContext or a changed copy)");
+			refuseFetchField(changed, "a request interceptor set requestContext.fetch", "return");
+			current = normalize(changed, current);
+		}
 		let res;
 		try {
 			res = await send(current);
 		} catch (thrown) {
 			if (!isArthronError(thrown)) throw thrown;
 			let err = thrown;
-			for (const interceptor of error) err = returned(await interceptor(err, current), "an error interceptor", "the error (err or a changed one)", thrown);
+			for (const interceptor of errorInterceptors) err = returned(await interceptor(err, current), "an error interceptor", "the error (error or a changed one)", thrown);
 			throw err;
 		}
-		for (const interceptor of response) res = returned(await interceptor(res, current), "a response interceptor", "the Response (res or a new one)");
+		for (const interceptor of responseInterceptors) res = returned(await interceptor(res, current), "a response interceptor", "the Response (response or a new one)");
 		return res;
 	};
-	const dispatch = async (index, input) => {
+	const runFrom = async (index, input, send) => {
 		const middleware = middlewares[index];
-		if (!middleware) return attempt(input);
-		return returned(await middleware(input, (next) => {
+		if (!middleware) return attempt(input, send);
+		return returned(await middleware(input, (passed) => {
+			refuseFetchField(passed, "a middleware passed requestContext.fetch to next", "pass");
 			const ctx = {
-				...next,
-				meta: next.meta ?? input.meta
+				...passed,
+				meta: passed.meta ?? input.meta
 			};
-			const fetch = next.fetch ?? input.fetch;
-			if (fetch) ctx.fetch = fetch;
-			return dispatch(index + 1, ctx);
-		}), "a middleware", "the Response, usually `return next(ctx)`", void 0, "resolved with");
+			const fetchFn = passed.fetchFn ?? input.fetchFn;
+			if (fetchFn) ctx.fetchFn = fetchFn;
+			return runFrom(index + 1, ctx, send);
+		}), "a middleware", "the Response, usually `return next(requestContext)`", void 0, "resolved with");
 	};
-	return dispatch(0, ctx);
+	return (ctx, send) => runFrom(0, ctx, send);
 }
 //#endregion
 //#region src/response/schema-validation.ts
 const pathOf = (issue) => (issue.path ?? []).map((part) => String(typeof part === "object" && part !== null ? part.key : part)).join(".");
 /**
-* `.json(schema)` got a body that does not match. Not an ArthronError: the
-* request succeeded — the data is what is wrong.
+* `.json(schema)` got a body that does not match the schema. Not an
+* ArthronError: the request succeeded — the data is what is wrong.
 */
-var SchemaError = class extends Error {
-	name = "SchemaError";
+var SchemaMismatchError = class extends Error {
+	name = "SchemaMismatchError";
 	/** Every problem the validator reported, with the path to it. */
 	issues;
 	constructor(issues) {
@@ -148,15 +173,16 @@ var SchemaError = class extends Error {
 		this.issues = issues;
 	}
 };
-/** Validate `data`; resolve with the schema's output or reject with a SchemaError. */
-async function validate(schema, data) {
-	const result = await schema["~standard"].validate(data);
-	if (result.issues) throw new SchemaError(result.issues);
+/** Validate `body`; resolve with the schema's output or reject with a SchemaMismatchError. */
+async function validate(schema, body) {
+	const result = await schema["~standard"].validate(body);
+	if (result.issues) throw new SchemaMismatchError(result.issues);
 	return result.value;
 }
 //#endregion
 //#region src/response/stream-parser.ts
 const DEFAULT_LIMIT = 8388608;
+const DECODE_CHUNK_BYTES = 16384;
 /**
 * Yield the body line by line, reassembling lines split across chunks. Only
 * the newly arrived text is scanned, so a long line costs linear time; a line
@@ -173,28 +199,37 @@ async function* lines(response, maxLineLength) {
 	const breaks = /\r\n|\r|\n/g;
 	let pending = "";
 	let afterCR = false;
+	const scan = function* (decoded) {
+		let text = decoded;
+		if (afterCR && text.startsWith("\n")) {
+			text = text.slice(1);
+			afterCR = false;
+		}
+		if (text) afterCR = text.endsWith("\r");
+		let start = 0;
+		breaks.lastIndex = 0;
+		for (let m = breaks.exec(text); m; m = breaks.exec(text)) {
+			yield checked(pending + text.slice(start, m.index));
+			pending = "";
+			start = breaks.lastIndex;
+		}
+		pending = checked(pending + text.slice(start));
+	};
 	try {
 		while (true) {
 			const { value, done } = await reader.read();
-			let text = decoder.decode(value, { stream: !done });
-			if (afterCR && text.startsWith("\n")) {
-				text = text.slice(1);
-				afterCR = false;
+			if (value) for (let offset = 0; offset < value.byteLength; offset += DECODE_CHUNK_BYTES) {
+				const part = value.subarray(offset, offset + DECODE_CHUNK_BYTES);
+				yield* scan(decoder.decode(part, { stream: true }));
 			}
-			if (text) afterCR = text.endsWith("\r");
-			let start = 0;
-			breaks.lastIndex = 0;
-			for (let m = breaks.exec(text); m; m = breaks.exec(text)) {
-				yield checked(pending + text.slice(start, m.index));
-				pending = "";
-				start = breaks.lastIndex;
+			if (done) {
+				yield* scan(decoder.decode());
+				break;
 			}
-			pending = checked(pending + text.slice(start));
-			if (done) break;
 		}
 		if (pending) yield pending;
 	} finally {
-		await reader.cancel().catch(() => {});
+		reader.cancel().catch(() => {});
 		reader.releaseLock();
 	}
 }
@@ -206,24 +241,24 @@ async function* lines(response, maxLineLength) {
 * Provider sentinels like
 * `[DONE]` are passed through untouched — they are not part of the spec.
 */
-async function* parseSse(response, { maxLineLength = DEFAULT_LIMIT, maxEventSize = DEFAULT_LIMIT } = {}) {
+async function* parseSse(response, { maxLineLength = DEFAULT_LIMIT, maxDataLength = DEFAULT_LIMIT } = {}) {
 	let data = [];
 	let size = 0;
-	let event;
+	let type;
 	let id;
 	let lastEventId = "";
-	let retry;
+	let reconnectionTime;
 	const flush = () => {
 		const out = data.length === 0 ? void 0 : {
+			type: type || "message",
 			data: data.join("\n"),
 			lastEventId
 		};
-		if (out && event !== void 0) out.event = event;
 		if (out && id !== void 0) out.id = id;
-		if (out && retry !== void 0) out.retry = retry;
+		if (out && reconnectionTime !== void 0) out.reconnectionTime = reconnectionTime;
 		data = [];
 		size = 0;
-		event = id = void 0;
+		type = id = void 0;
 		return out;
 	};
 	for await (const line of lines(response, maxLineLength)) {
@@ -240,16 +275,16 @@ async function* parseSse(response, { maxLineLength = DEFAULT_LIMIT, maxEventSize
 		switch (field) {
 			case "data":
 				size += value.length + 1;
-				if (size > maxEventSize + 1) throw new RangeError(`arthron: an SSE event's data is longer than ${maxEventSize} characters — pass a larger maxEventSize to .sse() if that is expected`);
+				if (size > maxDataLength + 1) throw new RangeError(`arthron: an SSE event's data is longer than ${maxDataLength} characters — pass a larger maxDataLength to .sse() if that is expected`);
 				data.push(value);
 				break;
 			case "event":
-				event = value;
+				type = value;
 				break;
 			case "id":
 				if (!value.includes("\0")) id = lastEventId = value;
 				break;
-			case "retry": if (/^\d+$/.test(value)) retry = Number(value);
+			case "retry": if (/^\d+$/.test(value)) reconnectionTime = Number(value);
 		}
 	}
 }
@@ -264,7 +299,7 @@ async function* parseNdjson(response, { maxLineLength = DEFAULT_LIMIT } = {}) {
 	}
 }
 //#endregion
-//#region src/response/arthron-promise.ts
+//#region src/response/response-promise.ts
 /** Defer the Response until iteration starts, so the helper itself never rejects. */
 function iterate(promise, parse, signal) {
 	promise.catch(() => {});
@@ -280,14 +315,14 @@ function iterate(promise, parse, signal) {
 * Sugar over `Promise<Response>`: `.json()` is `(await p).json()`. Awaiting
 * without a helper still yields the untouched `Response`.
 */
-function toArthronPromise(promise, signal) {
-	const read = (body) => promise.then(body).catch((error) => {
+function toResponsePromise(promise, signal) {
+	const read = (readAs) => promise.then(readAs).catch((error) => {
 		throw cancellationError(error, signal);
 	});
 	return Object.assign(promise, {
 		json: ((schema) => read(async (res) => {
-			const data = await res.json();
-			return schema ? validate(schema, data) : data;
+			const body = await res.json();
+			return schema ? validate(schema, body) : body;
 		})),
 		text: () => read((res) => res.text()),
 		blob: () => read((res) => res.blob()),
@@ -298,19 +333,75 @@ function toArthronPromise(promise, signal) {
 	});
 }
 //#endregion
-//#region src/client/resolve-config.ts
+//#region src/pipeline/create-plugin.ts
+/** The slots a plugin may fill. */
+const SLOTS = [
+	"middleware",
+	"requestInterceptor",
+	"responseInterceptor",
+	"errorInterceptor"
+];
+/** 1.x slot names: a plugin that still uses one would have it ignored. */
+const REPLACED_SLOTS = {
+	request: "requestInterceptor",
+	response: "responseInterceptor",
+	error: "errorInterceptor"
+};
+/**
+* Throws a TypeError for what a plugin can get wrong where TypeScript does
+* not look — JS, a cast, an object built at runtime: not an object, no
+* pluginName, a key it does not take (a typo, a 1.x name), a slot that is not
+* a function, or nothing to run. `createPlugin` runs it where the plugin is
+* written; `use` and `plugins` run it again on whatever they are given.
+*/
+function checkPlugin(plugin) {
+	if (typeof plugin !== "object" || plugin === null) throw new TypeError(`arthron: a plugin is an object, got ${plugin === null ? "null" : `a ${typeof plugin}`} — e.g. createPlugin({ pluginName: "trace", middleware: fn })`);
+	const fields = plugin;
+	const own = (key) => Object.hasOwn(fields, key) ? fields[key] : void 0;
+	const given = fields.pluginName ?? own("name");
+	const label = typeof given === "string" && given !== "" ? `plugin "${given}"` : "a plugin";
+	if (own("name") !== void 0) throw new TypeError(`arthron: ${label}: the name field is called pluginName since 2.0 — rename it in the plugin`);
+	for (const [old, now] of Object.entries(REPLACED_SLOTS)) if (own(old) !== void 0) throw new TypeError(`arthron: ${label}: the ${old} interceptor is called ${now} since 2.0 — rename it in the plugin`);
+	if (typeof fields.pluginName !== "string" || fields.pluginName === "") throw new TypeError("arthron: a plugin needs a pluginName — e.g. createPlugin({ pluginName: \"trace\", … })");
+	for (const key of Object.keys(fields)) if (key !== "pluginName" && !SLOTS.includes(key)) throw new TypeError(`arthron: ${label} has an unknown key "${key}" — use pluginName, middleware, requestInterceptor, responseInterceptor or errorInterceptor; keep state in a closure, in a function that returns createPlugin({ … })`);
+	for (const slot of SLOTS) if (fields[slot] !== void 0 && typeof fields[slot] !== "function") throw new TypeError(`arthron: ${label}: ${slot} must be a function`);
+	if (SLOTS.every((slot) => fields[slot] === void 0)) throw new TypeError(`arthron: ${label} has nothing to run — add middleware, requestInterceptor, responseInterceptor or errorInterceptor`);
+}
+/**
+* A plugin, checked where it is written and typed without annotations:
+* `createPlugin({ pluginName: "trace", requestInterceptor: (requestContext) => … })`.
+*/
+function createPlugin(plugin) {
+	checkPlugin(plugin);
+	return plugin;
+}
+function aFunction(value, helper, example) {
+	if (typeof value !== "function") throw new TypeError(`arthron: ${helper} needs a function — e.g. ${example}`);
+	return value;
+}
+/** A middleware written on its own, typed without annotations. */
+const createMiddleware = (middleware) => aFunction(middleware, "createMiddleware", "createMiddleware((requestContext, next) => next(requestContext))");
+/** A request interceptor written on its own, typed without annotations. */
+const createRequestInterceptor = (interceptor) => aFunction(interceptor, "createRequestInterceptor", "createRequestInterceptor((requestContext) => requestContext)");
+/** A response interceptor written on its own, typed without annotations. */
+const createResponseInterceptor = (interceptor) => aFunction(interceptor, "createResponseInterceptor", "createResponseInterceptor((response) => response)");
+/** An error interceptor written on its own, typed without annotations. */
+const createErrorInterceptor = (interceptor) => aFunction(interceptor, "createErrorInterceptor", "createErrorInterceptor((error) => error)");
+//#endregion
+//#region src/client/resolve-options.ts
 /**
-* Config keys that configure arthron itself; every other key is a fetch
-* default. Typed so that a new config key fails to compile until it is
-* listed here — otherwise it would be sent to fetch.
+* Option keys that configure arthron itself; every other key is a fetch
+* default. Typed so that a new option key fails to compile until it is
+* listed here — otherwise it would be sent to fetch. `headers` is a fetch
+* field too, but one with arthron's own merge rules.
 */
 const OWN_KEYS = {
 	baseURL: true,
-	allowAbsoluteUrls: true,
+	allowedOrigins: true,
 	headers: true,
-	fetch: true,
-	use: true,
-	errorDetail: true,
+	fetchFn: true,
+	plugins: true,
+	extractDescription: true,
 	throwOn: true
 };
 /** Fields that belong to one request, refused as client defaults. */
@@ -320,15 +411,27 @@ const PER_CALL_ONLY = [
 	"method"
 ];
 /**
-* Add plugins to a list. A named plugin takes the place of the one already
-* there with that name — same position, so a replaced `logging()` stays
-* outermost and a second `retry()` does not multiply attempts. Unnamed
-* plugins append.
+* 1.x config keys and what replaced them. Left alone, each would become an
+* unknown key, then a fetch default, and be ignored: plugins not applied, a
+* test's fake fetch passed over for the real network.
+*/
+const REPLACED = {
+	fetch: "fetchFn",
+	use: "plugins",
+	errorDetail: "extractDescription",
+	allowAbsoluteUrls: "allowedOrigins"
+};
+/**
+* Add plugins to a list, each checked as `createPlugin` checks it. A plugin
+* takes the place of the one already there with its pluginName — same position,
+* so a replaced `logging()` stays outermost and a second `retry()` does not
+* multiply attempts. Other names append.
 */
 function addPlugins(base, added) {
 	const out = [...base];
 	for (const plugin of added) {
-		const at = plugin.name === void 0 ? -1 : out.findIndex((p) => p.name === plugin.name);
+		checkPlugin(plugin);
+		const at = out.findIndex((p) => p.pluginName === plugin.pluginName);
 		if (at === -1) out.push(plugin);
 		else out[at] = plugin;
 	}
@@ -339,31 +442,57 @@ function fetchDefaults(config) {
 	return Object.fromEntries(Object.entries(config).filter(([key, value]) => value !== void 0 && !(key in OWN_KEYS)));
 }
 /** Normalize once so `extend` can merge headers and add plugins cheaply. */
-function resolveConfig(config) {
+function resolveClientOptions(config) {
 	for (const key of PER_CALL_ONLY) if (config[key] !== void 0) throw new TypeError(`arthron: ${key} cannot be a client default, it belongs to one request — pass it per call (api.get(path, { signal }), api.post(path, body), api.request(path, { method }))`);
-	const { headers, use, ...rest } = config;
-	return {
+	for (const [old, now] of Object.entries(REPLACED)) if (config[old] !== void 0) throw new TypeError(`arthron: the ${old} option was replaced by ${now} in 2.0 — pass arthron({ ${now} })`);
+	const { headers, plugins, allowedOrigins, ...rest } = config;
+	if (rest.fetchFn !== void 0 && typeof rest.fetchFn !== "function") throw new TypeError(`arthron: fetchFn must be a function with fetch's signature, got ${kindOf(rest.fetchFn)} — e.g. arthron({ fetchFn: fetch })`);
+	if (rest.baseURL !== void 0) checkBaseURL(rest.baseURL);
+	if (allowedOrigins !== void 0 && !Array.isArray(allowedOrigins)) throw new TypeError(`arthron: allowedOrigins takes a list of URLs, got ${kindOf(allowedOrigins)} — e.g. allowedOrigins: ["https://cdn.example.com"]`);
+	const record = toHeaderRecord(headers);
+	if (rest.baseURL === void 0 && allowedOrigins !== void 0 && allowedOrigins.length > 0 && Object.keys(record).length > 0) throw new TypeError("arthron: config headers go to baseURL's origin only, and this client has allowedOrigins but no baseURL — set baseURL, or pass these headers per call");
+	const resolved = {
 		...rest,
-		headers: toHeaderRecord(headers),
-		use: addPlugins([], use ?? [])
+		headers: record,
+		plugins: addPlugins([], plugins ?? [])
 	};
+	if (allowedOrigins !== void 0) resolved.allowedOrigins = [...allowedOrigins];
+	return resolved;
+}
+/** "a string", "an object", "null" — for messages about a value of the wrong kind. */
+function kindOf(value) {
+	if (value === null) return "null";
+	const kind = typeof value;
+	return /^[aeiou]/.test(kind) ? `an ${kind}` : `a ${kind}`;
+}
+/**
+* An http(s) baseURL must name a host. `https://${HOST}/api` with HOST unset
+* is "https:///api", which a URL parser reads as host "api" — and a relative
+* path appended to "https://" chooses the host itself.
+*/
+function checkBaseURL(baseURL) {
+	if (!/^https?:\/\//i.test(baseURL)) return;
+	if (!/^https?:\/\/(?:[/\\?#]|$)/i.test(baseURL) && httpOrigin(baseURL)) return;
+	throw new TypeError(`arthron: baseURL "${withoutSecrets(baseURL)}" has no host — pass a full URL such as "https://api.example.com" (an unset environment variable?)`);
 }
 //#endregion
 //#region src/client/send.ts
 /**
 * The global fetch rejects a malformed URL or method with a TypeError that
-* looks just like a network failure (status 0, retried). A bodiless `Request`
-* runs the same checks first, so those become argument errors instead. Only
-* for the global fetch: an injected one owns its URL rules (SvelteKit's
-* server-side `fetch` accepts relative URLs, for one).
+* looks just like a network failure (status 0, retried). Once fetch has
+* failed, a bodiless `Request` runs the same checks, so those become argument
+* errors instead — at no cost to a call that goes through. Only for the
+* global fetch: an injected one owns its URL rules (SvelteKit's server-side
+* `fetch` accepts relative URLs, for one).
 */
 function assertSendable(url, method) {
 	if (typeof Request !== "function") return;
 	try {
 		new Request(url, { method });
 	} catch (cause) {
+		const safeCause = redactErrorUrl(cause, url);
 		const reason = redactUrlIn(cause instanceof Error ? cause.message : String(cause), url);
-		throw new TypeError(`arthron: cannot send ${method} ${redactUrl(url)} (${reason}) — use an absolute URL or a baseURL with a scheme (https://…), and a valid HTTP method`, { cause });
+		throw new TypeError(`arthron: cannot send ${method} ${redactUrl(url)} (${reason}) — use an absolute URL or a baseURL with a scheme (https://…), and a valid HTTP method`, { cause: safeCause });
 	}
 }
 /**
@@ -386,23 +515,23 @@ function failedByDefault(res, init) {
 }
 /** The one place a failure becomes an ArthronError. Cancellation passes through. */
 async function send(resolved, ctx, throwOn) {
-	const fetchImpl = ctx.fetch ?? resolved.fetch ?? globalThis.fetch;
-	if (resolved.fetch === void 0) {
-		const method = ctx.init.method ?? "GET";
-		assertSendable(ctx.url, method);
-		assertStreamable(ctx.url, method, ctx.init.body);
-	}
+	const fetchFn = ctx.fetchFn ?? resolved.fetchFn ?? globalThis.fetch;
+	if (typeof fetchFn !== "function") throw new TypeError(`arthron: requestContext.fetchFn must be a function with fetch's signature, got ${fetchFn === null ? "null" : `a ${typeof fetchFn}`} — a plugin set it; return { ...requestContext, fetchFn: fn }`);
+	const runtimeFetch = resolved.fetchFn === void 0;
+	const method = ctx.init.method ?? "GET";
+	if (runtimeFetch) assertStreamable(ctx.url, method, ctx.init.body);
 	const { signal } = ctx.init;
 	let res;
 	try {
-		res = await fetchImpl(ctx.url, ctx.init);
+		res = await fetchFn(ctx.url, ctx.init);
 	} catch (thrown) {
 		if (isCancellation(thrown, signal)) throw cancellationError(thrown, signal);
+		if (runtimeFetch) assertSendable(ctx.url, method);
 		throw networkError(thrown, ctx);
 	}
 	if (res.ok) return res;
 	if (!(throwOn ? throwOn(res) : failedByDefault(res, ctx.init))) return res;
-	const error = await responseError(res, ctx, resolved.errorDetail);
+	const error = await responseError(res, ctx, resolved.extractDescription);
 	if (signal?.aborted) throw signal.reason;
 	throw error;
 }
@@ -421,19 +550,30 @@ const STANDARD_METHODS = /* @__PURE__ */ new Set([
 	"QUERY"
 ]);
 /**
-* Build a client from config. The result is immutable — `use` and `extend`
+* 1.x per-call option names and what replaced them. Left in init they would
+* reach fetch and be ignored: {id} sent unfilled, the query left off.
+*/
+const REPLACED_PER_CALL = {
+	path: "pathParams",
+	params: "queryParams"
+};
+/**
+* Build a client from its options. The result is immutable — `use` and `extend`
 * return new clients and never touch the one they were called on.
 */
-function arthron(config = {}) {
-	const resolved = resolveConfig(config);
+function arthron(clientOptions = {}) {
+	const resolved = resolveClientOptions(clientOptions);
 	const initDefaults = fetchDefaults(resolved);
-	const dispatch = (path, method, rawBody, { params, headers: callHeaders, meta, throwOn = resolved.throwOn, path: pathValues, ...init }) => {
+	const allowed = resolved.allowedOrigins && originSet(resolved.allowedOrigins);
+	const pipeline = createPipeline(resolved.plugins);
+	const call = (path, method, rawBody, { queryParams, headers: callHeaders, meta, throwOn = resolved.throwOn, pathParams, ...init }) => {
 		try {
+			for (const [old, now] of Object.entries(REPLACED_PER_CALL)) if (init[old] !== void 0) throw new TypeError(`arthron: the ${old} option was replaced by ${now} in 2.0 — pass { ${now}: { … } }`);
 			const upper = method.toUpperCase();
 			const verb = STANDARD_METHODS.has(upper) ? upper : method;
-			if (rawBody !== void 0 && BODYLESS_METHODS.has(upper)) throw new TypeError(`arthron: ${upper} requests cannot carry a body — send it as params (query) or switch to POST`);
-			if (pathValues) path = fillPath(path, pathValues);
-			const url = resolveUrl(resolved.baseURL, path, params, resolved.allowAbsoluteUrls);
+			if (rawBody !== void 0 && BODYLESS_METHODS.has(upper)) throw new TypeError(`arthron: ${upper} requests cannot carry a body — send it as queryParams or switch to POST`);
+			if (pathParams) path = fillPath(path, pathParams);
+			const url = resolveUrl(resolved.baseURL, path, queryParams, allowed);
 			const defaults = leavesBase(resolved.baseURL, path) ? void 0 : resolved.headers;
 			const { body, headers } = serializeBody(rawBody, mergeHeaders(defaults, callHeaders));
 			const requestInit = {
@@ -444,66 +584,44 @@ function arthron(config = {}) {
 			};
 			if (body !== void 0) requestInit.body = body;
 			if (isReadableStream(body)) Object.assign(requestInit, { duplex: "half" });
-			return toArthronPromise(runPipeline(resolved.use, {
+			return toResponsePromise(pipeline({
 				url,
 				init: requestInit,
 				meta: { ...meta },
-				fetch: resolved.fetch ?? globalThis.fetch
+				fetchFn: resolved.fetchFn ?? globalThis.fetch
 			}, (ctx) => send(resolved, ctx, throwOn)), init.signal);
 		} catch (thrown) {
-			return toArthronPromise(Promise.reject(thrown));
+			return toResponsePromise(Promise.reject(thrown));
 		}
 	};
-	const derive = (next) => {
+	const derive = (changes) => {
 		return arthron({
 			...resolved,
-			...next,
-			headers: mergeHeaders(resolved.headers, next.headers),
-			use: addPlugins(resolved.use, next.use ?? [])
+			...changes,
+			headers: mergeHeaders(resolved.headers, changes.headers),
+			plugins: addPlugins(resolved.plugins, changes.plugins ?? [])
 		});
 	};
 	return {
-		get: (path, init = {}) => dispatch(path, "GET", void 0, init),
-		delete: (path, init = {}) => dispatch(path, "DELETE", void 0, init),
-		head: (path, init = {}) => dispatch(path, "HEAD", void 0, init),
-		post: (path, body, init = {}) => dispatch(path, "POST", body, init),
-		put: (path, body, init = {}) => dispatch(path, "PUT", body, init),
-		patch: (path, body, init = {}) => dispatch(path, "PATCH", body, init),
-		query: (path, body, init = {}) => dispatch(path, "QUERY", body, init),
-		request: (path, init) => {
-			const { method, body, ...rest } = init;
-			if (!method) return toArthronPromise(Promise.reject(/* @__PURE__ */ new TypeError("arthron: request() needs init.method — e.g. request(path, { method: \"OPTIONS\" }); use get/post/... for the common verbs")));
-			return dispatch(path, method, body, rest);
+		get: (path, requestOptions = {}) => call(path, "GET", void 0, requestOptions),
+		delete: (path, requestOptions = {}) => call(path, "DELETE", void 0, requestOptions),
+		head: (path, requestOptions = {}) => call(path, "HEAD", void 0, requestOptions),
+		post: (path, body, requestOptions = {}) => call(path, "POST", body, requestOptions),
+		put: (path, body, requestOptions = {}) => call(path, "PUT", body, requestOptions),
+		patch: (path, body, requestOptions = {}) => call(path, "PATCH", body, requestOptions),
+		query: (path, body, requestOptions = {}) => call(path, "QUERY", body, requestOptions),
+		request: (path, requestOptions) => {
+			const { method, body, ...rest } = requestOptions;
+			if (!method) return toResponsePromise(Promise.reject(/* @__PURE__ */ new TypeError("arthron: request() needs a method — e.g. request(path, { method: \"OPTIONS\" }); use get/post/... for the common verbs")));
+			return call(path, method, body, rest);
 		},
-		use: (...plugins) => derive({ use: plugins }),
-		extend: (next) => derive(next),
-		without: (...names) => arthron({
+		use: (...plugins) => derive({ plugins }),
+		extend: (changes) => derive(changes),
+		without: (...pluginNames) => arthron({
 			...resolved,
-			use: resolved.use.filter((p) => p.name === void 0 || !names.includes(p.name))
+			plugins: resolved.plugins.filter((p) => !pluginNames.includes(p.pluginName))
 		})
 	};
 }
 //#endregion
-//#region src/pipeline/define-plugin.ts
-/** Identity helper: gives a middleware written in its own file the right parameter types. */
-const defineMiddleware = (middleware) => middleware;
-/** Identity helpers for each interceptor kind — `defineInterceptor.request(fn)` etc. */
-const defineInterceptor = {
-	request: (interceptor) => interceptor,
-	response: (interceptor) => interceptor,
-	error: (interceptor) => interceptor
-};
-/** Identity helper: type-checks a plugin object literal without an annotation. */
-const definePlugin = (plugin) => plugin;
-//#endregion
-//#region src/index.ts
-/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
-const logging = logging$1;
-/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
-const retry = retry$1;
-/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
-const timeout = timeout$1;
-//#endregion
-export { ArthronError, SchemaError, arthron, defineInterceptor, defineMiddleware, definePlugin, isArthronError, logging, retry, timeout };
-
-//# sourceMappingURL=index.mjs.map
+export { ArthronError, SchemaMismatchError, arthron, createErrorInterceptor, createMiddleware, createPlugin, createRequestInterceptor, createResponseInterceptor, isArthronError };