@quickback-dev/cli 0.10.16 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +15 -10
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1225 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +73 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1225 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +340 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +73 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,488 @@
|
|
|
1
|
+
# Realtime
|
|
2
|
+
|
|
3
|
+
Quickback can generate realtime notification helpers for broadcasting changes to connected clients. This enables live updates via WebSocket using Cloudflare Durable Objects.
|
|
4
|
+
|
|
5
|
+
## Enabling Realtime
|
|
6
|
+
|
|
7
|
+
Add `realtime` configuration to individual table definitions:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
// features/applications/applications.ts
|
|
11
|
+
import { sqliteTable, text } from "drizzle-orm/sqlite-core";
|
|
12
|
+
import { defineTable } from "@quickback/compiler";
|
|
13
|
+
|
|
14
|
+
export const applications = sqliteTable("applications", {
|
|
15
|
+
id: text("id").primaryKey(),
|
|
16
|
+
candidateId: text("candidate_id").notNull(),
|
|
17
|
+
jobId: text("job_id").notNull(),
|
|
18
|
+
stage: text("stage").notNull(),
|
|
19
|
+
organizationId: text("organization_id").notNull(),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
export default defineTable(applications, {
|
|
23
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
24
|
+
realtime: {
|
|
25
|
+
enabled: true, // Enable realtime for this table
|
|
26
|
+
onInsert: true, // Broadcast on INSERT (default: true)
|
|
27
|
+
onUpdate: true, // Broadcast on UPDATE (default: true)
|
|
28
|
+
onDelete: true, // Broadcast on DELETE (default: true)
|
|
29
|
+
requiredRoles: ["recruiter", "hiring-manager"], // Who receives broadcasts
|
|
30
|
+
fields: ["id", "candidateId", "stage"], // Fields to include (optional)
|
|
31
|
+
},
|
|
32
|
+
// ... guards, crud
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
|
|
37
|
+
|
|
38
|
+
## Generated Helper
|
|
39
|
+
|
|
40
|
+
The `createRealtime()` factory provides convenient methods for both Postgres Changes (CRUD events) and custom broadcasts:
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
import { createRealtime } from '../lib/realtime';
|
|
44
|
+
|
|
45
|
+
export const execute: ActionExecutor = async ({ db, ctx, input }) => {
|
|
46
|
+
const realtime = createRealtime(ctx.env);
|
|
47
|
+
|
|
48
|
+
// After creating a record
|
|
49
|
+
await realtime.insert('applications', newApplication, ctx.activeOrgId!);
|
|
50
|
+
|
|
51
|
+
// After updating a record
|
|
52
|
+
await realtime.update('applications', newApplication, oldApplication, ctx.activeOrgId!);
|
|
53
|
+
|
|
54
|
+
// After deleting a record
|
|
55
|
+
await realtime.delete('applications', { id: applicationId }, ctx.activeOrgId!);
|
|
56
|
+
|
|
57
|
+
return { success: true };
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Event Format
|
|
62
|
+
|
|
63
|
+
Quickback broadcasts events in a structured JSON format for easy client-side handling.
|
|
64
|
+
|
|
65
|
+
### Insert Event
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
await realtime.insert('applications', {
|
|
69
|
+
id: 'app_123',
|
|
70
|
+
candidateId: 'cnd_456',
|
|
71
|
+
stage: 'applied'
|
|
72
|
+
}, ctx.activeOrgId!);
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Broadcasts:
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"type": "postgres_changes",
|
|
79
|
+
"table": "applications",
|
|
80
|
+
"eventType": "INSERT",
|
|
81
|
+
"schema": "public",
|
|
82
|
+
"new": {
|
|
83
|
+
"id": "app_123",
|
|
84
|
+
"candidateId": "cnd_456",
|
|
85
|
+
"stage": "applied"
|
|
86
|
+
},
|
|
87
|
+
"old": null
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Update Event
|
|
92
|
+
|
|
93
|
+
```typescript
|
|
94
|
+
await realtime.update('applications',
|
|
95
|
+
{ id: 'app_123', stage: 'interview' }, // new
|
|
96
|
+
{ id: 'app_123', stage: 'screening' }, // old
|
|
97
|
+
ctx.activeOrgId!
|
|
98
|
+
);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Broadcasts:
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"type": "postgres_changes",
|
|
105
|
+
"table": "applications",
|
|
106
|
+
"eventType": "UPDATE",
|
|
107
|
+
"schema": "public",
|
|
108
|
+
"new": { "id": "app_123", "stage": "interview" },
|
|
109
|
+
"old": { "id": "app_123", "stage": "screening" }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Delete Event
|
|
114
|
+
|
|
115
|
+
```typescript
|
|
116
|
+
await realtime.delete('applications',
|
|
117
|
+
{ id: 'app_123' },
|
|
118
|
+
ctx.activeOrgId!
|
|
119
|
+
);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Broadcasts:
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"type": "postgres_changes",
|
|
126
|
+
"table": "applications",
|
|
127
|
+
"eventType": "DELETE",
|
|
128
|
+
"schema": "public",
|
|
129
|
+
"new": null,
|
|
130
|
+
"old": { "id": "app_123" }
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Custom Broadcasts
|
|
135
|
+
|
|
136
|
+
For arbitrary events that don't map to CRUD operations:
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
await realtime.broadcast('screening-complete', {
|
|
140
|
+
applicationId: 'app_123',
|
|
141
|
+
candidateId: 'cnd_456',
|
|
142
|
+
stage: 'interview'
|
|
143
|
+
}, ctx.activeOrgId!);
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Broadcasts:
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"type": "broadcast",
|
|
150
|
+
"event": "screening-complete",
|
|
151
|
+
"payload": {
|
|
152
|
+
"applicationId": "app_123",
|
|
153
|
+
"candidateId": "cnd_456",
|
|
154
|
+
"stage": "interview"
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## User-Specific Broadcasts
|
|
160
|
+
|
|
161
|
+
Target a specific user instead of the entire organization:
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
// Only this user receives the notification
|
|
165
|
+
await realtime.insert('notifications', newNotification, ctx.activeOrgId!, {
|
|
166
|
+
userId: ctx.userId
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
// Notify a hiring manager of a new application
|
|
170
|
+
await realtime.broadcast('application-received', {
|
|
171
|
+
applicationId: 'app_123',
|
|
172
|
+
jobId: 'job_789'
|
|
173
|
+
}, ctx.activeOrgId!, {
|
|
174
|
+
userId: hiringManagerId
|
|
175
|
+
});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Role-Based Filtering
|
|
179
|
+
|
|
180
|
+
Limit which roles receive a broadcast using `targetRoles`:
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
// Only hiring managers and recruiters receive this broadcast
|
|
184
|
+
await realtime.insert('applications', application, ctx.activeOrgId!, {
|
|
185
|
+
targetRoles: ['hiring-manager', 'recruiter']
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
// Interviewers only see applications assigned to them
|
|
189
|
+
await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
|
|
190
|
+
targetRoles: ['hiring-manager']
|
|
191
|
+
});
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
If `targetRoles` is not specified, all authenticated users in the organization receive the broadcast.
|
|
195
|
+
|
|
196
|
+
## Per-Role Field Masking
|
|
197
|
+
|
|
198
|
+
Apply different field masking based on the subscriber's role using `maskingConfig`:
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
await realtime.insert('candidates', newCandidate, ctx.activeOrgId!, {
|
|
202
|
+
maskingConfig: {
|
|
203
|
+
phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
204
|
+
email: { type: 'email', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
205
|
+
resumeUrl: { type: 'redact', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
206
|
+
},
|
|
207
|
+
});
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**How masking works:**
|
|
211
|
+
- Each subscriber receives a payload masked according to their role
|
|
212
|
+
- Roles in the `show.roles` array see unmasked values
|
|
213
|
+
- All other roles see the masked version
|
|
214
|
+
- Masking is pre-computed per-role (O(roles) not O(subscribers))
|
|
215
|
+
|
|
216
|
+
**Available mask types:**
|
|
217
|
+
| Type | Example Output |
|
|
218
|
+
|------|----------------|
|
|
219
|
+
| `email` | `j***@y*********.com` |
|
|
220
|
+
| `phone` | `******4567` |
|
|
221
|
+
| `ssn` | `*****6789` |
|
|
222
|
+
| `creditCard` | `**** **** **** 1111` |
|
|
223
|
+
| `name` | `J***` |
|
|
224
|
+
| `redact` | `[REDACTED]` |
|
|
225
|
+
|
|
226
|
+
### Owner-Based Masking
|
|
227
|
+
|
|
228
|
+
Show unmasked data to the record owner:
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
maskingConfig: {
|
|
232
|
+
phone: {
|
|
233
|
+
type: 'phone',
|
|
234
|
+
show: { roles: ['hiring-manager'], or: 'owner' } // Hiring manager OR owner sees unmasked
|
|
235
|
+
},
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## Client-Side Subscription
|
|
240
|
+
|
|
241
|
+
### WebSocket Authentication
|
|
242
|
+
|
|
243
|
+
Quickback uses **ticket-based authentication** for WebSocket connections. The client first obtains a short-lived ticket from the main API, then connects with it as a URL parameter. The Broadcaster verifies the ticket cryptographically at upgrade time — no HTTP round-trip needed.
|
|
244
|
+
|
|
245
|
+
```typescript
|
|
246
|
+
// 1. Get a ws-ticket from your API (requires session auth)
|
|
247
|
+
const response = await fetch('/broadcast/v1/ws-ticket', {
|
|
248
|
+
method: 'POST',
|
|
249
|
+
headers: { Authorization: `Bearer ${sessionToken}` },
|
|
250
|
+
});
|
|
251
|
+
const { wsTicket } = await response.json();
|
|
252
|
+
|
|
253
|
+
// 2. Connect with ticket as URL param
|
|
254
|
+
const ws = new WebSocket(
|
|
255
|
+
`wss://api.yourdomain.com/broadcast/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
|
|
256
|
+
);
|
|
257
|
+
|
|
258
|
+
ws.onopen = () => {
|
|
259
|
+
console.log('Connected and authenticated!');
|
|
260
|
+
// No auth message needed — pre-authenticated at upgrade
|
|
261
|
+
};
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Tickets expire after 60 seconds, so fetch a fresh one before each connection or reconnection.
|
|
265
|
+
|
|
266
|
+
### Handling Messages
|
|
267
|
+
|
|
268
|
+
```typescript
|
|
269
|
+
ws.onmessage = (event) => {
|
|
270
|
+
const msg = JSON.parse(event.data);
|
|
271
|
+
|
|
272
|
+
// Handle CRUD events
|
|
273
|
+
if (msg.type === 'postgres_changes') {
|
|
274
|
+
const { table, eventType, new: newRecord, old: oldRecord } = msg;
|
|
275
|
+
|
|
276
|
+
if (eventType === 'INSERT') {
|
|
277
|
+
addRecord(table, newRecord);
|
|
278
|
+
} else if (eventType === 'UPDATE') {
|
|
279
|
+
updateRecord(table, newRecord);
|
|
280
|
+
} else if (eventType === 'DELETE') {
|
|
281
|
+
removeRecord(table, oldRecord.id);
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
// Handle custom broadcasts
|
|
286
|
+
if (msg.type === 'broadcast') {
|
|
287
|
+
const { event, payload } = msg;
|
|
288
|
+
|
|
289
|
+
if (event === 'screening-complete') {
|
|
290
|
+
refreshApplication(payload.applicationId);
|
|
291
|
+
} else if (event === 'interview-scheduled') {
|
|
292
|
+
showInterviewNotification(payload.applicationId);
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
};
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Environment
|
|
299
|
+
|
|
300
|
+
No additional environment variables are needed for realtime. The Broadcaster DO runs inline in your main worker and uses `BETTER_AUTH_SECRET` (already required for auth) to sign and verify WebSocket tickets.
|
|
301
|
+
|
|
302
|
+
| Variable | Description |
|
|
303
|
+
|----------|-------------|
|
|
304
|
+
| `BETTER_AUTH_SECRET` | Signs/verifies WebSocket tickets (already set for auth) |
|
|
305
|
+
|
|
306
|
+
The `BROADCASTER` binding is a `DurableObjectNamespace` — the compiler generates this in your `wrangler.toml` automatically:
|
|
307
|
+
|
|
308
|
+
```toml
|
|
309
|
+
[[durable_objects.bindings]]
|
|
310
|
+
name = "BROADCASTER"
|
|
311
|
+
class_name = "Broadcaster"
|
|
312
|
+
|
|
313
|
+
[[migrations]]
|
|
314
|
+
tag = "v1"
|
|
315
|
+
new_classes = ["Broadcaster"]
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
## Architecture
|
|
319
|
+
|
|
320
|
+
```
|
|
321
|
+
1. POST /ws-ticket
|
|
322
|
+
┌───────────────────────────────────────────────┐ ┌─────────────────┐
|
|
323
|
+
│ Quickback Worker │ ◄──│ Browser Client │
|
|
324
|
+
│ │ ──►│ │
|
|
325
|
+
│ ┌──────────┐ DO binding ┌────────────────┐ │ └───────┬─────────┘
|
|
326
|
+
│ │ Hono API │ ───────────► │ Broadcaster DO │ │ │
|
|
327
|
+
│ └──────────┘ (in-process)└───────┬────────┘ │ 2. WS ?ws_ticket=...
|
|
328
|
+
│ │ │ │
|
|
329
|
+
└────────────────────────────────────┼──────────┘ │
|
|
330
|
+
│◄──────────────────────┘
|
|
331
|
+
WebSocket (verified at upgrade)
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
1. **Client gets a ticket** — `POST /broadcast/v1/ws-ticket` on the main API (session-authenticated). Returns a 60-second HMAC-signed ticket.
|
|
335
|
+
2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object verifies the ticket cryptographically at upgrade — no HTTP round-trip.
|
|
336
|
+
3. **API broadcasts** — After CRUD ops, the API calls the Broadcaster DO directly via its binding (in-process, no network hop).
|
|
337
|
+
|
|
338
|
+
## Best Practices
|
|
339
|
+
|
|
340
|
+
### Broadcast After Commit
|
|
341
|
+
|
|
342
|
+
Always broadcast after the database operation succeeds:
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
// Good - broadcast after successful insert
|
|
346
|
+
const [newApp] = await db.insert(applications).values(data).returning();
|
|
347
|
+
await realtime.insert('applications', newApp, ctx.activeOrgId!);
|
|
348
|
+
|
|
349
|
+
// Bad - don't broadcast before confirming success
|
|
350
|
+
await realtime.insert('applications', data, ctx.activeOrgId!);
|
|
351
|
+
await db.insert(applications).values(data); // Could fail!
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### Minimal Payloads
|
|
355
|
+
|
|
356
|
+
Only include necessary data in broadcasts:
|
|
357
|
+
|
|
358
|
+
```typescript
|
|
359
|
+
// Good - minimal payload
|
|
360
|
+
await realtime.update('applications',
|
|
361
|
+
{ id: record.id, stage: 'interview' },
|
|
362
|
+
{ id: record.id, stage: 'screening' },
|
|
363
|
+
ctx.activeOrgId!
|
|
364
|
+
);
|
|
365
|
+
|
|
366
|
+
// Avoid - sending entire record with large content
|
|
367
|
+
await realtime.update('applications', fullRecord, oldRecord, ctx.activeOrgId!);
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### Use Broadcasts for Complex Events
|
|
371
|
+
|
|
372
|
+
For events that don't map cleanly to CRUD:
|
|
373
|
+
|
|
374
|
+
```typescript
|
|
375
|
+
// Hiring pipeline stage completed
|
|
376
|
+
await realtime.broadcast('pipeline-stage-complete', {
|
|
377
|
+
applicationId: application.id,
|
|
378
|
+
stages: ['applied', 'screening', 'interview'],
|
|
379
|
+
currentStage: 'offer',
|
|
380
|
+
candidateId: application.candidateId
|
|
381
|
+
}, ctx.activeOrgId!);
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
## Custom Event Namespaces
|
|
385
|
+
|
|
386
|
+
For complex applications with many custom events, you can define typed event namespaces using `defineRealtime`. This generates strongly-typed helper methods for your custom events.
|
|
387
|
+
|
|
388
|
+
### Defining Event Namespaces
|
|
389
|
+
|
|
390
|
+
Create a file in `services/realtime/`:
|
|
391
|
+
|
|
392
|
+
```typescript
|
|
393
|
+
// services/realtime/screening.ts
|
|
394
|
+
import { defineRealtime } from '@quickback/compiler';
|
|
395
|
+
|
|
396
|
+
export default defineRealtime({
|
|
397
|
+
name: 'screening',
|
|
398
|
+
events: ['started', 'progress', 'completed', 'failed'],
|
|
399
|
+
description: 'Candidate screening pipeline events',
|
|
400
|
+
});
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### Generated Helper Methods
|
|
404
|
+
|
|
405
|
+
After compilation, the `createRealtime()` helper includes your custom namespace:
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
import { createRealtime } from '../lib/realtime';
|
|
409
|
+
|
|
410
|
+
export const execute: ActionExecutor = async ({ ctx, input }) => {
|
|
411
|
+
const realtime = createRealtime(ctx.env);
|
|
412
|
+
|
|
413
|
+
// Type-safe custom event methods
|
|
414
|
+
await realtime.screening.started({
|
|
415
|
+
applicationId: input.applicationId,
|
|
416
|
+
}, ctx.activeOrgId!);
|
|
417
|
+
|
|
418
|
+
// Progress updates
|
|
419
|
+
await realtime.screening.progress({
|
|
420
|
+
applicationId: input.applicationId,
|
|
421
|
+
percent: 50,
|
|
422
|
+
step: 'background-check',
|
|
423
|
+
}, ctx.activeOrgId!);
|
|
424
|
+
|
|
425
|
+
// Completion
|
|
426
|
+
await realtime.screening.completed({
|
|
427
|
+
applicationId: input.applicationId,
|
|
428
|
+
result: 'passed',
|
|
429
|
+
duration: 1234,
|
|
430
|
+
}, ctx.activeOrgId!);
|
|
431
|
+
|
|
432
|
+
return { success: true };
|
|
433
|
+
};
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
### Event Format
|
|
437
|
+
|
|
438
|
+
Custom namespace events use the `broadcast` type with namespaced event names:
|
|
439
|
+
|
|
440
|
+
```json
|
|
441
|
+
{
|
|
442
|
+
"type": "broadcast",
|
|
443
|
+
"event": "screening:started",
|
|
444
|
+
"payload": {
|
|
445
|
+
"applicationId": "app_123"
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
### Multiple Namespaces
|
|
451
|
+
|
|
452
|
+
Define multiple namespaces for different parts of your application:
|
|
453
|
+
|
|
454
|
+
```typescript
|
|
455
|
+
// services/realtime/notifications.ts
|
|
456
|
+
export default defineRealtime({
|
|
457
|
+
name: 'notifications',
|
|
458
|
+
events: ['interview-reminder', 'offer-update', 'application-received'],
|
|
459
|
+
description: 'Recruitment notification events',
|
|
460
|
+
});
|
|
461
|
+
|
|
462
|
+
// services/realtime/presence.ts
|
|
463
|
+
export default defineRealtime({
|
|
464
|
+
name: 'presence',
|
|
465
|
+
events: ['joined', 'left', 'reviewing', 'idle'],
|
|
466
|
+
description: 'Who is reviewing which candidate',
|
|
467
|
+
});
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
Usage:
|
|
471
|
+
```typescript
|
|
472
|
+
const realtime = createRealtime(ctx.env);
|
|
473
|
+
|
|
474
|
+
// Notification events
|
|
475
|
+
await realtime.notifications['interview-reminder']({ ... }, ctx.activeOrgId!);
|
|
476
|
+
|
|
477
|
+
// Presence events — who's reviewing which candidate
|
|
478
|
+
await realtime.presence.reviewing({ userId: ctx.userId, candidateId: 'cnd_456' }, ctx.activeOrgId!);
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
### Namespace vs Generic Broadcast
|
|
482
|
+
|
|
483
|
+
| Use Case | Approach |
|
|
484
|
+
|----------|----------|
|
|
485
|
+
| One-off custom event | `realtime.broadcast('event-name', payload, orgId)` |
|
|
486
|
+
| Repeated event patterns | `defineRealtime` namespace |
|
|
487
|
+
| Type-safe events | `defineRealtime` namespace |
|
|
488
|
+
| Event discovery | `defineRealtime` (appears in generated types) |
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Realtime
|
|
2
|
+
|
|
3
|
+
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
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.
|
|
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
|
+
|
|
8
|
+
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
9
|
+
|
|
10
|
+
## Architecture
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
┌──────────────────────────────────────────┐
|
|
14
|
+
│ Quickback Worker │
|
|
15
|
+
│ │
|
|
16
|
+
│ ┌──────────┐ DO binding ┌────────────────────┐
|
|
17
|
+
│ │ Hono API │ ──────────────► │ Broadcaster (DO) │
|
|
18
|
+
│ │ │ │ WebSocket manager │
|
|
19
|
+
│ └──────────┘ └─────────┬──────────┘
|
|
20
|
+
│ │
|
|
21
|
+
└─────────────────────────────────────────┼┘
|
|
22
|
+
│ WebSocket
|
|
23
|
+
│
|
|
24
|
+
┌────────▼─────────┐
|
|
25
|
+
│ Browser Clients │
|
|
26
|
+
│ (CMS, Account, │
|
|
27
|
+
│ Admin, Custom) │
|
|
28
|
+
└──────────────────┘
|
|
29
|
+
```
|
|
30
|
+
|
|
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
|
+
|
|
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.
|
|
35
|
+
3. **Browser Clients** — CMS, Account, Admin, and custom frontends connect via WebSocket on the same origin.
|
|
36
|
+
|
|
37
|
+
## Key Features
|
|
38
|
+
|
|
39
|
+
| Feature | Description |
|
|
40
|
+
|---------|-------------|
|
|
41
|
+
| Organization-scoped | Each org gets its own Durable Object instance |
|
|
42
|
+
| Role-based filtering | Only send events to users with matching roles |
|
|
43
|
+
| Per-role masking | Different users see different field values based on their role |
|
|
44
|
+
| User-specific targeting | Send events to a specific user within an org |
|
|
45
|
+
| Custom broadcasts | Arbitrary events beyond CRUD |
|
|
46
|
+
| Custom namespaces | `defineRealtime()` for type-safe event helpers |
|
|
47
|
+
| Ticket-based auth | HMAC-signed tickets verified at WebSocket upgrade — no HTTP round-trip |
|
|
48
|
+
|
|
49
|
+
## Enabling Realtime
|
|
50
|
+
|
|
51
|
+
Add `realtime` to individual table definitions:
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
export default defineTable(applications, {
|
|
55
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
56
|
+
realtime: {
|
|
57
|
+
enabled: true,
|
|
58
|
+
onInsert: true,
|
|
59
|
+
onUpdate: true,
|
|
60
|
+
onDelete: true,
|
|
61
|
+
requiredRoles: ["recruiter", "hiring-manager"],
|
|
62
|
+
fields: ["id", "candidateId", "stage"],
|
|
63
|
+
},
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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
|
+
## Pages
|
|
70
|
+
|
|
71
|
+
- **[Durable Objects Setup](/stack/realtime/durable-objects)** — Broadcaster configuration, wrangler bindings, event formats, masking, and custom namespaces
|
|
72
|
+
- **[Using Realtime](/stack/realtime/using-realtime)** — Subscribing to `/broadcast/v1/*`: WebSocket connection, ticket auth, client-side handling
|
|
73
|
+
- **[PartyServer Rooms](/stack/realtime/partyserver-rooms)** — Per-room collab via `/realtime/<binding>/<room-id>`: presence, live notes, room IDs
|