apiblaze 0.20.45 → 0.21.0

package/README.md

@@ -13,6 +13,10 @@ npm install -g apiblaze    # or install globally
 
 Requires Node.js 18+.
 
+### Running as `npx mcpblaze`
+
+[`mcpblaze`](https://www.npmjs.com/package/mcpblaze) is the same CLI under its MCP name: a thin wrapper that runs this package with `APIBLAZE_BRAND=mcpblaze`. Every command and flag is identical; the wording changes — `create` says "Create an MCP server", the thing you make lives at `https://{name}-{tenant}.mcpblaze.com/{version}/{env}`, and the demo after a create is connecting Claude Code or Codex to it rather than a curl. Set `APIBLAZE_BRAND=mcpblaze` yourself to get the same output from `npx apiblaze`.
+
 ## Quick start
 
 The easiest way is to just chat with it:
@@ -31,25 +35,36 @@ Prefer commands? A few one-liners:
 npx apiblaze apichat --openapi https://apiblaze.com/pokeapi_openapi.yaml
 
 # Make an API in one line — no account needed (prints a claim URL).
-# By default callers sign in with GitHub (APIblaze-hosted); add --apikey for an API-key door.
+# Both doors open by default: an API key for your backend and widget (send X-API-Key and
+# say who is calling with X-End-User-Id), and GitHub sign-in for people and agents.
+# --apikey = the key door only; --oauth = the sign-in door only.
 npx apiblaze create --target https://api.example.com
 
 # Or build it straight from an OpenAPI spec — a URL or a local file.
 # The routes, the API version and one environment per `servers` entry all come from the spec,
 # and you're asked which resources to lock to the person who created them (e.g. /reservations).
+# At the end it offers to connect Claude Code or Codex to the new MCP server — by default with
+# an API key issued to you (works on the first message), or with GitHub sign-in.
 npx apiblaze create --target https://petstore3.swagger.io/api/v3/openapi.json
 
-# Same thing with zero prompts: GitHub sign-in, every lockable resource locked.
+# Same thing with zero prompts: both doors, every lockable resource locked.
 npx apiblaze create --target ./openapi.yaml --auto
 
+# Teach Claude Code to do all of the above for you when you say "ship this API"
+npx apiblaze skill --install
+
 # Configure how your backend is accessed through the proxy
 npx apiblaze config
 
 # Configure who accesses your backend through the proxy
 npx apiblaze tenant
 
-# Access your localhost through a proxied URL
-npx apiblaze dev 3000
+# Your local code, shipped safely: both doors, resources locked to their creator,
+# an admin, Claude Code connected — with localhost as the target, through a tunnel.
+npx apiblaze dev --port 3000 --openapi ./openapi.yaml
+
+# What to add to your frontend + frontend-server (widgets, call-through, env vars)
+npx apiblaze integration myapi --stack nextjs
 
 # Route a Next.js app's outbound fetch() through APIblaze
 npx apiblaze sidecar
@@ -58,6 +73,41 @@ npx apiblaze sidecar
 npx apiblaze login
 ```
 
+## Skill
+
+`npx apiblaze skill --install` writes `.claude/skills/ship-safely/SKILL.md` into your project. From then on, when you tell Claude Code to ship, expose or add auth to an API, it puts APIblaze in front of your code instead of hand-rolling auth: it uses the control-plane MCP (`claude mcp add --transport http apiblaze https://mcp.apiblaze.com`, then `/mcp` to sign in once) to create the server, propose and apply the ownership rules, add an admin, issue keys and hand you the integration snippets — your backend does not change.
+Under `npx mcpblaze` the same skill names MCPblaze and `mcp.mcpblaze.com`; it is the same server.
+
+`skills` is an alias of `skill` — Claude Code's folder is `.claude/skills/`, so both spellings do the same thing:
+
+```bash
+npx apiblaze skill              # print SKILL.md to stdout
+npx apiblaze skills             # identical
+npx apiblaze skills --install   # write .claude/skills/ship-safely/SKILL.md (add --force to overwrite)
+```
+
+### Where your callers sign in
+
+The skill teaches Claude to ask "where do your users sign in today?" before creating anything, because a multi-tenant app usually already has a login and its users should not get a second one. Three shapes, exactly as `create --oauth` (and `dev --oauth`) accepts them:
+
+```bash
+# 1. Nothing passed — both doors: an API key for your server, plus hosted GitHub sign-in
+#    for people and agents. Bare --oauth narrows it to the sign-in door alone.
+npx apiblaze create --target https://api.example.com
+
+# 2. YOUR OWN OAuth app on a hosted login page — the agent's users sign in exactly where
+#    your users already do. provider is one of: auth0 · google · github · microsoft · facebook.
+npx apiblaze create --target https://api.example.com \
+  --oauth «'{"provider":"auth0","clientId":"AbC123…","clientSecret":"s3cr3t…"}'»
+
+# 3. YOUR OWN JWT issuer — no login page at all; the proxy verifies the tokens you already
+#    issue. All three fields are required; jwks is that issuer's JWKS URL.
+npx apiblaze create --target https://api.example.com \
+  --oauth «'{"iss":"https://login.acme.com/","aud":"acme-api","jwks":"https://login.acme.com/.well-known/jwks.json"}'»
+```
+
+Your tenants then self-serve their own keys from the key widget inside **your** app (`npx apiblaze integration <name> --stack nextjs`), your frontend-server holds one server key and says who is calling with `X-End-User-Id`, and `npx apiblaze apikeys mint --tenant <tenant> --for <email>` mints a key bound to one person.
+
 ## Embeddable widgets (React)
 
 Let your customers self-serve from **your** site — **API keys** (`<ApiKeyWidget/>`) and
@@ -122,10 +172,12 @@ Every chat turn shows its cost.
 
 | Command | What it does |
 |---|---|
-| `apiblaze create --target <url>` | Make an API from a backend (no account needed). Callers sign in with GitHub by default; `--apikey` for an API-key door |
-| `apiblaze create --target <file\|url>` | Make an API from an OpenAPI spec — a local file or a spec URL. Asks which resources to lock to their creator; `--auto` locks them all |
+| `apiblaze create --target <url>` | Make an API from a backend (no account needed). Both doors by default: an API key for your code, GitHub sign-in for agents. `--apikey` / `--oauth` open one door only |
+| `apiblaze create --target <file\|url>` | Make an API from an OpenAPI spec — a local file or a spec URL. Asks which resources to lock to their creator, then offers to connect Claude Code / Codex; `--auto` locks them all |
+| `apiblaze skill [--install]` | Print (or install into `.claude/skills/`) the Claude Code skill that teaches Claude to ship your API safely with APIblaze. `apiblaze skills` is the same command; `--force` overwrites an existing SKILL.md |
 | `apiblaze sidecar` | Route a Next.js app's external `fetch()` calls through APIblaze (one command) |
-| `apiblaze dev [port]` | Put your localhost behind a public URL |
+| `apiblaze dev --port <p> [--openapi <spec>]` | The hero command for code on this machine: everything `create` does, with localhost as the target through a tunnel. Without `--openapi` it looks for `/openapi.json`, `/openapi.yaml`, `/docs/openapi.json` on that port. `--auto` = every answer is the default |
+| `apiblaze integration <name> --stack nextjs` | What to add to your frontend and frontend-server (also `express`, `fastapi`, `other`): the widgets, the call-through with the key + `X-End-User-Id`, what your backend must trust, env vars, what stays open. `--json` for the raw kit |
 | `apiblaze login` / `logout` | Sign in / out (logout asks producer or consumer) |
 | `apiblaze whoami` | Who am I — both Producer and Consumer |
 | `apiblaze team [name]` | Switch team |
@@ -187,16 +239,44 @@ shows both, and `logout` asks which to drop.
 >
 > Advanced: `apiblaze apikeys` manages producer control-plane keys for scripting.
 
-## How it works
+## `apiblaze dev` — your local code, shipped safely
+
+```
+$ npx apiblaze dev --port 3000 --openapi ./backend/openapi.yaml
+
+  Tunnel → http://localhost:3000
+  Spec: ./backend/openapi.yaml
+? Name: nino
+? Do you want to prevent unauthorized users from taking unauthorized actions? Yes
+? Lock these to the person who created them (or an admin): reservations, tables, restaurants
+? Who is the admin? Their email address (Enter to skip): julien@ninopizzas.com
+
+  ✓ https://nino.abz.run/1.0.0/dev  → localhost:3000   (sign-in with GitHub, or an API key)
+  ✓ reservations, tables + restaurants locked to their creator · julien@ninopizzas.com is admin
+  ✓ agents: https://nino-ninodefaulttenant.mcpblaze.com/1.0.0/dev
+
+  API key (for your frontend-server, shown once): sk_dev_…   → send it as X-API-Key and say who is calling with X-End-User-Id
+
+? Connect Claude Code to it now? Yes
+  ✓ connected — it acts as julien@ninopizzas.com; try "Create a reservation, then show it to me."
+
+  Tunnel is up — leave this running. Ctrl-C stops it.
+```
 
-`apiblaze dev` automatically:
+No login needed (logged out, the proxy lives in an anonymous workspace you can claim).
+What it does, in order:
 
-1. Fetches your APIblaze projects that target `localhost` (or other internal targets)
-2. Registers a temporary dev tunnel with APIblaze
-3. Opens a secure connection and forwards incoming requests to your local server
-4. Streams live traffic logs to your terminal in real time
+1. Reads your OpenAPI spec (`--openapi`, or `/openapi.json` · `/openapi.yaml` · `/docs/openapi.json`
+   on the port). No spec → no rules; everything else still works.
+2. Asks four short questions (name, lock resources, which ones, the admin) — `--auto` takes the defaults.
+3. Creates the proxy with both doors open, points it at your machine through a tunnel, applies the
+   rules, adds the admin (active now — a key issued to them creates their identity first).
+4. Offers to connect Claude Code (or Codex) with a key that acts as the admin — nothing to sign in to.
+5. Streams live traffic until Ctrl-C, then restores the project's original target.
 
-On Ctrl+C the tunnel is cleanly deregistered.
+If a project already points at this machine, `dev` offers to re-attach it instead (`--project <name>`
+picks one for scripts). Then `npx apiblaze integration <name> --stack nextjs` tells you what to add
+to your frontend and frontend-server.
 
 ## Sidecar — proxy a Next.js app's egress
 
@@ -230,9 +310,8 @@ left alone.
 
 ## How it works
 
-- **No project yet?** If none of your projects point at this machine, `apiblaze dev`
-  offers to spin up a throwaway dev proxy (random name like `braveotter42`) pointed at
-  `http://localhost:<port>` and tunnels it immediately — pick `none` or `api_key` auth.
+- **No project yet?** `apiblaze dev` sets one up (see above): both doors, rules from your
+  spec, an admin, an agent — pointed at `http://localhost:<port>` and tunneled immediately.
 - **Server not running yet?** If nothing is listening on the local port, requests aren't
   dropped: each one is printed in full (headers + body, with API keys/JWTs masked and JWTs
   decoded) and answered with a friendly synthetic `200`. The moment your dev server comes