zlient 3.3.3 → 4.0.0

package/dist/index.cjs

@@ -5,7 +5,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * Use this when you don't need authentication.
 */
 var NoAuth = class {
-	async apply(_req) {}
+	apply(_ctx) {}
 };
 /**
 * API Key authentication provider.
@@ -26,18 +26,18 @@ var ApiKeyAuth = class {
 		if (!opts.header && !opts.query) throw new Error("ApiKeyAuth requires either \"header\" or \"query\" option");
 		if (opts.header && opts.query) throw new Error("ApiKeyAuth cannot use both \"header\" and \"query\" options");
 	}
-	apply({ url, init }) {
+	apply(ctx) {
 		const value = this.opts.value;
-		if (this.opts.header) if (init.headers instanceof Headers) init.headers.set(this.opts.header, value);
-		else if (Array.isArray(init.headers)) init.headers.push([this.opts.header, value]);
-		else init.headers = {
-			...init.headers,
+		if (this.opts.header) if (ctx.init.headers instanceof Headers) ctx.init.headers.set(this.opts.header, value);
+		else if (Array.isArray(ctx.init.headers)) ctx.init.headers.push([this.opts.header, value]);
+		else ctx.init.headers = {
+			...ctx.init.headers,
 			[this.opts.header]: value
 		};
 		else if (this.opts.query) {
-			const u = new URL(url);
+			const u = new URL(ctx.url);
 			u.searchParams.set(this.opts.query, value);
-			init.__urlOverride = u.toString();
+			ctx.url = u.toString();
 		}
 	}
 };
@@ -60,14 +60,14 @@ var BearerTokenAuth = class {
 	constructor(getToken) {
 		this.getToken = getToken;
 	}
-	async apply({ init }) {
+	async apply(ctx) {
 		const token = await this.getToken();
 		if (!token) throw new Error("BearerTokenAuth: token is empty or undefined");
 		const authHeader = `Bearer ${token}`;
-		if (init.headers instanceof Headers) init.headers.set("Authorization", authHeader);
-		else if (Array.isArray(init.headers)) init.headers.push(["Authorization", authHeader]);
-		else init.headers = {
-			...init.headers,
+		if (ctx.init.headers instanceof Headers) ctx.init.headers.set("Authorization", authHeader);
+		else if (Array.isArray(ctx.init.headers)) ctx.init.headers.push(["Authorization", authHeader]);
+		else ctx.init.headers = {
+			...ctx.init.headers,
 			Authorization: authHeader
 		};
 	}
@@ -320,6 +320,9 @@ const HTTPStatusCode = {
 	NOT_EXTENDED: 510,
 	NETWORK_AUTHENTICATION_REQUIRED: 511
 };
+function captureStackTrace(targetObject, constructorOpt) {
+	Error.captureStackTrace?.(targetObject, constructorOpt);
+}
 /**
 * Custom error class for API-related errors.
 * Includes HTTP status codes, response details, and validation errors.
@@ -337,10 +340,12 @@ var ApiError = class ApiError extends Error {
 		super(message);
 		this.name = "ApiError";
 		this.status = options?.status;
+		this.method = options?.method;
+		this.url = options?.url;
 		this.details = options?.details;
 		this.cause = options?.cause;
 		this.validationIssues = options?.validationIssues;
-		if (Error.captureStackTrace) Error.captureStackTrace(this, ApiError);
+		captureStackTrace(this, ApiError);
 	}
 	/**
 	* Check if this is a validation error (has validationIssues)
@@ -368,6 +373,8 @@ var ApiError = class ApiError extends Error {
 			name: this.name,
 			message: this.message,
 			status: this.status,
+			method: this.method,
+			url: this.url,
 			details: this.details,
 			validationIssues: this.validationIssues,
 			stack: this.stack
@@ -383,7 +390,7 @@ var SchemaDefinitionError = class SchemaDefinitionError extends Error {
 		super(`No schema defined for status code ${status}`);
 		this.status = status;
 		this.name = "SchemaDefinitionError";
-		if (Error.captureStackTrace) Error.captureStackTrace(this, SchemaDefinitionError);
+		captureStackTrace(this, SchemaDefinitionError);
 	}
 };
 /**
@@ -405,15 +412,34 @@ function toQueryString(q) {
 		const s = q.toString();
 		return s ? `?${s}` : "";
 	}
+	if (typeof q !== "object") throw new TypeError("Query parameters must be a URLSearchParams instance or an object");
 	const params = new URLSearchParams();
 	Object.entries(q).forEach(([k, v]) => {
-		if (v !== void 0) params.append(k, String(v));
+		if (v !== void 0 && v !== null) params.append(k, String(v));
 	});
 	const s = params.toString();
 	return s ? `?${s}` : "";
 }
+function toRequestQuery(q) {
+	if (q === void 0 || q instanceof URLSearchParams) return q;
+	if (q !== null && typeof q === "object") return q;
+	throw new TypeError("Query parameters must be a URLSearchParams instance or an object");
+}
 //#endregion
 //#region lib/validation.ts
+function formatPath(path) {
+	if (!path || path.length === 0) return "";
+	return path.map((segment) => {
+		const key = typeof segment === "object" && segment !== null ? segment.key : segment;
+		return typeof key === "symbol" ? key.toString() : String(key);
+	}).join(".");
+}
+function formatValidationIssues(issues, maxIssues = 3) {
+	return issues.slice(0, maxIssues).map((issue) => {
+		const path = formatPath(issue.path);
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
 /**
 * Safely parse/validate data with any Standard Schema-compatible library (Zod, Valibot, ArkType, etc.).
 * Returns a result object with success status and data or issues.
@@ -476,9 +502,19 @@ async function safeParse(schema, data) {
 * }
 * ```
 */
-async function parseOrThrow(schema, data) {
+async function parseOrThrow(schema, data, context = {}) {
 	const result = await schema["~standard"].validate(data);
-	if (result.issues) throw new ApiError(`Validation failed: ${result.issues.map((issue) => issue.message).join(", ")}`, { validationIssues: result.issues });
+	if (result.issues) {
+		const messages = formatValidationIssues(result.issues);
+		const issueCount = result.issues.length > 3 ? ` (${result.issues.length} issues total)` : "";
+		throw new ApiError(`${context.label ? `${context.label} validation failed` : "Validation failed"}: ${messages}${issueCount}`, {
+			status: context.status,
+			method: context.method,
+			url: context.url,
+			details: context.details,
+			validationIssues: result.issues
+		});
+	}
 	return result.value;
 }
 /**
@@ -495,47 +531,132 @@ function isStandardSchema(value) {
 	return "~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"] !== null && schema["~standard"].version === 1 && typeof schema["~standard"].validate === "function";
 }
 //#endregion
+//#region lib/endpoint-utils.ts
+function validateRequiredHeaders(mustHeaderKeys, headers) {
+	if (!mustHeaderKeys || mustHeaderKeys.length === 0) return;
+	const missing = mustHeaderKeys.filter((key) => !headers || !(key in headers));
+	if (missing.length > 0) throw new ApiError(`Missing required header(s): ${missing.join(", ")}`, { details: { missingHeaders: missing } });
+}
+async function parseEndpointValue(schema, value, skipValidation, label) {
+	if (skipValidation || !schema || value === void 0) return value;
+	return parseOrThrow(schema, value, { label });
+}
+function assertRequiredEndpointValue(schema, value, missingParam, message) {
+	if (!schema || value !== void 0) return;
+	throw new ApiError(message, { details: { missingParam } });
+}
+function resolveEndpointPath(path, rawPathParams, parsedPathParams) {
+	if (typeof path !== "function") return path;
+	if (!rawPathParams) throw new ApiError("Path function requires pathParams", { details: { missingParam: "pathParams" } });
+	return path(parsedPathParams);
+}
+/**
+* Shared validation pipeline used by HTTP, SSE, and WebSocket endpoints.
+* Validates request body, query params, and path params; asserts required
+* fields are present; and resolves the final path string.
+*/
+async function validateEndpointParams(config, raw, labels = {}) {
+	const skip = config.advanced?.skipRequestValidation ?? false;
+	const parsedData = await parseEndpointValue(config.request, raw.data, skip, labels.request ?? "Request body");
+	const parsedQuery = await parseEndpointValue(config.query, raw.query, skip, labels.query ?? "Query parameters");
+	const parsedPathParams = await parseEndpointValue(config.pathParams, raw.pathParams, skip, labels.path ?? "Path parameters");
+	assertRequiredEndpointValue(config.request, raw.data, "data", "Missing required request body (data)");
+	assertRequiredEndpointValue(config.pathParams, raw.pathParams, "pathParams", "Missing required path parameters (pathParams)");
+	return {
+		parsedData,
+		parsedQuery,
+		parsedPathParams,
+		pathStr: resolveEndpointPath(config.path, raw.pathParams, parsedPathParams)
+	};
+}
+//#endregion
+//#region lib/event-emitter.ts
+/**
+* Minimal typed event emitter used internally by SSEConnectionImpl and WSConnectionImpl.
+* Not part of the public API.
+*/
+var EventEmitter = class {
+	constructor() {
+		this.handlers = /* @__PURE__ */ new Map();
+	}
+	on(event, handler) {
+		let set = this.handlers.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.handlers.set(event, set);
+		}
+		set.add(handler);
+	}
+	off(event, handler) {
+		this.handlers.get(event)?.delete(handler);
+	}
+	emit(event, ...args) {
+		const set = this.handlers.get(event);
+		if (set) set.forEach((handler) => handler(...args));
+	}
+};
+//#endregion
+//#region lib/realtime-utils.ts
+function looksLikeJsonValue(value) {
+	return value.startsWith("{") && value.endsWith("}") || value.startsWith("[") && value.endsWith("]") || value.startsWith("\"") && value.endsWith("\"");
+}
+function parseRealtimeData(data) {
+	if (typeof data !== "string" || data.length === 0 || !looksLikeJsonValue(data)) return data;
+	try {
+		return JSON.parse(data);
+	} catch {
+		return data;
+	}
+}
+function serializeRealtimeData(data) {
+	if (data != null && typeof data === "object") return JSON.stringify(data);
+	if (typeof data === "string") return data;
+	return String(data);
+}
+//#endregion
 //#region lib/sse/sse-client.ts
-var SSEConnectionImpl = class {
+var SSEConnectionImpl = class extends EventEmitter {
 	constructor(url, responseSchema, options = {}) {
+		super();
 		this.url = url;
 		this.responseSchema = responseSchema;
 		this.options = options;
 		this.abortController = new AbortController();
-		this.handlers = /* @__PURE__ */ new Map();
 		this._readyState = 0;
 		this.start();
 	}
 	async start() {
 		try {
-			let { method = "GET", data, headers = {}, withCredentials, signal, auth, logger } = this.options;
-			let url = this.url;
+			const { method = "GET", data, withCredentials, signal, auth, logger } = this.options;
+			const requestHeaders = {
+				Accept: "text/event-stream",
+				...this.options.headers
+			};
 			const init = {
 				method,
-				headers: {
-					Accept: "text/event-stream",
-					...headers
-				},
+				headers: requestHeaders,
 				signal: signal || this.abortController.signal
 			};
+			let url = this.url;
 			if (auth) {
-				await auth.apply({
+				const ctx = {
 					url,
 					init
-				});
-				if (init.__urlOverride) url = init.__urlOverride;
+				};
+				await auth.apply(ctx);
+				url = ctx.url;
 			}
 			if (withCredentials) init.credentials = "include";
-			if (data) {
+			if (data != null) {
 				init.body = typeof data === "object" ? JSON.stringify(data) : String(data);
-				if (!init.headers || !("Content-Type" in init.headers)) init.headers["Content-Type"] = "application/json";
+				if (!("Content-Type" in requestHeaders)) requestHeaders["Content-Type"] = "application/json";
 			}
 			if (logger) logger.debug("SSE connection initiated", {
 				method,
 				url,
-				hasData: !!data
+				hasData: data != null
 			});
-			const response = await fetch(url, init);
+			const response = await (this.options.fetch ?? globalThis.fetch.bind(globalThis))(url, init);
 			if (!response.ok) {
 				if (logger) logger.error(`SSE request failed with status ${response.status}`, /* @__PURE__ */ new Error("SSE Error"), {
 					url,
@@ -547,39 +668,7 @@ var SSEConnectionImpl = class {
 			this.emit("open", { type: "open" });
 			const reader = response.body?.getReader();
 			if (!reader) throw new Error("Response body is not readable");
-			const decoder = new TextDecoder();
-			let buffer = "";
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				buffer += decoder.decode(value, { stream: true });
-				const parts = buffer.split(/\r\n|\r|\n/);
-				buffer = parts.pop() || "";
-				let eventData = "";
-				let eventName = "message";
-				for (const line of parts) {
-					if (line === "") {
-						if (eventData) {
-							this.handleEvent(eventName, eventData.trim());
-							eventData = "";
-							eventName = "message";
-						}
-						continue;
-					}
-					if (line.startsWith(":")) continue;
-					const colonIndex = line.indexOf(":");
-					if (colonIndex === -1) this.processField(line, "", (name, data) => {
-						eventName = name || eventName;
-						eventData += data;
-					});
-					else {
-						const field = line.slice(0, colonIndex);
-						const value = line.slice(colonIndex + 1).trim();
-						if (field === "event") eventName = value;
-						else if (field === "data") eventData += (eventData ? "\n" : "") + value;
-					}
-				}
-			}
+			await this.readStream(reader);
 		} catch (error) {
 			if (error.name === "AbortError") return;
 			this._readyState = 2;
@@ -588,16 +677,78 @@ var SSEConnectionImpl = class {
 			this._readyState = 2;
 		}
 	}
-	processField(field, value, callback) {
-		if (field === "event") callback(value, "");
-		else if (field === "data") callback("", value);
+	/**
+	* Reads the SSE stream according to the spec:
+	* - Lines are separated by LF, CR, or CRLF
+	* - Empty line dispatches the accumulated event
+	* - Lines starting with ':' are comments
+	* - 'event' field sets the event name; 'data' field accumulates the payload
+	*/
+	async readStream(reader) {
+		const decoder = new TextDecoder();
+		let lineBuffer = "";
+		let eventData = "";
+		let eventName = "message";
+		let lastCharWasCR = false;
+		const processLine = (line) => {
+			if (line === "") {
+				if (eventData) {
+					this.handleEvent(eventName, eventData.endsWith("\n") ? eventData.slice(0, -1) : eventData);
+					eventData = "";
+				}
+				eventName = "message";
+				return;
+			}
+			if (line.startsWith(":")) return;
+			const colonIndex = line.indexOf(":");
+			let field;
+			let value;
+			if (colonIndex === -1) {
+				field = line;
+				value = "";
+			} else {
+				field = line.slice(0, colonIndex);
+				value = line.slice(colonIndex + 1);
+				if (value.startsWith(" ")) value = value.slice(1);
+			}
+			if (field === "event") eventName = value;
+			else if (field === "data") eventData += value + "\n";
+		};
+		const processChunk = (chunk) => {
+			for (let i = 0; i < chunk.length; i++) {
+				const char = chunk[i];
+				if (char === "\n") if (lastCharWasCR) lastCharWasCR = false;
+				else {
+					processLine(lineBuffer);
+					lineBuffer = "";
+				}
+				else if (char === "\r") {
+					processLine(lineBuffer);
+					lineBuffer = "";
+					lastCharWasCR = true;
+				} else {
+					lastCharWasCR = false;
+					lineBuffer += char;
+				}
+			}
+		};
+		while (true) {
+			const { done, value } = await reader.read();
+			processChunk(decoder.decode(value, { stream: true }));
+			if (done) {
+				processChunk(decoder.decode());
+				if (lineBuffer) {
+					processLine(lineBuffer);
+					lineBuffer = "";
+				}
+				if (eventData) this.handleEvent(eventName, eventData.endsWith("\n") ? eventData.slice(0, -1) : eventData);
+				break;
+			}
+		}
 	}
 	async handleEvent(event, data) {
-		let parsedData = data;
+		let parsedData = parseRealtimeData(data);
 		try {
-			if (typeof data === "string") try {
-				parsedData = JSON.parse(data);
-			} catch {}
 			const schema = this.getSchema(event);
 			if (!this.options.skipResponseValidation && schema) parsedData = await parseOrThrow(schema, parsedData);
 			this.emit(event, parsedData);
@@ -607,24 +758,9 @@ var SSEConnectionImpl = class {
 	}
 	getSchema(event) {
 		if (!this.responseSchema) return void 0;
-		if ("~standard" in this.responseSchema) {
-			if (event === "message") return this.responseSchema;
-			return;
-		}
+		if ("~standard" in this.responseSchema) return event === "message" ? this.responseSchema : void 0;
 		return this.responseSchema[event];
 	}
-	on(event, handler) {
-		if (!this.handlers.has(event)) this.handlers.set(event, /* @__PURE__ */ new Set());
-		this.handlers.get(event).add(handler);
-	}
-	off(event, handler) {
-		const handlers = this.handlers.get(event);
-		if (handlers) handlers.delete(handler);
-	}
-	emit(event, ...args) {
-		const handlers = this.handlers.get(event);
-		if (handlers) handlers.forEach((handler) => handler(...args));
-	}
 	close() {
 		this.abortController.abort();
 		this._readyState = 2;
@@ -643,18 +779,16 @@ var SSEEndpointImpl = class {
 	createCall() {
 		return async (params) => {
 			const { query, pathParams, data, headers, signal } = params || {};
-			const skipRequestValidation = this.config.advanced?.skipRequestValidation ?? false;
-			if (!skipRequestValidation && this.config.request && data !== void 0) await parseOrThrow(this.config.request, data);
-			if (!skipRequestValidation && this.config.query && query !== void 0) await parseOrThrow(this.config.query, query);
-			if (!skipRequestValidation && this.config.pathParams && pathParams !== void 0) await parseOrThrow(this.config.pathParams, pathParams);
-			if (this.config.request && data === void 0) throw new Error("Missing required request body (data)");
-			if (this.config.pathParams && pathParams === void 0) throw new Error("Missing required path parameters (pathParams)");
-			let pathStr;
-			if (typeof this.config.path === "function") {
-				if (!pathParams) throw new Error("Path function requires pathParams");
-				pathStr = this.config.path(pathParams);
-			} else pathStr = this.config.path;
-			return new SSEConnectionImpl(`${this.client.getBaseUrl(this.config.advanced?.baseUrlKey || "default")}${pathStr}${toQueryString(query)}`, this.config.response, {
+			const { parsedQuery, pathStr } = await validateEndpointParams(this.config, {
+				data,
+				query,
+				pathParams
+			}, {
+				request: "SSE request body",
+				query: "SSE query parameters",
+				path: "SSE path parameters"
+			});
+			return new SSEConnectionImpl(`${this.client.getBaseUrl(this.config.advanced?.baseUrlKey || "default")}${pathStr}${toQueryString(toRequestQuery(parsedQuery))}`, this.config.response, {
 				skipResponseValidation: this.config.advanced?.skipResponseValidation,
 				withCredentials: this.config.advanced?.withCredentials,
 				method: this.config.method,
@@ -666,31 +800,29 @@ var SSEEndpointImpl = class {
 				},
 				signal,
 				auth: this.config.advanced?.skipAuth ? void 0 : this.client.getAuth(),
-				logger: this.client.getLogger()
+				logger: this.client.getLogger(),
+				fetch: this.client.getFetch()
 			});
 		};
 	}
 };
 //#endregion
 //#region lib/ws/ws-client.ts
-var WSConnectionImpl = class {
+var WSConnectionImpl = class extends EventEmitter {
 	constructor(url, sendSchema, receiveSchema, skipRequestValidation = false, skipResponseValidation = false, protocols) {
+		super();
 		this.sendSchema = sendSchema;
 		this.receiveSchema = receiveSchema;
 		this.skipRequestValidation = skipRequestValidation;
 		this.skipResponseValidation = skipResponseValidation;
-		this.handlers = /* @__PURE__ */ new Map();
 		if (typeof WebSocket === "undefined") throw new Error("WebSocket is not defined. Ensure you are in a supported environment.");
 		this.ws = new WebSocket(url, protocols);
 		this.ws.onopen = () => this.emit("open");
 		this.ws.onclose = (event) => this.emit("close", event);
 		this.ws.onerror = (event) => this.emit("error", event);
 		this.ws.onmessage = async (event) => {
-			let data = event.data;
+			let data = parseRealtimeData(event.data);
 			try {
-				if (typeof data === "string") try {
-					data = JSON.parse(data);
-				} catch {}
 				if (!this.skipResponseValidation && this.receiveSchema) data = await parseOrThrow(this.receiveSchema, data);
 				this.emit("message", data);
 			} catch (error) {
@@ -700,20 +832,13 @@ var WSConnectionImpl = class {
 	}
 	async send(data) {
 		if (!this.skipRequestValidation && this.sendSchema) await parseOrThrow(this.sendSchema, data);
-		const message = data != null && typeof data === "object" ? JSON.stringify(data) : data;
-		this.ws.send(message);
+		this.ws.send(serializeRealtimeData(data));
 	}
 	on(event, handler) {
-		if (!this.handlers.has(event)) this.handlers.set(event, /* @__PURE__ */ new Set());
-		this.handlers.get(event).add(handler);
+		super.on(event, handler);
 	}
 	off(event, handler) {
-		const handlers = this.handlers.get(event);
-		if (handlers) handlers.delete(handler);
-	}
-	emit(event, ...args) {
-		const handlers = this.handlers.get(event);
-		if (handlers) handlers.forEach((handler) => handler(...args));
+		super.off(event, handler);
 	}
 	close(code, reason) {
 		this.ws.close(code, reason);
@@ -730,14 +855,16 @@ var WSEndpointImpl = class {
 		this.config = config;
 	}
 	createCall() {
-		return (params) => {
+		return async (params) => {
 			const { query, pathParams, protocols } = params || {};
-			let pathStr;
-			if (typeof this.config.path === "function") {
-				if (!pathParams) throw new Error("Path function requires pathParams");
-				pathStr = this.config.path(pathParams);
-			} else pathStr = this.config.path;
-			return new WSConnectionImpl(`${this.client.getBaseUrl(this.config.advanced?.baseUrlKey || "default").replace(/^http/, "ws")}${pathStr}${toQueryString(query)}`, this.config.send, this.config.receive, this.config.advanced?.skipRequestValidation, this.config.advanced?.skipResponseValidation, protocols);
+			const { parsedQuery, pathStr } = await validateEndpointParams(this.config, {
+				query,
+				pathParams
+			}, {
+				query: "WebSocket query parameters",
+				path: "WebSocket path parameters"
+			});
+			return new WSConnectionImpl(`${this.client.getBaseUrl(this.config.advanced?.baseUrlKey || "default").replace(/^http/, "ws")}${pathStr}${toQueryString(toRequestQuery(parsedQuery))}`, this.config.send, this.config.receive, this.config.advanced?.skipRequestValidation, this.config.advanced?.skipResponseValidation, protocols);
 		};
 	}
 };
@@ -751,42 +878,185 @@ var EndpointImpl = class {
 	async call(params) {
 		const { data, query, pathParams, signal } = params;
 		const headers = "headers" in params ? params.headers : void 0;
-		const skipRequestValidation = this.config.advanced?.skipRequestValidation ?? false;
-		const skipResponseValidation = this.config.advanced?.skipResponseValidation ?? false;
-		if (this.config.mustHeaderKeys && this.config.mustHeaderKeys.length > 0) {
-			const missingHeaders = this.config.mustHeaderKeys.filter((key) => !headers || !(key in headers));
-			if (missingHeaders.length > 0) throw new Error(`Missing required header(s): ${missingHeaders.join(", ")}`);
-		}
-		if (!skipRequestValidation && this.config.request && data !== void 0) await parseOrThrow(this.config.request, data);
-		if (!skipRequestValidation && this.config.query && query !== void 0) await parseOrThrow(this.config.query, query);
-		if (!skipRequestValidation && this.config.pathParams && pathParams !== void 0) await parseOrThrow(this.config.pathParams, pathParams);
-		if (this.config.request && data === void 0) throw new Error("Missing required request body (data)");
-		if (this.config.pathParams && pathParams === void 0) throw new Error("Missing required path parameters (pathParams)");
-		let pathStr;
-		if (typeof this.config.path === "function") {
-			if (!pathParams) throw new Error("Path function requires pathParams");
-			pathStr = this.config.path(pathParams);
-		} else pathStr = this.config.path;
-		const { data: responseData, status } = await this.client.request(this.config.method, pathStr, data, {
+		validateRequiredHeaders(this.config.mustHeaderKeys, headers);
+		const { parsedQuery, pathStr } = await validateEndpointParams(this.config, {
+			data,
 			query,
+			pathParams
+		});
+		const { data: responseData, status } = await this.client.request(this.config.method, pathStr, data, {
+			query: toRequestQuery(parsedQuery),
 			headers,
 			baseUrlKey: this.config.advanced?.baseUrlKey,
 			skipAuth: this.config.advanced?.skipAuth,
 			skipRetry: this.config.advanced?.skipRetry,
 			signal
 		});
+		if (this.config.advanced?.skipResponseValidation) return responseData;
 		const schema = this.config.response;
-		if (skipResponseValidation) return responseData;
-		if (isStandardSchema(schema)) return await parseOrThrow(schema, responseData);
+		if (isStandardSchema(schema)) return await parseOrThrow(schema, responseData, {
+			label: `Response body for status ${status}`,
+			status
+		});
 		const specificSchema = schema[status];
 		if (!specificSchema) throw new SchemaDefinitionError(status);
-		return await parseOrThrow(specificSchema, responseData);
+		return await parseOrThrow(specificSchema, responseData, {
+			label: `Response body for status ${status}`,
+			status
+		});
 	}
 };
 //#endregion
+//#region lib/http/request-utils.ts
+function serializeRequestBody(body, headers) {
+	if (body == null) return void 0;
+	if (body instanceof FormData) {
+		delete headers["Content-Type"];
+		return body;
+	}
+	if (body instanceof Blob || body instanceof ArrayBuffer) return body;
+	if (headers["Content-Type"]?.includes("json")) return JSON.stringify(body);
+	return String(body);
+}
+function isBinaryContentType(contentType) {
+	return contentType.includes("application/octet-stream") || contentType.includes("application/pdf") || contentType.includes("image/") || contentType.includes("video/") || contentType.includes("audio/") || contentType.startsWith("application/zip") || contentType.startsWith("application/x-");
+}
+async function parseResponseData(res, method, url) {
+	if (res.status === 204 || res.status === 205) return void 0;
+	const contentType = res.headers.get("content-type") || "";
+	try {
+		if (contentType.includes("json")) {
+			const text = await res.text();
+			return text ? JSON.parse(text) : void 0;
+		}
+		if (isBinaryContentType(contentType)) return await res.blob();
+		return await res.text();
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new ApiError(`Failed to parse response body from ${method} ${url} (status ${res.status}): ${reason}`, {
+			status: res.status,
+			method,
+			url,
+			cause: error,
+			details: { contentType }
+		});
+	}
+}
+function getResponseMessage(details) {
+	if (typeof details === "string") return details.trim() || void 0;
+	if (!details || typeof details !== "object") return void 0;
+	const record = details;
+	for (const key of [
+		"message",
+		"error",
+		"title",
+		"detail"
+	]) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) return value;
+	}
+}
+function createStatusError(method, url, res, details) {
+	const statusText = res.statusText ? ` ${res.statusText}` : "";
+	const responseMessage = getResponseMessage(details);
+	const suffix = responseMessage ? `: ${responseMessage}` : "";
+	return new ApiError(`Request failed: ${method} ${url} returned ${res.status}${statusText}${suffix}`, {
+		status: res.status,
+		method,
+		url,
+		details
+	});
+}
+function createNetworkError(method, url, error) {
+	if (error instanceof ApiError) return error;
+	const reason = error instanceof Error ? error.message : String(error);
+	const name = error instanceof Error ? error.name : "Error";
+	return new ApiError(`${name === "AbortError" || name === "TimeoutError" ? "Request aborted" : "Network request failed"}: ${method} ${url}: ${reason}`, {
+		method,
+		url,
+		cause: error,
+		details: error && typeof error === "object" ? { name } : void 0
+	});
+}
+function isRetryableResponse(retryPolicy, method, status, retryAttempt, skipRetry) {
+	return !skipRetry && retryPolicy.maxAttempts > 0 && retryAttempt < retryPolicy.maxAttempts && !!retryPolicy.retryStatusCodes?.includes(status) && !!retryPolicy.retryMethods?.includes(method);
+}
+function getRetryDelay(retryPolicy, retryAttempt, response) {
+	const exponentialDelay = retryPolicy.baseDelayMs * 2 ** (retryAttempt - 1);
+	if (!retryPolicy.respectRetryAfter) return {
+		delay: exponentialDelay,
+		usedRetryAfter: false
+	};
+	const retryAfterHeader = response.headers.get("Retry-After") || response.headers.get("retry-after");
+	if (retryAfterHeader) {
+		const parsed = parseInt(retryAfterHeader, 10);
+		if (Number.isFinite(parsed) && parsed > 0) return {
+			delay: parsed * 1e3,
+			usedRetryAfter: true
+		};
+	}
+	return {
+		delay: exponentialDelay,
+		usedRetryAfter: false
+	};
+}
+function recordSuccessfulRequest(logger, metrics, method, path, url, status, durationMs) {
+	logger.info("HTTP request successful", {
+		method,
+		url,
+		status,
+		durationMs
+	});
+	metrics.collect({
+		method,
+		path,
+		status,
+		durationMs,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		success: true
+	});
+}
+function recordFailedRequest(logger, metrics, method, path, url, durationMs, error) {
+	logger.error("HTTP request failed", error, {
+		method,
+		url,
+		durationMs
+	});
+	metrics.collect({
+		method,
+		path,
+		status: error instanceof ApiError ? error.status : void 0,
+		durationMs,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		success: false,
+		error: error instanceof Error ? error.message : String(error)
+	});
+}
+/**
+* Re-applies auth to an existing AuthContext, cloning headers first so that
+* a fresh token overwrites the stale one from the previous attempt.
+*/
+async function reapplyAuth(auth, ctx) {
+	const originalHeaders = ctx.init.headers;
+	const clonedHeaders = typeof originalHeaders === "object" && !(originalHeaders instanceof Headers) && !Array.isArray(originalHeaders) ? { ...originalHeaders } : originalHeaders;
+	ctx.init = {
+		...ctx.init,
+		headers: clonedHeaders
+	};
+	await auth.apply(ctx);
+}
+function startRequestTimeout(timeoutMs, hasExternalSignal, controller) {
+	if (!timeoutMs || hasExternalSignal) return void 0;
+	return setTimeout(() => {
+		const timeoutError = /* @__PURE__ */ new Error("Request timeout");
+		timeoutError.name = "TimeoutError";
+		controller.abort(timeoutError);
+	}, timeoutMs);
+}
+//#endregion
 //#region lib/http/http-client.ts
 /**
-* HTTP client with built-in authentication, and interceptors.
+* HTTP client with built-in authentication, retry, and interceptors.
 * Supports multiple base URLs, type-safe requests, and comprehensive error handling.
 *
 * @example
@@ -796,17 +1066,9 @@ var EndpointImpl = class {
 *   headers: { 'Content-Type': 'application/json' },
 *   timeout: { requestTimeoutMs: 30000 }
 * });
-*
-* const { data } = await client.request('GET', '/users', undefined, { query: { page: 1 } });
 * ```
 */
 var HttpClient = class {
-	/**
-	* Creates a new HTTP client instance.
-	*
-	* @param opts - Client configuration options
-	* @throws {Error} If no fetch implementation is available
-	*/
 	constructor(opts) {
 		this.fetchImpl = opts.fetch ?? globalThis.fetch?.bind(globalThis);
 		if (!this.fetchImpl) throw new Error("No fetch implementation found. Pass one via options.fetch.");
@@ -823,20 +1085,12 @@ var HttpClient = class {
 		if (this.retryPolicy.baseDelayMs < 0) throw new Error("retry.baseDelayMs must be non-negative");
 		this.timeoutMs = opts.timeout?.requestTimeoutMs;
 		if (this.timeoutMs !== void 0 && this.timeoutMs < 0) throw new Error("timeout.requestTimeoutMs must be non-negative");
-		this.auth = opts["auth"] ?? new NoAuth();
+		this.auth = opts.auth ?? new NoAuth();
 		this.logger = new LoggerUtil(opts.logger ?? new NoOpLogger());
 		this.metrics = opts.metrics ?? new NoOpMetricsCollector();
 		this.onUnauthenticated = opts.onUnauthenticated;
 	}
-	/**
-	* Set or update the authentication provider.
-	*
-	* @param auth - Authentication provider instance
-	* @example
-	* ```ts
-	* client.setAuth(new BearerTokenAuth(() => getToken()));
-	* ```
-	*/
+	/** Set or update the authentication provider at runtime. */
 	setAuth(auth) {
 		this.auth = auth;
 	}
@@ -849,20 +1103,12 @@ var HttpClient = class {
 		}
 		return url.replace(/\/$/, "");
 	}
-	/**
-	* Run all registered before-request hooks.
-	* @private
-	*/
 	async runBeforeHooks(url, init) {
 		for (const h of this.interceptors.beforeRequest ?? []) await h({
 			url,
 			init
 		});
 	}
-	/**
-	* Run all registered after-response hooks.
-	* @private
-	*/
 	async runAfterHooks(req, res, parsed) {
 		for (const h of this.interceptors.afterResponse ?? []) await h({
 			request: req,
@@ -871,19 +1117,40 @@ var HttpClient = class {
 		});
 	}
 	/**
-	* Get all configured base URLs.
-	*
-	* @returns Object mapping base URL keys to their resolved URLs
+	* Returns retry info if the response should be retried, or null if not.
 	*/
-	getBaseUrls() {
-		return this.baseUrls;
+	async getRetryInfo(res, url, method, status, attempt, skipRetry) {
+		if (!isRetryableResponse(this.retryPolicy, method, status, attempt, skipRetry)) return null;
+		if (this.retryPolicy.shouldRetry) {
+			if (!await this.retryPolicy.shouldRetry({
+				url,
+				method,
+				status,
+				attempt,
+				response: res.clone()
+			})) return null;
+		}
+		return getRetryDelay(this.retryPolicy, attempt + 1, res);
+	}
+	logRetry(method, url, status, attempt, info) {
+		const suffix = info.usedRetryAfter ? "due to Retry-After header" : `attempt ${attempt}`;
+		this.logger.warn(`Request failed with status ${status}. Retrying ${suffix} after ${info.delay}ms...`, {
+			method,
+			url,
+			status,
+			retryAttempt: attempt
+		});
 	}
 	/**
-	* Get the resolved base URL for a given key.
-	*
-	* @param key - Base URL key (defaults to 'default' if not provided)
-	* @returns Resolved base URL string
+	* Checks whether the 401 response should trigger a token refresh + retry.
 	*/
+	async shouldRefresh(res, refreshAttempted) {
+		if (res.status !== 401 || !this.onUnauthenticated || refreshAttempted) return false;
+		return this.onUnauthenticated(res.clone());
+	}
+	getBaseUrls() {
+		return this.baseUrls;
+	}
 	getBaseUrl(key) {
 		return this.resolveBaseUrl(key);
 	}
@@ -899,257 +1166,120 @@ var HttpClient = class {
 	getLogger() {
 		return this.logger;
 	}
+	/** @internal */
+	getFetch() {
+		return this.fetchImpl;
+	}
 	/**
 	* Make an HTTP request with automatic retry, authentication, and validation.
 	*
-	* @param method - HTTP method (GET, POST, PUT, etc.)
-	* @param path - Request path (will be appended to base URL)
-	* @param body - Request body (will be JSON.stringify'd if Content-Type is json)
-	* @param options - Additional request options (headers, query params, etc.)
-	* @returns Promise resolving to response data and Response object
-	* @throws {ApiError} If request fails or response validation fails
-	*
 	* @example
 	* ```ts
-	* const { data, response } = await client.request('GET', '/users', undefined, {
-	*   query: { page: 1, limit: 10 },
+	* const { data } = await client.request('GET', '/users', undefined, {
+	*   query: { page: 1 },
 	*   headers: { 'X-Custom': 'value' }
 	* });
 	* ```
 	*/
 	async request(method, path, body, options) {
 		const startTime = Date.now();
-		let url = `${this.resolveBaseUrl(options?.baseUrlKey)}${path}${toQueryString(options?.query)}`;
-		this.logger.debug("HTTP request initiated", {
-			method,
-			path,
-			baseUrlKey: options?.baseUrlKey,
-			hasBody: body !== void 0
-		});
+		const base = this.resolveBaseUrl(options?.baseUrlKey);
 		const headers = {
 			...this.headers,
 			...options?.headers ?? {}
 		};
 		const controller = new AbortController();
 		const signal = options?.signal ?? controller.signal;
-		let requestBody;
-		if (body != null) if (body instanceof FormData) {
-			requestBody = body;
-			delete headers["Content-Type"];
-		} else if (body instanceof Blob || body instanceof ArrayBuffer) requestBody = body;
-		else if (headers["Content-Type"]?.includes("json")) requestBody = JSON.stringify(body);
-		else requestBody = String(body);
+		this.logger.debug("HTTP request initiated", {
+			method,
+			path,
+			baseUrlKey: options?.baseUrlKey,
+			hasBody: body !== void 0
+		});
 		const init = {
 			method,
 			headers,
-			body: requestBody,
+			body: serializeRequestBody(body, headers),
 			signal
 		};
-		if (!options?.skipAuth) await this.auth.apply({
-			url,
+		const authCtx = {
+			url: `${base}${path}${toQueryString(options?.query)}`,
 			init,
 			options
-		});
-		if (init.__urlOverride) url = init.__urlOverride;
-		await this.runBeforeHooks(url, init);
+		};
+		if (!options?.skipAuth) await this.auth.apply(authCtx);
+		await this.runBeforeHooks(authCtx.url, authCtx.init);
 		let refreshAttempted = false;
 		let retryAttempt = 0;
-		const doFetch = async () => {
-			while (true) {
-				let timeoutId;
-				if (this.timeoutMs && !options?.signal) timeoutId = setTimeout(() => {
-					const timeoutError = /* @__PURE__ */ new Error("Request timeout");
-					timeoutError.name = "TimeoutError";
-					controller.abort(timeoutError);
-				}, this.timeoutMs);
+		while (true) {
+			const timeoutId = startRequestTimeout(this.timeoutMs, !!options?.signal, controller);
+			try {
+				if (refreshAttempted && !options?.skipAuth) await reapplyAuth(this.auth, authCtx);
+				const req = new Request(authCtx.url, authCtx.init);
+				let res;
 				try {
-					if (refreshAttempted && !options?.skipAuth) {
-						const freshInit = {
-							...init,
-							headers: typeof init.headers === "object" && !(init.headers instanceof Headers) && !Array.isArray(init.headers) ? { ...init.headers } : init.headers
-						};
-						await this.auth.apply({
-							url,
-							init: freshInit,
-							options
-						});
-						init.headers = freshInit.headers;
-					}
-					const req = new Request(url, init);
-					const res = await this.fetchImpl(req);
-					if (res.status === 401 && this.onUnauthenticated && !refreshAttempted) {
-						if (await this.onUnauthenticated(res.clone())) {
-							refreshAttempted = true;
-							if (timeoutId) clearTimeout(timeoutId);
-							continue;
-						}
-					}
-					const status = res.status;
-					const contentType = res.headers.get("content-type") || "";
-					if (!res.ok) {
-						if (!options?.skipRetry && this.retryPolicy.maxAttempts > 0 && retryAttempt < this.retryPolicy.maxAttempts && this.retryPolicy.retryStatusCodes?.includes(status) && this.retryPolicy.retryMethods?.includes(method)) {
-							let shouldRetry = true;
-							if (this.retryPolicy.shouldRetry) shouldRetry = await this.retryPolicy.shouldRetry({
-								url,
-								method,
-								status,
-								attempt: retryAttempt,
-								response: res.clone()
-							});
-							if (shouldRetry) {
-								retryAttempt++;
-								let delay = this.retryPolicy.baseDelayMs * 2 ** (retryAttempt - 1);
-								if (this.retryPolicy.respectRetryAfter) {
-									const retryAfter = res.headers.get("Retry-After") || res.headers.get("retry-after");
-									if (retryAfter) {
-										delay = parseInt(retryAfter, 10) * 1e3;
-										this.logger.warn(`Request failed with status ${status}. Retrying after ${delay}ms due to Retry-After header...`, {
-											method,
-											url,
-											status,
-											retryAttempt: retryAttempt + 1
-										});
-									}
-								} else this.logger.warn(`Request failed with status ${status}. Retrying attempt ${retryAttempt} after ${delay}ms...`, {
-									method,
-									url,
-									status,
-									retryAttempt
-								});
-								await new Promise((resolve) => setTimeout(resolve, delay));
-								continue;
-							}
-						}
-					}
-					let data;
-					if (contentType.includes("json")) data = await res.json();
-					else if (contentType.includes("application/octet-stream") || contentType.includes("application/pdf") || contentType.includes("image/") || contentType.includes("video/") || contentType.includes("audio/") || contentType.startsWith("application/zip") || contentType.startsWith("application/x-")) data = await res.blob();
-					else data = await res.text();
-					await this.runAfterHooks(new Request(url, init), res, data);
-					const duration = Date.now() - startTime;
-					this.logger.info("HTTP request successful", {
-						method,
-						url,
-						status: res.status,
-						durationMs: duration
-					});
-					this.metrics.collect({
-						method,
-						path,
-						status: res.status,
-						durationMs: duration,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						success: true
-					});
-					return {
-						data,
-						status
-					};
-				} catch (error) {
-					const duration = Date.now() - startTime;
-					this.logger.error("HTTP request failed", error, {
-						method,
-						url,
-						durationMs: duration
-					});
-					this.metrics.collect({
-						method,
-						path,
-						status: error instanceof ApiError ? error.status : void 0,
-						durationMs: duration,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						success: false,
-						error: error instanceof Error ? error.message : String(error)
-					});
-					throw error;
-				} finally {
+					res = await this.fetchImpl(req);
+				} catch (err) {
+					throw createNetworkError(method, authCtx.url, err);
+				}
+				if (await this.shouldRefresh(res, refreshAttempted)) {
+					refreshAttempted = true;
 					if (timeoutId) clearTimeout(timeoutId);
+					continue;
 				}
+				const status = res.status;
+				if (!res.ok) {
+					const retryInfo = await this.getRetryInfo(res, authCtx.url, method, status, retryAttempt, options?.skipRetry);
+					if (retryInfo) {
+						retryAttempt++;
+						this.logRetry(method, authCtx.url, status, retryAttempt, retryInfo);
+						await new Promise((resolve) => setTimeout(resolve, retryInfo.delay));
+						continue;
+					}
+				}
+				const data = await parseResponseData(res, method, authCtx.url);
+				await this.runAfterHooks(new Request(authCtx.url, authCtx.init), res, data);
+				if (!res.ok) throw createStatusError(method, authCtx.url, res, data);
+				recordSuccessfulRequest(this.logger, this.metrics, method, path, authCtx.url, res.status, Date.now() - startTime);
+				return {
+					data,
+					status
+				};
+			} catch (error) {
+				recordFailedRequest(this.logger, this.metrics, method, path, authCtx.url, Date.now() - startTime, error);
+				throw error;
+			} finally {
+				if (timeoutId) clearTimeout(timeoutId);
 			}
-		};
-		return doFetch();
+		}
 	}
-	/**
-	* Convenience method for GET requests.
-	*
-	* @example
-	* ```ts
-	* const { data } = await client.get('/users', { query: { page: 1 } });
-	* ```
-	*/
 	async get(path, options) {
 		return this.request("GET", path, void 0, options);
 	}
-	/**
-	* Convenience method for POST requests.
-	*
-	* @example
-	* ```ts
-	* const { data } = await client.post('/users', { name: 'John' });
-	* ```
-	*/
 	async post(path, body, options) {
 		return this.request("POST", path, body, options);
 	}
-	/**
-	* Convenience method for PUT requests.
-	*
-	* @example
-	* ```ts
-	* const { data } = await client.put('/users/1', { name: 'John Updated' });
-	* ```
-	*/
 	async put(path, body, options) {
 		return this.request("PUT", path, body, options);
 	}
-	/**
-	* Convenience method for PATCH requests.
-	*
-	* @example
-	* ```ts
-	* const { data } = await client.patch('/users/1', { name: 'John' });
-	* ```
-	*/
 	async patch(path, body, options) {
 		return this.request("PATCH", path, body, options);
 	}
-	/**
-	* Convenience method for DELETE requests.
-	*
-	* @example
-	* ```ts
-	* const { data } = await client.delete('/users/1');
-	* ```
-	*/
 	async delete(path, options) {
 		return this.request("DELETE", path, void 0, options);
 	}
 	/**
-	* Create a strongly-typed endpoint builder.
+	* Create a strongly-typed HTTP endpoint.
 	* Works with any Standard Schema-compatible library (Zod, Valibot, ArkType, etc.)
 	*
-	* @param config - Endpoint configuration with schemas
-	* @returns Endpoint call function
-	*
 	* @example
 	* ```ts
-	* // With Zod
-	* import { z } from 'zod';
 	* const getUser = client.createEndpoint({
 	*   method: 'GET',
 	*   path: '/users/:id',
 	*   response: z.object({ id: z.string(), name: z.string() }),
 	*   pathParams: z.object({ id: z.string() }),
 	* });
-	*
-	* // With Valibot
-	* import * as v from 'valibot';
-	* const getUser = client.createEndpoint({
-	*   method: 'GET',
-	*   path: '/users/:id',
-	*   response: v.object({ id: v.string(), name: v.string() }),
-	*   pathParams: v.object({ id: v.string() }),
-	* });
 	* ```
 	*/
 	createEndpoint(config) {
@@ -1157,19 +1287,34 @@ var HttpClient = class {
 		return (params) => endpoint.call(params);
 	}
 	/**
-	* Create a strongly-typed WebSocket endpoint builder.
+	* Create a strongly-typed WebSocket endpoint.
 	*
-	* @param config - WebSocket endpoint configuration
-	* @returns WebSocket endpoint call function
+	* @example
+	* ```ts
+	* const chat = client.createWebSocket({
+	*   path: '/ws/chat',
+	*   send: z.object({ text: z.string() }),
+	*   receive: z.object({ text: z.string(), user: z.string() }),
+	* });
+	* const conn = await chat();
+	* ```
 	*/
 	createWebSocket(config) {
 		return new WSEndpointImpl(this, config).createCall();
 	}
 	/**
-	* Create a strongly-typed Server-Sent Events (SSE) endpoint builder.
+	* Create a strongly-typed Server-Sent Events endpoint.
 	*
-	* @param config - SSE endpoint configuration
-	* @returns SSE endpoint call function
+	* @example
+	* ```ts
+	* const stream = client.createSSE({
+	*   method: 'GET',
+	*   path: '/events',
+	*   response: z.object({ message: z.string() }),
+	* });
+	* const conn = await stream();
+	* conn.on('message', (data) => console.log(data));
+	* ```
 	*/
 	createSSE(config) {
 		return new SSEEndpointImpl(this, config).createCall();
@@ -1196,9 +1341,11 @@ exports.SSEEndpointImpl = SSEEndpointImpl;
 exports.SchemaDefinitionError = SchemaDefinitionError;
 exports.WSConnectionImpl = WSConnectionImpl;
 exports.WSEndpointImpl = WSEndpointImpl;
+exports.formatValidationIssues = formatValidationIssues;
 exports.isStandardSchema = isStandardSchema;
 exports.parseOrThrow = parseOrThrow;
 exports.safeParse = safeParse;
 exports.toQueryString = toQueryString;
+exports.toRequestQuery = toRequestQuery;
 
 //# sourceMappingURL=index.cjs.map