@tahanabavi/typefetch 1.1.0 → 1.2.1

package/dist/index.d.ts

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 
-type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
+/**
+ * Generic request schema:
+ *
+ * request: z.object({
+ *   path: z.object({ ... }).optional(),
+ *   query: z.object({ ... }).optional(),
+ *   body: z.object({ ... }).optional(),
+ * })
+ */
+type RequestSchema = z.ZodTypeAny;
+type ResponseSchema = z.ZodTypeAny;
+type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
     method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
     path: string;
     auth?: boolean;
@@ -10,7 +21,7 @@ type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
 };
 type Contracts = {
     [ModuleName: string]: {
-        [EndpointName: string]: EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+        [EndpointName: string]: EndpointDef<RequestSchema, ResponseSchema>;
     };
 };
 interface MiddlewareContext {
@@ -25,10 +36,18 @@ type ErrorLike = {
     code?: string;
     [key: string]: any;
 };
-type EndpointDefZ = EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+type EndpointDefZ = EndpointDef<RequestSchema, ResponseSchema>;
+/**
+ * For each endpoint we expose a method:
+ *   (input: z.infer<Endpoint["request"]>) => Promise<z.infer<Endpoint["response"]>>
+ *
+ * So VSCode will show you:
+ *   { path?: { ... }, query?: { ... }, body?: { ... } }
+ */
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
     [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
 };
+type TokenProvider = () => string | Promise<string>;
 
 declare class RichError extends Error implements ErrorLike {
     status?: number;
@@ -40,6 +59,18 @@ declare class RichError extends Error implements ErrorLike {
         message: string;
     });
 }
+/**
+ * Strongly-typed HTTP client built from Zod contracts.
+ *
+ * Features:
+ * - Type-safe request & response based on Zod schemas
+ * - Path/query/body support via { path?, query?, body? } shape
+ * - Backwards compatible with flat request bodies
+ * - Pluggable middleware pipeline
+ * - Token and tokenProvider support
+ * - Mock mode with configurable delay
+ * - Optional response wrapper for APIs that nest data
+ */
 declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private config;
     private contracts;
@@ -49,30 +80,107 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private useMockData;
     private mockDelay;
     private responseWrapper?;
+    private tokenProvider?;
     private _modules;
     constructor(config: {
         baseUrl: string;
         token?: string;
+        tokenProvider?: TokenProvider;
         useMockData?: boolean;
         mockDelay?: {
             min: number;
             max: number;
         };
     }, contracts: C);
+    /**
+     * Builds the strongly-typed `modules` API from the provided contracts.
+     * Must be called once after constructing the client.
+     */
     init(): void;
+    /**
+     * Type-safe entrypoint for calling API endpoints.
+     * Populated by `init()` based on the `contracts` passed to the constructor.
+     */
     get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
+    /**
+     * Registers a middleware in the pipeline.
+     * Middlewares are executed in reverse order of registration.
+     */
     use<T>(middleware: Middleware<T>, options?: T): void;
+    /**
+     * Registers a global error handler.
+     * The handler is invoked for normalized errors before they are re-thrown.
+     */
     onError(handler: (error: E) => void): void;
+    /**
+     * Registers a transformation function applied to all successful responses
+     * after Zod parsing.
+     */
     useResponseTransform(fn: (data: any) => any): void;
+    /**
+     * Enables or disables mock mode. When enabled, endpoints with `mockData`
+     * return mocked responses instead of performing network requests.
+     */
     setMockMode(enabled: boolean, delay?: {
         min: number;
         max: number;
     }): void;
+    /**
+     * Registers a schema wrapper for APIs that wrap data in an envelope.
+     * Example: { success, data, message, code, ... }.
+     */
     setResponseWrapper(wrapper: (successResponse: z.ZodTypeAny) => z.ZodTypeAny): void;
+    /**
+     * Sets or updates the token provider used for authenticated endpoints.
+     * Overrides any static token provided in the constructor.
+     */
+    setTokenProvider(provider: TokenProvider): void;
+    /**
+     * Returns the current token, preferring the tokenProvider if present,
+     * otherwise falling back to the static token from the constructor.
+     */
+    getCurrentToken(): Promise<string | undefined>;
+    /**
+     * Executes a single endpoint request.
+     *
+     * Expected request shape (new style):
+     *   z.object({
+     *     path: z.object({...}).optional(),
+     *     query: z.object({...}).optional(),
+     *     body: z.any().optional(),
+     *   })
+     *
+     * If the parsed request does not contain `path`, `query` or `body`,
+     * the entire input is treated as the legacy flat request body.
+     */
     private request;
+    /**
+     * Builds the effective URL and request body for an endpoint.
+     *
+     * - Legacy mode: if the input does not contain `path`, `query` or `body`,
+     *   the entire input is used as the JSON request body for non-GET methods.
+     *
+     * - New mode: uses `path` to interpolate `:param` segments, `query` to
+     *   construct the query string, and `body` as the JSON payload.
+     */
+    private buildUrlAndBody;
+    /**
+     * Returns a mocked response based on `endpoint.mockData`,
+     * respecting the configured mock delay and response wrapper.
+     */
     private handleMockRequest;
+    /**
+     * Returns a random delay in milliseconds within the current mock delay range.
+     */
     private getRandomDelay;
+    /**
+     * Creates a RichError instance from a partial error description.
+     */
     private createError;
+    /**
+     * Normalizes unknown errors into a RichError instance.
+     * Zod validation errors are converted into a standardized validation error.
+     */
     private normalizeError;
 }
 
@@ -99,4 +207,4 @@ type CacheOptions = {
 };
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };