@quickback-dev/cli 0.65.0 → 0.66.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts +1 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -0
- package/dist/commands/compile.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +14 -6
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +26 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle.js +6 -1
- package/dist/lib/migrations/drizzle.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +3 -0
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/skill/docs/api/batch-operations.md +1 -1
- package/dist/skill/docs/api/crud.md +1 -1
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/query-params.md +5 -8
- package/dist/skill/docs/changelog/index.md +109 -1
- package/dist/skill/docs/configure/auth.md +20 -12
- package/dist/skill/docs/configure/domains.md +11 -0
- package/dist/skill/docs/configure/index.md +16 -27
- package/dist/skill/docs/configure/providers.md +1 -1
- package/dist/skill/docs/define/actions/defining.md +2 -2
- package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +1 -1
- package/dist/skill/docs/define/changesets.md +7 -8
- package/dist/skill/docs/define/feature.md +0 -1
- package/dist/skill/docs/define/read.md +2 -2
- package/dist/skill/docs/define/sealed-protocol.md +1 -1
- package/dist/skill/docs/platform/api-contract/index.md +52 -42
- package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/dist/skill/docs/platform/auth/plugins/index.md +9 -2
- package/dist/skill/docs/platform/database/neon.md +1 -1
- package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/dist/skill/docs/platform/realtime/index.md +8 -10
- package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/dist/skill/docs/platform/realtime/using-realtime.md +58 -34
- package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
- package/dist/skill/docs/tooling/output.md +1 -1
- package/dist/skill/docs/ui/account/hooks.md +0 -1
- package/package.json +1 -1
- package/src/skill/docs/api/batch-operations.md +1 -1
- package/src/skill/docs/api/crud.md +1 -1
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/query-params.md +5 -8
- package/src/skill/docs/changelog/index.md +109 -1
- package/src/skill/docs/configure/auth.md +20 -12
- package/src/skill/docs/configure/domains.md +11 -0
- package/src/skill/docs/configure/index.md +16 -27
- package/src/skill/docs/configure/providers.md +1 -1
- package/src/skill/docs/define/actions/defining.md +2 -2
- package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/src/skill/docs/define/actions/scoped-db.md +1 -1
- package/src/skill/docs/define/changesets.md +7 -8
- package/src/skill/docs/define/feature.md +0 -1
- package/src/skill/docs/define/read.md +2 -2
- package/src/skill/docs/define/sealed-protocol.md +1 -1
- package/src/skill/docs/platform/api-contract/index.md +52 -42
- package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/src/skill/docs/platform/auth/plugins/index.md +9 -2
- package/src/skill/docs/platform/database/neon.md +1 -1
- package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/src/skill/docs/platform/realtime/index.md +8 -10
- package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/src/skill/docs/platform/realtime/using-realtime.md +58 -34
- package/src/skill/docs/platform/webhooks/outbound.md +4 -5
- package/src/skill/docs/tooling/output.md +1 -1
- package/src/skill/docs/ui/account/hooks.md +0 -1
|
@@ -8,6 +8,114 @@ The current release series. Older entries are archived by version range:
|
|
|
8
8
|
- [v0.20 – v0.29](/changelog/v0.2x)
|
|
9
9
|
- [v0.18 and earlier](/changelog/v0.1x)
|
|
10
10
|
|
|
11
|
+
## Unreleased — the standard API shape
|
|
12
|
+
|
|
13
|
+
### BREAKING: `contract.version` is retired
|
|
14
|
+
|
|
15
|
+
There is one standard API shape, so there is nothing to select. Pinning
|
|
16
|
+
`contract.version` is now a **compile error** on either value.
|
|
17
|
+
|
|
18
|
+
**Delete that one line and keep `contract.routes` if you have it.** `routes`
|
|
19
|
+
is the surviving axis and is what decides whether your URLs read `/api/v1` or
|
|
20
|
+
`/api/v2` — removing it would move them.
|
|
21
|
+
|
|
22
|
+
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
23
|
+
```typescript
|
|
24
|
+
contract: { version: "v2", routes: "v1" } // before
|
|
25
|
+
contract: { routes: "v1" } // after — same URLs, same behavior
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Deleting `version: "v2"` changes **no** behavior: it selected what is now
|
|
29
|
+
simply the standard shape. Deleting `version: "v1"` is a real migration — see
|
|
30
|
+
[the contract page](/platform/api-contract#contractversion-is-retired) for the
|
|
31
|
+
four behaviors that pin opted out of, all now unconditional.
|
|
32
|
+
|
|
33
|
+
### BREAKING: CloudEvents `type` is reverse-DNS prefixed
|
|
34
|
+
|
|
35
|
+
Realtime `postgres_changes` and `view_changes` frames now carry a
|
|
36
|
+
`dev.quickback.` prefix on the CloudEvents `type`:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
myapp.registrations.insert → dev.quickback.myapp.registrations.insert
|
|
40
|
+
myapp.view.agendaBoard.changed → dev.quickback.myapp.view.agendaBoard.changed
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**`qbframe` is the supported discriminator — do not match on `type`.** Its
|
|
44
|
+
shape is not a stable contract; `qbframe` (`"broadcast"` / `"postgres_changes"`
|
|
45
|
+
/ `"view_changes"`) is. A client switching on `type` breaks here.
|
|
46
|
+
|
|
47
|
+
**Author-supplied broadcast event names are unchanged.** A named-invalidation
|
|
48
|
+
frame's `type` is still your `wireName` verbatim — that vocabulary is yours,
|
|
49
|
+
not ours to prefix.
|
|
50
|
+
|
|
51
|
+
`/asyncapi.json` documents the new `type` patterns, and its `info.version` is
|
|
52
|
+
now the event-document version rather than a contract version.
|
|
53
|
+
|
|
54
|
+
### BREAKING: outbound webhooks are Standard Webhooks only
|
|
55
|
+
|
|
56
|
+
The legacy `X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery`
|
|
57
|
+
headers and the Stripe-format `signPayload` / `verifySignature` pair are gone
|
|
58
|
+
from the generated project — including from the public webhooks module's
|
|
59
|
+
exports. Receivers must verify with `webhook-signature`. This is the one
|
|
60
|
+
change a **receiver** absorbs without any config change of its own, so tell
|
|
61
|
+
your endpoint partners.
|
|
62
|
+
|
|
63
|
+
### BREAKING: `include` and `fields[...]` are reserved query params
|
|
64
|
+
|
|
65
|
+
`?include=` is always available now (where allowlisted), which makes `include`
|
|
66
|
+
a reserved parameter and any `fields[`-prefixed key reserved too. **A column
|
|
67
|
+
literally named `include` is no longer filterable** via `?include=…`. Unknown
|
|
68
|
+
`?fields=` and `fields[<fk>]=` names return **400** instead of being dropped.
|
|
69
|
+
|
|
70
|
+
### Fixed: scoped projects without `auth.jwt` could not admit their own scope tokens
|
|
71
|
+
|
|
72
|
+
Scope admission used to be emitted only inside the JWT credential lane, so a
|
|
73
|
+
project with `authz.scopes` and no `auth.jwt` minted scope tokens that no
|
|
74
|
+
generated code could accept — 401 on every presentation, with no diagnostic.
|
|
75
|
+
Live since v0.64.0, when that lane stopped being on by default.
|
|
76
|
+
|
|
77
|
+
Admission is now emitted whenever the project declares scopes, independent of
|
|
78
|
+
`auth.jwt`. **No config change is needed** — and declaring scopes does not
|
|
79
|
+
open the credential surface: no `POST /token` route, no identity fast-path,
|
|
80
|
+
no bearer fast-path unless you separately declare `auth.jwt`.
|
|
81
|
+
|
|
82
|
+
This covers **sessionless** scope tokens (`ctx.mintScope`). A token minted
|
|
83
|
+
from a session — `POST /scope/v1/enter`, or a namespace with
|
|
84
|
+
`mintScope: true` — carries user claims rather than the scope-only marker, so
|
|
85
|
+
without `auth.jwt` it still cannot be admitted: 200 from the mint, 401 on
|
|
86
|
+
presentation. The compiler now warns instead of failing silently. Declare
|
|
87
|
+
`auth: { jwt: {} }` if you use those routes.
|
|
88
|
+
|
|
89
|
+
## v0.65.x — August 16, 2026
|
|
90
|
+
|
|
91
|
+
### Passkeys no longer silently degrade to `rpID: 'localhost'`
|
|
92
|
+
|
|
93
|
+
The generated passkey plugin (and the SEALED reveal step-up, which must verify
|
|
94
|
+
against the same relying party) now bakes a compile-time fallback derived from
|
|
95
|
+
your configured domain — `account.domain` when set, else the unified host.
|
|
96
|
+
`ACCOUNT_URL` remains a runtime override, and its **bare origin** is now used
|
|
97
|
+
for WebAuthn even when the value carries a path (`https://host/account`), so
|
|
98
|
+
one variable serves both the email link base and the relying-party origin.
|
|
99
|
+
The rpID derivation also stops stripping two-label hostnames to a bare TLD
|
|
100
|
+
(`example.com` no longer became rpID `com`). `localhost` now applies only to
|
|
101
|
+
projects with no configured domain at all.
|
|
102
|
+
|
|
103
|
+
### `APP_URL` — per-deploy override for `account.appUrl`
|
|
104
|
+
|
|
105
|
+
`account.appUrl` is baked at compile time into the Account SPA runtime config
|
|
106
|
+
and the "Go To App" email CTAs, which pointed preview/dev deploys at
|
|
107
|
+
production. Set `APP_URL` on the deploy target to override both at serve
|
|
108
|
+
time — same one-bundle-several-hostnames pattern as `EXTRA_APP_HOSTS` and
|
|
109
|
+
`BETTER_AUTH_URL`.
|
|
110
|
+
|
|
111
|
+
### Account SPA keeps its `/account` basepath through login redirects
|
|
112
|
+
|
|
113
|
+
On path-mounted deployments, a post-login redirect could navigate to a bare
|
|
114
|
+
path (`/dashboard` instead of `/account/dashboard`) and fall through to a
|
|
115
|
+
tenant route. The callback sanitizer now re-applies the basepath to
|
|
116
|
+
same-origin paths, covering every sign-in flow (password, passkey, email OTP,
|
|
117
|
+
signup) and social-link callbacks.
|
|
118
|
+
|
|
11
119
|
## v0.65.0 — August 16, 2026
|
|
12
120
|
|
|
13
121
|
### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
|
|
@@ -131,7 +239,7 @@ total lost `required`, with sampled paths.
|
|
|
131
239
|
|
|
132
240
|
An unset `contract.version` resolves to `'v1'` today. That default becomes
|
|
133
241
|
`'v2'` in **v0.64.0**. See the
|
|
134
|
-
[contract matrix](/platform/api-contract#
|
|
242
|
+
[contract matrix](/platform/api-contract#contractversion-is-retired).
|
|
135
243
|
|
|
136
244
|
> v0.64.0 shipped this **without** moving any URLs — semantics and routes became
|
|
137
245
|
> independent axes, so `/api/v1` stays put. This entry originally said the flip
|
|
@@ -24,20 +24,28 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
|
|
|
24
24
|
|
|
25
25
|
Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
|
|
26
26
|
|
|
27
|
-
> **This JWT surface is opt-in
|
|
27
|
+
> **This JWT surface is opt-in**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
>
|
|
31
|
-
>
|
|
32
|
-
>
|
|
33
|
-
>
|
|
34
|
-
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
35
|
-
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
36
|
-
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
37
|
-
> available.
|
|
29
|
+
> Quickback emits this custom JWT surface only when `auth.jwt` is present. Omit
|
|
30
|
+
> it and the generated output has no generic `/api/v1/token` endpoint, no
|
|
31
|
+
> identity JWT mint, and no Bearer-JWT instructions in `llms.txt` or RFC 8414
|
|
32
|
+
> discovery metadata. Better Auth cookie and signed session-token bearer
|
|
33
|
+
> authentication remain available.
|
|
38
34
|
>
|
|
39
|
-
>
|
|
40
|
-
>
|
|
35
|
+
> **Scopes are the exception.** A project that declares
|
|
36
|
+
> [`authz.scopes`](/define/scopes) always emits `src/lib/jwt.ts` (scope tokens
|
|
37
|
+
> are signed JWTs) *and* a scope-only verification block that admits them —
|
|
38
|
+
> without the token endpoint or the identity fast-path. Declaring scopes does
|
|
39
|
+
> not open the credential surface.
|
|
40
|
+
>
|
|
41
|
+
> One gap to know about: that block admits **sessionless** scope tokens
|
|
42
|
+
> (`ctx.mintScope`). A token minted from a session — `POST /scope/v1/enter`, or
|
|
43
|
+
> a namespace with `mintScope: true` — carries user claims instead of the
|
|
44
|
+
> scope-only marker, and without `auth.jwt` nothing can admit it, so the caller
|
|
45
|
+
> gets 200 from the mint and 401 when presenting it. The compiler warns. Declare
|
|
46
|
+
> `auth: { jwt: {} }` if you rely on those routes.
|
|
47
|
+
>
|
|
48
|
+
> Use `auth: { jwt: {} }` to opt into the defaults documented below.
|
|
41
49
|
|
|
42
50
|
|
|
43
51
|
### Security posture at a glance
|
|
@@ -287,6 +287,17 @@ Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed w
|
|
|
287
287
|
> When more than one app is hostname-mounted, extras attach to the first registered apps middleware (Hono runs middleware in registration order and terminates on first match). If you need extras to route to a specific app in a multi-app deploy, set `apps[*].domain` directly and recompile rather than using this env var.
|
|
288
288
|
|
|
289
289
|
|
|
290
|
+
### Per-deploy app URL
|
|
291
|
+
|
|
292
|
+
`account.appUrl` is baked at compile time into the Account SPA's runtime config and used as the "Go To App" link base in transactional emails — so a preview or dev worker would send emails and render links pointing at production. Set `APP_URL` on the deploy target to override both at serve time: the worker merges it into the runtime config injected into every served shell, and email templates prefer it over `ACCOUNT_URL`.
|
|
293
|
+
|
|
294
|
+
```toml title="wrangler.preview.toml"
|
|
295
|
+
[vars]
|
|
296
|
+
APP_URL = "https://app-preview.example.com"
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Unset means zero behavior change. (Setting it changes the injected runtime-config bytes, so a strict-CSP deploy relying on the precomputed script hash should keep it unset on the production target — the same tradeoff as named-dev host injection.)
|
|
300
|
+
|
|
290
301
|
## See Also
|
|
291
302
|
|
|
292
303
|
- [Configuration](/configure) — CMS and Account config options
|
|
@@ -94,9 +94,9 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
94
94
|
| Field | Type | Description |
|
|
95
95
|
|-------|------|-------------|
|
|
96
96
|
| `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/configure/domains) |
|
|
97
|
-
| `contract` | `{
|
|
97
|
+
| `contract` | `{ routes?: "v1" \| "v2" }` | `routes` selects the URL prefix and nothing else (default `"v1"`). See [API Contract](/platform/api-contract#one-axis-routes). |
|
|
98
98
|
| `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
|
|
99
|
-
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals
|
|
99
|
+
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals) |
|
|
100
100
|
| `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
|
|
101
101
|
| `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/define/areas#the-capability-floor-requires-feature-areas) |
|
|
102
102
|
| `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
|
|
@@ -119,17 +119,16 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
119
119
|
| `dev` | `object` | Local development settings (`port`, `api`, `cms`, `account`, `hostnames`) — see [Variables](/configure/variables) |
|
|
120
120
|
| `preset` | `string` | Inherit defaults from a named preset |
|
|
121
121
|
|
|
122
|
-
## Public contract
|
|
122
|
+
## Public contract routes
|
|
123
123
|
|
|
124
|
-
|
|
125
|
-
`
|
|
126
|
-
`routes: "v2"` to move the URLs:
|
|
124
|
+
`contract.routes` selects the URL prefix and nothing else. It defaults to
|
|
125
|
+
`"v1"`; set `"v2"` to move the URLs:
|
|
127
126
|
|
|
128
127
|
```typescript
|
|
129
128
|
export default defineConfig({
|
|
130
129
|
name: "my-app",
|
|
131
130
|
template: "hono",
|
|
132
|
-
contract: {
|
|
131
|
+
contract: { routes: "v2" },
|
|
133
132
|
providers: cloudflare({}),
|
|
134
133
|
});
|
|
135
134
|
```
|
|
@@ -141,8 +140,12 @@ and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
|
|
|
141
140
|
bakes those paths into the SPA build and injects them at runtime. Quickback
|
|
142
141
|
does not expose a mixed v1/v2 URL surface from one compiled Worker.
|
|
143
142
|
|
|
144
|
-
|
|
145
|
-
|
|
143
|
+
`contract.version` is retired — there is one standard API shape. Pinning it is
|
|
144
|
+
a compile error; delete that line and keep `routes`. See
|
|
145
|
+
[API Contract](/platform/api-contract#contractversion-is-retired) for what
|
|
146
|
+
changes if you were pinned to `version: "v1"`.
|
|
147
|
+
|
|
148
|
+
Action input-schema fidelity is a compile gate since v0.63.0. The CLI must
|
|
146
149
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
147
150
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
148
151
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -151,26 +154,13 @@ ancestor installs, so an isolated `quickback/` definition tree can use a
|
|
|
151
154
|
sibling `src/` runtime without a workspace-root symlink. The compiler enforces
|
|
152
155
|
the same invariant at its shared input boundary, including
|
|
153
156
|
`POST /compile?complete=false`, so validation-only or raw API calls cannot
|
|
154
|
-
bypass it.
|
|
155
|
-
|
|
156
|
-
The version selection also moves the event and read surfaces:
|
|
157
|
-
|
|
158
|
-
| Surface | v1 (pinned) | v2 (flagship) |
|
|
159
|
-
|---|---|---|
|
|
160
|
-
| Realtime data frames (`/broadcast/*`) | raw frames, byte-stable | CloudEvents 1.0 envelopes at DO egress ([realtime](/platform/realtime)) |
|
|
161
|
-
| Outbound webhook signing | Standard Webhooks headers **plus** legacy `X-Webhook-*` | Standard Webhooks **only** |
|
|
162
|
-
| `?include=` FK-graph embedding | not available | available where a resource/view allowlists it |
|
|
163
|
-
| Bare `?fields=` / `fields[<fk>]=` unknown names | silent drop / n/a | 400 on both |
|
|
164
|
-
|
|
165
|
-
See [API Contract](/platform/api-contract) for the full v1 → v2 matrix and
|
|
166
|
-
migration sequencing.
|
|
157
|
+
bypass it.
|
|
167
158
|
|
|
168
|
-
## Delegated principals
|
|
159
|
+
## Delegated principals
|
|
169
160
|
|
|
170
161
|
`auth.principals` defines non-account authority such as an event pass or a
|
|
171
|
-
short-lived event session. It
|
|
162
|
+
short-lived event session. It requires both of:
|
|
172
163
|
|
|
173
|
-
- `contract: { version: "v2" }`
|
|
174
164
|
- the Cloudflare runtime
|
|
175
165
|
- Neon with `connectionMode: "hyperdrive"`
|
|
176
166
|
|
|
@@ -182,7 +172,6 @@ principal types cannot share a scheme.
|
|
|
182
172
|
export default defineConfig({
|
|
183
173
|
name: "attend-v2",
|
|
184
174
|
template: "hono",
|
|
185
|
-
contract: { version: "v2" },
|
|
186
175
|
auth: {
|
|
187
176
|
principals: {
|
|
188
177
|
event_pass: {
|
|
@@ -500,7 +489,7 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
500
489
|
When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
|
|
501
490
|
|
|
502
491
|
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
-
when `contract.routes` is `"v2"` (the URL axis —
|
|
492
|
+
when `contract.routes` is `"v2"` (the URL axis — the standard shape does
|
|
504
493
|
not move these)
|
|
505
494
|
- `/storage/*` — R2 file storage
|
|
506
495
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
@@ -215,7 +215,7 @@ providers: {
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`.
|
|
218
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. The path is the only thing `routes` moves — frame format is unaffected.
|
|
219
219
|
|
|
220
220
|
`wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
|
|
221
221
|
|
|
@@ -83,7 +83,7 @@ Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
|
|
|
83
83
|
evaluates project code. The output contract feeds OpenAPI and
|
|
84
84
|
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
85
85
|
|
|
86
|
-
**Every action input must produce a schema
|
|
86
|
+
**Every action input must produce a schema.** Since
|
|
87
87
|
v0.63.0 a failed harvest fails the compile, naming the exact action, whether
|
|
88
88
|
bundling or evaluation failed, and the underlying local error. Output remains
|
|
89
89
|
optional.
|
|
@@ -160,7 +160,7 @@ see [Error Handling](/api/actions#error-handling) for what actually happens.
|
|
|
160
160
|
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
161
161
|
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
162
162
|
those segments to the OpenAPI `{param}` form before applying the schema, so
|
|
163
|
-
|
|
163
|
+
completeness uses the same route key as the emitted OpenAPI and MCP
|
|
164
164
|
surfaces. The same normalization applies when a record resource path contains
|
|
165
165
|
namespace parameters.
|
|
166
166
|
|
|
@@ -138,7 +138,7 @@ single-record endpoint (`POST /:id/{action}`) or write a standalone action.
|
|
|
138
138
|
|
|
139
139
|
The generated OpenAPI document and MCP tools reuse that exact action schema
|
|
140
140
|
in both places: as the single-record request body and as the bulk wrapper's
|
|
141
|
-
nested `input` property.
|
|
141
|
+
nested `input` property. Quickback considers the action's
|
|
142
142
|
schema harvest complete only after both operations are patched. This also
|
|
143
143
|
holds when the table filename and declared table name use different casing or
|
|
144
144
|
separators (for example, `event-guests.ts` exporting `event_guests`); the
|
|
@@ -32,7 +32,7 @@ async execute({ db, ctx, input }) {
|
|
|
32
32
|
|
|
33
33
|
### Delegated principals and `databaseAccess`
|
|
34
34
|
|
|
35
|
-
On a
|
|
35
|
+
On a Cloudflare + Neon Hyperdrive project, an action can admit a
|
|
36
36
|
configured delegated principal with `access.principals`:
|
|
37
37
|
|
|
38
38
|
```typescript
|
|
@@ -7,12 +7,11 @@ compiler was missing — which relations are **compositions** (owned by this
|
|
|
7
7
|
root) vs **references** (independent entities) — and the compiler generates
|
|
8
8
|
the whole write path.
|
|
9
9
|
|
|
10
|
-
Changesets are a **contract v2** capability (`contract: { version: "v2" }`).
|
|
11
10
|
Declaring `owns` on a v1-pinned project is a compile error.
|
|
12
11
|
|
|
13
12
|
## Declaring the boundary — `owns`
|
|
14
13
|
|
|
15
|
-
{/* doc-compile: skip —
|
|
14
|
+
{/* doc-compile: skip — the fence is the `owns` boundary only: columns/firewall/guards/masking/read are elided, and it names three sibling tables (`tasks`, `people`, `taskChecklistItems`) it deliberately does not repeat. */}
|
|
16
15
|
```ts title="quickback/features/projects/projects.ts"
|
|
17
16
|
export default feature("projects", {
|
|
18
17
|
// ...columns, firewall, guards, masking, read...
|
|
@@ -70,9 +69,9 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
69
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
70
|
have. No subpath.
|
|
72
71
|
|
|
73
|
-
Paths below use the default `/api/v1` prefix. Changesets are a
|
|
72
|
+
Paths below use the default `/api/v1` prefix. Changesets are a
|
|
74
73
|
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
-
moving your URLs — set [`contract.routes`](/platform/api-contract#
|
|
74
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#one-axis-routes)
|
|
76
75
|
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
76
|
|
|
78
77
|
- `PATCH /api/v1/<resource>/:id` with
|
|
@@ -212,7 +211,7 @@ stamping (`createdBy` / `modifiedBy`) rides the same chokepoint. The only gap is
|
|
|
212
211
|
`afterDelete`, which the soft-delete stamp can't see — identical to the plain
|
|
213
212
|
DELETE route's own limitation. (`sql:` triggers fire on every path regardless,
|
|
214
213
|
as always.) This is the parity the trigger docs promise: a generated
|
|
215
|
-
|
|
214
|
+
changeset is a compiler write surface, not one of the
|
|
216
215
|
queue/cron/raw-SQL bypasses that skip handler hooks.
|
|
217
216
|
|
|
218
217
|
Compile-time, fail-closed (everything throws, nothing normalizes silently):
|
|
@@ -244,7 +243,7 @@ Compile-time, fail-closed (everything throws, nothing normalizes silently):
|
|
|
244
243
|
the wire parser reserves those payload keys, so such a relation would be
|
|
245
244
|
silently unreachable on the wire.
|
|
246
245
|
- One aggregate root per table, acyclic graph, bounded depth, declared child
|
|
247
|
-
ops only, soft-delete children only
|
|
246
|
+
ops only, soft-delete children only.
|
|
248
247
|
|
|
249
248
|
## `afterCommit` — emit a realtime signal after the changeset commits
|
|
250
249
|
|
|
@@ -255,7 +254,7 @@ strictly **after** the transaction commits, riding the existing
|
|
|
255
254
|
[named-invalidation / Broadcaster egress](/platform/realtime/named-invalidations)
|
|
256
255
|
(so it inherits the CloudEvents envelope + AsyncAPI description for free).
|
|
257
256
|
|
|
258
|
-
{/* doc-compile: skip — project-config
|
|
257
|
+
{/* doc-compile: skip — project-config prerequisite this fence cannot carry: the `broadcast` event `attendRealtime.mobileBundleChanged.travelUpdated` plus its `thisEvent` delivery profile must be declared in a realtime registry under `services/realtime/`. Columns/firewall/read/crud are elided to `// ...` and the owned child table is not repeated. */}
|
|
259
258
|
```ts title="quickback/features/travel/lodging-reservations.ts"
|
|
260
259
|
export default defineTable(lodgingReservations, {
|
|
261
260
|
// ...firewall / read / crud ...
|
|
@@ -423,7 +422,7 @@ authored actions delegate through when they still need residue logic
|
|
|
423
422
|
(preconditions, server-side transforms, notifications) around the aggregate
|
|
424
423
|
write:
|
|
425
424
|
|
|
426
|
-
{/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a
|
|
425
|
+
{/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a root that declares `owns`, which this fence does not carry, so the import cannot resolve. `description` / `input` / `access` are elided to `// ...` on purpose — the point is the delegation seam. */}
|
|
427
426
|
```ts title="quickback/features/projects/actions/importBoard.ts"
|
|
428
427
|
// Action files are compiled into the feature directory, next to the
|
|
429
428
|
// generated module — the relative import resolves at runtime.
|
|
@@ -191,7 +191,6 @@ that row." It does **not** say who owns whom. When a set of child rows has no
|
|
|
191
191
|
lifecycle of its own — junction memberships, normalized phones/emails, line
|
|
192
192
|
items — declare the composition with `owns` on the root table:
|
|
193
193
|
|
|
194
|
-
{/* doc-compile: skip — project-config prerequisite: `owns` is a contract-v2 capability (the prose below says so) and needs `contract: { version: 'v2' }` in quickback.config.ts; the gate's harness config pins v1. The file is otherwise whole. */}
|
|
195
194
|
```ts
|
|
196
195
|
export default feature("projects", {
|
|
197
196
|
columns: {
|
|
@@ -233,7 +233,7 @@ export default defineTable(balanceSnapshots, {
|
|
|
233
233
|
|
|
234
234
|
## Aggregate Reads
|
|
235
235
|
|
|
236
|
-
Reading a parent **with** its owned relations rides
|
|
236
|
+
Reading a parent **with** its owned relations rides `?include=`,
|
|
237
237
|
which accepts two kinds of tokens in the same `read.include` allowlist:
|
|
238
238
|
|
|
239
239
|
- **FK columns** (`?include=vendorId`) — forward embeds: the target rows the
|
|
@@ -242,7 +242,7 @@ which accepts two kinds of tokens in the same `read.include` allowlist:
|
|
|
242
242
|
reader: the changeset root's owned **child rows**, pivoting on the root PK
|
|
243
243
|
and matching the child's declared `fk` column.
|
|
244
244
|
|
|
245
|
-
{/* doc-compile: skip —
|
|
245
|
+
{/* doc-compile: skip — the fence names a `noteReactions` child table it deliberately does not repeat. */}
|
|
246
246
|
```typescript
|
|
247
247
|
export default defineTable(notes, {
|
|
248
248
|
owns: { reactions: { table: 'noteReactions', fk: 'noteId' } },
|
|
@@ -269,7 +269,7 @@ When the passkey plugin is enabled, `/reveal` verifies a WebAuthn assertion whos
|
|
|
269
269
|
| Field | Value |
|
|
270
270
|
|---|---|
|
|
271
271
|
| `challenge` | the `/challenge` `nonce` **as the base64url string** (the client signs the b64url text, the server passes `expectedChallenge = nonce`) |
|
|
272
|
-
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the host of `env.ACCOUNT_URL
|
|
272
|
+
| `rpID` | the passkey plugin's `rpID` — i.e. `crossSubDomainCookies.domain` (leading dot stripped) when configured, else the registrable host of `env.ACCOUNT_URL`, else the compile-time account origin (both emissions share one resolution, so they cannot skew) |
|
|
273
273
|
| `userVerification` | **required** (`requireUserVerification: true` — a reveal is a deliberate re-auth) |
|
|
274
274
|
| origin | the resolved account origin (mirrors the `passkey({ rpID, origin })` plugin) |
|
|
275
275
|
|
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
# API Contract
|
|
2
2
|
|
|
3
|
-
Every generated API speaks one public HTTP contract
|
|
3
|
+
Every generated API speaks **one** public HTTP contract. There is no version to
|
|
4
|
+
select: the behavior on this page is what every project gets.
|
|
5
|
+
|
|
6
|
+
The only contract choice is the URL prefix, and it defaults to `/api/v1` so
|
|
7
|
+
existing clients keep the address they already call:
|
|
4
8
|
|
|
5
9
|
```ts title="quickback/quickback.config.ts"
|
|
6
10
|
export default defineConfig({
|
|
7
|
-
|
|
8
|
-
contract: { version: "v2" },
|
|
11
|
+
contract: { routes: "v2" }, // optional — serve on /api/v2 instead
|
|
9
12
|
// ...
|
|
10
13
|
});
|
|
11
14
|
```
|
|
12
15
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
receives no new contract features until it migrates. Your URLs are a separate
|
|
16
|
-
choice — see [below](#two-axes-semantics-and-routes).
|
|
16
|
+
`contract.version` is retired and pinning it is a compile error — see
|
|
17
|
+
[below](#contractversion-is-retired).
|
|
17
18
|
|
|
18
19
|
## Response envelope
|
|
19
20
|
|
|
@@ -29,8 +30,8 @@ object itself:
|
|
|
29
30
|
}
|
|
30
31
|
```
|
|
31
32
|
|
|
32
|
-
`included` appears only when the request carried `?include=`
|
|
33
|
-
|
|
33
|
+
`included` appears only when the request carried `?include=` — see
|
|
34
|
+
[query params](/api/query-params).
|
|
34
35
|
|
|
35
36
|
## Errors — RFC 9457 Problem Details
|
|
36
37
|
|
|
@@ -112,59 +113,68 @@ export default defineAction({
|
|
|
112
113
|
});
|
|
113
114
|
```
|
|
114
115
|
|
|
115
|
-
##
|
|
116
|
+
## One axis: routes
|
|
116
117
|
|
|
117
|
-
`contract` has
|
|
118
|
-
mistake:
|
|
118
|
+
`contract` has a single key. It selects the URL prefix and nothing else.
|
|
119
119
|
|
|
120
120
|
| Key | Controls | Default |
|
|
121
121
|
|---|---|---|
|
|
122
|
-
| `version` | Semantics — framing, strictness, the auth lane | `'v2'` |
|
|
123
122
|
| `routes` | The URL prefix, and nothing else | `'v1'` |
|
|
124
123
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
does not change your semantics.
|
|
124
|
+
A project with no `contract` block serves `/api/v1`. Set `routes: "v2"` to
|
|
125
|
+
serve `/api/v2` instead — the behavior is identical either way.
|
|
128
126
|
|
|
129
127
|
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
130
128
|
```typescript
|
|
131
|
-
contract: {
|
|
132
|
-
contract: { routes: "v2" } // serve on /api/v2, keep v1 semantics
|
|
133
|
-
contract: { version: "v2", routes: "v2" } // both — the pre-v0.64.0 "v2"
|
|
129
|
+
contract: { routes: "v2" } // serve on /api/v2 instead of /api/v1
|
|
134
130
|
```
|
|
135
131
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
132
|
+
### `contract.version` is retired
|
|
133
|
+
|
|
134
|
+
There is one standard API shape, so there is nothing to select. Pinning
|
|
135
|
+
`contract.version` is a compile error.
|
|
139
136
|
|
|
140
|
-
**
|
|
141
|
-
|
|
142
|
-
key is the only pin.
|
|
137
|
+
**Delete that one line and keep `routes` if you have it.** `routes` is the
|
|
138
|
+
surviving axis and controls your URLs — removing it would move them.
|
|
143
139
|
|
|
144
|
-
|
|
140
|
+
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
141
|
+
```typescript
|
|
142
|
+
contract: { version: "v2", routes: "v1" } // before
|
|
143
|
+
contract: { routes: "v1" } // after — same URLs, same behavior
|
|
144
|
+
```
|
|
145
145
|
|
|
146
|
-
`version`
|
|
147
|
-
|
|
146
|
+
Deleting `version: "v2"` changes nothing: it selected what is now simply the
|
|
147
|
+
standard shape. Deleting `version: "v1"` is a real migration — that pin opted
|
|
148
|
+
out of four behaviors that are now unconditional:
|
|
148
149
|
|
|
149
|
-
| Surface | v1
|
|
150
|
+
| Surface | What `version: "v1"` did | What you get now |
|
|
150
151
|
|---|---|---|
|
|
151
|
-
| API base | `/api/v1` | `/api/v2` |
|
|
152
|
-
| Auth base | `/auth/v1` | `/auth/v2` |
|
|
153
|
-
| Realtime base | `/broadcast/v1` | `/broadcast/v2` |
|
|
154
152
|
| Quickback HMAC-JWT lane | on by default | only with explicit `auth.jwt` |
|
|
155
153
|
| Realtime data frames | raw (byte-stable) | CloudEvents 1.0 envelopes ([realtime](/platform/realtime)) |
|
|
156
154
|
| Outbound webhook signing | Standard Webhooks **+** legacy `X-Webhook-*` | Standard Webhooks **only** |
|
|
157
|
-
| `?include=` FK embedding | not available | available where allowlisted |
|
|
158
|
-
| Aggregate changesets (`application/vnd.quickback.changeset+json` on PATCH/POST, [`owns`](/define/changesets)) | not available | available where `owns` is declared |
|
|
159
155
|
| Bare `?fields=` unknown names | silently dropped | **400** |
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
156
|
+
|
|
157
|
+
Features that a v1 pin refused are now always available: `?include=` FK
|
|
158
|
+
embedding where allowlisted, aggregate changesets on PATCH/POST where
|
|
159
|
+
[`owns`](/define/changesets) is declared, `fields[<fk>]=` projection (unknown
|
|
160
|
+
names **400**), `auth.principals`, and `atomicAuthRoutes: 'emailOtpSignIn'`.
|
|
161
|
+
|
|
162
|
+
Migrating off a v1 pin: ship subscribers that parse CloudEvents frames, move
|
|
163
|
+
webhook consumers onto the `webhook-*` headers, and either adopt session-first
|
|
164
|
+
auth or declare `auth.jwt`.
|
|
165
|
+
|
|
166
|
+
**Pinning your CLI version does not pin behavior.** The compiler is a hosted
|
|
167
|
+
service, so an older CLI gets the same output.
|
|
168
|
+
|
|
169
|
+
### Base paths
|
|
170
|
+
|
|
171
|
+
`routes` moves all three together:
|
|
172
|
+
|
|
173
|
+
| Surface | `routes: "v1"` (default) | `routes: "v2"` |
|
|
174
|
+
|---|---|---|
|
|
175
|
+
| API base | `/api/v1` | `/api/v2` |
|
|
176
|
+
| Auth base | `/auth/v1` | `/auth/v2` |
|
|
177
|
+
| Realtime base | `/broadcast/v1` | `/broadcast/v2` |
|
|
168
178
|
|
|
169
179
|
## Machine-readable contract
|
|
170
180
|
|
|
@@ -51,7 +51,7 @@ auth: {
|
|
|
51
51
|
|
|
52
52
|
> **This surface is opt-in by default**
|
|
53
53
|
>
|
|
54
|
-
>
|
|
54
|
+
> The custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. A project that declares `authz.scopes` does **not** need `auth.jwt`: it gets scope-token admission on its own, without the token endpoint or the identity fast-path. Declaring `auth.jwt` is what opts into the full credential lane. See [Auth & JWT config](/configure/auth).
|
|
55
55
|
>
|
|
56
56
|
> `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
|
|
57
57
|
|
|
@@ -193,8 +193,15 @@ auth: defineAuth("better-auth", {
|
|
|
193
193
|
}),
|
|
194
194
|
```
|
|
195
195
|
|
|
196
|
-
**
|
|
197
|
-
|
|
196
|
+
**Relying party resolution:**
|
|
197
|
+
|
|
198
|
+
WebAuthn needs a relying party ID and origin. The generated plugin resolves them in this order:
|
|
199
|
+
|
|
200
|
+
1. `advanced.crossSubDomainCookies.domain` (leading dot stripped) becomes the `rpID` when configured — credentials then work across sibling subdomains.
|
|
201
|
+
2. The `ACCOUNT_URL` env var, when set on the deploy target: `rpID` is its registrable hostname (`account.example.com` → `example.com`; a two-label host like `example.com` is kept whole) and the origin is its **bare origin** — a path suffix such as `/account` is dropped, so the same variable can keep serving as the email link base.
|
|
202
|
+
3. The compile-time account origin — `account.domain` when configured, else the project's unified host. Baked automatically; no env var required.
|
|
203
|
+
|
|
204
|
+
`rpID: 'localhost'` applies only when the project has no configured domain at all (pure local dev). If passkey registration returns 500 on a deployed worker, check that one of the three sources above resolves to the hostname the Account UI is actually served from.
|
|
198
205
|
|
|
199
206
|
**Endpoints:**
|
|
200
207
|
- `POST /auth/v1/passkey/register/options` - Get registration challenge
|
|
@@ -504,7 +504,7 @@ with neither a stamped user id nor a delegated principal) and a `service_role`
|
|
|
504
504
|
policy (admits Worker-internal contexts — see
|
|
505
505
|
[Background jobs and cross-tenant actions](#background-jobs-and-cross-tenant-actions)).
|
|
506
506
|
|
|
507
|
-
### Delegated principal RLS
|
|
507
|
+
### Delegated principal RLS
|
|
508
508
|
|
|
509
509
|
Delegated principals require Cloudflare + Neon Hyperdrive. Their proof hook
|
|
510
510
|
returns only a digest and receives no database handle. Quickback then runs one
|