@tahanabavi/typefetch 1.1.1 → 1.2.2

package/README.md

@@ -1,309 +1,222 @@
 # TypeFetch
 
-TypeFetch is a type-safe client for working with APIs, built with TypeScript and Zod. This project allows you to define API contracts and safely use types, while also supporting middlewares, error handling, response transformation, mock data, and response wrappers.
+TypeFetch is a strongly-typed HTTP client built on TypeScript and Zod.
 
----
+You define your API once using Zod schemas, and TypeFetch generates a fully type-safe client with:
 
-## Features
-
-- Fully type-safe using TypeScript and Zod
-- Define contracts for modules and endpoints
-- Support for middlewares to add custom behavior before or after requests
-- Error handling with the `RichError` class
-- Ability to transform responses using a response transformer
-- Authentication support via token
-- Mock data support for development and testing
-- Response wrapper for consistent API response formats
-
----
+- End-to-end type safety
+- Automatic URL handling (path, query, body)
+- Middleware pipeline (logging, retry, cache, auth)
+- Mock mode for development
+- Dynamic token providers
+- Response wrappers for consistent API envelopes
+- Unified error system (RichError)
 
 ## Installation
 
-```bash
 npm install @tahanabavi/typefetch
+
 # or
+
 yarn add @tahanabavi/typefetch
-```
 
----
+## Key Features
+
+1. Type-Safe API Client  
+   Define your API with Zod schemas and get full type safety for request and response types.
 
-## What's New in v1.1.1
+2. Structured Request Support  
+   Each request may contain:
 
-### 🎯 Mock Data Support
+   - path: URL parameters (fills /users/:id)
+   - query: URL query string ?page=1&limit=10
+   - body: JSON payload for POST/PUT/PATCH
 
-- Add mock data to endpoints for development and testing
-- Configurable random delays to simulate network latency
-- Support for both static data and dynamic functions
-- Runtime toggle between mock and real API modes
+   The client automatically builds URLs and bodies correctly.
 
-### 🔄 Response Wrapper
+3. Backward Compatibility  
+   If your request schema is flat (z.object({ name: z.string() })), TypeFetch automatically treats it as a simple body payload—no breaking changes.
 
-- Consistent API response format handling
-- Automatic validation of wrapped responses
-- Support for success/error response patterns
-- Seamless integration with existing contracts
+4. Middlewares  
+   Middlewares allow modifying requests and responses.
+   Built-in middlewares include:
 
-### 🚀 Enhanced Error Handling
+   - loggingMiddleware
+   - retryMiddleware
+   - authMiddleware
+   - cacheMiddleware
 
-- Better Zod error wrapping and reporting
-- Improved type safety for response wrappers
+5. Token Provider System  
+   Provide tokens dynamically using:
 
-### 🔧 Token Provider System
+   - token: static auth token
+   - tokenProvider: function or async function returning a token
 
-- Dynamic token resolution: Tokens resolved at request time, not initialization
-- Universal compatibility: Works seamlessly in both server and client environments
-- Async token providers: Support for asynchronous token retrieval
-  - Multiple token sources: Flexible token sourcing from cookies, context, or external services
+6. Mock Mode  
+   Provides mock responses based on endpoint.mockData, with configurable fake delays.
 
----
+7. Response Wrapper  
+   For APIs that wrap responses:
 
-## Defining Contracts
+   ```
+   {
+     "success": true,
+     "data": {...},
+     "timestamp": "...",
+     "requestId": "..."
+   }
+   ```
 
-Contracts are defined using the `Contracts` and `EndpointDef` types.
+   TypeFetch unwraps the response automatically.
 
-```ts
+## Defining API Contracts
+
+Example contract definition:
+
+```
 import { z } from "zod";
 
 const contracts = {
   user: {
     getUser: {
       method: "GET",
-      path: "/user/:id",
+      path: "/users/:id",
       auth: true,
-      request: z.object({ id: z.string() }),
-      response: z.object({ id: z.string(), name: z.string() }),
-      // Optional mock data
-      mockData: { id: "1", name: "John Doe" },
+      request: z.object({
+        path: z.object({ id: z.string() }).optional(),
+        query: z.object({}).optional(),
+        body: z.never().optional(),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+      mockData: { id: "1", name: "John Doe" }
     },
+
     createUser: {
       method: "POST",
-      path: "/user",
-      request: z.object({ name: z.string() }),
-      response: z.object({ id: z.string(), name: z.string() }),
-      // Dynamic mock data function
-      mockData: () => ({ id: Math.random().toString(), name: "Dynamic User" }),
-    },
-  },
-} as const;
+      path: "/users",
+      auth: true,
+      request: z.object({
+        path: z.object({}).optional(),
+        query: z.object({}).optional(),
+        body: z.object({ name: z.string() }).optional(),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+      mockData: () => ({
+        id: Math.random().toString(36).slice(2),
+        name: "Mock User",
+      }),
+    }
+  }
+};
 ```
 
----
-
-## Using `ApiClient`
+## Using ApiClient
 
-```ts
-import { ApiClient, RichError } from "typefetch";
+```
+import { ApiClient } from "@tahanabavi/typefetch";
 
 const client = new ApiClient(
   {
     baseUrl: "https://api.example.com",
-    token: "your-auth-token",
-    useMockData: true,
-    mockDelay: { min: 100, max: 1000 },
+    tokenProvider: () => "dynamic-token",
+    useMockData: false
   },
   contracts
 );
 
 client.init();
 
-const { modules: api } = client;
+const api = client.modules;
 
-const user = await api.user.getUser({ id: "123" });
-const newUser = await api.user.createUser({ name: "Taha" });
+const user = await api.user.getUser({ path: { id: "123" } });
+const created = await api.user.createUser({ body: { name: "Alice" } });
 ```
 
----
-
-## Error Handling
+## Middlewares
 
-All errors are provided via the `RichError` class. You can define a custom error handler:
+Example custom middleware:
 
-```ts
-client.onError((error: RichError) => {
-  console.error("API Error:", error.message, error.status, error.code);
+```
+client.use(async (ctx, next) => {
+  console.log("Request to:", ctx.url);
+  const res = await next();
+  console.log("Response:", res.status);
+  return res;
 });
 ```
 
----
-
-## Middlewares
-
-You can add custom behavior before or after requests. Middlewares work similarly to Express:
+Built-in middlewares:
 
-```ts
-client.use(
-  async (ctx: MiddlewareContext, next: MiddlewareNext, options?: any) => {
-    console.log("Request URL:", ctx.url);
-    const response = await next();
-    console.log("Response status:", response.status);
-    return response;
-  }
-);
 ```
-
-### Built-in Middlewares
-
-This project provides some built-in middlewares:
-
-```ts
 import {
-  LoggingMiddleware,
-  RetryMiddleware,
-  AuthMiddleware,
-  CacheMiddleware,
-} from "typefetch/middlewares";
-
-client.use(LoggingMiddleware);
-client.use(RetryMiddleware, { maxRetries: 3, delay: 100 });
-client.use(AuthMiddleware, { refreshToken: () => "your-auth-token" });
-client.use(CacheMiddleware, { ttl: 60 * 1000 });
+  loggingMiddleware,
+  retryMiddleware,
+  cacheMiddleware,
+  authMiddleware
+} from "@tahanabavi/typefetch/middlewares";
+
+  client.use(loggingMiddleware, { logRequest: true });
+  client.use(retryMiddleware, { maxRetries: 3, delay: 100 });
+  client.use(cacheMiddleware, { ttl: 60000 });
+  client.use(authMiddleware, {
+  refreshToken: async () => "refreshed-token"
+});
 ```
 
-- `LoggingMiddleware` – Logs requests and responses
-- `RetryMiddleware` – Retries failed requests
-- `AuthMiddleware` – Automatically adds Authorization headers
-- `CacheMiddleware` – Caches responses to reduce repeated requests
-
----
-
+## Mock Mode
+```
+client.setMockMode(true, { min: 200, max: 1000 });
+client.setMockMode(false);
+```
 ## Response Transformation
-
-You can transform the response format before returning it:
-
-```ts
+```
 client.useResponseTransform((data) => {
-  return { ...data, fetchedAt: new Date() };
+  return {
+    ...data,
+    transformedAt: new Date().toISOString()
+  };
 });
 ```
-
----
-
-## Mock Data Features
-
-Static Mock Data:
-
-```ts
-mockData: { id: "1", name: "Static User" }
-```
-
-Dynamic Mock Data:
-
-```ts
-mockData: () => ({ id: Math.random().toString(), name: `User-${Date.now()}` });
+## Response Wrapper Example
 ```
-
-Runtime Control:
-
-```ts
-client.setMockMode(true, { min: 100, max: 2000 });
-client.setMockMode(false);
+const wrapper = (successResponse) =>
+z.union([
+  z.object({
+    success: z.literal(true),
+    data: successResponse,
+    timestamp: z.string(),
+    requestId: z.string(),
+  }),
+  z.object({
+    success: z.literal(false),
+    message: z.string(),
+    code: z.number(),
+    timestamp: z.string(),
+    requestId: z.string(),
+  }),
+]);
+
+client.setResponseWrapper(wrapper);
 ```
-
----
-
-## Response Wrapper Features
-
-```ts
-const apiResponseWrapper = (successResponse: z.ZodTypeAny) =>
-  z.union([
-    z.object({
-      success: z.literal(true),
-      data: successResponse,
-      timestamp: z.string(),
-      requestId: z.string(),
-    }),
-    z.object({
-      success: z.literal(false),
-      message: z.string(),
-      code: z.number(),
-      timestamp: z.string(),
-      requestId: z.string(),
-    }),
-  ]);
-
-client.setResponseWrapper(apiResponseWrapper);
+## Error Handling
 ```
-
----
-
-## Important Notes
-
-- Always call `client.init()` before using endpoints.
-- Types are automatically inferred from Zod, making inputs and outputs type-safe.
-- Middleware execution order: first added middleware runs last, last added middleware runs first.
-- Mock data is used only when `useMockData` is true and mock data is defined.
-- Response wrapper automatically handles success/error patterns.
-
----
-
-## Full Example
-
-```ts
-import { z } from "zod";
-import { ApiClient, RichError } from "typefetch";
-import { LoggingMiddleware, RetryMiddleware } from "typefetch/middlewares";
-
-const contracts = {
-  user: {
-    getUser: {
-      method: "GET",
-      path: "/users/:id",
-      auth: true,
-      request: z.object({ id: z.string() }),
-      response: z.object({
-        id: z.string(),
-        name: z.string(),
-        email: z.string(),
-      }),
-      mockData: { id: "1", name: "John Doe", email: "john@example.com" },
-    },
-  },
-} as const;
-
-const apiResponseWrapper = (successResponse: z.ZodTypeAny) =>
-  z.union([
-    z.object({
-      success: z.literal(true),
-      data: successResponse,
-      timestamp: z.string(),
-      requestId: z.string(),
-    }),
-    z.object({
-      success: z.literal(false),
-      message: z.string(),
-      code: z.number(),
-      timestamp: z.string(),
-      requestId: z.string(),
-    }),
-  ]);
-
-const client = new ApiClient(
-  {
-    baseUrl: "https://api.example.com",
-    token: "abc123",
-    useMockData: process.env.NODE_ENV === "development",
-  },
-  contracts
-);
-
-client.init();
-client.setResponseWrapper(apiResponseWrapper);
-client.use(LoggingMiddleware);
-client.use(RetryMiddleware, { maxRetries: 2 });
-
-client.onError((err: RichError) => {
-  console.error("Error:", err.message);
+client.onError((err) => {
+  console.error("API Error:", err.message, err.status, err.code);
 });
-
-const { modules: api } = client;
-
-(async () => {
-  const user = await api.user.getUser({ id: "1" });
-  console.log(user);
-})();
 ```
+## Notes
 
----
+- Always call client.init() before using client.modules.
+- Middlewares run in reverse registration order.
+- Endpoints requiring auth must have a token or tokenProvider.
+- All responses are validated via Zod.
+- Backward-compatible request support makes migration safe.
 
 ## License
 

package/dist/index.d.mts

@@ -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,7 +36,14 @@ 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"]>>;
 };
@@ -41,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;
@@ -62,22 +92,95 @@ 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.
+     */
     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;
 }
 
@@ -104,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, type TokenProvider, 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 };