@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.
- package/dist/commands/compile.d.ts +1 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -0
- package/dist/commands/compile.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +14 -6
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +26 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle.js +6 -1
- package/dist/lib/migrations/drizzle.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +3 -0
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +5 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +6 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/skill/SKILL.md +18 -3
- package/dist/skill/docs/api/batch-operations.md +1 -1
- package/dist/skill/docs/api/crud.md +1 -1
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/query-params.md +5 -8
- package/dist/skill/docs/changelog/index.md +87 -1
- package/dist/skill/docs/configure/auth.md +20 -12
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +19 -29
- package/dist/skill/docs/configure/providers.md +6 -4
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/define/access.md +3 -0
- package/dist/skill/docs/define/actions/defining.md +2 -2
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +23 -6
- package/dist/skill/docs/define/changesets.md +7 -8
- package/dist/skill/docs/define/feature.md +3 -2
- package/dist/skill/docs/define/firewall.md +2 -0
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/read.md +2 -2
- package/dist/skill/docs/define/relationships.md +7 -0
- package/dist/skill/docs/define/schema.md +21 -1
- package/dist/skill/docs/define/triggers.md +14 -3
- package/dist/skill/docs/platform/api-contract/index.md +52 -42
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +13 -1
- package/dist/skill/docs/platform/database/neon.md +1 -1
- package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/dist/skill/docs/platform/realtime/index.md +8 -10
- package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/dist/skill/docs/platform/realtime/using-realtime.md +62 -36
- package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
- package/dist/skill/docs/start/deploy-browser.md +2 -2
- package/dist/skill/docs/start/deploy-owner-access.md +49 -50
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/patterns.md +17 -2
- package/dist/skill/docs/start/template-cloudflare.md +1 -1
- package/dist/skill/docs/tooling/cli.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/dist/skill/docs/tooling/output.md +1 -1
- package/dist/skill/docs/ui/account/customization.md +1 -1
- package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/index.md +7 -6
- package/dist/skill/docs/ui/account/features/organizations.md +1 -1
- package/dist/skill/docs/ui/account/hooks.md +2 -1
- package/dist/skill/docs/ui/account/index.md +7 -4
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +18 -3
- package/src/skill/docs/api/batch-operations.md +1 -1
- package/src/skill/docs/api/crud.md +1 -1
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/query-params.md +5 -8
- package/src/skill/docs/changelog/index.md +87 -1
- package/src/skill/docs/configure/auth.md +20 -12
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +19 -29
- package/src/skill/docs/configure/providers.md +6 -4
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/define/access.md +3 -0
- package/src/skill/docs/define/actions/defining.md +2 -2
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/src/skill/docs/define/actions/scoped-db.md +23 -6
- package/src/skill/docs/define/changesets.md +7 -8
- package/src/skill/docs/define/feature.md +3 -2
- package/src/skill/docs/define/firewall.md +2 -0
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/read.md +2 -2
- package/src/skill/docs/define/relationships.md +7 -0
- package/src/skill/docs/define/schema.md +21 -1
- package/src/skill/docs/define/triggers.md +14 -3
- package/src/skill/docs/platform/api-contract/index.md +52 -42
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/src/skill/docs/platform/database/d1.md +13 -1
- package/src/skill/docs/platform/database/neon.md +1 -1
- package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/src/skill/docs/platform/realtime/index.md +8 -10
- package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/src/skill/docs/platform/realtime/using-realtime.md +62 -36
- package/src/skill/docs/platform/webhooks/outbound.md +4 -5
- package/src/skill/docs/start/deploy-browser.md +2 -2
- package/src/skill/docs/start/deploy-owner-access.md +49 -50
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/patterns.md +17 -2
- package/src/skill/docs/start/template-cloudflare.md +1 -1
- package/src/skill/docs/tooling/cli.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/src/skill/docs/tooling/output.md +1 -1
- package/src/skill/docs/ui/account/customization.md +1 -1
- package/src/skill/docs/ui/account/features/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/index.md +7 -6
- package/src/skill/docs/ui/account/features/organizations.md +1 -1
- package/src/skill/docs/ui/account/hooks.md +2 -1
- package/src/skill/docs/ui/account/index.md +7 -4
- 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
|
-
"
|
|
216
|
-
"
|
|
217
|
-
"
|
|
218
|
-
"
|
|
219
|
-
"
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
-
"
|
|
242
|
-
"
|
|
243
|
-
"
|
|
244
|
-
"
|
|
245
|
-
"
|
|
246
|
-
"
|
|
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
|
-
"
|
|
263
|
-
"
|
|
264
|
-
"
|
|
265
|
-
"
|
|
266
|
-
"
|
|
267
|
-
"
|
|
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
|
-
"
|
|
294
|
-
"
|
|
295
|
-
"
|
|
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.
|
|
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.
|
|
567
|
-
const
|
|
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
|
|
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
|
-
"
|
|
723
|
-
"
|
|
724
|
-
"
|
|
725
|
-
|
|
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).
|
|
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
|
|
197
|
+
## CloudEvents + AsyncAPI
|
|
198
198
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
[Using Realtime](/platform/realtime/using-realtime#cloudevents-envelopes
|
|
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`)
|
|
208
|
-
|
|
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, //
|
|
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
|
|
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
|
-
"
|
|
133
|
-
"
|
|
134
|
-
"
|
|
135
|
-
|
|
136
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
"
|
|
88
|
-
"
|
|
89
|
-
"
|
|
90
|
-
"
|
|
91
|
-
"
|
|
92
|
-
"
|
|
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
|
|
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.
|
|
104
|
-
const
|
|
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
|
-
"
|
|
119
|
-
"
|
|
120
|
-
"
|
|
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
|
|
235
|
+
## CloudEvents envelopes
|
|
216
236
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
-
|
|
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` |
|
|
229
|
-
| `view_changes` |
|
|
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
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
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
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
|
|
343
|
-
`X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery` set,
|
|
344
|
-
|
|
345
|
-
|
|
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
|
|
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 === "
|
|
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 (
|
|
5
|
-
|
|
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/
|
|
9
|
+
https://<your-app>.<subdomain>.workers.dev/account/login
|
|
9
10
|
```
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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 === "
|
|
45
|
-
the only path to the first
|
|
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;
|
|
48
|
+
coming; use the credentials on the deploy card.
|
|
51
49
|
|
|
52
|
-
**Quickback is not your app's identity provider.** The
|
|
53
|
-
bootstrap window, not a login method: once
|
|
54
|
-
no runtime dependency on Quickback or the deploy broker for
|
|
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?
|
|
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
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
64
|
-
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|