docs: add SSE and circuit breaker sections, update comparison table and API reference — 1.1.0

Author: Firekid-is-him

README.md

@@ -9,7 +9,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/firekid-is-him/hurl?style=flat-square&logo=github&logoColor=white&color=FACC15)](https://github.com/firekid-is-him/hurl/stargazers)
 [![Website](https://img.shields.io/badge/website-hurl.firekidofficial.name.ng-black?style=flat-square&logo=googlechrome&logoColor=white)](https://hurl.firekidofficial.name.ng)
 
-**`@firekid/hurl`** is a modern, zero-dependency HTTP client for Node.js 18+, Cloudflare Workers, Vercel Edge Functions, Deno, and Bun — built on native fetch with retries, interceptors, auth helpers, in-memory caching, request deduplication, and full TypeScript support.
+**`@firekid/hurl`** is a modern, zero-dependency HTTP client for Node.js 18+, Cloudflare Workers, Vercel Edge Functions, Deno, and Bun — built on native fetch with retries, interceptors, auth helpers, in-memory caching, request deduplication, SSE streaming, circuit breaker, and full TypeScript support.
 
 ```bash
 npm install @firekid/hurl
@@ -34,6 +34,15 @@ const data = await hurl.get('/users', {
   cache: { ttl: 60000 },
 })
 
+// Stream an AI response over SSE
+const { close } = hurl.sse('https://api.openai.com/v1/chat/completions', {
+  method: 'POST',
+  auth: { type: 'bearer', token: process.env.OPENAI_KEY },
+  body: { model: 'gpt-4o', stream: true, messages: [{ role: 'user', content: 'Hello' }] },
+  onMessage: (e) => process.stdout.write(JSON.parse(e.data).choices[0].delta.content ?? ''),
+  onDone: () => console.log('\ndone'),
+})
+
 // Parallel requests
 const [users, posts] = await hurl.all([
   hurl.get('/users'),
@@ -48,7 +57,7 @@ const [users, posts] = await hurl.all([
 | Feature | **hurl** | axios | ky | got | node-fetch |
 |---|:---:|:---:|:---:|:---:|:---:|
 | Zero dependencies | ✅ | ❌ | ✅ | ❌ | ✅ |
-| Bundle size | **~9KB** | ~35KB | ~5KB | ~45KB | ~8KB |
+| Bundle size | **~12KB** | ~35KB | ~5KB | ~45KB | ~8KB |
 | Node.js 18+ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Cloudflare Workers | ✅ | ❌ | ✅ | ❌ | ❌ |
 | Vercel Edge | ✅ | ❌ | ✅ | ❌ | ❌ |
@@ -58,6 +67,8 @@ const [users, posts] = await hurl.all([
 | Auth helpers | ✅ | ⚠️ | ❌ | ❌ | ❌ |
 | In-memory cache | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Request deduplication | ✅ | ❌ | ❌ | ❌ | ❌ |
+| SSE (with POST + auth) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Circuit breaker | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Upload progress | ✅ | ✅ | ❌ | ❌ | ❌ |
 | Download progress | ✅ | ✅ | ❌ | ❌ | ❌ |
 | Proxy support | ✅ | ✅ | ❌ | ✅ | ❌ |
@@ -178,6 +189,127 @@ await hurl.get('/users', { signal: controller.signal })
 
 ---
 
+## SSE — Server-Sent Events
+
+Unlike the native `EventSource`, `hurl.sse()` works with POST requests, custom headers, and all auth types. This makes it directly compatible with AI APIs like OpenAI, Anthropic, and Gemini that stream over SSE.
+
+```ts
+const { close } = hurl.sse('https://api.openai.com/v1/chat/completions', {
+  method: 'POST',
+  auth: { type: 'bearer', token: process.env.OPENAI_KEY },
+  body: {
+    model: 'gpt-4o',
+    stream: true,
+    messages: [{ role: 'user', content: 'Hello' }],
+  },
+  onOpen: () => console.log('stream opened'),
+  onMessage: (event) => {
+    // event.data, event.event, event.id, event.retry
+    const chunk = JSON.parse(event.data)
+    process.stdout.write(chunk.choices[0].delta.content ?? '')
+  },
+  onDone: () => console.log('\nstream complete'),
+  onError: (err) => console.error(err),
+})
+
+// Stop the stream at any time
+close()
+```
+
+SSE with an instance (inherits `baseUrl` and `auth` from defaults):
+
+```ts
+const ai = hurl.create({
+  baseUrl: 'https://api.openai.com/v1',
+  auth: { type: 'bearer', token: process.env.OPENAI_KEY },
+})
+
+const { close } = ai.sse('/chat/completions', {
+  method: 'POST',
+  body: { model: 'gpt-4o', stream: true, messages: [...] },
+  onMessage: (e) => console.log(e.data),
+})
+```
+
+`hurl.sse()` handles the `data: [DONE]` sentinel automatically — it fires `onDone` and closes the stream. You also get a `signal` option if you want to tie the stream to an `AbortController` you control.
+
+---
+
+## Circuit Breaker
+
+The circuit breaker stops your app from hammering a failing service. After a set number of consecutive failures it opens the circuit and fast-fails all requests until a cooldown period passes, then lets one probe through to check if the service recovered.
+
+States: **CLOSED** (normal) → **OPEN** (fast-failing) → **HALF_OPEN** (probing) → **CLOSED**
+
+```ts
+await hurl.get('https://api.example.com/users', {
+  circuitBreaker: {
+    threshold: 5,       // open after 5 consecutive failures
+    cooldown: 30_000,   // wait 30s before probing
+  },
+})
+```
+
+With a fallback so the circuit open doesn't throw:
+
+```ts
+await hurl.get('/users', {
+  circuitBreaker: {
+    threshold: 3,
+    cooldown: 10_000,
+    fallback: () => [],   // returned as res.data when circuit is open
+  },
+})
+```
+
+Set it on an instance so every request to that API is protected:
+
+```ts
+const api = hurl.create({
+  baseUrl: 'https://api.example.com',
+  circuitBreaker: {
+    threshold: 5,
+    cooldown: 30_000,
+  },
+})
+```
+
+Use a custom key if you want multiple endpoints on the same host to have independent breakers:
+
+```ts
+await hurl.get('/payments', {
+  circuitBreaker: { threshold: 3, cooldown: 15_000, key: 'payments-service' },
+})
+
+await hurl.get('/orders', {
+  circuitBreaker: { threshold: 3, cooldown: 15_000, key: 'orders-service' },
+})
+```
+
+Check the state of any breaker at any time:
+
+```ts
+import { getCircuitStats } from '@firekid/hurl'
+
+const { state, failures } = getCircuitStats('https://api.example.com')
+// state: 'CLOSED' | 'OPEN' | 'HALF_OPEN'
+// failures: number
+```
+
+When the circuit is open and no fallback is provided, a `HurlError` with type `CIRCUIT_OPEN` is thrown:
+
+```ts
+try {
+  await hurl.get('/users', { circuitBreaker: { threshold: 3, cooldown: 10_000 } })
+} catch (err) {
+  if (err instanceof HurlError && err.type === 'CIRCUIT_OPEN') {
+    console.log('service unavailable, try again later')
+  }
+}
+```
+
+---
+
 ## Interceptors
 
 ```ts
@@ -226,12 +358,9 @@ await hurl.get('/users', { cache: { ttl: 60000, bypass: true } })
 ```ts
 import { clearCache, invalidateCache } from '@firekid/hurl'
 
-// Clear the entire cache
 clearCache()
-
-// Invalidate a single entry by URL or custom key
 invalidateCache('https://api.example.com/users')
-invalidateCache('all-users') // if you used a custom cache key
+invalidateCache('all-users')
 ```
 
 ---
@@ -253,7 +382,6 @@ const [a, b] = await Promise.all([
 ## Upload & Download Progress
 
 ```ts
-// Upload
 const form = new FormData()
 form.append('file', file)
 
@@ -263,7 +391,6 @@ await hurl.post('/upload', form, {
   }
 })
 
-// Download
 await hurl.get('/large-file', {
   onDownloadProgress: ({ loaded, total, percent }) => {
     console.log(`Downloading: ${percent}%`)
@@ -294,17 +421,13 @@ setGlobalDispatcher(new ProxyAgent('http://proxy.example.com:8080'))
 ```ts
 import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici'
 setGlobalDispatcher(new EnvHttpProxyAgent())
-// now set HTTP_PROXY=http://proxy.example.com:8080 in your env
 ```
 
 **Node.js 24+** — native fetch respects env vars when `NODE_USE_ENV_PROXY=1` is set:
 ```bash
 NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 node app.js
 ```
 
-The `proxy` option in `HurlRequestOptions` is reserved for a future release where this will be handled automatically.
-
----
 ---
 
 ## Parallel Requests
@@ -330,7 +453,7 @@ const api = hurl.create({
 
 await api.get('/users')
 
-// Extend with overrides
+// Extend with overrides — inherits parent interceptors
 const adminApi = api.extend({
   headers: { 'x-role': 'admin' }
 })
@@ -340,9 +463,9 @@ const adminApi = api.extend({
 
 ## Error Handling
 
-`hurl` throws a `HurlError` on HTTP errors (4xx/5xx), network failures, timeouts, aborts, and parse failures. It never resolves silently on bad status codes.
+`hurl` throws a `HurlError` on HTTP errors (4xx/5xx), network failures, timeouts, aborts, parse failures, and open circuit breakers. It never resolves silently on bad status codes.
 
-If you want to handle 4xx/5xx responses yourself without a try/catch, set `throwOnError: false` — the response will resolve normally and you can check `res.status` yourself.
+Set `throwOnError: false` to receive 4xx/5xx responses without a throw:
 
 ```ts
 const res = await hurl.get('/users', { throwOnError: false })
@@ -358,7 +481,7 @@ try {
   await hurl.get('/users')
 } catch (err) {
   if (err instanceof HurlError) {
-    err.type        // 'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT_ERROR' | 'ABORT_ERROR' | 'PARSE_ERROR'
+    err.type        // 'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT_ERROR' | 'ABORT_ERROR' | 'PARSE_ERROR' | 'CIRCUIT_OPEN'
     err.status      // 404
     err.statusText  // 'Not Found'
     err.data        // parsed error response body
@@ -428,12 +551,13 @@ type HurlRequestOptions = {
   auth?: AuthConfig
   proxy?: ProxyConfig
   cache?: CacheConfig
+  circuitBreaker?: CircuitBreakerConfig
   signal?: AbortSignal
   followRedirects?: boolean
-  maxRedirects?: number
   onUploadProgress?: ProgressCallback
   onDownloadProgress?: ProgressCallback
   stream?: boolean
+  throwOnError?: boolean
   debug?: boolean
   requestId?: string
   deduplicate?: boolean
@@ -460,7 +584,7 @@ Exports both ESM (`import`) and CommonJS (`require`).
 
 ## Why Not Axios?
 
-**axios** is 35KB, has no native edge runtime support, no built-in retry, no deduplication, and carries `XMLHttpRequest` baggage from a different era of the web.
+**axios** is 35KB, has no native edge runtime support, no built-in retry, no deduplication, no SSE, no circuit breaker, and carries `XMLHttpRequest` baggage from a different era of the web.
 
 **got** dropped CommonJS in v12 — if your project uses `require()`, you're stuck on an old version.
 
@@ -486,16 +610,19 @@ Exports both ESM (`import`) and CommonJS (`require`).
 | `hurl.head(url, options?)` | HEAD request → `Promise<HurlResponse<void>>` |
 | `hurl.options(url, options?)` | OPTIONS request |
 | `hurl.request(url, options?)` | Generic request, method from options |
+| `hurl.sse(url, options)` | Open an SSE stream → `{ close() }` |
 | `hurl.all(requests)` | Run requests in parallel |
 | `hurl.create(defaults?)` | New isolated instance |
-| `hurl.extend(defaults?)` | New instance inheriting current defaults |
+| `hurl.extend(defaults?)` | New instance inheriting current defaults and interceptors |
 | `hurl.defaults.set(defaults)` | Set global defaults |
 | `hurl.defaults.get()` | Get current defaults |
 | `hurl.defaults.reset()` | Reset defaults to instance creation values |
 | `hurl.interceptors.request.use(fn)` | Register request interceptor |
 | `hurl.interceptors.response.use(fn)` | Register response interceptor |
 | `hurl.interceptors.error.use(fn)` | Register error interceptor |
 | `clearCache()` | Clear in-memory response cache |
+| `invalidateCache(key)` | Invalidate a single cache entry by URL or custom key |
+| `getCircuitStats(key)` | Get state and failure count for a circuit breaker key |
 
 ---