@tahanabavi/typefetch 1.3.0 → 1.5.3

package/README.md

@@ -1,361 +1,1187 @@
 # TypeFetch
 
-TypeFetch is a strongly-typed HTTP client built on **TypeScript** and **Zod**.
+**TypeFetch** is a strongly typed HTTP client for TypeScript projects, built around **Zod** contracts.
 
-You define your API once using Zod schemas, and TypeFetch generates a fully type-safe client with:
+Define your API once with Zod schemas, then TypeFetch generates a fully typed client with request validation, response validation, middleware support, retries, mock data, response wrappers, token handling, and structured request support.
 
-- End-to-end type safety
-- Structured request support: `{ path, query, body, headers }`
-- Automatic URL handling (path parameters, query string, JSON body)
-- Middleware pipeline (logging, retry, cache, auth, custom)
-- Mock mode for development
-- Dynamic token providers
-- Response wrappers for consistent API envelopes
-- Unified error system (`RichError`)
-- Optional `form-data` body support for file uploads
+```ts
+const user = await api.user.getUser({
+  path: { id: "123" },
+});
+```
+
+---
+
+## Features
+
+* End-to-end TypeScript inference from Zod schemas
+* Runtime request and response validation
+* Structured request model: `{ path, query, body, headers }`
+* Automatic path parameter injection
+* Automatic query string generation
+* JSON and `form-data` request bodies
+* Middleware pipeline
+* Built-in retry engine with backoff strategies
+* Timeout and `AbortController` support
+* Static tokens and dynamic token providers
+* Mock mode for development and testing
+* Response wrapper support for API envelopes
+* Normalized error handling with `RichError`
+* Field-level encryption middleware
+* Backward-compatible flat request schemas
 
 ---
 
 ## Installation
 
 ```bash
-npm install @tahanabavi/typefetch
-# or
-yarn add @tahanabavi/typefetch
+npm install @tahanabavi/typefetch zod
 ```
 
----
-
-## Core Concepts
+Or with Yarn:
 
-### 1. Type-Safe API Client
-
-Define your API with Zod schemas and get full type safety for request and response types.
+```bash
+yarn add @tahanabavi/typefetch zod
+```
 
-Each endpoint has:
+Or with pnpm:
 
-- `method`: HTTP verb (`GET | POST | PUT | PATCH | DELETE`)
-- `path`: path template (e.g. `/users/:id`)
-- `auth?`: whether a token is required
-- `request`: Zod schema for the request
-- `response`: Zod schema for the response
-- `mockData?`: static or dynamic mock response
-- `headers?`: static or function-based default headers
-- `bodyType?`: `"json"` (default) or `"form-data"`
+```bash
+pnpm add @tahanabavi/typefetch zod
+```
 
-### 2. Structured Request Shape
+---
 
-The recommended request shape is:
+## Quick Start
 
 ```ts
-z.object({
-  path: z.object({ ... }).optional(),    // URL params → /users/:id
-  query: z.object({ ... }).optional(),   // query string → ?page=1
-  body: z.object({ ... }).optional(),    // JSON body
-  headers: z.record(z.string()).optional(), // per-call extra headers
-})
-```
+import { z } from "zod";
+import { ApiClient } from "@tahanabavi/typefetch";
+
+const contracts = {
+  user: {
+    getUser: {
+      method: "GET",
+      path: "/users/:id",
+      auth: true,
+      request: z.object({
+        path: z.object({
+          id: z.string(),
+        }),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+} as const;
 
-TypeFetch will:
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    tokenProvider: async () => "your-token",
+  },
+  contracts,
+);
 
-- Replace `:param` segments in the path using `path`
-- Build query string from `query`
-- Serialize `body` as JSON (or `FormData` if `bodyType: "form-data"`)
-- Merge headers from:
-  - auth (Authorization)
-  - endpoint-level `headers`
-  - per-call `headers` in the request (highest priority)
+client.init();
 
-### 3. Backward Compatibility
+const api = client.modules;
 
-If your `request` schema is **flat** (e.g. `z.object({ name: z.string() })`) and does **not** contain `path`, `query`, `body`, or `headers`, TypeFetch treats the entire object as the request body for non-GET methods.
+const user = await api.user.getUser({
+  path: { id: "123" },
+});
 
-This makes migration to the structured format incremental and safe.
+console.log(user.name);
+```
 
 ---
 
 ## Defining API Contracts
 
-Example contract definition:
+A TypeFetch contract is a grouped object of modules and endpoints.
 
 ```ts
-import { z } from "zod";
-import { Contracts, EndpointDef } from "@tahanabavi/typefetch";
-
 const contracts = {
   user: {
     getUser: {
       method: "GET",
       path: "/users/:id",
-      auth: true,
       request: z.object({
-        path: z.object({ id: z.string() }).optional(),
-        query: z.object({}).optional(),
-        body: z.never().optional(),
-        headers: z.record(z.string()).optional(),
+        path: z.object({
+          id: z.string(),
+        }),
       }),
       response: z.object({
         id: z.string(),
         name: z.string(),
       }),
-      mockData: { id: "1", name: "John Doe" },
     },
 
     createUser: {
       method: "POST",
       path: "/users",
-      auth: true,
       request: z.object({
-        path: z.object({}).optional(),
-        query: z.object({}).optional(),
-        body: z
-          .object({
-            name: z.string(),
-          })
-          .optional(),
-        headers: z.record(z.string()).optional(),
+        body: z.object({
+          name: z.string(),
+          email: z.string().email(),
+        }),
       }),
       response: z.object({
         id: z.string(),
         name: z.string(),
-      }),
-      mockData: () => ({
-        id: Math.random().toString(36).slice(2),
-        name: "Mock User",
+        email: z.string(),
       }),
     },
   },
 } as const;
 ```
 
-You **do not** have to use these explicit generic annotations if you don’t want to – they are shown here only for clarity. In most cases, simple `as const` + inference is enough.
+After calling `client.init()`, TypeFetch generates typed methods:
+
+```ts
+await api.user.getUser({
+  path: { id: "123" },
+});
+
+await api.user.createUser({
+  body: {
+    name: "Taha",
+    email: "taha@example.com",
+  },
+});
+```
 
 ---
 
-## Using `ApiClient`
+## Structured Request Model
+
+The recommended request shape is:
 
 ```ts
-import { ApiClient } from "@tahanabavi/typefetch";
-import { contracts } from "./contracts";
+z.object({
+  path: z.object({}).optional(),
+  query: z.object({}).optional(),
+  body: z.any().optional(),
+  headers: z.record(z.string()).optional(),
+});
+```
 
-const client = new ApiClient(
-  {
-    baseUrl: "https://api.example.com",
-    tokenProvider: () => "dynamic-token", // or undefined for public endpoints
-    useMockData: false,
+Each section has a specific purpose.
+
+| Key       | Purpose                                    |
+| --------- | ------------------------------------------ |
+| `path`    | Replaces path parameters like `/users/:id` |
+| `query`   | Builds the query string                    |
+| `body`    | Sent as the JSON or `form-data` body       |
+| `headers` | Per-request headers                        |
+
+Example:
+
+```ts
+const contracts = {
+  user: {
+    updateUser: {
+      method: "PATCH",
+      path: "/users/:id",
+      request: z.object({
+        path: z.object({
+          id: z.string(),
+        }),
+        query: z.object({
+          notify: z.boolean().optional(),
+        }).optional(),
+        body: z.object({
+          name: z.string(),
+        }),
+        headers: z.record(z.string()).optional(),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
   },
-  contracts
-);
+} as const;
+```
 
-client.init();
+Usage:
 
-const api = client.modules;
+```ts
+await api.user.updateUser({
+  path: { id: "123" },
+  query: { notify: true },
+  headers: {
+    "X-Tenant": "main",
+  },
+  body: {
+    name: "Taha",
+  },
+});
+```
+
+TypeFetch sends:
 
-const user = await api.user.getUser({ path: { id: "123" } });
-const created = await api.user.createUser({ body: { name: "Alice" } });
+```ts
+PATCH /users/123?notify=true
 ```
 
-- `client.init()` builds the typed `modules` API using your contracts.
-- `api.user.getUser` and `api.user.createUser` are fully typed from the Zod schemas.
+With body:
 
----
+```json
+{
+  "name": "Taha"
+}
+```
 
-## Middlewares
+---
 
-Middlewares allow you to hook into the request/response lifecycle.
+## Request Schema Helper
 
-### Custom Middleware Example
+You can use `makeRequestSchema` to make structured request schemas easier to write.
 
 ```ts
-client.use(async (ctx, next) => {
-  console.log("Request to:", ctx.url);
-  const res = await next();
-  console.log("Response:", res.status);
-  return res;
+import { z } from "zod";
+import { makeRequestSchema } from "@tahanabavi/typefetch";
+
+const updateUserRequest = makeRequestSchema<
+  { id: z.ZodString },
+  { notify: z.ZodOptional<z.ZodBoolean> },
+  z.ZodObject<{
+    name: z.ZodString;
+  }>
+>()({
+  path: z.object({
+    id: z.string(),
+  }),
+  query: z.object({
+    notify: z.boolean().optional(),
+  }),
+  body: z.object({
+    name: z.string(),
+  }),
+  headers: z.record(z.string()).optional(),
 });
 ```
 
-### Built-in Middlewares
+Use it inside an endpoint:
 
 ```ts
-import {
-  loggingMiddleware,
-  retryMiddleware,
-  cacheMiddleware,
-  authMiddleware,
-} from "@tahanabavi/typefetch/middlewares";
+const contracts = {
+  user: {
+    updateUser: {
+      method: "PATCH",
+      path: "/users/:id",
+      request: updateUserRequest,
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+} as const;
+```
 
-client.use(loggingMiddleware, {
-  logRequest: true,
-  logResponse: true,
-  debug: true,
-});
-client.use(retryMiddleware, { maxRetries: 3, delay: 100 });
-client.use(cacheMiddleware, { ttl: 60000 });
-client.use(authMiddleware, {
-  refreshToken: async () => "refreshed-token",
+---
+
+## Backward Compatibility
+
+Flat request schemas are still supported.
+
+```ts
+const contracts = {
+  user: {
+    createUser: {
+      method: "POST",
+      path: "/users",
+      request: z.object({
+        name: z.string(),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+} as const;
+```
+
+Usage:
+
+```ts
+await api.user.createUser({
+  name: "Taha",
 });
 ```
 
-- **`loggingMiddleware`** – logs requests and responses (controlled by `debug`, `logRequest`, `logResponse`).
-- **`retryMiddleware`** – retries failed requests with configurable `maxRetries` and `delay`.
-- **`cacheMiddleware`** – caches GET responses in-memory per URL with `ttl` (ms).
-- **`authMiddleware`** – can refresh tokens and inject `Authorization` headers before the request.
+For non-`GET` requests, the full flat input is sent as the JSON body.
 
----
+For `GET` requests, flat input is validated but no body is sent.
 
-## Mock Mode
+---
 
-Enable or disable mock mode globally:
+## Creating the Client
 
 ```ts
-client.setMockMode(true, { min: 200, max: 1000 }); // simulate network delay
-// ...
-client.setMockMode(false);
+import { ApiClient } from "@tahanabavi/typefetch";
+
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+  },
+  contracts,
+);
+
+client.init();
+
+const api = client.modules;
 ```
 
-When mock mode is enabled and `endpoint.mockData` is defined, requests will return mock data instead of hitting the network. The response wrapper and response transform still apply.
+Always call `client.init()` before using `client.modules`.
 
 ---
 
-## Response Transformation
-
-You can apply a global transformation to all successful responses:
+## Client Configuration
 
 ```ts
-client.useResponseTransform((data) => {
-  return {
-    ...data,
-    transformedAt: new Date().toISOString(),
-  };
-});
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "static-token",
+    tokenProvider: async () => "dynamic-token",
+    useMockData: false,
+    mockDelay: {
+      min: 200,
+      max: 1000,
+    },
+  },
+  contracts,
+);
 ```
 
-This runs after:
+| Option          | Type                              | Description            |
+| --------------- | --------------------------------- | ---------------------- |
+| `baseUrl`       | `string`                          | Base API URL           |
+| `token`         | `string`                          | Static bearer token    |
+| `tokenProvider` | `() => string \| Promise<string>` | Dynamic token provider |
+| `useMockData`   | `boolean`                         | Enables mock mode      |
+| `mockDelay`     | `{ min: number; max: number }`    | Simulated mock latency |
 
-1. The HTTP call succeeds (`res.ok` is true)
-2. Optional response wrapper has been unwrapped
-3. The response has been validated with the endpoint’s Zod schema
+When both `token` and `tokenProvider` are provided, `tokenProvider` takes priority.
 
 ---
 
-## Response Wrapper Example
+## Authentication
 
-For APIs that wrap responses like this:
+Set `auth: true` on endpoints that require an authorization token.
 
-```json
-{
-  "success": true,
-  "data": { ... },
-  "timestamp": "...",
-  "requestId": "..."
-}
+```ts
+const contracts = {
+  user: {
+    getProfile: {
+      method: "GET",
+      path: "/profile",
+      auth: true,
+      request: z.object({}),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+} as const;
 ```
 
-You can define a single wrapper schema:
+Use a static token:
 
 ```ts
-import { z } from "zod";
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "my-token",
+  },
+  contracts,
+);
+```
 
-const wrapper = (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(),
-    }),
-  ]);
+Or use a dynamic token provider:
 
-client.setResponseWrapper(wrapper);
+```ts
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    tokenProvider: async () => {
+      return localStorage.getItem("token") ?? "";
+    },
+  },
+  contracts,
+);
 ```
 
-On `success: true`, `data` is passed to the endpoint’s `response` schema.  
-On `success: false`, a `RichError` is thrown with normalized information.
+You can also set the token provider later:
+
+```ts
+client.setTokenProvider(async () => "new-token");
+```
 
 ---
 
-## Error Handling
+## Middleware System
+
+TypeFetch supports middleware for logging, authentication, caching, retries, encryption, and custom request behavior.
 
 ```ts
-client.onError((err) => {
-  console.error("API Error:", err.message, err.status, err.code);
+client.use(async (ctx, next) => {
+  console.log("Request:", ctx.url);
+
+  const response = await next();
+
+  console.log("Response:", response.status);
+
+  return response;
 });
 ```
 
-Errors are normalized into `RichError` (or your custom type if you change the generic). Zod validation errors are also wrapped into a `VALIDATION_ERROR` with a readable message.
-
-You can still handle errors per-call with `try/catch`:
+Middlewares run in registration order before the request, then unwind in reverse order after the response.
 
 ```ts
-try {
-  const user = await api.user.getUser({ path: { id: "123" } });
-} catch (err) {
-  // err is RichError
-}
+client.use(firstMiddleware);
+client.use(secondMiddleware);
+```
+
+Execution flow:
+
+```txt
+firstMiddleware before
+secondMiddleware before
+fetch
+secondMiddleware after
+firstMiddleware after
 ```
 
 ---
 
-## File Uploads (`form-data`)
+## Built-in Middlewares
 
-For endpoints that need file upload, set `bodyType: "form-data"` and put file(s) inside `body`:
+Depending on how you export your middlewares, they can be registered directly or as factories.
+
+Direct middleware example:
 
 ```ts
-const uploadAvatarRequest = z.object({
-  path: z.object({}).optional(),
-  query: z.object({}).optional(),
-  body: z.object({
-    file: z.any(), // or z.instanceof(File) in browser
-  }),
-  headers: z.record(z.string()).optional(),
+client.use(loggingMiddleware, {
+  debug: true,
+  logRequest: true,
+  logResponse: true,
 });
+```
 
-const uploadAvatarResponse = z.object({
-  url: z.string(),
-});
+Factory middleware example:
 
-const contracts = {
-  user: {
-    uploadAvatar: {
-      method: "POST",
-      path: "/users/avatar",
-      auth: true,
-      bodyType: "form-data",
-      request: uploadAvatarRequest,
-      response: uploadAvatarResponse,
-    },
-  },
-} as const;
+```ts
+client.use(cacheMiddleware({ ttl: 60_000 }));
+client.use(retryMiddleware({ maxRetries: 3, delay: 300 }));
 ```
 
-Usage:
+---
+
+## Retry Engine
+
+TypeFetch includes a built-in retry engine on the client.
+
+```ts
+client.setRetryConfig({
+  maxRetries: 3,
+  backoff: "exponential",
+  retryCondition: (error, attempt) => {
+    return error.status !== undefined && error.status >= 500;
+  },
+});
+```
+
+Supported backoff strategies:
+
+| Strategy      | Behavior                       |
+| ------------- | ------------------------------ |
+| `fixed`       | Same delay each retry          |
+| `linear`      | Delay increases linearly       |
+| `exponential` | Delay doubles after each retry |
+
+Example:
+
+```ts
+client.setRetryConfig({
+  maxRetries: 3,
+  backoff: "fixed",
+});
+```
+
+---
+
+## Timeout and Abort Support
+
+Each request can receive per-call options.
+
+```ts
+await api.user.getUser(
+  {
+    path: { id: "123" },
+  },
+  {
+    timeout: 5000,
+  },
+);
+```
+
+You can also pass an external `AbortSignal`.
+
+```ts
+const controller = new AbortController();
+
+await api.user.getUser(
+  {
+    path: { id: "123" },
+  },
+  {
+    signal: controller.signal,
+  },
+);
+
+controller.abort();
+```
+
+---
+
+## Mock Mode
+
+Mock mode lets you return endpoint-level mock data instead of calling the network.
+
+```ts
+const contracts = {
+  user: {
+    getUser: {
+      method: "GET",
+      path: "/users/:id",
+      request: z.object({
+        path: z.object({
+          id: z.string(),
+        }),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+      mockData: {
+        id: "mock-1",
+        name: "Mock User",
+      },
+    },
+  },
+} as const;
+```
+
+Enable mock mode:
+
+```ts
+client.setMockMode(true, {
+  min: 200,
+  max: 1000,
+});
+```
+
+Dynamic mock data is also supported:
+
+```ts
+mockData: () => ({
+  id: crypto.randomUUID(),
+  name: "Dynamic Mock User",
+});
+```
+
+Mock responses are still validated against the endpoint response schema.
+
+---
+
+## Response Wrappers
+
+Many APIs return wrapped responses.
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "123",
+    "name": "Taha"
+  },
+  "timestamp": "2026-01-01T00:00:00.000Z"
+}
+```
+
+TypeFetch can validate and unwrap these responses.
+
+```ts
+import { z } from "zod";
+
+client.setResponseWrapper((successResponse) =>
+  z.union([
+    z.object({
+      success: z.literal(true),
+      data: successResponse,
+      timestamp: z.string().optional(),
+      requestId: z.string().optional(),
+    }),
+    z.object({
+      success: z.literal(false),
+      message: z.string(),
+      code: z.number().optional(),
+      timestamp: z.string().optional(),
+      requestId: z.string().optional(),
+    }),
+  ]),
+);
+```
+
+Successful responses return only `data`.
+
+Failed wrapped responses throw `RichError`.
+
+---
+
+## Error Handling
+
+TypeFetch normalizes errors into `RichError`.
+
+```ts
+client.onError((error) => {
+  console.error(error.message);
+  console.error(error.status);
+  console.error(error.code);
+});
+```
+
+`RichError` may include:
+
+```ts
+{
+  message: string;
+  status?: number;
+  code?: string;
+  title?: string;
+  detail?: string;
+  errors?: Record<string, string[]>;
+}
+```
+
+Handled error types include:
+
+* HTTP errors
+* Validation errors
+* Wrapped API errors
+* Missing token errors
+* Network errors
+* Timeout errors
+* Retry exhaustion
+
+Example:
+
+```ts
+try {
+  await api.user.getUser({
+    path: { id: "missing" },
+  });
+} catch (error) {
+  if (error instanceof RichError) {
+    console.error(error.status, error.message);
+  }
+}
+```
+
+---
+
+## File Uploads
+
+Set `bodyType: "form-data"` on an endpoint.
+
+```ts
+const contracts = {
+  user: {
+    uploadAvatar: {
+      method: "POST",
+      path: "/users/:id/avatar",
+      bodyType: "form-data",
+      request: z.object({
+        path: z.object({
+          id: z.string(),
+        }),
+        body: z.object({
+          file: z.instanceof(File),
+          alt: z.string().optional(),
+        }),
+      }),
+      response: z.object({
+        uploaded: z.boolean(),
+      }),
+    },
+  },
+} as const;
+```
+
+Usage:
 
 ```ts
-const file = input.files?.[0];
 await api.user.uploadAvatar({
-  body: { file },
+  path: { id: "123" },
+  body: {
+    file,
+    alt: "Profile avatar",
+  },
+});
+```
+
+When using `form-data`, TypeFetch does not force the `Content-Type: application/json` header.
+
+---
+
+## Encryption Middleware
+
+TypeFetch includes optional field-level encryption through `encryptionMiddleware`.
+
+It can:
+
+* Encrypt selected request body fields
+* Decrypt selected response fields
+* Process deeply nested objects
+* Process arrays
+* Use different encryption methods per field
+* Support custom encryption and decryption handlers
+
+Supported methods:
+
+```ts
+type EncryptionMethod = "AES" | "DES" | "RSA" | "Base64" | "Custom";
+```
+
+### Registering the Middleware
+
+```ts
+import { encryptionMiddleware } from "@tahanabavi/typefetch/middlewares";
+
+client.use(encryptionMiddleware, {
+  keyProvider: async () => ({
+    type: "symmetric",
+    key: "my-secret-key",
+  }),
+});
+```
+
+### Endpoint Encryption Config
+
+```ts
+const contracts = {
+  secure: {
+    createSecret: {
+      method: "POST",
+      path: "/secure",
+      request: z.object({
+        body: z.object({
+          secret: z.string(),
+          profile: z.object({
+            pin: z.string(),
+          }),
+        }),
+      }),
+      response: z.object({
+        id: z.string(),
+        token: z.string(),
+      }),
+      encryption: {
+        method: "AES",
+        request: {
+          secret: true,
+          profile: {
+            pin: "Base64",
+          },
+        },
+        response: {
+          token: true,
+        },
+      },
+    },
+  },
+} as const;
+```
+
+Usage:
+
+```ts
+await api.secure.createSecret({
+  body: {
+    secret: "private-value",
+    profile: {
+      pin: "1234",
+    },
+  },
 });
 ```
 
-The client will build a `FormData` object and let the browser set the `Content-Type` header.
+Before the request is sent:
+
+* `secret` is encrypted with AES
+* `profile.pin` is encoded with Base64
+
+After the response is received:
+
+* `token` is decrypted with AES
+
+### Separate Request and Response Methods
+
+```ts
+encryption: {
+  method: {
+    request: "RSA",
+    response: "AES",
+  },
+  request: {
+    password: true,
+  },
+  response: {
+    token: true,
+  },
+}
+```
+
+### Custom Encryption
+
+```ts
+client.use(encryptionMiddleware, {
+  keyProvider: async () => ({
+    type: "symmetric",
+    key: "custom-key",
+  }),
+  customHandlers: {
+    encrypt: async (value, key) => {
+      return `encrypted:${value}`;
+    },
+    decrypt: async (value, key) => {
+      return value.replace("encrypted:", "");
+    },
+  },
+});
+```
+
+Endpoint config:
+
+```ts
+encryption: {
+  method: "Custom",
+  request: {
+    secret: true,
+  },
+  response: {
+    token: true,
+  },
+}
+```
+
+### Fail-Closed Behavior
+
+By default, encryption should fail closed.
+
+That means if request encryption fails, the request is not sent as plaintext.
+
+```ts
+client.use(encryptionMiddleware, {
+  keyProvider: async () => ({
+    type: "symmetric",
+    key: "secret",
+  }),
+  failClosed: true,
+});
+```
+
+For debugging, you may disable fail-closed behavior:
+
+```ts
+client.use(encryptionMiddleware, {
+  keyProvider: async () => ({
+    type: "symmetric",
+    key: "secret",
+  }),
+  failClosed: false,
+});
+```
+
+Use `failClosed: false` carefully.
+
+---
+
+## Encryption Maps
+
+Encryption maps describe which fields should be transformed.
+
+```ts
+encryption: {
+  method: "AES",
+  request: {
+    password: true,
+    profile: {
+      ssn: true,
+    },
+    metadata: {
+      publicValue: false,
+    },
+  },
+}
+```
+
+Map values:
+
+| Value      | Behavior                             |
+| ---------- | ------------------------------------ |
+| `true`     | Encrypt/decrypt using default method |
+| `false`    | Skip field                           |
+| `"AES"`    | Use AES for this field               |
+| `"DES"`    | Use DES for this field               |
+| `"RSA"`    | Use RSA for this field               |
+| `"Base64"` | Use Base64 for this field            |
+| `"Custom"` | Use custom handler                   |
+| `{ ... }`  | Recursively process object           |
+| `[ ... ]`  | Process array items                  |
+
+Array example:
+
+```ts
+encryption: {
+  method: "AES",
+  request: {
+    users: [
+      {
+        password: true,
+      },
+    ],
+  },
+}
+```
+
+This applies the first array map to every item unless an index-specific map exists.
+
+---
+
+## Endpoint-Level Headers
+
+Headers can be defined on the endpoint.
+
+```ts
+const contracts = {
+  user: {
+    createUser: {
+      method: "POST",
+      path: "/users",
+      request: z.object({
+        body: z.object({
+          name: z.string(),
+        }),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+      headers: {
+        "X-App": "typefetch",
+      },
+    },
+  },
+} as const;
+```
+
+Headers can also be generated from input:
+
+```ts
+headers: (input) => ({
+  "X-Tenant": input.headers?.["X-Tenant"] ?? "default",
+});
+```
+
+Per-request headers can be passed through the structured request input:
+
+```ts
+await api.user.createUser({
+  headers: {
+    "X-Request-ID": "req-123",
+  },
+  body: {
+    name: "Taha",
+  },
+});
+```
+
+---
+
+## Custom Middleware
+
+A middleware receives:
+
+```ts
+type Middleware = (
+  ctx: MiddlewareContext,
+  next: () => Promise<Response>,
+  options?: unknown,
+) => Promise<Response>;
+```
+
+Example:
+
+```ts
+client.use(async (ctx, next) => {
+  const startedAt = Date.now();
+
+  const response = await next();
+
+  console.log(`${ctx.init.method} ${ctx.url} took ${Date.now() - startedAt}ms`);
+
+  return response;
+});
+```
+
+With options:
+
+```ts
+const timingMiddleware = async (ctx, next, options) => {
+  const response = await next();
+
+  if (options?.debug) {
+    console.log("Timing middleware enabled");
+  }
+
+  return response;
+};
+
+client.use(timingMiddleware, {
+  debug: true,
+});
+```
+
+---
+
+## Type Inference
+
+TypeFetch infers endpoint input and output types automatically from Zod schemas.
+
+```ts
+const user = await api.user.getUser({
+  path: {
+    id: "123",
+  },
+});
+```
+
+`user` is inferred as:
+
+```ts
+{
+  id: string;
+  name: string;
+}
+```
+
+Invalid input fails at compile time when possible and at runtime through Zod validation.
+
+---
+
+## Recommended Project Structure
+
+```txt
+src/
+  api/
+    contracts.ts
+    client.ts
+  middlewares/
+    logging.ts
+    retry.ts
+    cache.ts
+    auth.ts
+    encryption.ts
+```
+
+Example:
+
+```ts
+// api/client.ts
+import { ApiClient } from "@tahanabavi/typefetch";
+import { contracts } from "./contracts";
+
+export const client = new ApiClient(
+  {
+    baseUrl: import.meta.env.VITE_API_URL,
+    tokenProvider: async () => localStorage.getItem("token") ?? "",
+  },
+  contracts,
+);
+
+client.init();
+
+export const api = client.modules;
+```
+
+---
+
+## Testing
+
+TypeFetch is designed to be easy to test with mocked `fetch`.
+
+Example:
+
+```ts
+global.fetch = vi.fn();
+
+(fetch as any).mockResolvedValueOnce({
+  ok: true,
+  json: async () => ({
+    id: "1",
+    name: "Taha",
+  }),
+});
+
+const user = await api.user.getUser({
+  path: {
+    id: "1",
+  },
+});
+
+expect(user.name).toBe("Taha");
+```
+
+Recommended test coverage:
+
+* Request validation
+* Response validation
+* Path parameter handling
+* Query string generation
+* JSON body serialization
+* Header merging
+* Auth token injection
+* Token provider behavior
+* Middleware execution order
+* Retry behavior
+* Timeout and abort behavior
+* Mock mode
+* Response wrappers
+* Error normalization
+* Encryption middleware
 
 ---
 
 ## Notes
 
-- Always call `client.init()` before using `client.modules`.
-- Middlewares execute in **reverse registration order** (last registered runs first).
-- Endpoints with `auth: true` require a valid token from `token` or `tokenProvider`.
-- All responses are parsed and validated by Zod using each endpoint’s `response` schema.
-- Structured `{ path, query, body, headers }` shape is the canonical model; flat request schemas are still supported for backwards compatibility.
+* Always call `client.init()` before using `client.modules`.
+* All request inputs are validated with Zod.
+* All successful responses are validated with Zod.
+* Structured request schemas are recommended for new APIs.
+* Flat request schemas are still supported for backward compatibility.
+* `GET` requests do not send a body.
+* `form-data` endpoints should use `bodyType: "form-data"`.
+* Auth tokens are only required for endpoints with `auth: true`.
+* Mock data bypasses network calls but still validates responses.
 
 ---