@quickback-dev/cli 0.66.0 → 0.66.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/README.md +7 -4
  2. package/dist/commands/build.d.ts +51 -0
  3. package/dist/commands/build.d.ts.map +1 -0
  4. package/dist/commands/build.js +793 -0
  5. package/dist/commands/build.js.map +1 -0
  6. package/dist/commands/build.test.d.ts +2 -0
  7. package/dist/commands/build.test.d.ts.map +1 -0
  8. package/dist/commands/build.test.js +150 -0
  9. package/dist/commands/build.test.js.map +1 -0
  10. package/dist/commands/check.d.ts +2 -2
  11. package/dist/commands/check.js +4 -4
  12. package/dist/commands/check.js.map +1 -1
  13. package/dist/commands/create.d.ts +1 -1
  14. package/dist/commands/create.js +7 -7
  15. package/dist/commands/create.js.map +1 -1
  16. package/dist/commands/deploy.d.ts +6 -6
  17. package/dist/commands/deploy.js +23 -23
  18. package/dist/commands/deploy.js.map +1 -1
  19. package/dist/commands/example.js +1 -1
  20. package/dist/commands/example.js.map +1 -1
  21. package/dist/commands/mcp.js +1 -1
  22. package/dist/commands/mcp.js.map +1 -1
  23. package/dist/commands/migrate.d.ts +1 -1
  24. package/dist/commands/migrate.js +3 -3
  25. package/dist/commands/migrate.js.map +1 -1
  26. package/dist/commands/migrations.js +2 -2
  27. package/dist/commands/migrations.js.map +1 -1
  28. package/dist/commands/push.js +1 -1
  29. package/dist/commands/push.js.map +1 -1
  30. package/dist/commands/start.js +1 -1
  31. package/dist/commands/start.js.map +1 -1
  32. package/dist/cursor/quickback.mdc +1 -1
  33. package/dist/index.js +18 -15
  34. package/dist/index.js.map +1 -1
  35. package/dist/lib/auth.js +1 -1
  36. package/dist/lib/auth.js.map +1 -1
  37. package/dist/lib/compiler-floor.d.ts +1 -1
  38. package/dist/lib/compiler-floor.js +1 -1
  39. package/dist/lib/file-loader.js +2 -2
  40. package/dist/lib/file-loader.js.map +1 -1
  41. package/dist/lib/file-writer.d.ts +2 -0
  42. package/dist/lib/file-writer.d.ts.map +1 -1
  43. package/dist/lib/file-writer.js +16 -0
  44. package/dist/lib/file-writer.js.map +1 -1
  45. package/dist/lib/file-writer.test.js +16 -0
  46. package/dist/lib/file-writer.test.js.map +1 -1
  47. package/dist/lib/migrations/file-envelopes.js +3 -3
  48. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  49. package/dist/lib/prepare-output.test.js +1 -1
  50. package/dist/lib/prepare-output.test.js.map +1 -1
  51. package/dist/lib/schema-sync/index.js +1 -1
  52. package/dist/lib/schema-sync/index.test.js +1 -1
  53. package/dist/lib/schema-sync/index.test.js.map +1 -1
  54. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  55. package/dist/lib/wrangler-resources.js +5 -2
  56. package/dist/lib/wrangler-resources.js.map +1 -1
  57. package/dist/lib/wrangler-resources.test.js +6 -0
  58. package/dist/lib/wrangler-resources.test.js.map +1 -1
  59. package/dist/skill/SKILL.md +24 -9
  60. package/dist/skill/docs/api/crud.md +7 -0
  61. package/dist/skill/docs/api/index.md +1 -1
  62. package/dist/skill/docs/api/openapi.md +1 -1
  63. package/dist/skill/docs/changelog/index.md +27 -1
  64. package/dist/skill/docs/configure/agents.md +1 -1
  65. package/dist/skill/docs/configure/domains.md +1 -1
  66. package/dist/skill/docs/configure/index.md +11 -5
  67. package/dist/skill/docs/configure/providers.md +6 -3
  68. package/dist/skill/docs/configure/single-tenant.md +7 -3
  69. package/dist/skill/docs/configure/variables.md +3 -3
  70. package/dist/skill/docs/define/access.md +10 -0
  71. package/dist/skill/docs/define/actions/defining.md +35 -7
  72. package/dist/skill/docs/define/actions/index.md +1 -1
  73. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  74. package/dist/skill/docs/define/actions/scoped-db.md +68 -21
  75. package/dist/skill/docs/define/areas.md +1 -1
  76. package/dist/skill/docs/define/diagnostics.md +1 -0
  77. package/dist/skill/docs/define/encryption.md +1 -1
  78. package/dist/skill/docs/define/feature.md +17 -8
  79. package/dist/skill/docs/define/firewall.md +2 -0
  80. package/dist/skill/docs/define/guards.md +27 -3
  81. package/dist/skill/docs/define/index.md +1 -1
  82. package/dist/skill/docs/define/relationships.md +7 -0
  83. package/dist/skill/docs/define/schema.md +44 -14
  84. package/dist/skill/docs/define/security.md +1 -1
  85. package/dist/skill/docs/define/transitions.md +35 -4
  86. package/dist/skill/docs/define/triggers.md +14 -3
  87. package/dist/skill/docs/define/views.md +33 -0
  88. package/dist/skill/docs/index.md +2 -2
  89. package/dist/skill/docs/platform/auth/api-keys.md +2 -2
  90. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  91. package/dist/skill/docs/platform/database/d1.md +15 -3
  92. package/dist/skill/docs/platform/database/neon.md +4 -4
  93. package/dist/skill/docs/platform/email/index.md +1 -1
  94. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  95. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  96. package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
  97. package/dist/skill/docs/platform/schedules/index.md +1 -1
  98. package/dist/skill/docs/platform/storage/index.md +3 -3
  99. package/dist/skill/docs/platform/storage/r2.md +87 -37
  100. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  101. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  102. package/dist/skill/docs/start/deploy-browser.md +40 -45
  103. package/dist/skill/docs/start/deploy-owner-access.md +60 -52
  104. package/dist/skill/docs/start/deploy.md +4 -4
  105. package/dist/skill/docs/start/first-api.md +2 -2
  106. package/dist/skill/docs/start/hand-crafted.md +3 -3
  107. package/dist/skill/docs/start/index.md +3 -3
  108. package/dist/skill/docs/start/patterns.md +17 -2
  109. package/dist/skill/docs/start/quickstart.md +3 -3
  110. package/dist/skill/docs/start/template-blog.md +2 -2
  111. package/dist/skill/docs/start/template-cloudflare.md +3 -3
  112. package/dist/skill/docs/start/template-empty.md +1 -1
  113. package/dist/skill/docs/start/templates.md +1 -1
  114. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  115. package/dist/skill/docs/tooling/cli.md +21 -16
  116. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  117. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  118. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  119. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  120. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  121. package/dist/skill/docs/tooling/output.md +23 -2
  122. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  123. package/dist/skill/docs/ui/account/customization.md +1 -1
  124. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  125. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  126. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  127. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  128. package/dist/skill/docs/ui/account/features/index.md +16 -11
  129. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  130. package/dist/skill/docs/ui/account/hooks.md +2 -0
  131. package/dist/skill/docs/ui/account/index.md +10 -5
  132. package/dist/skill/docs/ui/account/with-quickback.md +2 -2
  133. package/dist/skill/docs/ui/admin/actions.md +97 -3
  134. package/dist/skill/docs/ui/admin/components.md +4 -6
  135. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  136. package/dist/skill/docs/ui/admin/index.md +71 -6
  137. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  138. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  139. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  140. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  141. package/dist/skill/docs/ui/admin/security.md +19 -4
  142. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  143. package/package.json +1 -1
  144. package/src/cursor/quickback.mdc +1 -1
  145. package/src/skill/SKILL.md +24 -9
  146. package/src/skill/docs/api/crud.md +7 -0
  147. package/src/skill/docs/api/index.md +1 -1
  148. package/src/skill/docs/api/openapi.md +1 -1
  149. package/src/skill/docs/changelog/index.md +27 -1
  150. package/src/skill/docs/configure/agents.md +1 -1
  151. package/src/skill/docs/configure/domains.md +1 -1
  152. package/src/skill/docs/configure/index.md +11 -5
  153. package/src/skill/docs/configure/providers.md +6 -3
  154. package/src/skill/docs/configure/single-tenant.md +7 -3
  155. package/src/skill/docs/configure/variables.md +3 -3
  156. package/src/skill/docs/define/access.md +10 -0
  157. package/src/skill/docs/define/actions/defining.md +35 -7
  158. package/src/skill/docs/define/actions/index.md +1 -1
  159. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  160. package/src/skill/docs/define/actions/scoped-db.md +68 -21
  161. package/src/skill/docs/define/areas.md +1 -1
  162. package/src/skill/docs/define/diagnostics.md +1 -0
  163. package/src/skill/docs/define/encryption.md +1 -1
  164. package/src/skill/docs/define/feature.md +17 -8
  165. package/src/skill/docs/define/firewall.md +2 -0
  166. package/src/skill/docs/define/guards.md +27 -3
  167. package/src/skill/docs/define/index.md +1 -1
  168. package/src/skill/docs/define/relationships.md +7 -0
  169. package/src/skill/docs/define/schema.md +44 -14
  170. package/src/skill/docs/define/security.md +1 -1
  171. package/src/skill/docs/define/transitions.md +35 -4
  172. package/src/skill/docs/define/triggers.md +14 -3
  173. package/src/skill/docs/define/views.md +33 -0
  174. package/src/skill/docs/index.md +2 -2
  175. package/src/skill/docs/platform/auth/api-keys.md +2 -2
  176. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  177. package/src/skill/docs/platform/database/d1.md +15 -3
  178. package/src/skill/docs/platform/database/neon.md +4 -4
  179. package/src/skill/docs/platform/email/index.md +1 -1
  180. package/src/skill/docs/platform/queues/handlers.md +1 -1
  181. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  182. package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
  183. package/src/skill/docs/platform/schedules/index.md +1 -1
  184. package/src/skill/docs/platform/storage/index.md +3 -3
  185. package/src/skill/docs/platform/storage/r2.md +87 -37
  186. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  187. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  188. package/src/skill/docs/start/deploy-browser.md +40 -45
  189. package/src/skill/docs/start/deploy-owner-access.md +60 -52
  190. package/src/skill/docs/start/deploy.md +4 -4
  191. package/src/skill/docs/start/first-api.md +2 -2
  192. package/src/skill/docs/start/hand-crafted.md +3 -3
  193. package/src/skill/docs/start/index.md +3 -3
  194. package/src/skill/docs/start/patterns.md +17 -2
  195. package/src/skill/docs/start/quickstart.md +3 -3
  196. package/src/skill/docs/start/template-blog.md +2 -2
  197. package/src/skill/docs/start/template-cloudflare.md +3 -3
  198. package/src/skill/docs/start/template-empty.md +1 -1
  199. package/src/skill/docs/start/templates.md +1 -1
  200. package/src/skill/docs/tooling/claude-skill.md +1 -1
  201. package/src/skill/docs/tooling/cli.md +21 -16
  202. package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  203. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  204. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  205. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  206. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  207. package/src/skill/docs/tooling/output.md +23 -2
  208. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  209. package/src/skill/docs/ui/account/customization.md +1 -1
  210. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  211. package/src/skill/docs/ui/account/features/admin.md +1 -1
  212. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  213. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  214. package/src/skill/docs/ui/account/features/index.md +16 -11
  215. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  216. package/src/skill/docs/ui/account/hooks.md +2 -0
  217. package/src/skill/docs/ui/account/index.md +10 -5
  218. package/src/skill/docs/ui/account/with-quickback.md +2 -2
  219. package/src/skill/docs/ui/admin/actions.md +97 -3
  220. package/src/skill/docs/ui/admin/components.md +4 -6
  221. package/src/skill/docs/ui/admin/connecting.md +15 -3
  222. package/src/skill/docs/ui/admin/index.md +71 -6
  223. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  224. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  225. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  226. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  227. package/src/skill/docs/ui/admin/security.md +19 -4
  228. 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 all fields
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 defined. Options include:
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
- - **All Fields** — Shows all columns (default)
80
- - Custom views — Only show the columns specified in the view config
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', 'admin'] },
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: "All Fields" and "summary"
104
- - Admins see: "All Fields", "summary", and "full"
105
- - Owners see: "All Fields", "summary", and "full"
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 a view is selected, the CMS calls the `listView` API endpoint instead of the standard `list`, fetching only the projected columns.
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 all columns. Type a query and the CMS debounces the request, then fetches matching records from the API.
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, and works with views (searching within the projected columns).
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.0",
3
+ "version": "0.66.2",
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",
@@ -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 compile # Compile definitions
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
@@ -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 compile
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 compile` regenerates (and what it never touches)
61
+ ## What `quickback build` regenerates (and what it never touches)
62
62
 
63
- `quickback compile` is a **pure code generator**. It reads your `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 compile` → regenerates `src/` and **appends only the new migration(s)**
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**
@@ -273,9 +273,17 @@ throw new ActionError("Not enough balance", "INSUFFICIENT_FUNDS", 400, { availab
273
273
 
274
274
  Constructor: `(message, code, statusCode = 400, details?)`. Do **NOT** throw Hono's `HTTPException` — it isn't unwrapped and surfaces as a 500 `ACTION_EXECUTION_FAILED`. Returning `c.json({...}, 400)` directly also works (the executor receives `c`).
275
275
 
276
- ## Reaching auth tables (org members, users) from actions
276
+ ## Reaching auth tables (org members, users)
277
277
 
278
- The scoped `db` only sees feature tables. For "is this userId a member of the caller's org?" (assignee-style features), use the Hono context's auth DB plus the generated helper:
278
+ The scoped feature `db` never includes Better Auth tables — that is by design.
279
+ `AUTH_DB` is a separate Drizzle client.
280
+
281
+ **Caller identity — use `ctx`, do not query AUTH_DB.** `ctx.userId`,
282
+ `ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request
283
+ (there is no `ctx.orgId`).
284
+
285
+ To check that a *submitted* userId is a member of the caller's org, use the
286
+ Hono context's auth DB plus the generated helper — from an **action**:
279
287
 
280
288
  ```ts
281
289
  import { getOrgMemberRole } from "../../../lib/org-access";
@@ -284,21 +292,28 @@ const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activ
284
292
  if (!role) throw new ActionError("Not a member of this organization", "NOT_A_MEMBER", 400);
285
293
  ```
286
294
 
287
- `c.get("authDb")` is the Drizzle connection to the Better Auth database (a separate D1 in dual-DB mode). For richer queries import tables from `../../../auth/schema`. The `ctx` fields are `userId`, `roles` (org-member roles), `activeOrgId`, `activeTeamId`, `userRole` — there is no `ctx.orgId`.
295
+ That is the native membership check. For a richer query from an `actions/`
296
+ file, import tables from `../../../auth/schema`. On D1 the tables are `user`,
297
+ `organization`, and `member` — not `organization_membership`.
298
+
299
+ Account hooks get `{ authDb, authSchema }` injected. Trigger `handler:` args
300
+ are `{ ctx, db, env }` — `db` is features only; there is no `c` and no
301
+ `authDb`. Prefer `ctx` for the acting user. Do not import `../../auth/schema`
302
+ from a table file to reach AUTH_DB.
288
303
 
289
304
  ---
290
305
 
291
306
  ## Quickback CLI (commands the user runs)
292
307
 
293
308
  ```bash
294
- quickback compile # compile project (prompts to log in if not authenticated)
309
+ quickback build # build project (prompts to log in if not authenticated)
295
310
  quickback create <template> # new project from template
296
311
  quickback login # authenticate via browser device flow
297
312
  ```
298
313
 
299
314
  The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
300
315
 
301
- If you have shell access (e.g. Claude Code), run these commands directly — `quickback compile` is interactive-safe and prompts for login in the browser. In environments without a shell, surface the commands to the user as instructions instead.
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.
302
317
 
303
318
  ---
304
319
 
@@ -158,6 +158,10 @@ 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()`).
161
165
 
162
166
  ### Response
163
167
 
@@ -196,6 +200,9 @@ Content-Type: application/json
196
200
  ```
197
201
 
198
202
  Updates an existing record. Only fields listed in `guards.updatable` are accepted.
203
+ Omit a key to leave that column untouched; send `null` to clear a nullable
204
+ column. `null` on a `.required()` column is a `400` — the DB would reject the
205
+ write, so the API does first.
199
206
 
200
207
  ### Response
201
208
 
@@ -1,6 +1,6 @@
1
1
  # Using the API
2
2
 
3
- When you run `quickback compile`, Quickback generates a complete REST API from your definitions. This section covers how to use the generated endpoints.
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 compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
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
 
@@ -86,6 +86,14 @@ without `auth.jwt` it still cannot be admitted: 200 from the mint, 401 on
86
86
  presentation. The compiler now warns instead of failing silently. Declare
87
87
  `auth: { jwt: {} }` if you use those routes.
88
88
 
89
+ ### CMS and Account consume CloudEvents frames as-is
90
+
91
+ The bundled SPAs no longer invert realtime frames back into a private
92
+ `{ type, table, event }` shape, and they no longer sniff `/api/v2` to pick
93
+ the broadcast URL. They match on `qbframe`, read `data` / `qbseq`, and take
94
+ `/broadcast/v1` or `/broadcast/v2` from the injected runtime config — the
95
+ same prefixes the worker actually mounts.
96
+
89
97
  ## v0.65.x — August 16, 2026
90
98
 
91
99
  ### Passkeys no longer silently degrade to `rpID: 'localhost'`
@@ -116,6 +124,22 @@ tenant route. The callback sanitizer now re-applies the basepath to
116
124
  same-origin paths, covering every sign-in flow (password, passkey, email OTP,
117
125
  signup) and social-link callbacks.
118
126
 
127
+ ### Fix: Start deploys of R2 apps failed to resolve `aws4fetch`
128
+
129
+ Package-mode compiles (Start's **Deploy to Cloudflare**) bundle against the
130
+ compiler image's `/deps/node_modules`, not a generated `npm install`. R2
131
+ apps import `aws4fetch` from `src/storage/presign.ts`, but it was only
132
+ declared on the generated `package.json` — CLI deploys worked, Start died
133
+ with `Could not resolve "aws4fetch"`. The compiler image now ships the same
134
+ pin the generator writes.
135
+
136
+ ### Start: seeded admin uses your Quickback email
137
+
138
+ A browser deploy writes the first `sysadmin` with the **verified email on
139
+ your Quickback account**, not a synthetic `owner@<app>.invalid` address.
140
+ Reset admin password still rotates the hash only — the broker never
141
+ `UPDATE`s that email afterwards. See [Owner access](/start/deploy-owner-access).
142
+
119
143
  ## v0.65.0 — August 16, 2026
120
144
 
121
145
  ### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
@@ -229,7 +253,9 @@ evaluation failed, and the underlying local error. This was previously the
229
253
  behavior of `contract.version: 'v2'` only.
230
254
 
231
255
  `quickback compile --allow-degraded-schemas` restores degrade-and-continue for a
232
- single compile. It prints every action that fell back and why.
256
+ single compile. It prints every action that fell back and why. (Removed in
257
+ 0.66.2 — it worked on a total harvest failure but still threw on a partial one,
258
+ the case it existed for.)
233
259
 
234
260
  The compiler also warns when a caller supplies no schemas at all — `rawFiles`
235
261
  callers such as the Start app cannot harvest — naming how many actions of the
@@ -28,7 +28,7 @@ export default defineConfig({
28
28
  });
29
29
  ```
30
30
 
31
- Run `quickback compile` and every endpoint above ships in the Worker.
31
+ Run `quickback build` and every endpoint above ships in the Worker.
32
32
 
33
33
  ## Opting out
34
34
 
@@ -146,7 +146,7 @@ When the compiler builds the Account SPA, it excludes route files for disabled f
146
146
 
147
147
  | Feature Flag | Routes Excluded When `false` |
148
148
  |-------------|------------------------------|
149
- | `auth.organizations` | Dashboard, organization CRUD, org switching (`$slug`) |
149
+ | `auth.organizations` | `/dashboard` (org list + invitations), organization CRUD, org switching (`$slug`) |
150
150
  | `auth.passkey` | Passkey management and setup |
151
151
  | `auth.admin` | Admin panel routes |
152
152
 
@@ -23,7 +23,7 @@ export default defineConfig({
23
23
 
24
24
  ## Discoverable options block
25
25
 
26
- After your first `quickback compile`, the file gets a managed block bracketed by sentinel comments:
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, // show the avatar upload UI on the profile page
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 compile --no-sync-config
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.
@@ -620,7 +625,8 @@ account: {
620
625
  |--------|------|-------------|
621
626
  | `domain` | `string` | Custom domain for Account UI (e.g., `auth.example.com`) |
622
627
  | `adminDomain` | `string` | Custom domain for admin-only access (e.g., `admin.example.com`). Serves the same Account SPA — the client-side router handles admin routing. |
623
- | `appUrl` | `string` | URL of the tenant's main application — where users are redirected after login. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Independent from `domain`. |
628
+ | `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for the profile **Go to…** picker. Independent from `domain`. A deploy-target `APP_URL` can override this at serve time. |
629
+ | `tenantPattern` | `string` | URL pattern for a tenant, with `{slug}` substituted. Default `/{slug}`. Relative patterns are resolved against `appUrl`; a full `https://{slug}.example.com` pattern is used as-is. Baked as `VITE_TENANT_URL_PATTERN`. |
624
630
  | `name` | `string` | App display name shown on login, profile, and email templates |
625
631
  | `companyName` | `string` | Company name for branding |
626
632
  | `tagline` | `string` | App tagline shown on login page |
@@ -638,7 +644,7 @@ Control which authentication features are exposed. Disabled features are exclude
638
644
  | `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
639
645
  | `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
640
646
  | `auth.signup` | `boolean` | `true` | `emailAndPassword.disableSignUp` (inverted) | Self-service account registration — false hides the UI **and** rejects the server endpoint with 403 |
641
- | `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (dashboard, invitations, roles). Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
647
+ | `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (`/dashboard` org list, invitations, roles). Sign-in lands on `/profile`. Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
642
648
  | `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
643
649
  | `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
644
650
 
@@ -100,12 +100,13 @@ single Postgres database with no bindings or split mode (see
100
100
  | `featuresBinding` | `string` | `"DB"` | Binding name for features database |
101
101
  | `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |
102
102
  | `authDatabaseId` | `string` | — | D1 database ID for the auth database |
103
+ | `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
104
  | `featuresDatabaseId` | `string` | — | Explicit features DB ID (falls back to `databaseId`) |
104
105
  | `filesDatabaseId` | `string` | — | D1 database ID for the files metadata database |
105
106
  | `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |
106
107
  | `auditBinding` | `string` | `"AUDIT_DB"` | Binding name for the security audit database |
107
108
  | `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
108
- | `auditDatabaseId` | `string` | — | Explicit D1 database ID for audit events |
109
+ | `auditDatabaseId` | `string` | — | D1 database ID for audit events. Optional at compile time — a placeholder is emitted and `quickback deploy` / the Start broker create the database and splice the real id back |
109
110
  | `experimentalRemote` | `{ auth?, features?, audit?, webhooks?, files? }` | `{}` | Per-binding `experimental_remote = true` flag for `wrangler dev` (see [below](#sharing-deployed-d1-in-dev-experimental_remote)) |
110
111
  | `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
111
112
  | `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
@@ -127,7 +128,9 @@ connection modes, RLS, and the migration workflow.
127
128
 
128
129
  Cross-tenant `unsafe` actions (see [Actions → Unsafe mode](/define/actions/scoped-db#unsafe-mode)) write mandatory audit events. Those events land in a dedicated D1 database — separate from your features DB — so audit history stays isolated from application data and can't be tampered with through a normal CRUD route.
129
130
 
130
- You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe action. To override defaults:
131
+ You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe, `PUBLIC`, or hard-delete action. Leave `auditDatabaseId` unset until deploy: compile emits a placeholder, and `quickback deploy` (or the Start Cloudflare card) creates the D1 and writes the id back. Do not put an empty string in the config.
132
+
133
+ To override defaults:
131
134
 
132
135
  ```typescript
133
136
  providers: {
@@ -139,7 +142,7 @@ providers: {
139
142
  }
140
143
  ```
141
144
 
142
- The binding name must match what your Worker reads at runtime. If you don't declare any unsafe actions, no audit DB is provisioned and these options have no effect.
145
+ The binding name must match what your Worker reads at runtime. If you don't declare any unsafe, `PUBLIC`, or hard-delete actions, no audit DB is provisioned and these options have no effect.
143
146
 
144
147
  #### Setting Database IDs for Deployment
145
148
 
@@ -25,9 +25,13 @@ export default defineConfig({
25
25
  });
26
26
  ```
27
27
 
28
- > **Use a Real Organization ID**
28
+ > **The organization must exist**
29
29
  >
30
- > `pinnedOrganizationId` must point at an organization that actually exists in your Better Auth data. The compiler does not create the organization for you.
30
+ > `pinnedOrganizationId` is the Better Auth organization id the compiled Worker hard-codes. The compiler does not insert that row.
31
+ >
32
+ > A **browser deploy** from Quickback Start does: the broker writes `organization.id` as this exact string, seeds `user.role = "sysadmin"`, and seats that user as `owner` of the org. `org_default` is a valid id — use it when you do not have a pre-existing org.
33
+ >
34
+ > A **CLI deploy** (`quickback deploy`) does not seed AUTH_DB. Create the organization yourself (or deploy once through Start) so the pin points at a real row.
31
35
 
32
36
 
33
37
  ## Removed Single-Tenant Settings
@@ -96,7 +100,7 @@ This is the intended replacement for the old single-tenant CMS flow.
96
100
  ## Migration from Single-Tenant Mode
97
101
 
98
102
  1. Remove `features.organizations: false`.
99
- 2. Add `features.pinnedOrganizationId: "<real-org-id>"`.
103
+ 2. Add `features.pinnedOrganizationId: "<org-id>"`. On a Start deploy, that string is the org the broker inserts — `"org_default"` is fine. On a CLI deploy, it must already exist in AUTH_DB.
100
104
  3. Remove any assumptions that `ctx.roles` mirrors `user.role`.
101
105
  4. If you need platform-wide roles, keep those checks on `userRole`, not `roles`.
102
106
 
@@ -19,13 +19,13 @@ The CLI authenticates via two methods:
19
19
 
20
20
  ```bash
21
21
  # Use the cloud compiler (default)
22
- quickback compile
22
+ quickback build
23
23
 
24
24
  # Use a local compiler instance
25
- QUICKBACK_API_URL=http://localhost:3000 quickback compile
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 compile
28
+ QUICKBACK_API_KEY=qb_key_... quickback build
29
29
  ```
30
30
 
31
31
  ## Compiler Service Variables
@@ -23,6 +23,9 @@ Start here. **Most apps need only the first row** — this page, and nothing bel
23
23
  > declare a relationship to ask "is this person in the org?" — a relationship's `from:` must
24
24
  > be one of *your* feature tables, and the compiler rejects one pointing at Better Auth's
25
25
  > `organization_memberships`. See [the authorization ladder](/define#the-authorization-ladder).
26
+ >
27
+ > To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
28
+ > see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
26
29
 
27
30
 
28
31
  ## Basic Usage
@@ -411,6 +414,13 @@ opaque 404 instead.
411
414
  Function-form access (`access: async (ctx, record) => ...`) is opaque to
412
415
  the pre-record phase and always passes there; it's fully evaluated post-record.
413
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
+
414
424
  ## Context Variables
415
425
 
416
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,11 @@ 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 compile` writes the same typed
58
+ > **Your editor is typed too.** `quickback build` writes the same typed
60
59
  > helpers into `quickback/features/<feature>/.quickback/` (plus a
61
60
  > `quickback/tsconfig.json`), so the import above resolves — and typechecks —
62
61
  > in the tree you actually edit, not just in the generated output. The helper
63
- > also **re-exports the feature's table** typed with the generated schema, so
62
+ > also **re-exports every table in the feature** typed with the generated schema, so
64
63
  > compiler-managed columns (`createdAt`, `modifiedBy`, `deletedAt`,
65
64
  > `organizationId`) are visible on it without casts:
66
65
  >
@@ -68,6 +67,10 @@ export default defineAction({
68
67
  > import { defineAction, applications } from "../.quickback/define-action";
69
68
  > ```
70
69
  >
70
+ > Other tables in the same feature come from that same helper. The boundary is
71
+ > the **feature**, not the whole project: a table owned by another feature is
72
+ > not re-exported here.
73
+ >
71
74
  > Prefer this single import over the older
72
75
  > `import { applications } from "../applications"` — that path resolves to
73
76
  > your authored file at edit time, which has no named export and none of the
@@ -75,6 +78,32 @@ export default defineAction({
75
78
  > `quickback/features/*/.quickback/` in `.gitignore` (new projects get this
76
79
  > automatically).
77
80
 
81
+ For an action that joins or writes a table owned by another feature, keep
82
+ `defineAction` from the action's own helper and import the other table
83
+ separately from its feature's generated helper (or generated table module).
84
+ Query operators come from the generated project `lib/q`, not from either
85
+ feature helper:
86
+
87
+ {/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
88
+ ```typescript
89
+ // features/waitlist/actions/promote.ts
90
+ import {
91
+ defineAction,
92
+ waitlistEntries,
93
+ } from "../.quickback/define-action";
94
+ import { reservations } from "../../reservations/.quickback/define-action";
95
+ import { q } from "../../../lib/q";
96
+
97
+ // `defineAction` stays bound to waitlistEntries; reservations is only a table.
98
+ // For a direct generated-table import, use "../../reservations/reservations".
99
+ ```
100
+
101
+ This waitlist/reservations shape is generic: for any cross-feature action, the
102
+ own-feature helper supplies the action's `record`, `whereRecord`, and
103
+ `whereTransition` context; each external feature supplies only its own tables.
104
+ Importing `defineAction` from the external feature would bind the wrong
105
+ context.
106
+
78
107
  ### Local action-schema harvest
79
108
 
80
109
  Before sending a compile request, the CLI loads each action in an isolated
@@ -96,9 +125,8 @@ generated clients treat every required field as optional, and unknown keys pass.
96
125
  Constructs it cannot parse at all degrade further, to a bare `{}` with no
97
126
  `properties`. Neither is visible in a diff.
98
127
 
99
- `--allow-degraded-schemas` restores the old degrade-and-continue behavior for a
100
- single compile. It still prints every action that fell back and why, and the
101
- compiler warns again with the count and sampled paths.
128
+ There is no opt-out. Fix the action so its input schema harvests — the error
129
+ names each one, the phase that failed, and the underlying local error.
102
130
 
103
131
  Bare imports are resolved from the generated runtime's configured
104
132
  `build.outputDir/node_modules` first. If definitions live in `quickback/` and
@@ -183,6 +211,7 @@ namespace parameters.
183
211
  | `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
212
  | `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
185
213
  | `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) |
214
+ | `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
215
  | `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
216
  | `cms` | No | Pass-through metadata blob for CMS surfaces |
188
217
 
@@ -243,4 +272,3 @@ export default defineAction({
243
272
  - Ref keys must exist on the inline `z.object` input with agreeing
244
273
  optionality; `as` names can't shadow reserved context keys. Injected rows
245
274
  are the **unmasked** DB rows (masking remains a read-projection concern).
246
-
@@ -169,7 +169,7 @@ is not supported.
169
169
  - **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
170
170
  - **[Record and standalone actions](/define/actions/record-and-standalone)** — the two shapes, and what `path:` changes
171
171
  - **[Access](/define/actions/access)** — roles, record conditions, context substitution, relationship-roles
172
- - **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, unsafe mode, raw SQL policy, sharing code
172
+ - **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, AUTH_DB vs `ctx`, unsafe mode, raw SQL policy, sharing code
173
173
  - **[Examples](/define/actions/examples)** — end-to-end action files
174
174
 
175
175
  Related: **[Transitions](/define/transitions)** for state-machine policy,
@@ -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
- **Route pattern:** Custom `path`
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