@seanhogg/builderforce-sdk 0.4.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 Typed TypeScript SDK for the [Builderforce.ai](https://builderforce.ai) LLM gateway. OpenAI-compatible chat completions with tool calling and structured output, embeddings, model registry, and usage analytics — all behind a single tenant API key. Vendor failover (OpenRouter / Cerebras / Ollama / Claude / GPT / Gemini / Grok) is handled server-side so your code only knows about Builderforce.
 
 - **Vanilla `fetch` / `AbortController` / `ReadableStream` / `TextDecoder`** — runs on Node 18+, Cloudflare Workers, browsers, edge runtimes.
-- **Zero runtime dependencies.** ~22 kB compressed, ~100 kB unpacked.
+- **Zero runtime dependencies.** ~23 kB compressed, ~102 kB unpacked.
 - **Dual ESM + CJS + `.d.ts`** out of the box.
 
 ## Install
@@ -18,9 +18,9 @@ npm install @seanhogg/builderforce-sdk
 import { BuilderforceClient } from '@seanhogg/builderforce-sdk';
 
 const client = new BuilderforceClient({
-  apiKey: process.env.BUILDERFORCE_API_KEY!,
+  apiKey:  process.env.BUILDERFORCE_API_KEY!,
+  baseUrl: process.env.BUILDERFORCE_BASE_URL ?? 'https://api.builderforce.ai',
   // Optional:
-  // baseUrl: 'https://api.builderforce.ai',
   // timeoutMs: 60_000,
 });
 
@@ -31,6 +31,13 @@ const res = await client.chat.completions.create({
 console.log(res.choices?.[0]?.message?.content);
 ```
 
+**Env-var convention:**
+
+| Var | Required | Value |
+|---|---|---|
+| `BUILDERFORCE_API_KEY` | yes | Your `bfk_*` / `clk_*` / tenant-JWT (mint at `/settings/api-keys`) |
+| `BUILDERFORCE_BASE_URL` | no | `https://api.builderforce.ai` (production). Override for staging or self-hosted gateways. |
+
 When you don't pass a `model`, the gateway picks one from your plan's pool and reorders by **request shape** — presence of `tools`, `response_format`, image content blocks. When you do pass a `model`, the gateway treats it as a hint (it tries that model first, may substitute on cooldown / failure — read `_builderforce.resolvedModel` to detect substitution). See [docs/SCENARIOS.md](./docs/SCENARIOS.md) for typical request shapes per scenario.
 
 ## Auth
@@ -39,10 +46,26 @@ The SDK sends `Authorization: Bearer <apiKey>` automatically. The gateway accept
 
 | Prefix | Issued by | Best for |
 |---|---|---|
-| `bfk_*` | `POST /api/tenants/:tenantId/api-keys` (owner-only) | Tenant apps (server-to-server). Long-lived, tenant-scoped, revocable. |
+| `bfk_*` | `POST /api/tenants/:tenantId/api-keys` (owner-only) | Tenant apps (server-to-server). Long-lived, tenant-scoped, revocable, optional origin allowlist. |
 | `clk_*` | `POST /api/claws` (CoderClaw registration) | Self-hosted CoderClaw instances; carries optional per-claw daily token cap. |
 | Tenant JWT | `POST /api/auth/web/login` → `POST /api/auth/tenant-token` | Browser-side calls from a logged-in user. Short-lived. |
 
+### Browser use & origin allowlist
+
+By default, every `bfk_*` is a **server-only** key — any request that arrives with an `Origin` header (i.e. came from a browser) is rejected with `403`. This protects against the common failure mode of leaking a long-lived secret through devtools.
+
+To use a key from a browser, register the allowed origins when minting it (in the portal at `/settings/api-keys`, or via the SDK):
+
+| Allowlist | Browser behaviour |
+|---|---|
+| `null` (default) | Server-only. Browser requests rejected. |
+| `['https://app.example.com']` | Browser calls allowed only from `https://app.example.com`. Exact match — no port/subdomain wildcards. |
+| `['*']` | Any origin allowed. Escape hatch — equivalent to shipping a long-lived secret to the world. Don't. |
+
+When you change a key's allowlist later, in-flight calls are unaffected; new calls take the new policy on the next request.
+
+The SDK preflight headers (`Authorization`, `Idempotency-Key`, `Content-Type`) and exposed response headers (`x-builderforce-daily-tokens-*`, `x-request-id`) are all configured on the gateway's CORS policy — your origin only needs to be in your key's allowlist.
+
 ## Streaming chat
 
 ```ts
@@ -285,6 +308,7 @@ try {
 | 409 | `idempotent_replay` | `Idempotency-Key` was used within the last 10 min — treat as no-op |
 | 429 | `plan_token_limit_exceeded` | Tenant hit daily plan budget |
 | 429 | `claw_token_limit_exceeded` | Per-claw daily cap exceeded (`clk_*` keys only) |
+| 403 | `origin_not_authorized` | Browser request from an origin not in the key's allowlist (or key has no allowlist — server-only) |
 | 503 | (no code) | Vendor key not configured for the active plan tier |
 | 401 | `missing_api_key` | Auth issues |
 | 403 | (varied) | Wrong scope / wrong tenant for the URL |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Typed SDK for the Builderforce.ai LLM gateway — chat completions with tool-calling and structured output, embeddings, models, and usage analytics over an OpenAI-compatible surface.",
   "license": "MIT",
   "author": "Sean Hogg",