@tahanabavi/typefetch 1.4.1 → 1.5.3

package/README.md

@@ -1,137 +1,302 @@
 # TypeFetch
 
-TypeFetch is a production-grade, strongly-typed HTTP client built on
-**TypeScript** and **Zod**.
-
-Define your API once using Zod schemas, and TypeFetch generates a fully
-type-safe client with:
-
-- 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)
-- Built-in retry engine with backoff strategies
-- Timeout & AbortController support
-- 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
-- Concurrency-safe request handling
-- Production-grade validation and error normalization
+**TypeFetch** is a strongly typed HTTP client for TypeScript projects, built around **Zod** contracts.
+
+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.
+
+```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
 ```
 
----
+Or with Yarn:
 
-# What's New / Updated
+```bash
+yarn add @tahanabavi/typefetch zod
+```
 
-## 1. Advanced Retry Engine
+Or with pnpm:
 
-TypeFetch now includes:
+```bash
+pnpm add @tahanabavi/typefetch zod
+```
 
-- Configurable `maxRetries`
-- Custom `retryCondition`
-- Built-in backoff strategies:
-  - `fixed`
-  - `exponential`
-- Fully normalized retry errors
+---
 
-Example:
+## Quick Start
 
 ```ts
-client.setRetryConfig({
-  maxRetries: 3,
-  backoff: "exponential",
-  retryCondition: (err) => err.status === 500,
-});
-```
+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;
+
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    tokenProvider: async () => "your-token",
+  },
+  contracts,
+);
 
-## 2. Backoff Strategies
+client.init();
 
-Supported strategies:
+const api = client.modules;
 
-- **fixed** → constant delay
-- **exponential** → 100ms, 200ms, 400ms...
+const user = await api.user.getUser({
+  path: { id: "123" },
+});
 
-Backoff is applied automatically between retries.
+console.log(user.name);
+```
 
 ---
 
-## 3. Timeout & Abort Support
+## Defining API Contracts
 
-Per-request timeout:
+A TypeFetch contract is a grouped object of modules and endpoints.
 
 ```ts
-await api.user.getUser({ path: { id: "123" } }, { timeout: 5000 });
+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(),
+      }),
+    },
+
+    createUser: {
+      method: "POST",
+      path: "/users",
+      request: z.object({
+        body: z.object({
+          name: z.string(),
+          email: z.string().email(),
+        }),
+      }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    },
+  },
+} as const;
 ```
 
-Internally uses `AbortController` for safe cancellation.
+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",
+  },
+});
+```
 
 ---
 
-## 4. Structured Request Model (Canonical Format)
+## Structured Request Model
+
+The recommended request shape is:
 
 ```ts
 z.object({
-  path: z.object({...}).optional(),
-  query: z.object({...}).optional(),
-  body: z.object({...}).optional(),
+  path: z.object({}).optional(),
+  query: z.object({}).optional(),
+  body: z.any().optional(),
   headers: z.record(z.string()).optional(),
-})
+});
 ```
 
-TypeFetch automatically:
+Each section has a specific purpose.
 
-- Injects path params
-- Builds query string
-- Serializes JSON body
-- Merges headers in priority order:
-  1.  auth
-  2.  endpoint-level headers
-  3.  per-call headers
+| 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:
 
-## 5. Backward Compatibility
+```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(),
+      }),
+    },
+  },
+} as const;
+```
 
-Flat request schemas still work:
+Usage:
 
 ```ts
-z.object({
-  name: z.string(),
+await api.user.updateUser({
+  path: { id: "123" },
+  query: { notify: true },
+  headers: {
+    "X-Tenant": "main",
+  },
+  body: {
+    name: "Taha",
+  },
 });
 ```
 
-For non-GET requests, the entire object becomes the JSON body.
+TypeFetch sends:
+
+```ts
+PATCH /users/123?notify=true
+```
+
+With body:
+
+```json
+{
+  "name": "Taha"
+}
+```
 
 ---
 
-# Defining API Contracts
+## Request Schema Helper
 
-Example:
+You can use `makeRequestSchema` to make structured request schemas easier to write.
 
 ```ts
 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(),
+});
+```
 
+Use it inside an endpoint:
+
+```ts
 const contracts = {
   user: {
-    getUser: {
-      method: "GET",
+    updateUser: {
+      method: "PATCH",
       path: "/users/:id",
-      auth: true,
+      request: updateUserRequest,
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+} as const;
+```
+
+---
+
+## Backward Compatibility
+
+Flat request schemas are still supported.
+
+```ts
+const contracts = {
+  user: {
+    createUser: {
+      method: "POST",
+      path: "/users",
       request: z.object({
-        path: z.object({ id: z.string() }),
+        name: z.string(),
       }),
       response: z.object({
         id: z.string(),
@@ -142,9 +307,21 @@ const contracts = {
 } as const;
 ```
 
+Usage:
+
+```ts
+await api.user.createUser({
+  name: "Taha",
+});
+```
+
+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.
+
 ---
 
-# Using ApiClient
+## Creating the Client
 
 ```ts
 import { ApiClient } from "@tahanabavi/typefetch";
@@ -152,7 +329,6 @@ import { ApiClient } from "@tahanabavi/typefetch";
 const client = new ApiClient(
   {
     baseUrl: "https://api.example.com",
-    tokenProvider: async () => "dynamic-token",
   },
   contracts,
 );
@@ -160,144 +336,855 @@ const client = new ApiClient(
 client.init();
 
 const api = client.modules;
+```
+
+Always call `client.init()` before using `client.modules`.
 
-const user = await api.user.getUser({ path: { id: "123" } });
+---
+
+## Client Configuration
+
+```ts
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "static-token",
+    tokenProvider: async () => "dynamic-token",
+    useMockData: false,
+    mockDelay: {
+      min: 200,
+      max: 1000,
+    },
+  },
+  contracts,
+);
 ```
 
+| 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 |
+
+When both `token` and `tokenProvider` are provided, `tokenProvider` takes priority.
+
 ---
 
-# Middleware System
+## Authentication
 
-Middlewares execute in reverse registration order.
+Set `auth: true` on endpoints that require an authorization token.
 
-## Custom Middleware
+```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;
+```
+
+Use a static token:
+
+```ts
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "my-token",
+  },
+  contracts,
+);
+```
+
+Or use a dynamic token provider:
+
+```ts
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    tokenProvider: async () => {
+      return localStorage.getItem("token") ?? "";
+    },
+  },
+  contracts,
+);
+```
+
+You can also set the token provider later:
+
+```ts
+client.setTokenProvider(async () => "new-token");
+```
+
+---
+
+## Middleware System
+
+TypeFetch supports middleware for logging, authentication, caching, retries, encryption, and custom request behavior.
 
 ```ts
 client.use(async (ctx, next) => {
   console.log("Request:", ctx.url);
-  const res = await next();
-  console.log("Response:", res.status);
-  return res;
+
+  const response = await next();
+
+  console.log("Response:", response.status);
+
+  return response;
 });
 ```
 
+Middlewares run in registration order before the request, then unwind in reverse order after the response.
+
+```ts
+client.use(firstMiddleware);
+client.use(secondMiddleware);
+```
+
+Execution flow:
+
+```txt
+firstMiddleware before
+secondMiddleware before
+fetch
+secondMiddleware after
+firstMiddleware after
+```
+
+---
+
 ## Built-in Middlewares
 
-- `loggingMiddleware`
-- `retryMiddleware`
-- `cacheMiddleware`
-- `authMiddleware`
+Depending on how you export your middlewares, they can be registered directly or as factories.
+
+Direct middleware example:
+
+```ts
+client.use(loggingMiddleware, {
+  debug: true,
+  logRequest: true,
+  logResponse: true,
+});
+```
+
+Factory middleware example:
+
+```ts
+client.use(cacheMiddleware({ ttl: 60_000 }));
+client.use(retryMiddleware({ maxRetries: 3, delay: 300 }));
+```
+
+---
+
+## 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.use(loggingMiddleware);
-client.use(retryMiddleware, { maxRetries: 3 });
-client.use(cacheMiddleware, { ttl: 60000 });
-client.use(authMiddleware);
+client.setRetryConfig({
+  maxRetries: 3,
+  backoff: "fixed",
+});
 ```
 
 ---
 
-# Mock Mode
+## Timeout and Abort Support
+
+Each request can receive per-call options.
 
 ```ts
-client.setMockMode(true, { min: 200, max: 1000 });
+await api.user.getUser(
+  {
+    path: { id: "123" },
+  },
+  {
+    timeout: 5000,
+  },
+);
 ```
 
-- Returns `mockData` instead of calling network
-- Still applies response validation and wrapper
+You can also pass an external `AbortSignal`.
+
+```ts
+const controller = new AbortController();
+
+await api.user.getUser(
+  {
+    path: { id: "123" },
+  },
+  {
+    signal: controller.signal,
+  },
+);
+
+controller.abort();
+```
 
 ---
 
-# Response Wrapper
+## Mock Mode
 
-Supports envelope APIs:
+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": {...},
-  "timestamp": "..."
+  "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
-client.setResponseWrapper(wrapperSchema);
+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
+await api.user.uploadAvatar({
+  path: { id: "123" },
+  body: {
+    file,
+    alt: "Profile avatar",
+  },
+});
 ```
 
-On failure, throws normalized `RichError`.
+When using `form-data`, TypeFetch does not force the `Content-Type: application/json` header.
 
 ---
 
-# Error Handling
+## 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",
+    },
+  },
+});
+```
+
+Before the request is sent:
+
+* `secret` is encrypted with AES
+* `profile.pin` is encoded with Base64
+
+After the response is received:
 
-All errors are normalized into `RichError`:
+* `token` is decrypted with AES
 
-- HTTP errors
-- Network failures
-- Validation errors
-- Timeout errors
-- Retry exhaustion
+### Separate Request and Response Methods
+
+```ts
+encryption: {
+  method: {
+    request: "RSA",
+    response: "AES",
+  },
+  request: {
+    password: true,
+  },
+  response: {
+    token: true,
+  },
+}
+```
 
-Global handler:
+### Custom Encryption
 
 ```ts
-client.onError((err) => {
-  console.error(err.message, err.status);
+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.
+
 ---
 
-# File Uploads (FormData)
+## 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                  |
 
-Set `bodyType: "form-data"` in endpoint definition.
+Array example:
+
+```ts
+encryption: {
+  method: "AES",
+  request: {
+    users: [
+      {
+        password: true,
+      },
+    ],
+  },
+}
+```
 
-TypeFetch builds `FormData` automatically.
+This applies the first array map to every item unless an index-specific map exists.
 
 ---
 
-# Concurrency Safety
+## 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",
+});
+```
 
-TypeFetch safely handles parallel requests:
+Per-request headers can be passed through the structured request input:
 
-- No shared mutable state issues
-- Independent retry cycles
-- Independent AbortControllers
+```ts
+await api.user.createUser({
+  headers: {
+    "X-Request-ID": "req-123",
+  },
+  body: {
+    name: "Taha",
+  },
+});
+```
 
 ---
 
-# Production-Grade Test Coverage
+## Custom Middleware
+
+A middleware receives:
 
-The project now includes:
+```ts
+type Middleware = (
+  ctx: MiddlewareContext,
+  next: () => Promise<Response>,
+  options?: unknown,
+) => Promise<Response>;
+```
+
+Example:
 
-- Validation tests
-- Middleware tests
-- Retry tests
-- Backoff timing tests
-- Timeout & abort tests
-- Concurrency tests
-- Error propagation tests
-- Mock mode tests
-- TokenProvider tests
-- Edge case handling tests
+```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");
+```
 
-Suitable for publishing as a production SDK.
+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
+## Notes
 
-- Always call `client.init()` before using modules.
-- All responses are validated via Zod.
-- Structured request shape is recommended.
-- Retry + Timeout can be combined safely.
+* 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.
 
 ---
 
-# License
+## License
 
 MIT