@tahanabavi/typefetch 1.3.0 → 1.5.3

package/dist/index.d.mts

@@ -1,54 +1,198 @@
-import { z } from 'zod';
+import z$1, { z } from 'zod';
 
+type EncryptionMethod = "AES" | "DES" | "RSA" | "Base64" | "Custom";
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
- * Generic request schema:
- *
- * request: z.object({
- *   path: z.object({ ... }).optional(),
- *   query: z.object({ ... }).optional(),
- *   body: z.object({ ... }).optional(),
- * })
+ * DeepEncryptionMap<T>
+ * --------------------
+ * Recursively describes which fields should be encrypted/decrypted.
+ * Supports:
+ *   - Primitive fields → boolean | method
+ *   - Objects → recursively typed maps
+ *   - Arrays → mapping applies to element type (U)
+ *   - Array-map override (optional but supported)
+ */
+type DeepEncryptionMap = boolean | EncryptionMethod | {
+    [key: string]: DeepEncryptionMap;
+} | DeepEncryptionMap[];
+/**
+ * EncryptionConfig
+ * ================
+ * Defines the encryption/decryption strategy for an endpoint.
+ * Both request and response maps are strictly typed based on their respective Zod schemas.
+ */
+type EncryptionConfig<TReq, TRes> = {
+    method: EncryptionMethod | {
+        request?: EncryptionMethod;
+        response?: EncryptionMethod;
+    };
+    /** Map of request fields to encrypt before sending to the server */
+    request?: DeepEncryptionMap;
+    /** Map of response fields to decrypt after receiving from the server */
+    response?: DeepEncryptionMap;
+};
+/**
+ * Base types for Zod schemas representing request and response structures.
+ * These are abstract—each concrete endpoint will define its own Zod object for these.
  */
 type RequestSchema = z.ZodTypeAny;
 type ResponseSchema = z.ZodTypeAny;
+/**
+ * EndpointDef
+ * ============
+ * Defines the structure of a **single API endpoint**, including:
+ * - HTTP method and path
+ * - request/response validation schemas
+ * - optional authentication requirement
+ * - optional mock or static mock data
+ * - optional custom headers and body format
+ */
 type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
-    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** HTTP method used by this endpoint */
+    method: Method;
+    /** URL path for this endpoint, e.g. "/users/:id" */
     path: string;
+    /** Whether this endpoint requires an Authorization token */
     auth?: boolean;
+    /** Zod schema describing the expected request structure */
     request: TReq;
+    /** Zod schema describing the expected response structure */
     response: TRes;
+    /**
+     * Mock data support — enables quick testing or local dev mode:
+     * - Either a function returning a mock response object
+     * - Or a static mock response object
+     */
     mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
+    /**
+     * Field-level encryption configuration.
+     * Allows selecting specific fields in request/response to be encrypted/decrypted.
+     */
+    encryption?: EncryptionConfig<z.infer<TReq>, z.infer<TRes>>;
+    /**
+     * Optional custom headers. Can be:
+     * - A fixed record of header key/values
+     * - A function returning headers derived from the input data
+     */
     headers?: Record<string, string> | ((input: z.infer<TReq>) => Record<string, string>);
+    /**
+     * Defines how the request body should be sent:
+     * - `"json"` (default): serialized as JSON
+     * - `"form-data"`: multipart form
+     */
     bodyType?: "json" | "form-data";
 };
+/**
+ * Contracts
+ * =========
+ * A collection of modules, each containing one or more endpoints.
+ * This defines a **hierarchical API contract**.
+ *
+ * For example:
+ * {
+ *   users: {
+ *     getUser: EndpointDef(...),
+ *     updateUser: EndpointDef(...)
+ *   },
+ *   posts: {
+ *     createPost: EndpointDef(...),
+ *     listPosts: EndpointDef(...)
+ *   }
+ * }
+ */
 type Contracts = {
     [ModuleName: string]: {
         [EndpointName: string]: EndpointDef<RequestSchema, ResponseSchema>;
     };
 };
-interface MiddlewareContext {
+/**
+ * Convenience alias that pins both generic types
+ * to `z.ZodTypeAny`, simplifying the contract declarations.
+ */
+type EndpointDefZ = EndpointDef<RequestSchema, ResponseSchema>;
+/**
+ * Context passed to all middleware functions.
+ * Contains the current request URL, initialization object,
+ * and the specific endpoint definition for metadata access.
+ */
+type RequestParts = {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers: Record<string, string>;
+    isStructured: boolean;
+    rawInput?: unknown;
+};
+interface MiddlewareContext<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema> {
     url: string;
     init: RequestInit;
+    endpoint: EndpointDef<TReq, TRes>;
+    request?: RequestParts;
 }
+/**
+ * The `next()` function type signature used inside middleware.
+ * When called, it executes the next function in the chain
+ * or finally performs the fetch request.
+ */
 type MiddlewareNext = () => Promise<Response>;
-type Middleware<Options = any> = (ctx: MiddlewareContext, next: MiddlewareNext, options?: Options) => Promise<Response>;
+/**
+ * Middleware
+ * ==========
+ * Defines the standard structure for a request middleware.
+ * Middlewares can intercept, modify, or even short-circuit requests.
+ *
+ * @example Logging Example:
+ * const logMiddleware: Middleware = async (ctx, next) => {
+ *   console.log("Request:", ctx.url);
+ *   const res = await next();
+ *   console.log("Response:", res.status);
+ *   return res;
+ * };
+ */
+type Middleware<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema, Options = any> = (ctx: MiddlewareContext<TReq, TRes>, next: MiddlewareNext, options?: Options) => Promise<Response>;
+/**
+ * ErrorLike
+ * =========
+ * Represents the normalized error shape used across the client.
+ * Provides consistency for error handling modules such as RichError.
+ */
 type ErrorLike = {
     message: string;
     status?: number;
     code?: string;
     [key: string]: any;
 };
-type EndpointDefZ = EndpointDef<RequestSchema, ResponseSchema>;
 /**
- * For each endpoint we expose a method:
- *   (input: z.infer<Endpoint["request"]>) => Promise<z.infer<Endpoint["response"]>>
+ * RequestOptions
+ * ==============
+ * Per-request options passed to the client execution:
+ * - Optional AbortSignal (for cancellation)
+ * - Optional timeout (in milliseconds)
+ */
+type RequestOptions = {
+    signal?: AbortSignal;
+    timeout?: number;
+};
+/**
+ * EndpointMethods
+ * ================
+ * Automatically generated method signatures for all endpoints
+ * within a module, based on the Zod contract definitions.
  *
- * So VSCode will show you:
- *   { path?: { ... }, query?: { ... }, body?: { ... } }
+ * Each endpoint method:
+ * - Validates input against its request schema
+ * - Returns a Promise of the parsed and validated response type
  */
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
-    [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
+    [K in keyof M]: (input: z.infer<M[K]["request"]>, // Auto‑derived input type from Zod schema
+    options?: RequestOptions) => Promise<z.infer<M[K]["response"]>>;
 };
+/**
+ * TokenProvider
+ * =============
+ * Specifies the contract for a function that supplies authentication tokens.
+ * Can be synchronous or async, e.g. fetching from localStorage or refreshing with an API.
+ */
 type TokenProvider = () => string | Promise<string>;
 
 declare class RichError extends Error implements ErrorLike {
@@ -61,9 +205,6 @@ declare class RichError extends Error implements ErrorLike {
         message: string;
     });
 }
-/**
- * Strongly-typed HTTP client built from Zod contracts.
- */
 declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private config;
     private contracts;
@@ -74,6 +215,7 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private mockDelay;
     private responseWrapper?;
     private tokenProvider?;
+    private retryConfig?;
     private _modules;
     constructor(config: {
         baseUrl: string;
@@ -85,92 +227,35 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
             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.
-     */
+    use<T>(middleware: Middleware<any, any, T>, options?: T): void;
     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.
-     */
+    setRetryConfig(config: ApiClient<C>["retryConfig"]): void;
+    setTokenProvider(provider: TokenProvider): void;
     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(),
-     *     header: z.object({...}).optional(),
-     *   })
-     *
-     * If the parsed request does not contain `path`, `header`,`query` or `body`,
-     * the entire input is treated as the legacy flat request body.
-     */
     private request;
-    /**
-     * Builds final URL and body from endpoint + request input.
-     * Supports both structured `{ path, query, body, headers }` and legacy flat input.
-     */
+    private performRequestLogic;
+    private executeWithRetry;
+    private getBackoffDelay;
     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 extractRequestParts;
+    private isStructuredRequestInput;
+    private isObjectRecord;
+    private applyPathParams;
+    private appendQueryParams;
+    private appendQueryValue;
+    private appendFormValue;
+    private normalizeHeaders;
     private createError;
-    /**
-     * Normalizes unknown errors into a RichError instance.
-     * Zod validation errors are converted into a standardized validation error.
-     */
     private normalizeError;
+    private handleMockRequest;
 }
 
 type LoggingOptions = {
@@ -178,7 +263,7 @@ type LoggingOptions = {
     logResponse?: boolean;
     debug?: boolean;
 };
-declare const loggingMiddleware: Middleware<LoggingOptions>;
+declare const loggingMiddleware: Middleware<z$1.ZodTypeAny, z$1.ZodTypeAny, LoggingOptions>;
 
 type RetryOptions = {
     maxRetries?: number;
@@ -186,17 +271,129 @@ type RetryOptions = {
 };
 declare const retryMiddleware: (options?: RetryOptions) => Middleware;
 
+/**
+ * TokenManagementOptions
+ * ======================
+ * Configuration structure for supplying credentials to the authentication layer.
+ *
+ * @property refreshToken A required asynchronous function responsible for
+ *                        obtaining a current, valid access token string. This allows
+ *                        for token fetching from storage or re-issuance upon expiry.
+ */
 type AuthOptions = {
     refreshToken?: () => Promise<string>;
 };
-declare const authMiddleware: Middleware<AuthOptions>;
+/**
+ * AuthenticationInjectorMiddleware
+ * ==================================
+ * This middleware operates early in the request pipeline to ensure every
+ * outgoing request is properly authorized by prepending an Authorization header.
+ *
+ * Core Logic:
+ * -----------
+ * 1. It checks if an explicit `refreshToken` supplier was configured in its options.
+ * 2. If present, it synchronously calls this supplier to obtain the latest token.
+ * 3. The resulting token is formatted as a standard 'Bearer' token and merged
+ *    into the request's `init.headers`.
+ * 4. The request context (`ctx`) is then passed downstream.
+ *
+ * Note on Error Handling:
+ * -----------------------
+ * Any failure during the token retrieval process (e.g., if `refreshToken` throws)
+ * results in the error being caught, and the request proceeds **without** an
+ * Authorization header. This design defers failure response handling to
+ * subsequent middleware or the final network fetcher.
+ *
+ * @param ctx The current request context object, including mutable `init` properties.
+ * @param next The function to execute the rest of the middleware chain.
+ * @param options The specific configuration passed to this middleware instance.
+ *
+ * @returns The final `Response` object after the network call completes.
+ *
+ * @example
+ * // Assuming token retrieval logic is defined elsewhere
+ * const tokenSupplier = () => fetchTokenFromSecureStorage();
+ *
+ * client.addInterceptor(
+ *   authMiddleware({ refreshToken: tokenSupplier })
+ * );
+ */
+declare const authMiddleware: Middleware<z$1.ZodTypeAny, z$1.ZodTypeAny, AuthOptions>;
 
+/**
+ * CacheOptions
+ * ============
+ * Options for configuring the cache middleware.
+ * - `ttl` (Time To Live): Duration (in milliseconds) to keep cached GET responses.
+ *   After this time, cached data expires and a fresh network call is performed.
+ */
 type CacheOptions = {
     ttl?: number;
 };
+/**
+ * cacheMiddleware
+ * ===============
+ * A generic caching middleware for GET requests in the ApiClient.
+ * It stores successful responses in memory based on URL and method,
+ * returning cached data for subsequent identical requests until the TTL expires.
+ *
+ * Purpose:
+ * --------
+ * - Reduces redundant network calls
+ * - Improves performance for frequently fetched resources
+ * - Useful for lightweight front-end caching (not suitable for sensitive data)
+ *
+ * Behavior:
+ * ---------
+ * 1. Only applies to `GET` requests; all other HTTP methods bypass caching.
+ * 2. Caches the parsed JSON response in a simple in-memory Map.
+ * 3. On subsequent requests:
+ *    - If the cache entry exists and hasn’t expired, returns a synthetic
+ *      `Response` object built from cached JSON.
+ *    - Otherwise performs the network call and refreshes the cache.
+ *
+ * @param options - Optional cache configuration (TTL in ms)
+ *
+ * @returns Middleware function compatible with the ApiClient pipeline.
+ *
+ * @example
+ * client.use(
+ *   cacheMiddleware({ ttl: 120000 }) // cache GET results for 2 minutes
+ * );
+ *
+ * @note Each middleware instance maintains its own internal cache
+ *       and is memory-scoped (not persistent between reloads).
+ */
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
-declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery extends z.ZodRawShape = {}, TBody extends z.ZodTypeAny = z.ZodUndefined>() => (defs: {
+type SymmetricKeyMaterial = {
+    type: "symmetric";
+    key: string;
+};
+type RSAKeyMaterial = {
+    type: "rsa";
+    publicKey: string;
+    privateKey: string;
+};
+type KeyMaterial = SymmetricKeyMaterial | RSAKeyMaterial;
+type CustomHandlers = {
+    encrypt: (value: string, key: KeyMaterial) => string | Promise<string>;
+    decrypt: (value: string, key: KeyMaterial) => string | Promise<string>;
+};
+interface EncryptionOptions {
+    keyProvider: () => KeyMaterial | Promise<KeyMaterial>;
+    customHandlers?: CustomHandlers;
+    /**
+     * true  = throw when encryption/decryption fails, which avoids leaking plaintext.
+     * false = log and continue/fallback to the original response.
+     * Default: true
+     */
+    failClosed?: boolean;
+}
+declare function processDeep<T = unknown>(data: unknown, map: DeepEncryptionMap | null | undefined, defaultMethod: EncryptionMethod, transform: (value: unknown, method: EncryptionMethod) => Promise<unknown>): Promise<T>;
+declare const encryptionMiddleware: Middleware<z.ZodTypeAny, z.ZodTypeAny, EncryptionOptions>;
+
+declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery extends z.ZodRawShape = {}, TBody extends z.ZodTypeAny = z.ZodUndefined>() => (defs?: {
     path?: z.ZodObject<TPath>;
     query?: z.ZodObject<TQuery>;
     body?: TBody;
@@ -218,4 +415,4 @@ declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery exten
     headers: any;
 }> extends infer T_9 ? { [k_5 in keyof T_9]: T_9[k_5]; } : never>;
 
-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, makeRequestSchema, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type DeepEncryptionMap, type EncryptionConfig, type EncryptionMethod, type EncryptionOptions, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Method, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestOptions, type RequestParts, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, encryptionMiddleware, loggingMiddleware, makeRequestSchema, processDeep, retryMiddleware };