Specbook 0.8.1: APIs that allow CORS work again with the extension installed

With the 0.8.0 extension installed, a live call to an API that already allows CORS (the Petstore demo, for example) asked you to allow it first. It no longer does.

• A call to an API you have not allowed yet is tried straight from the page first, as it was before the extension. Only when the browser blocks that does the response offer Allow. The one exception is a plain POST (a form or text body, no headers of its own), which a browser sends without asking the API first, so it still asks you first.
• The extension's window is readable in dark mode: failed rows in "Recent calls" are now a lighter red.

The extension zip (specbook-extension-chromium-0.8.1.zip) changes only in that dark-mode color; the call fix is in @specbook/ui.

No breaking changes.

Full Changelog: v0.8.0...v0.8.1

Specbook 0.8.0: browser extension for live calls

Live calls from a hosted Specbook page no longer need an API that allows CORS. A new browser extension makes the call for you, with your permission for each API.

• A browser extension for Chromium browsers on a computer. It is attached to this release as specbook-extension-chromium-0.8.0.zip; the install steps are on https://docs.specbook.dev/reference/browser-extension/. It asks for nothing when you install it. The first live call to an API fails with an Allow button, and a grant belongs to one site and one API. It reads only until you also allow Modify data (POST, PUT, PATCH and DELETE), sends no cookies, and every grant can be revoked.
• The offer is in the failed response. A call the browser blocked says the extension can send it. A call it has not been allowed to make shows Allow, and a refused change shows Allow modifying data. A response that came through the extension says via extension and carries an x-specbook-via header.
• One list in the extension's window. The API being asked about is highlighted, with a Modify data box beside Allow, so reading and modifying can be allowed in one answer.
• @specbook/core: a failed step can say what a page can offer (StepResult.errorHint), and the extension's wire protocol and its dispatcher are available as @specbook/core/wire.
• Docs: a reference page for the extension and its privacy policy, and variables explained: {petId} in a spec is the path parameter, {{petId}} is a Specbook variable.

The extension is not in a store yet. Until it is, unzip it and load it unpacked (turn on Developer mode in chrome://extensions).

No breaking changes.

Full Changelog: v0.7.0...v0.8.0

Specbook 0.7.0: better mock heuristics

Mock responses and generated examples now read your spec more closely.

• Values come from the spec: examples, defaults, enums, descriptions ("Can be amex", "ISO currency code") and the same field elsewhere in the document. Nothing is invented for an enum.
• Limits are honoured: pattern, length, minimum/maximum, multipleOf, minItems.
• Responses are smaller: another resource embedded by value is null or left out (Stripe's Customer goes from 457 lines to 84), and errors keep only the usual fields (Stripe's error from 1,139 lines to 9).
• A spec's own response example is used when it satisfies the schema.
• The mock recognises a secret or client id header as a credential.

No breaking changes. Run specbook generate to refresh generated examples.

Full changelog: v0.6.1...v0.7.0

Specbook 0.6.1: optional fields in OpenAPI 3.1

A fix for specs that mark optional fields the OpenAPI 3.1 way, which is how FastAPI and Pydantic v2 write every Optional field.

Fixes

• No false "differences from spec" on optional fields. A field written as anyOf: [{ type: integer }, { type: 'null' }] lost its null branch, so a response with "owner_id": null was flagged as "expected integer, got null". It now matches. This affects the viewer, the play panel and the portal.

Also

• specbook-fastapi 0.1.0 is out on PyPI, as a separate package: pip install specbook-fastapi serves the viewer from a FastAPI app. See Use with FastAPI.
• The README's example instructions no longer run specbook generate before specbook dev, since dev generates what it needs.

Full changelog: v0.6.0...v0.6.1

Specbook 0.6.0

Embeds and the viewer now show the same Specbook header everywhere, and "Powered by Specbook" leads to the docs.

What's new

• Header name and mark go together. When the header shows "Specbook" it now shows the Specbook mark too, however the viewer was opened, including embeds such as the Hono middleware. A project that sets its own branding.name without a logo shows the name alone, and a logo (yours or the spec's x-logo) still wins.
• "Powered by Specbook" links to the docs. The link in the overview now goes to docs.specbook.dev, where the whole product is described, with your site's hostname in the address.

Fixes

• A tab left open across a deploy loads the new page. If a deploy removed a chunk the open page still needs, the portal reloads once (at most once a minute) instead of failing with a missing file.

Hosted sites

• The docs site allows Cloudflare Web Analytics. On ui.specbook.dev it runs on the home page only, never on the viewer or the sign-in return page, whose addresses can carry a spec address or an authorization code.

Full changelog: v0.5.0...v0.6.0

Specbook 0.5.1

A steadier header and no stale tabs.

The portal and the viewer recover when a tab is left open across a deploy, and the header always pairs our name with our mark.

What's new

• Header name and mark go together. When the header shows "Specbook" it now shows the Specbook mark too, however the viewer was opened, including embeds such as the Hono middleware. A project that sets its own branding.name without a logo shows the name alone, and a logo (yours or the spec's x-logo) still wins.

Fixes

• A tab left open across a deploy loads the new page. If a deploy removed a chunk the open page still needs, the portal reloads once (at most once a minute) instead of failing with a missing file. This applies to the QA portal, the demo and the viewer.

Hosted sites

• The docs site allows Cloudflare Web Analytics. On ui.specbook.dev it runs on the home page only, never on the viewer or the sign-in return page, whose addresses can carry a spec address or an authorization code.

Full changelog: v0.5.0...v0.5.1

Specbook 0.5.0

Generated values now appear only when you write them, and the hosted viewer no longer downloads faker.

What's new

• Hosted viewer and embed ship no faker. ui.specbook.dev and the dist-viewer/ folder in @specbook/ui no longer include the 422 KB faker chunk. A {{faker.…}} typed there stops the run with a clear message instead of being sent as text.
• No more "Dynamic" example. Each operation has one generated Default; old dynamic.example.json files are removed when you regenerate.
• Faker is always there for projects. specbook init adds @faker-js/faker, and faker from @specbook/core/faker is now typed, so a misspelt generator fails tsc. QA can type {{faker.person.firstName}} into any field in the portal.
• Smaller builds. A portal ships only the faker locales listed in your config (plus en), and a browser downloads faker only when a run uses it. specbook test and specbook bundle leave it out when nothing uses it.
• Generated values control. "Synthetic data" is now "Generated values" and is on while the open request or flow uses faker. specbook test --seed repeats a run.

Fixes

• A misspelt {{faker.…}}, or one with arguments, now stops the run and names the placeholder instead of reporting a missing variable or being sent as it is.
• The command line reference lists every flag.

Full changelog: v0.4.0...v0.5.0

Specbook 0.4.0

Agents can now build your requests and flows, and the viewer embed can open on a live API.

What's new

• Agents can build your requests and flows. specbook init writes an agent guide to .specbook/agent-guide.md and adds a short section to AGENTS.md (or CLAUDE.md). It never edits a file you wrote unless you pass --agents, and --no-agents skips it. The docs site also serves llms.txt.
• Embed opens where you want. The viewer embed takes defaultEnv ("live", or a server name from your spec) to start on that environment instead of mock.
• Array positions in placeholders. {{tags[0].name}} works, and placeholders read only a value's own properties.
• Clearer failures. A failing request shows its full URL with the base path, and an unreachable API says why: connection refused, DNS, timeout or certificate.
• Docs: the Content-Security-Policy for the hosted viewer lists style-src as well as script-src and worker-src (with blob:).

Fixes

• A request from your project is called a request in the viewer, and its note says only what is true.
• On a phone the header keeps the brand whole and its links get their own row.
• The docs hero has a button that opens your own spec in the viewer.

Full changelog: v0.3.0...v0.4.0

Specbook 0.3.0

The docs site is live at docs.specbook.dev, and the runner, reporters and QA portal are production-grade.

Breaking changes

• Mocks moved out of the request. The mock: field is gone. Wrap the request in withMock, typed from the operation:

  export default withMock(GetOrderById.request({ /* ... */ }), (req, res) => {
    if (res.status === 200) res.data.status = 'placed'
  })

  Most requests need no hook: the mock environment answers from your spec's examples with the request's values filled in.
• The play panel opens from data-specbook-try and data-specbook-flow. The old data-specbook, data-operation and data-sequence attributes are removed.
• specbook test replaces specbook run.

What's new

• Test and monitor: list, JUnit, GitHub, JSON and NDJSON reporters, tags, retries with flaky detection, --safe for production, secrets masked in every report, and a failing check shown as expected versus received.
• specbook bundle: your tests as one .mjs that runs with just node.
• specbook build --minimal: a portal of just your requests and flows, for QA.
• Timeouts and Stop: timeoutMs in the config and --timeout on the CLI (default 30 s, 0 waits), and a Stop button for flows and requests in the UI.
• Inputs: generated defaults for flow inputs, and Run with defaults in the UI.
• specbook add <service> --spec <url> downloads and records a spec, and --refresh fetches it again.
• Docs site and demo: a demo API that runs as a service worker, and a terminal that runs the real runner in the page.

Fixes

• A run that returns something unexpected no longer freezes the panel.
• A select whose default is not one of its options now picks the first option.
• A request that times out says so.

Packages: @specbook/core, codegen, vite, ui, cli. The viewer zip, with checksums and a build attestation, is attached below.

Full changelog: v0.2.0...v0.3.0

Specbook 0.2.0

Sign in to OAuth APIs from the browser, and every server a spec lists is now an environment.

New

• Sign in with OAuth 2.0 and OpenID Connect. When a spec declares an authorization code flow, or an OpenID
  Connect provider, the credentials prompt offers Sign in. It uses PKCE, so there is no client secret. The
  token stays in the tab, is bound to the API's origin, and is applied through the same {{secrets.*}}
  substitution as a pasted value. Pasting a token still works, and is the fallback if the provider will not talk
  to a browser.
• Every servers entry is an environment. Opening a spec with production, sandbox and regional servers now
  gives you each of them in the Environment picker, not just the first. The first stays live; the others are
  named from their description. Credentials are kept per API origin, so a key typed for one server's host is not
  sent to another's.

Setting up sign-in

Register a public client (no secret) with your provider and allow this redirect URI:

https://ui.specbook.dev/oauth/callback/

It is a page that does not change when the viewer's version does. On a viewer you embed or host yourself the
address is your page's own, and specbook dev and specbook preview print theirs. Enter the client id in the
prompt. Sign-in works from an embedded viewer, and needs a secure page (https, or localhost).

Improved

• The response is shown as soon as a request has been sent.
• The sign-in prompt, and the example links on the landing page, are laid out for a phone.
• Third-party notices ship with the built viewer.
• Fixed a stale landing-page stylesheet meeting new markup after a deploy.
• Fixed a rare half-read of specbook.json while another generate was writing it.

Good to know

• A scheme has one sign-in provider for all its environments. If an environment signs in somewhere else, paste a
  token there.
• From the hosted viewer or a static build the token exchange is made by the browser, so the provider must allow
  calls from the page's origin: add https://ui.specbook.dev to its allowed (web) origins. In specbook dev and
  preview it goes through the dev server's proxy, so that is not needed.
• A viewer framed inside another site's page completes sign-in only with providers that do not cut the
  window's opener (a provider can, with a Cross-Origin-Opener-Policy header). Embed the script, host the viewer
  yourself, or paste a token there.
• Providers that need a client secret at the token endpoint cannot be used from a browser; paste a token instead.
• Refresh tokens are not handled yet: sign in again when a token expires.

No breaking changes. Config gains an optional oauth setting on auth profiles, and @specbook/core exports the
new OAuth and server helpers.

Sign-in is tested against a real Keycloak in Docker (pnpm test:oauth, also run weekly).

Full changelog: v0.1.0...v0.2.0