@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.
- package/dist/commands/migrate.js +2 -2
- package/dist/commands/migrate.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-prompts.js +11 -0
- package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +21 -51
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
- package/dist/lib/migrations/prompt-runner.js +6 -1
- package/dist/lib/migrations/prompt-runner.js.map +1 -1
- package/dist/skill/docs/api/actions.md +13 -6
- package/dist/skill/docs/api/batch-operations.md +6 -2
- package/dist/skill/docs/api/crud.md +72 -9
- package/dist/skill/docs/api/errors.md +86 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +8 -7
- package/dist/skill/docs/api/typescript.md +196 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +37 -9
- package/dist/skill/docs/define/actions/defining.md +16 -7
- package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/dist/skill/docs/define/actions/scoped-db.md +18 -3
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/firewall.md +39 -0
- package/dist/skill/docs/define/guards.md +7 -2
- package/dist/skill/docs/define/masking.md +14 -0
- package/dist/skill/docs/define/read.md +3 -0
- package/dist/skill/docs/define/relationships.md +9 -0
- package/dist/skill/docs/define/schema.md +14 -10
- package/dist/skill/docs/define/transitions.md +12 -5
- package/dist/skill/docs/define/triggers.md +2 -1
- package/dist/skill/docs/index.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/database/neon.md +110 -30
- package/dist/skill/docs/platform/payments/index.md +1 -1
- package/dist/skill/docs/start/frontend.md +278 -0
- package/dist/skill/docs/start/index.md +1 -0
- package/dist/skill/docs/tooling/cli.md +28 -7
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +42 -11
- package/dist/skill/docs/tooling/troubleshooting.md +67 -0
- package/dist/skill/docs/ui/admin/actions.md +6 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
- package/dist/skill/docs/ui/admin/schema-format.md +74 -36
- package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
- package/dist/skill/docs/ui/admin/security.md +2 -2
- package/dist/skill/docs/ui/components/action-dialog.md +62 -0
- package/dist/skill/docs/ui/components/auth.md +90 -0
- package/dist/skill/docs/ui/components/index.md +48 -0
- package/dist/skill/docs/ui/components/install.md +118 -0
- package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
- package/dist/skill/docs/ui/components/resource-form.md +80 -0
- package/dist/skill/docs/ui/components/resource-table.md +46 -0
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +13 -6
- package/src/skill/docs/api/batch-operations.md +6 -2
- package/src/skill/docs/api/crud.md +72 -9
- package/src/skill/docs/api/errors.md +86 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +8 -7
- package/src/skill/docs/api/typescript.md +196 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +37 -9
- package/src/skill/docs/define/actions/defining.md +16 -7
- package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/src/skill/docs/define/actions/scoped-db.md +18 -3
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/firewall.md +39 -0
- package/src/skill/docs/define/guards.md +7 -2
- package/src/skill/docs/define/masking.md +14 -0
- package/src/skill/docs/define/read.md +3 -0
- package/src/skill/docs/define/relationships.md +9 -0
- package/src/skill/docs/define/schema.md +14 -10
- package/src/skill/docs/define/transitions.md +12 -5
- package/src/skill/docs/define/triggers.md +2 -1
- package/src/skill/docs/index.md +1 -0
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/database/neon.md +110 -30
- package/src/skill/docs/platform/payments/index.md +1 -1
- package/src/skill/docs/start/frontend.md +278 -0
- package/src/skill/docs/start/index.md +1 -0
- package/src/skill/docs/tooling/cli.md +28 -7
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +42 -11
- package/src/skill/docs/tooling/troubleshooting.md +67 -0
- package/src/skill/docs/ui/admin/actions.md +6 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/inline-editing.md +6 -2
- package/src/skill/docs/ui/admin/schema-format.md +74 -36
- package/src/skill/docs/ui/admin/schema-registry.md +22 -9
- package/src/skill/docs/ui/admin/security.md +2 -2
- package/src/skill/docs/ui/components/action-dialog.md +62 -0
- package/src/skill/docs/ui/components/auth.md +90 -0
- package/src/skill/docs/ui/components/index.md +48 -0
- package/src/skill/docs/ui/components/install.md +118 -0
- package/src/skill/docs/ui/components/quickback-provider.md +123 -0
- package/src/skill/docs/ui/components/resource-form.md +80 -0
- package/src/skill/docs/ui/components/resource-table.md +46 -0
|
@@ -134,10 +134,61 @@ Single-record reads run a role-only access check **before** the firewall query,
|
|
|
134
134
|
|
|
135
135
|
| Status | Description |
|
|
136
136
|
|--------|-------------|
|
|
137
|
+
| `400` | `:id` isn't shaped like this table's ids (`INVALID_ID`) — see [Malformed ids](#malformed-ids-400-invalid_id) |
|
|
137
138
|
| `401` | Not authenticated |
|
|
138
139
|
| `403` | Authenticated but role doesn't satisfy `read.access` — **or** the role passes and the firewall excluded the record (`FIREWALL_NOT_FOUND`). This is the default: `firewallErrorMode` is `'reveal'`. |
|
|
139
140
|
| `404` | Same firewall miss, but on a resource that sets [`firewallErrorMode: 'hide'`](/define/firewall) to make an out-of-scope row indistinguishable from a nonexistent one. |
|
|
140
141
|
|
|
142
|
+
### Malformed ids (`400 INVALID_ID`)
|
|
143
|
+
|
|
144
|
+
Every record route — `GET`, `PATCH` (plain and [changeset](/define/changesets)),
|
|
145
|
+
`PUT`, `DELETE /:id`, and record actions at `/:id/<action>` — checks `:id`
|
|
146
|
+
against the table's id format and answers `400 INVALID_ID` before any database
|
|
147
|
+
work. A client gets "that's not an id" instead of a 403/404 that reads like a
|
|
148
|
+
missing row, and garbage never costs a round-trip.
|
|
149
|
+
|
|
150
|
+
The check runs **after** the auth gate (a `401` still wins) and **before** the
|
|
151
|
+
role-only access pre-check. That ordering adds nothing to the ID-probe channel
|
|
152
|
+
above: the verdict is a function of the URL string alone — identical whether or
|
|
153
|
+
not any row exists, in any tenant — and the id format is public (it is in every
|
|
154
|
+
id the API returns). Every well-formed id still goes through the pre-check and
|
|
155
|
+
the firewall exactly as before.
|
|
156
|
+
|
|
157
|
+
The accepted shape is everything the compiler could have minted for the table,
|
|
158
|
+
not just what it mints today:
|
|
159
|
+
|
|
160
|
+
| Id column / `generateId` | `:id` accepts |
|
|
161
|
+
|--------------------------|---------------|
|
|
162
|
+
| unset (the default) | UUID **or** anything `"prefixed"` accepts — before the default became `"uuid"`, unset projects minted prefixed ids, and those rows stay addressable. See [Upgrading](/configure/providers#id-generation-options) |
|
|
163
|
+
| `"uuid"` | UUID (any case) |
|
|
164
|
+
| `"cuid"` | cuid / cuid2 (lowercase letter + 1–31 lowercase alphanumerics) **or** UUID — schema auto-injection has backed `createId()` with `crypto.randomUUID()`, so existing rows can be UUIDs |
|
|
165
|
+
| `"nanoid"` | 21 URL-safe characters |
|
|
166
|
+
| `"short"` | 6 alphanumerics |
|
|
167
|
+
| `"prefixed"` | optional alphanumeric `<prefix>_` + 32 hex (dashes allowed) — **any** prefix, since it derives from the table name and a rename leaves old rows on the old one |
|
|
168
|
+
| `serial` / `bigserial` / `smallserial` column | positive integer (any integer under `generateId: false`) |
|
|
169
|
+
| other integer column | integer |
|
|
170
|
+
| Postgres `uuid` column | UUID, whatever the strategy |
|
|
171
|
+
|
|
172
|
+
Every id a client may supply on create (`allowClientIds`, below) passes this
|
|
173
|
+
check, so a created id is always addressable.
|
|
174
|
+
|
|
175
|
+
**Never checked** — the compiler can't know the format:
|
|
176
|
+
|
|
177
|
+
- `generateId: false` (ids are any client-supplied string — this is also the
|
|
178
|
+
only mode with `PUT /:id` upsert, so upsert ids are never rejected);
|
|
179
|
+
- an id column with an **authored** default (anything other than the
|
|
180
|
+
strategy's own `$defaultFn`), or a non-`id` primary key;
|
|
181
|
+
- other column types (`varchar`, `real`, …).
|
|
182
|
+
|
|
183
|
+
> The check trusts that every row's id has the current strategy's shape. That
|
|
184
|
+
> stops being true when `generateId` changed after rows were written, data was
|
|
185
|
+
> imported with foreign ids, or an action `db.insert`s a hand-made id. Those rows
|
|
186
|
+
> answer **400 instead of the row** — they become unreachable through `/:id`. Set
|
|
187
|
+
> [`validateIdParams: false`](/configure/providers#database-options) on the
|
|
188
|
+
> database config for such a project; routes then read `:id` as a plain string
|
|
189
|
+
> again (numeric primary keys keep their integer check).
|
|
190
|
+
|
|
191
|
+
|
|
141
192
|
### FK Label Resolution
|
|
142
193
|
|
|
143
194
|
Foreign key columns are automatically enriched with `_label` fields containing the referenced table's display value. The name is the FK column with a trailing `Id` stripped, plus `_label` — so `departmentId` gets `department_label`. Enrichment only happens when the referenced table declares a display column. See [Display Column](/define/schema#display-column) for details.
|
|
@@ -157,7 +208,10 @@ Content-Type: application/json
|
|
|
157
208
|
}
|
|
158
209
|
```
|
|
159
210
|
|
|
160
|
-
Creates a new record.
|
|
211
|
+
Creates a new record. With `guards`, only fields in `guards.createable` or
|
|
212
|
+
`guards.immutable` are accepted. Without `guards`, every column except the
|
|
213
|
+
primary key, audit columns, and firewall/scope columns is accepted. Either way,
|
|
214
|
+
a client-supplied `id` is accepted where the project takes one (see below).
|
|
161
215
|
Required columns (`.required()` with no default) must be present; nullable
|
|
162
216
|
columns may be omitted or sent as `null`. An empty string is **not** a blank —
|
|
163
217
|
`""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
|
|
@@ -197,12 +251,15 @@ client-generated and server-generated ids are indistinguishable in the table:
|
|
|
197
251
|
|
|
198
252
|
| `generateId` | Accepted shape | Client mints with |
|
|
199
253
|
|--------------|----------------|-------------------|
|
|
200
|
-
| `"uuid"` | UUID | `crypto.randomUUID()` |
|
|
254
|
+
| unset (the default) or `"uuid"` | UUID | `crypto.randomUUID()` |
|
|
201
255
|
| `"prefixed"` | `<prefix>_` + 32 hex chars (e.g. `job_550e8400…`) | `` `${prefix}_${crypto.randomUUID().replaceAll('-', '')}` `` |
|
|
202
256
|
| `"cuid"` | 24-char cuid2 | `createId()` from `@paralleldrive/cuid2` |
|
|
203
257
|
| `"nanoid"` | 21-char nanoid | `nanoid()` |
|
|
204
258
|
| `"short"` | 6 alphanumerics | matching `customAlphabet` call |
|
|
205
259
|
|
|
260
|
+
The server mints the same shape on every path: `POST /`, `POST /batch`, and
|
|
261
|
+
the schema default that an action's `db.insert()` falls back on.
|
|
262
|
+
|
|
206
263
|
What breaks, and how:
|
|
207
264
|
|
|
208
265
|
- A malformed id is a `400 VALIDATION_ERROR` at the Zod boundary.
|
|
@@ -216,8 +273,11 @@ What breaks, and how:
|
|
|
216
273
|
keys (the database owns the id).
|
|
217
274
|
|
|
218
275
|
Guards do not apply to the id: it is compiler-managed, so it does not need to
|
|
219
|
-
appear in `guards.createable`.
|
|
220
|
-
|
|
276
|
+
appear in `guards.createable`. The same rule holds under `generateId: false`,
|
|
277
|
+
where the id is **required** on `POST /`, `POST /batch` and a changeset
|
|
278
|
+
`POST` (root and owned-child inserts): guards check every other field, never
|
|
279
|
+
the id. `PUT /:id` and `PATCH` are unchanged — the id still comes from the
|
|
280
|
+
URL, never the body.
|
|
221
281
|
|
|
222
282
|
### Response
|
|
223
283
|
|
|
@@ -256,7 +316,9 @@ Content-Type: application/json
|
|
|
256
316
|
}
|
|
257
317
|
```
|
|
258
318
|
|
|
259
|
-
Updates an existing record.
|
|
319
|
+
Updates an existing record. With `guards`, only fields in `guards.updatable`
|
|
320
|
+
are accepted. Without `guards`, every column except the primary key, audit
|
|
321
|
+
columns, and firewall/scope columns is accepted.
|
|
260
322
|
Omit a key to leave that column untouched; send `null` to clear a nullable
|
|
261
323
|
column. `null` on a `.required()` column is a `400` — the DB would reject the
|
|
262
324
|
write, so the API does first.
|
|
@@ -279,7 +341,7 @@ patched ones) — there is no `data` wrapper:
|
|
|
279
341
|
|
|
280
342
|
| Status | Description |
|
|
281
343
|
|--------|-------------|
|
|
282
|
-
| `400` | Invalid field or field not updatable |
|
|
344
|
+
| `400` | Invalid field or field not updatable, or a malformed `:id` ([`INVALID_ID`](#malformed-ids-400-invalid_id)) |
|
|
283
345
|
| `403` | User lacks permission to update this record, or the firewall excluded it (default `firewallErrorMode: 'reveal'`) |
|
|
284
346
|
| `404` | Record excluded by the firewall when the resource sets `firewallErrorMode: 'hide'` |
|
|
285
347
|
| `412` | `If-Match` revision mismatch |
|
|
@@ -319,6 +381,7 @@ returned, in either mode:
|
|
|
319
381
|
|
|
320
382
|
| Status | Description |
|
|
321
383
|
|--------|-------------|
|
|
384
|
+
| `400` | Malformed `:id` ([`INVALID_ID`](#malformed-ids-400-invalid_id)) |
|
|
322
385
|
| `403` | User lacks permission to delete this record, or the firewall excluded it (default `firewallErrorMode: 'reveal'`) |
|
|
323
386
|
| `404` | Record excluded by the firewall when the resource sets `firewallErrorMode: 'hide'` |
|
|
324
387
|
| `412` | `If-Match` revision mismatch |
|
|
@@ -402,7 +465,7 @@ Creates multiple records in a single request. Each record follows the same valid
|
|
|
402
465
|
"error": "Field cannot be set during creation",
|
|
403
466
|
"layer": "guards",
|
|
404
467
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
405
|
-
"details": { "fields":
|
|
468
|
+
"details": { "fields": { "status": "cannot be set on create" } }
|
|
406
469
|
}
|
|
407
470
|
}
|
|
408
471
|
],
|
|
@@ -634,7 +697,7 @@ By default, batch operations use **partial success** mode:
|
|
|
634
697
|
"error": "Human-readable message",
|
|
635
698
|
"layer": "guards",
|
|
636
699
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
637
|
-
"details": { "fields":
|
|
700
|
+
"details": { "fields": { "status": "cannot be set on create" } },
|
|
638
701
|
"hint": "These fields are set automatically or must be omitted"
|
|
639
702
|
}
|
|
640
703
|
}
|
|
@@ -688,7 +751,7 @@ On the first failure under `failFast: true`:
|
|
|
688
751
|
"details": {
|
|
689
752
|
"failedAt": 2,
|
|
690
753
|
"reason": "Field cannot be set during creation",
|
|
691
|
-
"errorDetails": { "fields":
|
|
754
|
+
"errorDetails": { "fields": { "status": "cannot be set on create" } }
|
|
692
755
|
},
|
|
693
756
|
"hint": "Records before index 2 were applied and are NOT rolled back. Inspect application state before retrying — re-sending the same batch may double-apply records that already succeeded."
|
|
694
757
|
}
|
|
@@ -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
|
|
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":
|
|
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": {
|
|
223
|
-
|
|
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":
|
|
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
|
|
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.).
|
|
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
|
|
320
|
-
`fields[<fk>]=` are rejected with a 400 Problem.
|
|
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
|
-
| `
|
|
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` | `"
|
|
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`)
|