thebird 1.2.74 → 1.2.75

package/CLAUDE.md

@@ -133,14 +133,41 @@ Run examples against real Gemini API to validate message translation.
 - Cannot bundle index.js directly for browser — it imports Node-only modules (oauth.js, config.js, cloud-generate.js) at top level. Create a separate browser entry that imports only lib/client.js, lib/errors.js, lib/convert.js. Use ESM wrapper (not CJS module.exports) to preserve named exports in bundle.
 - Tool parameter types must be lowercase for Gemini API — `object`, `string`, `number` not `OBJECT`, `STRING`, `NUMBER`. Uppercase types fail schema validation.
 - agentGenerate passes raw Anthropic-format messages to streamGemini internally, which calls convertMessages. Do NOT pre-convert in app.js — double-conversion breaks tool schemas.
+- Anthropic format IS the canonical message format — do NOT add an intermediate transformation layer. Direct translation to provider-native formats is cleaner than another abstraction level.
+
+## Error Architecture
+
+**Error hierarchy** (lib/errors.js):
+- `BridgeError(message, { status, code, retryable, provider, headers })` — base class, `GeminiError` alias for backwards compat
+- `AuthError` (401/403), `RateLimitError` (429, retryable), `TimeoutError` (408, retryable), `ContextWindowError` (413), `ContentPolicyError` (451), `ProviderError` (5xx, retryable)
+- `classifyError(status, message, provider)` — factory returns typed error from status code
+- `redactKeys(str)` — masks API keys (AIza, sk-, key- patterns) to `...XXXX`
+- `parseRetryAfterHeader(err)` — standard HTTP Retry-After (seconds + date formats)
+
+**Stream guards** (lib/stream-guard.js):
+- `guardStream(iterable, { chunkTimeoutMs, maxRepeats })` — wraps async iterables
+- Chunk timeout default 30s, repeat threshold default 100
+
+**Circuit breaker** (lib/circuit-breaker.js):
+- `createCircuitBreaker({ maxFailures, cooldownMs })` — per-provider failure tracking
+- Auto-recovery after cooldown, reset on success
+
+**Capabilities** (lib/capabilities.js):
+- `getCapabilities(provider)` — merges provider.capabilities with defaults
+- `stripUnsupported(params, caps)` — removes unsupported features, returns warnings
+- Defaults: streaming, toolUse, vision, systemMessage = true; jsonMode = false
 
 ## Files
 
 - `lib/convert.js`: Message/tool translation logic
 - `lib/client.js`: Provider client factory
-- `lib/errors.js`: Error handling and retry logic
+- `lib/errors.js`: Typed error hierarchy (BridgeError, AuthError, RateLimitError, etc.), classifyError, redactKeys, withRetry
+- `lib/stream-guard.js`: guardStream — chunk timeout and repeated-chunk detection for async iterables
+- `lib/circuit-breaker.js`: Per-provider failure tracking with auto-recovery
+- `lib/capabilities.js`: Provider capability metadata and unsupported feature stripping
+- `lib/router-stream.js`: Router streaming/generation with circuit breaker and capability integration
 - `lib/providers/`: Provider-specific streaming implementations
-- `index.js`: Main entry point, streaming and generation wrappers
+- `index.js`: Main entry point, Gemini streaming/generation, re-exports
 - `index.d.ts`: TypeScript type definitions
 - `examples/`: Working examples using Anthropic SDK format
 - `wasi/cli.ts`: Deno streaming CLI — `deno run --allow-net --allow-env wasi/cli.ts [--model M] [--system S] <prompt>`

package/README.md

@@ -152,6 +152,68 @@ Pass options as a nested array: `["maxtoken", { "max_tokens": 16384 }]`.
 }
 ```
 
+## Error Handling
+
+thebird uses a typed error hierarchy. All errors extend `BridgeError`:
+
+| Error | Status | Retryable | When |
+|---|---|---|---|
+| `AuthError` | 401, 403 | No | Invalid API key |
+| `RateLimitError` | 429 | Yes | Quota exceeded |
+| `TimeoutError` | 408 | Yes | Stream chunk timeout |
+| `ContextWindowError` | 413 | No | Input too long |
+| `ContentPolicyError` | 451 | No | Safety filter triggered |
+| `ProviderError` | 5xx | Yes | Upstream server error |
+
+`GeminiError` is an alias for `BridgeError` (backwards compatible). API keys are auto-redacted in error messages.
+
+```js
+const { classifyError, BridgeError } = require('thebird');
+try { /* ... */ } catch (err) {
+  if (err instanceof BridgeError && err.retryable) { /* retry */ }
+}
+```
+
+## Streaming Resilience
+
+Pass `streamGuard` to protect against stalled or looping streams:
+
+```js
+streamGemini({
+  messages,
+  streamGuard: { chunkTimeoutMs: 30000, maxRepeats: 100 }
+});
+```
+
+- **Chunk timeout** — throws `TimeoutError` if no chunk received within the timeout (default 30s)
+- **Repeat detection** — throws if the same chunk appears consecutively N times (default 100)
+
+## Circuit Breaker
+
+The router tracks per-provider failures. After consecutive failures exceed the threshold, the provider is temporarily skipped:
+
+```js
+createRouter({
+  Providers: [/* ... */],
+  circuitBreaker: { maxFailures: 5, cooldownMs: 60000 }
+});
+```
+
+## Provider Capabilities
+
+Declare what each provider supports. Unsupported features are stripped automatically with warnings:
+
+```json
+{
+  "name": "groq",
+  "api_base_url": "...",
+  "api_key": "$GROQ_API_KEY",
+  "capabilities": { "vision": false, "jsonMode": true }
+}
+```
+
+Defaults: `streaming: true, toolUse: true, vision: true, systemMessage: true, jsonMode: false`.
+
 ## Gemini Direct API
 
 `streamGemini` / `generateGemini` bypass routing and call Gemini natively via `@google/genai`. Requires `GEMINI_API_KEY`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thebird",
-  "version": "1.2.74",
+  "version": "1.2.75",
   "description": "Anthropic SDK to Gemini streaming bridge — drop-in proxy that translates Anthropic message format and tool calls to Google Gemini",
   "scripts": {
     "start": "node serve.js"