@quickback-dev/cli 0.66.20 → 0.66.22

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 (102) hide show
  1. package/dist/commands/migrate.js +2 -2
  2. package/dist/commands/migrate.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  5. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  6. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  7. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  8. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  9. package/dist/lib/migrations/file-envelopes.js +21 -51
  10. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  11. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  12. package/dist/lib/migrations/prompt-runner.js +6 -1
  13. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  14. package/dist/skill/docs/api/actions.md +13 -6
  15. package/dist/skill/docs/api/batch-operations.md +6 -2
  16. package/dist/skill/docs/api/crud.md +72 -9
  17. package/dist/skill/docs/api/errors.md +86 -6
  18. package/dist/skill/docs/api/openapi.md +1 -1
  19. package/dist/skill/docs/api/query-params.md +8 -7
  20. package/dist/skill/docs/api/typescript.md +196 -0
  21. package/dist/skill/docs/configure/index.md +36 -2
  22. package/dist/skill/docs/configure/providers.md +37 -9
  23. package/dist/skill/docs/define/actions/defining.md +16 -7
  24. package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
  25. package/dist/skill/docs/define/actions/scoped-db.md +18 -3
  26. package/dist/skill/docs/define/changesets.md +2 -0
  27. package/dist/skill/docs/define/firewall.md +39 -0
  28. package/dist/skill/docs/define/guards.md +7 -2
  29. package/dist/skill/docs/define/masking.md +14 -0
  30. package/dist/skill/docs/define/read.md +3 -0
  31. package/dist/skill/docs/define/relationships.md +9 -0
  32. package/dist/skill/docs/define/schema.md +14 -10
  33. package/dist/skill/docs/define/transitions.md +12 -5
  34. package/dist/skill/docs/define/triggers.md +2 -1
  35. package/dist/skill/docs/index.md +1 -0
  36. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  37. package/dist/skill/docs/platform/database/neon.md +110 -30
  38. package/dist/skill/docs/platform/payments/index.md +1 -1
  39. package/dist/skill/docs/start/frontend.md +278 -0
  40. package/dist/skill/docs/start/index.md +1 -0
  41. package/dist/skill/docs/tooling/cli.md +28 -7
  42. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  43. package/dist/skill/docs/tooling/output.md +42 -11
  44. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  45. package/dist/skill/docs/ui/admin/actions.md +6 -2
  46. package/dist/skill/docs/ui/admin/index.md +1 -1
  47. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  48. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  49. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  50. package/dist/skill/docs/ui/admin/security.md +2 -2
  51. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  52. package/dist/skill/docs/ui/components/auth.md +90 -0
  53. package/dist/skill/docs/ui/components/index.md +48 -0
  54. package/dist/skill/docs/ui/components/install.md +118 -0
  55. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  56. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  57. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  58. package/package.json +1 -1
  59. package/src/skill/docs/api/actions.md +13 -6
  60. package/src/skill/docs/api/batch-operations.md +6 -2
  61. package/src/skill/docs/api/crud.md +72 -9
  62. package/src/skill/docs/api/errors.md +86 -6
  63. package/src/skill/docs/api/openapi.md +1 -1
  64. package/src/skill/docs/api/query-params.md +8 -7
  65. package/src/skill/docs/api/typescript.md +196 -0
  66. package/src/skill/docs/configure/index.md +36 -2
  67. package/src/skill/docs/configure/providers.md +37 -9
  68. package/src/skill/docs/define/actions/defining.md +16 -7
  69. package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
  70. package/src/skill/docs/define/actions/scoped-db.md +18 -3
  71. package/src/skill/docs/define/changesets.md +2 -0
  72. package/src/skill/docs/define/firewall.md +39 -0
  73. package/src/skill/docs/define/guards.md +7 -2
  74. package/src/skill/docs/define/masking.md +14 -0
  75. package/src/skill/docs/define/read.md +3 -0
  76. package/src/skill/docs/define/relationships.md +9 -0
  77. package/src/skill/docs/define/schema.md +14 -10
  78. package/src/skill/docs/define/transitions.md +12 -5
  79. package/src/skill/docs/define/triggers.md +2 -1
  80. package/src/skill/docs/index.md +1 -0
  81. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  82. package/src/skill/docs/platform/database/neon.md +110 -30
  83. package/src/skill/docs/platform/payments/index.md +1 -1
  84. package/src/skill/docs/start/frontend.md +278 -0
  85. package/src/skill/docs/start/index.md +1 -0
  86. package/src/skill/docs/tooling/cli.md +28 -7
  87. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  88. package/src/skill/docs/tooling/output.md +42 -11
  89. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  90. package/src/skill/docs/ui/admin/actions.md +6 -2
  91. package/src/skill/docs/ui/admin/index.md +1 -1
  92. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  93. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  94. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  95. package/src/skill/docs/ui/admin/security.md +2 -2
  96. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  97. package/src/skill/docs/ui/components/auth.md +90 -0
  98. package/src/skill/docs/ui/components/index.md +48 -0
  99. package/src/skill/docs/ui/components/install.md +118 -0
  100. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  101. package/src/skill/docs/ui/components/resource-form.md +80 -0
  102. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -9,7 +9,7 @@ The generated API returns structured error responses with consistent fields acro
9
9
  | `200` | OK | Successful GET, PATCH, DELETE |
10
10
  | `201` | Created | Successful POST |
11
11
  | `207` | Multi-Status | Batch operation with mixed results |
12
- | `400` | Bad Request | Guard violation, validation error, invalid input |
12
+ | `400` | Bad Request | Guard violation, validation error, invalid input, malformed record id (`INVALID_ID`) |
13
13
  | `401` | Unauthorized | Missing or expired authentication |
14
14
  | `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
15
15
  | `404` | Not Found | Firewall blocked the record on a resource that set `firewallErrorMode: 'hide'` (or the route doesn't exist) |
@@ -66,7 +66,7 @@ enough to triage or hand the response to an LLM agent without grepping logs:
66
66
  | `layer` | string | Extension — security layer that rejected the request |
67
67
  | `code` | string | Extension — machine-readable error code (the full enum ships in `openapi.json` as `Problem.code`) |
68
68
  | `details` | object | Extension — layer-specific context (optional) |
69
- | `pointer` | string | Extension — first offending field for validation failures, e.g. `/stage` (optional) |
69
+ | `pointer` | string | Extension — first key of `details.fields` for guard and validation failures, e.g. `/stage` (optional) |
70
70
  | `hint` | string | Extension — actionable guidance for resolution (optional) |
71
71
  | `request` | object | Extension — method, URL, redacted body, and request ID. Auto-attached by the runtime so the error body is self-contained — bodies are capped at 4 KB and well-known sensitive keys (`password`, `token`, `secret`, `apiKey`, `otp`, `code`, `authorization`, …) plus every credential field the compiler itself introduces (`sessionToken`, `eventSessionToken`, `scopeJwt`, `scopeToken`, `wsTicket`, `inviteToken`, `jwt`, `signature`, …) are replaced with `"[REDACTED]"` |
72
72
 
@@ -123,6 +123,7 @@ Firewall filtering is transparent — the query is scoped by `WHERE organization
123
123
  | `FIREWALL_ORG_ISOLATION` | Record belongs to a different organization |
124
124
  | `FIREWALL_USER_ISOLATION` | Record belongs to another user |
125
125
  | `FIREWALL_SOFT_DELETED` | Record has been soft deleted |
126
+ | `FIREWALL_WRITE_DENIED` | A create would land a row outside the caller's firewall (see [Firewall on write](/define/firewall#firewall-on-write)); also a Postgres RLS refusal (`42501`) |
126
127
 
127
128
  Inside an action, an `INSERT` through the [scoped `db`](/define/actions/scoped-db)
128
129
  into a table whose firewall requires a claim the caller does not carry (no
@@ -131,6 +132,13 @@ into a table whose firewall requires a claim the caller does not carry (no
131
132
  `details: { table, column, claim }` — the row is never written into whatever
132
133
  tenant the body named.
133
134
 
135
+ An `INSERT` through the scoped `db` whose row would land outside the table's
136
+ firewall (a project the caller has no relationship to) fails with **403**
137
+ `FIREWALL_WRITE_DENIED`, `layer: "firewall"` — the same Problem the CRUD create
138
+ paths return, and the one a Postgres RLS refusal (`42501`) inside an action maps
139
+ to. A `.prepare()`d insert into such a table is refused with **400**
140
+ `FIREWALL_WRITE_CHECK_UNSUPPORTED`.
141
+
134
142
  For security-hardened deployments, set `firewallErrorMode: 'hide'` at the **top
135
143
  level of the resource definition** (not inside `firewall:` — it was lifted off
136
144
  when `firewall` became a predicate array) to return opaque **404 Not Found**
@@ -189,13 +197,16 @@ Guard violations return **400 Bad Request** when the request body contains field
189
197
  "layer": "guards",
190
198
  "code": "GUARD_FIELD_NOT_CREATEABLE",
191
199
  "details": {
192
- "fields": ["stage"]
200
+ "fields": { "stage": "cannot be set on create" }
193
201
  },
194
202
  "pointer": "/stage",
195
203
  "hint": "These fields are set automatically or must be omitted"
196
204
  }
197
205
  ```
198
206
 
207
+ `GUARD_FIELD_PROTECTED` also carries `details.actions` — the actions that may
208
+ change the field.
209
+
199
210
  **Error codes:**
200
211
 
201
212
  | Code | Description |
@@ -206,6 +217,67 @@ Guard violations return **400 Bad Request** when the request body contains field
206
217
  | `GUARD_FIELD_IMMUTABLE` | Field cannot be modified after creation |
207
218
  | `GUARD_SYSTEM_MANAGED` | System field (createdAt, modifiedAt, etc.) |
208
219
 
220
+ ### Malformed record id (400)
221
+
222
+ Record routes (`GET`/`PATCH`/`PUT`/`DELETE /:id`, the changeset `PATCH`, and
223
+ record actions at `/:id/<action>`) check `:id` against the table's id format
224
+ and answer **400** before any database work when it can't be an id — a UUID
225
+ route given `job_123`, a serial route given `abc`:
226
+
227
+ ```json
228
+ {
229
+ "type": "https://quickback.dev/problems/invalid-id",
230
+ "title": "Invalid id",
231
+ "status": 400,
232
+ "detail": "Malformed \"id\" path parameter",
233
+ "layer": "validation",
234
+ "code": "INVALID_ID",
235
+ "details": { "param": "id", "expected": "a UUID" },
236
+ "hint": "\"id\" must be a UUID. No record was looked up."
237
+ }
238
+ ```
239
+
240
+ | Code | Description |
241
+ |------|-------------|
242
+ | `INVALID_ID` | `:id` isn't shaped like the table's ids — see [Malformed ids](/api/crud#malformed-ids-400-invalid_id) for the per-strategy shapes, what is never checked, and the `validateIdParams: false` opt-out |
243
+
244
+ It is its own code, not a `VALIDATION_*` one: those describe the request
245
+ *body*, and carry a JSON pointer into it. A bad path segment has no pointer,
246
+ and "that's not an id" (400) versus "no such row" (403/404) is the
247
+ distinction a client wants to branch on.
248
+
249
+ ### Validation (400)
250
+
251
+ A body that fails the column or action-input schema returns **400** with
252
+ `layer: "validation"`: `VALIDATION_ERROR` for CRUD bodies,
253
+ `VALIDATION_INVALID_INPUT` for action input and query parameters (which also
254
+ carries the raw Zod `details.issues`), `VALIDATION_FAILED` inside a changeset.
255
+ `details.fields` maps each offending field to its message; an unknown key is
256
+ reported under its own name:
257
+
258
+ ```json
259
+ {
260
+ "detail": "Invalid input",
261
+ "layer": "validation",
262
+ "code": "VALIDATION_INVALID_INPUT",
263
+ "details": {
264
+ "issues": [ … ],
265
+ "fields": { "name": "Required", "status": "Unrecognized field" }
266
+ },
267
+ "pointer": "/name"
268
+ }
269
+ ```
270
+
271
+ ### Field errors — one shape
272
+
273
+ `details.fields` has **one** shape on every layer that names fields — guards,
274
+ body and action-input validation, `FK_NOT_FOUND`: an object mapping the field
275
+ name (a dotted path for nested input) to a human-readable message. A form can
276
+ render each message under its input without knowing which layer rejected the
277
+ request; the generated client exposes it as
278
+ [`QuickbackError.fields`](/api/typescript#fetch-client). `pointer` names the
279
+ first entry.
280
+
209
281
  ### Masking
210
282
 
211
283
  Masking doesn't produce errors — it silently transforms field values in the response.
@@ -219,11 +291,19 @@ Surfaced when a SQL write fails *post-validation* — most often a `NOT NULL` or
219
291
  "detail": "Duplicate value",
220
292
  "layer": "database",
221
293
  "code": "DB_UNIQUE_VIOLATION",
222
- "details": { "column": "email" },
223
- "hint": "A record with this \"email\" already exists"
294
+ "details": {
295
+ "column": "organizationId",
296
+ "columns": ["organizationId", "email"],
297
+ "fields": { "organizationId": "Already taken", "email": "Already taken" }
298
+ },
299
+ "hint": "A record with this \"organizationId\" + \"email\" already exists"
224
300
  }
225
301
  ```
226
302
 
303
+ A unique violation names every column of the constraint (a composite unique
304
+ lists all of them) as API field names, and marks each in `details.fields` so a
305
+ form can show the conflict inline. `details.column` is the first of them.
306
+
227
307
  **Error codes:**
228
308
 
229
309
  | Code | Status | Description |
@@ -265,7 +345,7 @@ keep the internal flat shape (`error` message field, `layer`, `code`,
265
345
  "error": "Field cannot be set during creation",
266
346
  "layer": "guards",
267
347
  "code": "GUARD_FIELD_NOT_CREATEABLE",
268
- "details": { "fields": ["stage"] },
348
+ "details": { "fields": { "stage": "cannot be set on create" } },
269
349
  "hint": "These fields are set automatically or must be omitted"
270
350
  }
271
351
  }
@@ -35,7 +35,7 @@ The generated component schemas carry enough type information that strict valida
35
35
  - **Logical q types survive database lowering** — `q.bool()` remains `boolean`, `q.timestamp()` remains an ISO date-time string, and `q.url()` retains its URI format even when D1 stores the value as text or integer.
36
36
  - **Closed enums on `text(_, { enum: [...] })` columns** — emitted as `{ type: "string", enum: [...] }`, narrowing to a literal union in TS.
37
37
  - **`Error.code` is a closed enum** — every `code` value the API can emit (`AUTH_MISSING`, `DB_UNIQUE_VIOLATION`, `BATCH_SIZE_EXCEEDED`, …) is enumerated so consumers can `switch` exhaustively.
38
- - **ID `format`** — only emitted as `format: "uuid"` when your project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }`, keeping strict OpenAPI validators happy.
38
+ - **ID `format`** — only emitted as `format: "uuid"` when your project sets `generateId: "uuid"` explicitly. An unset `generateId` mints UUIDs too, but the table may still hold prefixed ids from before `"uuid"` became the default, so it gets no `format`. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }`, keeping strict OpenAPI validators happy.
39
39
 
40
40
  ### Action input and output schemas
41
41
 
@@ -42,6 +42,8 @@ It is never dropped:
42
42
  | `?status=open` on a view whose `query.filterable` omits `status` | `400` — `Field "status" is not filterable on this view` |
43
43
  | `?title.matches=x` (no such operator) | `400` — `Unknown filter operator "matches"` |
44
44
  | `?ssn=123` where `ssn` is masked for your role | `400` — see [Masking](/define/masking) |
45
+ | `?resolvedAt.gte=yesterday` on a Postgres timestamp column | `400` — `"yesterday" is not an ISO 8601 timestamp` |
46
+ | `?resolvedAt.like=2026` on a Postgres timestamp column | `400` — use `eq`, `ne`, `gt`, `gte`, `lt`, `lte` or `in` |
45
47
 
46
48
  Silently dropping a predicate would return **every row the firewall allows**
47
49
  while still reading as a scoped list — a typo'd or join-table field turns a
@@ -88,8 +90,8 @@ currently wired into the emitted route.
88
90
  - `view` — the named projection behind the response; `null` for the default collection read
89
91
  - `count` — number of records returned on this page
90
92
  - `page` / `pageSize` — derived from `?offset=` and `?limit=`
91
- - `hasMore` — whether more rows exist in the queried direction. Without `?total=true` it comes from a `limit + 1` over-fetch probe, so it never lies on a final page that exactly fills the limit; with `?total=true` it is page arithmetic (`page < totalPages`).
92
- - `nextCursor` / `prevCursor` — keyset cursors; pass them back as `?starting_after=` and `?ending_before=`. Treat them as opaque, but they are encoded, not encrypted: they carry the boundary row's sort-key values. Either can be `null` — including when the sort includes a [masked](/define/masking) column the caller may sort by (`query.roles`) but not see (`show.roles`); page with `?offset=` in that case.
93
+ - `hasMore` — whether more rows exist in the queried direction. Without `?total=true` it comes from a `limit + 1` over-fetch probe, so it never lies on a final page that exactly fills the limit; with `?total=true` it is page arithmetic (`page < totalPages`) on offset pages, and the probe again on cursor pages.
94
+ - `nextCursor` / `prevCursor` — keyset cursors; pass them back as `?starting_after=` and `?ending_before=`. Treat them as opaque, but they are encoded, not encrypted: they carry the boundary row's sort-key values. Either can be `null` — including when the sort includes a [masked](/define/masking) column the caller may sort by (`query.roles`) but not see (`show.roles`), or a column the response does not carry (a view sorting on a field it doesn't list, or `?fields=` without the sort key); page with `?offset=` in that case.
93
95
  - `total` / `totalPages` — present **only** when the request passed `?total=true` (see below)
94
96
 
95
97
  There is no `limit` or `offset` member in `pagination`.
@@ -154,13 +156,13 @@ GET /api/v1/jobs?fields=id,title,status&status=open&sort=-createdAt
154
156
  GET /api/v1/jobs/job_123?fields=id,title,salaryMin,salaryMax
155
157
  ```
156
158
 
157
- All columns are available including system columns (`id`, `organizationId`, `createdAt`, `modifiedAt`, etc.). Invalid field names are silently ignored. If no valid fields are provided, all columns are returned.
159
+ All declared columns are available, including system columns (`id`, `organizationId`, `createdAt`, `modifiedAt`, etc.). An unknown field name is a `400` Problem (`Unknown field "<name>"`), never silently dropped. An empty `?fields=` returns all columns. Views ignore `?fields=` — they project their own `fields`.
158
160
 
159
161
  **Security**: Masking still applies to selected fields. Requesting `?fields=ssn` will return the masked value, not the raw data.
160
162
 
161
163
  ## Total Count
162
164
 
163
- Get the total number of matching records across all pages by adding `?total=true`. Available on LIST and VIEW routes.
165
+ Get the total number of matching records across all pages by adding `?total=true`. Available on LIST and VIEW routes. The count ignores `?starting_after=` / `?ending_before=`: a cursor page reports the same `total` as the first page.
164
166
 
165
167
  ```bash
166
168
  GET /api/v1/jobs?status=open&total=true
@@ -316,9 +318,8 @@ by target primary key — row objects are never mutated.
316
318
  each listed FK column in its `fields` projection (compile error
317
319
  otherwise — the embedded lookup pivots on that column).
318
320
 
319
- **Strict fields on v2:** unknown names in bare `?fields=` and in
320
- `fields[<fk>]=` are rejected with a 400 Problem. (Pinned v1 keeps its
321
- historical silent-drop for bare `?fields=`.) A `?fields=` projection that
321
+ **Strict fields:** unknown names in bare `?fields=` and in
322
+ `fields[<fk>]=` are rejected with a 400 Problem. A `?fields=` projection that
322
323
  drops the FK column of a requested `?include=` is also a **400** —
323
324
  `include=orderId requires "orderId" in ?fields=` — never a silently-empty
324
325
  `included` slot.
@@ -112,6 +112,23 @@ function that requires the real value cannot silently accept the default row.
112
112
  Name the role you fetched with to get the revealed type; a union role
113
113
  (`Row<"member" | "admin">`) yields `T | Qb.Masked<T>`.
114
114
 
115
+ A masked value narrower than a free string — a number, boolean, array, JSON
116
+ value or enum literal — cannot keep its type once masked: the `redact` mask
117
+ replaces it with the string `"[REDACTED]"`. `Qb.Masked<T>` admits that
118
+ marker, typed `Qb.Redacted`, so narrow before using the value:
119
+
120
+ ```typescript
121
+ // masking: { salary: { type: 'redact', show: { roles: ['admin'] } } } — q.int()
122
+ declare const row: Api.jobs.Row;
123
+ row.salary; // Qb.Masked<number> | null (includes Qb.Redacted)
124
+ if (typeof row.salary === "number") console.log(row.salary * 12);
125
+ ```
126
+
127
+ OpenAPI documents the same thing: the column's schema becomes
128
+ `anyOf: [<schema>, { type: "string", enum: ["[REDACTED]"] }]`. String-shaped
129
+ masks (`email`, `phone`, …) can't mask such columns at all — see
130
+ [Masking](/define/masking#non-string-columns).
131
+
115
132
  `show: { or: 'owner' }` reveals by record ownership, which no type parameter
116
133
  can see, so those columns stay `Masked` for every role outside `show.roles`.
117
134
 
@@ -150,6 +167,9 @@ import { defineAction, row, applications } from "../.quickback/define-action";
150
167
 
151
168
  // Output = Api.applications.Row
152
169
  output: row(applications)
170
+
171
+ // Nested works too: Output = { application: Api.applications.Row; created: boolean }
172
+ output: z.object({ application: row(applications), created: z.boolean() })
153
173
  ```
154
174
 
155
175
  For any other shape, write the schema out:
@@ -205,6 +225,182 @@ const api = createClient<paths>({ baseUrl: "https://api.example.com" });
205
225
  const { data } = await api.GET("/api/v1/jobs/{id}", { params: { path: { id } } });
206
226
  ```
207
227
 
228
+ ## Fetch client
229
+
230
+ Set `client: true` and every compile also emits `quickback.client.ts`: a
231
+ zero-dependency `fetch` client with one method per generated route, typed
232
+ through `quickback.gen.ts`. It has no React and no runtime package, and it is
233
+ the only generated code that knows the wire format (list envelopes, filter
234
+ syntax, Problem Details), so UI code built on it never builds a URL or parses a
235
+ response.
236
+
237
+ ```typescript
238
+ export default defineConfig({
239
+ client: true, // quickback.client.ts
240
+ // client: "apps/web/src/lib/api.ts", // or one custom path
241
+ // client: ["apps/web/src/api.ts", "apps/admin/src/api.ts"],
242
+ });
243
+ ```
244
+
245
+ `client` requires `types` — the client imports `Api` and `Qb` from the first
246
+ `types` output, and the compile fails if `types` is `false`. It is off by
247
+ default.
248
+
249
+ ```typescript
250
+ import { createClient, QuickbackError } from "./quickback.client";
251
+
252
+ const api = createClient({
253
+ baseUrl: "https://api.example.com", // paths already include /api/v1
254
+ // credentials: "include" by default — the Better Auth session cookie
255
+ // headers: () => ({ authorization: `Bearer ${token}` }),
256
+ });
257
+
258
+ // GET /api/v1/applications?stage.in=screen,offer&sort=-createdAt&total=true
259
+ const page = await api.applications.list({
260
+ filter: { "stage.in": ["screen", "offer"] },
261
+ sort: "-createdAt",
262
+ total: true,
263
+ });
264
+ page.data; // Api.applications.Row[]
265
+ page.pagination.total; // present because total: true
266
+
267
+ const app = await api.applications.get(id); // bare record
268
+ await api.applications.update(id, { notes: "…" }); // bare record
269
+ await api.applications.delete(id); // void ({ success: true } on the wire)
270
+ await api.applications.views.pipeline({ limit: 25 });
271
+ await api.applications.actions.advance(id, { notes: "Strong interview" });
272
+
273
+ try {
274
+ await api.applications.create({ candidateId, jobId });
275
+ } catch (err) {
276
+ if (err instanceof QuickbackError) {
277
+ err.status; // HTTP status
278
+ err.problem; // Qb.Problem when the body was application/problem+json, else null
279
+ err.fields; // { [field]: message } from details.fields — guards and validation alike — else null
280
+ }
281
+ }
282
+ ```
283
+
284
+ ### Batch, upsert and pagination
285
+
286
+ Where the batch routes exist, `api.<x>.batch` sends the documented
287
+ [batch bodies](/api/batch-operations); `207` partial success resolves (read
288
+ `errors` and `meta.transactional`), a fail-fast stop throws. `upsert(id, body)`
289
+ is `PUT /:id` and exists only on tables that mount it (`guards: false` +
290
+ `generateId: false`).
291
+
292
+ ```typescript
293
+ const result = await api.applications.batch.create(records, { failFast: true });
294
+ result.success; // Api.applications.Row[]
295
+ result.errors; // [{ index, record, error: { code, details: { fields } } }]
296
+ await api.applications.batch.update([{ id, stage: "offer" }]);
297
+ await api.applications.batch.delete([id1, id2]);
298
+
299
+ // Every page, following pagination.nextCursor (?starting_after=). When the
300
+ // cursor is null — sorting by a column masked for you — it pages by offset.
301
+ import { paginate } from "./quickback.client";
302
+ for await (const page of paginate(api.applications.list, { limit: 100 })) {
303
+ page.data;
304
+ }
305
+ ```
306
+
307
+ ### Bearer lane (React Native, native clients)
308
+
309
+ By default the client authenticates with the Better Auth session cookie
310
+ (`credentials: "include"`). React Native and other non-browser clients send
311
+ no `Origin` header, so every cookie-authenticated write is refused with
312
+ `403 CSRF_ORIGIN_REJECTED` — the [CSRF guard](/platform/auth/security) only
313
+ admits cookie mutations from a trusted origin. Use the bearer lane instead:
314
+
315
+ ```typescript
316
+ import * as SecureStore from "expo-secure-store";
317
+
318
+ const api = createClient({
319
+ baseUrl: "https://api.example.com",
320
+ auth: "bearer", // no cookies; credentials default to "omit"
321
+ sessionStore: { // default: memory, lost on reload
322
+ get: () => SecureStore.getItemAsync("qb.session"),
323
+ set: (token) => (token
324
+ ? SecureStore.setItemAsync("qb.session", token)
325
+ : SecureStore.deleteItemAsync("qb.session")),
326
+ },
327
+ });
328
+
329
+ // Sign in through the client: the session token arrives in set-auth-token
330
+ // on /auth/v1/* and is saved to sessionStore.
331
+ await api.request("POST", "/auth/v1/sign-in/email", { body: { email, password } });
332
+ await api.applications.list();
333
+ ```
334
+
335
+ Every request carries `Authorization: Bearer <token>`:
336
+
337
+ 1. the JWT the API returned last in `set-auth-token` (kept in memory — with
338
+ [`auth.jwt`](/platform/auth/jwt-optimization) every session-authenticated
339
+ call returns one), else
340
+ 2. the session token from `sessionStore`.
341
+
342
+ `set-auth-token` means two things by path: under `/auth/v1` it is Better
343
+ Auth's **session** token (saved to `sessionStore`); anywhere else it is a
344
+ short-lived **JWT** (cached in memory). When the API answers `401` to a JWT —
345
+ expired, key rotated, [revoked](/platform/auth/jwt-optimization#revocation--revocationcheck-kv) —
346
+ the client drops it and retries the request **once** on the session token;
347
+ the session path re-validates and returns a fresh JWT. A `401` on the session
348
+ token itself is final. An `authorization` header you pass in `headers` wins
349
+ over the lane.
350
+
351
+ ### Realtime
352
+
353
+ With realtime enabled, `api.realtime.subscribe(handler, { ticket? })` opens
354
+ the WebSocket for you: it mints a [ws-ticket](/platform/realtime/using-realtime)
355
+ through the same auth lane (a fresh one for every reconnect — tickets live 60
356
+ seconds), shares one socket between subscribers with the same `ticket` body,
357
+ reconnects two seconds after a drop, and closes when the last subscriber
358
+ unsubscribes. Frames are CloudEvents envelopes — switch on `qbframe`.
359
+
360
+ ```typescript
361
+ const unsubscribe = api.realtime.subscribe((frame) => {
362
+ if (frame.qbframe === "postgres_changes") refetch(frame.data.table);
363
+ });
364
+ ```
365
+
366
+ The client mirrors the type tree: `api.<x>` exists wherever `Api.<x>` is a
367
+ table with routes, and a method exists **only** if its route does — a table
368
+ without `delete` access has no `delete`. Record actions take the record id
369
+ first; standalone actions with path parameters take a `params` object; `GET`
370
+ actions send their input as query parameters. Actions declared
371
+ `responseType: 'stream'` or `'file'` resolve to the raw `Response`.
372
+ List-shaped methods accept `limit`, `offset`, `sort`, `search`, `total`,
373
+ `fields`, `include`, `startingAfter` / `endingBefore` and `filter` — see
374
+ [Query Parameters](/api/query-params); array filter values are comma-joined for
375
+ `.in`, and an unknown filter field is a `400`, not an ignored key.
376
+ Changeset (`application/vnd.quickback.changeset+json`) writes are not in the
377
+ client; send them with `api.request`.
378
+
379
+ Runtime extras for generic UI and native clients:
380
+
381
+ - `resources` — keyed by **schema-registry table name** (the key of
382
+ `SchemaRegistry.tables`, the table's JS name), so UI holding a registry
383
+ table can reach its routes without building a URL:
384
+ `{ client, table, ops, views, actions, recordActions, routes }`. `client` is
385
+ the dotted path on the client (`"applications"`, `"crm.contacts"`);
386
+ `recordActions` is the subset of `actions` that take the record id;
387
+ `routes` maps `list` / `get` / `create` / `update` / `delete` / `upsert`,
388
+ `batchCreate` / `batchUpdate` / `batchDelete` / `batchUpsert`,
389
+ `views.<name>` and `actions.<name>` to `{ method, path }` (path templates
390
+ with `{id}`) for clients that build requests themselves (Swift, Kotlin).
391
+ - `api.schema()` — `GET /api/v1/schema`, typed as `SchemaRegistry` (see
392
+ [Schema Registry](/ui/admin/schema-registry)). The registry is **fetched,
393
+ never embedded**: it describes columns, roles and masking, so it stays
394
+ behind that route's auth gate instead of shipping in every frontend bundle.
395
+ The gate defaults to platform sysadmins; open it to your frontend's users
396
+ with [`schemaRegistry.access`](/configure#schema-registry-access).
397
+ - `api.request(method, path, { query, body })` — any other route (Better Auth,
398
+ changesets, custom paths) through the same auth lane and error handling.
399
+
400
+ The emitted file is plain TypeScript that passes `strict`,
401
+ `erasableSyntaxOnly`, `verbatimModuleSyntax` and `noUnused*` — it drops into a
402
+ Vite / shadcn template as-is.
403
+
208
404
  ## Configuration
209
405
 
210
406
  The artifact is on by default:
@@ -108,7 +108,8 @@ Every optional top-level key the config accepts is listed below. You never have
108
108
  | `security` | `object \| false` | HTTP response security headers (CSP, HSTS, COOP/COEP, Referrer/Permissions-Policy) — see [Security Headers](/configure/security) |
109
109
  | `openapi` | `object` | OpenAPI spec generation (`generate`, `publish`, `docs: 'scalar' \| 'swagger'`, `types`) — see [OpenAPI](/api/openapi) |
110
110
  | `types` | `boolean \| object` | Quickback's first-party TypeScript contract (`output`, `brandIds`) — see [TypeScript](/api/typescript) |
111
- | `schemaRegistry` | `object` | Schema registry generation for the CMS (`{ generate: false }` to disable) — see [Schema Registry](/ui/admin/schema-registry) |
111
+ | `client` | `boolean \| string \| string[]` | Emit `quickback.client.ts`, a zero-dependency `fetch` client typed by `types` (default off; requires `types`) — see [Fetch client](/api/typescript#fetch-client) |
112
+ | `schemaRegistry` | `object` | Schema registry for the CMS and generic UI: `{ generate: false }` disables it; `access` sets who may read `GET /api/v1/schema` — see [Schema registry access](#schema-registry-access) and [Schema Registry](/ui/admin/schema-registry) |
112
113
  | `etag` | `object` | ETag caching for GET responses (`{ enabled: false }` to disable) — see [Caching & ETags](/api/caching) |
113
114
  | `email` | `object` | Email delivery config (`provider`, `from`, `fromName`, `region`) — see [Email Configuration](#email-configuration) |
114
115
  | `push` | `object` | Web Push (VAPID keys, TTL/urgency defaults, queue fan-out) — see [Push](/platform/push) |
@@ -557,6 +558,39 @@ If you only want Better Auth to **advertise** itself on a different URL (e.g. so
557
558
 
558
559
  `auth.domain` (Shape 1, above) is the heavier option: it binds an actual hostname to the Worker, configures CORS/cookies/CSP for it, and adds the path-shortcut rewriter. Use it when you want the dedicated hostname as a real ingress, not just a label.
559
560
 
561
+ ## Schema registry access
562
+
563
+ `GET /api/v1/schema` serves the [schema registry](/ui/admin/schema-registry) —
564
+ the columns, validation rules, views, actions, masking and access metadata
565
+ that generic UI renders from (the CMS, and components built on the
566
+ [fetch client](/api/typescript#fetch-client)'s `api.schema()`). It describes
567
+ your data model, so it is gated, by default to platform sysadmins.
568
+
569
+ A frontend for your own users opens it with `schemaRegistry.access`, with or
570
+ without the CMS:
571
+
572
+ ```typescript
573
+ export default defineConfig({
574
+ client: true,
575
+ schemaRegistry: { access: "member" },
576
+ });
577
+ ```
578
+
579
+ | `schemaRegistry.access` | Admits | Denied with |
580
+ |---|---|---|
581
+ | omitted | whatever `cms.access` admits (`"sysadmin"` by default) | `403 CMS_ACCESS_DENIED` |
582
+ | `"sysadmin"` | `user.role === "sysadmin"` | `403 CMS_ACCESS_DENIED` |
583
+ | `"member"` | sysadmins, and any caller holding an organization membership | `403 CMS_ACCESS_DENIED` |
584
+ | `"authenticated"` | any signed-in caller — for owner-scoped apps with no organizations | `401 AUTH_MISSING` |
585
+
586
+ In every mode an anonymous caller gets `401 AUTH_MISSING` (sign in) first;
587
+ `403 CMS_ACCESS_DENIED` is only ever sent to a signed-in caller who lacks the
588
+ role.
589
+
590
+ The route is also the CMS's gate, so with `cms` enabled `schemaRegistry.access`
591
+ must equal `cms.access` — a mismatch is a compile error rather than a silent
592
+ widening of the CMS. The CMS has no `"authenticated"` mode.
593
+
560
594
  ## CMS Configuration
561
595
 
562
596
  Embed the [Admin UI](/ui/admin) in your compiled Worker. It reads your schema registry and renders a complete admin interface — zero UI code per table.
@@ -578,7 +612,7 @@ cms: { domain: "cms.example.com", sysadmin: true },
578
612
  | Option | Type | Default | Description |
579
613
  |--------|------|---------|-------------|
580
614
  | `domain` | `string` | — | Custom domain for CMS. Adds a `custom_domain` route to `wrangler.toml`. |
581
- | `access` | `"user" \| "admin"` | `"admin"` | Controls who can access the CMS. When `"admin"`, platform control-plane users (`user.role === "appmanager"`) can enter; when `sysadmin` mode is also on, `user.role === "sysadmin"` is admitted too. The gate is enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to callers outside those roles) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/ui/admin/connecting) for the full enforcement model. |
615
+ | `access` | `"sysadmin" \| "member"` | `"sysadmin"` | Who can use the CMS. `"sysadmin"` admits `user.role === "sysadmin"` only; `"member"` also admits any caller holding an organization membership, scoped to their active organization. `appmanager` is admitted by neither. The real gate is `GET /api/v1/schema` (and `custom_view` CRUD) — both answer 403 with `CMS_ACCESS_DENIED` naming the requirement (401 `AUTH_MISSING` when not signed in); the SPA shell is served to any signed-in caller so it can explain. The pre-v0.62 values `"admin"` and `"user"` are compile errors. See [CMS Connecting](/ui/admin/connecting) for the full enforcement model. |
582
616
  | `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"appmanager"`. Off by default. See [`SYSADMIN` pseudo-role](/define/access#sysadmin--cross-tenant-db-admin-tier). |
583
617
 
584
618
  ### Sysadmin tier (`cms.sysadmin: true`)
@@ -74,16 +74,20 @@ registered provider; MySQL is not supported.
74
74
  One database provider per app: auth tables and feature tables always share the
75
75
  selected database. On either Postgres provider, Better Auth uses its PostgreSQL/Drizzle adapter
76
76
  in the same Postgres database as your features; on `cloudflare-d1`, both use
77
- D1. A per-service map (`database: { auth: ..., features: ... }`) is rejected at
78
- compile time — mixed database providers are not supported.
77
+ D1. A per-service map (`database: { auth: ..., features: ... }`) is not part
78
+ of the config type (`quickback check` flags it) and is rejected at compile
79
+ time — mixed database providers are not supported. On D1, auth still gets its
80
+ own database by default (`splitDatabases: true`); `authBinding` and
81
+ `featuresBinding` name the two bindings.
79
82
 
80
83
  ```typescript
81
84
  import { defineDatabase } from "@quickback/compiler";
82
85
 
83
86
  providers: {
84
87
  database: defineDatabase("cloudflare-d1", {
85
- generateId: "prefixed", // "uuid" | "cuid" | "nanoid" | "prefixed" | "serial" | false
88
+ generateId: "uuid", // default; "cuid" | "nanoid" | "short" | "prefixed" | "serial" | false
86
89
  allowClientIds: false, // true: POST bodies MAY carry a strategy-shaped id
90
+ validateIdParams: true, // false: /:id is a plain string again (see the hazard below)
87
91
  namingConvention: "snake_case", // "camelCase" | "snake_case"
88
92
  usePlurals: false, // Auth table names: "users" vs "user"
89
93
  }),
@@ -98,8 +102,9 @@ single Postgres database with no bindings or split mode (see
98
102
 
99
103
  | Option | Type | Default (D1) | Description |
100
104
  |--------|------|---------|-------------|
101
- | `generateId` | `string \| false` | `"prefixed"` | ID generation strategy |
105
+ | `generateId` | `string \| false` | `"uuid"` (every provider) | ID generation strategy — see [ID Generation Options](#id-generation-options) |
102
106
  | `allowClientIds` | `boolean` | `false` | Accept an optional client-supplied `id` on create, shaped like the `generateId` strategy — see [Client-supplied IDs](/api/crud#client-supplied-ids-optimistic-updates). Ignored under `generateId: false` (ids are already client-supplied and required) and `"serial"` / numeric PKs |
107
+ | `validateIdParams` | `boolean` | `true` | Check a record route's `:id` against the table's id format and answer `400 INVALID_ID` before any database work — see [Malformed ids](/api/crud#malformed-ids-400-invalid_id). **Set `false` if any table holds rows whose ids don't match the current `generateId` shape** (the strategy changed after rows were written, imported data, ids hand-minted by actions): with the check on, those rows answer 400 instead of the row. Tables whose format the compiler can't know (`generateId: false`, an authored id default) are never checked |
103
108
  | `namingConvention` | `string` | `"snake_case"` | Column naming convention |
104
109
  | `usePlurals` | `boolean` | `false` | Pluralize auth table names (e.g. `user` vs `users`) |
105
110
  | `splitDatabases` | `boolean` | `true` | Separate auth and features databases (D1 only) |
@@ -266,7 +271,7 @@ See [Realtime](/platform/realtime) for the client-side connection flow and helpe
266
271
 
267
272
  | Value | Description | Example |
268
273
  |-------|-------------|---------|
269
- | `"uuid"` | Server generates UUID | `550e8400-e29b-41d4-a716-446655440000` |
274
+ | `"uuid"` (default) | Server generates UUID | `550e8400-e29b-41d4-a716-446655440000` |
270
275
  | `"cuid"` | Server generates CUID | `clh2v8k9g0000l508h5gx8j1a` |
271
276
  | `"nanoid"` | Server generates nanoid (21-char, URL-safe) | `V1StGXR8_Z5jdHi6B-myT` |
272
277
  | `"short"` | 6-char alphanumeric (nanoid `customAlphabet`) | `a3F9xK` |
@@ -274,10 +279,33 @@ See [Realtime](/platform/realtime) for the client-side connection flow and helpe
274
279
  | `"serial"` | Database auto-increments | `1`, `2`, `3` |
275
280
  | `false` | Client provides ID (enables PUT/upsert) | Any string |
276
281
 
277
- > `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records. `"nanoid"` and `"short"` both require the `nanoid` package in your project.
278
-
279
-
280
- > `generateId: "cuid"` is not byte-for-byte uniform across every compiler path. Import-capable runtime paths emit real `createId()` usage, but compiler-managed schema auto-injection may preserve the `createId()` call site with a file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes stay dependency-free. If you require true cuid2 strings everywhere, explicitly import `createId` from `@paralleldrive/cuid2` in the authored schema file.
282
+ Leave `generateId` unset and every provider mints UUIDs, in the CRUD route and
283
+ in the schema default an action's `db.insert()` falls back on alike.
284
+
285
+ > **Upgrading: the default changed from prefixed to uuid**
286
+ >
287
+ > Before this release an unset `generateId` minted **prefixed** ids on D1
288
+ > (`job_550e8400e29b41d4a716446655440000`), and on every provider the CRUD route
289
+ > fell back to prefixed. Unset now means `"uuid"` everywhere. Existing rows keep
290
+ > their ids, so a table that was on the old default holds both shapes:
291
+ >
292
+ > - **Old rows stay reachable.** While `generateId` is unset, record routes'
293
+ > [`:id` check](/api/crud#malformed-ids-400-invalid_id) accepts a UUID **or**
294
+ > any prefixed id the old default minted, and the OpenAPI spec declares no
295
+ > `format` on ids, so a strict client doesn't reject old ids.
296
+ > - **New rows are UUIDs**, including client-supplied ids under `allowClientIds`.
297
+ > - **To keep minting prefixed ids**, set `generateId: "prefixed"` explicitly.
298
+ > - **Once every row is a UUID** (or on a new project), set `generateId: "uuid"`
299
+ > explicitly. That is a promise about every row, so `:id` then accepts only a
300
+ > UUID and ids get `format: "uuid"` in OpenAPI.
301
+ >
302
+ > Code that parses the `<prefix>_` part of an id breaks on new rows either way.
303
+
304
+
305
+ > `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records.
306
+
307
+
308
+ > `"cuid"`, `"nanoid"`, and `"short"` mint with an npm package: `@paralleldrive/cuid2` for `"cuid"`, and `nanoid` for the other two. The compiler adds the package to the generated `package.json` and imports it wherever it mints an id, so don't add it yourself, and don't import it in a table file (table files can't import it). Every server-side mint produces the shape in the table: the CRUD route, and the schema default that a `db.insert()` in an action falls back on. Older compilers backed the schema-side `createId()` with a `crypto.randomUUID()` polyfill, so a `cuid` table can hold UUID rows; record routes' [`:id` check](/api/crud#malformed-ids-400-invalid_id) accepts both.
281
309
 
282
310
 
283
311
  ## Auth Providers
@@ -74,10 +74,11 @@ export default defineAction({
74
74
  > the **feature**, not the whole project: a table owned by another feature is
75
75
  > not re-exported here.
76
76
  >
77
- > Prefer this single import over the older
78
- > `import { applications } from "../applications"` — that path resolves to
79
- > your authored file at edit time, which has no named export and none of the
80
- > injected columns. The helper files are regenerated on every compile; keep
77
+ > Prefer this single import over the older two-import form with
78
+ > `import { applications } from "../applications"`. That form still builds
79
+ > and typechecks — `quickback check` resolves a named import from a
80
+ > `feature()` file to the generated table, as the build does — it is just one
81
+ > import more. The helper files are regenerated on every compile; keep
81
82
  > `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
82
83
  > automatically).
83
84
 
@@ -154,7 +155,10 @@ nothing under that substitution — see
154
155
  `output:` is optional, and omitting it degrades quietly: the operation's
155
156
  OpenAPI success response becomes `{}` and
156
157
  `Api.<feature>.actions.<action>.Output` becomes `unknown`. The compile still
157
- succeeds — it warns, naming how many actions are affected.
158
+ succeeds, but it warns, naming how many actions are affected. Every compile
159
+ emits the warning, validation compiles included. It skips actions whose
160
+ response the compiler owns: `responseType: 'file'` or `'stream'`, bundles, and
161
+ transitions without an `execute`.
158
162
 
159
163
  **An action that returns a row declares it with `row(<table>)`**, imported
160
164
  from the same helper as `defineAction`. **Any other shape is a literal Zod
@@ -166,6 +170,9 @@ import { defineAction, row, tickets } from "../.quickback/define-action";
166
170
  // Returns one ticket: Output = Api.tickets.Row, OpenAPI = the Tickets component.
167
171
  output: row(tickets)
168
172
 
173
+ // row() composes: nest it in an envelope, make it nullable, or put it in an array.
174
+ output: z.object({ ticket: row(tickets), previous: row(tickets).nullable(), related: z.array(row(tickets)) })
175
+
169
176
  // Any other shape — write it out.
170
177
  output: z.object({
171
178
  tickets: z.array(z.object({ id: z.string(), name: z.string(), priceCents: z.number() })),
@@ -177,8 +184,10 @@ output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
177
184
 
178
185
  `row(table)` is compiler-recognised: the harvester records which table it
179
186
  was handed, and the compiler resolves that to the table's `Row` type in
180
- `quickback.gen.ts` and to its resource component in OpenAPI (the table must
181
- be a `defineTable()` resource — anything else is a compile error). At
187
+ `quickback.gen.ts` and to its resource component in OpenAPI — wherever it
188
+ appears in the output: bare, as an object property, under `.nullable()`, or
189
+ as array items (the table must be a `defineTable()` resource — anything else
190
+ is a compile error). At
182
191
  runtime it is a real Zod object built from the table's columns.
183
192
 
184
193
  The harvest substitutes inert proxies for table modules, so anything that