@igniter-js/caller 0.1.56 → 0.1.58

package/README.md

@@ -1,619 +1,1336 @@
 # @igniter-js/caller
 
-[![NPM Version](https://img.shields.io/npm/v/@igniter-js/caller.svg)](https://www.npmjs.com/package/@igniter-js/caller)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<div align="center">
 
-Type-safe HTTP client for Igniter.js apps. Built on top of `fetch`, it gives you a fluent request builder, interceptors, retries, caching (memory or store), schema validation (Standard Schema V1), and global response events.
+[![npm version](https://img.shields.io/npm/v/@igniter-js/caller)](https://www.npmjs.com/package/@igniter-js/caller)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-orange)](https://bun.sh)
 
-## Features
+**End-to-end type-safe HTTP client**  
+Built on `fetch` with interceptors, retries, caching, schema validation, and full observability.
 
-- ✅ **Fluent API** - `api.get('/users').execute()` or builder pattern
-- ✅ **axios-style requests** - `api.request({ method, url, body, ... })`
-- ✅ **Auto content-type detection** - JSON, XML, CSV, Blob, Stream, etc.
-- ✅ **Interceptors** - modify requests and responses in one place
-- ✅ **Retries** - linear or exponential backoff + status-based retry
-- ✅ **Caching** - in-memory cache + optional persistent store adapter
-- ✅ **Schema Validation** - validate request/response using `StandardSchemaV1`
-- ✅ **StandardSchema Support** - Zod or any library that implements `StandardSchemaV1`
-- ✅ **Telemetry-ready** - optional integration with `@igniter-js/telemetry`
-- ✅ **Global Events** - observe responses for logging/telemetry/cache invalidation
-- ✅ **Auto query encoding** - body in GET requests converts to query params
+[Quick Start](#-quick-start) • [Documentation](https://igniterjs.com/docs/caller) • [Examples](#-real-world-examples) • [API Reference](#-api-reference)
 
-## Installation
+</div>
+
+---
+
+## ✨ Why @igniter-js/caller?
+
+Making API calls shouldn't require choosing between developer experience and runtime safety. Whether you're building a SaaS platform, a mobile backend, or a microservices architecture, you need:
+
+- ✅ **End-to-end type safety** — Catch API mismatches at build time, not in production
+- ✅ **Zero configuration** — Works anywhere `fetch` works (Node 18+, Bun, Deno, browsers)
+- ✅ **Production resilience** — Retries, timeouts, fallbacks, and caching built-in
+- ✅ **Full observability** — Telemetry, logging, and global events for every request
+- ✅ **Schema validation** — Runtime type checking with Zod, Valibot, or any StandardSchemaV1 library
+- ✅ **Developer experience** — Fluent API, autocomplete everywhere, zero boilerplate
+
+---
+
+## 🚀 Quick Start
+
+### Installation
 
 ```bash
-# npm
-npm install @igniter-js/caller @igniter-js/common
+# Using npm
+npm install @igniter-js/caller
 
-# pnpm
-pnpm add @igniter-js/caller @igniter-js/common
+# Using pnpm
+pnpm add @igniter-js/caller
 
-# yarn
-yarn add @igniter-js/caller @igniter-js/common
+# Using yarn
+yarn add @igniter-js/caller
 
-# bun
-bun add @igniter-js/caller @igniter-js/common
+# Using bun
+bun add @igniter-js/caller
 ```
 
-Optional dependencies:
+**Optional dependencies:**
 
 ```bash
-# Telemetry (optional)
+# For schema validation (any StandardSchemaV1 library)
+npm install zod
+
+# For observability (optional)
 npm install @igniter-js/telemetry
+```
 
-# Schema validation (optional - Zod or any StandardSchemaV1-compatible lib)
-npm install zod
+> **Note:** `@igniter-js/common` is automatically installed as a dependency. `zod` and `@igniter-js/telemetry` are optional peer dependencies.
+
+### Your First API Call (60 seconds)
+
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
+
+// 1️⃣ Create the client
+const api = IgniterCaller.create()
+  .withBaseUrl('https://api.github.com')
+  .withHeaders({ 
+    'Accept': 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28'
+  })
+  .build();
+
+// 2️⃣ Make a request
+const result = await api.get('/users/octocat').execute();
+
+// 3️⃣ Handle the response
+if (result.error) {
+  console.error('Request failed:', result.error.message);
+} else {
+  console.log('User:', result.data);
+}
 ```
 
-> `@igniter-js/common` is required. `@igniter-js/telemetry` and `zod` are optional peer dependencies.
+**✅ Success!** You just made a type-safe HTTP request with zero configuration.
 
-## Quick Start
+---
 
-```ts
-import { IgniterCaller } from '@igniter-js/caller'
+## 🎯 Core Concepts
 
-export const api = IgniterCaller.create()
+### Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                      Your Application                             │
+├──────────────────────────────────────────────────────────────────┤
+│  api.get('/users').params({ page: 1 }).execute()                │
+└────────────┬─────────────────────────────────────────────────────┘
+             │ Type-safe fluent API
+             ▼
+┌──────────────────────────────────────────────────────────────────┐
+│              IgniterCallerBuilder (Immutable)                     │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Configuration:                                             │ │
+│  │  - baseURL, headers, cookies                               │ │
+│  │  - requestInterceptors, responseInterceptors                │ │
+│  │  - store, schemas, telemetry, logger                       │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└────────────┬─────────────────────────────────────────────────────┘
+             │ .build()
+             ▼
+┌──────────────────────────────────────────────────────────────────┐
+│              IgniterCallerManager (Runtime)                       │
+│  - get/post/put/patch/delete/head() → RequestBuilder           │
+│  - request() → axios-style direct execution                    │
+│  - Static: batch(), on(), invalidate()                         │
+└────────────┬─────────────────────────────────────────────────────┘
+             │ Creates
+             ▼
+┌──────────────────────────────────────────────────────────────────┐
+│          IgniterCallerRequestBuilder (Per-Request)                │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Configuration:                                             │ │
+│  │  - url, method, body, params, headers                      │ │
+│  │  - timeout, cache, staleTime, retry                        │ │
+│  │  - fallback, responseType (schema or type marker)          │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└────────────┬─────────────────────────────────────────────────────┘
+             │ .execute()
+             ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                 Execution Pipeline                                │
+│  1. Cache Check (if staleTime set)                              │
+│  2. Request Interceptors                                         │
+│  3. Request Validation (if schema defined)                       │
+│  4. Fetch with Retry Logic                                       │
+│  5. Response Parsing (Content-Type auto-detect)                  │
+│  6. Response Validation (if schema defined)                      │
+│  7. Response Interceptors                                        │
+│  8. Cache Store (if successful)                                  │
+│  9. Fallback (if failed and fallback set)                        │
+│  10. Telemetry Emission                                         │
+│  11. Global Event Emission                                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Key Abstractions
+
+- **Builder** → Immutable configuration (`.withHeaders()`, `.withSchemas()`)
+- **Manager** → Operational HTTP client instance (`.get()`, `.post()`)
+- **RequestBuilder** → Per-request fluent API (`.body()`, `.retry()`, `.execute()`)
+- **Interceptors** → Request/Response transformation pipeline
+- **Schemas** → Type inference + runtime validation (StandardSchemaV1)
+- **Cache** → In-memory or store-based (Redis, etc.)
+- **Events** → Global observation for logging/telemetry
+
+---
+
+## 📖 Usage Examples
+
+### Basic Usage
+
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
+
+const api = IgniterCaller.create()
   .withBaseUrl('https://api.example.com')
   .withHeaders({ Authorization: `Bearer ${process.env.API_TOKEN}` })
-  .build()
+  .build();
+
+// GET request
+const users = await api.get('/users').execute();
+
+// POST request with body
+const newUser = await api
+  .post('/users')
+  .body({ name: 'John Doe', email: 'john@example.com' })
+  .execute();
+
+// PUT request with params
+const updated = await api
+  .put('/users/:id')
+  .params({ id: '123' })
+  .body({ name: 'Jane Doe' })
+  .execute();
+
+// DELETE request
+const deleted = await api.delete('/users/123').execute();
+
+// Check for errors
+if (users.error) {
+  console.error('Request failed:', users.error.message);
+  throw users.error;
+}
 
-// Simple GET request with URL directly
-const result = await api.get('/users').execute()
+console.log('Users:', users.data);
+```
 
-// With query params
-const result = await api.get('/users').params({ page: 1 }).execute()
+### Query Parameters
 
-// With caching
-const result = await api.get('/users').stale(10_000).execute()
+```typescript
+// Using .params()
+const result = await api
+  .get('/search')
+  .params({ q: 'typescript', page: 1, limit: 10 })
+  .execute();
 
-if (result.error) {
-  throw result.error
-}
+// GET with body (auto-converted to query params)
+const result = await api
+  .get('/search')
+  .body({ q: 'typescript', page: 1 })
+  .execute();
+// Becomes: GET /search?q=typescript&page=1
+```
+
+### Request Headers
+
+```typescript
+// Per-request headers (merged with defaults)
+const result = await api
+  .get('/users')
+  .headers({ 'X-Custom-Header': 'value' })
+  .execute();
 
-console.log(result.data)
+// Override default headers
+const result = await api
+  .get('/public/data')
+  .headers({ Authorization: '' }) // Remove auth for this request
+  .execute();
 ```
 
-## React Client (Provider + Hooks)
+### Timeout & Retry
 
-The React client is exposed via the dedicated subpath export:
+```typescript
+// Set timeout
+const result = await api
+  .get('/slow-endpoint')
+  .timeout(5000) // 5 seconds
+  .execute();
 
-```ts
-import { IgniterCallerProvider, useIgniterCaller } from '@igniter-js/caller/client'
+// Retry with exponential backoff
+const result = await api
+  .get('/unreliable-endpoint')
+  .retry(3, {
+    baseDelay: 500,
+    backoff: 'exponential',
+    retryOnStatus: [408, 429, 500, 502, 503, 504],
+  })
+  .execute();
 ```
 
-This keeps the root entrypoint server-safe and avoids bundling React in non-React environments.
+### Caching
 
-### Basic usage
+```typescript
+// In-memory cache
+const result = await api
+  .get('/users')
+  .stale(60_000) // Cache for 60 seconds
+  .execute();
 
-```tsx
-import { IgniterCallerProvider, useIgniterCaller } from '@igniter-js/caller/client'
+// Custom cache key
+const result = await api
+  .get('/users')
+  .cache({}, 'custom-cache-key')
+  .stale(60_000)
+  .execute();
 
-export function CallerProvider() {
-  return (
-    <IgniterCallerProvider callers={{ github: githubApi }}>
-      <UserProfile />
-    </IgniterCallerProvider>
-  )
-}
+// Store-based caching (Redis, etc.)
+const api = IgniterCaller.create()
+  .withStore(redisAdapter, {
+    ttl: 3600,
+    keyPrefix: 'api:',
+  })
+  .build();
 
-export const useCaller = useIgniterCaller<{
-  github: typeof githubApi
-}>()
-
-function UserProfile() {
-  const github = useCaller('github')
-  const { data, isLoading, error, refetch, invalidate } = github
-    .get('/me')
-    .useQuery({
-      params: {},
-      query: {},
-      headers: {},
-      cookies: {},
-      staleTime: 5000,
-      enabled: true,
-    })
+const result = await api
+  .get('/users')
+  .stale(300_000) // 5 minutes
+  .execute();
+```
 
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error</div>
-  return <pre>{JSON.stringify(data, null, 2)}</pre>
-}
+### Fallback Values
+
+```typescript
+// Provide fallback if request fails
+const result = await api
+  .get('/optional-data')
+  .fallback(() => ({ default: 'value' }))
+  .execute();
+
+// result.data will be fallback value if request fails
+// result.error will still contain the original error
+```
+
+### axios-Style Direct Requests
+
+```typescript
+// Using .request() method
+const result = await api.request({
+  method: 'POST',
+  url: '/users',
+  body: { name: 'John' },
+  headers: { 'X-Custom': 'value' },
+  timeout: 5000,
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+  staleTime: 30_000,
+});
+```
+
+### Interceptors
+
+```typescript
+const api = IgniterCaller.create()
+  .withBaseUrl('https://api.example.com')
+  
+  // Request interceptor (modify before sending)
+  .withRequestInterceptor(async (request) => {
+    return {
+      ...request,
+      headers: {
+        ...request.headers,
+        'X-Request-ID': crypto.randomUUID(),
+        'X-Timestamp': new Date().toISOString(),
+      },
+    };
+  })
+  
+  // Response interceptor (transform after receiving)
+  .withResponseInterceptor(async (response) => {
+    // Normalize empty responses
+    if (response.data === '') {
+      return { ...response, data: null as any };
+    }
+    
+    // Add custom metadata
+    return {
+      ...response,
+      metadata: {
+        cached: response.headers?.get('X-Cache') === 'HIT',
+        duration: parseInt(response.headers?.get('X-Duration') || '0'),
+      },
+    };
+  })
+  
+  .build();
 ```
 
-### Global config and invalidation
+### Schema Validation (Type-Safe)
+
+```typescript
+import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller';
+import { z } from 'zod';
+
+// Define schemas
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const ErrorSchema = z.object({
+  message: z.string(),
+  code: z.string(),
+});
+
+// Build schema registry
+const apiSchemas = IgniterCallerSchema.create()
+  .schema('User', UserSchema)
+  .schema('Error', ErrorSchema)
+  
+  .path('/users/:id', (path) =>
+    path.get({
+      responses: {
+        200: path.ref('User').schema,
+        404: path.ref('Error').schema,
+      },
+    })
+  )
+  
+  .path('/users', (path) =>
+    path.get({
+      responses: {
+        200: path.ref('User').array(),
+      },
+    })
+    .post({
+      request: z.object({
+        name: z.string(),
+        email: z.string().email(),
+      }),
+      responses: {
+        201: path.ref('User').schema,
+        400: path.ref('Error').schema,
+      },
+    })
+  )
+  
+  .build();
+
+// Create typed client
+const api = IgniterCaller.create()
+  .withBaseUrl('https://api.example.com')
+  .withSchemas(apiSchemas, { mode: 'strict' })
+  .build();
+
+// Full type inference!
+const result = await api.get('/users/:id')
+  .params({ id: '123' }) // ✅ params typed from path pattern
+  .execute();
 
-```tsx
-const github = useCaller('github')
+// ✅ result.data is User | undefined (typed from schema)
+console.log(result.data?.name);
 
-// Global defaults
-github.config.set('headers', { Authorization: 'Bearer ...' })
-github.config.set('cookies', { session: '...' })
-github.config.set('query', { locale: 'en' })
+// POST with typed body
+const created = await api.post('/users')
+  .body({ name: 'John', email: 'john@example.com' }) // ✅ body is typed
+  .execute();
 
-// Typed invalidation with optional optimistic data
-github.invalidate('/me', { id: 'user_123' })
+// ✅ created.data is User | undefined
 ```
 
-### Client safety notes
+### Global Events
 
-- If your Caller instance uses store adapters or telemetry managers that are server-only,
-  do not bundle that instance into browser code. Create a browser-safe instance instead.
-- The React client does not automatically wire store/telemetry to avoid bundler contamination.
+```typescript
+import { IgniterCallerManager } from '@igniter-js/caller';
 
-## Mocking (IgniterCallerMock)
+// Listen to all requests
+const unsubscribe = IgniterCallerManager.on(/.*/, (result, ctx) => {
+  console.log(`[${ctx.method}] ${ctx.url}`, {
+    status: result.status,
+    success: !result.error,
+    duration: Date.now() - ctx.timestamp,
+  });
+});
+
+// Listen to specific paths
+IgniterCallerManager.on(/^\/users/, (result, ctx) => {
+  if (result.error) {
+    console.error('User API failed:', result.error.message);
+  }
+});
+
+// Listen to exact URL
+IgniterCallerManager.on('/auth/login', (result, ctx) => {
+  if (!result.error) {
+    console.log('User logged in successfully');
+  }
+});
+
+// Cleanup listener
+unsubscribe();
+```
 
-Use `IgniterCallerMock` to create a type-safe mock registry based on your schemas.
+### Typed Mocking
 
-```ts
-import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller'
+```typescript
+import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller';
+import { z } from 'zod';
 
 const schemas = {
   '/users/:id': {
     GET: {
       responses: {
-        200: UserSchema,
+        200: z.object({ id: z.string(), name: z.string() }),
       },
     },
   },
-}
+  '/users': {
+    POST: {
+      request: z.object({ name: z.string() }),
+      responses: {
+        201: z.object({ id: z.string(), name: z.string() }),
+      },
+    },
+  },
+};
 
+// Create mock
 const mock = IgniterCallerMock.create()
   .withSchemas(schemas)
+  
+  // Static response
   .mock('/users/:id', {
     GET: {
-      response: { id: 'user_1' },
+      response: { id: 'user_123', name: 'John Doe' },
+      status: 200,
     },
   })
-  .build()
+  
+  // Dynamic response
+  .mock('/users', {
+    POST: (request) => ({
+      response: {
+        id: crypto.randomUUID(),
+        name: request.body.name,
+      },
+      status: 201,
+      delayMs: 150, // Simulate network delay
+    }),
+  })
+  
+  .build();
 
+// Create API with mock
 const api = IgniterCaller.create()
   .withSchemas(schemas)
   .withMock({ enabled: true, mock })
-  .build()
+  .build();
+
+// All requests use mock
+const user = await api.get('/users/:id').params({ id: '123' }).execute();
+console.log(user.data); // { id: 'user_123', name: 'John Doe' }
 ```
 
-Mock handlers receive the full request context:
+---
 
-```ts
-const mock = IgniterCallerMock.create()
-  .withSchemas(schemas)
-  .mock('/users/:id', {
-    GET: (request) => ({
-      response: { id: request.params.id },
-      status: 200,
-      delayMs: 150,
-    }),
-  })
-  .build()
-```
+## 🌍 Real-World Examples
 
-Notes:
+### Example 1: E-Commerce Product Catalog
 
-- If mock is enabled but there is no handler for a request, it falls back to the real request.
-- Mock responses can include `status`, `headers`, and optional `delayMs`.
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
+import { z } from 'zod';
 
-## HTTP Methods
+const ProductSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+  inStock: z.boolean(),
+  images: z.array(z.string().url()),
+});
 
-All HTTP methods accept an optional URL directly:
+const api = IgniterCaller.create()
+  .withBaseUrl('https://shop-api.example.com')
+  .withHeaders({ 'X-API-Key': process.env.SHOP_API_KEY! })
+  .build();
+
+// Fetch products with caching
+async function getProducts(category?: string) {
+  const result = await api
+    .get('/products')
+    .params(category ? { category } : {})
+    .responseType(z.object({
+      products: z.array(ProductSchema),
+      total: z.number(),
+    }))
+    .stale(300_000) // 5 minutes
+    .execute();
+
+  if (result.error) {
+    throw new Error(`Failed to fetch products: ${result.error.message}`);
+  }
 
-```ts
-// GET
-const users = await api.get('/users').execute()
+  return result.data;
+}
 
-// POST with body
-const created = await api.post('/users').body({ name: 'John' }).execute()
+// Search with debouncing
+let searchAbortController: AbortController | null = null;
 
-// PUT
-const updated = await api.put('/users/1').body({ name: 'Jane' }).execute()
+async function searchProducts(query: string) {
+  // Cancel previous search
+  searchAbortController?.abort();
+  searchAbortController = new AbortController();
 
-// PATCH
-const patched = await api.patch('/users/1').body({ name: 'Jane' }).execute()
+  const result = await api
+    .get('/products/search')
+    .params({ q: query })
+    .timeout(3000)
+    .execute();
 
-// DELETE
-const deleted = await api.delete('/users/1').execute()
+  return result.data?.products || [];
+}
 
-// HEAD
-const head = await api.head('/users').execute()
+// Usage
+const products = await getProducts('electronics');
+console.log(`Found ${products.total} products`);
 ```
 
-You can also use the traditional builder pattern:
+### Example 2: Payment Processing with Retries
+
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
 
-```ts
-const result = await api.get().url('/users').params({ page: 1 }).execute()
+const api = IgniterCaller.create()
+  .withBaseUrl('https://payments-api.example.com')
+  .withHeaders({
+    'X-API-Key': process.env.PAYMENT_API_KEY!,
+    'Content-Type': 'application/json',
+  })
+  .build();
+
+async function processPayment(payment: {
+  amount: number;
+  currency: string;
+  recipient: { accountNumber: string };
+}) {
+  const result = await api
+    .post('/payments')
+    .body(payment)
+    .timeout(10_000) // 10 seconds
+    .retry(3, {
+      baseDelay: 500,
+      backoff: 'exponential',
+      retryOnStatus: [503, 504], // Only retry on server errors
+    })
+    .fallback(() => ({
+      id: 'fallback',
+      status: 'pending',
+      message: 'Payment queued for retry',
+    }))
+    .execute();
+
+  if (result.error) {
+    console.error('Payment failed:', result.error.message);
+    // Log to monitoring service
+    throw result.error;
+  }
+
+  return result.data;
+}
 ```
 
-## axios-style Requests
+### Example 3: Real-Time Analytics Dashboard
 
-For dynamic requests or when you prefer an object-based API:
+```typescript
+import { IgniterCaller, IgniterCallerManager } from '@igniter-js/caller';
 
-```ts
-const result = await api.request({
-  method: 'POST',
-  url: '/users',
-  body: { name: 'John' },
-  headers: { 'X-Custom': 'value' },
-  timeout: 5000,
-})
+const api = IgniterCaller.create()
+  .withBaseUrl('https://analytics-api.example.com')
+  .build();
 
-// With caching
-const result = await api.request({
-  method: 'GET',
-  url: '/users',
-  staleTime: 30000,
-})
+// Global event listener for monitoring
+IgniterCallerManager.on(/^\/metrics/, (result, ctx) => {
+  if (!result.error) {
+    console.log(`Metrics fetched in ${Date.now() - ctx.timestamp}ms`);
+  }
+});
+
+// Polling with cache
+async function startMetricsPolling(intervalMs: number) {
+  const poll = async () => {
+    const result = await api
+      .get('/metrics')
+      .params({
+        start: new Date(Date.now() - 300_000).toISOString(),
+        end: new Date().toISOString(),
+      })
+      .stale(30_000) // 30 seconds
+      .execute();
+
+    if (!result.error) {
+      updateDashboard(result.data);
+    }
+  };
 
-// With retry
-const result = await api.request({
-  method: 'GET',
-  url: '/health',
-  retry: { maxAttempts: 3, backoff: 'exponential' },
-})
-```
+  poll(); // Initial fetch
+  return setInterval(poll, intervalMs);
+}
 
-## Auto Content-Type Detection
+const pollInterval = await startMetricsPolling(30_000);
+```
 
-The response is automatically parsed based on the `Content-Type` header:
+### Example 4: Multi-Tenant SaaS API Client
 
-| Content-Type | Parsed As |
-|-------------|-----------|
-| `application/json` | JSON object |
-| `text/xml`, `application/xml` | Text (parse with your XML library) |
-| `text/csv` | Text |
-| `text/html`, `text/plain` | Text |
-| `image/*`, `audio/*`, `video/*` | Blob |
-| `application/pdf`, `application/zip` | Blob |
-| `application/octet-stream` | Blob |
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
 
-```ts
-// JSON response - automatically parsed
-const { data } = await api.get('/users').execute()
+function createTenantAPI(tenantId: string, apiKey: string) {
+  return IgniterCaller.create()
+    .withBaseUrl('https://saas-api.example.com')
+    .withHeaders({
+      'X-Tenant-ID': tenantId,
+      'Authorization': `Bearer ${apiKey}`,
+    })
+    .build();
+}
 
-// Blob response - automatically detected
-const { data } = await api.get('/file.pdf').responseType<Blob>().execute()
+const tenant1API = createTenantAPI('tenant_1', process.env.TENANT_1_KEY!);
+const tenant2API = createTenantAPI('tenant_2', process.env.TENANT_2_KEY!);
 
-// Stream response
-const { data } = await api.get('/stream').responseType<ReadableStream>().execute()
+// Isolated requests per tenant
+const tenant1Users = await tenant1API.get('/users').execute();
+const tenant2Users = await tenant2API.get('/users').execute();
 ```
 
-## GET with Body → Query Params
+### Example 5: GraphQL-Style Batch Requests
 
-When you pass a body to a GET request, it's automatically converted to query parameters:
+```typescript
+import { IgniterCallerManager } from '@igniter-js/caller';
 
-```ts
-// This:
-await api.get('/search').body({ q: 'test', page: 1 }).execute()
+async function fetchDashboardData() {
+  const [users, posts, comments] = await IgniterCallerManager.batch([
+    api.get('/users').params({ limit: 10 }).execute(),
+    api.get('/posts').params({ limit: 20 }).execute(),
+    api.get('/comments').params({ limit: 50 }).execute(),
+  ]);
 
-// Becomes: GET /search?q=test&page=1
+  return {
+    users: users.data,
+    posts: posts.data,
+    comments: comments.data,
+  };
+}
 ```
 
-## Interceptors
-
-Interceptors are great for cross-cutting concerns like auth headers, request ids, logging, and response normalization.
+---
+
+## 📚 API Reference
+
+### IgniterCaller (Main Builder)
+
+The main entry point for creating an HTTP client.
+
+```typescript
+class IgniterCallerBuilder<TSchemas> {
+  static create(): IgniterCallerBuilder<{}>
+  
+  withBaseUrl(url: string): this
+  withHeaders(headers: Record<string, string>): this
+  withCookies(cookies: Record<string, string>): this
+  withLogger(logger: IgniterLogger): this
+  withRequestInterceptor(interceptor: RequestInterceptor): this
+  withResponseInterceptor(interceptor: ResponseInterceptor): this
+  withStore(store: StoreAdapter, options?: StoreOptions): this
+  withSchemas<T>(schemas: T, validation?: ValidationOptions): Builder<T>
+  withTelemetry(telemetry: TelemetryManager): this
+  withMock(config: MockConfig): this
+  
+  build(): IgniterCallerManager<TSchemas>
+}
+```
 
-```ts
+**Methods:**
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `create()` | None | `Builder<{}>` | Static factory for new builder |
+| `withBaseUrl()` | `url: string` | `this` | Set base URL prefix for all requests |
+| `withHeaders()` | `headers: Record<string, string>` | `this` | Merge default headers into every request |
+| `withCookies()` | `cookies: Record<string, string>` | `this` | Set default cookies (sent as `Cookie` header) |
+| `withLogger()` | `logger: IgniterLogger` | `this` | Attach logger for request lifecycle logging |
+| `withRequestInterceptor()` | `interceptor: Function` | `this` | Add request modifier (runs before fetch) |
+| `withResponseInterceptor()` | `interceptor: Function` | `this` | Add response transformer (runs after fetch) |
+| `withStore()` | `store: Adapter, options?` | `this` | Configure persistent cache (Redis, etc.) |
+| `withSchemas()` | `schemas: Map, validation?` | `Builder<T>` | Enable type inference + validation |
+| `withTelemetry()` | `telemetry: Manager` | `this` | Connect to telemetry system |
+| `withMock()` | `config: MockConfig` | `this` | Enable mock mode for testing |
+| `build()` | None | `Manager` | Build the operational client instance |
+
+**Example:**
+
+```typescript
 const api = IgniterCaller.create()
   .withBaseUrl('https://api.example.com')
-  .withRequestInterceptor(async (request) => {
-    return {
-      ...request,
-      headers: {
-        ...request.headers,
-        'x-request-id': crypto.randomUUID(),
-      },
-    }
-  })
-  .withResponseInterceptor(async (response) => {
-    // Example: normalize empty responses
-    if (response.data === '') {
-      return { ...response, data: null as any }
-    }
-    return response
-  })
-  .build()
+  .withHeaders({ Authorization: 'Bearer token' })
+  .withStore(redisAdapter)
+  .withSchemas(schemas)
+  .build();
 ```
 
-## Retries
+---
+
+### IgniterCallerManager (HTTP Client)
+
+The operational HTTP client instance for making requests.
+
+```typescript
+class IgniterCallerManager<TSchemas> {
+  // HTTP Methods
+  get<T>(url?: string): RequestBuilder<T>
+  post<T>(url?: string): RequestBuilder<T>
+  put<T>(url?: string): RequestBuilder<T>
+  patch<T>(url?: string): RequestBuilder<T>
+  delete<T>(url?: string): RequestBuilder<T>
+  head<T>(url?: string): RequestBuilder<T>
+  
+  // Direct execution (axios-style)
+  request<T>(options: DirectRequestOptions): Promise<ApiResponse<T>>
+  
+  // Static methods
+  static on(pattern: string | RegExp, callback: EventCallback): () => void
+  static off(pattern: string | RegExp, callback?: EventCallback): void
+  static invalidate(key: string): Promise<void>
+  static invalidatePattern(pattern: string): Promise<void>
+  static batch<T extends Promise<any>[]>(requests: T): Promise<AwaitedArray<T>>
+}
+```
 
-Configure retry behavior for transient errors:
+**Methods:**
+
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `get()` | `url?: string` | `RequestBuilder` | Create GET request |
+| `post()` | `url?: string` | `RequestBuilder` | Create POST request |
+| `put()` | `url?: string` | `RequestBuilder` | Create PUT request |
+| `patch()` | `url?: string` | `RequestBuilder` | Create PATCH request |
+| `delete()` | `url?: string` | `RequestBuilder` | Create DELETE request |
+| `head()` | `url?: string` | `RequestBuilder` | Create HEAD request |
+| `request()` | `options: DirectRequestOptions` | `Promise<ApiResponse>` | Execute request directly |
+| `on()` | `pattern, callback` | `unsubscribe: Function` | Register global event listener |
+| `off()` | `pattern, callback?` | `void` | Remove event listener(s) |
+| `invalidate()` | `key: string` | `Promise<void>` | Invalidate specific cache entry |
+| `invalidatePattern()` | `pattern: string` | `Promise<void>` | Invalidate cache by pattern |
+| `batch()` | `requests: Promise[]` | `Promise<Results[]>` | Execute requests in parallel |
+
+---
+
+### RequestBuilder (Fluent Request API)
+
+Per-request configuration builder.
+
+```typescript
+class IgniterCallerRequestBuilder<TResponse> {
+  url(url: string): this
+  body<T>(body: T): this
+  params<T>(params: T): this
+  headers(headers: Record<string, string>): this
+  timeout(ms: number): this
+  cache(cache: CacheInit, key?: string): this
+  stale(ms: number): this
+  retry(attempts: number, options?: RetryOptions): this
+  fallback<T>(fn: () => T): this
+  responseType<T>(schema?: StandardSchemaV1<T>): RequestBuilder<T>
+  
+  execute(): Promise<ApiResponse<TResponse>>
+}
+```
 
-```ts
-const result = await api
-  .get('/health')
-  .retry(3, {
-    baseDelay: 250,
-    backoff: 'exponential',
-    retryOnStatus: [408, 429, 500, 502, 503, 504],
-  })
-  .execute()
+**Methods:**
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `url()` | `url: string` | `this` | Set request URL |
+| `body()` | `body: any` | `this` | Set request body (JSON, FormData, Blob) |
+| `params()` | `params: Record<string, any>` | `this` | Set query parameters |
+| `headers()` | `headers: Record<string, string>` | `this` | Merge additional headers |
+| `timeout()` | `ms: number` | `this` | Set request timeout |
+| `cache()` | `cache: CacheInit, key?: string` | `this` | Set cache strategy |
+| `stale()` | `ms: number` | `this` | Set cache stale time |
+| `retry()` | `attempts: number, options?` | `this` | Configure retry behavior |
+| `fallback()` | `fn: () => T` | `this` | Provide fallback value on error |
+| `responseType()` | `schema?: StandardSchemaV1` | `Builder<T>` | Set expected response type |
+| `execute()` | None | `Promise<ApiResponse>` | Execute the request |
+
+---
+
+### Types
+
+#### ApiResponse
+
+```typescript
+interface IgniterCallerApiResponse<TData> {
+  data?: TData;
+  error?: IgniterCallerError;
+  status?: number;
+  headers?: Headers;
+}
 ```
 
-## Caching
+#### RetryOptions
 
-### In-memory caching
+```typescript
+interface IgniterCallerRetryOptions {
+  maxAttempts: number;
+  baseDelay?: number;
+  backoff?: 'linear' | 'exponential';
+  retryOnStatus?: number[];
+}
+```
 
-Use `.stale(ms)` to enable caching. The cache key defaults to the request URL, or you can set it via `.cache(cache, key)`.
+#### ValidationOptions
 
-```ts
-const users = await api.get('/users').stale(30_000).execute()
+```typescript
+interface IgniterCallerSchemaValidationOptions {
+  mode?: 'strict' | 'soft' | 'off';
+  onValidationError?: (error: ValidationError) => void;
+}
 ```
 
-### Store-based caching
+---
+
+## 🔧 Configuration
 
-You can plug any store that matches `IgniterCallerStoreAdapter` (Redis, etc.).
+### Store Adapter
 
-```ts
-import { IgniterCaller } from '@igniter-js/caller'
+Configure persistent caching with Redis or other stores:
+
+```typescript
+interface IgniterCallerStoreAdapter<TClient = any> {
+  client: TClient | null;
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  has(key: string): Promise<boolean>;
+}
 
-const store = {
-  client: null,
-  async get(key) { return null },
-  async set(key, value) { void key; void value },
-  async delete(key) { void key },
-  async has(key) { void key; return false },
+interface IgniterCallerStoreOptions {
+  ttl?: number;
+  keyPrefix?: string;
 }
+```
+
+**Example:**
+
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
+
+const redisAdapter: IgniterCallerStoreAdapter = {
+  client: redis,
+  async get(key) { return await redis.get(key); },
+  async set(key, value, ttl) { await redis.setex(key, ttl || 3600, value); },
+  async delete(key) { await redis.del(key); },
+  async has(key) { return (await redis.exists(key)) === 1; },
+};
 
 const api = IgniterCaller.create()
-  .withStore(store, {
+  .withStore(redisAdapter, {
     ttl: 3600,
-    keyPrefix: 'igniter:caller:',
+    keyPrefix: 'api:',
   })
-  .build()
+  .build();
 ```
 
-## Adapters
-
-The package ships a mock store adapter for tests and local development:
+### Schema Validation
 
-```ts
-import { MockCallerStoreAdapter } from '@igniter-js/caller/adapters'
-import { IgniterCaller } from '@igniter-js/caller'
+Enable runtime validation with any StandardSchemaV1 library:
 
-const store = MockCallerStoreAdapter.create()
+```typescript
+import { z } from 'zod';
 
 const api = IgniterCaller.create()
-  .withStore(store)
-  .build()
+  .withSchemas(schemas, {
+    mode: 'strict', // 'strict' | 'soft' | 'off'
+    onValidationError: (error) => {
+      console.error('Validation failed:', error);
+    },
+  })
+  .build();
 ```
 
-## Schema Validation (StandardSchemaV1)
+**Modes:**
+- `strict`: Throw on validation failure (default)
+- `soft`: Log error and continue
+- `off`: Skip validation
 
-If you already use schemas in your Igniter.js app, you can validate requests and responses automatically.
-Schemas must implement `StandardSchemaV1` (Zod is supported, and any compatible library works).
+---
 
-### Preferred: IgniterCallerSchema builder
+## 🧪 Testing
 
-```ts
-import { IgniterCaller, IgniterCallerSchema } from '@igniter-js/caller'
-import { z } from 'zod'
+### Unit Testing with Mock Adapter
 
-const UserSchema = z.object({ id: z.string(), name: z.string() })
-const ErrorSchema = z.object({ message: z.string() })
+```typescript
+import { describe, it, expect } from 'vitest';
+import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller';
+import { MockCallerStoreAdapter } from '@igniter-js/caller/adapters';
 
-const callerSchemas = IgniterCallerSchema.create()
-  .schema('User', UserSchema)
-  .schema('Error', ErrorSchema)
-  .path('/users/:id', (path) =>
-    path.get({
-      responses: {
-        200: path.ref('User').schema,
-        404: path.ref('Error').schema,
-      },
-      doc: 'Get user by id',
-      tags: ['users'],
-      operationId: 'users.get',
-    }),
-  )
-  .build()
+describe('API Client', () => {
+  const mock = IgniterCallerMock.create()
+    .mock('/users/:id', {
+      GET: (request) => ({
+        response: { id: request.params.id, name: 'Test User' },
+        status: 200,
+      }),
+    })
+    .build();
+
+  const api = IgniterCaller.create()
+    .withMock({ enabled: true, mock })
+    .build();
+
+  it('should fetch user', async () => {
+    const result = await api.get('/users/:id').params({ id: '123' }).execute();
+    
+    expect(result.error).toBeUndefined();
+    expect(result.data).toEqual({ id: '123', name: 'Test User' });
+  });
+
+  it('should handle errors', async () => {
+    const mock = IgniterCallerMock.create()
+      .mock('/error', {
+        GET: { response: null, status: 500 },
+      })
+      .build();
+
+    const api = IgniterCaller.create()
+      .withMock({ enabled: true, mock })
+      .build();
+
+    const result = await api.get('/error').execute();
+    
+    expect(result.error).toBeDefined();
+  });
+});
+```
 
-const api = IgniterCaller.create()
-  .withBaseUrl('https://api.example.com')
-  .withSchemas(callerSchemas, { mode: 'strict' })
-  .build()
+### Integration Testing
+
+```typescript
+import { IgniterCaller } from '@igniter-js/caller';
 
-type UserResponse = ReturnType<
-  typeof callerSchemas.$Infer.Response<'/users/:id', 'GET', 200>
->
+describe('Integration: Real API', () => {
+  const api = IgniterCaller.create()
+    .withBaseUrl(process.env.TEST_API_URL!)
+    .build();
+
+  it('should fetch users from real API', async () => {
+    const result = await api.get('/users').execute();
+    
+    expect(result.error).toBeUndefined();
+    expect(Array.isArray(result.data)).toBe(true);
+  });
+});
 ```
 
-`callerSchemas.get` exposes runtime helpers (`path`, `endpoint`, `request`, `response`, `schema`) and
-`callerSchemas.$Infer` provides type inference without extra imports. `path.ref()` helpers use Zod
-wrappers; when using a different StandardSchema implementation, use `ref().schema` directly.
+---
 
-### Manual object literal (still supported)
+## 🎨 Best Practices
 
-```ts
-import { IgniterCaller } from '@igniter-js/caller'
-import { z } from 'zod'
+### ✅ Do
 
-const schemas = {
-  '/users/:id': {
-    GET: {
-      responses: {
-        200: z.object({ id: z.string(), name: z.string() }),
-      },
-    },
-  },
-} as const
+```typescript
+// ✅ Use immutable builders
+const api = IgniterCaller.create()
+  .withBaseUrl('...')
+  .withHeaders({ ... })
+  .build();
 
+// ✅ Handle errors explicitly
+const result = await api.get('/users').execute();
+if (result.error) {
+  console.error(result.error);
+  throw result.error;
+}
+
+// ✅ Use schema validation for type safety
 const api = IgniterCaller.create()
-  .withBaseUrl('https://api.example.com')
   .withSchemas(schemas, { mode: 'strict' })
-  .build()
+  .build();
+
+// ✅ Cache expensive requests
+const result = await api
+  .get('/expensive')
+  .stale(300_000) // 5 minutes
+  .execute();
 
-const result = await api.get('/users/123').execute()
+// ✅ Use retry for transient failures
+const result = await api
+  .get('/unreliable')
+  .retry(3, { backoff: 'exponential' })
+  .execute();
+
+// ✅ Provide fallbacks for optional data
+const result = await api
+  .get('/optional')
+  .fallback(() => defaultValue)
+  .execute();
 ```
 
-**Note:** Schema validation only runs for validatable content types (JSON, XML, CSV). Binary responses (Blob, Stream) are not validated.
+### ❌ Don't
 
-## Generate schemas via CLI
+```typescript
+// ❌ Don't mutate builder state
+const builder = IgniterCaller.create();
+builder.state.baseURL = 'https://api.example.com'; // ❌ Won't work
 
-You can bootstrap Zod schemas and a ready-to-use caller from an OpenAPI 3 spec using the Igniter CLI:
+// ❌ Don't ignore errors
+const result = await api.get('/users').execute();
+console.log(result.data); // ❌ Might be undefined
 
-```bash
-npx @igniter-js/cli generate caller --name facebook --url https://api.example.com/openapi.json
+// ❌ Don't skip validation in production
+const api = IgniterCaller.create()
+  .withSchemas(schemas, { mode: 'off' }) // ❌ Risky
+  .build();
+
+// ❌ Don't cache mutations
+const result = await api
+  .post('/users')
+  .stale(60_000) // ❌ Don't cache POST/PUT/PATCH/DELETE
+  .execute();
+
+// ❌ Don't retry non-idempotent operations
+const result = await api
+  .post('/payments')
+  .retry(3) // ❌ Might duplicate payment
+  .execute();
 ```
 
-By default this outputs `src/callers/<hostname>/schema.ts` and `index.ts`:
+---
+
+## 🚨 Troubleshooting
 
-```ts
-import { facebookCaller } from './src/callers/api.example.com'
-import { facebookCallerSchemas } from './src/callers/api.example.com/schema'
+### Error: Request timeout
 
-const result = await facebookCaller.get('/products').execute()
-type ProductsResponse = ReturnType<
-  typeof facebookCallerSchemas.$Infer.Response<'/products', 'GET', 200>
->
+**Cause:** Request took longer than configured timeout
+
+**Solution:**
+
+```typescript
+// Increase timeout
+const result = await api
+  .get('/slow-endpoint')
+  .timeout(30_000) // 30 seconds
+  .execute();
 ```
 
-The generated `schema.ts` uses `IgniterCallerSchema` (path-first builder), registers reusable
-schemas, and includes derived type aliases for each endpoint.
+---
 
-## `responseType()` for Typing and Validation
+### Error: Validation failed
 
-Use `responseType()` to:
+**Cause:** Response doesn't match schema
 
-1. **Type the response** - for TypeScript inference
-2. **Validate the response** - if you pass a Zod/StandardSchema (only for JSON/XML/CSV)
+**Solution:**
 
-```ts
-import { z } from 'zod'
+```typescript
+// Check schema definition
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(), // ❌ API returns `username`
+});
 
-// With Zod schema - validates JSON response
-const result = await api
-  .get('/users')
-  .responseType(z.array(z.object({ id: z.string(), name: z.string() })))
-  .execute()
+// Fix schema
+const UserSchema = z.object({
+  id: z.string(),
+  username: z.string(), // ✅ Matches API
+});
 
-// With type marker - typing only, no validation
-const result = await api.get('/file').responseType<Blob>().execute()
+// Or use soft mode
+const api = IgniterCaller.create()
+  .withSchemas(schemas, { mode: 'soft' })
+  .build();
 ```
 
-## Global Events
+---
 
-You can observe responses globally using `IgniterCallerManager.on()`:
+### Error: Cache not invalidating
 
-```ts
-import { IgniterCallerManager } from '@igniter-js/caller'
+**Cause:** Cache key doesn't match
 
-const unsubscribe = IgniterCallerManager.on(/^\/users/, (result, ctx) => {
-  console.log(`[${ctx.method}] ${ctx.url}`, {
-    ok: !result.error,
-    status: result.status,
-  })
-})
+**Solution:**
 
-// later
-unsubscribe()
+```typescript
+// Ensure consistent cache keys
+const result1 = await api.get('/users').cache({}, 'users-list').execute();
+
+// Later, invalidate with same key
+await IgniterCallerManager.invalidate('users-list');
 ```
 
-## Observability (Telemetry)
+---
+
+### Performance: Slow requests
 
-```ts
-import { IgniterTelemetry } from '@igniter-js/telemetry'
-import { IgniterCaller } from '@igniter-js/caller'
-import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry'
+**Diagnosis:** No caching or retries
 
-const telemetry = IgniterTelemetry.create()
-  .withService('my-api')
-  .addEvents(IgniterCallerTelemetryEvents)
-  .build()
+**Solution:**
 
+```typescript
+// Enable caching for read-heavy endpoints
+const result = await api
+  .get('/heavy-computation')
+  .stale(600_000) // 10 minutes
+  .execute();
+
+// Use store-based cache for persistence
 const api = IgniterCaller.create()
-  .withBaseUrl('https://api.example.com')
-  .withTelemetry(telemetry)
-  .build()
+  .withStore(redisAdapter)
+  .build();
 ```
 
-## Error Handling
+---
 
-All predictable failures return an `IgniterCallerError` with stable error codes.
+### Type Inference: Not working
 
-```ts
-import { IgniterCallerError } from '@igniter-js/caller'
+**Cause:** Schema path doesn't match request URL
 
-const result = await api.get('/users').execute()
+**Solution:**
 
-if (result.error) {
-  if (IgniterCallerError.is(result.error)) {
-    console.error(result.error.code, result.error.operation)
+```typescript
+// ❌ Schema path doesn't match
+const schemas = {
+  '/users': { GET: { responses: { 200: UserSchema } } }
+};
+
+const result = await api.get('/users/list').execute(); // ❌ No match
+
+// ✅ Fix schema or URL
+const schemas = {
+  '/users/list': { GET: { responses: { 200: UserSchema } } }
+};
+
+const result = await api.get('/users/list').execute(); // ✅ Typed
+```
+
+---
+
+## 🔗 Framework Integration
+
+### Next.js (App Router)
+
+```typescript
+// lib/api.ts
+import { IgniterCaller } from '@igniter-js/caller';
+
+export const api = IgniterCaller.create()
+  .withBaseUrl(process.env.NEXT_PUBLIC_API_URL!)
+  .build();
+
+// app/users/page.tsx
+import { api } from '@/lib/api';
+
+export default async function UsersPage() {
+  const result = await api.get('/users').execute();
+  
+  if (result.error) {
+    throw new Error('Failed to fetch users');
   }
-  throw result.error
+  
+  return (
+    <div>
+      {result.data.map((user) => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### React with TanStack Query
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { api } from './api';
+
+function useUsers() {
+  return useQuery({
+    queryKey: ['users'],
+    queryFn: async () => {
+      const result = await api.get('/users').execute();
+      if (result.error) throw result.error;
+      return result.data;
+    },
+  });
 }
 
-// Response includes status and headers
-console.log(result.status) // 200
-console.log(result.headers?.get('x-request-id'))
+function Users() {
+  const { data, isLoading, error } = useUsers();
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return <ul>{data.map(...)}</ul>;
+}
 ```
 
-## API Reference
+### Express.js
 
-### `IgniterCaller.create()`
+```typescript
+import express from 'express';
+import { IgniterCaller } from '@igniter-js/caller';
 
-Creates a new caller builder.
+const app = express();
+const api = IgniterCaller.create()
+  .withBaseUrl('https://external-api.example.com')
+  .build();
+
+app.get('/proxy/users', async (req, res) => {
+  const result = await api.get('/users').execute();
+  
+  if (result.error) {
+    return res.status(result.status || 500).json({
+      error: result.error.message,
+    });
+  }
+  
+  res.json(result.data);
+});
+```
+
+---
+
+## 📊 Performance Tips
+
+1. **Use caching aggressively** for read-heavy endpoints
+2. **Enable store-based caching** (Redis) for distributed systems
+3. **Batch parallel requests** with `IgniterCallerManager.batch()`
+4. **Set appropriate timeouts** to fail fast
+5. **Use retry with exponential backoff** for transient failures
+6. **Minimize interceptor overhead** (avoid heavy computation)
+7. **Enable compression** via headers (`Accept-Encoding: gzip`)
 
-### Builder Methods
+---
 
-| Method | Description |
-|--------|-------------|
-| `.withBaseUrl(url)` | Sets the base URL for all requests |
-| `.withHeaders(headers)` | Sets default headers |
-| `.withCookies(cookies)` | Sets default cookies |
-| `.withLogger(logger)` | Attaches a logger |
-| `.withRequestInterceptor(fn)` | Adds a request interceptor |
-| `.withResponseInterceptor(fn)` | Adds a response interceptor |
-| `.withStore(store, options)` | Configures a persistent store |
-| `.withSchemas(schemas, options)` | Configures schema validation |
-| `.withTelemetry(telemetry)` | Attaches telemetry manager |
-| `.build()` | Builds the caller instance |
+## 🤝 Contributing
 
-### Request Methods
+Contributions are welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+
+```bash
+git clone https://github.com/felipebarcelospro/igniter-js.git
+cd igniter-js/packages/caller
+npm install
+npm run build
+npm test
+```
 
-| Method | Description |
-|--------|-------------|
-| `.get(url?)` | Creates a GET request |
-| `.post(url?)` | Creates a POST request |
-| `.put(url?)` | Creates a PUT request |
-| `.patch(url?)` | Creates a PATCH request |
-| `.delete(url?)` | Creates a DELETE request |
-| `.head(url?)` | Creates a HEAD request |
-| `.request(options)` | Executes request directly (axios-style) |
+---
 
-### Request Builder Methods
+## 📄 License
 
-| Method | Description |
-|--------|-------------|
-| `.url(url)` | Sets the URL |
-| `.body(body)` | Sets the request body |
-| `.params(params)` | Sets query parameters |
-| `.headers(headers)` | Merges additional headers |
-| `.timeout(ms)` | Sets request timeout |
-| `.cache(cache, key?)` | Sets cache strategy |
-| `.stale(ms)` | Sets cache stale time |
-| `.retry(attempts, options)` | Configures retry behavior |
-| `.fallback(fn)` | Provides fallback value |
-| `.responseType(schema?)` | Sets expected response type |
-| `.execute()` | Executes the request |
+MIT © [Felipe Barcelos](https://github.com/felipebarcelospro)
 
-### Static Methods
+---
 
-| Method | Description |
-|--------|-------------|
-| `IgniterCallerManager.on(pattern, callback)` | Registers event listener |
-| `IgniterCallerManager.off(pattern, callback?)` | Removes event listener |
-| `IgniterCallerManager.invalidate(key)` | Invalidates cache entry |
-| `IgniterCallerManager.invalidatePattern(pattern)` | Invalidates cache by pattern |
-| `IgniterCallerManager.batch(requests)` | Executes requests in parallel |
+## 🔗 Related Packages
 
-## Contributing
+- [@igniter-js/core](../core) — HTTP framework core
+- [@igniter-js/telemetry](../telemetry) — Observability system
+- [@igniter-js/store](../store) — State management
+- [Igniter.js Documentation](https://igniterjs.com)
 
-Contributions are welcome! Please see the main [CONTRIBUTING.md](https://github.com/felipebarcelospro/igniter-js/blob/main/CONTRIBUTING.md) for details.
+---
 
-## License
+## 💬 Community & Support
 
-MIT License - see [LICENSE](https://github.com/felipebarcelospro/igniter-js/blob/main/LICENSE) for details.
+- 📚 [Documentation](https://igniterjs.com/docs/caller)
+- 💬 [Discord Community](https://discord.gg/igniterjs)
+- 🐛 [Report Issues](https://github.com/felipebarcelospro/igniter-js/issues)
+- 🔒 [Security Policy](https://github.com/felipebarcelospro/igniter-js/security/policy)
 
-## Links
+---
 
-- **Documentation:** https://igniterjs.com/docs
-- **GitHub:** https://github.com/felipebarcelospro/igniter-js
-- **NPM:** https://www.npmjs.com/package/@igniter-js/caller
-- **Issues:** https://github.com/felipebarcelospro/igniter-js/issues
+**Built with ❤️ by the Igniter.js team**