@quickback-dev/cli 0.16.5 → 0.17.1

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 (114) 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 +37 -37
  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 +145 -0
  41. package/dist/skill/docs/compiler/config/providers.md +87 -0
  42. package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
  43. package/dist/skill/docs/compiler/definitions/access.md +43 -57
  44. package/dist/skill/docs/compiler/definitions/feature.md +7 -11
  45. package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
  46. package/dist/skill/docs/compiler/definitions/guards.md +16 -18
  47. package/dist/skill/docs/compiler/definitions/index.md +10 -14
  48. package/dist/skill/docs/compiler/definitions/masking.md +6 -6
  49. package/dist/skill/docs/compiler/definitions/read.md +6 -11
  50. package/dist/skill/docs/compiler/definitions/schema.md +18 -18
  51. package/dist/skill/docs/compiler/definitions/views.md +3 -5
  52. package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
  53. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  54. package/dist/skill/docs/compiler/getting-started/index.md +23 -20
  55. package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
  56. package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
  57. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
  58. package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  63. package/dist/skill/docs/compiler/troubleshooting.md +10 -0
  64. package/dist/skill/docs/stack/auth/security.md +69 -0
  65. package/dist/skill/docs/stack/cms/actions.md +28 -0
  66. package/dist/skill/docs/stack/cms/connecting.md +2 -2
  67. package/dist/skill/docs/stack/cms/index.md +2 -2
  68. package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
  69. package/dist/skill/docs/stack/cms/schema-format.md +33 -3
  70. package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
  71. package/dist/skill/docs/stack/cms/security.md +10 -12
  72. package/dist/skill/docs/stack/cms/table-views.md +1 -1
  73. package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
  74. package/dist/skill/docs/stack/realtime/index.md +20 -3
  75. package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
  76. package/dist/skill/docs/stack/vector/embeddings.md +7 -6
  77. package/package.json +1 -1
  78. package/src/skill/docs/changelog.md +145 -0
  79. package/src/skill/docs/compiler/config/providers.md +87 -0
  80. package/src/skill/docs/compiler/config/single-tenant.md +5 -11
  81. package/src/skill/docs/compiler/definitions/access.md +43 -57
  82. package/src/skill/docs/compiler/definitions/feature.md +7 -11
  83. package/src/skill/docs/compiler/definitions/firewall.md +2 -4
  84. package/src/skill/docs/compiler/definitions/guards.md +16 -18
  85. package/src/skill/docs/compiler/definitions/index.md +10 -14
  86. package/src/skill/docs/compiler/definitions/masking.md +6 -6
  87. package/src/skill/docs/compiler/definitions/read.md +6 -11
  88. package/src/skill/docs/compiler/definitions/schema.md +18 -18
  89. package/src/skill/docs/compiler/definitions/views.md +3 -5
  90. package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
  91. package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  92. package/src/skill/docs/compiler/getting-started/index.md +23 -20
  93. package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
  94. package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
  95. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
  96. package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
  97. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  98. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  100. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  101. package/src/skill/docs/compiler/troubleshooting.md +10 -0
  102. package/src/skill/docs/stack/auth/security.md +69 -0
  103. package/src/skill/docs/stack/cms/actions.md +28 -0
  104. package/src/skill/docs/stack/cms/connecting.md +2 -2
  105. package/src/skill/docs/stack/cms/index.md +2 -2
  106. package/src/skill/docs/stack/cms/record-layouts.md +19 -19
  107. package/src/skill/docs/stack/cms/schema-format.md +33 -3
  108. package/src/skill/docs/stack/cms/schema-registry.md +22 -2
  109. package/src/skill/docs/stack/cms/security.md +10 -12
  110. package/src/skill/docs/stack/cms/table-views.md +1 -1
  111. package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
  112. package/src/skill/docs/stack/realtime/index.md +20 -3
  113. package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
  114. package/src/skill/docs/stack/vector/embeddings.md +7 -6
@@ -2,29 +2,34 @@
2
2
 
3
3
  Get started with Quickback in minutes. This guide shows you how to define a complete table with security configuration.
4
4
 
5
- ## Install the CLI
5
+ ## Start a Project
6
6
 
7
7
  ```bash
8
- npm install -g @quickback-dev/cli
8
+ mkdir my-app && cd my-app
9
+ npx @quickback-dev/cli start
9
10
  ```
10
11
 
11
- ## Create a Project
12
+ `quickback start` is interactive — it asks for a template and project name, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; finish later with `quickback login && quickback compile`.
13
+
14
+ Prefer a scriptable form?
12
15
 
13
16
  ```bash
17
+ npm install -g @quickback-dev/cli
14
18
  quickback create cloudflare my-app
15
19
  cd my-app
16
20
  ```
17
21
 
18
- This scaffolds a complete project with:
22
+ Both paths scaffold the same project:
19
23
  - `quickback.config.ts` — Project configuration
20
24
  - `quickback/features/` — Your table definitions
21
- - Example feature with full security configuration
25
+ - Working example feature with full security configuration (when you pick `todos`/`blog`/`saas`)
22
26
 
23
27
  **Available templates:**
24
- - `cloudflare` — Cloudflare Workers + D1 + Better Auth (free)
25
- - `blog` — Single-tenant blog (PUBLIC reads, admin writes) (free)
28
+ - `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
29
+ - `todos` — Working CRUD example with masking + actions (free)
30
+ - `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
26
31
  - `empty` — Cloudflare scaffold, no example features (free)
27
- - `multi-tenant` — Full SaaS with orgs, teams, billing (pro)
32
+ - `saas` — Full B2B SaaS with orgs, R2 file storage, webhooks (pro)
28
33
 
29
34
  ## File Structure
30
35
 
@@ -77,16 +82,14 @@ export default feature('jobs', {
77
82
  pageSize: 25,
78
83
  },
79
84
 
80
- // 4. CRUD — Write operations
81
- crud: {
82
- create: { access: { roles: ["owner", "hiring-manager"] } },
83
- update: { access: { roles: ["owner", "hiring-manager"] } },
84
- delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
85
- },
85
+ // 4. WRITE OPERATIONS
86
+ create: { access: { roles: ["owner", "hiring-manager"] } },
87
+ update: { access: { roles: ["owner", "hiring-manager"] } },
88
+ delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
86
89
  });
87
90
  ```
88
91
 
89
- One import, one export, every security layer declared in one place. Secure by default — no CRUD routes ship until you opt in with `crud: { … }`.
92
+ One import, one export, every security layer declared in one place. Secure by default — no write routes ship until you opt in with top-level `create`, `update`, `delete`, or `upsert`.
90
93
 
91
94
  ### Alternatives — same result, different shape
92
95
 
@@ -117,21 +120,21 @@ See [feature() — single-export sugar](/compiler/definitions/feature) and [Sche
117
120
 
118
121
  1. **Firewall**: Automatically adds `WHERE organizationId = ?` to every query. Users in Org A can never see Org B's data.
119
122
  2. **Guards**: Controls which fields can be modified — `createable` for POST, `updatable` for PATCH, `protected` for action-only fields.
120
- 3. **CRUD Access**: Role-based access control for each operation. All roles can read, only hiring managers can write.
123
+ 3. **Write Access**: Role-based access control for each operation. All roles can read, only hiring managers can write.
121
124
 
122
125
  ## Compile and Run
123
126
 
124
127
  ```bash
125
- # Log in (first time only)
126
- quickback login
127
-
128
- # Compile your definitions
128
+ # Compile your definitions — prompts you to sign in or sign up
129
+ # if you haven't already (no separate `quickback login` step needed)
129
130
  quickback compile
130
131
 
131
132
  # Run locally
132
133
  npm run dev
133
134
  ```
134
135
 
136
+ The first compile prompts for an account; subsequent compiles re-use the stored session.
137
+
135
138
  ## Generated Endpoints
136
139
 
137
140
  Quickback generates these endpoints from the example above:
@@ -17,11 +17,9 @@ export default defineTable(jobs, {
17
17
  read: {
18
18
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
19
19
  },
20
- crud: {
21
- create: { access: { roles: ["owner", "hiring-manager"] } },
22
- update: { access: { roles: ["owner", "hiring-manager"] } },
23
- delete: { access: { roles: ["owner", "hiring-manager"] } },
24
- },
20
+ create: { access: { roles: ["owner", "hiring-manager"] } },
21
+ update: { access: { roles: ["owner", "hiring-manager"] } },
22
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
25
23
  });
26
24
  ```
27
25
 
@@ -54,11 +52,9 @@ export default defineTable(interviewNotes, {
54
52
  read: {
55
53
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
56
54
  },
57
- crud: {
58
- create: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
59
- update: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
60
- delete: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
61
- },
55
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
56
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
57
+ delete: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
62
58
  });
63
59
  ```
64
60
 
@@ -79,11 +75,9 @@ export default defineTable(applications, {
79
75
  read: {
80
76
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
81
77
  },
82
- crud: {
83
- create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
84
- update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
85
- delete: { access: { roles: ["owner", "hiring-manager"] } },
86
- },
78
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
79
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
80
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
87
81
  });
88
82
  ```
89
83
 
@@ -138,11 +132,9 @@ export default defineTable(applications, {
138
132
  read: {
139
133
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
140
134
  },
141
- crud: {
142
- create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
143
- update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
144
- delete: { access: { roles: ["hiring-manager"] } },
145
- },
135
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
136
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
137
+ delete: { access: { roles: ["hiring-manager"] } },
146
138
  });
147
139
  ```
148
140
 
@@ -181,11 +173,9 @@ export default defineTable(candidates, {
181
173
  read: {
182
174
  access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
183
175
  },
184
- crud: {
185
- create: { access: { roles: ["hiring-manager", "recruiter"] } },
186
- update: { access: { roles: ["hiring-manager", "recruiter"] } },
187
- delete: { access: { roles: ["hiring-manager"] } },
188
- },
176
+ create: { access: { roles: ["hiring-manager", "recruiter"] } },
177
+ update: { access: { roles: ["hiring-manager", "recruiter"] } },
178
+ delete: { access: { roles: ["hiring-manager"] } },
189
179
  });
190
180
  ```
191
181
 
@@ -197,7 +187,7 @@ export default defineTable(candidates, {
197
187
 
198
188
  ## External System Sync
199
189
 
200
- An import table for syncing candidates from an external ATS via PUT/upsert:
190
+ An import table for syncing candidates from an external ATS via upsert:
201
191
 
202
192
  ```typescript
203
193
  // quickback/features/ats-imports/ats-imports.ts
@@ -210,11 +200,9 @@ export default defineTable(atsImports, {
210
200
  read: {
211
201
  access: { roles: ["owner", "hiring-manager"] },
212
202
  },
213
- crud: {
214
- create: { access: { roles: ["owner", "hiring-manager"] } },
215
- update: { access: { roles: ["owner", "hiring-manager"] } },
216
- delete: { access: { roles: ["owner"] } },
217
- },
203
+ create: { access: { roles: ["owner", "hiring-manager"] } },
204
+ update: { access: { roles: ["owner", "hiring-manager"] } },
205
+ delete: { access: { roles: ["owner"] } },
218
206
  });
219
207
  ```
220
208
 
@@ -84,11 +84,9 @@ export default defineTable(posts, {
84
84
  read: {
85
85
  access: { roles: ["PUBLIC"] },
86
86
  },
87
- crud: {
88
- create: { access: { roles: ["admin"] } },
89
- update: { access: { roles: ["admin"] } },
90
- delete: { access: { roles: ["admin"] }, mode: "soft" },
91
- },
87
+ create: { access: { roles: ["admin"] } },
88
+ update: { access: { roles: ["admin"] } },
89
+ delete: { access: { roles: ["admin"] }, mode: "soft" },
92
90
  });
93
91
  ```
94
92
 
@@ -248,11 +246,9 @@ export default defineTable(pages, {
248
246
  read: {
249
247
  access: { roles: ["PUBLIC"] },
250
248
  },
251
- crud: {
252
- create: { access: { roles: ["admin"] } },
253
- update: { access: { roles: ["admin"] } },
254
- delete: { access: { roles: ["admin"] } },
255
- },
249
+ create: { access: { roles: ["admin"] } },
250
+ update: { access: { roles: ["admin"] } },
251
+ delete: { access: { roles: ["admin"] } },
256
252
  });
257
253
  ```
258
254
 
@@ -88,11 +88,9 @@ export default defineTable(todos, {
88
88
  read: {
89
89
  access: { roles: ["owner", "admin", "member"] },
90
90
  },
91
- crud: {
92
- create: { access: { roles: ["owner", "admin", "member"] } },
93
- update: { access: { roles: ["owner", "admin", "member"] } },
94
- delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
95
- },
91
+ create: { access: { roles: ["owner", "admin", "member"] } },
92
+ update: { access: { roles: ["owner", "admin", "member"] } },
93
+ delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
96
94
  });
97
95
  ```
98
96
 
@@ -84,11 +84,9 @@ export default defineTable(products, {
84
84
  read: {
85
85
  access: { roles: ["member+"] },
86
86
  },
87
- crud: {
88
- create: { access: { roles: ["member+"] } },
89
- update: { access: { roles: ["member+"] } },
90
- delete: { access: { roles: ["admin+"] }, mode: "soft" },
91
- },
87
+ create: { access: { roles: ["member+"] } },
88
+ update: { access: { roles: ["member+"] } },
89
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
92
90
  });
93
91
  ```
94
92
 
@@ -1,22 +1,22 @@
1
1
  # Batch Operations
2
2
 
3
- Batch operations let you create, update, or delete multiple records in a single request. They are **auto-enabled** when the corresponding CRUD operation exists in your definition.
3
+ Batch operations let you create, update, upsert, or delete multiple records in a single request. They are **auto-enabled** when the corresponding write operation exists in your definition.
4
4
 
5
5
  ## Available Endpoints
6
6
 
7
7
  | Endpoint | Method | Auto-enabled When |
8
8
  |----------|--------|-------------------|
9
- | `/{resource}/batch` | `POST` | `crud.create` exists |
10
- | `/{resource}/batch` | `PATCH` | `crud.update` exists |
11
- | `/{resource}/batch` | `DELETE` | `crud.delete` exists |
12
- | `/{resource}/batch` | `PUT` | `crud.put` exists |
9
+ | `/{resource}/batch` | `POST` | `create` exists |
10
+ | `/{resource}/batch` | `PATCH` | `update` exists |
11
+ | `/{resource}/batch` | `DELETE` | `delete` exists |
12
+ | `/{resource}/batch` | `PUT` | `upsert` exists |
13
13
 
14
14
  To disable a batch operation, set it to `false` in your definition:
15
15
 
16
16
  ```typescript
17
- crud: {
18
- create: { access: { roles: ['hiring-manager'] } },
19
- batchCreate: false, // Disable batch create
17
+ create: {
18
+ access: { roles: ['hiring-manager'] },
19
+ batch: false, // Disable batch create
20
20
  }
21
21
  ```
22
22
 
@@ -309,33 +309,39 @@ The default maximum batch size is **100 records**. Requests exceeding the limit
309
309
 
310
310
  ## Configuration
311
311
 
312
- Batch operations inherit access control from their corresponding CRUD operation. You can override per-batch settings:
312
+ Batch operations inherit access control from their corresponding write operation. You can override per-batch settings:
313
313
 
314
314
  ```typescript
315
315
  export default defineTable(applications, {
316
- crud: {
317
- create: { access: { roles: ['hiring-manager', 'recruiter'] } },
318
- update: { access: { roles: ['hiring-manager', 'recruiter'] } },
319
- delete: { access: { roles: ['hiring-manager'] }, mode: 'soft' },
320
-
321
- // Override batch-specific settings
322
- batchCreate: {
323
- access: { roles: ['hiring-manager'] }, // More restrictive than single create
324
- maxBatchSize: 50, // Default: 100
325
- allowFailFast: true, // Default: true
316
+ create: {
317
+ access: { roles: ['hiring-manager', 'recruiter'] },
318
+ batch: {
319
+ access: { roles: ['hiring-manager'] }, // More restrictive than single create
320
+ maxBatchSize: 50, // Default: 100
321
+ allowFailFast: true, // Default: true
326
322
  },
327
- batchUpdate: {
323
+ },
324
+ update: {
325
+ access: { roles: ['hiring-manager', 'recruiter'] },
326
+ batch: {
328
327
  maxBatchSize: 100,
329
328
  allowFailFast: true,
330
329
  },
331
- batchDelete: {
330
+ },
331
+ delete: {
332
+ access: { roles: ['hiring-manager'] },
333
+ mode: 'soft',
334
+ batch: {
332
335
  access: { roles: ['hiring-manager'] },
333
336
  maxBatchSize: 100,
334
337
  allowFailFast: true,
335
338
  },
339
+ },
336
340
 
337
- // Disable a batch operation entirely
338
- batchUpsert: false,
341
+ // Disable only batch upsert
342
+ upsert: {
343
+ access: { roles: ['hiring-manager'] },
344
+ batch: false,
339
345
  },
340
346
  });
341
347
  ```
@@ -580,30 +580,28 @@ All batch operation errors include:
580
580
 
581
581
  #### Configuration
582
582
 
583
- Batch operations are **auto-enabled** when corresponding CRUD operations exist:
583
+ Batch operations are **auto-enabled** when corresponding write operations exist:
584
584
 
585
585
  ```typescript
586
586
  // Auto-enabled - no configuration needed
587
- crud: {
588
- create: { access: { roles: ['recruiter'] } },
589
- update: { access: { roles: ['recruiter'] } }
590
- // batchCreate and batchUpdate automatically available
591
- }
587
+ create: { access: { roles: ['recruiter'] } },
588
+ update: { access: { roles: ['recruiter'] } }
589
+ // create.batch and update.batch automatically available
592
590
 
593
591
  // Customize batch operations
594
- crud: {
595
- create: { access: { roles: ['recruiter'] } },
596
- batchCreate: {
592
+ create: {
593
+ access: { roles: ['recruiter'] },
594
+ batch: {
597
595
  access: { roles: ['hiring-manager'] }, // Different access rules
598
- maxBatchSize: 50, // Lower limit
599
- allowFailFast: false // Disable failFast mode
596
+ maxBatchSize: 50, // Lower limit
597
+ allowFailFast: false // Disable failFast mode
600
598
  }
601
599
  }
602
600
 
603
601
  // Disable batch operations
604
- crud: {
605
- create: { access: { roles: ['recruiter'] } },
606
- batchCreate: false // Explicitly disable
602
+ create: {
603
+ access: { roles: ['recruiter'] },
604
+ batch: false // Explicitly disable
607
605
  }
608
606
  ```
609
607
 
@@ -140,18 +140,21 @@ const { data, error } = await client.GET('/api/v1/jobs', { params: { query: { li
140
140
  | `true` (default) | Write `api-types.gen.ts` to the project root |
141
141
  | `false` | Don't emit the types file |
142
142
  | `"src/lib/api-types.ts"` | Custom output path (relative to project root) |
143
+ | `["api-types.gen.ts", "apps/web/src/lib/api-types.gen.ts"]` | Write the same generated types to multiple paths in one compile |
143
144
 
144
145
  ```typescript
145
146
  // quickback.config.ts
146
147
  export default defineConfig({
147
148
  // ...
148
149
  openapi: {
149
- types: 'src/lib/api-types.gen.ts', // emit straight into your client app
150
+ types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'],
150
151
  },
151
152
  });
152
153
  ```
153
154
 
154
- 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. Skipped automatically when `openapi.generate` is `false`.
155
+ 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`.
156
+
157
+ The bundled Quickback CMS and Account SPAs do not import `api-types.gen.ts`. CMS is driven by `schema-registry.json`, and Account uses Better Auth plus small hand-written fetch helpers. Use `openapi.types` for your own colocated client apps.
155
158
 
156
159
  ### External viewer
157
160
 
@@ -42,15 +42,13 @@ GET /api/v1/jobs?department.in=Engineering,Design,Product
42
42
  GET /api/v1/jobs?limit=25&offset=50
43
43
  ```
44
44
 
45
- The default `limit` can be configured per-resource in your definition:
45
+ The default `limit` can be configured per-resource in your `read` definition:
46
46
 
47
47
  ```typescript
48
- crud: {
49
- list: {
50
- access: { roles: ["recruiter"] },
51
- pageSize: 25, // Default limit
52
- maxPageSize: 100, // Maximum allowed limit
53
- },
48
+ read: {
49
+ access: { roles: ["recruiter"] },
50
+ pageSize: 25, // Default limit
51
+ maxPageSize: 100, // Maximum allowed limit
54
52
  },
55
53
  ```
56
54
 
@@ -65,6 +65,16 @@ To clean up, you'd need to manually create a migration.
65
65
 
66
66
  If compilation fails with `drizzle-kit requested interactive rename input`, add explicit rename hints in your config. See [Drizzle rename prompts](/compiler/cloud-compiler/troubleshooting#drizzle-rename-prompts-in-ciheadless-compile).
67
67
 
68
+ ### Cloudflare D1 destructive migrations
69
+
70
+ Quickback now adds a D1-specific safety pass around Drizzle-generated migrations for the `cloudflare-d1` provider:
71
+
72
+ 1. **Better Auth cleanup** for retired managed tables is stripped instead of shipped as raw `DROP TABLE` SQL.
73
+ 2. **Drop-only cleanup migrations** are reordered child-first when foreign keys require it.
74
+ 3. **All D1 migration directories** generated by the compiler are replayed against SQLite during compile, so a D1-breaking migration fails before deploy.
75
+
76
+ If `quickback compile` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
77
+
68
78
  ## Runtime Issues
69
79
 
70
80
  ### 401 on all requests
@@ -138,6 +138,75 @@ rateLimit: {
138
138
 
139
139
  ---
140
140
 
141
+ ## Bearer Tokens and Cookie Precedence
142
+
143
+ Quickback supports three bearer-token flavors alongside the standard browser session cookie:
144
+
145
+ | Credential | Used by | Resolved by |
146
+ |------------|---------|-------------|
147
+ | Session cookie | Browser SPAs (CMS, Account, your app) | Better Auth session lookup |
148
+ | Session-token bearer | API clients that grabbed `set-auth-token` | Better Auth `bearer` plugin |
149
+ | JWT bearer | API clients that hit `/api/v1/token` | In-worker JWT fast-path (no DB hit) |
150
+ | API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` / `?api_key=` |
151
+
152
+ These match Better Auth's own framing of bearer tokens as **an alternative to cookies, not a supplement** — a request uses one or the other.
153
+
154
+ ### Precedence: bearer always wins
155
+
156
+ If a request carries both `Authorization` and `Cookie` headers, the bearer wins universally and the cookie is dropped before session resolution:
157
+
158
+ ```
159
+ Request Resolved as
160
+ ────────────────────────────────────── ─────────────
161
+ Cookie only cookie session
162
+ Authorization: Bearer <jwt> JWT claims
163
+ Authorization: Bearer <api-key> API-key owner
164
+ Authorization: Bearer <session-token> bearer session
165
+ Cookie + Authorization: Bearer <token> bearer wins, cookie ignored
166
+ ```
167
+
168
+ This closes a class of silent-impersonation bugs where an ambient session cookie (multi-account browser tabs, a malicious extension, a misconfigured proxy injecting `Set-Cookie`) would otherwise override an explicit bearer credential. The decision is made before `getSession()` runs, so it applies to every code path in the auth middleware.
169
+
170
+ The api-key and JWT bearers also short-circuit before cookie resolution via dedicated fast-paths — they never touch the database for session lookup. Only session-token bearers reach `getSession()`, where Better Auth's `bearer` plugin resolves the `Authorization` header.
171
+
172
+ ### `requireSignature: true` is the secure default
173
+
174
+ Quickback configures the Better Auth `bearer` plugin with `requireSignature: true` by default. This means:
175
+
176
+ - The session token Better Auth emits via the `set-auth-token` response header is **signed server-side** with `BETTER_AUTH_SECRET`.
177
+ - Unsigned bearer tokens are **rejected** at the plugin layer before any session lookup happens.
178
+ - A session token leaked via a proxy access log, a browser dev-tools panel, or a misrouted `Referer` header **cannot** be replayed as a bearer token by an attacker — they would need the signing secret to forge a valid signature.
179
+
180
+ Better Auth's own default for this option is `false`. Quickback overrides it on the secure side. JWT bearers and agent-auth bearers are independently signed and unaffected by this setting.
181
+
182
+ ### Overriding the default
183
+
184
+ If a project genuinely needs unsigned bearers (e.g., a closed loopback service where signing is redundant), pass an explicit object:
185
+
186
+ ```ts
187
+ auth: defineAuth("better-auth", {
188
+ plugins: {
189
+ bearer: { requireSignature: false },
190
+ },
191
+ })
192
+ ```
193
+
194
+ User-supplied options merge on top of the secure default, so any other [`bearer` plugin option](https://better-auth.com/docs/plugins/bearer) can be passed the same way.
195
+
196
+ ### Threat model and trade-offs
197
+
198
+ | Threat | Mitigation |
199
+ |--------|-----------|
200
+ | Stolen session-token bearer replayed against the API | `requireSignature: true` blocks unsigned values |
201
+ | Browser extension injects a victim's session cookie into an attacker's bearer-authed API call | Cookie stripped when `Authorization` is present |
202
+ | Multi-account user has cookies for two identities and uses bearer for the second | Bearer identity wins; no ambiguity in audit log |
203
+ | MCP / agent flow exposed to ambient browser cookies | `/mcp` and agent-auth routes are bearer-only (cookies dropped entirely, see [Agent Auth](/stack/auth/plugins/agent-auth)) |
204
+ | Alg-confusion / forged JWT (alg=none, HS384, RS256) | Verifier pins HS256; signature math rejects all non-matching algs uniformly with 401 |
205
+
206
+ For a deeper walkthrough of the bearer flow itself, see the upstream [Better Auth bearer plugin docs](https://better-auth.com/docs/plugins/bearer).
207
+
208
+ ---
209
+
141
210
  ## Cross-Domain Authentication
142
211
 
143
212
  For applications spanning multiple subdomains (e.g., `account.example.com`, `api.example.com`, `dashboard.example.com`), Quickback provides dual-layer security.
@@ -106,6 +106,8 @@ Actions can include an optional `cms` property for enhanced CMS rendering. Actio
106
106
  | `destructive` | `boolean` | `false` | Red styling + requires confirmation |
107
107
  | `category` | `string` | none | Group actions under a header |
108
108
  | `hidden` | `boolean` | `false` | Hide from CMS entirely (API-only actions) |
109
+ | `placement` | `"feature" \| "tables"` | none | Where standalone actions appear in multi-table features |
110
+ | `tables` | `string[]` | none | Explicit table list when `placement` is `"tables"` |
109
111
  | `successMessage` | `string` | none | Toast message after success |
110
112
  | `onSuccess` | `"refresh" \| "redirect:list" \| "close"` | `"refresh"` | Behavior after successful execution |
111
113
  | `order` | `number` | `0` | Sort priority (lower = first) |
@@ -177,6 +179,32 @@ This provides a visual cue that the action has permanent consequences.
177
179
 
178
180
  Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
179
181
 
182
+ ### Placement in Multi-Table Features
183
+
184
+ When a standalone action belongs to a feature with multiple tables, the CMS needs to know where to render it.
185
+
186
+ - Use `cms.placement: "feature"` to show the action in the table toolbar for every table in that feature.
187
+ - Use `cms.placement: "tables"` with `cms.tables` to show it only on specific tables.
188
+ - Use `cms.hidden: true` to keep it API-only.
189
+
190
+ Single-table features and clearly table-scoped standalone paths are inferred automatically. Feature-root standalone actions in multi-table features should set placement explicitly.
191
+
192
+ ```typescript
193
+ defineAction({
194
+ path: "/chat/post-message",
195
+ method: "POST",
196
+ access: { roles: ["member"] },
197
+ cms: {
198
+ label: "Post Message",
199
+ placement: "tables",
200
+ tables: ["chatChannels", "chatMessages"],
201
+ },
202
+ async execute() {
203
+ return { ok: true };
204
+ },
205
+ });
206
+ ```
207
+
180
208
  ## File Response Actions
181
209
 
182
210
  Actions with `responseType: "file"` show a download icon instead of the lightning bolt. When executed, the response is treated as a file download rather than a JSON result.
@@ -155,10 +155,10 @@ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the B
155
155
  - **Account UI** hides the "Go to CMS" button for non-admins.
156
156
  - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-admin. A non-admin who types the CMS URL directly cannot load the app.
157
157
  - **`/api/v1/schema`** returns `403 Admin access required` to non-admin callers, so schema metadata can't be scraped by hitting the API directly.
158
- - **`custom_view` CRUD** is gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
158
+ - **`custom_view` routes** are gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
159
159
  - **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
160
160
 
161
- Your resource CRUD endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `crud.access.roles` you defined.
161
+ Your resource API endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
162
162
 
163
163
  To allow any authenticated user to access the CMS, opt out explicitly:
164
164
 
@@ -116,9 +116,9 @@ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the u
116
116
  1. **Account UI link** — the "Go to CMS" button is hidden for non-admins.
117
117
  2. **CMS SPA shell** — the Worker returns `403 Admin access required` before serving `index.html` to a non-admin. Unauthenticated requests are redirected to the login page.
118
118
  3. **`/api/v1/schema`** — the CMS metadata endpoint checks `ctx.userRole === "admin"` and returns `403` otherwise.
119
- 4. **`custom_view` CRUD** — the CMS-internal saved-views table is gated on `userRole: ["admin"]` (see the [`userRole` access primitive](/compiler/definitions/access#userrole)) rather than org membership.
119
+ 4. **`custom_view` routes** — the CMS-internal saved-views table is gated on `userRole: ["admin"]` (see the [`userRole` access primitive](/compiler/definitions/access#userrole)) rather than org membership.
120
120
 
121
- Your resource CRUD endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `crud.access.roles` you defined.
121
+ Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
122
122
 
123
123
  To allow any authenticated user, opt out explicitly:
124
124
 
@@ -14,7 +14,9 @@ Add a `layouts` property to your `defineTable()` config:
14
14
  ```typescript
15
15
  export default defineTable(contacts, {
16
16
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
17
- crud: { /* ... */ },
17
+ create: { /* ... */ },
18
+ update: { /* ... */ },
19
+ delete: { /* ... */ },
18
20
  layouts: {
19
21
  default: {
20
22
  sections: [
@@ -106,26 +108,24 @@ export default defineTable(customView, {
106
108
  read: {
107
109
  access: { roles: ["owner", "admin", "member"] },
108
110
  },
109
- crud: {
110
- create: { access: { roles: ["owner", "admin", "member"] } },
111
- update: {
112
- access: {
113
- or: [
114
- { roles: ["owner", "admin"] },
115
- { roles: ["member"], record: { createdBy: { equals: "$userId" } } }
116
- ]
117
- }
118
- },
119
- delete: {
120
- access: {
121
- or: [
122
- { roles: ["owner", "admin"] },
123
- { roles: ["member"], record: { createdBy: { equals: "$userId" } } }
124
- ]
125
- },
126
- mode: "hard"
111
+ create: { access: { roles: ["owner", "admin", "member"] } },
112
+ update: {
113
+ access: {
114
+ or: [
115
+ { roles: ["owner", "admin"] },
116
+ { roles: ["member"], record: { createdBy: { equals: "$userId" } } }
117
+ ]
127
118
  }
128
119
  },
120
+ delete: {
121
+ access: {
122
+ or: [
123
+ { roles: ["owner", "admin"] },
124
+ { roles: ["member"], record: { createdBy: { equals: "$userId" } } }
125
+ ]
126
+ },
127
+ mode: "hard"
128
+ },
129
129
  guards: {
130
130
  createable: ["tableName", "name", "description", "layoutConfig", "isShared"],
131
131
  updatable: ["name", "description", "layoutConfig", "isShared"]