@quickback-dev/cli 0.10.16 → 0.10.20

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 (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. 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('/realtime/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/realtime/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 /realtime/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,67 @@
1
+ # Realtime
2
+
3
+ The Quickback Stack uses Cloudflare Durable Objects to broadcast real-time updates over WebSockets. CRUD events and custom broadcasts are delivered to connected clients with the same security layers (firewall isolation, role-based filtering, field masking) applied.
4
+
5
+ ## Architecture
6
+
7
+ ```
8
+ ┌──────────────────────────────────────────┐
9
+ │ Quickback Worker │
10
+ │ │
11
+ │ ┌──────────┐ DO binding ┌────────────────────┐
12
+ │ │ Hono API │ ──────────────► │ Broadcaster (DO) │
13
+ │ │ │ │ WebSocket manager │
14
+ │ └──────────┘ └─────────┬──────────┘
15
+ │ │
16
+ └─────────────────────────────────────────┼┘
17
+ │ WebSocket
18
+ │
19
+ ┌────────▼─────────┐
20
+ │ Browser Clients │
21
+ │ (CMS, Account, │
22
+ │ Admin, Custom) │
23
+ └──────────────────┘
24
+ ```
25
+
26
+ 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).
27
+
28
+ 1. **Quickback Worker** — Your compiled API with the Broadcaster DO class exported from the same worker.
29
+ 2. **Broadcaster (Durable Object)** — Manages WebSocket connections per organization. One instance per org.
30
+ 3. **Browser Clients** — CMS, Account, Admin, and custom frontends connect via WebSocket on the same origin.
31
+
32
+ ## Key Features
33
+
34
+ | Feature | Description |
35
+ |---------|-------------|
36
+ | Organization-scoped | Each org gets its own Durable Object instance |
37
+ | Role-based filtering | Only send events to users with matching roles |
38
+ | Per-role masking | Different users see different field values based on their role |
39
+ | User-specific targeting | Send events to a specific user within an org |
40
+ | Custom broadcasts | Arbitrary events beyond CRUD |
41
+ | Custom namespaces | `defineRealtime()` for type-safe event helpers |
42
+ | Ticket-based auth | HMAC-signed tickets verified at WebSocket upgrade — no HTTP round-trip |
43
+
44
+ ## Enabling Realtime
45
+
46
+ Add `realtime` to individual table definitions:
47
+
48
+ ```typescript
49
+ export default defineTable(applications, {
50
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
51
+ realtime: {
52
+ enabled: true,
53
+ onInsert: true,
54
+ onUpdate: true,
55
+ onDelete: true,
56
+ requiredRoles: ["recruiter", "hiring-manager"],
57
+ fields: ["id", "candidateId", "stage"],
58
+ },
59
+ });
60
+ ```
61
+
62
+ 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.
63
+
64
+ ## Pages
65
+
66
+ - **[Durable Objects Setup](/stack/realtime/durable-objects)** — Configuration, wrangler bindings, event formats, masking, and custom namespaces
67
+ - **[Using Realtime](/stack/realtime/using-realtime)** — WebSocket connection, authentication, and client-side handling