@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
@@ -331,6 +331,80 @@ Better Auth's older `better-auth/plugins/mcp` is being deprecated in favour of `
331
331
 
332
332
  Keep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.
333
333
 
334
+ ### Custom plugins (escape hatch)
335
+
336
+ The named plugins above cover the curated set Quickback ships first-class wiring for. For anything else — third-party packages (`@better-auth-kit/audit`, …), Better Auth built-ins outside the registry, or project-local plugins — use `customPlugins`.
337
+
338
+ ```ts
339
+ auth: defineAuth("better-auth", {
340
+ emailAndPassword: { enabled: true },
341
+ plugins: { passkey: true, organization: true },
342
+ customPlugins: [
343
+ // (1) Project-local plugin file at quickback/plugins/long-session.ts
344
+ { from: "./plugins/long-session", export: "longSessionPlugin" },
345
+ // (2) Third-party npm package
346
+ {
347
+ from: "@better-auth-kit/audit",
348
+ export: "auditPlugin",
349
+ args: { events: ["sign-in"] },
350
+ dependencies: { "@better-auth-kit/audit": "^1.0.0" },
351
+ },
352
+ ],
353
+ }),
354
+ ```
355
+
356
+ Each entry in `customPlugins` is an explicit import descriptor. The compiler runs each through Zod, then emits an `import { <export> } from "<from>"` line in the generated `src/lib/auth.ts` and appends the call (or bare symbol) to the `plugins: [...]` array — after the named plugins, in declared order.
357
+
358
+ #### `from`
359
+
360
+ - **Relative path** (must start with `./` or `../`, must resolve under `./plugins/`): refers to a file you author in `quickback/plugins/`. The CLI auto-discovers `quickback/plugins/**/*.ts` and ships matching files; the compiler copies the source into the generated output at `src/plugins/<name>.ts` and rewrites the emitted import path. Files in `quickback/plugins/` that aren't referenced by any descriptor are uploaded but ignored — the compiler picks only what's needed.
361
+ - **Bare specifier** (any value not starting with `./` or `../`): treated as an npm import, emitted verbatim. Combine with `dependencies` so the package lands in the generated `package.json`.
362
+
363
+ #### `export`
364
+
365
+ The named export to import. Must be a valid JS identifier (e.g. `longSessionPlugin`, `auditPlugin`). Use the symbol's source name from the file or package — Quickback emits the import as-is.
366
+
367
+ #### `args` (optional)
368
+
369
+ - **Omitted** → emits the symbol uncalled (`plugins: [..., longSessionPlugin]`). Use this when your export is already a `BetterAuthPlugin` instance.
370
+ - **Provided** → emits a factory call with JSON-serialized args (`plugins: [..., auditPlugin({"events":["sign-in"]})]`). The value must be JSON-serializable; functions and other non-serializable values fail at compile time. (The user config crosses an HTTP boundary as JSON, so this constraint exists by construction.)
371
+
372
+ #### `dependencies` (optional)
373
+
374
+ `Record<string, string>` of npm packages and version specs. Merged into the generated `package.json` alongside the named-plugin deps. Only meaningful for bare-specifier `from` — relative-path entries don't need to declare anything.
375
+
376
+ #### Project-local plugin shape
377
+
378
+ A plugin file in `quickback/plugins/` is plain Better Auth — the compiler doesn't transform it. Author it like any other BA plugin and let TypeScript check it against the `BetterAuthPlugin` type:
379
+
380
+ ```ts
381
+ // quickback/plugins/long-session.ts
382
+ import type { BetterAuthPlugin } from "better-auth";
383
+
384
+ export const longSessionPlugin = {
385
+ id: "long-session",
386
+ databaseHooks: {
387
+ session: {
388
+ create: {
389
+ before: async (session) => ({
390
+ data: {
391
+ ...session,
392
+ // 5-year session for an event-app use case
393
+ expiresAt: new Date(Date.now() + 5 * 365 * 24 * 60 * 60 * 1000),
394
+ },
395
+ }),
396
+ },
397
+ },
398
+ },
399
+ } satisfies BetterAuthPlugin;
400
+ ```
401
+
402
+ #### Out of scope
403
+
404
+ - **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature — the compiler does not run schema introspection on custom plugins.
405
+ - **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.
406
+ - **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.
407
+
334
408
  ## Where This Runs
335
409
 
336
410
  All Better Auth plugin routes are served under your auth base path:
@@ -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"]
@@ -15,6 +15,7 @@ interface SchemaRegistry {
15
15
  features: Record<string, string[]>;
16
16
  tables: Record<string, TableMeta>;
17
17
  tablesByFeature: Record<string, string[]>;
18
+ featureActions: Record<string, ActionMeta[]>;
18
19
  pages: Record<string, PageMeta>;
19
20
  pagesByFeature: Record<string, string[]>;
20
21
  }
@@ -29,6 +30,7 @@ interface SchemaRegistry {
29
30
  | `features` | Map of feature name to array of source file names |
30
31
  | `tables` | Map of camelCase table name to full table metadata |
31
32
  | `tablesByFeature` | Map of feature name to array of table names in that feature |
33
+ | `featureActions` | Map of feature name to standalone actions not attached to one table |
32
34
  | `pages` | Map of page slug to full page metadata |
33
35
  | `pagesByFeature` | Map of feature name to array of page slugs in that feature |
34
36
 
@@ -44,6 +46,10 @@ interface TableMeta {
44
46
  columns: ColumnMeta[];
45
47
  firewall: Record<string, unknown>;
46
48
  crud: Record<string, CrudConfig>;
49
+ create?: WriteOperationConfig | false;
50
+ update?: WriteOperationConfig | false;
51
+ delete?: WriteOperationConfig | false;
52
+ upsert?: WriteOperationConfig | false;
47
53
  guards: GuardsConfig;
48
54
  masking: Record<string, MaskingRule>;
49
55
  views: Record<string, ViewConfig>;
@@ -64,12 +70,13 @@ interface TableMeta {
64
70
  | `feature` | Parent feature name (e.g., `"accounting"`) |
65
71
  | `columns` | Ordered array of column metadata |
66
72
  | `firewall` | Tenant isolation config (organization, owner, softDelete, exception) |
67
- | `crud` | Per-operation (create, read, update, delete) access config |
73
+ | `crud` | Legacy normalized write config kept for backwards compatibility |
74
+ | `create` / `update` / `delete` / `upsert` | Flat write-operation aliases mirroring the authored `defineTable(...)` DSL |
68
75
  | `guards` | Field-level create/update/immutable/protected rules |
69
76
  | `masking` | Per-field masking rules keyed by column name |
70
77
  | `views` | Named column projections keyed by view name |
71
78
  | `validation` | Per-field validation rules keyed by column name |
72
- | `actions` | Array of action definitions for this table |
79
+ | `actions` | Array of action definitions scoped to this table |
73
80
  | `displayColumn` | Column used as human-readable label (auto-detected or explicit) |
74
81
  | `defaultSort` | Default sort for CMS table list view (e.g., `{ field: "createdAt", order: "desc" }`) |
75
82
  | `inputHints` | Map of column name to preferred CMS input type (e.g., `"richtext"`, `"select"`, `"textarea"`, `"checkbox"`) |
@@ -114,6 +121,15 @@ interface CrudConfig {
114
121
  mode?: string;
115
122
  }
116
123
 
124
+ interface WriteOperationConfig extends CrudConfig {
125
+ defaults?: Record<string, unknown>;
126
+ computed?: Record<string, unknown>;
127
+ fields?: string[];
128
+ maxBatchSize?: number;
129
+ allowFailFast?: boolean;
130
+ batch?: false | Record<string, unknown>;
131
+ }
132
+
117
133
  interface AccessRule {
118
134
  roles?: string[];
119
135
  or?: Array<{
@@ -130,6 +146,9 @@ interface AccessRule {
130
146
  | `access.or` | Alternative access conditions (any must match) |
131
147
  | `access.record` | Record-level conditions for access |
132
148
  | `mode` | Operation mode (e.g., `"batch"` for bulk create) |
149
+ | `defaults` / `computed` | Create-time defaults and computed field metadata |
150
+ | `maxBatchSize` / `allowFailFast` | Batch-write controls when the config describes a batch operation |
151
+ | `batch` | Nested batch config for the flat `create` / `update` / `delete` / `upsert` aliases |
133
152
 
134
153
  ## GuardsConfig
135
154
 
@@ -179,6 +198,8 @@ interface CmsConfig {
179
198
  destructive?: boolean;
180
199
  category?: string;
181
200
  hidden?: boolean;
201
+ placement?: 'feature' | 'tables';
202
+ tables?: string[];
182
203
  successMessage?: string;
183
204
  onSuccess?: 'refresh' | 'redirect:list' | 'close';
184
205
  order?: number;
@@ -204,7 +225,16 @@ interface ActionInputField {
204
225
  | `method` | HTTP method (defaults to POST) |
205
226
  | `responseType` | `"file"` for download responses |
206
227
  | `sideEffects` | `"sync"` for actions with synchronous side effects |
207
- | `cms` | Optional CMS rendering metadata (label, icon, confirm, destructive, category, hidden, successMessage, onSuccess, order) |
228
+ | `cms` | Optional CMS rendering metadata (label, icon, confirm, destructive, category, hidden, placement, tables, successMessage, onSuccess, order) |
229
+
230
+ ### CmsConfig placement rules
231
+
232
+ `placement` is only relevant for standalone actions in multi-table features:
233
+
234
+ - `"feature"` shows the action in the toolbar for every table in the feature.
235
+ - `"tables"` shows the action only for the tables listed in `tables`.
236
+
237
+ If the action is already unambiguously table-scoped, the compiler can infer placement and `placement` is optional.
208
238
 
209
239
  ### ActionInputField
210
240
 
@@ -28,6 +28,7 @@ The top-level structure of `schema-registry.json`:
28
28
  "features": { ... },
29
29
  "tables": { ... },
30
30
  "tablesByFeature": { ... },
31
+ "featureActions": { ... },
31
32
  "pages": { ... },
32
33
  "pagesByFeature": { ... }
33
34
  }
@@ -42,6 +43,7 @@ The top-level structure of `schema-registry.json`:
42
43
  | `features` | `Record<string, string[]>` | Feature name to file list mapping |
43
44
  | `tables` | `Record<string, TableMeta>` | Table name to full metadata |
44
45
  | `tablesByFeature` | `Record<string, string[]>` | Feature name to table name list |
46
+ | `featureActions` | `Record<string, ActionMeta[]>` | Feature name to standalone actions not owned by one table |
45
47
  | `pages` | `Record<string, PageMeta>` | Page slug to full page metadata |
46
48
  | `pagesByFeature` | `Record<string, string[]>` | Feature name to page slug list |
47
49
 
@@ -56,7 +58,11 @@ interface TableMeta {
56
58
  feature: string; // Parent feature name
57
59
  columns: ColumnMeta[]; // All columns including audit fields
58
60
  firewall: Record<string, unknown>; // Tenant isolation config
59
- crud: Record<string, CrudConfig>; // Per-operation access rules
61
+ crud: Record<string, CrudConfig>; // Legacy normalized write surface
62
+ create?: WriteOperationConfig | false; // Flat create config
63
+ update?: WriteOperationConfig | false; // Flat update config
64
+ delete?: WriteOperationConfig | false; // Flat delete config
65
+ upsert?: WriteOperationConfig | false; // Flat upsert config
60
66
  guards: {
61
67
  createable: string[]; // Fields allowed on create
62
68
  updatable: string[]; // Fields allowed on update
@@ -66,12 +72,26 @@ interface TableMeta {
66
72
  masking: Record<string, MaskingRule>; // Per-field masking rules
67
73
  views: Record<string, ViewConfig>; // Named column projections
68
74
  validation: Record<string, ValidationRule>; // Per-field validation
69
- actions: ActionMeta[]; // Available actions for this table
75
+ actions: ActionMeta[]; // Table-scoped actions for this table
70
76
  displayColumn?: string; // Human-readable label column
71
77
  internal?: boolean; // Hidden from CMS sidebar when true
72
78
  }
73
79
  ```
74
80
 
81
+ `create`, `update`, `delete`, and `upsert` mirror the preferred flat DSL from `defineTable(...)`. The legacy `crud` block is still emitted for backwards compatibility with older consumers.
82
+
83
+ ## Feature Actions
84
+
85
+ Standalone actions do not always belong to a single table. When an action is attached to a multi-table feature root, the compiler emits it under `featureActions[featureName]` instead of duplicating it across every table.
86
+
87
+ ```typescript
88
+ interface SchemaRegistry {
89
+ featureActions: Record<string, ActionMeta[]>;
90
+ }
91
+ ```
92
+
93
+ The CMS uses `featureActions` for toolbar-style actions that apply to the feature as a whole. Use `cms.placement` on standalone actions to control whether they show for the whole feature or only selected tables.
94
+
75
95
  > **Internal Tables**
76
96
  >
77
97
  > Tables without a `defineTable()` resource config are marked `internal: true` and hidden from the CMS sidebar. These are typically join tables or system tables.
@@ -15,10 +15,10 @@ Under the default `access: "admin"`, the compiler emits server-side gates on eve
15
15
  1. **Account UI** — the "Go to CMS" button is hidden.
16
16
  2. **CMS SPA shell** — the Worker checks `ctx.userRole === "admin"` before serving `index.html`. Unauthenticated requests are redirected to login; authenticated non-admins get `403 Admin access required`.
17
17
  3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to non-admins.
18
- 4. **`custom_view` CRUD** — the CMS-internal saved-views table uses `userRole: ["admin"]` (see [`userRole`](/compiler/definitions/access#userrole-vs-roles)), so saved views can't be read or modified from outside the CMS by non-admin accounts.
18
+ 4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["admin"]` (see [`userRole`](/compiler/definitions/access#userrole-vs-roles)), so saved views can't be read or modified from outside the CMS by non-admin accounts.
19
19
  5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
20
20
 
21
- Your resource CRUD endpoints keep whatever `crud.access.roles` you defined — they're the app's data API and unaffected by the CMS gate.
21
+ Your resource API endpoints keep whatever `read`, `create`, `update`, `delete`, or `upsert` access rules you defined — they're the app's data API and unaffected by the CMS gate.
22
22
 
23
23
  ## The Four Layers
24
24
 
@@ -27,7 +27,7 @@ Quickback enforces security through four complementary layers:
27
27
  | Layer | Purpose | CMS Behavior |
28
28
  |-------|---------|-------------|
29
29
  | **Firewall** | Tenant isolation (org-scoped data) | Handled server-side. CMS cannot bypass it. |
30
- | **CRUD Access** | Per-operation role requirements | Buttons hidden when role lacks permission |
30
+ | **Operation Access** | Per-operation role requirements | Buttons hidden when role lacks permission |
31
31
  | **Guards** | Field-level create/update control | Form fields enabled/disabled per guard rules |
32
32
  | **Masking** | Sensitive field redaction | Masked values with lock icons per role |
33
33
 
@@ -36,20 +36,18 @@ Quickback enforces security through four complementary layers:
36
36
  The CMS header includes a **role switcher** (in demo mode) or reads the user's actual role from their organization membership (in live mode). The three roles are:
37
37
 
38
38
  - **owner** — Full access to all operations and data
39
- - **admin** — Elevated access, typically all CRUD and most actions
39
+ - **admin** — Elevated access, typically all write operations and most actions
40
40
  - **member** — Standard access with restrictions on sensitive data and destructive actions
41
41
 
42
- ### CRUD Button Visibility
42
+ ### Operation Button Visibility
43
43
 
44
- CRUD operation buttons are shown or hidden based on the current role's access:
44
+ Create, edit, and delete buttons are shown or hidden based on the current role's access:
45
45
 
46
46
  ```typescript
47
- crud: {
48
- create: { access: { roles: ['admin', 'owner'] } },
49
- read: { access: { roles: ['member', 'admin', 'owner'] } },
50
- update: { access: { roles: ['admin', 'owner'] } },
51
- delete: { access: { roles: ['owner'] } },
52
- }
47
+ read: { access: { roles: ['member', 'admin', 'owner'] } },
48
+ create: { access: { roles: ['admin', 'owner'] } },
49
+ update: { access: { roles: ['admin', 'owner'] } },
50
+ delete: { access: { roles: ['owner'] } },
53
51
  ```
54
52
 
55
53
  With the config above:
@@ -25,7 +25,7 @@ The three-dot menu on each row provides:
25
25
  | Custom actions | Filtered by role + record state | Run actions like approve, void, post |
26
26
  | Delete | When role has `delete` access | Delete with confirmation |
27
27
 
28
- Actions are filtered by the current role's CRUD permissions and the action's access conditions. For example, an "approve" action that requires `status === "pending"` only appears on pending records.
28
+ Actions are filtered by the current role's write permissions and the action's access conditions. For example, an "approve" action that requires `status === "pending"` only appears on pending records.
29
29
 
30
30
  ## Data Table Mode
31
31
 
@@ -51,13 +51,17 @@ Quickback provides the architecture and the code generation. You own the infrast
51
51
  ## Quick start
52
52
 
53
53
  ```bash
54
- npm install -g wrangler @quickback-dev/cli
55
- quickback create cloudflare my-app
56
- cd my-app
57
- quickback compile
54
+ # Scaffold + compile interactively
55
+ mkdir my-app && cd my-app
56
+ npx @quickback-dev/cli start
57
+
58
+ # Deploy to your Cloudflare account
59
+ npm i -g wrangler
58
60
  wrangler deploy
59
61
  ```
60
62
 
63
+ `start` handles scaffold, login (only when needed), and the first compile in one shot. The deploy step uses your own wrangler auth and ships everything to your Cloudflare account.
64
+
61
65
  ## See also
62
66
 
63
67
  - [Quickback Compiler](/compiler) — the build tool that generates your API
@@ -2,6 +2,13 @@
2
2
 
3
3
  Quickback can generate realtime notification helpers for broadcasting changes to connected clients. This enables live updates via WebSocket using Cloudflare Durable Objects.
4
4
 
5
+ The targeting model is shared across ws tickets, websocket attachment, and server-side broadcasts:
6
+
7
+ - string target: historical `organizationId` shorthand
8
+ - object target: `{ scopeKey?, organizationId?, userId? }`
9
+
10
+ That means the same mental model drives both `createRealtime()` and the generated Broadcaster filter path.
11
+
5
12
  ## Enabling Realtime
6
13
 
7
14
  Add `realtime` configuration to individual table definitions:
@@ -35,6 +42,24 @@ export default defineTable(applications, {
35
42
 
36
43
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
37
44
 
45
+ At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need relationship-authorized resource tickets:
46
+
47
+ ```typescript
48
+ providers: {
49
+ database: defineDatabase("cloudflare-d1", {
50
+ realtime: {
51
+ wsTicket: {
52
+ role: "attendee",
53
+ requestField: "eventId",
54
+ scopeTable: "events",
55
+ },
56
+ },
57
+ }),
58
+ }
59
+ ```
60
+
61
+ That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, verify the `attendee` relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane.
62
+
38
63
  ## When auto-broadcast fires (and when you call it manually)
39
64
 
40
65
  Quickback emits auto-broadcasts in **only one place**: the generated CRUD route handlers (`POST /` create, `PATCH /:id` update, `DELETE /:id` delete) for resources with `realtime.enabled` (or covered by `dbConfig.realtime: true`'s project-level default). Those handlers wrap each successful write with a `realtime.insert / update / delete` call before responding.
@@ -74,6 +99,18 @@ export const execute: ActionExecutor = async ({ db, ctx, input }) => {
74
99
  };
75
100
  ```
76
101
 
102
+ For explicit targeting, pass an object instead of the historical org string:
103
+
104
+ ```typescript
105
+ await realtime.broadcast("event-page-updated", payload, {
106
+ scopeKey: `events:${input.eventId}`,
107
+ });
108
+
109
+ await realtime.broadcast("dm", payload, {
110
+ userId: recipientId,
111
+ });
112
+ ```
113
+
77
114
  ## Event Format
78
115
 
79
116
  Quickback broadcasts events in a structured JSON format for easy client-side handling.
@@ -207,7 +244,7 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
207
244
  });
208
245
  ```
209
246
 
210
- If `targetRoles` is not specified, all authenticated users in the organization receive the broadcast.
247
+ If `targetRoles` is not specified, all authenticated subscribers in the chosen scope receive the broadcast.
211
248
 
212
249
  ## Per-Role Field Masking
213
250
 
@@ -262,13 +299,17 @@ Quickback uses **ticket-based authentication** for WebSocket connections. The cl
262
299
  // 1. Get a ws-ticket from your API (requires session auth)
263
300
  const response = await fetch('/broadcast/v1/ws-ticket', {
264
301
  method: 'POST',
265
- headers: { Authorization: `Bearer ${sessionToken}` },
302
+ headers: {
303
+ Authorization: `Bearer ${sessionToken}`,
304
+ 'Content-Type': 'application/json',
305
+ },
306
+ body: JSON.stringify({ eventId: 'evt_123' }),
266
307
  });
267
308
  const { wsTicket } = await response.json();
268
309
 
269
310
  // 2. Connect with ticket as URL param
270
311
  const ws = new WebSocket(
271
- `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
312
+ `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}`
272
313
  );
273
314
 
274
315
  ws.onopen = () => {
@@ -348,8 +389,8 @@ new_classes = ["Broadcaster"]
348
389
  ```
349
390
 
350
391
  1. **Client gets a ticket** — `POST /broadcast/v1/ws-ticket` on the main API (session-authenticated). Returns a 60-second HMAC-signed ticket.
351
- 2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object verifies the ticket cryptographically at upgrade — no HTTP round-trip.
352
- 3. **API broadcasts** — After CRUD ops, the API calls the Broadcaster DO directly via its binding (in-process, no network hop).
392
+ 2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object verifies the ticket cryptographically at upgrade and attaches the socket to the ticket's `scopeKey`, `organizationId`, or `userId`.
393
+ 3. **API broadcasts** — After CRUD ops, or from custom handlers, the API calls the Broadcaster DO directly via its binding (in-process, no network hop) using the same target model.
353
394
 
354
395
  ## Best Practices
355
396