@quickback-dev/cli 0.65.1 → 0.66.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 (123) hide show
  1. package/dist/commands/compile.d.ts +1 -1
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +13 -0
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/action-harvest.d.ts.map +1 -1
  7. package/dist/lib/action-harvest.js +14 -6
  8. package/dist/lib/action-harvest.js.map +1 -1
  9. package/dist/lib/action-harvest.test.js +26 -0
  10. package/dist/lib/action-harvest.test.js.map +1 -1
  11. package/dist/lib/migrations/drizzle.d.ts.map +1 -1
  12. package/dist/lib/migrations/drizzle.js +6 -1
  13. package/dist/lib/migrations/drizzle.js.map +1 -1
  14. package/dist/lib/migrations/drizzle.test.js +3 -0
  15. package/dist/lib/migrations/drizzle.test.js.map +1 -1
  16. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  17. package/dist/lib/wrangler-resources.js +5 -2
  18. package/dist/lib/wrangler-resources.js.map +1 -1
  19. package/dist/lib/wrangler-resources.test.js +6 -0
  20. package/dist/lib/wrangler-resources.test.js.map +1 -1
  21. package/dist/skill/SKILL.md +18 -3
  22. package/dist/skill/docs/api/batch-operations.md +1 -1
  23. package/dist/skill/docs/api/crud.md +1 -1
  24. package/dist/skill/docs/api/index.md +1 -1
  25. package/dist/skill/docs/api/query-params.md +5 -8
  26. package/dist/skill/docs/changelog/index.md +87 -1
  27. package/dist/skill/docs/configure/auth.md +20 -12
  28. package/dist/skill/docs/configure/domains.md +1 -1
  29. package/dist/skill/docs/configure/index.md +19 -29
  30. package/dist/skill/docs/configure/providers.md +6 -4
  31. package/dist/skill/docs/configure/single-tenant.md +7 -3
  32. package/dist/skill/docs/define/access.md +3 -0
  33. package/dist/skill/docs/define/actions/defining.md +2 -2
  34. package/dist/skill/docs/define/actions/index.md +1 -1
  35. package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
  36. package/dist/skill/docs/define/actions/scoped-db.md +23 -6
  37. package/dist/skill/docs/define/changesets.md +7 -8
  38. package/dist/skill/docs/define/feature.md +3 -2
  39. package/dist/skill/docs/define/firewall.md +2 -0
  40. package/dist/skill/docs/define/index.md +1 -1
  41. package/dist/skill/docs/define/read.md +2 -2
  42. package/dist/skill/docs/define/relationships.md +7 -0
  43. package/dist/skill/docs/define/schema.md +21 -1
  44. package/dist/skill/docs/define/triggers.md +14 -3
  45. package/dist/skill/docs/platform/api-contract/index.md +52 -42
  46. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  47. package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
  48. package/dist/skill/docs/platform/database/d1.md +13 -1
  49. package/dist/skill/docs/platform/database/neon.md +1 -1
  50. package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
  51. package/dist/skill/docs/platform/realtime/index.md +8 -10
  52. package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
  53. package/dist/skill/docs/platform/realtime/using-realtime.md +62 -36
  54. package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
  55. package/dist/skill/docs/start/deploy-browser.md +2 -2
  56. package/dist/skill/docs/start/deploy-owner-access.md +49 -50
  57. package/dist/skill/docs/start/deploy.md +2 -2
  58. package/dist/skill/docs/start/first-api.md +1 -1
  59. package/dist/skill/docs/start/patterns.md +17 -2
  60. package/dist/skill/docs/start/template-cloudflare.md +1 -1
  61. package/dist/skill/docs/tooling/cli.md +1 -1
  62. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  63. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  64. package/dist/skill/docs/tooling/output.md +1 -1
  65. package/dist/skill/docs/ui/account/customization.md +1 -1
  66. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  67. package/dist/skill/docs/ui/account/features/index.md +7 -6
  68. package/dist/skill/docs/ui/account/features/organizations.md +1 -1
  69. package/dist/skill/docs/ui/account/hooks.md +2 -1
  70. package/dist/skill/docs/ui/account/index.md +7 -4
  71. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  72. package/package.json +1 -1
  73. package/src/skill/SKILL.md +18 -3
  74. package/src/skill/docs/api/batch-operations.md +1 -1
  75. package/src/skill/docs/api/crud.md +1 -1
  76. package/src/skill/docs/api/index.md +1 -1
  77. package/src/skill/docs/api/query-params.md +5 -8
  78. package/src/skill/docs/changelog/index.md +87 -1
  79. package/src/skill/docs/configure/auth.md +20 -12
  80. package/src/skill/docs/configure/domains.md +1 -1
  81. package/src/skill/docs/configure/index.md +19 -29
  82. package/src/skill/docs/configure/providers.md +6 -4
  83. package/src/skill/docs/configure/single-tenant.md +7 -3
  84. package/src/skill/docs/define/access.md +3 -0
  85. package/src/skill/docs/define/actions/defining.md +2 -2
  86. package/src/skill/docs/define/actions/index.md +1 -1
  87. package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
  88. package/src/skill/docs/define/actions/scoped-db.md +23 -6
  89. package/src/skill/docs/define/changesets.md +7 -8
  90. package/src/skill/docs/define/feature.md +3 -2
  91. package/src/skill/docs/define/firewall.md +2 -0
  92. package/src/skill/docs/define/index.md +1 -1
  93. package/src/skill/docs/define/read.md +2 -2
  94. package/src/skill/docs/define/relationships.md +7 -0
  95. package/src/skill/docs/define/schema.md +21 -1
  96. package/src/skill/docs/define/triggers.md +14 -3
  97. package/src/skill/docs/platform/api-contract/index.md +52 -42
  98. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  99. package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
  100. package/src/skill/docs/platform/database/d1.md +13 -1
  101. package/src/skill/docs/platform/database/neon.md +1 -1
  102. package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
  103. package/src/skill/docs/platform/realtime/index.md +8 -10
  104. package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
  105. package/src/skill/docs/platform/realtime/using-realtime.md +62 -36
  106. package/src/skill/docs/platform/webhooks/outbound.md +4 -5
  107. package/src/skill/docs/start/deploy-browser.md +2 -2
  108. package/src/skill/docs/start/deploy-owner-access.md +49 -50
  109. package/src/skill/docs/start/deploy.md +2 -2
  110. package/src/skill/docs/start/first-api.md +1 -1
  111. package/src/skill/docs/start/patterns.md +17 -2
  112. package/src/skill/docs/start/template-cloudflare.md +1 -1
  113. package/src/skill/docs/tooling/cli.md +1 -1
  114. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  115. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
  116. package/src/skill/docs/tooling/output.md +1 -1
  117. package/src/skill/docs/ui/account/customization.md +1 -1
  118. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  119. package/src/skill/docs/ui/account/features/index.md +7 -6
  120. package/src/skill/docs/ui/account/features/organizations.md +1 -1
  121. package/src/skill/docs/ui/account/hooks.md +2 -1
  122. package/src/skill/docs/ui/account/index.md +7 -4
  123. package/src/skill/docs/ui/account/with-quickback.md +1 -1
@@ -212,16 +212,20 @@ await realtime.insert('applications', {
212
212
  Broadcasts:
213
213
  ```json
214
214
  {
215
- "type": "postgres_changes",
216
- "table": "applications",
217
- "eventType": "INSERT",
218
- "schema": "public",
219
- "new": {
220
- "id": "app_123",
221
- "candidateId": "cnd_456",
222
- "stage": "applied"
223
- },
224
- "old": null
215
+ "specversion": "1.0",
216
+ "id": "evt_…",
217
+ "source": "/broadcast/v1/websocket",
218
+ "type": "dev.quickback.myapp.applications.insert",
219
+ "time": "2026-08-17T10:04:11.921Z",
220
+ "datacontenttype": "application/json",
221
+ "qbframe": "postgres_changes",
222
+ "data": {
223
+ "table": "applications",
224
+ "schema": "public",
225
+ "eventType": "INSERT",
226
+ "new": { "id": "app_123", "candidateId": "cnd_456", "stage": "applied" },
227
+ "old": null
228
+ }
225
229
  }
226
230
  ```
227
231
 
@@ -238,12 +242,20 @@ await realtime.update('applications',
238
242
  Broadcasts:
239
243
  ```json
240
244
  {
241
- "type": "postgres_changes",
242
- "table": "applications",
243
- "eventType": "UPDATE",
244
- "schema": "public",
245
- "new": { "id": "app_123", "stage": "interview" },
246
- "old": { "id": "app_123", "stage": "screening" }
245
+ "specversion": "1.0",
246
+ "id": "evt_…",
247
+ "source": "/broadcast/v1/websocket",
248
+ "type": "dev.quickback.myapp.applications.update",
249
+ "time": "2026-08-17T10:04:11.921Z",
250
+ "datacontenttype": "application/json",
251
+ "qbframe": "postgres_changes",
252
+ "data": {
253
+ "table": "applications",
254
+ "schema": "public",
255
+ "eventType": "UPDATE",
256
+ "new": { "id": "app_123", "stage": "interview" },
257
+ "old": { "id": "app_123", "stage": "screening" }
258
+ }
247
259
  }
248
260
  ```
249
261
 
@@ -259,12 +271,20 @@ await realtime.delete('applications',
259
271
  Broadcasts:
260
272
  ```json
261
273
  {
262
- "type": "postgres_changes",
263
- "table": "applications",
264
- "eventType": "DELETE",
265
- "schema": "public",
266
- "new": null,
267
- "old": { "id": "app_123" }
274
+ "specversion": "1.0",
275
+ "id": "evt_…",
276
+ "source": "/broadcast/v1/websocket",
277
+ "type": "dev.quickback.myapp.applications.delete",
278
+ "time": "2026-08-17T10:04:11.921Z",
279
+ "datacontenttype": "application/json",
280
+ "qbframe": "postgres_changes",
281
+ "data": {
282
+ "table": "applications",
283
+ "schema": "public",
284
+ "eventType": "DELETE",
285
+ "new": null,
286
+ "old": { "id": "app_123" }
287
+ }
268
288
  }
269
289
  ```
270
290
 
@@ -290,9 +310,14 @@ subscriber) or `['PUBLIC']`.
290
310
  Broadcasts:
291
311
  ```json
292
312
  {
293
- "type": "broadcast",
294
- "event": "screening-complete",
295
- "payload": {
313
+ "specversion": "1.0",
314
+ "id": "evt_…",
315
+ "source": "/broadcast/v1/websocket",
316
+ "type": "screening-complete",
317
+ "time": "2026-08-17T10:04:11.921Z",
318
+ "datacontenttype": "application/json",
319
+ "qbframe": "broadcast",
320
+ "data": {
296
321
  "applicationId": "app_123",
297
322
  "candidateId": "cnd_456",
298
323
  "stage": "interview"
@@ -545,13 +570,16 @@ Tickets expire after 60 seconds, so fetch a fresh one before each connection or
545
570
 
546
571
  ### Handling Messages
547
572
 
573
+ Data frames are [CloudEvents 1.0 envelopes](/platform/realtime/using-realtime#cloudevents-envelopes).
574
+ Discriminate on `qbframe`, never on `type`, and read the body from `data`:
575
+
548
576
  ```typescript
549
577
  ws.onmessage = (event) => {
550
578
  const msg = JSON.parse(event.data);
551
579
 
552
580
  // Handle CRUD events
553
- if (msg.type === 'postgres_changes') {
554
- const { table, eventType, new: newRecord, old: oldRecord } = msg;
581
+ if (msg.qbframe === 'postgres_changes') {
582
+ const { table, eventType, new: newRecord, old: oldRecord } = msg.data;
555
583
 
556
584
  if (eventType === 'INSERT') {
557
585
  addRecord(table, newRecord);
@@ -562,9 +590,10 @@ ws.onmessage = (event) => {
562
590
  }
563
591
  }
564
592
 
565
- // Handle custom broadcasts
566
- if (msg.type === 'broadcast') {
567
- const { event, payload } = msg;
593
+ // Handle custom broadcasts — `type` is your wire name verbatim.
594
+ if (msg.qbframe === 'broadcast') {
595
+ const event = msg.type;
596
+ const payload = msg.data;
568
597
 
569
598
  if (event === 'screening-complete') {
570
599
  refreshApplication(payload.applicationId);
@@ -715,15 +744,19 @@ export const execute: ActionExecutor = async ({ ctx, input }) => {
715
744
 
716
745
  ### Event Format
717
746
 
718
- Custom namespace events use the `broadcast` type with namespaced event names:
747
+ Custom namespace events carry `qbframe: "broadcast"`; the namespaced event
748
+ name is the CloudEvents `type`, verbatim:
719
749
 
720
750
  ```json
721
751
  {
722
- "type": "broadcast",
723
- "event": "screening:started",
724
- "payload": {
725
- "applicationId": "app_123"
726
- }
752
+ "specversion": "1.0",
753
+ "id": "evt_…",
754
+ "source": "/broadcast/v1/websocket",
755
+ "type": "screening:started",
756
+ "time": "2026-08-17T10:04:11.921Z",
757
+ "datacontenttype": "application/json",
758
+ "qbframe": "broadcast",
759
+ "data": { "applicationId": "app_123" }
727
760
  }
728
761
  ```
729
762
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
4
4
 
5
- - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
5
+ - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). Framing is independent of the path: frames are [CloudEvents 1.0](/platform/realtime/using-realtime#cloudevents-envelopes) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
6
6
  - **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -194,20 +194,18 @@ There are **three declarative emission surfaces** — pick by what did the write
194
194
  | A custom action | **`invalidates:`** on the action | [Named invalidations](/platform/realtime/named-invalidations) |
195
195
  | An [aggregate changeset](/define/changesets) (`owns`) | **`afterCommit`** on the aggregate root — one CloudEvent after commit | [changesets → afterCommit](/define/changesets#aftercommit--emit-a-realtime-signal-after-the-changeset-commits) |
196
196
 
197
- ## CloudEvents (contract v2) + AsyncAPI (any contract)
197
+ ## CloudEvents + AsyncAPI
198
198
 
199
- On the v2 contract, realtime data frames are delivered as CloudEvents 1.0
200
- envelopes (control frames stay raw); the path stays wherever `contract.routes`
201
- mounts it. See
202
- [Using Realtime](/platform/realtime/using-realtime#cloudevents-envelopes-contract-v2)
199
+ Realtime data frames are delivered as CloudEvents 1.0 envelopes (control
200
+ frames stay raw), on whatever path `contract.routes` mounts. Match frames on
201
+ the `qbframe` extension, never on `type`. See
202
+ [Using Realtime](/platform/realtime/using-realtime#cloudevents-envelopes)
203
203
  for the frame mapping.
204
204
 
205
205
  The project's event surface — realtime channels, named-invalidation events,
206
206
  and outbound webhook messages — is published as an AsyncAPI 3.0 document at
207
- `GET /asyncapi.json` (same auth gating as `/openapi.json`). The document is
208
- **contract-version-independent**: it is emitted for any project with realtime
209
- or webhooks (v1 included); only the message payload *schemas* are shaped by
210
- the pinned contract — raw frames on v1, CloudEvents envelopes on v2.
207
+ `GET /asyncapi.json` (same auth gating as `/openapi.json`), for any project
208
+ with realtime or webhooks.
211
209
 
212
210
  ## Realtime emit from actions
213
211
 
@@ -32,7 +32,7 @@ export const attendRealtime = defineRealtime({
32
32
  events: {
33
33
  mobileBundleChanged: {
34
34
  wireName: "event.mobile-bundle.changed", // clients listen for this
35
- version: 1, // contract version (baked into every frame)
35
+ version: 1, // event version (rides as qbversion)
36
36
  variants: {
37
37
  documentCreated: {
38
38
  reason: "document.created", // clients branch on this
@@ -121,26 +121,40 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
121
121
  - **After-commit, best-effort.** Calls queue frames that fire only after `execute` returns successfully; a `throw` or a `dryRun` discards them (they ride the after-commit effects collector). A rolled-back batch record fires nothing.
122
122
  - **Fail-closed targeting.** An unresolvable scope room or a missing recipient set delivers to nobody — never a broad fan-out.
123
123
  - **Projection.** The frame payload is projected to the variant's declared keys; undeclared fields never reach the wire.
124
- - **Contract fields.** `version` and `reason` are baked from the registry and always present.
124
+ - **Contract fields.** `version` and `reason` are baked from the registry and always present, riding as the `qbversion` / `qbreason` CloudEvents extensions.
125
125
 
126
126
  ## The wire frame
127
127
 
128
- Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
128
+ Clients receive a [CloudEvents 1.0](/platform/realtime/using-realtime#cloudevents-envelopes)
129
+ frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
129
130
 
130
131
  ```jsonc
131
132
  {
132
- "type": "broadcast",
133
- "event": "event.mobile-bundle.changed", // the wireName
134
- "payload": {
135
- "version": 1, // contract version → negotiation
136
- "reason": "document.created", // what changed → what to refresh
133
+ "specversion": "1.0",
134
+ "id": "evt_9f2…",
135
+ "source": "/broadcast/v1/websocket",
136
+ "type": "event.mobile-bundle.changed", // the wireName, VERBATIM
137
+ "time": "2026-08-17T10:04:11.921Z",
138
+ "datacontenttype": "application/json",
139
+ "qbframe": "broadcast", // the discriminator — match on this
140
+ "qbversion": 1, // event version → negotiation
141
+ "qbreason": "document.created", // what changed → what to refresh
142
+ "data": { // payload MINUS version/reason
137
143
  "eventId": "evt_1",
138
144
  "documentId": "doc_9"
139
145
  }
140
146
  }
141
147
  ```
142
148
 
143
- Subscribe to the `wireName`, use `version` for contract negotiation, and branch on `reason` to decide which query/cache to invalidate. Role gating (`targetRoles`) and — when a recipient resolver is used — identity narrowing (`targetTags`) are applied by the Broadcaster before the frame reaches any socket; the client just receives the frames meant for it.
149
+ `version` and `reason` ride as the `qbversion` / `qbreason` extension
150
+ attributes, not inside `data` — the projected payload keys are `data`'s only
151
+ contents. Your `wireName` is the `type` verbatim: author-supplied event names
152
+ are never reverse-DNS prefixed.
153
+
154
+ Match on `qbframe === "broadcast"` (never on `type`, whose shape is not a
155
+ stable contract), then dispatch on `type` for the wireName, use `qbversion` for
156
+ negotiation, and branch on `qbreason` to decide which query/cache to
157
+ invalidate. Role gating (`targetRoles`) and — when a recipient resolver is used — identity narrowing (`targetTags`) are applied by the Broadcaster before the frame reaches any socket; the client just receives the frames meant for it.
144
158
 
145
159
  ## Related
146
160
 
@@ -56,14 +56,16 @@ If the ticket is invalid or expired, the WebSocket upgrade is rejected with a 40
56
56
 
57
57
  ### CRUD Events
58
58
 
59
- CRUD events use the `postgres_changes` type:
59
+ Data frames are [CloudEvents 1.0 envelopes](#cloudevents-envelopes).
60
+ Discriminate on the `qbframe` extension — **never** on `type`, whose shape is
61
+ not a stable contract — and read the row from `data`:
60
62
 
61
63
  ```typescript
62
64
  ws.onmessage = (event) => {
63
65
  const msg = JSON.parse(event.data);
64
66
 
65
- if (msg.type === "postgres_changes") {
66
- const { table, eventType, new: newRecord, old: oldRecord } = msg;
67
+ if (msg.qbframe === "postgres_changes") {
68
+ const { table, eventType, new: newRecord, old: oldRecord } = msg.data;
67
69
 
68
70
  switch (eventType) {
69
71
  case "INSERT":
@@ -84,12 +86,20 @@ ws.onmessage = (event) => {
84
86
 
85
87
  ```json
86
88
  {
87
- "type": "postgres_changes",
88
- "table": "applications",
89
- "schema": "public",
90
- "eventType": "INSERT",
91
- "new": { "id": "app_123", "candidateId": "cnd_456", "stage": "interview" },
92
- "old": null
89
+ "specversion": "1.0",
90
+ "id": "evt_5b1c…",
91
+ "source": "/broadcast/v1/websocket",
92
+ "type": "dev.quickback.myapp.applications.insert",
93
+ "time": "2026-08-17T10:04:11.921Z",
94
+ "datacontenttype": "application/json",
95
+ "qbframe": "postgres_changes",
96
+ "data": {
97
+ "table": "applications",
98
+ "schema": "public",
99
+ "eventType": "INSERT",
100
+ "new": { "id": "app_123", "candidateId": "cnd_456", "stage": "interview" },
101
+ "old": null
102
+ }
93
103
  }
94
104
  ```
95
105
 
@@ -97,11 +107,13 @@ For UPDATE events, both `new` and `old` are populated. For DELETE events, only `
97
107
 
98
108
  ### Custom Broadcasts
99
109
 
100
- Custom events use the `broadcast` type:
110
+ Custom events carry `qbframe: "broadcast"`. Their `type` is your wire name
111
+ verbatim — author-supplied names are never prefixed:
101
112
 
102
113
  ```typescript
103
- if (msg.type === "broadcast") {
104
- const { event, payload } = msg;
114
+ if (msg.qbframe === "broadcast") {
115
+ const event = msg.type;
116
+ const payload = msg.data;
105
117
 
106
118
  if (event === "screening-complete") {
107
119
  refreshApplication(payload.applicationId);
@@ -115,9 +127,14 @@ if (msg.type === "broadcast") {
115
127
 
116
128
  ```json
117
129
  {
118
- "type": "broadcast",
119
- "event": "screening-complete",
120
- "payload": {
130
+ "specversion": "1.0",
131
+ "id": "evt_a71f…",
132
+ "source": "/broadcast/v1/websocket",
133
+ "type": "screening-complete",
134
+ "time": "2026-08-17T10:04:11.921Z",
135
+ "datacontenttype": "application/json",
136
+ "qbframe": "broadcast",
137
+ "data": {
121
138
  "applicationId": "app_123",
122
139
  "candidateId": "cnd_456",
123
140
  "stage": "interview"
@@ -125,6 +142,9 @@ if (msg.type === "broadcast") {
125
142
  }
126
143
  ```
127
144
 
145
+ `type` is your wire name verbatim — author-supplied event names are never
146
+ prefixed. Match on `qbframe`, not `type`.
147
+
128
148
  Custom namespaces (from `defineRealtime()`) use the format `namespace:event` — e.g., `screening:started`, `screening:progress`.
129
149
 
130
150
  ## Security
@@ -212,26 +232,32 @@ tag = "v1"
212
232
  new_classes = ["Broadcaster"]
213
233
  ```
214
234
 
215
- ## CloudEvents envelopes (contract v2)
235
+ ## CloudEvents envelopes
216
236
 
217
- On `contract: { version: "v2" }` every **data frame** is wrapped in a
218
- [CloudEvents 1.0](https://cloudevents.io) envelope at the Durable Object's
219
- send boundary. The endpoint does **not** move — the path segment tracks
220
- `contract.routes` (so `/broadcast/v1` unless you also set `routes: "v2"`);
221
- `version` changes only the frame format. Control frames (`pong`, `error`,
222
- `reauth_ok`) stay raw on both versions, and pinned-v1 projects keep the raw
223
- frames byte-identically.
237
+ Every **data frame** is wrapped in a [CloudEvents 1.0](https://cloudevents.io)
238
+ envelope at the Durable Object's send boundary. Control frames (`pong`,
239
+ `error`, `reauth_ok`) stay raw.
224
240
 
225
- | v1 frame | CloudEvents `type` | `data` | extensions |
241
+ The endpoint path is independent of the framing — it tracks `contract.routes`,
242
+ so `/broadcast/v1` unless you set `routes: "v2"`. Frames are CloudEvents on
243
+ either path.
244
+
245
+ | Frame | CloudEvents `type` | `data` | extensions |
226
246
  |---|---|---|---|
227
247
  | `broadcast` (named invalidation) | the wire name verbatim | payload minus `version`/`reason` | `qbframe: "broadcast"`, `qbversion`, `qbreason` |
228
- | `postgres_changes` | `<project>.<table>.<insert\|update\|delete>` | `{ table, schema, eventType, new, old }` | `qbframe: "postgres_changes"` |
229
- | `view_changes` | `<project>.view.<viewName>.changed` | `{ view, rootId, delta }` | `qbframe: "view_changes"`, `qbseq` (the per-surface monotonic seq — your reconnect/gap-detection contract) |
248
+ | `postgres_changes` | `dev.quickback.<project>.<table>.<insert\|update\|delete>` | `{ table, schema, eventType, new, old }` | `qbframe: "postgres_changes"` |
249
+ | `view_changes` | `dev.quickback.<project>.view.<viewName>.changed` | `{ view, rootId, delta }` | `qbframe: "view_changes"`, `qbseq` (the per-surface monotonic seq — your reconnect/gap-detection contract) |
250
+
251
+ **Discriminate frames on the `qbframe` extension.** Never on `type`, whose
252
+ shape is not a stable contract, and never on payload keys — named-invalidation
253
+ payloads are author-supplied maps, so a broadcast whose payload happens to
254
+ carry `view`/`delta` or `table`/`eventType` keys must not be mistaken for a
255
+ system frame.
230
256
 
231
- Discriminate frames on the `qbframe` extension, **never** on payload keys —
232
- named-invalidation payloads are author-supplied maps, so a broadcast whose
233
- payload happens to carry `view`/`delta` or `table`/`eventType` keys must not
234
- be mistaken for a system frame.
257
+ Compiler-defined types carry the `dev.quickback.` reverse-DNS prefix, per the
258
+ CloudEvents core spec: the prefixed domain names whoever defines the event's
259
+ semantics. Your own broadcast wire names are **not** prefixed — that vocabulary
260
+ is yours.
235
261
 
236
262
  A changeset's [`afterCommit`](/define/changesets#aftercommit--emit-a-realtime-signal-after-the-changeset-commits)
237
263
  broadcast rides the **same `broadcast` frame** (the referenced typed event's
@@ -252,12 +278,12 @@ as a normal `postgres_changes` frame on the table's room.
252
278
  "data": { "eventId": "…", "documentId": "…" } }
253
279
  ```
254
280
 
255
- The bundled CMS unwraps envelopes automatically. The full channel/message
256
- catalog ships as `GET /asyncapi.json` (AsyncAPI 3.0), served under the same
257
- auth gating as `/openapi.json`. The catalog itself is not v2-only — any
258
- project with realtime or webhooks serves it, on either contract version;
259
- what the pinned contract shapes is the message payload schemas it documents
260
- (raw frames on v1, the CloudEvents envelopes above on v2).
281
+ The bundled CMS and Account SPAs consume these envelopes as-is:
282
+ match on `qbframe`, read the row from `data`, and (for live views) the
283
+ monotonic seq from `qbseq`. The full channel/message catalog ships as
284
+ `GET /asyncapi.json` (AsyncAPI 3.0), served under the same auth gating as
285
+ `/openapi.json`. Any project with realtime or webhooks serves it, and it
286
+ documents the CloudEvents envelopes above.
261
287
 
262
288
  ## Cloudflare Only
263
289
 
@@ -339,11 +339,10 @@ format:
339
339
  | `webhook-timestamp` | unix seconds |
340
340
  | `webhook-signature` | `v1,<base64 HMAC-SHA256 over id.timestamp.body>` |
341
341
 
342
- On **contract v1** these are sent **in addition to** the legacy
343
- `X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery` set, so
344
- existing receivers keep working during the migration window. On
345
- **contract v2** only the Standard Webhooks headers are sent — the legacy set
346
- (and its Stripe-format signature) is dropped.
342
+ These are the **only** signature headers sent. The legacy
343
+ `X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery` set, and its
344
+ Stripe-format signature, are gone — a receiver still reading them sees no
345
+ signature at all, so move verification onto `webhook-signature` first.
347
346
 
348
347
  Receiver verification (any Standard Webhooks library works):
349
348
 
@@ -113,7 +113,7 @@ Deploy is disabled while a reconnect is pending, so a deploy never starts on a c
113
113
 
114
114
  ### Reconnecting
115
115
 
116
- **Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and claim links all keep working. Reconnecting is also how you widen a grant that's missing a permission.
116
+ **Reconnect** re-runs the same consent and lands on the **same connection record** — your account picker, deploys, and admin password reset all keep working. Reconnecting is also how you widen a grant that's missing a permission.
117
117
 
118
118
  ### Connecting more than one Cloudflare account
119
119
 
@@ -177,7 +177,7 @@ Start keeps a chip above the composer naming the app this chat deployed, with li
177
177
  Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
178
178
 
179
179
  - **API-only apps** serve a small landing page at `/` (browsers) and a JSON service descriptor (everything else), linking `/api/v1`, `/openapi.json`, and `/health` — never a bare 404 on first visit.
180
- - **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS needs `user.role === "appmanager"`, which your first deploy seeds for you — see [Owner access](/start/deploy-owner-access).
180
+ - **Apps with the Account UI or CMS** redirect `/` to the login page or CMS. Both ship by default from Start, at `/cms/` and `/account/`. The CMS needs `user.role === "sysadmin"`, which your first deploy seeds (along with a first organization) — see [Owner access](/start/deploy-owner-access).
181
181
  - `/health` reports status and whether email is configured.
182
182
 
183
183
  The deployed app is a normal Worker in *your* account: logs, metrics, and settings live in your Cloudflare dashboard, and you can take over management with the CLI at any time — download the project from Start and `quickback deploy` picks up the same resources.
@@ -1,73 +1,72 @@
1
1
  # Owner access after a browser deploy
2
2
 
3
3
  When you deploy from Quickback Start's **Deploy to Cloudflare** card, the very
4
- first deploy seeds your app's first administrator (an `appmanager` user) and
5
- shows a **one-time claim link** next to the live URL:
4
+ first deploy seeds your app's first administrator (`user.role === "sysadmin"`),
5
+ a first organization they own, and a password. The card shows the **email**, a
6
+ **click-to-reveal password**, and a normal link to your app's Account login:
6
7
 
7
8
  ```
8
- https://<your-app>.<subdomain>.workers.dev/__quickback/claim#token=…
9
+ https://<your-app>.<subdomain>.workers.dev/account/login
9
10
  ```
10
11
 
11
- Opening it lets you set your email and a password, and you're the app's admin.
12
- That's the whole setup.
13
-
14
- ## What the claim link is
15
-
16
- - **One-time and short-lived.** The link works once and expires about six
17
- hours after the deploy. It's shown exactly once, in the deploy card —
18
- Quickback keeps no copy of it.
19
- - **Owner-only.** The link can only claim the admin account the deploy
20
- seeded. It can never create a new account or elevate an existing one.
21
- - **Fragment-carried.** The token rides the URL fragment (`#token=…`), which
22
- browsers never send to servers — it stays out of request logs entirely.
23
- - **Closed once it's used.** The claim page checks the link before it renders
24
- anything: a spent, expired, or unrecognised token gets a "this app has
25
- already been claimed" message instead of a form. Visiting
26
- `/__quickback/claim` without a valid token never shows a working signup.
27
-
28
- The record of a used link lives in your app's own database, so single-use is
29
- enforced exactly — there's no window in which a spent link claims again.
30
-
31
- ## What happens when you claim
32
-
33
- 1. You open the link and choose your **email** and a **password** (the seeded
34
- placeholder email is synthetic — deployed apps can't send mail, so your
35
- chosen address is marked verified directly).
36
- 2. From that moment you sign in through **your app's own auth** — the same
37
- email + password login every other user of your app gets. If your app has
38
- the Account UI enabled, you land on `/account`; API-only apps sign in via
39
- `POST /auth/v1/sign-in/email`.
12
+ Sign in with that email and password. That's the whole setup. After sign-in,
13
+ `/cms/` opens because the seeded role is `sysadmin` — the CMS data-plane tier,
14
+ one above `appmanager`.
15
+
16
+ ## What you get
17
+
18
+ - **Shown once.** The plaintext password is returned to Start on the deploy
19
+ that created the admin, and again only if you explicitly reset it. Quickback
20
+ stores the hash in your app's auth database, never the password.
21
+ - **A first organization.** The deploy also inserts an organization named after
22
+ your Worker and seats the admin as `owner`, so org-scoped tables and the CMS
23
+ tenant picker have somewhere to land. A routine redeploy does not create a
24
+ second one. If the compiled config sets `features.pinnedOrganizationId`, that
25
+ string **is** the organization id — the pin and the AUTH_DB row match, the
26
+ CMS skips the tenant picker, and the seeded sysadmin is `owner` of that org
27
+ (so create/update/delete in the CMS actually work). Without a pin the id is
28
+ a random hex.
29
+ - **Your app's login.** After that reveal you sign in through **your app's
30
+ own auth** — the same email + password login every other user of your app
31
+ gets. If your app has the Account UI enabled, that's `/account/login`.
32
+ - **A public URL, not a secret.** The login link is an ordinary
33
+ `<a href="…/account/login">`. It does not carry a token. Anyone can open
34
+ the page; only the password signs you in.
35
+
36
+ The synthetic email looks like `owner@<your-app>.invalid`. Type it exactly as
37
+ shown next to the password.
40
38
 
41
39
  ## Signing up yourself doesn't make you an admin
42
40
 
43
41
  `/account/signup` creates an ordinary user. It never sets
44
- `role === "appmanager"`, so that account can't open `/cms/`. The claim link is
45
- the only path to the first admin.
42
+ `role === "sysadmin"`, so that account can't open `/cms/`. The seeded
43
+ admin is the only path to the first administrator.
46
44
 
47
45
  No confirmation email is sent, either — apps built from Start default to email
48
46
  and password with verification off, because a `workers.dev` deploy has no
49
47
  verified sending domain. If you're waiting on a signup email, nothing is
50
- coming; open the claim link instead, or re-issue one from the deploy card.
48
+ coming; use the credentials on the deploy card.
51
49
 
52
- **Quickback is not your app's identity provider.** The claim link is a
53
- bootstrap window, not a login method: once claimed (or expired), your app has
54
- no runtime dependency on Quickback or the deploy broker for authentication.
50
+ **Quickback is not your app's identity provider.** The password reveal is a
51
+ bootstrap window, not a login method: once you've signed in (or reset), your
52
+ app has no runtime dependency on Quickback or the deploy broker for
53
+ authentication.
55
54
 
56
- ## Lost access? Re-issue from Start
55
+ ## Lost access? Reset from Start
57
56
 
58
57
  Deployed apps on `workers.dev` can't send password-reset email, so your
59
- Cloudflare account is the recovery root: in the deploy card, **Re-issue admin
60
- claim link** mints a fresh link — authorized by the same Cloudflare connection
61
- that deployed the app. Re-claiming resets the admin password.
58
+ Cloudflare account is the recovery root: in the deploy card (or the chip above
59
+ the composer), **Reset admin password** writes a new hash and shows a fresh
60
+ password once — authorized by the same Cloudflare connection that deployed
61
+ the app.
62
62
 
63
- Every issue **rotates the signing key**, so any older link immediately stops
64
- working, claimed or not. A fresh link re-opens the claim page on its own —
65
- nothing has to be reset first, because "claimable" just means a signed,
66
- unexpired, unused token exists.
63
+ A routine redeploy does **not** re-surface credentials. Only an explicit
64
+ reset does.
67
65
 
68
66
  ## For CLI deploys
69
67
 
70
- The claim route only activates when the `QUICKBACK_CLAIM_KEY` Worker secret is
71
- set — the browser-deploy broker mints it automatically. Apps deployed with
72
- `quickback deploy` don't get a claim link (the route answers 404); create your
73
- admin through your own flow, or deploy once through Start to bootstrap.
68
+ Browser deploys seed the admin automatically. Apps deployed with
69
+ `quickback deploy` don't; create your admin through your own flow, or deploy
70
+ once through Start to bootstrap. The generated `/__quickback/claim` route
71
+ still exists for older apps and answers 404 unless a leftover
72
+ `QUICKBACK_CLAIM_KEY` Worker secret is set — new deploys do not set it.
@@ -15,7 +15,7 @@ cd my-app && quickback deploy
15
15
  1. **Preflight** — verifies `wrangler` is runnable (via `npx`) and authenticated with Cloudflare (`wrangler whoami`). Log in with `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`.
16
16
  2. **Compiles first if needed** — if the project has never compiled (no `wrangler.toml`), it runs the same flow as `quickback compile` before planning anything.
17
17
  3. **Plans from wrangler.toml** — reads the generated `wrangler.toml` and finds every resource whose id is still a placeholder:
18
- - **D1 databases** — auth, features, files, and webhooks databases (whichever your project's features pull in; split-database projects get one entry each)
18
+ - **D1 databases** — auth, features, files, webhooks, and audit databases (whichever your project's features pull in; split-database projects get one entry each)
19
19
  - **KV namespace** — the `KV` binding used for rate limiting and session overflow
20
20
  - **R2 buckets** — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)
21
21
  4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
@@ -78,7 +78,7 @@ Re-run with `--force` to take Cloudflare's value, or fix the config by hand.
78
78
 
79
79
  ## Notes
80
80
 
81
- - **Security-audit database** — projects using unsafe cross-tenant actions require an audit D1 database, and the compiler fails closed at compile time until `auditDatabaseId` is set. Follow the compile error's instructions (create the database, set the id), then re-run `quickback deploy`.
81
+ - **Security-audit database** — projects using unsafe, `PUBLIC`, or hard-delete actions get an `AUDIT_DB` D1. Compile emits a placeholder id; `quickback deploy` creates the database and writes `auditDatabaseId` back, same as AUTH_DB / features DB. Direct `wrangler deploy` of the placeholder fails Cloudflare 10021 — use `quickback deploy`.
82
82
  - **Neon projects** — `quickback deploy` does not apply Postgres migrations. Run `npm run db:migrate` (needs `DATABASE_MIGRATION_URL`) before traffic hits the worker, or use the generated project's `npm run deploy` script which chains both.
83
83
  - **Hyperdrive** — a Hyperdrive binding can't be auto-created (it needs your database connection string). Create it with `wrangler hyperdrive create <name> --connection-string=… --caching-disabled` and set `providers.database.config.hyperdrive.id`.
84
84
  - **Two logins** — the compile step uses your Quickback account (`quickback login`); resource creation and deploy use your wrangler credentials.
@@ -70,7 +70,7 @@ export default feature('candidates', {
70
70
  });
71
71
  ```
72
72
 
73
- > `mode: 'hard'` is also available, but hard deletes erase the row — so they require the security-audit pipeline. On D1 that means setting `auditDatabaseId` on the database provider config (the compiler errors with setup instructions if it's missing). A table only drops `...q.softDelete()` when **both** `delete.mode` and `batchDelete.mode` are `'hard'`; declaring the pair on a hard-delete table is itself a compile error.
73
+ > `mode: 'hard'` is also available, but hard deletes erase the row — so they require the security-audit pipeline. On D1 the compiler emits an `AUDIT_DB` binding (placeholder id until `quickback deploy` creates the database). A table only drops `...q.softDelete()` when **both** `delete.mode` and `batchDelete.mode` are `'hard'`; declaring the pair on a hard-delete table is itself a compile error.
74
74
 
75
75
  > Prefer the explicit two-export form (or interop with existing Drizzle schemas)? See [feature() — single-export sugar](/define/feature) and [Schema: choosing between `q` and Drizzle](/define/schema#choosing-between-q-and-drizzle). All forms compile identically; mix freely per file.
76
76