zlient 1.0.8 → 1.0.10

package/dist/endpoint/base-endpoint.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { HttpClient } from '../http/http-client';
+import { HTTPMethod } from '../types';
+/**
+ * Request configuration for endpoint calls.
+ * Wrapper object containing all request parameters.
+ *
+ * @template ReqSchema - Zod schema for request validation
+ * @template PathParams - Type for path parameters
+ * @template QueryParams - Type for query parameters
+ */
+export type EndpointCallConfig<ReqSchema extends z.ZodType, PathParams = never, QueryParams = never> = {
+    /** Request body data (for POST, PUT, PATCH, etc.) or request args */
+    data?: z.infer<ReqSchema>;
+    /** Path parameters for dynamic path construction */
+    pathParams?: PathParams;
+    /** Query string parameters */
+    query?: QueryParams;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Override base URL for this call */
+    baseUrlKey?: string;
+    /** Abort controller signal for cancellation */
+    signal?: globalThis.AbortSignal;
+};
+/**
+ * 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
+ * @template PathParams - Type for path parameters (optional)
+ * @template QueryParams - Type for query parameters (optional)
+ *
+ * @example
+ * ```ts
+ * const UserSchema = z.object({ id: z.number(), name: z.string() });
+ * const CreateUserSchema = z.object({ name: z.string() });
+ *
+ * type UserPathParams = { id: string };
+ * type UserQueryParams = { include?: string; limit?: number };
+ *
+ * class GetUser extends BaseEndpoint<
+ *   typeof CreateUserSchema,
+ *   typeof UserSchema,
+ *   UserPathParams,
+ *   UserQueryParams
+ * > {
+ *   protected method = 'GET' as const;
+ *   protected path = (params: UserPathParams) => `/users/${params.id}`;
+ *
+ *   constructor(client: HttpClient) {
+ *     super(client, {
+ *       requestSchema: CreateUserSchema,
+ *       responseSchema: UserSchema
+ *     });
+ *   }
+ * }
+ *
+ * // Usage:
+ * const user = await endpoint.call({
+ *   pathParams: { id: '123' },
+ *   query: { include: 'posts', limit: 10 }
+ * });
+ * ```
+ */
+export declare abstract class BaseEndpoint<ReqSchema extends z.ZodType, ResSchema extends z.ZodType, PathParams = never, QueryParams = never> {
+    protected client: HttpClient;
+    /** HTTP method for this endpoint */
+    protected abstract readonly method: keyof typeof HTTPMethod;
+    /** URL path (can be a function for dynamic paths) */
+    protected abstract readonly path: string | ((params: PathParams) => string);
+    /** Additional options for the request */
+    protected readonly options?: {
+        /** Override base URL for this call */
+        baseUrlKey?: string;
+    };
+    /** Optional request schema for validation */
+    protected readonly requestSchema?: ReqSchema;
+    /** Response schema for validation */
+    protected readonly responseSchema: ResSchema;
+    /**
+     * @param client - HttpClient instance
+     * @param cfg - Configuration with request and response schemas
+     */
+    constructor(client: HttpClient, cfg: {
+        requestSchema?: ReqSchema;
+        responseSchema: ResSchema;
+    });
+    /**
+     * Call the endpoint with strong typing derived from schemas.
+     * Validates request data before sending and response data after receiving.
+     *
+     * @param config - Request configuration object containing all parameters
+     * @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({
+     *   pathParams: { id: '123' },
+     *   query: { include: 'posts' }
+     * });
+     * // With additional options:
+     * const user = await endpoint.call({
+     *   data: { name: 'John' },
+     *   pathParams: { id: '123' },
+     *   headers: { 'X-Custom': 'value' },
+     *   query: { include: 'posts' }
+     * });
+     * ```
+     */
+    call(config?: EndpointCallConfig<ReqSchema, PathParams, QueryParams>): Promise<z.infer<ResSchema>>;
+}
+//# sourceMappingURL=base-endpoint.d.ts.map

package/dist/endpoint/base-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-endpoint.d.ts","sourceRoot":"","sources":["../../lib/endpoint/base-endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAC5B,SAAS,SAAS,CAAC,CAAC,OAAO,EAC3B,UAAU,GAAG,KAAK,EAClB,WAAW,GAAG,KAAK,IACjB;IACF,qEAAqE;IACrE,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,8BAAsB,YAAY,CAChC,SAAS,SAAS,CAAC,CAAC,OAAO,EAC3B,SAAS,SAAS,CAAC,CAAC,OAAO,EAC3B,UAAU,GAAG,KAAK,EAClB,WAAW,GAAG,KAAK;IAqBjB,SAAS,CAAC,MAAM,EAAE,UAAU;IAnB9B,oCAAoC;IACpC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,UAAU,CAAC;IAC5D,qDAAqD;IACrD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC,CAAC;IAC5E,yCAAyC;IACzC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAC3B,sCAAsC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IAC7C,qCAAqC;IACrC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IAE7C;;;OAGG;gBAES,MAAM,EAAE,UAAU,EAC5B,GAAG,EAAE;QACH,aAAa,CAAC,EAAE,SAAS,CAAC;QAC1B,cAAc,EAAE,SAAS,CAAC;KAC3B;IAMH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,IAAI,CACR,MAAM,GAAE,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAI5D,GACA,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;CAgC/B"}

package/dist/http/{HttpClient.d.ts → http-client.d.ts}

@@ -147,4 +147,4 @@ export declare class HttpClient {
         response: Response;
     }>;
 }
-//# sourceMappingURL=HttpClient.d.ts.map
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../lib/http/http-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAEL,aAAa,EAEb,UAAU,EAEV,cAAc,EAGf,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,OAAO,CAAmB;IAElC;;;;;OAKG;gBACS,IAAI,EAAE,aAAa;IA4C/B;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,YAAY;IAI1B,OAAO,CAAC,cAAc;IAUtB;;;OAGG;IACH,OAAO,CAAC,KAAK;IAIb;;;OAGG;YACW,SAAS;IAmBvB;;;OAGG;YACW,cAAc;IAM5B;;;OAGG;YACW,aAAa;IAM3B;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,MAAM,OAAO,UAAU,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAmI3C;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAI3C;;;;;;;OAOG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAI3C;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAI3C;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;IAI3C;;;;;;;OAOG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC;CAG5C"}

package/dist/index.cjs

@@ -37,7 +37,7 @@ const HTTPMethod = {
 /**
 * Custom error class for API-related errors.
 * Includes HTTP status codes, response details, and validation errors.
-* 
+*
 * @example
 * ```ts
 * throw new ApiError('Invalid request', {
@@ -103,10 +103,10 @@ const PaginationSchema = zod.z.object({
 /**
 * 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"
@@ -139,12 +139,12 @@ var NoAuth = class {
 /**
 * 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' });
 * ```
@@ -170,12 +170,12 @@ var ApiKeyAuth = class {
 /**
 * 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();
@@ -201,11 +201,11 @@ var BearerTokenAuth = class {
 /**
 * 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);
@@ -230,12 +230,12 @@ function safeParse(schema, data) {
 /**
 * 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 {
@@ -424,11 +424,11 @@ var ConsoleMetricsCollector = class {
 };
 
 //#endregion
-//#region lib/http/HttpClient.ts
+//#region lib/http/http-client.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({
@@ -437,7 +437,7 @@ var ConsoleMetricsCollector = class {
 *   retry: { maxRetries: 3, baseDelayMs: 1000 },
 *   timeout: { requestTimeoutMs: 30000 }
 * });
-* 
+*
 * const { data } = await client.request('GET', '/users', undefined, { query: { page: 1 } });
 * ```
 */
@@ -453,7 +453,7 @@ var HttpClient = class {
 	metrics;
 	/**
 	* Creates a new HTTP client instance.
-	* 
+	*
 	* @param opts - Client configuration options
 	* @throws {Error} If no fetch implementation is available
 	*/
@@ -482,7 +482,7 @@ var HttpClient = class {
 	}
 	/**
 	* Set or update the authentication provider.
-	* 
+	*
 	* @param auth - Authentication provider instance
 	* @example
 	* ```ts
@@ -551,14 +551,14 @@ var HttpClient = class {
 	}
 	/**
 	* 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, {
@@ -673,7 +673,7 @@ var HttpClient = class {
 	}
 	/**
 	* Convenience method for GET requests.
-	* 
+	*
 	* @example
 	* ```ts
 	* const { data } = await client.get('/users', { query: { page: 1 } });
@@ -684,7 +684,7 @@ var HttpClient = class {
 	}
 	/**
 	* Convenience method for POST requests.
-	* 
+	*
 	* @example
 	* ```ts
 	* const { data } = await client.post('/users', { name: 'John' });
@@ -695,7 +695,7 @@ var HttpClient = class {
 	}
 	/**
 	* Convenience method for PUT requests.
-	* 
+	*
 	* @example
 	* ```ts
 	* const { data } = await client.put('/users/1', { name: 'John Updated' });
@@ -706,7 +706,7 @@ var HttpClient = class {
 	}
 	/**
 	* Convenience method for PATCH requests.
-	* 
+	*
 	* @example
 	* ```ts
 	* const { data } = await client.patch('/users/1', { name: 'John' });
@@ -717,7 +717,7 @@ var HttpClient = class {
 	}
 	/**
 	* Convenience method for DELETE requests.
-	* 
+	*
 	* @example
 	* ```ts
 	* const { data } = await client.delete('/users/1');
@@ -729,33 +729,51 @@ var HttpClient = class {
 };
 
 //#endregion
-//#region lib/endpoint/BaseEndpoint.ts
+//#region lib/endpoint/base-endpoint.ts
 /**
 * 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
-* 
+* @template PathParams - Type for path parameters (optional)
+* @template QueryParams - Type for query parameters (optional)
+*
 * @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> {
+*
+* type UserPathParams = { id: string };
+* type UserQueryParams = { include?: string; limit?: number };
+*
+* class GetUser extends BaseEndpoint<
+*   typeof CreateUserSchema,
+*   typeof UserSchema,
+*   UserPathParams,
+*   UserQueryParams
+* > {
 *   protected method = 'GET' as const;
-*   protected path = (args: z.infer<typeof CreateUserSchema>) => `/users/${args.id}`;
-*   
+*   protected path = (params: UserPathParams) => `/users/${params.id}`;
+*
 *   constructor(client: HttpClient) {
-*     super(client, { 
+*     super(client, {
 *       requestSchema: CreateUserSchema,
-*       responseSchema: UserSchema 
+*       responseSchema: UserSchema
 *     });
 *   }
 * }
+*
+* // Usage:
+* const user = await endpoint.call({
+*   pathParams: { id: '123' },
+*   query: { include: 'posts', limit: 10 }
+* });
 * ```
 */
 var BaseEndpoint = class {
+	/** Additional options for the request */
+	options;
 	/** Optional request schema for validation */
 	requestSchema;
 	/** Response schema for validation */
@@ -772,37 +790,45 @@ 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
+	*
+	* @param config - Request configuration object containing all parameters
 	* @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 });
+	* const user = await endpoint.call({
+	*   pathParams: { id: '123' },
+	*   query: { include: 'posts' }
+	* });
+	* // With additional options:
+	* const user = await endpoint.call({
+	*   data: { name: 'John' },
+	*   pathParams: { id: '123' },
+	*   headers: { 'X-Custom': 'value' },
+	*   query: { include: 'posts' }
+	* });
 	* ```
 	*/
-	async call(args, options) {
-		if (this.requestSchema) {
-			const parsed = this.requestSchema.safeParse(args);
+	async call(config = {}) {
+		const { data, query, headers, baseUrlKey, signal, pathParams } = config;
+		if (this.requestSchema && data !== void 0) {
+			const parsed = this.requestSchema.safeParse(data);
 			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" ? 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: mergedQuery && Object.keys(mergedQuery).length > 0 ? mergedQuery : options?.query
+		const pathArgs = pathParams ?? data;
+		const path = typeof this.path === "function" ? this.path(pathArgs) : this.path;
+		const body = this.method !== "GET" && this.method !== "HEAD" ? data : void 0;
+		const queryForRequest = query;
+		const { data: responseData } = await this.client.request(this.method, path, body, {
+			query: queryForRequest,
+			headers,
+			baseUrlKey: baseUrlKey ?? this.options?.baseUrlKey,
+			signal
 		});
-		return parseOrThrow(this.responseSchema, data);
+		return parseOrThrow(this.responseSchema, responseData);
 	}
 };
 
@@ -811,7 +837,7 @@ var BaseEndpoint = class {
 /**
 * 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() });
@@ -825,7 +851,7 @@ const Id = zod.z.union([
 /**
 * Common timestamp fields for entities.
 * Use this for database models with creation/update tracking.
-* 
+*
 * @example
 * ```ts
 * const UserSchema = z.object({
@@ -867,14 +893,14 @@ const ApiErrorSchema = zod.z.object({
 /**
 * 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,