@quickback-dev/cli 0.63.0 → 0.64.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/index.js +1 -1
- package/dist/skill/docs/changelog/index.md +76 -4
- package/dist/skill/docs/configure/index.md +13 -13
- package/dist/skill/docs/platform/api-contract/index.md +33 -20
- package/package.json +1 -1
- package/src/skill/docs/changelog/index.md +76 -4
- package/src/skill/docs/configure/index.md +13 -13
- package/src/skill/docs/platform/api-contract/index.md +33 -20
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.
|
|
@@ -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
|
|
@@ -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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.64.0",
|
|
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.
|
|
@@ -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
|
|
@@ -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
|
|