@quickback-dev/cli 0.16.5 → 0.18.0

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 (127) hide show
  1. package/README.md +7 -3
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +12 -48
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/commands/create.d.ts +20 -0
  6. package/dist/commands/create.d.ts.map +1 -1
  7. package/dist/commands/create.js +216 -151
  8. package/dist/commands/create.js.map +1 -1
  9. package/dist/commands/login.d.ts +4 -2
  10. package/dist/commands/login.d.ts.map +1 -1
  11. package/dist/commands/login.js +25 -17
  12. package/dist/commands/login.js.map +1 -1
  13. package/dist/commands/start.d.ts +20 -0
  14. package/dist/commands/start.d.ts.map +1 -0
  15. package/dist/commands/start.js +163 -0
  16. package/dist/commands/start.js.map +1 -0
  17. package/dist/commands/whoami.d.ts.map +1 -1
  18. package/dist/commands/whoami.js +5 -4
  19. package/dist/commands/whoami.js.map +1 -1
  20. package/dist/docs/content.js +42 -42
  21. package/dist/docs/content.js.map +1 -1
  22. package/dist/index.js +27 -10
  23. package/dist/index.js.map +1 -1
  24. package/dist/lib/api-client.js +1 -1
  25. package/dist/lib/api-client.js.map +1 -1
  26. package/dist/lib/api-client.test.js +15 -0
  27. package/dist/lib/api-client.test.js.map +1 -1
  28. package/dist/lib/auth.d.ts +39 -3
  29. package/dist/lib/auth.d.ts.map +1 -1
  30. package/dist/lib/auth.js +57 -3
  31. package/dist/lib/auth.js.map +1 -1
  32. package/dist/lib/drizzle-meta-routing.test.js +16 -3
  33. package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
  34. package/dist/lib/file-loader.d.ts +6 -4
  35. package/dist/lib/file-loader.d.ts.map +1 -1
  36. package/dist/lib/file-loader.js +30 -27
  37. package/dist/lib/file-loader.js.map +1 -1
  38. package/dist/lib/file-loader.test.js +16 -7
  39. package/dist/lib/file-loader.test.js.map +1 -1
  40. package/dist/skill/docs/changelog.md +429 -1100
  41. package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  42. package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
  43. package/dist/skill/docs/compiler/config/providers.md +87 -0
  44. package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
  45. package/dist/skill/docs/compiler/definitions/access.md +43 -57
  46. package/dist/skill/docs/compiler/definitions/feature.md +7 -11
  47. package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
  48. package/dist/skill/docs/compiler/definitions/guards.md +16 -18
  49. package/dist/skill/docs/compiler/definitions/index.md +10 -14
  50. package/dist/skill/docs/compiler/definitions/masking.md +6 -6
  51. package/dist/skill/docs/compiler/definitions/read.md +6 -11
  52. package/dist/skill/docs/compiler/definitions/schema.md +18 -18
  53. package/dist/skill/docs/compiler/definitions/views.md +3 -5
  54. package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
  55. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  56. package/dist/skill/docs/compiler/getting-started/index.md +23 -20
  57. package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
  58. package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
  59. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
  60. package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
  61. package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  66. package/dist/skill/docs/compiler/troubleshooting.md +10 -0
  67. package/dist/skill/docs/index.md +9 -0
  68. package/dist/skill/docs/stack/auth/security.md +69 -0
  69. package/dist/skill/docs/stack/cms/actions.md +28 -0
  70. package/dist/skill/docs/stack/cms/connecting.md +2 -2
  71. package/dist/skill/docs/stack/cms/index.md +2 -2
  72. package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
  73. package/dist/skill/docs/stack/cms/schema-format.md +33 -3
  74. package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
  75. package/dist/skill/docs/stack/cms/security.md +10 -12
  76. package/dist/skill/docs/stack/cms/table-views.md +1 -1
  77. package/dist/skill/docs/stack/index.md +8 -4
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
  79. package/dist/skill/docs/stack/realtime/index.md +20 -3
  80. package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
  81. package/dist/skill/docs/stack/vector/embeddings.md +7 -6
  82. package/package.json +1 -1
  83. package/src/skill/docs/changelog.md +486 -1097
  84. package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  85. package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
  86. package/src/skill/docs/compiler/config/domains.md +44 -10
  87. package/src/skill/docs/compiler/config/output.md +1 -1
  88. package/src/skill/docs/compiler/config/providers.md +87 -0
  89. package/src/skill/docs/compiler/config/single-tenant.md +5 -11
  90. package/src/skill/docs/compiler/definitions/access.md +43 -57
  91. package/src/skill/docs/compiler/definitions/feature.md +7 -11
  92. package/src/skill/docs/compiler/definitions/firewall.md +2 -4
  93. package/src/skill/docs/compiler/definitions/guards.md +16 -18
  94. package/src/skill/docs/compiler/definitions/index.md +10 -14
  95. package/src/skill/docs/compiler/definitions/masking.md +6 -6
  96. package/src/skill/docs/compiler/definitions/read.md +6 -11
  97. package/src/skill/docs/compiler/definitions/schema.md +18 -18
  98. package/src/skill/docs/compiler/definitions/views.md +3 -5
  99. package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
  100. package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  101. package/src/skill/docs/compiler/getting-started/index.md +23 -20
  102. package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
  103. package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
  104. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
  105. package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
  106. package/src/skill/docs/compiler/getting-started/templates.md +58 -56
  107. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  108. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  109. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  110. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  111. package/src/skill/docs/compiler/troubleshooting.md +10 -0
  112. package/src/skill/docs/index.md +9 -0
  113. package/src/skill/docs/stack/auth/plugins/index.md +74 -0
  114. package/src/skill/docs/stack/auth/security.md +69 -0
  115. package/src/skill/docs/stack/cms/actions.md +28 -0
  116. package/src/skill/docs/stack/cms/connecting.md +2 -2
  117. package/src/skill/docs/stack/cms/index.md +2 -2
  118. package/src/skill/docs/stack/cms/record-layouts.md +19 -19
  119. package/src/skill/docs/stack/cms/schema-format.md +33 -3
  120. package/src/skill/docs/stack/cms/schema-registry.md +22 -2
  121. package/src/skill/docs/stack/cms/security.md +10 -12
  122. package/src/skill/docs/stack/cms/table-views.md +1 -1
  123. package/src/skill/docs/stack/index.md +8 -4
  124. package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
  125. package/src/skill/docs/stack/realtime/index.md +20 -3
  126. package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
  127. package/src/skill/docs/stack/vector/embeddings.md +7 -6
@@ -5,33 +5,58 @@ The Quickback CLI is the fastest way to create, compile, and manage your backend
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
+ # One-shot via npx — recommended for first run
9
+ npx @quickback-dev/cli start
10
+
11
+ # Or install globally for repeat use
8
12
  npm install -g @quickback-dev/cli
9
13
  ```
10
14
 
11
15
  ## Commands
12
16
 
13
- ### Create a Project
17
+ ### Start a Project (interactive)
18
+
19
+ ```bash
20
+ quickback start
21
+ ```
22
+
23
+ Interactive onboarding designed for new users. No flags required.
24
+
25
+ - Prompts for a template (curated free-tier picker: `cloudflare`, `todos`, `blog`, `empty`)
26
+ - Prompts for a project name (defaults to the current directory's name if empty)
27
+ - Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
28
+ - Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later
29
+
30
+ **Example:**
31
+ ```bash
32
+ mkdir my-app && cd my-app
33
+ npx @quickback-dev/cli start
34
+ ```
35
+
36
+ ### Create a Project (scriptable)
14
37
 
15
38
  ```bash
16
39
  quickback create <template> <name>
17
40
  ```
18
41
 
19
42
  **Templates:**
20
- - `cloudflare` - Cloudflare Workers + D1 + Better Auth (free)
21
- - `supabase` - Hono + Supabase Postgres + Supabase Auth (free)
22
- - `blog` - Single-tenant blog (PUBLIC reads, admin writes) (free)
23
- - `empty` - Cloudflare scaffold, no example features (free)
24
- - `multi-tenant` - Full SaaS with orgs, teams, billing (pro)
43
+ - `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
44
+ - `todos` — Working todos example with masking + actions + a named view (free)
45
+ - `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
46
+ - `empty` — Cloudflare scaffold, no example features (free)
47
+ - `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime (pro)
25
48
 
26
49
  **Example:**
27
50
  ```bash
28
- quickback create cloudflare my-app
51
+ quickback create todos my-app
29
52
  ```
30
53
 
31
54
  This scaffolds a complete project with:
32
- - `quickback.config.ts` - Project configuration
33
- - `quickback/features/` - Your table definitions
34
- - Example todos feature with full security configuration
55
+ - `quickback.config.ts` — Project configuration
56
+ - `quickback/features/` — Your table definitions
57
+ - Example feature with full security configuration (for `todos` / `blog` / `saas`)
58
+
59
+ See the [Templates](/compiler/getting-started/templates) page for a deeper guide on choosing between them.
35
60
 
36
61
  ### Compile Definitions
37
62
 
@@ -68,19 +93,6 @@ ls quickback/.archives/
68
93
 
69
94
  As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.
70
95
 
71
- ### Initialize Structure
72
-
73
- ```bash
74
- quickback init
75
- ```
76
-
77
- Creates the Quickback folder structure in an existing project:
78
- ```
79
- quickback/
80
- features/
81
- quickback.config.ts
82
- ```
83
-
84
96
  ### View Documentation
85
97
 
86
98
  ```bash
@@ -209,18 +221,27 @@ The active organization is stored in your credentials and sent with compile requ
209
221
  ## Quick Start
210
222
 
211
223
  ```bash
212
- # 1. Create a new project
213
- quickback create cloudflare my-app
214
- cd my-app
224
+ # 1. Start a new project (interactive — picks template, scaffolds,
225
+ # prompts for login only when needed)
226
+ mkdir my-app && cd my-app
227
+ npx @quickback-dev/cli start
228
+
229
+ # 2. Run locally
230
+ npm run dev
231
+ ```
215
232
 
216
- # 2. Define your tables in quickback/features/
217
- # (Already has example todos feature)
233
+ Or the scriptable form:
218
234
 
219
- # 3. Compile
220
- quickback compile
235
+ ```bash
236
+ # 1. Create the project (scaffolds + compiles + installs)
237
+ quickback create todos my-app # prompts for login on first compile
238
+ cd my-app
221
239
 
222
- # 4. Run
240
+ # 2. Run
223
241
  npm run dev
242
+
243
+ # 3. Recompile after editing definitions
244
+ quickback compile
224
245
  ```
225
246
 
226
247
  ## Options
@@ -278,9 +299,9 @@ Make sure the CLI is installed globally:
278
299
  npm install -g @quickback-dev/cli
279
300
  ```
280
301
 
281
- Or use npx:
302
+ Or use npx (no global install needed):
282
303
  ```bash
283
- npx @quickback-dev/cli create cloudflare my-app
304
+ npx @quickback-dev/cli start
284
305
  ```
285
306
 
286
307
  ### Compile errors
@@ -24,18 +24,18 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
24
24
  ## Quick Start
25
25
 
26
26
  ```bash
27
- # 1. Install the CLI
28
- npm install -g @quickback-dev/cli
27
+ # 1. Scaffold + compile interactively
28
+ mkdir my-app && cd my-app
29
+ npx @quickback-dev/cli start
30
+ ```
29
31
 
30
- # 2. Create a project
32
+ `start` walks through template selection, scaffolding, login (only when needed), and the first compile in one flow. Or do it scriptably:
33
+
34
+ ```bash
35
+ npm install -g @quickback-dev/cli
31
36
  quickback create cloudflare my-app
32
37
  cd my-app
33
-
34
- # 3. Log in
35
- quickback login
36
-
37
- # 4. Compile
38
- quickback compile
38
+ quickback compile # prompts for login on the first run
39
39
  ```
40
40
 
41
41
  ## Existing Databases
@@ -18,6 +18,49 @@ providers: {
18
18
  }
19
19
  ```
20
20
 
21
+ ### Runtime Options
22
+
23
+ | Option | Type | Description |
24
+ |--------|------|-------------|
25
+ | `compatibilityDate` | `string` | Emits Cloudflare `compatibility_date` in `wrangler.toml`. |
26
+ | `placement.mode` | `"smart" \| "standard"` | Emits Cloudflare's `[placement]` block. |
27
+ | `observability.enabled` | `boolean` | Emits top-level Workers Logs persistence under `[observability]`. |
28
+ | `observability.headSamplingRate` | `number` | Top-level Workers Logs sample rate from `0` to `1`. |
29
+ | `observability.logs.enabled` | `boolean` | Emits `[observability.logs]`. |
30
+ | `observability.logs.invocationLogs` | `boolean` | Enables or suppresses invocation logs. |
31
+ | `observability.logs.destinations` | `string[]` | Named log export destinations configured in Cloudflare. |
32
+ | `observability.logs.headSamplingRate` | `number` | Workers Logs sample rate from `0` to `1`. |
33
+ | `observability.logs.persist` | `boolean` | Keeps exported logs in the Cloudflare dashboard. |
34
+ | `observability.traces.enabled` | `boolean` | Emits `[observability.traces]`. |
35
+ | `observability.traces.destinations` | `string[]` | Named trace export destinations configured in Cloudflare. |
36
+ | `observability.traces.headSamplingRate` | `number` | Workers Traces sample rate from `0` to `1`. |
37
+ | `observability.traces.persist` | `boolean` | Keeps exported traces in the Cloudflare dashboard. |
38
+ | `routes` | `{ pattern, custom_domain? }[]` | Custom domain routes for the generated Worker. |
39
+
40
+ ```typescript
41
+ providers: {
42
+ runtime: defineRuntime("cloudflare", {
43
+ compatibilityDate: "2026-05-13",
44
+ placement: { mode: "smart" },
45
+ observability: {
46
+ enabled: true,
47
+ logs: {
48
+ enabled: true,
49
+ invocationLogs: false,
50
+ destinations: ["logs-prod"],
51
+ headSamplingRate: 0.6,
52
+ },
53
+ traces: {
54
+ enabled: true,
55
+ destinations: ["otel-prod"],
56
+ headSamplingRate: 0.05,
57
+ persist: false,
58
+ },
59
+ },
60
+ }),
61
+ }
62
+ ```
63
+
21
64
  ## Database Providers
22
65
 
23
66
  | Provider | Description |
@@ -59,6 +102,7 @@ providers: {
59
102
  | `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
60
103
  | `auditDatabaseId` | `string` | — | Explicit D1 database ID for audit events |
61
104
  | `experimentalRemote` | `{ auth?, features?, audit?, webhooks?, files? }` | `{}` | Per-binding `experimental_remote = true` flag for `wrangler dev` (see [below](#sharing-deployed-d1-in-dev-experimental_remote)) |
105
+ | `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
62
106
  | `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
63
107
 
64
108
  #### Audit Database
@@ -125,6 +169,49 @@ Only `true` flips the flag on; `false` or omitted leaves the binding local. Off
125
169
  > `experimental_remote` is a Wrangler dev feature. A flagged binding hits the deployed D1 from `wrangler dev`, so any write goes to production. Only enable for bindings you've decided are safe to read/write from local dev.
126
170
 
127
171
 
172
+ #### Realtime Broadcast Config
173
+
174
+ Set `realtime: true` to enable the generated Broadcaster Durable Object with the default organization-scoped routing model:
175
+
176
+ ```typescript
177
+ providers: {
178
+ database: defineDatabase("cloudflare-d1", {
179
+ realtime: true,
180
+ }),
181
+ }
182
+ ```
183
+
184
+ For relationship-authorized resource scopes, use the object form:
185
+
186
+ ```typescript
187
+ providers: {
188
+ database: defineDatabase("cloudflare-d1", {
189
+ realtime: {
190
+ wsTicket: {
191
+ role: "attendee",
192
+ requestField: "eventId",
193
+ scopeTable: "events",
194
+ },
195
+ },
196
+ }),
197
+ }
198
+ ```
199
+
200
+ `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
201
+
202
+ - `role`: an authz role declared under `authz.roles` that uses a direct relationship (`{ via: "..." }`)
203
+ - `requestField`: the JSON body field the client posts to `/broadcast/v1/ws-ticket`
204
+ - `scopeTable`: the parent resource table that defines the broadcast scope key
205
+
206
+ In other words: the relationship table proves access, and the `scopeTable` row defines the channel. For an attendee flow, `guests` (or RSVP) would be the relationship evidence and `events` would be the `scopeTable`.
207
+
208
+ Quickback keeps Better Auth as the front door, then mints its own 60-second websocket ticket after the authz check succeeds. The generated `createRealtime()` helper and Broadcaster share the same targeting model:
209
+
210
+ - string target: historical `organizationId` shorthand
211
+ - object target: `{ scopeKey?, organizationId?, userId? }`
212
+
213
+ See [Realtime](/stack/realtime) for the client-side connection flow and helper examples.
214
+
128
215
  <Callout>
129
216
  `usePlurals` only affects **auth tables** generated by Better Auth (e.g. `user` vs `users`, `session` vs `sessions`). Feature table names come directly from your Drizzle schema definitions — whatever you pass to `sqliteTable()` or `pgTable()` is used as-is. The `namingConvention` setting applies to both auth and feature column names.
130
217
  </Callout>
@@ -46,9 +46,7 @@ export default defineTable(posts, {
46
46
  read: {
47
47
  access: { roles: ['user', 'admin'] },
48
48
  },
49
- crud: {
50
- create: { access: { roles: ['admin'] } },
51
- },
49
+ create: { access: { roles: ['admin'] } },
52
50
  });
53
51
 
54
52
  // Public data (no ownership filtering)
@@ -57,11 +55,9 @@ export default defineTable(pages, {
57
55
  read: {
58
56
  access: { roles: ['PUBLIC'] },
59
57
  },
60
- crud: {
61
- create: { access: { roles: ['admin'] } },
62
- update: { access: { roles: ['admin'] } },
63
- delete: { access: { roles: ['admin'] } },
64
- },
58
+ create: { access: { roles: ['admin'] } },
59
+ update: { access: { roles: ['admin'] } },
60
+ delete: { access: { roles: ['admin'] } },
65
61
  });
66
62
  ```
67
63
 
@@ -76,9 +72,7 @@ Use the `PUBLIC` role to expose routes without authentication. This works the sa
76
72
  read: {
77
73
  access: { roles: ['PUBLIC'] }, // GET / and GET /:id — no auth required
78
74
  },
79
- crud: {
80
- create: { access: { roles: ['admin'] } }, // Admin only
81
- }
75
+ create: { access: { roles: ['admin'] } }, // Admin only
82
76
  ```
83
77
 
84
78
  ## Role-Based Access
@@ -1,6 +1,6 @@
1
1
  # Access - Role & Condition-Based Access Control
2
2
 
3
- Define who can perform CRUD operations and under what conditions.
3
+ Define who can perform read and write operations and under what conditions.
4
4
 
5
5
  ## Basic Usage
6
6
 
@@ -24,11 +24,9 @@ export default defineTable(applications, {
24
24
  read: {
25
25
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
26
26
  },
27
- crud: {
28
- create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
29
- update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
30
- delete: { access: { roles: ["owner", "hiring-manager"] } },
31
- },
27
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
28
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
29
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
32
30
  });
33
31
  ```
34
32
 
@@ -51,10 +49,8 @@ Then in your resource definitions:
51
49
 
52
50
  ```typescript
53
51
  read: { access: { roles: ["member+"] } }, // member, admin, owner
54
- crud: {
55
- create: { access: { roles: ["admin+"] } }, // admin, owner
56
- delete: { access: { roles: ["owner"] } }, // owner only (no +)
57
- }
52
+ create: { access: { roles: ["admin+"] } }, // admin, owner
53
+ delete: { access: { roles: ["owner"] } }, // owner only (no +)
58
54
  ```
59
55
 
60
56
  The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
@@ -118,11 +114,9 @@ access: {
118
114
 
119
115
  // CMS-internal resource: only platform admins
120
116
  read: { access: { userRole: ['admin'] } },
121
- crud: {
122
- create: { access: { userRole: ['admin'] } },
123
- update: { access: { userRole: ['admin'] } },
124
- delete: { access: { userRole: ['admin'] } },
125
- }
117
+ create: { access: { userRole: ['admin'] } },
118
+ update: { access: { userRole: ['admin'] } },
119
+ delete: { access: { userRole: ['admin'] } },
126
120
  ```
127
121
 
128
122
  When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
@@ -153,7 +147,7 @@ access: { roles: ["PUBLIC"] }
153
147
 
154
148
  **Important:**
155
149
  - `PUBLIC` skips authentication and role checks — anyone can call the endpoint
156
- - **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, CRUD writes (`crud.create`/`update`/`delete`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous CRUD endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
150
+ - **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
157
151
  - **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
158
152
  - Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
159
153
  - The wildcard `"*"` is **not supported** — using it throws a compile-time error
@@ -172,9 +166,7 @@ The firewall WHERE clause is always enforced. If no `organizationId` is provided
172
166
  export default defineTable(listings, {
173
167
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
174
168
  read: { access: { roles: ["PUBLIC"] } }, // Public browsing + detail
175
- crud: {
176
- create: { access: { roles: ["admin", "member"] } }, // Auth required to create
177
- },
169
+ create: { access: { roles: ["admin", "member"] } }, // Auth required to create
178
170
  });
179
171
  ```
180
172
 
@@ -196,11 +188,9 @@ Use `roles: ["USER"]` for resources where each user only sees their own records.
196
188
  export default defineTable(todos, {
197
189
  firewall: [{ field: 'userId', equals: 'ctx.userId' }],
198
190
  read: { access: { roles: ["USER"] } },
199
- crud: {
200
- create: { access: { roles: ["USER"] } },
201
- update: { access: { roles: ["USER"] } },
202
- delete: { access: { roles: ["USER"] } },
203
- },
191
+ create: { access: { roles: ["USER"] } },
192
+ update: { access: { roles: ["USER"] } },
193
+ delete: { access: { roles: ["USER"] } },
204
194
  });
205
195
  ```
206
196
 
@@ -444,9 +434,9 @@ The validator and resolver reject:
444
434
  - `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
445
435
  - Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
446
436
 
447
- ## Read & CRUD Configuration
437
+ ## Read & Write Configuration
448
438
 
449
- Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under `crud:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
439
+ Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
450
440
 
451
441
  ```typescript
452
442
  read: {
@@ -462,35 +452,33 @@ read: {
462
452
  },
463
453
  }
464
454
 
465
- crud: {
455
+ create: {
466
456
  // CREATE - POST /resource
467
- create: {
468
- access: { roles: ["owner", "hiring-manager", "recruiter"] },
469
- defaults: { // Default values for new records
470
- stage: 'applied',
471
- },
457
+ access: { roles: ["owner", "hiring-manager", "recruiter"] },
458
+ defaults: { // Default values for new records
459
+ stage: 'applied',
472
460
  },
461
+ },
473
462
 
463
+ update: {
474
464
  // UPDATE - PATCH /resource/:id
475
- update: {
476
- access: {
477
- or: [
478
- { roles: ["hiring-manager", "recruiter"] },
479
- { roles: ["interviewer"], record: { stage: { equals: "interview" } } }
480
- ]
481
- },
465
+ access: {
466
+ or: [
467
+ { roles: ["hiring-manager", "recruiter"] },
468
+ { roles: ["interviewer"], record: { stage: { equals: "interview" } } }
469
+ ]
482
470
  },
471
+ },
483
472
 
473
+ delete: {
484
474
  // DELETE - DELETE /resource/:id
485
- delete: {
486
- access: { roles: ["owner", "hiring-manager"] },
487
- mode: "soft", // 'soft' (default) or 'hard'
488
- },
475
+ access: { roles: ["owner", "hiring-manager"] },
476
+ mode: "soft", // 'soft' (default) or 'hard'
477
+ },
489
478
 
479
+ upsert: {
490
480
  // PUT - PUT /resource/:id (only when generateId: false + guards: false)
491
- put: {
492
- access: { roles: ["hiring-manager", "sync-service"] },
493
- },
481
+ access: { roles: ["hiring-manager", "sync-service"] },
494
482
  }
495
483
  ```
496
484
 
@@ -601,17 +589,15 @@ access: {
601
589
  For complex access logic that can't be expressed declaratively, use a function:
602
590
 
603
591
  ```typescript
604
- crud: {
605
- update: {
606
- access: async (ctx, record) => {
607
- // Custom logic - return true to allow, false to deny
608
- if (ctx.roles.includes('admin')) return true;
609
- if (record.ownerId === ctx.userId) return true;
610
-
611
- // Check custom business logic
612
- const membership = await checkTeamMembership(ctx.userId, record.teamId);
613
- return membership.canEdit;
614
- }
592
+ update: {
593
+ access: async (ctx, record) => {
594
+ // Custom logic - return true to allow, false to deny
595
+ if (ctx.roles.includes('admin')) return true;
596
+ if (record.ownerId === ctx.userId) return true;
597
+
598
+ // Check custom business logic
599
+ const membership = await checkTeamMembership(ctx.userId, record.teamId);
600
+ return membership.canEdit;
615
601
  }
616
602
  }
617
603
  ```
@@ -19,11 +19,9 @@ export const contacts = q.table("contacts", {
19
19
  export default defineTable(contacts, {
20
20
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
21
21
  read: { access: { roles: ["member+"] } },
22
- crud: {
23
- create: { access: { roles: ["member+"] } },
24
- update: { access: { roles: ["member+"] } },
25
- delete: { access: { roles: ["admin+"] }, mode: "soft" },
26
- },
22
+ create: { access: { roles: ["member+"] } },
23
+ update: { access: { roles: ["member+"] } },
24
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
27
25
  guards: { createable: ["address", "name"] },
28
26
  });
29
27
 
@@ -44,11 +42,9 @@ export default feature("contacts", {
44
42
  },
45
43
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
46
44
  read: { access: { roles: ["member+"] } },
47
- crud: {
48
- create: { access: { roles: ["member+"] } },
49
- update: { access: { roles: ["member+"] } },
50
- delete: { access: { roles: ["admin+"] }, mode: "soft" },
51
- },
45
+ create: { access: { roles: ["member+"] } },
46
+ update: { access: { roles: ["member+"] } },
47
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
52
48
  guards: { createable: ["address", "name"] },
53
49
  });
54
50
  ```
@@ -57,7 +53,7 @@ Type inference still works — `typeof import("./contacts").default.$infer` give
57
53
 
58
54
  ## How it works
59
55
 
60
- `feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts, CRUD routes, OpenAPI, MCP tools, RLS emission — runs on the same Drizzle source it always did. Zero runtime cost; zero semantic difference from `q.table()` + `defineTable()`.
56
+ `feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts, generated routes, OpenAPI, MCP tools, RLS emission — runs on the same Drizzle source it always did. Zero runtime cost; zero semantic difference from `q.table()` + `defineTable()`.
61
57
 
62
58
  That means:
63
59
 
@@ -341,10 +341,8 @@ export default defineTable(jobs, {
341
341
  // via record-level access conditions on /:id
342
342
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
343
343
  },
344
- crud: {
345
- // Use record conditions to allow public jobs OR owned jobs on GET /:id
346
- // (single-record GET inherits read.access, with optional record-level overrides)
347
- },
344
+ // Use record conditions to allow public jobs OR owned jobs on GET /:id
345
+ // (single-record GET inherits read.access, with optional record-level overrides)
348
346
  // ...
349
347
  });
350
348
  ```
@@ -29,9 +29,9 @@ export default defineTable(applications, {
29
29
  },
30
30
  immutable: ["appliedAt", "candidateId", "jobId"],
31
31
  },
32
- crud: {
33
- // ...
34
- },
32
+ create: { /* ... */ },
33
+ update: { /* ... */ },
34
+ delete: { /* ... */ },
35
35
  });
36
36
  ```
37
37
 
@@ -59,7 +59,7 @@ guards: {
59
59
  |------|------------------|
60
60
  | `createable` | Fields allowed in create (POST) request body |
61
61
  | `updatable` | Fields allowed in update (PATCH) request body |
62
- | `protected` | Fields blocked from CRUD, only modifiable via named actions |
62
+ | `protected` | Fields blocked from direct writes, only modifiable via named actions |
63
63
  | `immutable` | Fields allowed on create, blocked on all updates |
64
64
 
65
65
  **Combining lists:**
@@ -130,21 +130,21 @@ guards: {
130
130
  guards: false // Only system fields protected
131
131
  ```
132
132
 
133
- When `guards: false` is set, all user-defined fields become writable via CRUD operations. This is useful for:
133
+ When `guards: false` is set, all user-defined fields become writable via direct create/update/upsert operations. This is useful for:
134
134
  - External sync scenarios where you need full field control
135
135
  - Batch upsert operations where field restrictions would be limiting
136
136
  - Simple tables where field-level protection isn't needed
137
137
 
138
- ## PUT/Upsert with External IDs
138
+ ## Upsert with External IDs
139
139
 
140
- When you disable guards AND use client-provided IDs, you unlock PUT (upsert) operations. This is designed for **syncing data from external systems**.
140
+ When you disable guards AND use client-provided IDs, you unlock upsert operations. This is designed for **syncing data from external systems**.
141
141
 
142
- ### Requirements for PUT
142
+ ### Requirements for Upsert
143
143
 
144
144
  1. `generateId: false` in database config (client provides IDs)
145
145
  2. `guards: false` in resource definition
146
146
 
147
- ### How PUT Works
147
+ ### How Upsert Works
148
148
 
149
149
  ```
150
150
  PUT /resource/:id
@@ -158,7 +158,7 @@ PUT /resource/:id
158
158
  // quickback.config.ts
159
159
  export default {
160
160
  database: {
161
- generateId: false, // Client provides IDs (enables PUT)
161
+ generateId: false, // Client provides IDs (enables upsert)
162
162
  // Other options: 'uuid' | 'cuid' | 'nanoid' | 'short' | 'prefixed' | 'serial'
163
163
  }
164
164
  };
@@ -171,10 +171,8 @@ export default {
171
171
  export default defineTable(atsImports, {
172
172
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
173
173
  guards: false, // Disables field restrictions
174
- crud: {
175
- put: {
176
- access: { roles: ['hiring-manager', 'sync-service'] }
177
- }
174
+ upsert: {
175
+ access: { roles: ['hiring-manager', 'sync-service'] }
178
176
  },
179
177
  });
180
178
  ```
@@ -192,7 +190,7 @@ So `guards: false` only opens up user-defined business fields. Tenant scope and
192
190
 
193
191
  ## Ownership Auto-Population
194
192
 
195
- When PUT creates a new record, ownership fields are auto-set from context:
193
+ When upsert creates a new record, ownership fields are auto-set from context:
196
194
 
197
195
  ```typescript
198
196
  // Client sends: PUT /ats-imports/ext-123 { candidateName: "Jane Doe" }
@@ -208,9 +206,9 @@ When PUT creates a new record, ownership fields are auto-set from context:
208
206
  }
209
207
  ```
210
208
 
211
- ## Use Cases for PUT/External IDs
209
+ ## Use Cases for Upsert/External IDs
212
210
 
213
- | Use Case | Why PUT? |
211
+ | Use Case | Why upsert? |
214
212
  |----------|----------|
215
213
  | External API sync | External system controls the ID |
216
214
  | Webhook handlers | Events come with their own IDs |
@@ -220,7 +218,7 @@ When PUT creates a new record, ownership fields are auto-set from context:
220
218
 
221
219
  ## ID Generation Options
222
220
 
223
- | `generateId` | PUT Available? | Notes |
221
+ | `generateId` | Upsert Available? | Notes |
224
222
  |--------------|----------------|-------|
225
223
  | `'uuid'` | No | Server generates UUID |
226
224
  | `'cuid'` | No | Server generates CUID |