@quickback-dev/cli 0.66.1 → 0.66.3
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/README.md +7 -4
- package/dist/commands/build.d.ts +51 -0
- package/dist/commands/build.d.ts.map +1 -0
- package/dist/commands/build.js +804 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/build.test.d.ts +2 -0
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/build.test.js +150 -0
- package/dist/commands/build.test.js.map +1 -0
- package/dist/commands/check.d.ts +2 -2
- package/dist/commands/check.js +4 -4
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.d.ts +1 -1
- package/dist/commands/create.js +7 -7
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/deploy.d.ts +6 -6
- package/dist/commands/deploy.js +23 -23
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/example.js +1 -1
- package/dist/commands/example.js.map +1 -1
- package/dist/commands/mcp.js +1 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/migrate.d.ts +1 -1
- package/dist/commands/migrate.js +3 -3
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrations.js +2 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/push.js +1 -1
- package/dist/commands/push.js.map +1 -1
- package/dist/commands/start.js +1 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/cursor/quickback.mdc +1 -1
- package/dist/index.js +18 -15
- package/dist/index.js.map +1 -1
- package/dist/lib/auth.js +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +1 -1
- package/dist/lib/compiler-floor.js +1 -1
- package/dist/lib/file-loader.js +2 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +16 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +16 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +3 -3
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/prepare-output.test.js +1 -1
- package/dist/lib/prepare-output.test.js.map +1 -1
- package/dist/lib/schema-sync/index.js +1 -1
- package/dist/lib/schema-sync/index.test.js +1 -1
- package/dist/lib/schema-sync/index.test.js.map +1 -1
- package/dist/skill/SKILL.md +6 -6
- package/dist/skill/docs/api/actions.md +27 -3
- package/dist/skill/docs/api/batch-operations.md +4 -0
- package/dist/skill/docs/api/crud.md +64 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +19 -2
- package/dist/skill/docs/changelog/index.md +33 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/index.md +8 -3
- package/dist/skill/docs/configure/providers.md +3 -0
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +7 -0
- package/dist/skill/docs/define/actions/defining.md +39 -8
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +46 -16
- package/dist/skill/docs/define/areas.md +1 -1
- package/dist/skill/docs/define/diagnostics.md +1 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/feature.md +14 -7
- package/dist/skill/docs/define/guards.md +34 -3
- package/dist/skill/docs/define/schema.md +29 -17
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/views.md +33 -0
- package/dist/skill/docs/index.md +2 -2
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +2 -2
- package/dist/skill/docs/platform/database/neon.md +4 -4
- package/dist/skill/docs/platform/email/index.md +1 -1
- package/dist/skill/docs/platform/queues/handlers.md +1 -1
- package/dist/skill/docs/platform/queues/using-queues.md +1 -1
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/index.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +87 -37
- package/dist/skill/docs/platform/storage/using-r2.md +99 -19
- package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
- package/dist/skill/docs/start/deploy-browser.md +39 -44
- package/dist/skill/docs/start/deploy-owner-access.md +28 -19
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/quickstart.md +3 -3
- package/dist/skill/docs/start/template-blog.md +2 -2
- package/dist/skill/docs/start/template-cloudflare.md +2 -2
- package/dist/skill/docs/start/template-empty.md +1 -1
- package/dist/skill/docs/start/templates.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +1 -1
- package/dist/skill/docs/tooling/cli.md +40 -19
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/dist/skill/docs/tooling/output.md +32 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/environment-variables.md +2 -2
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +9 -5
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/index.md +3 -1
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/dist/skill/docs/ui/admin/actions.md +97 -3
- package/dist/skill/docs/ui/admin/components.md +4 -6
- package/dist/skill/docs/ui/admin/connecting.md +15 -3
- package/dist/skill/docs/ui/admin/index.md +71 -6
- package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
- package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
- package/dist/skill/docs/ui/admin/schema-format.md +39 -2
- package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
- package/dist/skill/docs/ui/admin/security.md +19 -4
- package/dist/skill/docs/ui/admin/table-views.md +59 -12
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +1 -1
- package/src/skill/SKILL.md +6 -6
- package/src/skill/docs/api/actions.md +27 -3
- package/src/skill/docs/api/batch-operations.md +4 -0
- package/src/skill/docs/api/crud.md +64 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +19 -2
- package/src/skill/docs/changelog/index.md +33 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/index.md +8 -3
- package/src/skill/docs/configure/providers.md +3 -0
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +7 -0
- package/src/skill/docs/define/actions/defining.md +39 -8
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +46 -16
- package/src/skill/docs/define/areas.md +1 -1
- package/src/skill/docs/define/diagnostics.md +1 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/feature.md +14 -7
- package/src/skill/docs/define/guards.md +34 -3
- package/src/skill/docs/define/schema.md +29 -17
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/views.md +33 -0
- package/src/skill/docs/index.md +2 -2
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +2 -2
- package/src/skill/docs/platform/database/neon.md +4 -4
- package/src/skill/docs/platform/email/index.md +1 -1
- package/src/skill/docs/platform/queues/handlers.md +1 -1
- package/src/skill/docs/platform/queues/using-queues.md +1 -1
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/index.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +87 -37
- package/src/skill/docs/platform/storage/using-r2.md +99 -19
- package/src/skill/docs/platform/webhooks/inbound.md +40 -0
- package/src/skill/docs/start/deploy-browser.md +39 -44
- package/src/skill/docs/start/deploy-owner-access.md +28 -19
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/quickstart.md +3 -3
- package/src/skill/docs/start/template-blog.md +2 -2
- package/src/skill/docs/start/template-cloudflare.md +2 -2
- package/src/skill/docs/start/template-empty.md +1 -1
- package/src/skill/docs/start/templates.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +1 -1
- package/src/skill/docs/tooling/cli.md +40 -19
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
- package/src/skill/docs/tooling/output.md +32 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/environment-variables.md +2 -2
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +9 -5
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/index.md +3 -1
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- package/src/skill/docs/ui/admin/actions.md +97 -3
- package/src/skill/docs/ui/admin/components.md +4 -6
- package/src/skill/docs/ui/admin/connecting.md +15 -3
- package/src/skill/docs/ui/admin/index.md +71 -6
- package/src/skill/docs/ui/admin/inline-editing.md +38 -4
- package/src/skill/docs/ui/admin/record-layouts.md +22 -21
- package/src/skill/docs/ui/admin/schema-format.md +39 -2
- package/src/skill/docs/ui/admin/schema-registry.md +107 -7
- package/src/skill/docs/ui/admin/security.md +19 -4
- package/src/skill/docs/ui/admin/table-views.md +59 -12
|
@@ -9,7 +9,7 @@ Table mode is the default browse experience:
|
|
|
9
9
|
- **Click rows** to navigate to the record detail view
|
|
10
10
|
- **Row action menus** (three-dot icon) with view, edit, delete, and custom actions
|
|
11
11
|
- **Column headers** are sortable — click to toggle ascending/descending
|
|
12
|
-
- **Search bar** for full-text search across
|
|
12
|
+
- **Search bar** for full-text search across fields allowed by the active collection or named-view query contract
|
|
13
13
|
- **Responsive columns** that adapt to available space
|
|
14
14
|
|
|
15
15
|
Each row shows the most relevant columns for the table. Foreign key columns display human-readable labels (resolved via `_label` fields) instead of raw UUIDs. Boolean columns render as colored Yes/No badges. Enum columns use color-coded pills.
|
|
@@ -74,10 +74,22 @@ Views are named column projections defined in your table's resource config. They
|
|
|
74
74
|
|
|
75
75
|
### Toolbar
|
|
76
76
|
|
|
77
|
-
The toolbar shows a view dropdown when the table has views
|
|
77
|
+
The toolbar shows a view dropdown when the table has named views. Its options
|
|
78
|
+
are the named views the current role may access.
|
|
78
79
|
|
|
79
|
-
|
|
80
|
-
|
|
80
|
+
For a table with no named views, the toolbar renders no view control and the
|
|
81
|
+
table uses its ordinary collection projection. Declaring any `read.views`
|
|
82
|
+
replaces that projection with the named-view contract; **All Fields** is not an
|
|
83
|
+
extra option alongside the named views. Set `read.defaultView` to choose which
|
|
84
|
+
named projection opens first in the CMS. The schema registry carries that
|
|
85
|
+
selection as `defaultView`, and the CMS calls the named-view route from its
|
|
86
|
+
first request.
|
|
87
|
+
|
|
88
|
+
If named views exist without `read.defaultView`, the registry emits
|
|
89
|
+
`requiresExplicitView: true`. The CMS shows **Choose a view** and makes no data
|
|
90
|
+
request until the user selects an accessible named view. It never silently
|
|
91
|
+
chooses the first accessible projection, because projection choice is part of
|
|
92
|
+
the table's data/access contract.
|
|
81
93
|
|
|
82
94
|
Views are filtered by role access. If a view's access rules require `admin` and the current user is a `member`, that view won't appear in the dropdown.
|
|
83
95
|
|
|
@@ -87,24 +99,49 @@ Given this definition:
|
|
|
87
99
|
|
|
88
100
|
```typescript
|
|
89
101
|
read: {
|
|
102
|
+
defaultView: 'summary',
|
|
90
103
|
views: {
|
|
91
104
|
summary: {
|
|
92
105
|
fields: ['id', 'name', 'status'],
|
|
93
|
-
access: { roles: ['member'
|
|
106
|
+
access: { roles: ['member+'] },
|
|
94
107
|
},
|
|
95
108
|
full: {
|
|
96
109
|
fields: ['id', 'name', 'status', 'ssn', 'internalNotes'],
|
|
97
|
-
access: { roles: ['admin'] },
|
|
110
|
+
access: { roles: ['admin+'] },
|
|
98
111
|
},
|
|
99
112
|
},
|
|
100
113
|
}
|
|
101
114
|
```
|
|
102
115
|
|
|
103
|
-
- Members see
|
|
104
|
-
- Admins
|
|
105
|
-
|
|
116
|
+
- Members see `summary`, which opens by default.
|
|
117
|
+
- Admins and owners see `summary` and `full`; `summary` still opens by default.
|
|
118
|
+
|
|
119
|
+
When a view is selected, the CMS calls
|
|
120
|
+
`GET /api/v1/<table>/views/<name>`, fetching only the projected columns. With
|
|
121
|
+
named views but no `read.defaultView`, bare `GET /api/v1/<table>` returns
|
|
122
|
+
`400 VIEW_REQUIRED`. That can be intentional for API callers that must choose a
|
|
123
|
+
projection, but a CMS table intended to open directly should declare an
|
|
124
|
+
accessible default view.
|
|
125
|
+
|
|
126
|
+
### Views Used by FK Lookups
|
|
106
127
|
|
|
107
|
-
When
|
|
128
|
+
When this table is the target of an FK selector, a table with no named views
|
|
129
|
+
uses its ordinary collection route. A table with named views is different: the
|
|
130
|
+
CMS lookup uses only the authored `read.defaultView`, verifies that the current
|
|
131
|
+
role may access it, and calls its named-view route. It never retries the bare
|
|
132
|
+
collection endpoint and never chooses another named view automatically.
|
|
133
|
+
|
|
134
|
+
Make that default view lookup-safe by including the table's primary key and
|
|
135
|
+
`displayColumn` in `fields`. For searchable label typeahead, include the
|
|
136
|
+
`displayColumn` in the view's effective `query.searchable` allowlist. An
|
|
137
|
+
explicit named-view allowlist is authoritative, so the column does not also
|
|
138
|
+
need `.searchable()`. The schema registry emits the effective inherited view
|
|
139
|
+
access and searchability so the CMS can decide before requesting data.
|
|
140
|
+
|
|
141
|
+
If the default is missing, inaccessible, or omits the primary key/label, the
|
|
142
|
+
selector is disabled with an actionable message. If the default is otherwise
|
|
143
|
+
valid but its effective searchable list is empty, the selector shows the first
|
|
144
|
+
50 options as a chooser, keeps search read-only, and sends no `?search`.
|
|
108
145
|
|
|
109
146
|
## Default Sort
|
|
110
147
|
|
|
@@ -121,6 +158,10 @@ export default defineTable(podcastEpisodes, {
|
|
|
121
158
|
|
|
122
159
|
When the CMS loads the table, it applies this sort automatically. Users can still click column headers to change the sort — `defaultSort` only sets the initial state.
|
|
123
160
|
|
|
161
|
+
`defaultSort` does not select a named view. Adding or changing it cannot resolve
|
|
162
|
+
`VIEW_REQUIRED`; use `read.defaultView` (or call the explicit named-view route)
|
|
163
|
+
for that.
|
|
164
|
+
|
|
124
165
|
## Pagination
|
|
125
166
|
|
|
126
167
|
The bottom of every table view shows pagination controls:
|
|
@@ -133,9 +174,15 @@ The default page size is 25 records. The CMS resets to page 1 when you change th
|
|
|
133
174
|
|
|
134
175
|
## Search
|
|
135
176
|
|
|
136
|
-
The search bar performs full-text search across
|
|
177
|
+
The search bar performs full-text search across the fields allowed by the
|
|
178
|
+
active collection or named-view query contract. Type a query and the CMS
|
|
179
|
+
debounces the request, then fetches matching records from the API. For named
|
|
180
|
+
views, the registry's effective `query.searchable` list tells the CMS whether
|
|
181
|
+
the route accepts `?search` and which projected fields participate.
|
|
137
182
|
|
|
138
|
-
Search works in both Table and Data Table modes
|
|
183
|
+
Search works in both Table and Data Table modes when the active route supports
|
|
184
|
+
it. For FK selectors, an empty named-default-view search allowlist activates
|
|
185
|
+
the first-50 chooser behavior above, which sends no `?search`.
|
|
139
186
|
|
|
140
187
|
## Next Steps
|
|
141
188
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.66.
|
|
3
|
+
"version": "0.66.3",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
package/src/cursor/quickback.mdc
CHANGED
|
@@ -277,7 +277,7 @@ Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
|
|
|
277
277
|
|
|
278
278
|
```bash
|
|
279
279
|
quickback create <template> <name> # Create project
|
|
280
|
-
quickback
|
|
280
|
+
quickback build # Build definitions into your API
|
|
281
281
|
quickback docs [topic] # Show documentation
|
|
282
282
|
quickback claude install # Install Claude Code skill
|
|
283
283
|
quickback cursor install # Install Cursor rules
|
package/src/skill/SKILL.md
CHANGED
|
@@ -46,7 +46,7 @@ Everything runs on the user's own Cloudflare account — no Quickback infrastruc
|
|
|
46
46
|
npm install -g @quickback-dev/cli
|
|
47
47
|
quickback create cloudflare my-app
|
|
48
48
|
cd my-app
|
|
49
|
-
quickback
|
|
49
|
+
quickback build
|
|
50
50
|
wrangler deploy
|
|
51
51
|
```
|
|
52
52
|
|
|
@@ -58,9 +58,9 @@ Three concept files do most of the work:
|
|
|
58
58
|
|
|
59
59
|
---
|
|
60
60
|
|
|
61
|
-
## What `quickback
|
|
61
|
+
## What `quickback build` regenerates (and what it never touches)
|
|
62
62
|
|
|
63
|
-
`quickback
|
|
63
|
+
`quickback build` is a **pure code generator**. It reads your `quickback/`
|
|
64
64
|
definitions, sends them to the compiler service, and writes output to disk. It does
|
|
65
65
|
**not** connect to, migrate, or read any database — that is a separate, explicit
|
|
66
66
|
deploy step.
|
|
@@ -90,7 +90,7 @@ migrations are no-ops and only pending ones run. The safe loop against a live pr
|
|
|
90
90
|
DB:
|
|
91
91
|
|
|
92
92
|
1. Edit `quickback/` definitions.
|
|
93
|
-
2. `quickback
|
|
93
|
+
2. `quickback build` → regenerates `src/` and **appends only the new migration(s)**
|
|
94
94
|
to `quickback/drizzle/` (diffed from your committed meta — it does not rewrite or
|
|
95
95
|
replay history).
|
|
96
96
|
3. Deploy → apply pending migrations (no-op for any prod already has), **then**
|
|
@@ -306,14 +306,14 @@ from a table file to reach AUTH_DB.
|
|
|
306
306
|
## Quickback CLI (commands the user runs)
|
|
307
307
|
|
|
308
308
|
```bash
|
|
309
|
-
quickback
|
|
309
|
+
quickback build # build project (prompts to log in if not authenticated)
|
|
310
310
|
quickback create <template> # new project from template
|
|
311
311
|
quickback login # authenticate via browser device flow
|
|
312
312
|
```
|
|
313
313
|
|
|
314
314
|
The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
|
|
315
315
|
|
|
316
|
-
If you have shell access (e.g. Claude Code), run these commands directly — `quickback
|
|
316
|
+
If you have shell access (e.g. Claude Code), run these commands directly — `quickback build` is interactive-safe and prompts for login in the browser. In environments without a shell, surface the commands to the user as instructions instead.
|
|
317
317
|
|
|
318
318
|
---
|
|
319
319
|
|
|
@@ -206,11 +206,35 @@ Raw SQL in action code is blocked by default at compile time. If you need it for
|
|
|
206
206
|
|
|
207
207
|
Unsafe handlers often need to derive the tenant from somewhere other than the ambient request context — an inbound webhook reads it from a mailbox record, a cron job iterates over every organization, a background worker acts on behalf of a specific user. `unsafeDb.scopeTo({ organizationId?, userId?, teamId? })` returns a scoped db that applies the firewall with your explicit scope instead of `ctx`:
|
|
208
208
|
|
|
209
|
-
```typescript
|
|
210
|
-
//
|
|
209
|
+
```typescript
|
|
210
|
+
// features/mail/mailboxes.ts
|
|
211
|
+
import { q } from "@quickback/compiler";
|
|
212
|
+
|
|
213
|
+
export const mailboxes = q.table("mailboxes", {
|
|
214
|
+
id: q.id(),
|
|
215
|
+
address: q.text().required(),
|
|
216
|
+
organizationId: q.text().required(),
|
|
217
|
+
});
|
|
218
|
+
|
|
219
|
+
// features/mail/messages.ts
|
|
220
|
+
import { q } from "@quickback/compiler";
|
|
221
|
+
|
|
222
|
+
export const messages = q.table("messages", {
|
|
223
|
+
id: q.id(),
|
|
224
|
+
mailboxId: q.text().required(),
|
|
225
|
+
body: q.text().required(),
|
|
226
|
+
organizationId: q.text().required(),
|
|
227
|
+
});
|
|
228
|
+
|
|
229
|
+
// features/mail/actions/ingestInbound.ts
|
|
230
|
+
// Inbound mail webhook — PUBLIC + unsafe. `mail` is a multi-table feature
|
|
231
|
+
// with no primary table, so its flat `.quickback/define-action` helper
|
|
232
|
+
// exports no tables — import them from their own table modules.
|
|
211
233
|
import { z } from "zod";
|
|
212
234
|
import { eq } from "drizzle-orm";
|
|
213
|
-
import { defineAction
|
|
235
|
+
import { defineAction } from "../.quickback/define-action";
|
|
236
|
+
import { mailboxes } from "../mailboxes";
|
|
237
|
+
import { messages } from "../messages";
|
|
214
238
|
|
|
215
239
|
export default defineAction({
|
|
216
240
|
description: 'Ingest an inbound mail webhook.',
|
|
@@ -26,6 +26,10 @@ create: {
|
|
|
26
26
|
POST /api/v1/{resource}/batch
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
+
With [`allowClientIds: true`](/api/crud#client-supplied-ids-optimistic-updates)
|
|
30
|
+
each record MAY carry a strategy-shaped `id`; records without one get
|
|
31
|
+
server-minted ids as usual.
|
|
32
|
+
|
|
29
33
|
### Request
|
|
30
34
|
|
|
31
35
|
```json
|
|
@@ -158,6 +158,66 @@ Content-Type: application/json
|
|
|
158
158
|
```
|
|
159
159
|
|
|
160
160
|
Creates a new record. Only fields listed in `guards.createable` are accepted.
|
|
161
|
+
Required columns (`.required()` with no default) must be present; nullable
|
|
162
|
+
columns may be omitted or sent as `null`. An empty string is **not** a blank —
|
|
163
|
+
`""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
|
|
164
|
+
`q.int()`).
|
|
165
|
+
|
|
166
|
+
### Client-supplied IDs (optimistic updates)
|
|
167
|
+
|
|
168
|
+
Set `allowClientIds: true` on the database config to let `POST /` and
|
|
169
|
+
`POST /batch` carry an **optional** `id`. The server inserts the supplied id;
|
|
170
|
+
omit it and the server mints one exactly as before. This is built for
|
|
171
|
+
optimistic updates — the client generates the id up front, renders
|
|
172
|
+
immediately, and every follow-up request can reference the record before the
|
|
173
|
+
`201` arrives.
|
|
174
|
+
|
|
175
|
+
{/* doc-compile: skip — config fragment */}
|
|
176
|
+
```typescript
|
|
177
|
+
providers: {
|
|
178
|
+
database: defineDatabase("cloudflare-d1", {
|
|
179
|
+
generateId: "uuid",
|
|
180
|
+
allowClientIds: true,
|
|
181
|
+
}),
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
POST /jobs
|
|
187
|
+
Content-Type: application/json
|
|
188
|
+
|
|
189
|
+
{
|
|
190
|
+
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
191
|
+
"title": "Senior Engineer"
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
The id must match the shape the active `generateId` strategy mints, so
|
|
196
|
+
client-generated and server-generated ids are indistinguishable in the table:
|
|
197
|
+
|
|
198
|
+
| `generateId` | Accepted shape | Client mints with |
|
|
199
|
+
|--------------|----------------|-------------------|
|
|
200
|
+
| `"uuid"` | UUID | `crypto.randomUUID()` |
|
|
201
|
+
| `"prefixed"` | `<prefix>_` + 32 hex chars (e.g. `job_550e8400…`) | `` `${prefix}_${crypto.randomUUID().replaceAll('-', '')}` `` |
|
|
202
|
+
| `"cuid"` | 24-char cuid2 | `createId()` from `@paralleldrive/cuid2` |
|
|
203
|
+
| `"nanoid"` | 21-char nanoid | `nanoid()` |
|
|
204
|
+
| `"short"` | 6 alphanumerics | matching `customAlphabet` call |
|
|
205
|
+
|
|
206
|
+
What breaks, and how:
|
|
207
|
+
|
|
208
|
+
- A malformed id is a `400 VALIDATION_ERROR` at the Zod boundary.
|
|
209
|
+
- An id that already exists is a `409` UNIQUE-constraint conflict — the row is
|
|
210
|
+
not touched. Retrying a create with the same id is therefore safe: the first
|
|
211
|
+
attempt wins, replays fail loudly. For retry-safety across *any* endpoint,
|
|
212
|
+
prefer the [`Idempotency-Key` header](/platform/api-contract#idempotency-key),
|
|
213
|
+
which replays the original response instead of erroring.
|
|
214
|
+
- The flag is ignored under `generateId: false` (ids are already
|
|
215
|
+
client-supplied and **required**) and under `"serial"` / numeric primary
|
|
216
|
+
keys (the database owns the id).
|
|
217
|
+
|
|
218
|
+
Guards do not apply to the id: it is compiler-managed, so it does not need to
|
|
219
|
+
appear in `guards.createable`. `PUT /:id` and `PATCH` are unchanged — the id
|
|
220
|
+
still comes from the URL, never the body.
|
|
161
221
|
|
|
162
222
|
### Response
|
|
163
223
|
|
|
@@ -183,6 +243,7 @@ wrapper:
|
|
|
183
243
|
|--------|-------------|
|
|
184
244
|
| `400` | Invalid field or missing required field |
|
|
185
245
|
| `403` | User lacks permission to create records |
|
|
246
|
+
| `409` | Client-supplied `id` (with `allowClientIds: true`) already exists |
|
|
186
247
|
|
|
187
248
|
## Update Record
|
|
188
249
|
|
|
@@ -196,6 +257,9 @@ Content-Type: application/json
|
|
|
196
257
|
```
|
|
197
258
|
|
|
198
259
|
Updates an existing record. Only fields listed in `guards.updatable` are accepted.
|
|
260
|
+
Omit a key to leave that column untouched; send `null` to clear a nullable
|
|
261
|
+
column. `null` on a `.required()` column is a `400` — the DB would reject the
|
|
262
|
+
write, so the API does first.
|
|
199
263
|
|
|
200
264
|
### Response
|
|
201
265
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Using the API
|
|
2
2
|
|
|
3
|
-
When you run `quickback
|
|
3
|
+
When you run `quickback build`, Quickback generates a complete REST API from your definitions. This section covers how to use the generated endpoints.
|
|
4
4
|
|
|
5
5
|
## Base URL
|
|
6
6
|
|
|
@@ -155,7 +155,7 @@ export default defineConfig({
|
|
|
155
155
|
});
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
-
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback
|
|
158
|
+
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback build` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
|
|
159
159
|
|
|
160
160
|
For application code, prefer the compact first-party [`quickback.gen.ts` type tree](/api/typescript). Keep `api-types.gen.ts` for `openapi-fetch` and third-party OpenAPI tooling.
|
|
161
161
|
|
|
@@ -241,9 +241,26 @@ This request:
|
|
|
241
241
|
A resource can allowlist FK columns for **FK-graph embedding**, collapsing
|
|
242
242
|
client-side N+1 fetches:
|
|
243
243
|
|
|
244
|
-
```ts
|
|
244
|
+
```ts
|
|
245
|
+
// features/orders/orders.ts
|
|
245
246
|
import { feature, q } from "@quickback/compiler";
|
|
246
|
-
|
|
247
|
+
|
|
248
|
+
export default feature("orders", {
|
|
249
|
+
columns: {
|
|
250
|
+
id: q.id(),
|
|
251
|
+
total: q.int().required(),
|
|
252
|
+
organizationId: q.scope("organization"),
|
|
253
|
+
...q.audit(),
|
|
254
|
+
...q.softDelete(),
|
|
255
|
+
},
|
|
256
|
+
// include is a read of the TARGET resource — embedding orders rows
|
|
257
|
+
// requires orders to declare its own read gate (fail-closed).
|
|
258
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
259
|
+
});
|
|
260
|
+
|
|
261
|
+
// features/orders/order-items.ts
|
|
262
|
+
import { feature, q } from "@quickback/compiler";
|
|
263
|
+
import orders from "./orders";
|
|
247
264
|
|
|
248
265
|
export default feature("orderItems", {
|
|
249
266
|
columns: {
|
|
@@ -94,6 +94,20 @@ the broadcast URL. They match on `qbframe`, read `data` / `qbseq`, and take
|
|
|
94
94
|
`/broadcast/v1` or `/broadcast/v2` from the injected runtime config — the
|
|
95
95
|
same prefixes the worker actually mounts.
|
|
96
96
|
|
|
97
|
+
### `allowClientIds` — optional client-supplied ids on create
|
|
98
|
+
|
|
99
|
+
`providers.database.config.allowClientIds: true` lets `POST /` and
|
|
100
|
+
`POST /batch` carry an **optional** `id`, built for optimistic updates: the
|
|
101
|
+
client mints the id up front (`crypto.randomUUID()` under
|
|
102
|
+
`generateId: 'uuid'`), renders immediately, and the server inserts that id —
|
|
103
|
+
or mints one when it is omitted, exactly as before. The id is shape-locked at
|
|
104
|
+
the Zod boundary to the active `generateId` strategy's format (400 on
|
|
105
|
+
mismatch, 409 on collision), guards stay on (the id is compiler-managed and
|
|
106
|
+
exempt from `createable`), and OpenAPI `<R>Create` schemas plus the client
|
|
107
|
+
`Insert` types advertise it as optional. A no-op under `generateId: false`
|
|
108
|
+
(ids stay client-supplied and **required**) and `'serial'` / numeric PKs.
|
|
109
|
+
See [Client-supplied IDs](/api/crud#client-supplied-ids-optimistic-updates).
|
|
110
|
+
|
|
97
111
|
## v0.65.x — August 16, 2026
|
|
98
112
|
|
|
99
113
|
### Passkeys no longer silently degrade to `rpID: 'localhost'`
|
|
@@ -124,6 +138,22 @@ tenant route. The callback sanitizer now re-applies the basepath to
|
|
|
124
138
|
same-origin paths, covering every sign-in flow (password, passkey, email OTP,
|
|
125
139
|
signup) and social-link callbacks.
|
|
126
140
|
|
|
141
|
+
### Fix: Start deploys of R2 apps failed to resolve `aws4fetch`
|
|
142
|
+
|
|
143
|
+
Package-mode compiles (Start's **Deploy to Cloudflare**) bundle against the
|
|
144
|
+
compiler image's `/deps/node_modules`, not a generated `npm install`. R2
|
|
145
|
+
apps import `aws4fetch` from `src/storage/presign.ts`, but it was only
|
|
146
|
+
declared on the generated `package.json` — CLI deploys worked, Start died
|
|
147
|
+
with `Could not resolve "aws4fetch"`. The compiler image now ships the same
|
|
148
|
+
pin the generator writes.
|
|
149
|
+
|
|
150
|
+
### Start: seeded admin uses your Quickback email
|
|
151
|
+
|
|
152
|
+
A browser deploy writes the first `sysadmin` with the **verified email on
|
|
153
|
+
your Quickback account**, not a synthetic `owner@<app>.invalid` address.
|
|
154
|
+
Reset admin password still rotates the hash only — the broker never
|
|
155
|
+
`UPDATE`s that email afterwards. See [Owner access](/start/deploy-owner-access).
|
|
156
|
+
|
|
127
157
|
## v0.65.0 — August 16, 2026
|
|
128
158
|
|
|
129
159
|
### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
|
|
@@ -237,7 +267,9 @@ evaluation failed, and the underlying local error. This was previously the
|
|
|
237
267
|
behavior of `contract.version: 'v2'` only.
|
|
238
268
|
|
|
239
269
|
`quickback compile --allow-degraded-schemas` restores degrade-and-continue for a
|
|
240
|
-
single compile. It prints every action that fell back and why.
|
|
270
|
+
single compile. It prints every action that fell back and why. (Removed in
|
|
271
|
+
0.66.2 — it worked on a total harvest failure but still threw on a partial one,
|
|
272
|
+
the case it existed for.)
|
|
241
273
|
|
|
242
274
|
The compiler also warns when a caller supplies no schemas at all — `rawFiles`
|
|
243
275
|
callers such as the Start app cannot harvest — naming how many actions of the
|
|
@@ -23,7 +23,7 @@ export default defineConfig({
|
|
|
23
23
|
|
|
24
24
|
## Discoverable options block
|
|
25
25
|
|
|
26
|
-
After your first `quickback
|
|
26
|
+
After your first `quickback build`, the file gets a managed block bracketed by sentinel comments:
|
|
27
27
|
|
|
28
28
|
```typescript
|
|
29
29
|
export default defineConfig({
|
|
@@ -41,7 +41,7 @@ export default defineConfig({
|
|
|
41
41
|
//
|
|
42
42
|
// Login/signup/profile/orgs SPA. Set `true` for default, or object to customize.
|
|
43
43
|
// account: {
|
|
44
|
-
// fileUploads: false, //
|
|
44
|
+
// fileUploads: false, // avatar + org-logo upload. Needs managed R2 + valid R2 credentials. Off on Start.
|
|
45
45
|
// auth: { passkey: false, emailOTP: false, ... },
|
|
46
46
|
// ...
|
|
47
47
|
// },
|
|
@@ -76,7 +76,7 @@ Quickback notices that `account` is set above the marker and drops it from the m
|
|
|
76
76
|
If you ever want to opt out of the auto-managed block, run:
|
|
77
77
|
|
|
78
78
|
```bash
|
|
79
|
-
quickback
|
|
79
|
+
quickback build --no-sync-config
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
## Required Fields
|
|
@@ -310,6 +310,11 @@ export default defineConfig({
|
|
|
310
310
|
|
|
311
311
|
These are merged into the generated `package.json` alongside Quickback's own dependencies. Run `npm install` after compiling to install them.
|
|
312
312
|
|
|
313
|
+
The cloud compiler never installs them — it has no network. A project that
|
|
314
|
+
declares `build.dependencies` therefore skips the [Worker bundle
|
|
315
|
+
check](/tooling/cloud-compiler/troubleshooting#complete-compile-wrangler-bundle-failed)
|
|
316
|
+
and reports that as a compile warning.
|
|
317
|
+
|
|
313
318
|
## Headless Migration Rename Hints
|
|
314
319
|
|
|
315
320
|
When `drizzle-kit generate` detects a potential rename, it normally prompts for confirmation. Cloud/CI compiles are non-interactive, so you must provide explicit rename hints.
|
|
@@ -78,6 +78,7 @@ import { defineDatabase } from "@quickback/compiler";
|
|
|
78
78
|
providers: {
|
|
79
79
|
database: defineDatabase("cloudflare-d1", {
|
|
80
80
|
generateId: "prefixed", // "uuid" | "cuid" | "nanoid" | "prefixed" | "serial" | false
|
|
81
|
+
allowClientIds: false, // true: POST bodies MAY carry a strategy-shaped id
|
|
81
82
|
namingConvention: "snake_case", // "camelCase" | "snake_case"
|
|
82
83
|
usePlurals: false, // Auth table names: "users" vs "user"
|
|
83
84
|
}),
|
|
@@ -93,6 +94,7 @@ single Postgres database with no bindings or split mode (see
|
|
|
93
94
|
| Option | Type | Default (D1) | Description |
|
|
94
95
|
|--------|------|---------|-------------|
|
|
95
96
|
| `generateId` | `string \| false` | `"prefixed"` | ID generation strategy |
|
|
97
|
+
| `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 |
|
|
96
98
|
| `namingConvention` | `string` | `"snake_case"` | Column naming convention |
|
|
97
99
|
| `usePlurals` | `boolean` | `false` | Pluralize auth table names (e.g. `user` vs `users`) |
|
|
98
100
|
| `splitDatabases` | `boolean` | `true` | Separate auth and features databases (D1 only) |
|
|
@@ -100,6 +102,7 @@ single Postgres database with no bindings or split mode (see
|
|
|
100
102
|
| `featuresBinding` | `string` | `"DB"` | Binding name for features database |
|
|
101
103
|
| `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |
|
|
102
104
|
| `authDatabaseId` | `string` | — | D1 database ID for the auth database |
|
|
105
|
+
| `authMigrations` | `'managed' \| 'external'` | `'managed'` | `'external'` when another project owns the auth D1 (a sibling worker sharing one auth database): no `db:migrate:auth:*` script is emitted and `db:migrate:*` / `deploy` skip it. Deleting the step from `package.json` by hand does not stick — compiler-owned scripts converge on every compile |
|
|
103
106
|
| `featuresDatabaseId` | `string` | — | Explicit features DB ID (falls back to `databaseId`) |
|
|
104
107
|
| `filesDatabaseId` | `string` | — | D1 database ID for the files metadata database |
|
|
105
108
|
| `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |
|
|
@@ -19,13 +19,13 @@ The CLI authenticates via two methods:
|
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
21
|
# Use the cloud compiler (default)
|
|
22
|
-
quickback
|
|
22
|
+
quickback build
|
|
23
23
|
|
|
24
24
|
# Use a local compiler instance
|
|
25
|
-
QUICKBACK_API_URL=http://localhost:3000 quickback
|
|
25
|
+
QUICKBACK_API_URL=http://localhost:3000 quickback build
|
|
26
26
|
|
|
27
27
|
# CI/CD with API key
|
|
28
|
-
QUICKBACK_API_KEY=qb_key_... quickback
|
|
28
|
+
QUICKBACK_API_KEY=qb_key_... quickback build
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
## Compiler Service Variables
|
|
@@ -414,6 +414,13 @@ opaque 404 instead.
|
|
|
414
414
|
Function-form access (`access: async (ctx, record) => ...`) is opaque to
|
|
415
415
|
the pre-record phase and always passes there; it's fully evaluated post-record.
|
|
416
416
|
|
|
417
|
+
Collection routes (`GET /`, `POST /batch`, and the generated MCP list tool)
|
|
418
|
+
stop at step 2: there is no record to evaluate, so `access.record` is **not**
|
|
419
|
+
applied to a list — row scoping on a list is the [firewall's](/define/firewall)
|
|
420
|
+
job. Don't use an unsatisfiable predicate (`record: { id: { equals: "never" } }`)
|
|
421
|
+
to hide a resource; it still lists. To give a resource no read surface, omit
|
|
422
|
+
`read` — no list, get, batch, or MCP route is emitted.
|
|
423
|
+
|
|
417
424
|
## Context Variables
|
|
418
425
|
|
|
419
426
|
Use `$ctx.` prefix to reference context values in conditions:
|
|
@@ -5,7 +5,6 @@
|
|
|
5
5
|
```typescript
|
|
6
6
|
// features/applications/actions/advance.ts
|
|
7
7
|
import { z } from "zod";
|
|
8
|
-
import { eq } from "drizzle-orm";
|
|
9
8
|
import { defineAction, applications } from "../.quickback/define-action";
|
|
10
9
|
|
|
11
10
|
export default defineAction({
|
|
@@ -56,11 +55,14 @@ export default defineAction({
|
|
|
56
55
|
> `db.insert().values()` and `db.update().set()` — handlers don't pass
|
|
57
56
|
> them and can't override them.
|
|
58
57
|
|
|
59
|
-
> **Your editor is typed too.** `quickback
|
|
58
|
+
> **Your editor is typed too.** `quickback build` writes the same typed
|
|
60
59
|
> helpers into `quickback/features/<feature>/.quickback/` (plus a
|
|
61
|
-
> `quickback/tsconfig.json`
|
|
60
|
+
> `quickback/tsconfig.json` and a `quickback/.quickback/compiler/` snapshot
|
|
61
|
+
> of the `@quickback/compiler` types, so `feature`/`q`/`defineTable` imports
|
|
62
|
+
> in table files and `quickback.config.ts` resolve as well). The import above
|
|
63
|
+
> resolves — and typechecks —
|
|
62
64
|
> in the tree you actually edit, not just in the generated output. The helper
|
|
63
|
-
> also **re-exports the feature
|
|
65
|
+
> also **re-exports every table in the feature** typed with the generated schema, so
|
|
64
66
|
> compiler-managed columns (`createdAt`, `modifiedBy`, `deletedAt`,
|
|
65
67
|
> `organizationId`) are visible on it without casts:
|
|
66
68
|
>
|
|
@@ -68,6 +70,10 @@ export default defineAction({
|
|
|
68
70
|
> import { defineAction, applications } from "../.quickback/define-action";
|
|
69
71
|
> ```
|
|
70
72
|
>
|
|
73
|
+
> Other tables in the same feature come from that same helper. The boundary is
|
|
74
|
+
> the **feature**, not the whole project: a table owned by another feature is
|
|
75
|
+
> not re-exported here.
|
|
76
|
+
>
|
|
71
77
|
> Prefer this single import over the older
|
|
72
78
|
> `import { applications } from "../applications"` — that path resolves to
|
|
73
79
|
> your authored file at edit time, which has no named export and none of the
|
|
@@ -75,6 +81,32 @@ export default defineAction({
|
|
|
75
81
|
> `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
|
|
76
82
|
> automatically).
|
|
77
83
|
|
|
84
|
+
For an action that joins or writes a table owned by another feature, keep
|
|
85
|
+
`defineAction` from the action's own helper and import the other table
|
|
86
|
+
separately from its feature's generated helper (or generated table module).
|
|
87
|
+
Query operators come from the generated project `lib/q`, not from either
|
|
88
|
+
feature helper:
|
|
89
|
+
|
|
90
|
+
{/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
|
|
91
|
+
```typescript
|
|
92
|
+
// features/waitlist/actions/promote.ts
|
|
93
|
+
import {
|
|
94
|
+
defineAction,
|
|
95
|
+
waitlistEntries,
|
|
96
|
+
} from "../.quickback/define-action";
|
|
97
|
+
import { reservations } from "../../reservations/.quickback/define-action";
|
|
98
|
+
import { q } from "../../../lib/q";
|
|
99
|
+
|
|
100
|
+
// `defineAction` stays bound to waitlistEntries; reservations is only a table.
|
|
101
|
+
// For a direct generated-table import, use "../../reservations/reservations".
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
This waitlist/reservations shape is generic: for any cross-feature action, the
|
|
105
|
+
own-feature helper supplies the action's `record`, `whereRecord`, and
|
|
106
|
+
`whereTransition` context; each external feature supplies only its own tables.
|
|
107
|
+
Importing `defineAction` from the external feature would bind the wrong
|
|
108
|
+
context.
|
|
109
|
+
|
|
78
110
|
### Local action-schema harvest
|
|
79
111
|
|
|
80
112
|
Before sending a compile request, the CLI loads each action in an isolated
|
|
@@ -96,9 +128,8 @@ generated clients treat every required field as optional, and unknown keys pass.
|
|
|
96
128
|
Constructs it cannot parse at all degrade further, to a bare `{}` with no
|
|
97
129
|
`properties`. Neither is visible in a diff.
|
|
98
130
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
compiler warns again with the count and sampled paths.
|
|
131
|
+
There is no opt-out. Fix the action so its input schema harvests — the error
|
|
132
|
+
names each one, the phase that failed, and the underlying local error.
|
|
102
133
|
|
|
103
134
|
Bare imports are resolved from the generated runtime's configured
|
|
104
135
|
`build.outputDir/node_modules` first. If definitions live in `quickback/` and
|
|
@@ -183,6 +214,7 @@ namespace parameters.
|
|
|
183
214
|
| `record` | Standalone only | Feature-area transition adapter binding: `{ table, idFrom: "path.<param>", matchScope? }`. Binds + firewalls the record a `transition` operates on from a proven route param. See [Feature-area transition adapter](#feature-area-transition-adapter) |
|
|
184
215
|
| `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
|
|
185
216
|
| `webhook` | No | Standalone only. Compile-declared inbound signature verification (`standard-webhooks`, `hmac-sha256`, or `aws-sns`) that runs on the raw bytes **before** parse/access — see [Inbound webhooks](/platform/webhooks/inbound) |
|
|
217
|
+
| `rawBody` | No | Standalone, non-GET only. Hand `execute` the request body as received (`rawBody: string`, bounded to 1 MiB) for signature schemes the compiler does not model — a per-organization secret stored in the database, a provider with its own canonicalisation. `input` still parses from the same bytes. Actions with `webhook:` receive `rawBody` automatically — see [Per-organization secrets](/platform/webhooks/inbound#per-organization-secrets-verify-in-the-action) |
|
|
186
218
|
| `idempotency` | No | `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/platform/api-contract) |
|
|
187
219
|
| `cms` | No | Pass-through metadata blob for CMS surfaces |
|
|
188
220
|
|
|
@@ -243,4 +275,3 @@ export default defineAction({
|
|
|
243
275
|
- Ref keys must exist on the inline `z.object` input with agreeing
|
|
244
276
|
optionality; `as` names can't shadow reserved context keys. Injected rows
|
|
245
277
|
are the **unmasked** DB rows (masking remains a read-projection concern).
|
|
246
|
-
|
|
@@ -199,14 +199,17 @@ land in `success[]` masked the same way the single-record response is.
|
|
|
199
199
|
|
|
200
200
|
Standalone actions are independent endpoints that don't require a record context. Set a `path:` to declare the action standalone.
|
|
201
201
|
|
|
202
|
-
**
|
|
202
|
+
**Public URL:** `/api/v1` plus `path:`
|
|
203
203
|
|
|
204
204
|
```
|
|
205
|
-
POST /chat
|
|
206
|
-
GET /reports/summary
|
|
207
|
-
POST /webhooks/stripe
|
|
205
|
+
POST /api/v1/chat
|
|
206
|
+
GET /api/v1/reports/summary
|
|
207
|
+
POST /api/v1/webhooks/stripe
|
|
208
208
|
```
|
|
209
209
|
|
|
210
|
+
`path:` is the suffix under `/api/v1`. `path: "/chat"` and `path: "/api/v1/chat"`
|
|
211
|
+
are the same route. Write either; do not tell callers a URL that omits `/api/v1`.
|
|
212
|
+
|
|
210
213
|
Paths are absolute (`/...`). Inside a [feature area](/define/areas)
|
|
211
214
|
with a mounted prefix, two more forms apply:
|
|
212
215
|
|