zlient 1.0.3 → 1.0.5

package/dist/index.js

@@ -1,34 +1,5 @@
 import { z } from "zod";
 
-//#region rolldown:runtime
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function() {
-	return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (all) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	return target;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-//#endregion
 //#region lib/types.ts
 const HTTPMethod = {
 	GET: "GET",
@@ -39,7 +10,19 @@ const HTTPMethod = {
 	HEAD: "HEAD",
 	OPTIONS: "OPTIONS"
 };
-var ApiError = class extends Error {
+/**
+* Custom error class for API-related errors.
+* Includes HTTP status codes, response details, and validation errors.
+* 
+* @example
+* ```ts
+* throw new ApiError('Invalid request', {
+*   status: 400,
+*   details: { field: 'email', message: 'Invalid format' }
+* });
+* ```
+*/
+var ApiError = class ApiError extends Error {
 	status;
 	details;
 	zodError;
@@ -50,14 +33,62 @@ var ApiError = class extends Error {
 		this.details = options?.details;
 		this.cause = options?.cause;
 		this.zodError = options?.zodError;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, ApiError);
+	}
+	/**
+	* Check if this is a validation error (has zodError)
+	*/
+	isValidationError() {
+		return !!this.zodError;
+	}
+	/**
+	* Check if this is a client error (4xx status)
+	*/
+	isClientError() {
+		return !!this.status && this.status >= 400 && this.status < 500;
+	}
+	/**
+	* Check if this is a server error (5xx status)
+	*/
+	isServerError() {
+		return !!this.status && this.status >= 500;
+	}
+	/**
+	* Get a formatted error message with all available details
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			status: this.status,
+			details: this.details,
+			zodError: this.zodError?.issues,
+			stack: this.stack
+		};
 	}
 };
+/**
+* Schema for paginated responses
+*/
 const PaginationSchema = z.object({
 	items: z.array(z.unknown()),
 	total: z.number().int().nonnegative(),
 	page: z.number().int().nonnegative(),
 	pageSize: z.number().int().positive()
 });
+/**
+* Converts query parameters to a URL query string.
+* Filters out undefined values automatically.
+* 
+* @param q - Query parameters as URLSearchParams or object
+* @returns Query string with leading '?' or empty string
+* 
+* @example
+* ```ts
+* toQueryString({ page: 1, filter: 'active' }) // "?page=1&filter=active"
+* toQueryString({ optional: undefined }) // ""
+* ```
+*/
 function toQueryString(q) {
 	if (!q) return "";
 	if (q instanceof URLSearchParams) {
@@ -74,48 +105,93 @@ function toQueryString(q) {
 
 //#endregion
 //#region lib/auth.ts
-var auth_exports = /* @__PURE__ */ __export({
-	ApiKeyAuth: () => ApiKeyAuth,
-	BearerTokenAuth: () => BearerTokenAuth,
-	NoAuth: () => NoAuth
-});
-var NoAuth, ApiKeyAuth, BearerTokenAuth;
-var init_auth = __esm({ "lib/auth.ts": (() => {
-	NoAuth = class {
-		async apply() {}
-	};
-	ApiKeyAuth = class {
-		constructor(opts) {
-			this.opts = opts;
-		}
-		apply({ url, init }) {
-			if (this.opts.header) init.headers = {
-				...init.headers,
-				[this.opts.header]: this.opts.value
-			};
-			else if (this.opts.query) {
-				const u = new URL(url);
-				u.searchParams.set(this.opts.query, this.opts.value);
-				init.__urlOverride = u.toString();
-			}
-		}
-	};
-	BearerTokenAuth = class {
-		constructor(getToken) {
-			this.getToken = getToken;
-		}
-		async apply({ init }) {
-			const token = await this.getToken();
-			init.headers = {
-				...init.headers,
-				Authorization: `Bearer ${token}`
-			};
+/**
+* No-op authentication provider (no authentication applied).
+* Use this when you don't need authentication.
+*/
+var NoAuth = class {
+	async apply() {}
+};
+/**
+* API Key authentication provider.
+* Supports both header-based and query parameter-based authentication.
+* 
+* @example
+* ```ts
+* // Header-based
+* const auth = new ApiKeyAuth({ header: 'X-API-Key', value: 'secret' });
+* 
+* // Query parameter-based
+* const auth = new ApiKeyAuth({ query: 'apiKey', value: 'secret' });
+* ```
+*/
+var ApiKeyAuth = class {
+	constructor(opts) {
+		this.opts = opts;
+		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 }) {
+		if (this.opts.header) init.headers = {
+			...init.headers,
+			[this.opts.header]: this.opts.value
+		};
+		else if (this.opts.query) {
+			const u = new URL(url);
+			u.searchParams.set(this.opts.query, this.opts.value);
+			init.__urlOverride = u.toString();
 		}
-	};
-}) });
+	}
+};
+/**
+* Bearer token authentication provider.
+* Supports both static tokens and dynamic token fetching (e.g., for OAuth2 refresh).
+* 
+* @example
+* ```ts
+* // Static token
+* const auth = new BearerTokenAuth(() => 'my-token');
+* 
+* // Dynamic token with refresh
+* const auth = new BearerTokenAuth(async () => {
+*   return await refreshAccessToken();
+* });
+* ```
+*/
+var BearerTokenAuth = class {
+	constructor(getToken) {
+		this.getToken = getToken;
+	}
+	async apply({ init }) {
+		const token = await this.getToken();
+		if (!token) throw new Error("BearerTokenAuth: token is empty or undefined");
+		init.headers = {
+			...init.headers,
+			Authorization: `Bearer ${token}`
+		};
+	}
+};
 
 //#endregion
 //#region lib/validation.ts
+/**
+* Safely parse data with a Zod schema without throwing.
+* Returns a result object with success status and data or error.
+* 
+* @param schema - Zod schema to validate against
+* @param data - Data to validate
+* @returns Result object with success flag and data/error
+* 
+* @example
+* ```ts
+* const result = safeParse(UserSchema, userData);
+* if (result.success) {
+*   console.log(result.data);
+* } else {
+*   console.error(result.error);
+* }
+* ```
+*/
 function safeParse(schema, data) {
 	const res = schema.safeParse(data);
 	if (res.success) return {
@@ -127,14 +203,220 @@ function safeParse(schema, data) {
 		error: res.error
 	};
 }
+/**
+* Parse data with a Zod schema, throwing an ApiError on validation failure.
+* Use this when you want to fail fast on invalid data.
+* 
+* @param schema - Zod schema to validate against
+* @param data - Data to validate
+* @returns Validated and typed data
+* @throws {ApiError} If validation fails
+* 
+* @example
+* ```ts
+* try {
+*   const user = parseOrThrow(UserSchema, userData);
+*   console.log(user);
+* } catch (error) {
+*   if (error instanceof ApiError && error.zodError) {
+*     console.error('Validation failed:', error.zodError.issues);
+*   }
+* }
+* ```
+*/
 function parseOrThrow(schema, data) {
 	const res = schema.safeParse(data);
 	if (!res.success) throw new ApiError("Response validation failed", { zodError: res.error });
 	return res.data;
 }
 
+//#endregion
+//#region lib/logger.ts
+/**
+* Log levels for structured logging.
+*/
+let LogLevel = /* @__PURE__ */ function(LogLevel$1) {
+	LogLevel$1["DEBUG"] = "debug";
+	LogLevel$1["INFO"] = "info";
+	LogLevel$1["WARN"] = "warn";
+	LogLevel$1["ERROR"] = "error";
+	return LogLevel$1;
+}({});
+/**
+* Default console logger implementation.
+* Formats log entries as JSON for easy parsing.
+*/
+var ConsoleLogger = class {
+	constructor(minLevel = LogLevel.INFO) {
+		this.minLevel = minLevel;
+	}
+	log(entry) {
+		const levels = [
+			LogLevel.DEBUG,
+			LogLevel.INFO,
+			LogLevel.WARN,
+			LogLevel.ERROR
+		];
+		if (levels.indexOf(entry.level) < levels.indexOf(this.minLevel)) return;
+		const output = {
+			...entry,
+			error: entry.error ? {
+				message: entry.error.message,
+				stack: entry.error.stack,
+				name: entry.error.name
+			} : void 0
+		};
+		switch (entry.level) {
+			case LogLevel.DEBUG:
+				console.debug(JSON.stringify(output));
+				break;
+			case LogLevel.INFO:
+				console.info(JSON.stringify(output));
+				break;
+			case LogLevel.WARN:
+				console.warn(JSON.stringify(output));
+				break;
+			case LogLevel.ERROR:
+				console.error(JSON.stringify(output));
+				break;
+		}
+	}
+};
+/**
+* No-op logger that discards all log entries.
+* Use this in production if you don't want any logging.
+*/
+var NoOpLogger = class {
+	log(_entry) {}
+};
+/**
+* Utility class for creating structured log entries.
+*/
+var LoggerUtil = class {
+	constructor(logger) {
+		this.logger = logger;
+	}
+	debug(message, context) {
+		this.logger.log({
+			level: LogLevel.DEBUG,
+			message,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			context
+		});
+	}
+	info(message, context) {
+		this.logger.log({
+			level: LogLevel.INFO,
+			message,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			context
+		});
+	}
+	warn(message, context) {
+		this.logger.log({
+			level: LogLevel.WARN,
+			message,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			context
+		});
+	}
+	error(message, error, context) {
+		this.logger.log({
+			level: LogLevel.ERROR,
+			message,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			context,
+			error
+		});
+	}
+};
+
+//#endregion
+//#region lib/metrics.ts
+/**
+* No-op metrics collector that discards all metrics.
+*/
+var NoOpMetricsCollector = class {
+	collect(_metrics) {}
+};
+/**
+* In-memory metrics collector for testing and development.
+* Stores metrics in memory with configurable retention.
+*/
+var InMemoryMetricsCollector = class {
+	metrics = [];
+	maxEntries;
+	constructor(maxEntries = 1e3) {
+		this.maxEntries = maxEntries;
+	}
+	collect(metrics) {
+		this.metrics.push(metrics);
+		if (this.metrics.length > this.maxEntries) this.metrics.shift();
+	}
+	/**
+	* Get all collected metrics.
+	*/
+	getMetrics() {
+		return [...this.metrics];
+	}
+	/**
+	* Get metrics summary statistics.
+	*/
+	getSummary() {
+		if (this.metrics.length === 0) return {
+			total: 0,
+			successful: 0,
+			failed: 0,
+			avgDurationMs: 0,
+			minDurationMs: 0,
+			maxDurationMs: 0
+		};
+		const successful = this.metrics.filter((m) => m.success).length;
+		const durations = this.metrics.map((m) => m.durationMs);
+		const sum = durations.reduce((a, b) => a + b, 0);
+		return {
+			total: this.metrics.length,
+			successful,
+			failed: this.metrics.length - successful,
+			avgDurationMs: sum / this.metrics.length,
+			minDurationMs: Math.min(...durations),
+			maxDurationMs: Math.max(...durations)
+		};
+	}
+	/**
+	* Clear all collected metrics.
+	*/
+	clear() {
+		this.metrics = [];
+	}
+};
+/**
+* Console-based metrics collector for debugging.
+*/
+var ConsoleMetricsCollector = class {
+	collect(metrics) {
+		console.log("[METRICS]", JSON.stringify(metrics));
+	}
+};
+
 //#endregion
 //#region lib/http/HttpClient.ts
+/**
+* HTTP client with built-in retry logic, authentication, and interceptors.
+* Supports multiple base URLs, type-safe requests, and comprehensive error handling.
+* 
+* @example
+* ```ts
+* const client = new HttpClient({
+*   baseUrls: { default: 'https://api.example.com' },
+*   headers: { 'Content-Type': 'application/json' },
+*   retry: { maxRetries: 3, baseDelayMs: 1000 },
+*   timeout: { requestTimeoutMs: 30000 }
+* });
+* 
+* const { data } = await client.request('GET', '/users', undefined, { query: { page: 1 } });
+* ```
+*/
 var HttpClient = class {
 	fetchImpl;
 	baseUrls;
@@ -143,9 +425,19 @@ var HttpClient = class {
 	retry;
 	timeoutMs;
 	auth;
+	logger;
+	metrics;
+	/**
+	* 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.");
+		if (!opts.baseUrls || typeof opts.baseUrls !== "object") throw new Error("baseUrls must be provided and must be an object");
+		if (!opts.baseUrls.default) throw new Error("baseUrls must include a \"default\" key");
 		this.baseUrls = opts.baseUrls;
 		this.headers = opts.headers ?? { "Content-Type": "application/json" };
 		this.interceptors = opts.interceptors ?? {};
@@ -155,21 +447,47 @@ var HttpClient = class {
 			jitter: .2,
 			retryMethods: ["GET", "HEAD"]
 		};
+		if (this.retry.maxRetries < 0) throw new Error("retry.maxRetries must be non-negative");
+		if (this.retry.baseDelayMs < 0) throw new Error("retry.baseDelayMs must be non-negative");
+		if (this.retry.jitter !== void 0 && (this.retry.jitter < 0 || this.retry.jitter > 1)) throw new Error("retry.jitter must be between 0 and 1");
 		this.timeoutMs = opts.timeout?.requestTimeoutMs;
-		this.auth = opts["auth"] ?? new (init_auth(), __toCommonJS(auth_exports)).NoAuth();
+		if (this.timeoutMs !== void 0 && this.timeoutMs < 0) throw new Error("timeout.requestTimeoutMs must be non-negative");
+		this.auth = opts["auth"] ?? new NoAuth();
+		this.logger = new LoggerUtil(opts.logger ?? new NoOpLogger());
+		this.metrics = opts.metrics ?? new NoOpMetricsCollector();
 	}
+	/**
+	* Set or update the authentication provider.
+	* 
+	* @param auth - Authentication provider instance
+	* @example
+	* ```ts
+	* client.setAuth(new BearerTokenAuth(() => getToken()));
+	* ```
+	*/
 	setAuth(auth) {
 		this.auth = auth;
 	}
 	resolveBaseUrl(key) {
 		const k = key || "default";
 		const url = this.baseUrls[k];
-		if (!url) throw new Error(`Unknown baseUrl key: ${k}`);
+		if (!url) {
+			const availableKeys = Object.keys(this.baseUrls).join(", ");
+			throw new Error(`Unknown baseUrl key: "${k}". Available keys: ${availableKeys}`);
+		}
 		return url.replace(/\/$/, "");
 	}
+	/**
+	* Sleep for a specified duration (used for retry backoff).
+	* @private
+	*/
 	sleep(ms) {
 		return new Promise((res) => setTimeout(res, ms));
 	}
+	/**
+	* Execute a function with retry logic and exponential backoff.
+	* @private
+	*/
 	async withRetry(fn, canRetry) {
 		let attempt = 0;
 		const { maxRetries, baseDelayMs, jitter = .2 } = this.retry;
@@ -186,12 +504,20 @@ var HttpClient = class {
 			attempt++;
 		}
 	}
+	/**
+	* 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,
@@ -199,8 +525,33 @@ var HttpClient = class {
 			parsed
 		});
 	}
+	/**
+	* 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 },
+	*   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 headers = {
 			...this.headers,
 			...options?.headers ?? {}
@@ -210,7 +561,7 @@ var HttpClient = class {
 		const init = {
 			method,
 			headers,
-			body: body != null ? headers["Content-Type"]?.includes("json") ? JSON.stringify(body) : body : void 0,
+			body: body != null ? headers["Content-Type"]?.includes("json") ? JSON.stringify(body) : String(body) : void 0,
 			signal
 		};
 		await this.auth.apply({
@@ -222,16 +573,21 @@ var HttpClient = class {
 		await this.runBeforeHooks(url, init);
 		const doFetch = async () => {
 			let timeoutId;
-			if (this.timeoutMs && !options?.signal) timeoutId = setTimeout(() => controller.abort(new ApiError("Request timeout", { status: 0 })), this.timeoutMs);
+			if (this.timeoutMs && !options?.signal) timeoutId = setTimeout(() => {
+				const timeoutError = /* @__PURE__ */ new Error("Request timeout");
+				timeoutError.name = "TimeoutError";
+				controller.abort(timeoutError);
+			}, this.timeoutMs);
 			try {
 				const req = new Request(url, init);
-				console.log("HTTP Request:", req.method, req.url, req);
 				const res = await this.fetchImpl(req);
 				if (!res.ok) {
 					let text = "";
 					try {
 						text = await res.text();
-					} catch {}
+					} catch (readError) {
+						text = `Failed to read response: ${readError instanceof Error ? readError.message : String(readError)}`;
+					}
 					throw new ApiError(`HTTP ${res.status}: ${res.statusText}`, {
 						status: res.status,
 						details: text
@@ -239,33 +595,151 @@ var HttpClient = class {
 				}
 				const data = (res.headers.get("content-type") || "").includes("json") ? await res.json() : 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,
 					response: res
 				};
+			} 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 {
 				if (timeoutId) clearTimeout(timeoutId);
 			}
 		};
 		const canRetry = ({ response, error }) => {
+			if (error && typeof error === "object" && "name" in error) {
+				const errorName = error.name;
+				if (errorName === "AbortError" || errorName === "TimeoutError") return false;
+			}
 			if (error instanceof ApiError && error.status && error.status >= 500) return true;
-			if (error?.name === "AbortError") return false;
-			if (!error?.status && !response) return true;
+			if (error && !response) return true;
 			return false;
 		};
 		if (!this.retry.retryMethods?.includes(method)) return doFetch();
 		return this.withRetry(doFetch, canRetry);
 	}
+	/**
+	* 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);
+	}
 };
 
 //#endregion
 //#region lib/endpoint/BaseEndpoint.ts
 /**
-* Generic, strongly-typed endpoint with Zod schemas for request and response.
+* Generic, strongly-typed endpoint with Zod schemas for request and response validation.
+* Extend this class to create type-safe API endpoints.
+* 
+* @template ReqSchema - Zod schema for request validation
+* @template ResSchema - Zod schema for response validation
+* 
+* @example
+* ```ts
+* const UserSchema = z.object({ id: z.number(), name: z.string() });
+* const CreateUserSchema = z.object({ name: z.string() });
+* 
+* class GetUser extends BaseEndpoint<typeof CreateUserSchema, typeof UserSchema> {
+*   protected method = 'GET' as const;
+*   protected path = (args: z.infer<typeof CreateUserSchema>) => `/users/${args.id}`;
+*   
+*   constructor(client: HttpClient) {
+*     super(client, { 
+*       requestSchema: CreateUserSchema,
+*       responseSchema: UserSchema 
+*     });
+*   }
+* }
+* ```
 */
 var BaseEndpoint = class {
+	/** Optional request schema for validation */
 	requestSchema;
+	/** Response schema for validation */
 	responseSchema;
+	/**
+	* @param client - HttpClient instance
+	* @param cfg - Configuration with request and response schemas
+	*/
 	constructor(client, cfg) {
 		this.client = client;
 		this.requestSchema = cfg.requestSchema;
@@ -273,6 +747,19 @@ var BaseEndpoint = class {
 	}
 	/**
 	* Call the endpoint with strong typing derived from schemas.
+	* Validates request data before sending and response data after receiving.
+	* 
+	* @param args - Request arguments (typed by ReqSchema)
+	* @param options - Additional request options
+	* @returns Promise resolving to validated response data (typed by ResSchema)
+	* @throws {ZodError} If request validation fails
+	* @throws {ApiError} If response validation fails or request fails
+	* 
+	* @example
+	* ```ts
+	* const endpoint = new GetUser(client);
+	* const user = await endpoint.call({ id: 1 });
+	* ```
 	*/
 	async call(args, options) {
 		if (this.requestSchema) {
@@ -280,10 +767,16 @@ var BaseEndpoint = class {
 			if (!parsed.success) throw parsed.error;
 		}
 		const path = typeof this.path === "function" ? this.path(args) : this.path;
-		const body = this.method === "GET" || this.method === "HEAD" ? void 0 : args;
+		const body = this.method !== "GET" && this.method !== "HEAD" ? args : void 0;
+		const queryFromArgs = args?.query;
+		let mergedQuery;
+		if (options?.query || queryFromArgs) mergedQuery = {
+			...typeof options?.query === "object" && !(options?.query instanceof URLSearchParams) ? options.query : {},
+			...typeof queryFromArgs === "object" && queryFromArgs !== null ? queryFromArgs : {}
+		};
 		const { data } = await this.client.request(this.method, path, body, {
 			...options,
-			query: (this.method === "GET" ? args?.query : void 0) ?? options?.query
+			query: mergedQuery && Object.keys(mergedQuery).length > 0 ? mergedQuery : options?.query
 		});
 		return parseOrThrow(this.responseSchema, data);
 	}
@@ -291,29 +784,81 @@ var BaseEndpoint = class {
 
 //#endregion
 //#region lib/schemas/common.ts
+/**
+* Common ID type that supports strings, numbers, or UUIDs.
+* Use this for entity identifiers in your schemas.
+* 
+* @example
+* ```ts
+* const UserSchema = z.object({ id: Id, name: z.string() });
+* ```
+*/
 const Id = z.union([
 	z.string().min(1),
 	z.number(),
 	z.uuid({ version: "v4" })
 ]);
+/**
+* Common timestamp fields for entities.
+* Use this for database models with creation/update tracking.
+* 
+* @example
+* ```ts
+* const UserSchema = z.object({
+*   id: Id,
+*   name: z.string(),
+*   ...Timestamps.shape
+* });
+* ```
+*/
 const Timestamps = z.object({
-	createdAt: z.iso.datetime(),
-	updatedAt: z.iso.datetime()
+	createdAt: z.string().datetime(),
+	updatedAt: z.string().datetime()
 });
+/**
+* Metadata information typically included in API responses.
+* Contains request tracking and debugging information.
+*/
 const Meta = z.object({
 	requestId: z.string().optional(),
-	timestamp: z.iso.datetime().optional(),
+	timestamp: z.string().datetime().optional(),
 	traceId: z.string().optional()
 });
+/**
+* Detailed error information for a specific field or path.
+*/
 const ErrorDetail = z.object({
 	path: z.string().optional(),
 	message: z.string()
 });
+/**
+* Standard API error response schema.
+* Use this for consistent error handling across your API.
+*/
 const ApiErrorSchema = z.object({
 	code: z.string(),
 	message: z.string(),
 	details: z.array(ErrorDetail).optional()
 });
+/**
+* Generic envelope wrapper for API responses.
+* Provides consistent structure with success flag, data, error, and metadata.
+* 
+* @param inner - Zod schema for the response data
+* @returns Envelope schema wrapping the inner schema
+* 
+* @example
+* ```ts
+* const UserResponseSchema = Envelope(z.object({ id: Id, name: z.string() }));
+* 
+* // Response structure:
+* // {
+* //   success: true,
+* //   data: { id: 1, name: 'John' },
+* //   meta: { requestId: '...' }
+* // }
+* ```
+*/
 const Envelope = (inner) => z.object({
 	success: z.boolean(),
 	data: inner.optional(),
@@ -322,9 +867,5 @@ const Envelope = (inner) => z.object({
 });
 
 //#endregion
-//#region lib/index.ts
-init_auth();
-
-//#endregion
-export { ApiError, ApiErrorSchema, ApiKeyAuth, BaseEndpoint, BearerTokenAuth, Envelope, ErrorDetail, HTTPMethod, HttpClient, Id, Meta, NoAuth, PaginationSchema, Timestamps, parseOrThrow, safeParse, toQueryString };
+export { ApiError, ApiErrorSchema, ApiKeyAuth, BaseEndpoint, BearerTokenAuth, ConsoleLogger, ConsoleMetricsCollector, Envelope, ErrorDetail, HTTPMethod, HttpClient, Id, InMemoryMetricsCollector, LogLevel, LoggerUtil, Meta, NoAuth, NoOpLogger, NoOpMetricsCollector, PaginationSchema, Timestamps, parseOrThrow, safeParse, toQueryString };
 //# sourceMappingURL=index.js.map