{"_id":"@0xshariq/voxa-core","_rev":"2-b4cfc3c6c5f0f8b7f41c345c8df4d7d9","name":"@0xshariq/voxa-core","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@0xshariq/voxa-core","version":"1.0.0","keywords":["http","http-client","fetch","axios","request","cache","retry","typescript"],"author":{"name":"Sharique Chaudhary"},"license":"MIT","_id":"@0xshariq/voxa-core@1.0.0","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"homepage":"https://github.com/0xshariq/voxa#readme","bugs":{"url":"https://github.com/0xshariq/voxa/issues"},"dist":{"shasum":"dabd7d39f9e5405423db8ba7d36eab0d3d5bbdcc","tarball":"https://registry.npmjs.org/@0xshariq/voxa-core/-/voxa-core-1.0.0.tgz","fileCount":48,"integrity":"sha512-3o530BuoxAslMvBsgK9msryuJZXJ4KbUVZtSCvdvolpoNenSY3UUkfrbXE+XrwqoawSof7vIlYj9Kir4Q1lTmQ==","signatures":[{"sig":"MEUCIBJmn4BOuZNqMlmKgj4kgsfR80LpJ8ibokIPOlrSiJchAiEAhut6dxuBYv4nP8cj/ufjVFyWPjpnJjwooxkg6aj4aW4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76353},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./cache":{"types":"./dist/lib/features/cache/manager.d.ts","import":"./dist/lib/features/cache/manager.js"},"./http2":{"types":"./dist/lib/features/http2-push/manager.d.ts","import":"./dist/lib/features/http2-push/manager.js"},"./types":{"types":"./dist/lib/types/client-types.d.ts"},"./client":{"types":"./dist/lib/client/voxa.d.ts","import":"./dist/lib/client/voxa.js"},"./streaming":{"types":"./dist/lib/features/streaming-images/manager.d.ts","import":"./dist/lib/features/streaming-images/manager.js"}},"gitHead":"8d323434c7356fab1dcd86adfbe0e5dc2bf2133e","scripts":{"test":"tsx src/test.ts","build":"node scripts/build.js","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"pnpm run clean && pnpm run build"},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"repository":{"url":"git+https://github.com/0xshariq/voxa.git","type":"git","directory":"packages/voxa"},"_npmVersion":"11.6.4","description":"Core HTTP client library built on native Fetch API with essential features like caching, retry, and request deduplication.","directories":{},"sideEffects":false,"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","terser":"^5.44.1","typescript":"^5.9.3","@types/node":"^24.10.1"},"_npmOperationalInternal":{"tmp":"tmp/voxa-core_1.0.0_1764952779216_0.1329055737433178","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@0xshariq/voxa-core","version":"1.0.1","description":"Lightweight (21KB minified, 5.8KB gzipped) HTTP client library built on native Fetch API with essential features like caching, retry, and request deduplication.","keywords":["http","http-client","fetch","axios","request","cache","retry","typescript"],"homepage":"https://github.com/0xshariq/voxa#readme","bugs":{"url":"https://github.com/0xshariq/voxa/issues"},"repository":{"type":"git","url":"git+https://github.com/0xshariq/voxa.git","directory":"packages/voxa"},"license":"MIT","author":{"name":"Sharique Chaudhary"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./client":{"types":"./dist/lib/client/voxa.d.ts","import":"./dist/lib/client/voxa.js"},"./cache":{"types":"./dist/lib/features/cache/manager.d.ts","import":"./dist/lib/features/cache/manager.js"},"./streaming":{"types":"./dist/lib/features/streaming-images/manager.d.ts","import":"./dist/lib/features/streaming-images/manager.js"},"./http2":{"types":"./dist/lib/features/http2-push/manager.d.ts","import":"./dist/lib/features/http2-push/manager.js"},"./types":{"types":"./dist/lib/types/client-types.d.ts"}},"sideEffects":false,"scripts":{"build":"node scripts/build.js","clean":"rm -rf dist","test":"tsx src/test.ts","prepublishOnly":"pnpm run clean && pnpm run build","typecheck":"tsc --noEmit"},"devDependencies":{"@types/node":"^24.10.1","terser":"^5.44.1","tsx":"^4.20.6","typescript":"^5.9.3"},"gitHead":"19e935403ae737f906ba2b2a9a58704dfb208f84","_id":"@0xshariq/voxa-core@1.0.1","_nodeVersion":"25.2.1","_npmVersion":"11.6.4","dist":{"integrity":"sha512-W9aREdmZp08fAcw+UK6ZPBNQf9LwBauAanW0G7Lk1dAxtURbklBEi2knlBiqurxYJA3SWrgtpM22TFjs5ftwIA==","shasum":"792670dc01df7959ca6d36301204ebd2ec87602d","tarball":"https://registry.npmjs.org/@0xshariq/voxa-core/-/voxa-core-1.0.1.tgz","fileCount":48,"unpackedSize":76525,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDSpeK8K2VbRtYqeexbD7WPQ20ZhpY6tNdHXd4ssoxIZAIgKR3kVd3h198a9UE7TMq+bHAYy0BQzyt+TcNATR9XXwc="}]},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"directories":{},"maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/voxa-core_1.0.1_1764954596269_0.09188976448540886"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-05T16:39:39.135Z","modified":"2025-12-05T17:09:56.659Z","1.0.0":"2025-12-05T16:39:39.356Z","1.0.1":"2025-12-05T17:09:56.479Z"},"bugs":{"url":"https://github.com/0xshariq/voxa/issues"},"author":{"name":"Sharique Chaudhary"},"license":"MIT","homepage":"https://github.com/0xshariq/voxa#readme","keywords":["http","http-client","fetch","axios","request","cache","retry","typescript"],"repository":{"type":"git","url":"git+https://github.com/0xshariq/voxa.git","directory":"packages/voxa"},"description":"Lightweight (21KB minified, 5.8KB gzipped) HTTP client library built on native Fetch API with essential features like caching, retry, and request deduplication.","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"readme":"

Voxa HTTP Client

\n\n

\n Modern, feature-rich HTTP client for Node.js and browsers, built on the native Fetch API. Modular architecture with separate feature packages for optimal bundle size.\n

\n\n

\n \"npm\n \"License:\n

\n\n---\n\n## πŸ“Š Why Voxa?\n\nVoxa isn't just another HTTP clientβ€”it's a **complete request management system** with a **modular architecture**. Install only the features you need, keeping your bundle size minimal while having access to advanced capabilities that Axios, Fetch, and other popular clients simply don't have.\n\n### 🎯 Modular Design\n\nVoxa is split into multiple packages:\n\n- **@0xshariq/voxa-core** (~140KB) - Essential HTTP client with caching, retry, queue, rate limiting, and deduplication\n- **@0xshariq/voxa-streaming-images** - Image streaming with progress tracking\n- **@0xshariq/voxa-streaming-videos** - Video streaming with progress tracking\n- **@0xshariq/voxa-http2** - HTTP/2 Server Push support\n- **@0xshariq/voxa-graphql** - GraphQL query support\n- **@0xshariq/voxa-batch** - Request batching\n- **@0xshariq/voxa-offline** - Offline queue management\n- **@0xshariq/voxa-circuit-breaker** - Circuit breaker pattern\n- **@0xshariq/voxa-token** - OAuth/JWT token management\n- **@0xshariq/voxa-metrics** - Performance metrics tracking\n- **@0xshariq/voxa-cancel** - Advanced request cancellation\n\n---\n\n## Future Plans\n\n- Voxa CLI (Under Development)\n- Voxa API (Private API only for trusted users and organizations) (Done)\n- Voxa SDKs (Go,Rust,Python and Ruby) (Not Planned Yet)\n\n---\n\n## Feature Comparison\n\n| Feature | Voxa | Axios | Fetch | ky | Got | node-fetch |\n| --------------------------------- | :---------: | :------: | :------: | :------: | :---------: | :--------: |\n| **Bundle Size (Minified)** | 21 KB | 32.1 KB | 0KB | 14.6 KB | 180 KB | 18 KB |\n| **Bundle Size (Gzipped)** | 5.8 KB | 12.1 KB | 0KB | 4.8 KB | 52 KB | 6.5 KB |\n| **Dependencies** | 0 | 4 | 0 | 0 | 15 | 0 |\n| **Modular Architecture** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **TypeScript First** | βœ… | βœ… | βœ… | βœ… | βœ… | ⚠️ |\n| **Browser + Node.js** | βœ… | βœ… | βœ… | βœ… | ❌ | ❌ |\n| **Automatic Retry** | βœ… | ❌ | ❌ | βœ… | βœ… | ❌ |\n| **Response Caching** | βœ… Advanced | ❌ | ❌ | βœ… Basic | βœ… Advanced | ❌ |\n| **Request Deduplication** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Priority Queue** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Batch Requests** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Token Management** | βœ… Advanced | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Offline Queue** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **GraphQL Support** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Streaming Progress** | βœ… Advanced | βœ… Basic | βœ… Basic | βœ… | βœ… | βœ… |\n| **Request/Response Interceptors** | βœ… | βœ… | ❌ | βœ… | βœ… | ❌ |\n| **Circuit Breaker** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Rate Limiting** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **SSRF Protection** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Debug Mode** | βœ… | ⚠️ | ❌ | ⚠️ | βœ… | ❌ |\n| **Cancel Requests** | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… |\n| **Schema Validation** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **Error Classification** | βœ… | ⚠️ | ❌ | ⚠️ | βœ… | ❌ |\n| **Metadata Tracking** | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ |\n\n---\n\n## ✨ Core Features (in @0xshariq/voxa-core)\n\n- πŸ”„ **Automatic Retry** (exponential backoff)\n- πŸ’Ύ **Response Caching** (memory/file/custom)\n- 🎯 **Request Deduplication**\n- ⚑ **Priority Queue**\n- πŸ”’ **TypeScript First**\n- πŸ”Œ **Interceptors**\n- πŸ“Š **Request Tracking & Metadata**\n- ⏱️ **Timeout Control**\n- πŸš€ **Static Methods**\n- πŸ“‘ **Schema Validation**\n- πŸ” **SSRF Protection**\n- πŸ› **Debug Mode**\n- πŸ§ͺ **Automatic JSON Parsing**\n- βš–οΈ **Rate Limiting**\n\n## 🎁 Optional Feature Packages\n\nInstall only what you need:\n\n- πŸ“Ή **@0xshariq/voxa-streaming-images** - Image upload/download with progress\n- 🎬 **@0xshariq/voxa-streaming-videos** - Video upload/download with progress\n- ⚑ **@0xshariq/voxa-http2** - HTTP/2 Server Push\n- πŸ” **@0xshariq/voxa-graphql** - GraphQL queries\n- πŸ“¦ **@0xshariq/voxa-batch** - Request batching\n- πŸ“΄ **@0xshariq/voxa-offline** - Offline queue\n- πŸ”Œ **@0xshariq/voxa-circuit-breaker** - Circuit breaker pattern\n- 🎫 **@0xshariq/voxa-token** - OAuth/JWT token management\n- πŸ“Š **@0xshariq/voxa-metrics** - Performance metrics\n- πŸ›‘ **@0xshariq/voxa-cancel** - Advanced cancellation\n\n---\n\n## πŸ“¦ Installation\n\n### Core Package (Required)\n\n```bash\nnpm install @0xshariq/voxa-core\n# or\npnpm install @0xshariq/voxa-core\n# or\nyarn add @0xshariq/voxa-core\n```\n\n### Feature Packages (Optional)\n\n```bash\n# Install only the features you need\nnpm install @0xshariq/voxa-graphql @0xshariq/voxa-streaming-images\n```\n\n---\n\n## πŸš€ Quick Start\n\n### Basic Usage (Core Only)\n\n```typescript\nimport { Voxa } from \"@0xshariq/voxa-core\";\n\nconst client = new Voxa({\n baseURL: \"https://api.example.com\",\n timeout: 5000,\n cache: {\n enabled: true,\n ttl: 60000,\n },\n retry: {\n enabled: true,\n count: 3,\n },\n});\n\nconst response = await client.get(\"/users\");\nconsole.log(response.data);\n```\n\n### With Feature Packages\n\n```typescript\nimport { Voxa } from \"@0xshariq/voxa-core\";\nimport \"@0xshariq/voxa-graphql\"; // Types auto-merge\nimport \"@0xshariq/voxa-batch\";\nimport { StreamingImageManager } from \"@0xshariq/voxa-streaming-images\";\n\nconst client = new Voxa({\n baseURL: \"https://api.example.com\",\n graphql: {\n // TypeScript knows about this!\n enabled: true,\n endpoint: \"/graphql\",\n },\n batch: {\n enabled: true,\n wait: 100,\n },\n});\n\n// Use streaming\nconst imageManager = new StreamingImageManager();\nawait imageManager.upload(\"/upload\", imageFile, {}, (sent, total) => {\n console.log(`Progress: ${((sent / total) * 100).toFixed(2)}%`);\n});\n```\n\n---\n\n### Complete Instance Example\n\n```typescript\nimport { Voxa } from \"@0xshariq/voxa-core\";\n\nconst api = new Voxa({\n baseURL: \"https://api.example.com\",\n timeout: 5000,\n headers: {\n \"Content-Type\": \"application/json\", // string\n Authorization: \"Bearer \", // string\n },\n priority: \"high\", // 'critical' | 'high' | 'normal' | 'low'\n retry: {\n enabled: true, // boolean (default: true)\n count: 5, // number (max: 5)\n delay: 1000, // number (ms)\n exponentialBackoff: true, // boolean\n maxRetry: 10000, // number (ms)\n statusCodes: [429, 500, 502, 503, 504], // number[]\n },\n deduplication: {\n enabled: true, // boolean (default: true)\n ttl: 300000, // number (ms)\n },\n cache: {\n enabled: true, // boolean (default: true)\n ttl: 300000, // number (ms, default: 5 min)\n storage: \"memory\", // 'memory' | 'custom'\n adapter: undefined, // custom cache adapter (optional)\n },\n queue: {\n enabled: true, // boolean\n maxConcurrent: 5, // number\n },\n batch: {\n enabled: true, // boolean\n endpoint: \"/batch\", // string (optional)\n wait: 100, // number (ms, optional)\n maxBatchSize: 10, // number (optional)\n },\n token: {\n enabled: true, // boolean\n type: \"bearer\", // 'bearer' | 'oauth2' | 'jwt'\n tokenEndpoint: \"/auth/token\", // string\n clientId: \"client-id\", // string\n clientSecret: \"client-secret\", // string\n refreshEndpoint: \"/auth/refresh\", // string\n storage: \"memory\", // 'memory' | 'localStorage'\n getToken: async () => \"token\", // function\n setToken: (token: string) => {}, // function\n refreshToken: async () => \"new-token\", // function\n },\n // Token refresh failure hook\n onTokenRefreshFailure: (error, context) => {\n // Custom logic: log, alert, or trigger re-authentication\n console.error(\"Token refresh failed:\", error, context);\n // Optionally, redirect user or clear session\n },\n\n // Multi-tenant/multi-user support example\n getToken: async (userId) => {\n // Fetch token for a specific user/tenant\n return await fetchTokenForUser(userId);\n },\n setToken: (token, userId) => {\n // Store token for a specific user/tenant\n saveTokenForUser(token, userId);\n },\n refreshToken: async (userId) => {\n // Refresh token for a specific user/tenant\n return await refreshUserToken(userId);\n },\n\n // Usage:\n // await api.get('/resource', { userId: 'user-42' });\n offline: {\n enabled: true, // boolean (default: true)\n storage: \"localStorage\", // 'localStorage' | 'indexedDB'\n },\n circuitBreaker: {\n enabled: true, // boolean\n threshold: 5, // number\n timeout: 10000, // number (ms)\n onOpen: () => {}, // function (optional)\n },\n metrics: {\n enabled: true, // boolean\n },\n errors: {\n enabled: true, // boolean (default: true)\n },\n rate: {\n enabled: true, // boolean (default: true)\n maxRequests: 100, // number\n perMilliseconds: 60000, // number (ms)\n },\n schema: {\n enabled: true, // boolean\n requestSchema: undefined, // any (optional)\n responseSchema: undefined, // any (optional)\n library: \"zod\", // 'zod' | 'yup' (optional)\n },\n cancel: {\n enabled: true, // boolean (default: true)\n },\n graphql: {\n enabled: true, // boolean\n endpoint: \"https://graphqlzero.almansi.me/api\", // string\n logErrors: true, // boolean\n headers: undefined, // Record (optional)\n timeout: undefined, // number (optional)\n cache: undefined, // boolean (optional)\n },\n interceptors: {\n request: [\n (config) => {\n /* modify config */ return config;\n },\n ],\n response: [\n (response) => {\n /* log/modify response */ return response;\n },\n ],\n },\n metadata: {\n enabled: true, // boolean (default: true)\n log: true, // boolean (log metadata events)\n fields: [\n \"id\",\n \"method\",\n \"endpoint\",\n \"priority\",\n \"timestamp\",\n \"startTime\",\n \"endTime\",\n ], // string[] (fields to track)\n maxEntries: 100, // number (max entries to keep)\n customHandler: (meta) => {}, // function (custom handler)\n },\n});\n```\n\n---\n\n## πŸš€ Usage\n\n### 🧩 Feature Modularity & Extensibility\n\nVoxa's features (cache, retry, queue, batch, deduplication, interceptors, etc.) are fully modular and can be enabled, disabled, or extended at runtime.\n\n---\n\n### Enabling/Disabling Features at Runtime\n\nYou can toggle features on/off by updating the instance configuration:\n\n```typescript\n// Disable cache and queue at runtime\napi.updateConfig({\n cache: { enabled: false },\n queue: { enabled: false },\n});\n\n// Enable retry and set new retry count\napi.updateConfig({\n retry: { enabled: true, count: 10 },\n});\n```\n\n> **Note:** Not all features support dynamic reconfiguration in-flight. For critical changes, create a new instance with the desired config.\n\n---\n\n### Extending with Plugins (Custom Features)\n\nYou can add your own features or override built-in ones by attaching custom managers or hooks:\n\n```typescript\n// Example: Add a custom logging plugin\napi.usePlugin({\n onRequest(config) {\n console.log(\"Request:\", config.url);\n return config;\n },\n onResponse(response) {\n console.log(\"Response:\", response.status);\n return response;\n },\n});\n```\n\n---\n\n#### Plugin Interface\n\nA plugin is an object with any of these hooks:\n\n- `onRequest(config)`\n- `onResponse(response)`\n- `onError(error)`\n- `onBatch(batch)`\n- `onCacheEvent(event)`\n\nYou can register multiple plugins. They are called in the order added.\n\n---\n\n#### Disabling a Feature for a Single Request\n\n```typescript\n// Disable cache for a single request\nawait api.get('/users', { cache: { enabled: false } });\n\n// Set custom queue priority for a single request\nawait api.post('/orders', { ... }, { priority: 'critical' });\n```\n\nSee [Advanced Features](./docs/ADVANCED.md) for more on feature modularity and plugins.\n\n---\n\n### Using Voxa with an Instance\n\n### Injecting Custom requestId & Metadata\n\nRequestId will generate automatically and will use in features (like retry,batching,etc..):\n\n```typescript\n// Provide a custom requestId and metadata for tracing\nconst response = await api.get(\"/users/1\", {\n requestId: \"trace-abc-123\", // requestid will generate per request\n metadata: {\n traceId: \"trace-abc-123\",\n userId: \"user-42\",\n customField: \"my-value\",\n },\n});\nconsole.log(response.metadata); // includes your custom fields\n```\n\n> **Note:** The `requestId` generates automatically and use in all features.\n\nCreate a client instance to reuse configuration and advanced features:\n\n```typescript\nimport voxa from \"@0xshariq/voxa\";\n\nconst api = voxa.create({\n baseURL: \"https://api.example.com\",\n timeout: 5000,\n // ...other options\n});\n\n// Make requests (response is always parsed JSON)\nconst response = await api.get(\"/users/1\");\nconsole.log(response.data); // { id, name, ... }\n\n// You can also use other HTTP methods:\nawait api.post(\"/users\", { name: \"John\" });\nawait api.put(\"/users/1\", { name: \"Jane\" });\nawait api.delete(\"/users/1\");\n```\n\n---\n\n### Using Voxa Without an Instance (Static Methods)\n\nCall static methods directly for one-off requests:\n\n```typescript\nimport { Voxa } from \"@0xshariq/voxa\";\n\nconst response = await Voxa.get(\"https://api.example.com/users/1\");\nconsole.log(response.data);\n\n// Other static methods:\nawait Voxa.post(\"https://api.example.com/users\", { name: \"John\" });\nawait Voxa.put(\"https://api.example.com/users/1\", { name: \"Jane\" });\nawait Voxa.delete(\"https://api.example.com/users/1\");\n```\n\nUse an instance for advanced features (caching, queueing, interceptors, GraphQL, etc.), or static methods for simple requests.\n\n---\n\n### TypeScript Generics\n\n```typescript\ninterface User {\n id: number;\n name: string;\n email: string;\n}\n\n// Type-safe responses\nconst response = await api.get(\"/users/1\");\nconst user: User = await response.json();\n```\n\n---\n\n### Streaming Upload/Download\n\n```typescript\nimport { StreamingImageManager, StreamingVideoManager } from \"@0xshariq/voxa\";\n\n// Upload image with progress tracking\nconst streamingImages = new StreamingImageManager({});\n\nconst fileInput = document.querySelector('input[type=\"file\"]');\nconst file = fileInput.files[0];\n\nawait streamingImages.upload(\n \"https://api.example.com/images/upload\",\n file,\n { \"Content-Type\": \"image/jpeg\" },\n (sentBytes, totalBytes) => {\n const percentage = (sentBytes / totalBytes) * 100;\n console.log(`Upload progress: ${percentage.toFixed(2)}%`);\n }\n);\n\n// Download video with progress\nconst streamingVideos = new StreamingVideoManager({});\n\nconst response = await streamingVideos.download(\n \"https://api.example.com/videos/12345\",\n {},\n (receivedBytes, totalBytes) => {\n console.log(`Downloaded: ${receivedBytes}/${totalBytes} bytes`);\n }\n);\n\nconst blob = await response.blob();\nconst videoUrl = URL.createObjectURL(blob);\n```\n\nSee [Streaming Guide](./docs/STREAMING.md) for complete examples and advanced usage.\n\n---\n\n## πŸ“– Documentation\n\n### Core Documentation\n\n**Documentation:**\n\n- [Configuration Guide](./docs/CONFIGURATION.md) β€” All config options.\n- [Advanced Features](./docs/ADVANCED.md) β€” Caching, deduplication, queueing, interceptors, GraphQL, etc.\n- [Streaming Guide](./docs/STREAMING.md) β€” Image/video upload/download with progress tracking.\n- [Developer Experience](./docs/DEVELOPER_EXPERIENCE.md) β€” Debug mode, logging, public getters, type safety.\n- [Troubleshooting](./docs/TROUBLESHOOTING.md) β€” Common issues and solutions.\n- [Custom Cache](./docs/CUSTOM_CACHE.md) β€” Custom cache implementation.\n- [Batch Usage](./docs/BATCH_USAGE.md) β€” Batch request patterns.\n- [Examples](./docs/EXAMPLES.md) β€” Usage patterns and code samples.\n- [Migration](./docs/MIGRATION.md) - Migration from axios to voxa.\n\nSee docs/ for full details and up-to-date usage.\n\n---\n\n## 🎯 Key Features\n\n### Automatic Retry with Exponential Backoff\n\n```typescript\nconst api = voxa.create({\n baseURL: \"https://api.example.com\",\n retry: {\n count: 3, // Max 3 retries\n delay: 1000, // Initial delay: 1s\n exponentialBackoff: true, // 1s β†’ 2s β†’ 4s\n maxRetry: 10000, // Max delay: 10s\n },\n});\n```\n\n---\n\n### Response Structure\n\n```typescript\n{\n response: Response, // Http Response object\n data: {}, // Api Data will store here\n metadata: {\n id: \"string\", // requestId used everywhere\n method: \"'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'\",\n endpoint: \"string\",\n priority: \"'critical' | 'high' | 'normal' | 'low'\",\n timestamp: 2000,\n startTime: 2000,\n endTime: 2000\n },\n requestId: string, // Unique requestId, used in all features (queue, batch, cache, metrics, etc.)\n status: 200,\n statusText: \"Ok\"\n}\n```\n\nSee [Response Structure](./src/lib/types/client-types.ts) for detailed info.\n\n---\n\n### Response Caching\n\n```typescript\n// Memory cache (default)\nconst api = voxa.create({\n cache: {\n enabled: true,\n type: \"memory\",\n ttl: 300000, // 5 minutes\n },\n});\n\n// Redis cache\nconst api = voxa.create({\n cache: {\n enabled: true,\n type: \"redis\",\n ttl: 300000,\n },\n});\n```\n\n---\n\n### Request Prioritization\n\n```typescript\n// High priority request\nawait api.get(\"/critical-data\", { priority: \"critical\" });\n\n// Normal priority (default)\nawait api.get(\"/regular-data\");\n\n// Low priority\nawait api.get(\"/background-data\", { priority: \"low\" });\n```\n\n---\n\n### Request Interceptors\n\n```typescript\n// Add authentication header\napi.interceptors.request.use((config) => {\n config.headers = {\n ...config.headers,\n Authorization: `Bearer ${getToken()}`,\n };\n return config;\n});\n\n// Log responses\napi.interceptors.response.use((response) => {\n console.log(\"Response:\", response.status);\n return response;\n});\n```\n\n---\n\n## πŸ”§ Configuration\n\n### Environment Variables\n\nCreate a `.env` file in your project root:\n\n```env\n# Cache Configuration (Generic - works with any cache backend)\nCACHE_URL=redis://localhost:6379\nCACHE_PASSWORD=your-password\nCACHE_HOST=localhost\nCACHE_PORT=6379\nCACHE_DB=0\n\n# HTTP Configuration\nHTTP_TIMEOUT=5000\nHTTP_BASE_URL=https://api.example.com\n```\n\nSee [Configuration Guide](./docs/CONFIGURATION.md) for detailed options.\n\n---\n\n## πŸ“Š Monitoring & Statistics\n\n```typescript\n// Get cache statistics\nconst cacheStats = api.getCacheStats();\nconsole.log(cacheStats); // { storage: 'memory', size: 10, entries: [...] }\n\n// Get queue statistics\nconst queueStats = api.getQueueStats();\nconsole.log(queueStats); // { queueSize: 2, activeRequests: 3, maxConcurrent: 5 }\n\n// Get request metadata\nconst metadata = api.getRequestMetadata(\"request-id-123\");\nconsole.log(metadata); // { id, method, endpoint, duration, ... }\n```\n\n---\n\n## Request ID Format and Expiry\n\nEach request is assigned a unique `requestId` for tracking and feature management. The format is:\n\n```\n--\n```\n\n- `timestamp`: When the request was created\n- `expiry`: When the requestId expires (used for cache/batch conflict avoidance)\n- `random`: Random string for uniqueness\n\n- **Cache feature** uses a 5 minute expiry (default).\n- **Batch feature** uses a 15 minute expiry.\n\nThis prevents conflicts when the same request is sent at different times. Always use the generated requestId for all features (cache, batch, queue, etc.).\n\n---\n\n## Error Classification & Debugging\n\nVoxa now provides detailed error classification and debugging messages for every request. Use `api.classifyError(error)` to get both the error category and a helpful message for easier troubleshooting.\n\n---\n\n### Feature Manager Access\n\nAll feature managers (cache, queue, deduplication, metadata, circuit breaker, batch, rate limiter, metrics, schema, error classifier) are accessible via public methods or stats getters:\n\n- `api.getCacheStats()`\n- `api.getQueueStats()`\n- `api.getDeduplicationStats()`\n- `api.getMetadataStats()`\n- `api.circuitBreaker()`\n- `api.batch()`\n- `api.rate()`\n- `api.metrics()`\n- `api.schema()`\n- `api.classifyError(error)`\n\n---\n\n## πŸ§ͺ Testing\n\n```bash\n# Run test file directly\npnpm test\n\n# Or using development mode\npnpm dev\n```\n\n---\n\n## πŸ“ HTTP Methods\n\nVoxa supports all standard HTTP methods:\n\n```typescript\nawait api.get(\"/users\");\nawait api.post(\"/users\", { name: \"John\" });\nawait api.put(\"/users/1\", { name: \"Jane\" });\nawait api.patch(\"/users/1\", { email: \"new@example.com\" });\nawait api.delete(\"/users/1\");\nawait api.head(\"/users\");\nawait api.options(\"/users\");\n```\n\n---\n\n## 🀝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nSee the [Contributing Guide](./CONTRIBUTING.md)\n\n---\n\n## πŸ“„ License\n\nMIT Β© [Sharique Chaudhary](https://github.com/0xshariq)\n\n---\n\n## πŸ”— Links\n\n- [GitHub Repository](https://github.com/0xshariq/voxa)\n- [npm Package](https://www.npmjs.com/package/@0xshariq/voxa)\n- [Issue Tracker](https://github.com/0xshariq/voxa/issues)\n\n---\n\n**Note:** This project is built on the native Fetch API and requires Node.js 18+ or a modern browser environment.\n","readmeFilename":"README.md"}