@quickback-dev/cli 0.63.0 → 0.64.1
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/index.js +1 -1
- package/dist/skill/docs/changelog/index.md +76 -4
- package/dist/skill/docs/configure/auth.md +7 -5
- package/dist/skill/docs/configure/index.md +17 -16
- package/dist/skill/docs/configure/providers.md +1 -1
- package/dist/skill/docs/define/changesets.md +8 -3
- package/dist/skill/docs/platform/api-contract/index.md +33 -20
- package/dist/skill/docs/platform/auth/jwt-optimization.md +4 -2
- package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/dist/skill/docs/platform/realtime/index.md +1 -1
- package/dist/skill/docs/platform/realtime/live-views.md +1 -1
- package/dist/skill/docs/platform/realtime/named-invalidations.md +1 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +1 -1
- package/dist/skill/docs/tooling/output.md +3 -2
- package/dist/skill/docs/ui/admin/connecting.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/changelog/index.md +76 -4
- package/src/skill/docs/configure/auth.md +7 -5
- package/src/skill/docs/configure/index.md +17 -16
- package/src/skill/docs/configure/providers.md +1 -1
- package/src/skill/docs/define/changesets.md +8 -3
- package/src/skill/docs/platform/api-contract/index.md +33 -20
- package/src/skill/docs/platform/auth/jwt-optimization.md +4 -2
- package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/src/skill/docs/platform/realtime/index.md +1 -1
- package/src/skill/docs/platform/realtime/live-views.md +1 -1
- package/src/skill/docs/platform/realtime/named-invalidations.md +1 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +1 -1
- package/src/skill/docs/tooling/output.md +3 -2
- package/src/skill/docs/ui/admin/connecting.md +1 -1
package/dist/index.js
CHANGED
|
@@ -8,6 +8,76 @@ 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
|
+
## v0.64.0 — August 15, 2026
|
|
12
|
+
|
|
13
|
+
### `contract.version` defaults to v2 — and no longer moves your URLs
|
|
14
|
+
|
|
15
|
+
**Semantics and routes are now independent axes.**
|
|
16
|
+
|
|
17
|
+
| Key | Controls | Default |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `version` | Framing, strictness, the auth lane | `'v2'` |
|
|
20
|
+
| `routes` | The URL prefix, nothing else | `'v1'` |
|
|
21
|
+
|
|
22
|
+
A project with no `contract` block runs the **v2 contract on `/api/v1`**. You
|
|
23
|
+
inherit the flagship semantics; your clients keep calling the address they
|
|
24
|
+
already call.
|
|
25
|
+
|
|
26
|
+
Previously these were one knob: `version: 'v2'` moved `/api`, `/auth`, and
|
|
27
|
+
`/broadcast` to `/v2` as a side effect of selecting v2 behavior. That coupling
|
|
28
|
+
made the better contract expensive to adopt for the wrong reason — a URL
|
|
29
|
+
migration nobody asked for.
|
|
30
|
+
|
|
31
|
+
**Breaking — action required if you pinned `version: 'v2'` for the URLs.**
|
|
32
|
+
Add `routes: 'v2'` to keep serving `/api/v2`:
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
contract: { version: "v2", routes: "v2" }
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Without it, a previously-v2 project moves back to `/api/v1` on its next
|
|
39
|
+
compile. Semantics are unaffected either way.
|
|
40
|
+
|
|
41
|
+
### What the v2 default changes on the wire
|
|
42
|
+
|
|
43
|
+
URLs do not move. These do:
|
|
44
|
+
|
|
45
|
+
- Realtime frames become CloudEvents 1.0 envelopes. The largest change — every
|
|
46
|
+
subscriber re-parses. Routing info moves to `type`, payload to `data`.
|
|
47
|
+
- Outbound webhooks are signed Standard-Webhooks-only; the legacy
|
|
48
|
+
`X-Webhook-*` headers stop being sent. v1 already sent **both** sets, so
|
|
49
|
+
consumers can migrate to `webhook-signature` before upgrading and the flip
|
|
50
|
+
becomes a no-op for them.
|
|
51
|
+
- Unknown `?fields=` names return `400` instead of being silently dropped.
|
|
52
|
+
- The Quickback HMAC-JWT lane is off unless `auth.jwt` is declared.
|
|
53
|
+
- `?include=`, aggregate changesets (`owns`), and delegated principals become
|
|
54
|
+
available without a pin.
|
|
55
|
+
|
|
56
|
+
Pin `contract: { version: "v1" }` to opt out. Every compile that leaves
|
|
57
|
+
`contract.version` unset warns once, naming what changed.
|
|
58
|
+
|
|
59
|
+
### Action-schema harvest no longer keys on contract version
|
|
60
|
+
|
|
61
|
+
`assertCompleteActionInputSchemas` fired whenever the contract was v2 and any
|
|
62
|
+
harvested schema was absent. With v2 as the default that would have failed
|
|
63
|
+
every [Start](https://start.quickback.dev) project containing an action —
|
|
64
|
+
`rawFiles` callers post project source and never execute action code, so they
|
|
65
|
+
cannot harvest at all.
|
|
66
|
+
|
|
67
|
+
The gate now fires only on a **partial** payload: some schemas supplied,
|
|
68
|
+
others missing. Callers that supply none get the coverage warning instead. The
|
|
69
|
+
CLI has failed closed on its own since v0.63.0, with the local per-action
|
|
70
|
+
reason the compiler cannot know.
|
|
71
|
+
|
|
72
|
+
### Fixes
|
|
73
|
+
|
|
74
|
+
- CloudEvents framing was derived from `broadcastBase.endsWith('/v2')`. Once
|
|
75
|
+
routes and semantics decoupled, that silently reverted every default project
|
|
76
|
+
to raw v1 frames. Framing is now passed explicitly.
|
|
77
|
+
- The bundled CMS/Account SPAs gated their base-path override on *semantics*
|
|
78
|
+
when it is a *routes* concern, emitting a redundant `/api/v1` override for
|
|
79
|
+
every new project.
|
|
80
|
+
|
|
11
81
|
## v0.63.0 — August 14, 2026
|
|
12
82
|
|
|
13
83
|
### Action input schemas now fail the compile instead of degrading
|
|
@@ -39,12 +109,14 @@ total lost `required`, with sampled paths.
|
|
|
39
109
|
### `contract.version` default flips to v2 in v0.64.0
|
|
40
110
|
|
|
41
111
|
An unset `contract.version` resolves to `'v1'` today. That default becomes
|
|
42
|
-
`'v2'` in **v0.64.0
|
|
43
|
-
`/broadcast`), switches realtime frames to CloudEvents 1.0 envelopes, drops the
|
|
44
|
-
legacy `X-Webhook-*` signing headers, and disables the Quickback HMAC-JWT lane
|
|
45
|
-
unless `auth.jwt` is declared. See the
|
|
112
|
+
`'v2'` in **v0.64.0**. See the
|
|
46
113
|
[contract matrix](/platform/api-contract#contract-version-matrix).
|
|
47
114
|
|
|
115
|
+
> v0.64.0 shipped this **without** moving any URLs — semantics and routes became
|
|
116
|
+
> independent axes, so `/api/v1` stays put. This entry originally said the flip
|
|
117
|
+
> would move `/api/v1` → `/api/v2`; that is not what happened.
|
|
118
|
+
|
|
119
|
+
|
|
48
120
|
Every compile that leaves `contract.version` unset now warns. Pin
|
|
49
121
|
`contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
|
|
50
122
|
now.
|
|
@@ -24,12 +24,14 @@ 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
|
-
> **
|
|
27
|
+
> **This JWT surface is opt-in by default**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
> when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
-
> `/api/
|
|
32
|
-
>
|
|
29
|
+
> Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
|
|
30
|
+
> JWT surface only when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
+
> has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
|
|
32
|
+
> fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
|
|
33
|
+
> the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
|
|
34
|
+
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
33
35
|
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
34
36
|
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
35
37
|
> available.
|
|
@@ -94,7 +94,7 @@ 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` | `{ version?: "v1" \| "v2" }` |
|
|
97
|
+
| `contract` | `{ version?: "v1" \| "v2", routes?: "v1" \| "v2" }` | Two independent axes. `version` selects SEMANTICS (default `"v2"`); `routes` selects the URL prefix (default `"v1"`). See [API Contract](/platform/api-contract#two-axes-semantics-and-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
99
|
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
|
|
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 |
|
|
@@ -121,28 +121,28 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
121
121
|
|
|
122
122
|
## Public contract version
|
|
123
123
|
|
|
124
|
-
Quickback
|
|
125
|
-
|
|
124
|
+
Quickback runs the **v2 contract on `/api/v1` by default** — `version` and
|
|
125
|
+
`routes` are independent. Pin `version: "v1"` to opt out of v2 semantics; set
|
|
126
|
+
`routes: "v2"` to move the URLs:
|
|
126
127
|
|
|
127
128
|
```typescript
|
|
128
129
|
export default defineConfig({
|
|
129
130
|
name: "my-app",
|
|
130
131
|
template: "hono",
|
|
131
|
-
contract: { version: "v2" },
|
|
132
|
+
contract: { version: "v2", routes: "v2" },
|
|
132
133
|
providers: cloudflare({}),
|
|
133
134
|
});
|
|
134
135
|
```
|
|
135
136
|
|
|
136
|
-
|
|
137
|
-
to `/auth/v2/*`,
|
|
138
|
-
`llms.txt`, schema/embeddings routes,
|
|
139
|
-
|
|
140
|
-
those paths into the SPA build and injects them at runtime
|
|
141
|
-
|
|
142
|
-
does not expose a mixed v1/v2 surface from one compiled Worker. Omitting
|
|
143
|
-
`contract` remains byte-compatible with v1 projects.
|
|
137
|
+
`routes` is atomic across every surface: feature routes move to `/api/v2/*`,
|
|
138
|
+
Better Auth to `/auth/v2/*`, realtime to `/broadcast/v2`, and generated
|
|
139
|
+
OpenAPI, MCP tool calls, OAuth discovery, `llms.txt`, schema/embeddings routes,
|
|
140
|
+
and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
|
|
141
|
+
bakes those paths into the SPA build and injects them at runtime. Quickback
|
|
142
|
+
does not expose a mixed v1/v2 URL surface from one compiled Worker.
|
|
144
143
|
|
|
145
|
-
|
|
144
|
+
Action input-schema fidelity is a compile gate on **every** contract version
|
|
145
|
+
since v0.63.0, not just v2. The CLI must
|
|
146
146
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
147
147
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
148
148
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
499
499
|
|
|
500
500
|
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
501
|
|
|
502
|
-
- `/api/v1/*` and `/auth/v1/*`
|
|
503
|
-
|
|
502
|
+
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
+
when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
|
|
504
|
+
not move these)
|
|
504
505
|
- `/storage/*` — R2 file storage
|
|
505
506
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
506
507
|
- `/account/*`, `/cms/*` — bundled SPAs (when enabled)
|
|
507
|
-
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.
|
|
508
|
+
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
|
|
508
509
|
|
|
509
510
|
The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
|
|
510
511
|
|
|
@@ -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.
|
|
218
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
|
|
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
|
|
|
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
70
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
71
|
have. No subpath.
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
|
|
74
|
+
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
|
|
76
|
+
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
|
+
|
|
78
|
+
- `PATCH /api/v1/<resource>/:id` with
|
|
74
79
|
`Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
|
|
75
80
|
to an existing root. Plain `application/json` keeps the flat-column PATCH.
|
|
76
|
-
- `POST /api/
|
|
81
|
+
- `POST /api/v1/<resource>` with the same media type — create the root and its
|
|
77
82
|
children in one changeset.
|
|
78
83
|
|
|
79
84
|
```jsonc
|
|
80
|
-
// PATCH /api/
|
|
85
|
+
// PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
|
|
81
86
|
{
|
|
82
87
|
"patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
|
|
83
88
|
"tasks": {
|
|
@@ -4,15 +4,16 @@ Every generated API speaks one public HTTP contract, selected once per project:
|
|
|
4
4
|
|
|
5
5
|
```ts title="quickback/quickback.config.ts"
|
|
6
6
|
export default defineConfig({
|
|
7
|
-
// Omitted =
|
|
7
|
+
// Omitted = v2 semantics on /api/v1. Pin "v1" to opt out.
|
|
8
8
|
contract: { version: "v2" },
|
|
9
9
|
// ...
|
|
10
10
|
});
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
**v2 is the flagship contract
|
|
14
|
-
v1
|
|
15
|
-
|
|
13
|
+
**v2 is the flagship contract, and the default since v0.64.0.** Everything new
|
|
14
|
+
lands on v2; a project pinned to v1 keeps the byte-stable legacy wire and
|
|
15
|
+
receives no new contract features until it migrates. Your URLs are a separate
|
|
16
|
+
choice — see [below](#two-axes-semantics-and-routes).
|
|
16
17
|
|
|
17
18
|
## Response envelope
|
|
18
19
|
|
|
@@ -111,28 +112,39 @@ export default defineAction({
|
|
|
111
112
|
});
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
##
|
|
115
|
+
## Two axes: semantics and routes
|
|
115
116
|
|
|
116
|
-
`contract
|
|
117
|
-
|
|
118
|
-
moves the entire matrix below on its next compile after that release.
|
|
117
|
+
`contract` has two independent keys, and conflating them is the most common
|
|
118
|
+
mistake:
|
|
119
119
|
|
|
120
|
-
|
|
120
|
+
| Key | Controls | Default |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `version` | Semantics — framing, strictness, the auth lane | `'v2'` |
|
|
123
|
+
| `routes` | The URL prefix, and nothing else | `'v1'` |
|
|
124
|
+
|
|
125
|
+
So a project with no `contract` block **runs the v2 contract on `/api/v1`.**
|
|
126
|
+
Taking the flagship semantics does not move your URLs, and moving your URLs
|
|
127
|
+
does not change your semantics.
|
|
121
128
|
|
|
129
|
+
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
122
130
|
```typescript
|
|
123
|
-
{
|
|
124
|
-
contract: {
|
|
131
|
+
contract: { version: "v1" } // opt out of v2 semantics
|
|
132
|
+
contract: { routes: "v2" } // serve on /api/v2, keep v1 semantics
|
|
133
|
+
contract: { version: "v2", routes: "v2" } // both — the pre-v0.64.0 "v2"
|
|
125
134
|
```
|
|
126
135
|
|
|
136
|
+
**This changed in v0.64.0.** Before it, `version: 'v2'` moved the URLs too, and
|
|
137
|
+
the default was `'v1'` on both axes. A project that pinned `version: 'v2'` to
|
|
138
|
+
get `/api/v2` must now add `routes: 'v2'` to keep those URLs.
|
|
139
|
+
|
|
127
140
|
**Pinning your CLI version does not pin the contract.** The default lives in the
|
|
128
|
-
compiler, which is a hosted service — an older CLI inherits
|
|
129
|
-
|
|
130
|
-
`contract.version` unset.
|
|
141
|
+
compiler, which is a hosted service — an older CLI inherits it too. The config
|
|
142
|
+
key is the only pin.
|
|
131
143
|
|
|
132
144
|
## Contract version matrix
|
|
133
145
|
|
|
134
|
-
|
|
135
|
-
|
|
146
|
+
`version` moves everything in this table except the three base paths, which
|
|
147
|
+
follow `routes`:
|
|
136
148
|
|
|
137
149
|
| Surface | v1 (pinned) | v2 (flagship) |
|
|
138
150
|
|---|---|---|
|
|
@@ -148,10 +160,11 @@ client migration as one move:
|
|
|
148
160
|
| `fields[<fk>]=` unknown names | n/a | **400** |
|
|
149
161
|
| Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
|
|
150
162
|
|
|
151
|
-
Sequencing a migration:
|
|
152
|
-
|
|
153
|
-
consumers
|
|
154
|
-
|
|
163
|
+
Sequencing a migration: the URL row is the only one you can defer with
|
|
164
|
+
`routes`. For the rest — ship subscribers that parse CloudEvents frames, move
|
|
165
|
+
webhook consumers onto the `webhook-*` headers (v1 already sends **both** sets,
|
|
166
|
+
so that step needs no coordination), and either adopt session-first auth or
|
|
167
|
+
declare `auth.jwt`. Pin `version: "v1"` while that work lands.
|
|
155
168
|
|
|
156
169
|
## Machine-readable contract
|
|
157
170
|
|
|
@@ -49,9 +49,11 @@ auth: {
|
|
|
49
49
|
},
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
> **
|
|
52
|
+
> **This surface is opt-in by default**
|
|
53
53
|
>
|
|
54
|
-
>
|
|
54
|
+
> Contract v2 is the default since v0.64.0, and on it 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. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
|
|
55
|
+
>
|
|
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.
|
|
55
57
|
|
|
56
58
|
|
|
57
59
|
---
|
|
@@ -79,7 +79,7 @@ providers: {
|
|
|
79
79
|
}
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.
|
|
82
|
+
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
|
|
83
83
|
|
|
84
84
|
### Namespace-backed tickets (per-matched-lane)
|
|
85
85
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.
|
|
5
|
+
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
|
|
6
6
|
- **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
|
|
7
7
|
|
|
8
8
|
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
|
|
|
157
157
|
Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
|
|
158
158
|
slips through the gap between reading the surface and the socket going live:
|
|
159
159
|
|
|
160
|
-
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket`
|
|
160
|
+
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
|
|
161
161
|
`{ view, rootId }`) — gated by exactly the same `read.access` + firewall
|
|
162
162
|
checks as the read endpoint — and opens a WebSocket scoped to
|
|
163
163
|
`view:<view>:<rootId>`.
|
|
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
|
|
|
125
125
|
|
|
126
126
|
## The wire frame
|
|
127
127
|
|
|
128
|
-
Clients receive a broadcast frame on `/broadcast/v{n}` (the
|
|
128
|
+
Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
|
|
129
129
|
|
|
130
130
|
```jsonc
|
|
131
131
|
{
|
|
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
|
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
10
|
const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
|
|
11
|
-
// Note: /broadcast/v1 tracks contract.
|
|
11
|
+
// Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Authentication
|
|
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
|
|
|
377
377
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
378
378
|
| `POST /{action}` | Standalone actions defined |
|
|
379
379
|
|
|
380
|
-
Routes are mounted under `/api/v1/{feature}`
|
|
381
|
-
`/api/v2/{feature}` when `contract: {
|
|
380
|
+
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
381
|
+
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
|
|
382
|
+
selects semantics and leaves these paths alone.
|
|
382
383
|
|
|
383
384
|
## Migrations
|
|
384
385
|
|
|
@@ -105,7 +105,7 @@ interface ListResult {
|
|
|
105
105
|
The client is constructed once from the resolved `apiUrl` and provided via React
|
|
106
106
|
context (`ApiClientContext`), available throughout the component tree. It reads
|
|
107
107
|
the Better Auth session cookie and calls the standard REST endpoints
|
|
108
|
-
(`/api/v1/{table}`, or `/api/v2/…`
|
|
108
|
+
(`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
|
|
109
109
|
|
|
110
110
|
## Embedded Mode (Recommended)
|
|
111
111
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.64.1",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -8,6 +8,76 @@ 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
|
+
## v0.64.0 — August 15, 2026
|
|
12
|
+
|
|
13
|
+
### `contract.version` defaults to v2 — and no longer moves your URLs
|
|
14
|
+
|
|
15
|
+
**Semantics and routes are now independent axes.**
|
|
16
|
+
|
|
17
|
+
| Key | Controls | Default |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `version` | Framing, strictness, the auth lane | `'v2'` |
|
|
20
|
+
| `routes` | The URL prefix, nothing else | `'v1'` |
|
|
21
|
+
|
|
22
|
+
A project with no `contract` block runs the **v2 contract on `/api/v1`**. You
|
|
23
|
+
inherit the flagship semantics; your clients keep calling the address they
|
|
24
|
+
already call.
|
|
25
|
+
|
|
26
|
+
Previously these were one knob: `version: 'v2'` moved `/api`, `/auth`, and
|
|
27
|
+
`/broadcast` to `/v2` as a side effect of selecting v2 behavior. That coupling
|
|
28
|
+
made the better contract expensive to adopt for the wrong reason — a URL
|
|
29
|
+
migration nobody asked for.
|
|
30
|
+
|
|
31
|
+
**Breaking — action required if you pinned `version: 'v2'` for the URLs.**
|
|
32
|
+
Add `routes: 'v2'` to keep serving `/api/v2`:
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
contract: { version: "v2", routes: "v2" }
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Without it, a previously-v2 project moves back to `/api/v1` on its next
|
|
39
|
+
compile. Semantics are unaffected either way.
|
|
40
|
+
|
|
41
|
+
### What the v2 default changes on the wire
|
|
42
|
+
|
|
43
|
+
URLs do not move. These do:
|
|
44
|
+
|
|
45
|
+
- Realtime frames become CloudEvents 1.0 envelopes. The largest change — every
|
|
46
|
+
subscriber re-parses. Routing info moves to `type`, payload to `data`.
|
|
47
|
+
- Outbound webhooks are signed Standard-Webhooks-only; the legacy
|
|
48
|
+
`X-Webhook-*` headers stop being sent. v1 already sent **both** sets, so
|
|
49
|
+
consumers can migrate to `webhook-signature` before upgrading and the flip
|
|
50
|
+
becomes a no-op for them.
|
|
51
|
+
- Unknown `?fields=` names return `400` instead of being silently dropped.
|
|
52
|
+
- The Quickback HMAC-JWT lane is off unless `auth.jwt` is declared.
|
|
53
|
+
- `?include=`, aggregate changesets (`owns`), and delegated principals become
|
|
54
|
+
available without a pin.
|
|
55
|
+
|
|
56
|
+
Pin `contract: { version: "v1" }` to opt out. Every compile that leaves
|
|
57
|
+
`contract.version` unset warns once, naming what changed.
|
|
58
|
+
|
|
59
|
+
### Action-schema harvest no longer keys on contract version
|
|
60
|
+
|
|
61
|
+
`assertCompleteActionInputSchemas` fired whenever the contract was v2 and any
|
|
62
|
+
harvested schema was absent. With v2 as the default that would have failed
|
|
63
|
+
every [Start](https://start.quickback.dev) project containing an action —
|
|
64
|
+
`rawFiles` callers post project source and never execute action code, so they
|
|
65
|
+
cannot harvest at all.
|
|
66
|
+
|
|
67
|
+
The gate now fires only on a **partial** payload: some schemas supplied,
|
|
68
|
+
others missing. Callers that supply none get the coverage warning instead. The
|
|
69
|
+
CLI has failed closed on its own since v0.63.0, with the local per-action
|
|
70
|
+
reason the compiler cannot know.
|
|
71
|
+
|
|
72
|
+
### Fixes
|
|
73
|
+
|
|
74
|
+
- CloudEvents framing was derived from `broadcastBase.endsWith('/v2')`. Once
|
|
75
|
+
routes and semantics decoupled, that silently reverted every default project
|
|
76
|
+
to raw v1 frames. Framing is now passed explicitly.
|
|
77
|
+
- The bundled CMS/Account SPAs gated their base-path override on *semantics*
|
|
78
|
+
when it is a *routes* concern, emitting a redundant `/api/v1` override for
|
|
79
|
+
every new project.
|
|
80
|
+
|
|
11
81
|
## v0.63.0 — August 14, 2026
|
|
12
82
|
|
|
13
83
|
### Action input schemas now fail the compile instead of degrading
|
|
@@ -39,12 +109,14 @@ total lost `required`, with sampled paths.
|
|
|
39
109
|
### `contract.version` default flips to v2 in v0.64.0
|
|
40
110
|
|
|
41
111
|
An unset `contract.version` resolves to `'v1'` today. That default becomes
|
|
42
|
-
`'v2'` in **v0.64.0
|
|
43
|
-
`/broadcast`), switches realtime frames to CloudEvents 1.0 envelopes, drops the
|
|
44
|
-
legacy `X-Webhook-*` signing headers, and disables the Quickback HMAC-JWT lane
|
|
45
|
-
unless `auth.jwt` is declared. See the
|
|
112
|
+
`'v2'` in **v0.64.0**. See the
|
|
46
113
|
[contract matrix](/platform/api-contract#contract-version-matrix).
|
|
47
114
|
|
|
115
|
+
> v0.64.0 shipped this **without** moving any URLs — semantics and routes became
|
|
116
|
+
> independent axes, so `/api/v1` stays put. This entry originally said the flip
|
|
117
|
+
> would move `/api/v1` → `/api/v2`; that is not what happened.
|
|
118
|
+
|
|
119
|
+
|
|
48
120
|
Every compile that leaves `contract.version` unset now warns. Pin
|
|
49
121
|
`contract: { version: "v1" }` to keep the current wire, or set `"v2"` to migrate
|
|
50
122
|
now.
|
|
@@ -24,12 +24,14 @@ 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
|
-
> **
|
|
27
|
+
> **This JWT surface is opt-in by default**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
> when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
-
> `/api/
|
|
32
|
-
>
|
|
29
|
+
> Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
|
|
30
|
+
> JWT surface only when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
+
> has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
|
|
32
|
+
> fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
|
|
33
|
+
> the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
|
|
34
|
+
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
33
35
|
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
34
36
|
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
35
37
|
> available.
|
|
@@ -94,7 +94,7 @@ 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` | `{ version?: "v1" \| "v2" }` |
|
|
97
|
+
| `contract` | `{ version?: "v1" \| "v2", routes?: "v1" \| "v2" }` | Two independent axes. `version` selects SEMANTICS (default `"v2"`); `routes` selects the URL prefix (default `"v1"`). See [API Contract](/platform/api-contract#two-axes-semantics-and-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
99
|
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
|
|
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 |
|
|
@@ -121,28 +121,28 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
121
121
|
|
|
122
122
|
## Public contract version
|
|
123
123
|
|
|
124
|
-
Quickback
|
|
125
|
-
|
|
124
|
+
Quickback runs the **v2 contract on `/api/v1` by default** — `version` and
|
|
125
|
+
`routes` are independent. Pin `version: "v1"` to opt out of v2 semantics; set
|
|
126
|
+
`routes: "v2"` to move the URLs:
|
|
126
127
|
|
|
127
128
|
```typescript
|
|
128
129
|
export default defineConfig({
|
|
129
130
|
name: "my-app",
|
|
130
131
|
template: "hono",
|
|
131
|
-
contract: { version: "v2" },
|
|
132
|
+
contract: { version: "v2", routes: "v2" },
|
|
132
133
|
providers: cloudflare({}),
|
|
133
134
|
});
|
|
134
135
|
```
|
|
135
136
|
|
|
136
|
-
|
|
137
|
-
to `/auth/v2/*`,
|
|
138
|
-
`llms.txt`, schema/embeddings routes,
|
|
139
|
-
|
|
140
|
-
those paths into the SPA build and injects them at runtime
|
|
141
|
-
|
|
142
|
-
does not expose a mixed v1/v2 surface from one compiled Worker. Omitting
|
|
143
|
-
`contract` remains byte-compatible with v1 projects.
|
|
137
|
+
`routes` is atomic across every surface: feature routes move to `/api/v2/*`,
|
|
138
|
+
Better Auth to `/auth/v2/*`, realtime to `/broadcast/v2`, and generated
|
|
139
|
+
OpenAPI, MCP tool calls, OAuth discovery, `llms.txt`, schema/embeddings routes,
|
|
140
|
+
and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
|
|
141
|
+
bakes those paths into the SPA build and injects them at runtime. Quickback
|
|
142
|
+
does not expose a mixed v1/v2 URL surface from one compiled Worker.
|
|
144
143
|
|
|
145
|
-
|
|
144
|
+
Action input-schema fidelity is a compile gate on **every** contract version
|
|
145
|
+
since v0.63.0, not just v2. The CLI must
|
|
146
146
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
147
147
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
148
148
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
499
499
|
|
|
500
500
|
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
501
|
|
|
502
|
-
- `/api/v1/*` and `/auth/v1/*`
|
|
503
|
-
|
|
502
|
+
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
+
when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
|
|
504
|
+
not move these)
|
|
504
505
|
- `/storage/*` — R2 file storage
|
|
505
506
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
506
507
|
- `/account/*`, `/cms/*` — bundled SPAs (when enabled)
|
|
507
|
-
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.
|
|
508
|
+
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
|
|
508
509
|
|
|
509
510
|
The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
|
|
510
511
|
|
|
@@ -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.
|
|
218
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
|
|
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
|
|
|
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
70
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
71
|
have. No subpath.
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
|
|
74
|
+
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
|
|
76
|
+
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
|
+
|
|
78
|
+
- `PATCH /api/v1/<resource>/:id` with
|
|
74
79
|
`Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
|
|
75
80
|
to an existing root. Plain `application/json` keeps the flat-column PATCH.
|
|
76
|
-
- `POST /api/
|
|
81
|
+
- `POST /api/v1/<resource>` with the same media type — create the root and its
|
|
77
82
|
children in one changeset.
|
|
78
83
|
|
|
79
84
|
```jsonc
|
|
80
|
-
// PATCH /api/
|
|
85
|
+
// PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
|
|
81
86
|
{
|
|
82
87
|
"patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
|
|
83
88
|
"tasks": {
|
|
@@ -4,15 +4,16 @@ Every generated API speaks one public HTTP contract, selected once per project:
|
|
|
4
4
|
|
|
5
5
|
```ts title="quickback/quickback.config.ts"
|
|
6
6
|
export default defineConfig({
|
|
7
|
-
// Omitted =
|
|
7
|
+
// Omitted = v2 semantics on /api/v1. Pin "v1" to opt out.
|
|
8
8
|
contract: { version: "v2" },
|
|
9
9
|
// ...
|
|
10
10
|
});
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
**v2 is the flagship contract
|
|
14
|
-
v1
|
|
15
|
-
|
|
13
|
+
**v2 is the flagship contract, and the default since v0.64.0.** Everything new
|
|
14
|
+
lands on v2; a project pinned to v1 keeps the byte-stable legacy wire and
|
|
15
|
+
receives no new contract features until it migrates. Your URLs are a separate
|
|
16
|
+
choice — see [below](#two-axes-semantics-and-routes).
|
|
16
17
|
|
|
17
18
|
## Response envelope
|
|
18
19
|
|
|
@@ -111,28 +112,39 @@ export default defineAction({
|
|
|
111
112
|
});
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
##
|
|
115
|
+
## Two axes: semantics and routes
|
|
115
116
|
|
|
116
|
-
`contract
|
|
117
|
-
|
|
118
|
-
moves the entire matrix below on its next compile after that release.
|
|
117
|
+
`contract` has two independent keys, and conflating them is the most common
|
|
118
|
+
mistake:
|
|
119
119
|
|
|
120
|
-
|
|
120
|
+
| Key | Controls | Default |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `version` | Semantics — framing, strictness, the auth lane | `'v2'` |
|
|
123
|
+
| `routes` | The URL prefix, and nothing else | `'v1'` |
|
|
124
|
+
|
|
125
|
+
So a project with no `contract` block **runs the v2 contract on `/api/v1`.**
|
|
126
|
+
Taking the flagship semantics does not move your URLs, and moving your URLs
|
|
127
|
+
does not change your semantics.
|
|
121
128
|
|
|
129
|
+
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
122
130
|
```typescript
|
|
123
|
-
{
|
|
124
|
-
contract: {
|
|
131
|
+
contract: { version: "v1" } // opt out of v2 semantics
|
|
132
|
+
contract: { routes: "v2" } // serve on /api/v2, keep v1 semantics
|
|
133
|
+
contract: { version: "v2", routes: "v2" } // both — the pre-v0.64.0 "v2"
|
|
125
134
|
```
|
|
126
135
|
|
|
136
|
+
**This changed in v0.64.0.** Before it, `version: 'v2'` moved the URLs too, and
|
|
137
|
+
the default was `'v1'` on both axes. A project that pinned `version: 'v2'` to
|
|
138
|
+
get `/api/v2` must now add `routes: 'v2'` to keep those URLs.
|
|
139
|
+
|
|
127
140
|
**Pinning your CLI version does not pin the contract.** The default lives in the
|
|
128
|
-
compiler, which is a hosted service — an older CLI inherits
|
|
129
|
-
|
|
130
|
-
`contract.version` unset.
|
|
141
|
+
compiler, which is a hosted service — an older CLI inherits it too. The config
|
|
142
|
+
key is the only pin.
|
|
131
143
|
|
|
132
144
|
## Contract version matrix
|
|
133
145
|
|
|
134
|
-
|
|
135
|
-
|
|
146
|
+
`version` moves everything in this table except the three base paths, which
|
|
147
|
+
follow `routes`:
|
|
136
148
|
|
|
137
149
|
| Surface | v1 (pinned) | v2 (flagship) |
|
|
138
150
|
|---|---|---|
|
|
@@ -148,10 +160,11 @@ client migration as one move:
|
|
|
148
160
|
| `fields[<fk>]=` unknown names | n/a | **400** |
|
|
149
161
|
| Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
|
|
150
162
|
|
|
151
|
-
Sequencing a migration:
|
|
152
|
-
|
|
153
|
-
consumers
|
|
154
|
-
|
|
163
|
+
Sequencing a migration: the URL row is the only one you can defer with
|
|
164
|
+
`routes`. For the rest — ship subscribers that parse CloudEvents frames, move
|
|
165
|
+
webhook consumers onto the `webhook-*` headers (v1 already sends **both** sets,
|
|
166
|
+
so that step needs no coordination), and either adopt session-first auth or
|
|
167
|
+
declare `auth.jwt`. Pin `version: "v1"` while that work lands.
|
|
155
168
|
|
|
156
169
|
## Machine-readable contract
|
|
157
170
|
|
|
@@ -49,9 +49,11 @@ auth: {
|
|
|
49
49
|
},
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
> **
|
|
52
|
+
> **This surface is opt-in by default**
|
|
53
53
|
>
|
|
54
|
-
>
|
|
54
|
+
> Contract v2 is the default since v0.64.0, and on it 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. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
|
|
55
|
+
>
|
|
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.
|
|
55
57
|
|
|
56
58
|
|
|
57
59
|
---
|
|
@@ -79,7 +79,7 @@ providers: {
|
|
|
79
79
|
}
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.
|
|
82
|
+
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
|
|
83
83
|
|
|
84
84
|
### Namespace-backed tickets (per-matched-lane)
|
|
85
85
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.
|
|
5
|
+
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
|
|
6
6
|
- **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
|
|
7
7
|
|
|
8
8
|
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
|
|
|
157
157
|
Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
|
|
158
158
|
slips through the gap between reading the surface and the socket going live:
|
|
159
159
|
|
|
160
|
-
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket`
|
|
160
|
+
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
|
|
161
161
|
`{ view, rootId }`) — gated by exactly the same `read.access` + firewall
|
|
162
162
|
checks as the read endpoint — and opens a WebSocket scoped to
|
|
163
163
|
`view:<view>:<rootId>`.
|
|
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
|
|
|
125
125
|
|
|
126
126
|
## The wire frame
|
|
127
127
|
|
|
128
|
-
Clients receive a broadcast frame on `/broadcast/v{n}` (the
|
|
128
|
+
Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
|
|
129
129
|
|
|
130
130
|
```jsonc
|
|
131
131
|
{
|
|
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
|
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
10
|
const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
|
|
11
|
-
// Note: /broadcast/v1 tracks contract.
|
|
11
|
+
// Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Authentication
|
|
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
|
|
|
377
377
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
378
378
|
| `POST /{action}` | Standalone actions defined |
|
|
379
379
|
|
|
380
|
-
Routes are mounted under `/api/v1/{feature}`
|
|
381
|
-
`/api/v2/{feature}` when `contract: {
|
|
380
|
+
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
381
|
+
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
|
|
382
|
+
selects semantics and leaves these paths alone.
|
|
382
383
|
|
|
383
384
|
## Migrations
|
|
384
385
|
|
|
@@ -105,7 +105,7 @@ interface ListResult {
|
|
|
105
105
|
The client is constructed once from the resolved `apiUrl` and provided via React
|
|
106
106
|
context (`ApiClientContext`), available throughout the component tree. It reads
|
|
107
107
|
the Better Auth session cookie and calls the standard REST endpoints
|
|
108
|
-
(`/api/v1/{table}`, or `/api/v2/…`
|
|
108
|
+
(`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
|
|
109
109
|
|
|
110
110
|
## Embedded Mode (Recommended)
|
|
111
111
|
|