@igniter-js/caller 0.1.0 → 0.1.2

package/AGENTS.md

@@ -1,7 +1,7 @@
 # @igniter-js/caller - AI Agent Instructions
 
 > **Package Version:** 0.1.0  
-> **Last Updated:** 2025-12-13  
+> **Last Updated:** 2025-12-14  
 > **Status:** Ready for Publication
 
 ---
@@ -14,13 +14,16 @@
 
 ### Core Features
 
-- Fluent request builder API (`IgniterCaller.create()` + `.get()/.post()/.request()`)
+- Fluent request builder API (`api.get('/users').execute()`)
+- axios-style requests (`api.request({ method, url, body })`)
+- Auto content-type detection (JSON, XML, Blob, Stream, etc.)
 - Request and response interceptors
 - Retry support (linear/exponential backoff + status-based retries)
 - Caching (in-memory + optional persistent store adapter)
 - Global response events (observe responses across the app)
 - Schema validation using `StandardSchemaV1` from `@igniter-js/core`
 - Optional Zod response validation via `responseType(zodSchema)`
+- Auto-conversion of GET body to query params
 
 ---
 
@@ -38,32 +41,121 @@ This package is intentionally small and split into predictable layers:
 
 1. **Fetch-first**
    - Uses the global `fetch` API.
-   - Works in Node.js (18+), Bun, and modern runtimes.
+   - Works in Node.js (18+), Bun, Deno, and modern browsers.
 
-2. **Typed error surface**
+2. **Auto content-type detection**
+   - Response parsing is automatic based on `Content-Type` header.
+   - JSON, XML, CSV → parsed and validated if schema provided.
+   - Blob, Stream, ArrayBuffer → returned as-is, no validation.
+
+3. **Typed error surface**
    - Predictable errors are `IgniterCallerError` with stable error codes.
 
-3. **Separation of concerns**
+4. **Separation of concerns**
    - `IgniterCallerRequestBuilder` focuses on request composition and execution.
    - `IgniterCallerCacheUtils` focuses on caching.
    - `IgniterCallerSchemaUtils` focuses on schema matching and validation.
 
-4. **Stable public API**
+5. **Stable public API**
    - Keep exports in `src/index.ts` stable and backwards-compatible.
 
 ---
 
+## API Design
+
+### HTTP Methods
+
+HTTP methods accept an optional URL directly and return a builder **without** the `.method()` function (since method is already set):
+
+```typescript
+// These are equivalent:
+api.get('/users').execute()
+api.get().url('/users').execute()
+
+// POST, PUT, PATCH, DELETE, HEAD work the same way:
+api.post('/users').body({ name: 'John' }).execute()
+api.delete('/users/1').execute()
+```
+
+### axios-style Requests
+
+The `.request()` method executes immediately with all options:
+
+```typescript
+const result = await api.request({
+  method: 'POST',
+  url: '/users',
+  body: { name: 'John' },
+  headers: { 'X-Custom': 'value' },
+  timeout: 5000,
+  staleTime: 30000,
+  retry: { maxAttempts: 3 },
+})
+```
+
+### Response Type Detection
+
+Response is parsed automatically based on `Content-Type` header:
+
+| Content-Type | Parsed As |
+|-------------|-----------|
+| `application/json` | JSON object |
+| `text/xml`, `application/xml` | Text |
+| `text/csv` | Text |
+| `text/html`, `text/plain` | Text |
+| `image/*`, `audio/*`, `video/*` | Blob |
+| `application/octet-stream` | Blob |
+
+### GET Body → Query Params
+
+Body in GET/HEAD requests is automatically converted to query params:
+
+```typescript
+api.get('/search').body({ q: 'test', page: 1 }).execute()
+// → GET /search?q=test&page=1
+```
+
+---
+
+## CLI Integration
+
+- The Igniter CLI provides `igniter generate caller` to ingest an OpenAPI 3 spec (URL or file) and emit `schema.ts` + `index.ts` under `src/callers/<hostname>` by default.
+- Generated schemas must follow `IgniterCallerSchemaMap` (`{ [path]: { METHOD: { request?: ..., responses: { <status>: zod } } } }`) to work with `.withSchemas()`.
+- The CLI prefixes schemas and the exported caller with `--name` (e.g., `facebookCaller`, `FacebookSchema`).
+- If runtime schema expectations change, update both the CLI generator and this documentation so consumers stay aligned.
+
+---
+
 ## File Structure
 
 ```
 packages/caller/
 ├── src/
-│   ├── index.ts
+│   ├── index.ts                           # Public exports
+│   ├── igniter-caller.spec.ts             # Tests
 │   ├── core/
+│   │   ├── igniter-caller.ts              # Main IgniterCaller class
+│   │   └── igniter-caller-events.ts       # Event emitter
 │   ├── builder/
+│   │   ├── igniter-caller.builder.ts      # Builder for configuration
+│   │   └── igniter-caller-request.builder.ts  # Request builder
 │   ├── errors/
+│   │   └── igniter-caller.error.ts        # Error class
 │   ├── types/
+│   │   ├── events.ts
+│   │   ├── http.ts
+│   │   ├── interceptors.ts
+│   │   ├── request.ts
+│   │   ├── response.ts
+│   │   ├── retry.ts
+│   │   ├── schemas.ts
+│   │   └── store.ts
 │   └── utils/
+│       ├── body.ts
+│       ├── cache.ts
+│       ├── schema.ts
+│       ├── testing.ts
+│       └── url.ts
 ├── package.json
 ├── tsconfig.json
 ├── tsup.config.ts
@@ -89,10 +181,20 @@ packages/caller/
 - Use `IgniterCallerError` for predictable failures.
 - Prefer stable `code` values over new ad-hoc error messages.
 
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `IGNITER_CALLER_HTTP_ERROR` | HTTP response with non-2xx status |
+| `IGNITER_CALLER_TIMEOUT` | Request timeout |
+| `IGNITER_CALLER_REQUEST_VALIDATION_FAILED` | Request body schema validation failed |
+| `IGNITER_CALLER_RESPONSE_VALIDATION_FAILED` | Response schema validation failed |
+| `IGNITER_CALLER_UNKNOWN_ERROR` | Unexpected error |
+
 ### Dependencies
 
-- `@igniter-js/core` is a **peer dependency** (for shared types like `IgniterError` and `StandardSchemaV1`).
-- `zod` is a **peer dependency** (used when consumers call `responseType(zodSchema)` and referenced in public types).
+- `@igniter-js/core` is a **peer dependency** (for shared types like `IgniterLogger` and `StandardSchemaV1`).
+- `zod` is a **peer dependency** (used when consumers call `responseType(zodSchema)`).
 
 ---
 
@@ -104,6 +206,9 @@ packages/caller/
   - Response schema validation returns `IgniterCallerError` on invalid payload.
   - Caching returns cached data without calling `fetch` again.
   - Event emission happens for responses.
+  - URL is passed correctly to HTTP methods.
+  - Body is converted to query params for GET requests.
+  - Content-type detection works correctly.
 
 Run tests:
 
@@ -113,6 +218,43 @@ npm test --filter @igniter-js/caller
 
 ---
 
+## Key Implementation Details
+
+### IgniterCallerMethodRequestBuilder
+
+When using specific HTTP methods (get, post, etc.), the builder returns a type that omits internal methods:
+
+```typescript
+export type IgniterCallerMethodRequestBuilder<TResponse = unknown> = Omit<
+  IgniterCallerRequestBuilder<TResponse>,
+  '_setMethod' | '_setUrl'
+>
+```
+
+This prevents calling `.method()` on a request that already has a method set.
+
+### Content-Type Detection
+
+The `detectContentType` function maps headers to response types:
+
+```typescript
+function detectContentType(contentType: string | null): IgniterCallerResponseContentType
+```
+
+Returns one of: `'json' | 'xml' | 'csv' | 'text' | 'html' | 'blob' | 'stream' | 'arraybuffer' | 'formdata'`
+
+### Schema Validation
+
+Schema validation only runs for validatable content types:
+
+```typescript
+const VALIDATABLE_CONTENT_TYPES = ['json', 'xml', 'csv']
+```
+
+Binary responses (Blob, Stream, ArrayBuffer) are never validated.
+
+---
+
 ## Publishing Checklist
 
 - [ ] `npm run build --filter @igniter-js/caller`

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to this package will be documented in this file.
 
+## 0.1.1
+
+### New Features
+
+- **URL in HTTP methods** - All HTTP methods (`get`, `post`, `put`, `patch`, `delete`, `head`) now accept URL directly:
+  ```ts
+  // Before
+  api.get().url('/users').execute()
+  
+  // After
+  api.get('/users').execute()
+  ```
+
+- **axios-style requests** - New `.request()` method for object-based API:
+  ```ts
+  const result = await api.request({
+    method: 'POST',
+    url: '/users',
+    body: { name: 'John' },
+    timeout: 5000,
+  })
+  ```
+
+- **Auto content-type detection** - Response is automatically parsed based on `Content-Type` header:
+  - `application/json` → JSON object
+  - `text/xml`, `text/csv`, `text/html`, `text/plain` → Text
+  - `image/*`, `audio/*`, `video/*`, `application/pdf` → Blob
+  - `application/octet-stream` → Blob
+
+- **GET body → query params** - Body in GET/HEAD requests is automatically converted to query parameters:
+  ```ts
+  api.get('/search').body({ q: 'test' }).execute()
+  // → GET /search?q=test
+  ```
+
+- **Response includes status and headers** - API response now includes HTTP status and headers:
+  ```ts
+  const result = await api.get('/users').execute()
+  console.log(result.status)  // 200
+  console.log(result.headers?.get('x-request-id'))
+  ```
+
+- **HEAD method** - Added `.head()` method for HEAD requests.
+
+### Improvements
+
+- `responseType()` now serves primarily for TypeScript typing. Schema validation only runs for validatable content types (JSON, XML, CSV).
+- `.method()` is no longer available when using specific HTTP methods (`get`, `post`, etc.) to prevent confusion.
+- Better type inference for schema maps with new utility types.
+
+### Deprecated
+
+- `getFile()` is deprecated. Use `.responseType<Blob>().execute()` or `.responseType<File>().execute()` instead. Content-type detection is automatic.
+
 ## 0.1.0
 
 - Initial release of `@igniter-js/caller`.

package/README.md

@@ -7,13 +7,16 @@ Type-safe HTTP client for Igniter.js apps. Built on top of `fetch`, it gives you
 
 ## Features
 
-- ✅ **Fluent API** - `IgniterCaller.create().withBaseUrl(...).build()`
+- ✅ **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`
 - ✅ **Zod Support** - optional per-request `responseType(zodSchema)` validation
 - ✅ **Global Events** - observe responses for logging/telemetry/cache invalidation
+- ✅ **Auto query encoding** - body in GET requests converts to query params
 
 ## Installation
 
@@ -43,12 +46,14 @@ export const api = IgniterCaller.create()
   .withHeaders({ Authorization: `Bearer ${process.env.API_TOKEN}` })
   .build()
 
-const result = await api
-  .get()
-  .url('/users')
-  .params({ page: 1 })
-  .stale(10_000) // cache for 10s
-  .execute<{ id: string; name: string }[]>()
+// Simple GET request with URL directly
+const result = await api.get('/users').execute()
+
+// With query params
+const result = await api.get('/users').params({ page: 1 }).execute()
+
+// With caching
+const result = await api.get('/users').stale(10_000).execute()
 
 if (result.error) {
   throw result.error
@@ -57,13 +62,105 @@ if (result.error) {
 console.log(result.data)
 ```
 
+## HTTP Methods
+
+All HTTP methods accept an optional URL directly:
+
+```ts
+// GET
+const users = await api.get('/users').execute()
+
+// POST with body
+const created = await api.post('/users').body({ name: 'John' }).execute()
+
+// PUT
+const updated = await api.put('/users/1').body({ name: 'Jane' }).execute()
+
+// PATCH
+const patched = await api.patch('/users/1').body({ name: 'Jane' }).execute()
+
+// DELETE
+const deleted = await api.delete('/users/1').execute()
+
+// HEAD
+const head = await api.head('/users').execute()
+```
+
+You can also use the traditional builder pattern:
+
+```ts
+const result = await api.get().url('/users').params({ page: 1 }).execute()
+```
+
+## axios-style Requests
+
+For dynamic requests or when you prefer an object-based API:
+
+```ts
+const result = await api.request({
+  method: 'POST',
+  url: '/users',
+  body: { name: 'John' },
+  headers: { 'X-Custom': 'value' },
+  timeout: 5000,
+})
+
+// With caching
+const result = await api.request({
+  method: 'GET',
+  url: '/users',
+  staleTime: 30000,
+})
+
+// With retry
+const result = await api.request({
+  method: 'GET',
+  url: '/health',
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+})
+```
+
+## Auto Content-Type Detection
+
+The response is automatically parsed based on the `Content-Type` header:
+
+| 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 |
+
+```ts
+// JSON response - automatically parsed
+const { data } = await api.get('/users').execute()
+
+// Blob response - automatically detected
+const { data } = await api.get('/file.pdf').responseType<Blob>().execute()
+
+// Stream response
+const { data } = await api.get('/stream').responseType<ReadableStream>().execute()
+```
+
+## GET with Body → Query Params
+
+When you pass a body to a GET request, it's automatically converted to query parameters:
+
+```ts
+// This:
+await api.get('/search').body({ q: 'test', page: 1 }).execute()
+
+// Becomes: GET /search?q=test&page=1
+```
+
 ## Interceptors
 
 Interceptors are great for cross-cutting concerns like auth headers, request ids, logging, and response normalization.
 
 ```ts
-import { IgniterCaller } from '@igniter-js/caller'
-
 const api = IgniterCaller.create()
   .withBaseUrl('https://api.example.com')
   .withRequestInterceptor(async (request) => {
@@ -80,7 +177,6 @@ const api = IgniterCaller.create()
     if (response.data === '') {
       return { ...response, data: null as any }
     }
-
     return response
   })
   .build()
@@ -92,8 +188,7 @@ Configure retry behavior for transient errors:
 
 ```ts
 const result = await api
-  .get()
-  .url('/health')
+  .get('/health')
   .retry(3, {
     baseDelay: 250,
     backoff: 'exponential',
@@ -109,7 +204,7 @@ const result = await api
 Use `.stale(ms)` to enable caching. The cache key defaults to the request URL, or you can set it via `.cache(cache, key)`.
 
 ```ts
-const users = await api.get().url('/users').stale(30_000).execute()
+const users = await api.get('/users').stale(30_000).execute()
 ```
 
 ### Store-based caching
@@ -121,26 +216,18 @@ import { IgniterCaller } from '@igniter-js/caller'
 
 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
-  },
+  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 },
 }
 
-const api = IgniterCaller.create().withStore(store, {
-  ttl: 3600,
-  keyPrefix: 'igniter:caller:',
-}).build()
+const api = IgniterCaller.create()
+  .withStore(store, {
+    ttl: 3600,
+    keyPrefix: 'igniter:caller:',
+  })
+  .build()
 ```
 
 ## Schema Validation (StandardSchemaV1)
@@ -166,21 +253,45 @@ const api = IgniterCaller.create()
   .withSchemas(schemas, { mode: 'strict' })
   .build()
 
-const result = await api.get().url('/users/123').execute()
+const result = await api.get('/users/123').execute()
+```
+
+**Note:** Schema validation only runs for validatable content types (JSON, XML, CSV). Binary responses (Blob, Stream) are not validated.
+
+## Generate schemas via CLI
+
+You can bootstrap Zod schemas and a ready-to-use caller from an OpenAPI 3 spec using the Igniter CLI:
+
+```bash
+npx @igniter-js/cli generate caller --name facebook --url https://api.example.com/openapi.json
+```
+
+By default this outputs `src/callers/<hostname>/schema.ts` and `index.ts`:
+
+```ts
+import { facebookCaller } from './src/callers/api.example.com'
+
+const result = await facebookCaller.get('/products').execute()
 ```
 
-## Zod `responseType()`
+## `responseType()` for Typing and Validation
 
-For one-off validation, you can attach a Zod schema to a request:
+Use `responseType()` to:
+
+1. **Type the response** - for TypeScript inference
+2. **Validate the response** - if you pass a Zod/StandardSchema (only for JSON/XML/CSV)
 
 ```ts
 import { z } from 'zod'
 
+// With Zod schema - validates JSON response
 const result = await api
-  .get()
-  .url('/users')
+  .get('/users')
   .responseType(z.array(z.object({ id: z.string(), name: z.string() })))
   .execute()
+
+// With type marker - typing only, no validation
+const result = await api.get('/file').responseType<Blob>().execute()
 ```
 
 ## Global Events
@@ -193,6 +304,7 @@ import { IgniterCaller } from '@igniter-js/caller'
 const unsubscribe = IgniterCaller.on(/^\/users/, (result, ctx) => {
   console.log(`[${ctx.method}] ${ctx.url}`, {
     ok: !result.error,
+    status: result.status,
   })
 })
 
@@ -207,7 +319,7 @@ All predictable failures return an `IgniterCallerError` with stable error codes.
 ```ts
 import { IgniterCallerError } from '@igniter-js/caller'
 
-const result = await api.get().url('/users').execute()
+const result = await api.get('/users').execute()
 
 if (result.error) {
   if (IgniterCallerError.is(result.error)) {
@@ -215,8 +327,70 @@ if (result.error) {
   }
   throw result.error
 }
+
+// Response includes status and headers
+console.log(result.status) // 200
+console.log(result.headers?.get('x-request-id'))
 ```
 
+## API Reference
+
+### `IgniterCaller.create()`
+
+Creates a new caller builder.
+
+### 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 |
+| `.build()` | Builds the caller instance |
+
+### Request Methods
+
+| 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
+
+| 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 |
+
+### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `IgniterCaller.on(pattern, callback)` | Registers event listener |
+| `IgniterCaller.off(pattern, callback?)` | Removes event listener |
+| `IgniterCaller.invalidate(key)` | Invalidates cache entry |
+| `IgniterCaller.invalidatePattern(pattern)` | Invalidates cache by pattern |
+| `IgniterCaller.batch(requests)` | Executes requests in parallel |
+
 ## Contributing
 
 Contributions are welcome! Please see the main [CONTRIBUTING.md](https://github.com/felipebarcelospro/igniter-js/blob/main/CONTRIBUTING.md) for details.