@quickback-dev/cli 0.16.4 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +7 -3
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +12 -48
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/commands/create.d.ts +20 -0
  6. package/dist/commands/create.d.ts.map +1 -1
  7. package/dist/commands/create.js +216 -151
  8. package/dist/commands/create.js.map +1 -1
  9. package/dist/commands/login.d.ts +4 -2
  10. package/dist/commands/login.d.ts.map +1 -1
  11. package/dist/commands/login.js +25 -17
  12. package/dist/commands/login.js.map +1 -1
  13. package/dist/commands/start.d.ts +20 -0
  14. package/dist/commands/start.d.ts.map +1 -0
  15. package/dist/commands/start.js +163 -0
  16. package/dist/commands/start.js.map +1 -0
  17. package/dist/commands/whoami.d.ts.map +1 -1
  18. package/dist/commands/whoami.js +5 -4
  19. package/dist/commands/whoami.js.map +1 -1
  20. package/dist/docs/content.js +37 -37
  21. package/dist/docs/content.js.map +1 -1
  22. package/dist/index.js +27 -10
  23. package/dist/index.js.map +1 -1
  24. package/dist/lib/api-client.js +1 -1
  25. package/dist/lib/api-client.js.map +1 -1
  26. package/dist/lib/api-client.test.js +15 -0
  27. package/dist/lib/api-client.test.js.map +1 -1
  28. package/dist/lib/auth.d.ts +39 -3
  29. package/dist/lib/auth.d.ts.map +1 -1
  30. package/dist/lib/auth.js +57 -3
  31. package/dist/lib/auth.js.map +1 -1
  32. package/dist/lib/drizzle-meta-routing.test.js +16 -3
  33. package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
  34. package/dist/lib/file-loader.d.ts +6 -4
  35. package/dist/lib/file-loader.d.ts.map +1 -1
  36. package/dist/lib/file-loader.js +30 -27
  37. package/dist/lib/file-loader.js.map +1 -1
  38. package/dist/lib/file-loader.test.js +16 -7
  39. package/dist/lib/file-loader.test.js.map +1 -1
  40. package/dist/skill/docs/changelog.md +145 -0
  41. package/dist/skill/docs/compiler/config/providers.md +87 -0
  42. package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
  43. package/dist/skill/docs/compiler/definitions/access.md +43 -57
  44. package/dist/skill/docs/compiler/definitions/feature.md +7 -11
  45. package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
  46. package/dist/skill/docs/compiler/definitions/guards.md +16 -18
  47. package/dist/skill/docs/compiler/definitions/index.md +10 -14
  48. package/dist/skill/docs/compiler/definitions/masking.md +6 -6
  49. package/dist/skill/docs/compiler/definitions/read.md +6 -11
  50. package/dist/skill/docs/compiler/definitions/schema.md +19 -17
  51. package/dist/skill/docs/compiler/definitions/views.md +3 -5
  52. package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
  53. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  54. package/dist/skill/docs/compiler/getting-started/index.md +23 -20
  55. package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
  56. package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
  57. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
  58. package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  63. package/dist/skill/docs/compiler/troubleshooting.md +10 -0
  64. package/dist/skill/docs/stack/auth/security.md +69 -0
  65. package/dist/skill/docs/stack/cms/actions.md +28 -0
  66. package/dist/skill/docs/stack/cms/connecting.md +2 -2
  67. package/dist/skill/docs/stack/cms/index.md +2 -2
  68. package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
  69. package/dist/skill/docs/stack/cms/schema-format.md +33 -3
  70. package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
  71. package/dist/skill/docs/stack/cms/security.md +10 -12
  72. package/dist/skill/docs/stack/cms/table-views.md +1 -1
  73. package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
  74. package/dist/skill/docs/stack/realtime/index.md +20 -3
  75. package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
  76. package/dist/skill/docs/stack/vector/embeddings.md +7 -6
  77. package/package.json +1 -1
  78. package/src/skill/docs/changelog.md +183 -2
  79. package/src/skill/docs/compiler/config/index.md +13 -11
  80. package/src/skill/docs/compiler/config/providers.md +87 -0
  81. package/src/skill/docs/compiler/config/single-tenant.md +5 -11
  82. package/src/skill/docs/compiler/definitions/access.md +43 -57
  83. package/src/skill/docs/compiler/definitions/feature.md +7 -11
  84. package/src/skill/docs/compiler/definitions/firewall.md +2 -4
  85. package/src/skill/docs/compiler/definitions/guards.md +16 -18
  86. package/src/skill/docs/compiler/definitions/index.md +10 -14
  87. package/src/skill/docs/compiler/definitions/masking.md +6 -6
  88. package/src/skill/docs/compiler/definitions/read.md +6 -11
  89. package/src/skill/docs/compiler/definitions/schema.md +18 -18
  90. package/src/skill/docs/compiler/definitions/views.md +3 -5
  91. package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
  92. package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  93. package/src/skill/docs/compiler/getting-started/index.md +23 -20
  94. package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
  95. package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
  96. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
  97. package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
  98. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  100. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  101. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  102. package/src/skill/docs/compiler/troubleshooting.md +10 -0
  103. package/src/skill/docs/stack/auth/security.md +69 -0
  104. package/src/skill/docs/stack/cms/actions.md +28 -0
  105. package/src/skill/docs/stack/cms/connecting.md +2 -2
  106. package/src/skill/docs/stack/cms/index.md +2 -2
  107. package/src/skill/docs/stack/cms/record-layouts.md +19 -19
  108. package/src/skill/docs/stack/cms/schema-format.md +33 -3
  109. package/src/skill/docs/stack/cms/schema-registry.md +22 -2
  110. package/src/skill/docs/stack/cms/security.md +10 -12
  111. package/src/skill/docs/stack/cms/table-views.md +1 -1
  112. package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
  113. package/src/skill/docs/stack/realtime/index.md +20 -3
  114. package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
  115. package/src/skill/docs/stack/vector/embeddings.md +7 -6
@@ -2,6 +2,13 @@
2
2
 
3
3
  Quickback can generate realtime notification helpers for broadcasting changes to connected clients. This enables live updates via WebSocket using Cloudflare Durable Objects.
4
4
 
5
+ The targeting model is shared across ws tickets, websocket attachment, and server-side broadcasts:
6
+
7
+ - string target: historical `organizationId` shorthand
8
+ - object target: `{ scopeKey?, organizationId?, userId? }`
9
+
10
+ That means the same mental model drives both `createRealtime()` and the generated Broadcaster filter path.
11
+
5
12
  ## Enabling Realtime
6
13
 
7
14
  Add `realtime` configuration to individual table definitions:
@@ -35,6 +42,24 @@ export default defineTable(applications, {
35
42
 
36
43
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
37
44
 
45
+ At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need relationship-authorized resource tickets:
46
+
47
+ ```typescript
48
+ providers: {
49
+ database: defineDatabase("cloudflare-d1", {
50
+ realtime: {
51
+ wsTicket: {
52
+ role: "attendee",
53
+ requestField: "eventId",
54
+ scopeTable: "events",
55
+ },
56
+ },
57
+ }),
58
+ }
59
+ ```
60
+
61
+ That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, verify the `attendee` relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane.
62
+
38
63
  ## When auto-broadcast fires (and when you call it manually)
39
64
 
40
65
  Quickback emits auto-broadcasts in **only one place**: the generated CRUD route handlers (`POST /` create, `PATCH /:id` update, `DELETE /:id` delete) for resources with `realtime.enabled` (or covered by `dbConfig.realtime: true`'s project-level default). Those handlers wrap each successful write with a `realtime.insert / update / delete` call before responding.
@@ -74,6 +99,18 @@ export const execute: ActionExecutor = async ({ db, ctx, input }) => {
74
99
  };
75
100
  ```
76
101
 
102
+ For explicit targeting, pass an object instead of the historical org string:
103
+
104
+ ```typescript
105
+ await realtime.broadcast("event-page-updated", payload, {
106
+ scopeKey: `events:${input.eventId}`,
107
+ });
108
+
109
+ await realtime.broadcast("dm", payload, {
110
+ userId: recipientId,
111
+ });
112
+ ```
113
+
77
114
  ## Event Format
78
115
 
79
116
  Quickback broadcasts events in a structured JSON format for easy client-side handling.
@@ -207,7 +244,7 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
207
244
  });
208
245
  ```
209
246
 
210
- If `targetRoles` is not specified, all authenticated users in the organization receive the broadcast.
247
+ If `targetRoles` is not specified, all authenticated subscribers in the chosen scope receive the broadcast.
211
248
 
212
249
  ## Per-Role Field Masking
213
250
 
@@ -262,13 +299,17 @@ Quickback uses **ticket-based authentication** for WebSocket connections. The cl
262
299
  // 1. Get a ws-ticket from your API (requires session auth)
263
300
  const response = await fetch('/broadcast/v1/ws-ticket', {
264
301
  method: 'POST',
265
- headers: { Authorization: `Bearer ${sessionToken}` },
302
+ headers: {
303
+ Authorization: `Bearer ${sessionToken}`,
304
+ 'Content-Type': 'application/json',
305
+ },
306
+ body: JSON.stringify({ eventId: 'evt_123' }),
266
307
  });
267
308
  const { wsTicket } = await response.json();
268
309
 
269
310
  // 2. Connect with ticket as URL param
270
311
  const ws = new WebSocket(
271
- `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
312
+ `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}`
272
313
  );
273
314
 
274
315
  ws.onopen = () => {
@@ -348,8 +389,8 @@ new_classes = ["Broadcaster"]
348
389
  ```
349
390
 
350
391
  1. **Client gets a ticket** — `POST /broadcast/v1/ws-ticket` on the main API (session-authenticated). Returns a 60-second HMAC-signed ticket.
351
- 2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object verifies the ticket cryptographically at upgrade — no HTTP round-trip.
352
- 3. **API broadcasts** — After CRUD ops, the API calls the Broadcaster DO directly via its binding (in-process, no network hop).
392
+ 2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object verifies the ticket cryptographically at upgrade and attaches the socket to the ticket's `scopeKey`, `organizationId`, or `userId`.
393
+ 3. **API broadcasts** — After CRUD ops, or from custom handlers, the API calls the Broadcaster DO directly via its binding (in-process, no network hop) using the same target model.
353
394
 
354
395
  ## Best Practices
355
396
 
@@ -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 organization. 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 org that something changed." Documented on this page.
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`. Documented on this page.
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](/stack/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -31,17 +31,18 @@ Both share the same auth model and ride on the same compiled worker; they solve
31
31
  The Broadcaster Durable Object runs **inline** in your main Quickback worker — no separate worker deployment needed. The API calls the DO directly via its binding (in-process, no network hop).
32
32
 
33
33
  1. **Quickback Worker** — Your compiled API with the Broadcaster DO class exported from the same worker.
34
- 2. **Broadcaster (Durable Object)** — Manages WebSocket connections per organization. One instance per org.
34
+ 2. **Broadcaster (Durable Object)** — Manages WebSocket connections per subscription scope. One instance per `scopeKey`, organization, or user lane.
35
35
  3. **Browser Clients** — CMS, Account, Admin, and custom frontends connect via WebSocket on the same origin.
36
36
 
37
37
  ## Key Features
38
38
 
39
39
  | Feature | Description |
40
40
  |---------|-------------|
41
- | Organization-scoped | Each org gets its own Durable Object instance |
41
+ | Scope-aware fan-out | Routes by `scopeKey`, `organizationId`, or `userId` |
42
42
  | Role-based filtering | Only send events to users with matching roles |
43
43
  | Per-role masking | Different users see different field values based on their role |
44
44
  | User-specific targeting | Send events to a specific user within an org |
45
+ | Resource-scoped tickets | Reuse authz relationship roles to mint scope-bound ws tickets |
45
46
  | Custom broadcasts | Arbitrary events beyond CRUD |
46
47
  | Custom namespaces | `defineRealtime()` for type-safe event helpers |
47
48
  | Ticket-based auth | HMAC-signed tickets verified at WebSocket upgrade — no HTTP round-trip |
@@ -66,6 +67,22 @@ export default defineTable(applications, {
66
67
 
67
68
  And enable the realtime binding in your database config. The compiler generates the Durable Object class, helper functions, and wrangler bindings — all within your main worker.
68
69
 
70
+ ```typescript
71
+ providers: {
72
+ database: defineDatabase("cloudflare-d1", {
73
+ realtime: {
74
+ wsTicket: {
75
+ role: "attendee",
76
+ requestField: "eventId",
77
+ scopeTable: "events",
78
+ },
79
+ },
80
+ }),
81
+ }
82
+ ```
83
+
84
+ With that config, `/broadcast/v1/ws-ticket` can authenticate the caller, verify the declared authz relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` channel.
85
+
69
86
  ## Pages
70
87
 
71
88
  - **[Durable Objects Setup](/stack/realtime/durable-objects)** — Broadcaster configuration, wrangler bindings, event formats, masking, and custom namespaces
@@ -28,18 +28,19 @@ const response = await fetch("/broadcast/v1/ws-ticket", {
28
28
  Authorization: `Bearer ${sessionToken}`,
29
29
  "Content-Type": "application/json",
30
30
  },
31
+ body: JSON.stringify({ eventId: "evt_123" }), // optional; used by resource-scoped wsTicket config
31
32
  });
32
33
  const { wsTicket, expiresIn } = await response.json();
33
34
  // expiresIn = 60 (seconds)
34
35
  ```
35
36
 
36
- The ticket is a short-lived (60-second) HMAC-signed token containing your userId, organizationId, and roles.
37
+ The ticket is a short-lived (60-second) HMAC-signed token containing your userId, roles, and the resolved subscription scope.
37
38
 
38
39
  ### Step 2: Connect with Ticket
39
40
 
40
41
  ```typescript
41
42
  const ws = new WebSocket(
42
- `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
43
+ `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}`
43
44
  );
44
45
 
45
46
  ws.onopen = () => {
@@ -148,11 +149,11 @@ Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency.
148
149
 
149
150
  ### User-Specific Events
150
151
 
151
- Events can target a specific user within an organization. Only that user receives the broadcast — all other connections in the org are skipped.
152
+ Events can target a specific user lane. Only that user receives the broadcast — all other connections on the same scope are skipped.
152
153
 
153
- ### Organization Isolation
154
+ ### Scope Isolation
154
155
 
155
- Each organization has its own Durable Object instance. Users can only subscribe to events in organizations they belong to, enforced during authentication.
156
+ Each WebSocket connection is attached to exactly one resolved scope: `scopeKey`, `organizationId`, or `userId`. Users can only subscribe to the scope stamped into their ws ticket, enforced during authentication and ticket minting.
156
157
 
157
158
  ## Reconnection
158
159
 
@@ -164,11 +165,12 @@ async function connect() {
164
165
  const res = await fetch("/broadcast/v1/ws-ticket", {
165
166
  method: "POST",
166
167
  headers: { Authorization: `Bearer ${sessionToken}` },
168
+ body: JSON.stringify({ eventId: "evt_123" }),
167
169
  });
168
170
  const { wsTicket } = await res.json();
169
171
 
170
172
  const ws = new WebSocket(
171
- `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
173
+ `wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}`
172
174
  );
173
175
 
174
176
  ws.onclose = () => {
@@ -22,10 +22,8 @@ export default defineTable(jobs, {
22
22
  metadata: ['department'], // Metadata for Vectorize index
23
23
  },
24
24
 
25
- crud: {
26
- create: { access: { roles: ['recruiter'] } },
27
- update: { access: { roles: ['recruiter'] } },
28
- },
25
+ create: { access: { roles: ['recruiter'] } },
26
+ update: { access: { roles: ['recruiter'] } },
29
27
  });
30
28
  ```
31
29
 
@@ -94,7 +92,7 @@ onUpdate: ['description', 'title']
94
92
 
95
93
  ## Generic Embeddings API
96
94
 
97
- In addition to automatic embeddings on CRUD operations, Quickback generates a generic embeddings API endpoint that allows you to trigger embeddings on arbitrary content.
95
+ In addition to automatic embeddings on standard resource operations, Quickback generates a generic embeddings API endpoint that allows you to trigger embeddings on arbitrary content.
98
96
 
99
97
  ### POST /api/v1/embeddings
100
98
 
@@ -290,7 +288,10 @@ export default feature("jobs", {
290
288
  embedding: q.text().optional(),
291
289
  },
292
290
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
293
- crud: { list: {}, get: {}, create: {}, update: {}, delete: {} },
291
+ read: {},
292
+ create: {},
293
+ update: {},
294
+ delete: {},
294
295
  });
295
296
  ```
296
297