@quickback-dev/cli 0.38.0 → 0.39.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 (109) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.js +24 -24
  19. package/dist/docs/content.js.map +1 -1
  20. package/dist/examples/recruitment.tar.gz +0 -0
  21. package/dist/index.js +1 -1
  22. package/dist/lib/action-harvest.d.ts +48 -0
  23. package/dist/lib/action-harvest.d.ts.map +1 -0
  24. package/dist/lib/action-harvest.js +292 -0
  25. package/dist/lib/action-harvest.js.map +1 -0
  26. package/dist/lib/action-harvest.test.d.ts +2 -0
  27. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  28. package/dist/lib/action-harvest.test.js +112 -0
  29. package/dist/lib/action-harvest.test.js.map +1 -0
  30. package/dist/lib/api-client.d.ts +10 -0
  31. package/dist/lib/api-client.d.ts.map +1 -1
  32. package/dist/lib/api-client.js +17 -1
  33. package/dist/lib/api-client.js.map +1 -1
  34. package/dist/lib/api-client.test.js +19 -0
  35. package/dist/lib/api-client.test.js.map +1 -1
  36. package/dist/lib/artifact-routing.d.ts +1 -0
  37. package/dist/lib/artifact-routing.d.ts.map +1 -1
  38. package/dist/lib/artifact-routing.js +15 -3
  39. package/dist/lib/artifact-routing.js.map +1 -1
  40. package/dist/lib/artifact-routing.test.js +12 -1
  41. package/dist/lib/artifact-routing.test.js.map +1 -1
  42. package/dist/lib/file-loader.d.ts +1 -0
  43. package/dist/lib/file-loader.d.ts.map +1 -1
  44. package/dist/lib/file-loader.js +34 -1
  45. package/dist/lib/file-loader.js.map +1 -1
  46. package/dist/lib/file-loader.test.js +28 -4
  47. package/dist/lib/file-loader.test.js.map +1 -1
  48. package/dist/lib/prepare-state-output.d.ts +8 -0
  49. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  50. package/dist/lib/prepare-state-output.js +17 -0
  51. package/dist/lib/prepare-state-output.js.map +1 -0
  52. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  53. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  54. package/dist/lib/prepare-state-output.test.js +31 -0
  55. package/dist/lib/prepare-state-output.test.js.map +1 -0
  56. package/dist/skill/SKILL.md +1 -1
  57. package/dist/skill/docs/changelog.md +201 -0
  58. package/dist/skill/docs/compiler/config/agents.md +1 -1
  59. package/dist/skill/docs/compiler/config/auth.md +1 -1
  60. package/dist/skill/docs/compiler/config/index.md +8 -9
  61. package/dist/skill/docs/compiler/config/providers.md +3 -0
  62. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  63. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  64. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  65. package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
  66. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  67. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  68. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  69. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  70. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  71. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  72. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  73. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  74. package/dist/skill/docs/stack/cms/index.md +7 -7
  75. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  76. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  77. package/dist/skill/docs/stack/cms/security.md +6 -6
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
  79. package/dist/skill/docs/stack/storage/r2.md +112 -3
  80. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  81. package/dist/templates/registry.js +2 -2
  82. package/dist/templates/registry.js.map +1 -1
  83. package/package.json +1 -1
  84. package/src/examples/recruitment.tar.gz +0 -0
  85. package/src/skill/SKILL.md +1 -1
  86. package/src/skill/docs/changelog.md +201 -0
  87. package/src/skill/docs/compiler/config/agents.md +1 -1
  88. package/src/skill/docs/compiler/config/auth.md +1 -1
  89. package/src/skill/docs/compiler/config/index.md +8 -9
  90. package/src/skill/docs/compiler/config/providers.md +3 -0
  91. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  92. package/src/skill/docs/compiler/definitions/access.md +40 -33
  93. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  94. package/src/skill/docs/compiler/definitions/firewall.md +1 -1
  95. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  96. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  97. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  98. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  100. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  101. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  102. package/src/skill/docs/stack/cms/connecting.md +17 -16
  103. package/src/skill/docs/stack/cms/index.md +7 -7
  104. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  105. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  106. package/src/skill/docs/stack/cms/security.md +6 -6
  107. package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
  108. package/src/skill/docs/stack/storage/r2.md +112 -3
  109. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -56,7 +56,7 @@ delete: { access: { roles: ["owner"] } }, // owner only (no +)
56
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"]`.
57
57
 
58
58
  - Roles without `+` are exact matches (no expansion)
59
- - Pseudo-roles (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
59
+ - Pseudo-roles / reserved markers (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
60
60
  - Using `+` with a role not in the hierarchy throws a compile error
61
61
  - Using `+` without configuring `auth.roleHierarchy` throws a compile error
62
62
 
@@ -89,50 +89,50 @@ interface Access {
89
89
 
90
90
  | Primitive | Checks | Source | Example values |
91
91
  |-----------|--------|--------|----------------|
92
- | `roles` | `ctx.roles` | Org membership (multi-tenant) or single-tenant mirror of `user.role` | `"owner"`, `"admin"`, `"member"` |
93
- | `userRole` | `ctx.userRole` | The `user.role` column (Better Auth admin plugin) | `"user"`, `"admin"` |
92
+ | `roles` | `ctx.roles` | Org membership roles | `"owner"`, `"admin"`, `"member"` |
93
+ | `userRole` | `ctx.userRole` | The `user.role` column (Better Auth / platform control-plane roles) | `"user"`, `"appmanager"`, `"sysadmin"` |
94
94
 
95
- In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide admin.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want to let Better Auth system admins through regardless of org membership (e.g., for support/ops), use `userRole: ["admin"]`.
95
+ In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide role.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want platform control-plane operators through regardless of org membership (CMS, Better Auth admin surfaces, support tooling), use `userRole: ["appmanager"]`. If you need true cross-tenant data-plane access, use `roles: ["SYSADMIN"]` (with `cms: { sysadmin: true }`).
96
96
 
97
- In single-tenant mode (`features.organizations: false`), `ctx.roles` mirrors `user.role`, so `roles: ["admin"]` and `userRole: ["admin"]` behave the same. Using `userRole` in single-tenant code is still preferred — it documents intent and keeps the gate correct if you later enable orgs.
97
+ Pinned organization mode does not change this split. `roles` still come from organization membership in the pinned org, while `userRole` still comes from Better Auth's `user.role` column.
98
98
 
99
99
  ### When to use `userRole`
100
100
 
101
101
  ```typescript
102
- // Platform admin can see SSNs on every customer record, regardless of org
102
+ // Platform control-plane users can see SSNs on every customer record, regardless of org
103
103
  masking: {
104
- ssn: { type: 'ssn', show: { userRole: ['admin'] } },
104
+ ssn: { type: 'ssn', show: { userRole: ['appmanager'] } },
105
105
  }
106
106
 
107
- // Support staff (user.role === 'admin') OR the org owner can refund
107
+ // Platform ops (user.role === 'appmanager') OR the org owner can refund
108
108
  access: {
109
109
  or: [
110
- { userRole: ['admin'] },
110
+ { userRole: ['appmanager'] },
111
111
  { roles: ['owner'] },
112
112
  ],
113
113
  }
114
114
 
115
- // CMS-internal resource: only platform admins
116
- read: { access: { userRole: ['admin'] } },
117
- create: { access: { userRole: ['admin'] } },
118
- update: { access: { userRole: ['admin'] } },
119
- delete: { access: { userRole: ['admin'] } },
115
+ // CMS-internal resource: only platform control-plane users
116
+ read: { access: { userRole: ['appmanager'] } },
117
+ create: { access: { userRole: ['appmanager'] } },
118
+ update: { access: { userRole: ['appmanager'] } },
119
+ delete: { access: { userRole: ['appmanager'] } },
120
120
  ```
121
121
 
122
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".
123
123
 
124
- `userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"` and `"admin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
124
+ `userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"`, `"appmanager"`, and `"sysadmin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
125
125
 
126
126
  ### Pseudo-roles
127
127
 
128
- Quickback ships five UPPERCASE role markers that are **not backed by a Better Auth role column** — they're system-level shortcuts handled directly by the compiler. The casing carries the boundary: UPPERCASE = pseudo-role (no plugin context required), lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
128
+ Quickback ships five reserved UPPERCASE markers. Four are real pseudo-roles handled directly by the compiler; `ADMIN` is retained only as a reserved legacy marker so the compiler can fail loudly with migration guidance. The casing carries the boundary: UPPERCASE = compiler-owned marker, lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
129
129
 
130
130
  | Role | Auth gate | Compile-time requirement | Runtime check |
131
131
  |------|-----------|-------------------------|---------------|
132
132
  | `PUBLIC` | bypassed | none — explicit opt-in for unauthenticated access | always passes (auth skipped) |
133
133
  | `AUTHENTICATED` | required | none | `ctx.authenticated === true` |
134
134
  | `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole` is unset OR `ctx.userRole === "user"`) |
135
- | `ADMIN` | required | Better Auth admin plugin **must** be enabled | `ctx.authenticated && ctx.userRole === "admin"` |
135
+ | `ADMIN` | required | reserved legacy marker — compiler rejects it | `false` |
136
136
  | `SYSADMIN` | required | `cms: { sysadmin: true }` **must** be set on the project | `ctx.authenticated && ctx.userRole === "sysadmin"` |
137
137
 
138
138
  You can mix pseudo-roles with real roles in the same list — they're OR'd together.
@@ -198,18 +198,22 @@ If you forget the `userId` firewall predicate, the compiler throws:
198
198
 
199
199
  > `roles: ["USER"]` requires the resource to be scoped per-user. Add a `userId` column (auto-scoped) or an explicit owner predicate. If you want any signed-in user to read all records, use `roles: ["AUTHENTICATED"]` instead.
200
200
 
201
- When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — admins are excluded and should use `["USER", "ADMIN"]` if the same route should serve both.
201
+ When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — appmanagers and sysadmins are excluded. If the same route should serve both, express it explicitly with `or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }]`.
202
202
 
203
- #### `ADMIN` — Better Auth admin-plugin admins
203
+ #### `ADMIN` — legacy reserved marker (compile-time error)
204
204
 
205
- Use `roles: ["ADMIN"]` for system-administrator endpoints. **Requires the Better Auth admin plugin** so `user.role` exists. Compiles to `ctx.userRole === "admin"`.
205
+ `roles: ["ADMIN"]` is no longer supported. The compiler fails hard on any use of `ADMIN` so platform and tenant roles can't be confused.
206
206
 
207
207
  ```typescript
208
- // Platform-admin-only audit log
209
- read: { access: { roles: ["ADMIN"] } }
208
+ // Platform control-plane audit log
209
+ read: { access: { userRole: ["appmanager"] } }
210
210
  ```
211
211
 
212
- Without the admin plugin you get a compile error pointing you to either enable the plugin or use lowercase `roles: ["admin"]` (the org-membership admin role).
212
+ Use one of these instead:
213
+
214
+ - `userRole: ["appmanager"]` for platform control-plane access
215
+ - `roles: ["admin"]` for org-membership admin access
216
+ - `roles: ["SYSADMIN"]` for true cross-tenant access
213
217
 
214
218
  #### `SYSADMIN` — cross-tenant DB-admin tier
215
219
 
@@ -220,23 +224,23 @@ Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platfor
220
224
  read: { access: { roles: ["SYSADMIN"] } }
221
225
  ```
222
226
 
223
- `ADMIN` and `SYSADMIN` are **independent** at the evaluator level — `ADMIN` admits `userRole === 'admin'` only, `SYSADMIN` admits `userRole === 'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'admin'`; admins still go through the firewall like everyone else.
227
+ `SYSADMIN` is distinct from `userRole: ["appmanager"]`. Appmanager is the platform control-plane tier (CMS shell, Better Auth admin surfaces, support tooling); sysadmin is the cross-tenant data-plane tier. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, every `buildFirewallConditions` emits an `if (ctx.userRole === 'sysadmin') return undefined;` (or just the soft-delete predicate when present) at the top — so sysadmins see every tenant's rows, not just their own org's. That escape hatch does NOT fire for `userRole === 'appmanager'`; appmanagers still go through the firewall like everyone else.
224
228
 
225
- This separation exists so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'admin'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
229
+ This separation exists so Better Auth admin-plugin powers (user management, impersonation, org creation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'appmanager'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
226
230
 
227
231
  #### Mixing pseudo-roles with real roles
228
232
 
229
233
  Pseudo-roles and lowercase real roles compose with OR:
230
234
 
231
235
  ```typescript
232
- // Record owner OR a system admin can read
233
- read: { access: { roles: ["USER", "ADMIN"] } }
236
+ // Record owner OR a platform control-plane user can read
237
+ read: { access: { or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }] } }
234
238
 
235
- // Org owner OR system admin
236
- delete: { access: { roles: ["owner", "ADMIN"] } }
239
+ // Org owner OR sysadmin
240
+ delete: { access: { or: [{ roles: ["owner"] }, { roles: ["SYSADMIN"] }] } }
237
241
  ```
238
242
 
239
- > Note: today, an `ADMIN` match still goes through the `userId` firewall scope on USER-scoped resources — admins see only records they own on those routes. Use `firewall: { exception: true }` on a separate admin-only route if you need cross-user visibility.
243
+ > Note: `userRole: ["appmanager"]` never bypasses a `userId` firewall scope. If you need cross-user visibility, expose a separate route with `firewall: { exception: true }` or a `SYSADMIN`-gated cross-tenant surface.
240
244
 
241
245
  #### Quick reference
242
246
 
@@ -250,8 +254,11 @@ access: { roles: ["AUTHENTICATED"] }
250
254
  // Per-user records (requires userId firewall scope)
251
255
  access: { roles: ["USER"] }
252
256
 
253
- // System admin (requires admin plugin)
254
- access: { roles: ["ADMIN"] }
257
+ // Platform control-plane
258
+ access: { userRole: ["appmanager"] }
259
+
260
+ // Cross-tenant DB-admin tier
261
+ access: { roles: ["SYSADMIN"] }
255
262
 
256
263
  // Org-membership roles with hierarchy expansion
257
264
  access: { roles: ["member+"] } // expands to ["member", "admin", "owner"]
@@ -374,7 +381,7 @@ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
374
381
 
375
382
  These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
376
383
 
377
- v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / ADMIN / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before.
384
+ v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
378
385
 
379
386
  Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
380
387
 
@@ -686,7 +686,7 @@ export default defineAction({
686
686
  Unsafe cross-tenant actions are generated with:
687
687
 
688
688
  - Better Auth authentication required (no unauthenticated path)
689
- - platform admin gate (`ctx.userRole === "admin"`)
689
+ - sysadmin gate (`ctx.userRole === "sysadmin"`)
690
690
  - mandatory audit logging on deny/success/error
691
691
 
692
692
  `PUBLIC` actions also receive mandatory audit logging (same audit table), since unauthenticated endpoints are high-risk by nature.
@@ -269,7 +269,7 @@ The escape branch is **only** emitted when:
269
269
  - The table has at least one tenant-scope predicate (org / owner / team / `via:` relationship). Tables with no tenant scopes already return what a sysadmin would see, so the runtime check would be dead code.
270
270
  - The firewall does not declare `{ exception: true }` (no tenant scopes to drop).
271
271
 
272
- **Sysadmin is distinct from admin.** `userRole === 'admin'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Admins keep their existing universal-bypass at the *access* layer (cross-org reads on per-record routes via `?organizationId=`), but the firewall's row predicate remains in force. Sysadmin is opt-in, configured per-project, and intended for the cross-tenant CMS DB-admin tier — see [CMS Configuration](/compiler/config#cms-configuration).
272
+ **Sysadmin is distinct from appmanager.** `userRole === 'appmanager'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Appmanager is the platform control-plane tier, expressed with plain `userRole` checks; sysadmin is the opt-in cross-tenant DB-admin tier. See [CMS Configuration](/compiler/config#cms-configuration).
273
273
 
274
274
  If your project doesn't set `cms.sysadmin: true`, the escape branch is never emitted and the role value is functionally inert.
275
275
 
@@ -71,7 +71,7 @@ Produces byte-identical output to the `feature()` form above — the compiler ex
71
71
  A few mechanics to know:
72
72
 
73
73
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
74
- - **`q.id()`** emits `text('id').primaryKey()` with a cuid2 app-layer default.
74
+ - **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
75
75
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
76
76
  - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
77
77
  - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
@@ -95,7 +95,13 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting. This keeps q's output decoupled from any specific ID library.
99
+
100
+ For `generateId: "cuid"`, there is one important nuance: import-capable runtime
101
+ paths can emit real `createId()` usage, but compiler-managed schema
102
+ auto-injection may keep the same `createId()` call site and back it with a
103
+ file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes do not
104
+ depend on project `node_modules`.
99
105
 
100
106
  ### q.scope() — tenant scope columns
101
107
 
@@ -1,8 +1,8 @@
1
1
  # Blog Template
2
2
 
3
- The blog template creates a single-tenant backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts via Better Auth's admin plugin.
3
+ The blog template creates a fixed-org backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts through their membership in one pinned organization.
4
4
 
5
- This template uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, no `organizationId` columns. Roles come from `user.role` instead of org membership.
5
+ This template uses [pinned organization mode](/compiler/config/single-tenant). Organization support stays on, but the generated project hard-codes one organization id and hides org switching UI.
6
6
 
7
7
  ## Create the Project
8
8
 
@@ -16,7 +16,7 @@ This scaffolds a project with:
16
16
  ```
17
17
  my-site/
18
18
  ├── quickback/
19
- │ ├── quickback.config.ts # Single-tenant config
19
+ │ ├── quickback.config.ts # Pinned-organization config
20
20
  │ └── features/
21
21
  │ └── posts/
22
22
  │ ├── posts.ts # Schema + security (defineTable)
@@ -37,7 +37,7 @@ export default {
37
37
  name: "my-site",
38
38
  template: "hono",
39
39
  features: {
40
- organizations: false,
40
+ pinnedOrganizationId: "org_replace_me",
41
41
  },
42
42
  providers: {
43
43
  runtime: { name: "cloudflare", config: {} },
@@ -50,7 +50,7 @@ export default {
50
50
  };
51
51
  ```
52
52
 
53
- Key difference from the multi-tenant templates: `organizations: false` disables the Better Auth organization plugin. See [Single-Tenant Mode](/compiler/config/single-tenant) for details.
53
+ Replace `org_replace_me` with a real Better Auth organization id before deploying. Unlike the removed single-tenant mode, this template keeps the Better Auth organization plugin and resolves roles from membership in that pinned org. See [Pinned Organization Mode](/compiler/config/single-tenant) for details.
54
54
 
55
55
  ### Posts Feature (posts.ts)
56
56
 
@@ -91,7 +91,7 @@ export default defineTable(posts, {
91
91
  ```
92
92
 
93
93
  - **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
94
- - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `role: "admin"` (set via Better Auth's admin plugin)
94
+ - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `member.role === "admin"` in the pinned organization
95
95
  - **`owner`** firewall scope tracks who created each post via `ownerId`
96
96
  - **`softDelete`** marks posts as deleted rather than removing them from the database
97
97
 
@@ -270,7 +270,7 @@ npm run deploy
270
270
 
271
271
  ## Next Steps
272
272
 
273
- - [Single-Tenant Mode](/compiler/config/single-tenant) — How single-tenant mode works
273
+ - [Pinned Organization Mode](/compiler/config/single-tenant) — How fixed-org mode works
274
274
  - [Access Control](/compiler/definitions/access) — PUBLIC role and role-based permissions
275
275
  - [Custom Actions](/compiler/definitions/actions) — Add business logic beyond CRUD
276
276
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Multi-tenant alternative
@@ -33,9 +33,6 @@ my-app/
33
33
  export default {
34
34
  name: "my-app",
35
35
  template: "hono",
36
- features: {
37
- organizations: true,
38
- },
39
36
  providers: {
40
37
  runtime: { name: "cloudflare", config: {} },
41
38
  database: {
@@ -47,7 +44,7 @@ export default {
47
44
  };
48
45
  ```
49
46
 
50
- Multi-tenant mode (`organizations: true`) is the default. Change to `organizations: false` for [single-tenant mode](/compiler/config/single-tenant).
47
+ Organization-backed auth is the default. If you want a fixed-org deployment with no org switching UI, add `features.pinnedOrganizationId` as described in [Pinned Organization Mode](/compiler/config/single-tenant).
51
48
 
52
49
  ## Adding Your First Feature
53
50
 
@@ -23,13 +23,13 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
23
23
 
24
24
  The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
25
25
 
26
- ### Single-tenant starter (free)
26
+ ### Fixed-org starter (free)
27
27
 
28
28
  | Template | Includes | Command |
29
29
  |----------|----------|---------|
30
- | `blog` | Single-tenant blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions | `quickback create blog my-site` |
30
+ | `blog` | Blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions, and a pinned organization id placeholder | `quickback create blog my-site` |
31
31
 
32
- The **blog** template uses Better Auth's admin plugin (not the org plugin) and [single-tenant mode](/compiler/config/single-tenant) (`organizations: false`).
32
+ The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
33
33
 
34
34
  ### Empty scaffold (free)
35
35
 
@@ -68,9 +68,9 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
68
68
 
69
69
  Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
70
70
 
71
- ### Blog (single-tenant CMS)
71
+ ### Blog (pinned-organization CMS)
72
72
 
73
- Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role` via Better Auth's admin plugin.
73
+ Best for personal sites, blogs, or any app that only needs one organization at runtime. Uses [pinned organization mode](/compiler/config/single-tenant) — organization support stays on, but the generated app hard-codes one org id and hides org switching.
74
74
 
75
75
  - Public JSON API for content
76
76
  - Admin-only editing
@@ -110,4 +110,4 @@ See the individual template guides for detailed setup:
110
110
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare)
111
111
  - [Blog Template](/compiler/getting-started/template-blog)
112
112
  - [Empty Scaffolding](/compiler/getting-started/template-empty)
113
- - [Single-Tenant Mode](/compiler/config/single-tenant)
113
+ - [Pinned Organization Mode](/compiler/config/single-tenant)
@@ -131,7 +131,7 @@ execute: async ({ db, ctx, input }) => {
131
131
  }
132
132
  ```
133
133
 
134
- If you need unscoped access (for example, audited platform admin operations), declare `unsafe` on the action:
134
+ If you need unscoped access (for example, audited cross-tenant sysadmin operations), declare `unsafe` on the action:
135
135
 
136
136
  ```typescript
137
137
  adminReport: {
@@ -152,7 +152,7 @@ adminReport: {
152
152
  Cross-tenant unsafe actions are generated with:
153
153
 
154
154
  - Better Auth authentication required
155
- - platform admin gate (`ctx.userRole === 'admin'`)
155
+ - sysadmin gate (`ctx.userRole === 'sysadmin'`)
156
156
  - mandatory audit logging on denial/success/error
157
157
 
158
158
  Without unsafe mode, `unsafeDb` is `undefined`.
@@ -67,7 +67,7 @@ When both CMS and Account UI are enabled, the admin panel's profile page shows a
67
67
  cms: { domain: "cms.example.com", access: "admin" },
68
68
  ```
69
69
 
70
- With `access: "admin"`, non-admin users can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to admins. See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
70
+ With `access: "admin"`, callers outside the platform control-plane roles can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to `userRole: ["appmanager"]` (plus `sysadmin` when enabled). See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
71
71
 
72
72
  ## Related
73
73
 
@@ -196,7 +196,7 @@ ENABLE_ORGANIZATIONS=false
196
196
  ENABLE_ADMIN=false
197
197
  ```
198
198
 
199
- Simple email/password authentication for single-tenant apps.
199
+ Simple email/password authentication for apps that do not need advanced auth methods.
200
200
 
201
201
  ### Maximum Security
202
202
 
@@ -256,7 +256,7 @@ import { setAppConfig } from '@/config/app';
256
256
 
257
257
  setAppConfig({
258
258
  features: {
259
- organizations: false, // Disable organizations
259
+ organizations: false, // Hide organization-management UI
260
260
  passkey: true, // Enable passkey
261
261
  },
262
262
  });
@@ -150,12 +150,12 @@ cms: { domain: "cms.example.com" }
150
150
 
151
151
  This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
152
152
 
153
- CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the Better Auth platform-admin tier) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
153
+ CMS access defaults to `access: "admin"` — only `user.role === "appmanager"` (the Better Auth platform control-plane tier) can reach `/cms/*`. When `cms.sysadmin: true`, `user.role === "sysadmin"` is also admitted. Other authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
154
154
 
155
- - **Account UI** hides the "Go to CMS" button for non-admins.
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
- - **`/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` routes** are gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
155
+ - **Account UI** hides the "Go to CMS" button for callers outside those roles.
156
+ - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-operator. A non-operator who types the CMS URL directly cannot load the app.
157
+ - **`/api/v1/schema`** returns `403 Platform operator access required` to callers outside those roles, so schema metadata can't be scraped by hitting the API directly.
158
+ - **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
159
159
  - **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
160
160
 
161
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.
@@ -168,30 +168,31 @@ cms: { access: "user" }
168
168
 
169
169
  See [Multi-Domain Architecture](/compiler/config/domains) for details on multi-domain routing.
170
170
 
171
- ## Multi-Tenant vs Single-Tenant
171
+ ## Default Org Mode vs Pinned Organization Mode
172
172
 
173
- The CMS supports two authentication modes depending on your project's organization configuration.
173
+ The CMS supports two organization flows depending on your project's config.
174
174
 
175
- ### Multi-Tenant (Default)
175
+ ### Default Org Mode
176
176
 
177
- In multi-tenant mode, the CMS gates access behind organization membership:
177
+ By default, the CMS gates access behind organization membership:
178
178
 
179
179
  1. User logs in via Better Auth session
180
180
  2. CMS fetches the user's organization memberships
181
181
  3. If the user belongs to multiple organizations, an **org selector** is displayed
182
182
  4. Once an org is selected, the user's role within that org determines their CMS permissions
183
183
 
184
- This is the default behavior for all Quickback projects.
184
+ This is the default behavior for Quickback projects with no pinned org.
185
185
 
186
- ### Single-Tenant Mode
186
+ ### Pinned Organization Mode
187
187
 
188
- When your project disables organizations (`features.organizations: false` in config), the compiler sets `singleTenant: true` in the schema registry. In this mode:
188
+ When your project sets `features.pinnedOrganizationId`, the CMS keeps org-backed auth but fixes the active org at runtime. In this mode:
189
189
 
190
- - No org gate or org selector is shown
191
- - The user's role is read directly from `user.role` on the session
192
- - All data is unscoped (no `organizationId` filtering)
190
+ - No org selector is shown
191
+ - The org gate is bypassed because the active org is known up front
192
+ - The user's `roles` still come from membership in the pinned org
193
+ - Org-scoped data remains scoped by `organizationId`
193
194
 
194
- Single-tenant mode is useful for internal tools, personal projects, or apps that don't need multi-org isolation.
195
+ Pinned organization mode is useful for internal tools, blogs, and one-customer deployments that still want org-backed roles and schema conventions without runtime org switching.
195
196
 
196
197
  ## Next Steps
197
198
 
@@ -21,7 +21,7 @@ The CMS generates its entire UI from your Quickback definitions. Define a table
21
21
  - **Embedded in your Worker** — Set `cms: true` in config. The CMS is served as static assets from the same Cloudflare Worker as your API — same origin, no CORS, auth cookies work naturally.
22
22
  - **Dual view modes** — Table browse mode for navigation and Data Table mode for spreadsheet-style editing.
23
23
  - **Role-based access** — Owner, admin, and member roles with live switching. CRUD buttons hidden when unauthorized.
24
- - **Multi-tenant & single-tenant** — Org-scoped access by default, with single-tenant mode for simpler projects.
24
+ - **Multi-tenant & fixed-org** — Org-scoped access by default, with pinned-organization mode for simpler deployments.
25
25
  - **Inline spreadsheet editing** — Excel/Google Sheets-like editing with keyboard navigation (arrows, Tab, Enter, Escape).
26
26
  - **FK typeahead** — Server-side search for foreign key fields with debounced queries and keyboard navigation.
27
27
  - **Field masking** — Email, phone, SSN, and redaction patterns applied per role. Masked fields show a lock icon.
@@ -109,14 +109,14 @@ cms: { domain: "cms.example.com" }
109
109
 
110
110
  This adds a custom domain route to `wrangler.toml`. Both domains serve the same Worker — `api.example.com` for the API, `cms.example.com` for the CMS. The compiler also auto-infers a unified `quickback.example.com` domain where everything is available. See [Multi-Domain Architecture](/compiler/config/domains).
111
111
 
112
- ### Access gate (admin-only by default)
112
+ ### Access gate (platform-control-plane by default)
113
113
 
114
- CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the user-table role from Better Auth's admin plugin) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at **four layers** — defense in depth:
114
+ CMS access defaults to `access: "admin"` — only `user.role === "appmanager"` (the user-table platform control-plane role) can reach `/cms/*`. When `cms.sysadmin: true`, `user.role === "sysadmin"` is also admitted. Other authenticated users are redirected to `/account/profile`. The gate is enforced at **four layers** — defense in depth:
115
115
 
116
- 1. **Account UI link** — the "Go to CMS" button is hidden for non-admins.
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
- 3. **`/api/v1/schema`** — the CMS metadata endpoint checks `ctx.userRole === "admin"` and returns `403` otherwise.
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.
116
+ 1. **Account UI link** — the "Go to CMS" button is hidden for callers outside those roles.
117
+ 2. **CMS SPA shell** — the Worker returns `403 Platform operator access required` before serving `index.html` to a non-operator. Unauthenticated requests are redirected to the login page.
118
+ 3. **`/api/v1/schema`** — the CMS metadata endpoint checks `ctx.userRole === "appmanager"` (and admits `sysadmin` when enabled) and returns `403` otherwise.
119
+ 4. **`custom_view` routes** — the CMS-internal saved-views table is gated on `userRole: ["appmanager"]` (see the [`userRole` access primitive](/compiler/definitions/access#userrole)) rather than org membership.
120
120
 
121
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
 
@@ -11,7 +11,6 @@ interface SchemaRegistry {
11
11
  generatedAt: string;
12
12
  generatedBy: string;
13
13
  version: string;
14
- singleTenant?: boolean;
15
14
  features: Record<string, string[]>;
16
15
  tables: Record<string, TableMeta>;
17
16
  tablesByFeature: Record<string, string[]>;
@@ -26,7 +25,6 @@ interface SchemaRegistry {
26
25
  | `generatedAt` | ISO 8601 timestamp of when the registry was generated |
27
26
  | `generatedBy` | Always `"quickback-compiler"` |
28
27
  | `version` | Compiler version string |
29
- | `singleTenant` | When `true`, project has no organization layer (single-tenant mode) |
30
28
  | `features` | Map of feature name to array of source file names |
31
29
  | `tables` | Map of camelCase table name to full table metadata |
32
30
  | `tablesByFeature` | Map of feature name to array of table names in that feature |
@@ -24,7 +24,6 @@ The top-level structure of `schema-registry.json`:
24
24
  "generatedAt": "2026-02-14T06:26:53.554Z",
25
25
  "generatedBy": "quickback-compiler",
26
26
  "version": "1.0.0",
27
- "singleTenant": false,
28
27
  "features": { ... },
29
28
  "tables": { ... },
30
29
  "tablesByFeature": { ... },
@@ -39,7 +38,6 @@ The top-level structure of `schema-registry.json`:
39
38
  | `generatedAt` | `string` | ISO timestamp of generation |
40
39
  | `generatedBy` | `string` | Always `"quickback-compiler"` |
41
40
  | `version` | `string` | Compiler version used |
42
- | `singleTenant` | `boolean?` | When `true`, no organization layer |
43
41
  | `features` | `Record<string, string[]>` | Feature name to file list mapping |
44
42
  | `tables` | `Record<string, TableMeta>` | Table name to full metadata |
45
43
  | `tablesByFeature` | `Record<string, string[]>` | Feature name to table name list |
@@ -210,10 +208,6 @@ When features include `definePage()` files (in `features/{name}/pages/`), the co
210
208
 
211
209
  The CMS reads these fields to render custom pages in the sidebar and route to the page renderer. See [Custom Pages](/stack/cms/pages) for the full `definePage()` API.
212
210
 
213
- ## Single-Tenant Mode
214
-
215
- When `singleTenant` is `true` in the registry (set when the project config has `features.organizations: false`), the CMS skips the organization gate and reads the user's role directly from `user.role` on the session instead of from organization membership.
216
-
217
211
  ## Next Steps
218
212
 
219
213
  - **[Connecting](/stack/cms/connecting)** — Demo mode vs. live mode setup
@@ -2,20 +2,20 @@
2
2
 
3
3
  The CMS respects all four Quickback security layers. Every UI element — buttons, form fields, table columns, action menus — adapts based on the current user's role and the security rules defined in your feature files.
4
4
 
5
- ## CMS Access (admin-only by default)
5
+ ## CMS Access (platform-control-plane by default)
6
6
 
7
- The CMS is restricted to Better Auth platform admins (`user.role === "admin"`) by default — non-admin authenticated users are redirected to `/account/profile`. To allow any authenticated user, opt out explicitly:
7
+ The CMS is restricted to Better Auth platform control-plane users (`user.role === "appmanager"`) by default. If `cms.sysadmin: true` is enabled, `user.role === "sysadmin"` is also admitted. Other authenticated users are redirected to `/account/profile`. To allow any authenticated user, opt out explicitly:
8
8
 
9
9
  ```typescript
10
10
  cms: { access: "user" }
11
11
  ```
12
12
 
13
- Under the default `access: "admin"`, the compiler emits server-side gates on every CMS-facing surface so a non-admin can't reach the CMS even by bypassing the SPA:
13
+ Under the default `access: "admin"`, the compiler emits server-side gates on every CMS-facing surface so a non-operator can't reach the CMS even by bypassing the SPA:
14
14
 
15
15
  1. **Account UI** — the "Go to CMS" button is hidden.
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
- 3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to non-admins.
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.
16
+ 2. **CMS SPA shell** — the Worker checks `ctx.userRole === "appmanager"` before serving `index.html`. When `cms.sysadmin: true`, sysadmins are also admitted. Unauthenticated requests are redirected to login; authenticated non-operators get `403 Platform operator access required`.
17
+ 3. **`/api/v1/schema`** — the CMS metadata endpoint returns `403` to callers outside those roles.
18
+ 4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["appmanager"]` (and, when `cms.sysadmin: true`, also admits `sysadmin`), so saved views can't be read or modified from outside the CMS by non-operator 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
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.
@@ -107,7 +107,7 @@ attendee — their realtime socket now opens.
107
107
 
108
108
  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.
109
109
 
110
- Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually via the `createRealtime(env)` helper described below.
110
+ Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually. In action handlers on realtime-enabled projects, Quickback now injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
111
111
 
112
112
  | Mutation site | Auto-broadcast? | Why |
113
113
  |---|---|---|
@@ -121,14 +121,10 @@ The rule of thumb: if your code calls `db.insert(...)` / `scoped.insert(...)` di
121
121
 
122
122
  ## Generated Helper
123
123
 
124
- The `createRealtime()` factory provides convenient methods for both Postgres Changes (CRUD events) and custom broadcasts:
124
+ Action handlers on realtime-enabled projects receive a typed `realtime` param. The underlying `createRealtime()` factory still powers it and remains the API to use from queues, cron jobs, and other non-action code:
125
125
 
126
126
  ```typescript
127
- import { createRealtime } from '../lib/realtime';
128
-
129
- export const execute: ActionExecutor = async ({ db, ctx, input }) => {
130
- const realtime = createRealtime(ctx.env);
131
-
127
+ export const execute: ActionExecutor = async ({ db, ctx, input, realtime }) => {
132
128
  // After creating a record
133
129
  await realtime.insert('applications', newApplication, ctx.activeOrgId!);
134
130
 
@@ -142,6 +138,8 @@ export const execute: ActionExecutor = async ({ db, ctx, input }) => {
142
138
  };
143
139
  ```
144
140
 
141
+ `env` is also typed in action handlers, so custom bindings like R2, D1, Queues, Durable Objects, and auth env vars no longer need `(env as any)` casts.
142
+
145
143
  For explicit targeting, pass an object instead of the historical org string:
146
144
 
147
145
  ```typescript