@quickback-dev/cli 0.65.1 → 0.66.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.
Files changed (123) hide show
  1. package/dist/commands/compile.d.ts +1 -1
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +13 -0
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/action-harvest.d.ts.map +1 -1
  7. package/dist/lib/action-harvest.js +14 -6
  8. package/dist/lib/action-harvest.js.map +1 -1
  9. package/dist/lib/action-harvest.test.js +26 -0
  10. package/dist/lib/action-harvest.test.js.map +1 -1
  11. package/dist/lib/migrations/drizzle.d.ts.map +1 -1
  12. package/dist/lib/migrations/drizzle.js +6 -1
  13. package/dist/lib/migrations/drizzle.js.map +1 -1
  14. package/dist/lib/migrations/drizzle.test.js +3 -0
  15. package/dist/lib/migrations/drizzle.test.js.map +1 -1
  16. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  17. package/dist/lib/wrangler-resources.js +5 -2
  18. package/dist/lib/wrangler-resources.js.map +1 -1
  19. package/dist/lib/wrangler-resources.test.js +6 -0
  20. package/dist/lib/wrangler-resources.test.js.map +1 -1
  21. package/dist/skill/SKILL.md +18 -3
  22. package/dist/skill/docs/api/batch-operations.md +1 -1
  23. package/dist/skill/docs/api/crud.md +1 -1
  24. package/dist/skill/docs/api/index.md +1 -1
  25. package/dist/skill/docs/api/query-params.md +5 -8
  26. package/dist/skill/docs/changelog/index.md +87 -1
  27. package/dist/skill/docs/configure/auth.md +20 -12
  28. package/dist/skill/docs/configure/domains.md +1 -1
  29. package/dist/skill/docs/configure/index.md +19 -29
  30. package/dist/skill/docs/configure/providers.md +6 -4
  31. package/dist/skill/docs/configure/single-tenant.md +7 -3
  32. package/dist/skill/docs/define/access.md +3 -0
  33. package/dist/skill/docs/define/actions/defining.md +2 -2
  34. package/dist/skill/docs/define/actions/index.md +1 -1
  35. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
  36. package/dist/skill/docs/define/actions/scoped-db.md +23 -6
  37. package/dist/skill/docs/define/changesets.md +7 -8
  38. package/dist/skill/docs/define/feature.md +3 -2
  39. package/dist/skill/docs/define/firewall.md +2 -0
  40. package/dist/skill/docs/define/index.md +1 -1
  41. package/dist/skill/docs/define/read.md +2 -2
  42. package/dist/skill/docs/define/relationships.md +7 -0
  43. package/dist/skill/docs/define/schema.md +21 -1
  44. package/dist/skill/docs/define/triggers.md +14 -3
  45. package/dist/skill/docs/platform/api-contract/index.md +52 -42
  46. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  47. package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
  48. package/dist/skill/docs/platform/database/d1.md +13 -1
  49. package/dist/skill/docs/platform/database/neon.md +1 -1
  50. package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
  51. package/dist/skill/docs/platform/realtime/index.md +8 -10
  52. package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
  53. package/dist/skill/docs/platform/realtime/using-realtime.md +62 -36
  54. package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
  55. package/dist/skill/docs/start/deploy-browser.md +2 -2
  56. package/dist/skill/docs/start/deploy-owner-access.md +49 -50
  57. package/dist/skill/docs/start/deploy.md +2 -2
  58. package/dist/skill/docs/start/first-api.md +1 -1
  59. package/dist/skill/docs/start/patterns.md +17 -2
  60. package/dist/skill/docs/start/template-cloudflare.md +1 -1
  61. package/dist/skill/docs/tooling/cli.md +1 -1
  62. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  63. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  64. package/dist/skill/docs/tooling/output.md +1 -1
  65. package/dist/skill/docs/ui/account/customization.md +1 -1
  66. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  67. package/dist/skill/docs/ui/account/features/index.md +7 -6
  68. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  69. package/dist/skill/docs/ui/account/hooks.md +2 -1
  70. package/dist/skill/docs/ui/account/index.md +7 -4
  71. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  72. package/package.json +1 -1
  73. package/src/skill/SKILL.md +18 -3
  74. package/src/skill/docs/api/batch-operations.md +1 -1
  75. package/src/skill/docs/api/crud.md +1 -1
  76. package/src/skill/docs/api/index.md +1 -1
  77. package/src/skill/docs/api/query-params.md +5 -8
  78. package/src/skill/docs/changelog/index.md +87 -1
  79. package/src/skill/docs/configure/auth.md +20 -12
  80. package/src/skill/docs/configure/domains.md +1 -1
  81. package/src/skill/docs/configure/index.md +19 -29
  82. package/src/skill/docs/configure/providers.md +6 -4
  83. package/src/skill/docs/configure/single-tenant.md +7 -3
  84. package/src/skill/docs/define/access.md +3 -0
  85. package/src/skill/docs/define/actions/defining.md +2 -2
  86. package/src/skill/docs/define/actions/index.md +1 -1
  87. package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
  88. package/src/skill/docs/define/actions/scoped-db.md +23 -6
  89. package/src/skill/docs/define/changesets.md +7 -8
  90. package/src/skill/docs/define/feature.md +3 -2
  91. package/src/skill/docs/define/firewall.md +2 -0
  92. package/src/skill/docs/define/index.md +1 -1
  93. package/src/skill/docs/define/read.md +2 -2
  94. package/src/skill/docs/define/relationships.md +7 -0
  95. package/src/skill/docs/define/schema.md +21 -1
  96. package/src/skill/docs/define/triggers.md +14 -3
  97. package/src/skill/docs/platform/api-contract/index.md +52 -42
  98. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  99. package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
  100. package/src/skill/docs/platform/database/d1.md +13 -1
  101. package/src/skill/docs/platform/database/neon.md +1 -1
  102. package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
  103. package/src/skill/docs/platform/realtime/index.md +8 -10
  104. package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
  105. package/src/skill/docs/platform/realtime/using-realtime.md +62 -36
  106. package/src/skill/docs/platform/webhooks/outbound.md +4 -5
  107. package/src/skill/docs/start/deploy-browser.md +2 -2
  108. package/src/skill/docs/start/deploy-owner-access.md +49 -50
  109. package/src/skill/docs/start/deploy.md +2 -2
  110. package/src/skill/docs/start/first-api.md +1 -1
  111. package/src/skill/docs/start/patterns.md +17 -2
  112. package/src/skill/docs/start/template-cloudflare.md +1 -1
  113. package/src/skill/docs/tooling/cli.md +1 -1
  114. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  115. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  116. package/src/skill/docs/tooling/output.md +1 -1
  117. package/src/skill/docs/ui/account/customization.md +1 -1
  118. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  119. package/src/skill/docs/ui/account/features/index.md +7 -6
  120. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  121. package/src/skill/docs/ui/account/hooks.md +2 -1
  122. package/src/skill/docs/ui/account/index.md +7 -4
  123. package/src/skill/docs/ui/account/with-quickback.md +1 -1
@@ -169,7 +169,7 @@ is not supported.
169
169
  - **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
170
170
  - **[Record and standalone actions](/define/actions/record-and-standalone)** — the two shapes, and what `path:` changes
171
171
  - **[Access](/define/actions/access)** — roles, record conditions, context substitution, relationship-roles
172
- - **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, unsafe mode, raw SQL policy, sharing code
172
+ - **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, AUTH_DB vs `ctx`, unsafe mode, raw SQL policy, sharing code
173
173
  - **[Examples](/define/actions/examples)** — end-to-end action files
174
174
 
175
175
  Related: **[Transitions](/define/transitions)** for state-machine policy,
@@ -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. Under contract v2, Quickback considers the action's
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 contract-v2 Cloudflare + Neon Hyperdrive project, an action can admit 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
@@ -448,9 +448,14 @@ with the transition's "from" precondition for transition actions.
448
448
 
449
449
  #### Reaching Better Auth tables (`authDb`)
450
450
 
451
- The scoped `db` only sees your feature tables. To read Better Auth tables —
452
- users, organizations, members — use the auth database connection from the
453
- Hono context plus the generated `lib/org-access.ts` helper:
451
+ The scoped `db` is the **features** database. Better Auth tables never appear
452
+ on it — that is by design. `AUTH_DB` is a separate Drizzle client.
453
+
454
+ **Caller identity — use `ctx`, do not query `AUTH_DB`.** `ctx.userId`,
455
+ `ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request.
456
+
457
+ To check that a *submitted* user id is an org member (assignee-style
458
+ features), use `c.get("authDb")` plus the generated `getOrgMemberRole` helper:
454
459
 
455
460
  ```typescript
456
461
  // features/projects/actions/assign.ts — validate a userId is an org member
@@ -481,6 +486,18 @@ export default defineAction({
481
486
  ```
482
487
 
483
488
  `c.get("authDb")` is the Drizzle connection to the auth database (in dual-DB
484
- mode it's a separate D1 from your features). For richer queries, import the
485
- auth schema tables from `../../../auth/schema` and query `authDb` directly.
489
+ mode it's a separate D1 from your features). That is the native membership
490
+ check.
491
+
492
+ For a richer query, use the same `authDb` and import tables from
493
+ `../../../auth/schema` — from an **`actions/` file**. On D1 the tables are
494
+ `user`, `organization`, and `member` — not `organization_membership`. (Neon
495
+ exports the Better Auth CLI's plural names: `users`, `organizations`,
496
+ `members`.)
497
+
498
+ | Surface | AUTH_DB handle | Notes |
499
+ |---|---|---|
500
+ | Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
501
+ | [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
502
+ | Trigger `handler:` | **none** | Args are `{ ctx, db, env }` — `db` is features only. There is no `c`. Prefer `ctx` for the acting user. Do not import `../../auth/schema` from the table file to reach AUTH_DB; that path used to compile and then fail package-mode wrangler. Check another user's membership in an action. |
486
503
 
@@ -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 — two reasons. (1) Project-config prerequisite: `owns` is a contract-v2 capability (stated two paragraphs above) and needs `contract: { version: "v2" }`; the gate's harness config pins v1. (2) 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. */}
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 contract-v2
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#two-axes-semantics-and-routes)
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
- contract-v2 changeset is a compiler write surface, not one of the
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, contract v2 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 prerequisites this fence cannot carry: `owns` needs `contract: { version: "v2" }`, and 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. */}
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 contract-v2 root that declares `owns`; the gate's harness config pins v1, so the import cannot resolve. `description` / `input` / `access` are elided to `// ...` on purpose — the point is the delegation seam. */}
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.
@@ -187,11 +187,12 @@ For everything action-related — record vs standalone, conflict rules, the gene
187
187
  ## Composition vs reference — `owns`
188
188
 
189
189
  A schema-level FK (`references:` / `.references()`) says "this row points at
190
- that row." It does **not** say who owns whom. When a set of child rows has no
190
+ that row." It does **not** say who owns whom. `.references()` may only target
191
+ another **feature table in the same database** — never Better Auth `users` /
192
+ `user` / `organization` / `member` (those live in `AUTH_DB`). When a set of child rows has no
191
193
  lifecycle of its own — junction memberships, normalized phones/emails, line
192
194
  items — declare the composition with `owns` on the root table:
193
195
 
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
196
  ```ts
196
197
  export default feature("projects", {
197
198
  columns: {
@@ -90,6 +90,8 @@ An explicit predicate on a custom-named column is honoured **on that table** via
90
90
 
91
91
  If `userId` is genuinely informational, rename it to something that says so (`linkedUserId`, `assigneeId`, `inviteeId`) and the warning goes away.
92
92
 
93
+ Do **not** turn that column into a SQL FK to Better Auth. `.references(() => users.id)` (or `user`) is illegal across split D1s (`AUTH_DB` vs `DB`) and deploy fails with `Generate features database migrations`. Store it as `q.text().required()`. See [Schema → References](/define/schema).
94
+
93
95
  ## Predicate Shape
94
96
 
95
97
  ```typescript
@@ -17,7 +17,7 @@ Quickback is a **backend compiler**. You write definition files, and Quickback c
17
17
  - **Don't** create a `workspaces` / `teams` / `tenants` table.
18
18
  - **Don't** create a membership or `*_members` table.
19
19
  - **Do** put `organizationId: q.scope("organization")` on every tenant-scoped table — the firewall is auto-derived from it.
20
- - Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. You never query for them.
20
+ - Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. Do not query AUTH_DB for the **acting** user. To check that a *submitted* user id belongs to the org, query AUTH_DB from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
21
21
  - Create a tenant with `POST /auth/v1/organization/create` and switch with `POST /auth/v1/organization/set-active` — not a custom action.
22
22
 
23
23
  If your product calls it something else, that's a **label, not a schema decision** — the Account UI renames the organization surfaces for you (see [Account → Customization](/ui/account/customization)).
@@ -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 contract-v2 `?include=`,
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 — project-config prerequisite: `owns` + `?include=` are contract-v2 capabilities (the prose above says so) and need `contract: { version: 'v2' }` in quickback.config.ts; the gate's harness config pins v1. It also names a `noteReactions` child table that the fence deliberately does not repeat. */}
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' } },
@@ -10,6 +10,8 @@ isn't in your org.
10
10
  > A relationship's `from:` must be one of *your* feature tables — the compiler rejects one
11
11
  > pointing at Better Auth's `organization_memberships`, `organizations`, or `user`. Org
12
12
  > membership is already decided before your handler runs and is available as `ctx.roles`.
13
+ > To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
14
+ > see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
13
15
  >
14
16
  > A relationship's `where:` also takes **scalar equality only** (`string | number |
15
17
  > boolean`). `where: { role: ['admin','owner'] }` is not valid — declare one relationship
@@ -53,6 +55,11 @@ export default defineConfig({
53
55
  });
54
56
  ```
55
57
 
58
+ > **userId is not a SQL FK to Better Auth**
59
+ >
60
+ > `subject: { column: 'userId', equals: 'ctx.userId' }` matches a **plain text** column on your join table. Do not write `.references(() => users.id)` (or `user`, `organization`, `member`) on that column. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. SQLite cannot FK across those databases, and drizzle-kit fails generating features migrations with `Critical command failed: Generate features database migrations`. Store it as `userId: q.text().required()`. See [Schema → References](/define/schema).
61
+
62
+
56
63
  > **The `from:` table needs its own defineTable**
57
64
  >
58
65
  > A relationship resolves through the `from:` table's **generated resource module**
@@ -82,7 +82,27 @@ A few mechanics to know:
82
82
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
83
83
  - **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
84
84
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
85
- - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path.
85
+ - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
86
+
87
+ > **Never FK Better Auth tables**
88
+ >
89
+ > `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
90
+ >
91
+ > `Critical command failed: Generate features database migrations`
92
+ >
93
+ > A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
94
+ >
95
+ > A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
96
+ >
97
+ > {/* doc-compile: skip — two-column excerpt, not a host feature */}
98
+ > ```typescript
99
+ > userId: q.text().required(), // ctx.userId — no .references()
100
+ > channelId: q.text().required().references(() => channels.id, { onDelete: 'cascade' }),
101
+ > ```
102
+ >
103
+ > `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
104
+
105
+
86
106
  - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
87
107
 
88
108
  ### Column Types
@@ -106,6 +106,15 @@ Live Views, with full application context:
106
106
  handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) => { ... }
107
107
  ```
108
108
 
109
+ The `db` a handler receives is the **features** database. There is no `c` and
110
+ no `authDb`. Prefer `ctx.userId`, `ctx.activeOrgId`, `ctx.roles`, and
111
+ `ctx.userRole` for the acting user.
112
+
113
+ Do **not** import `../../auth/schema` from the table file to reach AUTH_DB —
114
+ that import used to survive compile and then fail package-mode wrangler with
115
+ `Could not resolve`. Checking that another user is an org member belongs in
116
+ an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
117
+
109
118
  - **`before*` hooks are synchronous.** Return a partial object to merge
110
119
  into the write payload, or throw to reject — the write never executes and
111
120
  the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
@@ -116,9 +125,11 @@ handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) =>
116
125
  `TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
117
126
  already persisted (no transactions on D1), so clients must not blind-retry.
118
127
  - Handlers must be **inline arrow/function expressions**. Imports they
119
- reference are hoisted into the generated registry, and each table's
120
- drizzle object is auto-imported under its authored name — so this works
121
- as written:
128
+ reference are hoisted into the generated registry (`src/lib/trigger-hooks.ts`)
129
+ with relative paths rewritten from the table file — including dynamic
130
+ `import("…")` inside the handler. Write them as they resolve next to the
131
+ table. Each table's drizzle object is auto-imported under its authored
132
+ name — so this works as written:
122
133
 
123
134
  ```typescript
124
135
  import { eq } from 'drizzle-orm';
@@ -1,19 +1,20 @@
1
1
  # API Contract
2
2
 
3
- Every generated API speaks one public HTTP contract, selected once per project:
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
- // Omitted = v2 semantics on /api/v1. Pin "v1" to opt out.
8
- contract: { version: "v2" },
11
+ contract: { routes: "v2" }, // optional — serve on /api/v2 instead
9
12
  // ...
10
13
  });
11
14
  ```
12
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
+ `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=` (contract v2 —
33
- see [query params](/api/query-params)).
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
- ## Two axes: semantics and routes
116
+ ## One axis: routes
116
117
 
117
- `contract` has two independent keys, and conflating them is the most common
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
- 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.
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: { 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"
129
+ contract: { routes: "v2" } // serve on /api/v2 instead of /api/v1
134
130
  ```
135
131
 
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.
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
- **Pinning your CLI version does not pin the contract.** The default lives in the
141
- compiler, which is a hosted service — an older CLI inherits it too. The config
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
- ## Contract version matrix
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` moves everything in this table except the three base paths, which
147
- follow `routes`:
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 (pinned) | v2 (flagship) |
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
- | `fields[<fk>]=` unknown names | n/a | **400** |
161
- | Action input schemas | complete client-side harvest **required** (since v0.63.0) | complete client-side harvest **required** |
162
-
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.
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
 
@@ -4,7 +4,7 @@ API keys provide programmatic access for CI/CD pipelines, scripts, and server-to
4
4
 
5
5
  ## Creating API Keys
6
6
 
7
- Create API keys from your [Quickback account](https://account.quickback.dev/profile). Each key is scoped to your organization.
7
+ Create API keys from [Account UI](/ui/account/features/api-keys) (`/api-keys`, linked from profile). Each key is owned by you and scoped to an organization.
8
8
 
9
9
  ## Usage
10
10
 
@@ -51,7 +51,7 @@ auth: {
51
51
 
52
52
  > **This surface is opt-in by default**
53
53
  >
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).
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
 
@@ -22,7 +22,7 @@ Quickback generates separate D1 databases for different concerns:
22
22
 
23
23
  | Database | Binding | Purpose |
24
24
  |----------|---------|---------|
25
- | `AUTH_DB` | `AUTH_DB` | Better Auth tables (user, session, account) |
25
+ | `AUTH_DB` | `AUTH_DB` | Better Auth tables (`user`, `session`, `account`, `organization`, `member`) |
26
26
  | `DB` | `DB` | Your application data |
27
27
  | `FILES_DB` | `FILES_DB` | File metadata for R2 uploads |
28
28
  | `WEBHOOKS_DB` | `WEBHOOKS_DB` | Webhook delivery tracking |
@@ -32,6 +32,18 @@ This separation provides:
32
32
  - **Isolation** - Auth schema changes don't touch your data
33
33
  - **Clarity** - Clear ownership of each database
34
34
 
35
+ SQLite foreign keys cannot cross those databases. Feature columns must never
36
+ `.references()` Better Auth tables (`user` / `users` / `organization` /
37
+ `member`). Store a Better Auth id as plain text (`userId: q.text().required()`).
38
+ A `.references(() => users.id)` on a feature table makes deploy fail with
39
+ `Critical command failed: Generate features database migrations`. See
40
+ [Schema → References](/define/schema).
41
+
42
+ The scoped feature `db` never includes those tables — query them from an
43
+ action with `c.get("authDb")`, not from a trigger. On D1 the membership table
44
+ is `member`, not `organization_membership`. See
45
+ [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
46
+
35
47
  ## Drizzle ORM Integration
36
48
 
37
49
  Quickback uses [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access:
@@ -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 (contract v2)
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