@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,211 @@
1
+ # Using Realtime
2
+
3
+ This page covers connecting to the Quickback realtime system from client applications — authentication, subscribing to events, and handling messages.
4
+
5
+ ## Connecting
6
+
7
+ Open a WebSocket connection to the realtime worker:
8
+
9
+ ```typescript
10
+ const ws = new WebSocket("wss://api.yourdomain.com/realtime/v1/websocket");
11
+ ```
12
+
13
+ ## Authentication
14
+
15
+ Quickback uses **ticket-based authentication** for WebSocket connections. This is a two-step process:
16
+
17
+ 1. **Get a ticket** — Call the ws-ticket endpoint with your session auth
18
+ 2. **Connect with ticket** — Pass the ticket as a URL parameter when opening the WebSocket
19
+
20
+ This approach is faster and more secure than in-band auth messages — the connection is authenticated at upgrade time with no HTTP round-trip from the Durable Object.
21
+
22
+ ### Step 1: Get a WebSocket Ticket
23
+
24
+ ```typescript
25
+ const response = await fetch("/realtime/v1/ws-ticket", {
26
+ method: "POST",
27
+ headers: {
28
+ Authorization: `Bearer ${sessionToken}`,
29
+ "Content-Type": "application/json",
30
+ },
31
+ });
32
+ const { wsTicket, expiresIn } = await response.json();
33
+ // expiresIn = 60 (seconds)
34
+ ```
35
+
36
+ The ticket is a short-lived (60-second) HMAC-signed token containing your userId, organizationId, and roles.
37
+
38
+ ### Step 2: Connect with Ticket
39
+
40
+ ```typescript
41
+ const ws = new WebSocket(
42
+ `wss://api.yourdomain.com/realtime/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
43
+ );
44
+
45
+ ws.onopen = () => {
46
+ console.log("Connected and authenticated!");
47
+ // No auth message needed — connection is pre-authenticated
48
+ };
49
+ ```
50
+
51
+ If the ticket is invalid or expired, the WebSocket upgrade is rejected with a 401 status.
52
+
53
+ ## Handling Messages
54
+
55
+ ### CRUD Events
56
+
57
+ CRUD events use the `postgres_changes` type:
58
+
59
+ ```typescript
60
+ ws.onmessage = (event) => {
61
+ const msg = JSON.parse(event.data);
62
+
63
+ if (msg.type === "postgres_changes") {
64
+ const { table, eventType, new: newRecord, old: oldRecord } = msg;
65
+
66
+ switch (eventType) {
67
+ case "INSERT":
68
+ addRecord(table, newRecord);
69
+ break;
70
+ case "UPDATE":
71
+ updateRecord(table, newRecord);
72
+ break;
73
+ case "DELETE":
74
+ removeRecord(table, oldRecord.id);
75
+ break;
76
+ }
77
+ }
78
+ };
79
+ ```
80
+
81
+ **Event payload:**
82
+
83
+ ```json
84
+ {
85
+ "type": "postgres_changes",
86
+ "table": "applications",
87
+ "schema": "public",
88
+ "eventType": "INSERT",
89
+ "new": { "id": "app_123", "candidateId": "cnd_456", "stage": "interview" },
90
+ "old": null
91
+ }
92
+ ```
93
+
94
+ For UPDATE events, both `new` and `old` are populated. For DELETE events, only `old` is populated.
95
+
96
+ ### Custom Broadcasts
97
+
98
+ Custom events use the `broadcast` type:
99
+
100
+ ```typescript
101
+ if (msg.type === "broadcast") {
102
+ const { event, payload } = msg;
103
+
104
+ if (event === "screening-complete") {
105
+ refreshApplication(payload.applicationId);
106
+ } else if (event === "screening:progress") {
107
+ updateProgressBar(payload.percent);
108
+ }
109
+ }
110
+ ```
111
+
112
+ **Event payload:**
113
+
114
+ ```json
115
+ {
116
+ "type": "broadcast",
117
+ "event": "screening-complete",
118
+ "payload": {
119
+ "applicationId": "app_123",
120
+ "candidateId": "cnd_456",
121
+ "stage": "interview"
122
+ }
123
+ }
124
+ ```
125
+
126
+ Custom namespaces (from `defineRealtime()`) use the format `namespace:event` — e.g., `screening:started`, `screening:progress`.
127
+
128
+ ## Security
129
+
130
+ ### Role-Based Filtering
131
+
132
+ Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events.
133
+
134
+ ### Per-Role Masking
135
+
136
+ Field values are masked according to the subscriber's role. For example, with this masking config:
137
+
138
+ ```typescript
139
+ masking: {
140
+ ssn: { type: "ssn", show: { roles: ["owner"] } },
141
+ }
142
+ ```
143
+
144
+ - **Owner sees:** `{ ssn: "123-45-6789" }`
145
+ - **Recruiter sees:** `{ ssn: "*****6789" }`
146
+
147
+ Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency.
148
+
149
+ ### User-Specific Events
150
+
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
+
153
+ ### Organization Isolation
154
+
155
+ Each organization has its own Durable Object instance. Users can only subscribe to events in organizations they belong to, enforced during authentication.
156
+
157
+ ## Reconnection
158
+
159
+ WebSocket connections can drop due to network issues. Implement reconnection logic in your client — note that you need to fetch a fresh ticket on each reconnect since tickets expire after 60 seconds:
160
+
161
+ ```typescript
162
+ async function connect() {
163
+ // Get a fresh ticket each time
164
+ const res = await fetch("/realtime/v1/ws-ticket", {
165
+ method: "POST",
166
+ headers: { Authorization: `Bearer ${sessionToken}` },
167
+ });
168
+ const { wsTicket } = await res.json();
169
+
170
+ const ws = new WebSocket(
171
+ `wss://api.yourdomain.com/realtime/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
172
+ );
173
+
174
+ ws.onclose = () => {
175
+ // Reconnect after delay
176
+ setTimeout(connect, 2000);
177
+ };
178
+
179
+ ws.onmessage = (event) => {
180
+ const msg = JSON.parse(event.data);
181
+ handleMessage(msg);
182
+ };
183
+
184
+ return ws;
185
+ }
186
+ ```
187
+
188
+ ## Environment
189
+
190
+ No additional environment variables are needed for realtime. The Broadcaster Durable Object runs inline in your main worker and reuses `BETTER_AUTH_SECRET` for WebSocket ticket signing.
191
+
192
+ The compiler generates the required `wrangler.toml` bindings automatically:
193
+
194
+ ```toml
195
+ [[durable_objects.bindings]]
196
+ name = "BROADCASTER"
197
+ class_name = "Broadcaster"
198
+
199
+ [[migrations]]
200
+ tag = "v1"
201
+ new_classes = ["Broadcaster"]
202
+ ```
203
+
204
+ ## Cloudflare Only
205
+
206
+ Realtime requires Cloudflare Durable Objects and is only available with the Cloudflare runtime.
207
+
208
+ ## See Also
209
+
210
+ - [Durable Objects Setup](/stack/realtime/durable-objects) — Configuration, event formats, masking, and custom namespaces
211
+ - [Masking](/compiler/definitions/masking) — Field masking configuration
@@ -0,0 +1,17 @@
1
+ # Storage
2
+
3
+ The Quickback Stack uses Cloudflare's storage primitives for different use cases.
4
+
5
+ ## Storage Types
6
+
7
+ | Service | Use Case | Pages |
8
+ |---------|----------|-------|
9
+ | **KV** | Sessions, caching, rate limiting | [Setup](/stack/storage/kv) · [Usage](/stack/storage/using-kv) |
10
+ | **R2** | File uploads, avatars, attachments | [Setup](/stack/storage/r2) · [Usage](/stack/storage/using-r2) |
11
+
12
+ ## Getting Started
13
+
14
+ - **[KV Setup](/stack/storage/kv)** — Namespace and bindings configuration
15
+ - **[Using KV](/stack/storage/using-kv)** — Sessions, caching, rate limiting
16
+ - **[R2 Setup](/stack/storage/r2)** — Bucket, bindings, CORS configuration
17
+ - **[Using R2](/stack/storage/using-r2)** — Uploads, downloads, role-based access
@@ -0,0 +1,204 @@
1
+ # KV Storage
2
+
3
+ Cloudflare Workers KV is a global key-value store optimized for read-heavy workloads. Quickback uses KV for session storage, caching, and fast lookups.
4
+
5
+ ## What is KV?
6
+
7
+ Workers KV is a distributed key-value store:
8
+
9
+ - **Global distribution** - Data replicated to 300+ edge locations
10
+ - **Low-latency reads** - Cached at the edge, sub-millisecond access
11
+ - **Eventually consistent** - Writes propagate globally within 60 seconds
12
+ - **Simple API** - Get, put, delete, list
13
+
14
+ ## Use Cases in Quickback
15
+
16
+ | Use Case | Description |
17
+ |----------|-------------|
18
+ | **Sessions** | Better Auth stores sessions in KV for fast validation |
19
+ | **Cache** | Cache expensive database queries or API responses |
20
+ | **Rate Limiting** | Track request counts per user/IP |
21
+ | **Feature Flags** | Store configuration that changes infrequently |
22
+
23
+ ## Namespace Setup
24
+
25
+ Create a KV namespace via Wrangler:
26
+
27
+ ```bash
28
+ # Create namespace
29
+ wrangler kv namespace create "KV"
30
+
31
+ # Output:
32
+ # Add the following to your wrangler.toml:
33
+ # [[kv_namespaces]]
34
+ # binding = "KV"
35
+ # id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
36
+ ```
37
+
38
+ ### Setting the namespace ID in config
39
+
40
+ To have the compiler generate `wrangler.toml` with your KV namespace ID, set it in your provider config:
41
+
42
+ ```typescript
43
+ providers: {
44
+ storage: defineStorage("kv", {
45
+ namespaceId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
46
+ }),
47
+ }
48
+ ```
49
+
50
+ The `namespaceId` can also be set as `kvId` on the auth provider config, since KV is primarily used for auth session storage. The compiler checks both locations.
51
+
52
+ ## Reading and Writing Values
53
+
54
+ ### Basic Operations
55
+
56
+ ```ts
57
+ // Write a value
58
+ await env.CACHE.put("user:123", JSON.stringify({ name: "Alice" }));
59
+
60
+ // Read a value
61
+ const data = await env.CACHE.get("user:123");
62
+ const user = data ? JSON.parse(data) : null;
63
+
64
+ // Delete a value
65
+ await env.CACHE.delete("user:123");
66
+
67
+ // Check if key exists
68
+ const exists = await env.CACHE.get("user:123") !== null;
69
+ ```
70
+
71
+ ### With Metadata
72
+
73
+ KV supports metadata attached to keys:
74
+
75
+ ```ts
76
+ // Write with metadata
77
+ await env.CACHE.put("user:123", JSON.stringify(userData), {
78
+ metadata: { updatedAt: Date.now(), version: 1 },
79
+ });
80
+
81
+ // Read with metadata
82
+ const { value, metadata } = await env.CACHE.getWithMetadata("user:123");
83
+ ```
84
+
85
+ ### List Keys
86
+
87
+ ```ts
88
+ // List all keys with prefix
89
+ const list = await env.CACHE.list({ prefix: "user:" });
90
+
91
+ for (const key of list.keys) {
92
+ console.log(key.name, key.metadata);
93
+ }
94
+
95
+ // Paginate through results
96
+ let cursor = undefined;
97
+ do {
98
+ const result = await env.CACHE.list({ prefix: "user:", cursor });
99
+ // Process result.keys
100
+ cursor = result.cursor;
101
+ } while (cursor);
102
+ ```
103
+
104
+ ## Expiration and TTL
105
+
106
+ Set automatic expiration on keys:
107
+
108
+ ```ts
109
+ // Expire in 1 hour (3600 seconds)
110
+ await env.CACHE.put("session:abc", sessionData, {
111
+ expirationTtl: 3600,
112
+ });
113
+
114
+ // Expire at specific timestamp
115
+ await env.CACHE.put("session:abc", sessionData, {
116
+ expiration: Math.floor(Date.now() / 1000) + 3600,
117
+ });
118
+ ```
119
+
120
+ Common TTL patterns:
121
+
122
+ | Use Case | TTL |
123
+ |----------|-----|
124
+ | Session tokens | 24 hours (86400) |
125
+ | API cache | 5 minutes (300) |
126
+ | Rate limit counters | 1 minute (60) |
127
+ | Feature flags | No expiration |
128
+
129
+ ## Session Storage
130
+
131
+ Better Auth uses KV for session storage in Cloudflare deployments:
132
+
133
+ ```ts
134
+ // Quickback configures this automatically
135
+ auth: defineAuth("better-auth", {
136
+ session: {
137
+ storage: "kv", // Uses SESSIONS namespace
138
+ },
139
+ }),
140
+ ```
141
+
142
+ Sessions are stored as:
143
+ - Key: `session:{sessionId}`
144
+ - Value: Serialized session object
145
+ - TTL: Configured session expiration
146
+
147
+ ## Caching Patterns
148
+
149
+ ### Cache-Aside Pattern
150
+
151
+ ```ts
152
+ async function getUser(userId: string) {
153
+ // Check cache first
154
+ const cached = await env.CACHE.get(`user:${userId}`);
155
+ if (cached) {
156
+ return JSON.parse(cached);
157
+ }
158
+
159
+ // Fetch from database
160
+ const user = await db.select().from(users).where(eq(users.id, userId));
161
+
162
+ // Store in cache
163
+ await env.CACHE.put(`user:${userId}`, JSON.stringify(user), {
164
+ expirationTtl: 300, // 5 minutes
165
+ });
166
+
167
+ return user;
168
+ }
169
+ ```
170
+
171
+ ### Cache Invalidation
172
+
173
+ ```ts
174
+ // Invalidate on update
175
+ async function updateUser(userId: string, data: UserUpdate) {
176
+ await db.update(users).set(data).where(eq(users.id, userId));
177
+ await env.CACHE.delete(`user:${userId}`);
178
+ }
179
+ ```
180
+
181
+ ## wrangler.toml Reference
182
+
183
+ ```toml
184
+ # Production namespace
185
+ [[kv_namespaces]]
186
+ binding = "SESSIONS"
187
+ id = "abc123..."
188
+
189
+ # Preview namespace (for wrangler dev)
190
+ [[kv_namespaces]]
191
+ binding = "SESSIONS"
192
+ id = "def456..."
193
+ preview_id = "ghi789..."
194
+ ```
195
+
196
+ ## Limitations
197
+
198
+ - **Value size** - Maximum 25 MB per value
199
+ - **Key size** - Maximum 512 bytes
200
+ - **Write limits** - 1 write per second per key
201
+ - **Eventual consistency** - Changes may take up to 60 seconds to propagate
202
+ - **Not for hot writes** - Use Durable Objects for high-write scenarios
203
+
204
+ KV is optimized for read-heavy workloads. For write-heavy use cases or strong consistency, consider [Durable Objects](/stack/realtime/durable-objects).
@@ -0,0 +1,232 @@
1
+ # File Storage (R2)
2
+
3
+ Quickback provides built-in file storage using Cloudflare R2, with role-based access control and a dedicated files worker for serving.
4
+
5
+ ## Architecture
6
+
7
+ ```
8
+ ┌─────────────────────────────────────────────────────────────────────┐
9
+ │ Your Application │
10
+ │ │
11
+ │ Upload/Manage Files Serve Files │
12
+ │ ───────────────────── ────────────── │
13
+ │ api.yourdomain.com files.yourdomain.com │
14
+ │ /storage/v1/* /* │
15
+ │ │
16
+ │ ┌─────────────────────┐ ┌─────────────────────┐ │
17
+ │ │ API Worker │ │ Files Worker │ │
18
+ │ │ │ │ │ │
19
+ │ │ POST /bucket │ │ GET /public/* │ │
20
+ │ │ GET /bucket │ │ → No auth │ │
21
+ │ │ POST /object/* │ │ │ │
22
+ │ │ DELETE /object/* │ │ GET /* │ │
23
+ │ │ │ │ → Session + RBAC │ │
24
+ │ └──────────┬──────────┘ └──────────┬──────────┘ │
25
+ │ │ │ │
26
+ │ └───────────┬───────────────────┘ │
27
+ │ │ │
28
+ │ ▼ │
29
+ │ ┌─────────────────────┐ │
30
+ │ │ R2 Bucket │ │
31
+ │ │ quickback-files │ │
32
+ │ └─────────────────────┘ │
33
+ └─────────────────────────────────────────────────────────────────────┘
34
+ ```
35
+
36
+ ## Enabling File Storage
37
+
38
+ Add the `fileStorage` provider to your `quickback.config.ts`:
39
+
40
+ ```typescript
41
+ export default {
42
+ name: 'my-app',
43
+ providers: {
44
+ runtime: { name: 'cloudflare' },
45
+ database: { name: 'cloudflare-d1' },
46
+ auth: { name: 'better-auth' },
47
+ fileStorage: {
48
+ name: 'cloudflare-r2',
49
+ config: {
50
+ binding: 'R2_BUCKET',
51
+ bucketName: 'my-app-files',
52
+ filesBinding: 'FILES_DB',
53
+ maxFileSize: 10 * 1024 * 1024, // 10MB
54
+ allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
55
+ },
56
+ },
57
+ },
58
+ };
59
+ ```
60
+
61
+ ## API Endpoints
62
+
63
+ ### Storage API (api.yourdomain.com/storage/v1)
64
+
65
+ | Method | Endpoint | Description |
66
+ |--------|----------|-------------|
67
+ | POST | `/bucket` | Create a bucket |
68
+ | GET | `/bucket` | List buckets |
69
+ | GET | `/bucket/:name` | Get bucket info |
70
+ | DELETE | `/bucket/:name` | Delete bucket (must be empty) |
71
+ | POST | `/object/:bucket/*path` | Upload file |
72
+ | GET | `/object/:bucket/*path` | Download file |
73
+ | HEAD | `/object/:bucket/*path` | Get file metadata |
74
+ | DELETE | `/object/:bucket/*path` | Delete file (soft delete) |
75
+ | GET | `/object` | List objects |
76
+ | POST | `/url` | Get file URL for serving |
77
+
78
+ ### Files Worker (files.yourdomain.com)
79
+
80
+ | Method | Path | Auth Required |
81
+ |--------|------|---------------|
82
+ | GET/HEAD | `/public/*` | No |
83
+ | GET/HEAD | `/*` | Yes (session + RBAC) |
84
+
85
+ ## Buckets
86
+
87
+ Buckets organize files and define access control policies.
88
+
89
+ ### Creating a Bucket
90
+
91
+ ```bash
92
+ POST /storage/v1/bucket
93
+ {
94
+ "name": "avatars",
95
+ "readScope": "organization",
96
+ "writeScope": "organization",
97
+ "readRoles": ["admin", "member"],
98
+ "writeRoles": ["admin"],
99
+ "deleteRoles": ["admin"]
100
+ }
101
+ ```
102
+
103
+ ### Scope Options
104
+
105
+ | Scope | Read Behavior | Write Behavior |
106
+ |-------|---------------|----------------|
107
+ | `public` | Anyone can read | N/A |
108
+ | `organization` | Org members only | Org members only |
109
+ | `user` | Owner only | Owner only |
110
+
111
+ ### Role-Based Access
112
+
113
+ You can restrict operations to specific roles:
114
+
115
+ ```json
116
+ {
117
+ "readRoles": ["admin", "member"],
118
+ "writeRoles": ["admin", "editor"],
119
+ "deleteRoles": ["admin"]
120
+ }
121
+ ```
122
+
123
+ An empty array `[]` means no role restriction (all authenticated users).
124
+
125
+ ## Uploading Files
126
+
127
+ ```bash
128
+ POST /storage/v1/object/avatars/profile.jpg
129
+ Content-Type: image/jpeg
130
+ Content-Length: 12345
131
+
132
+ <binary data>
133
+ ```
134
+
135
+ Response:
136
+ ```json
137
+ {
138
+ "id": "obj_123",
139
+ "key": "org_abc/avatars/profile.jpg",
140
+ "bucket": "avatars",
141
+ "name": "profile.jpg",
142
+ "size": 12345,
143
+ "mimeType": "image/jpeg",
144
+ "readScope": "organization"
145
+ }
146
+ ```
147
+
148
+ ## Serving Files
149
+
150
+ ### Public Files
151
+
152
+ Files in buckets with `readScope: "public"` are stored with a `public/` prefix:
153
+
154
+ ```
155
+ https://files.yourdomain.com/public/org_abc/avatars/logo.png
156
+ ```
157
+
158
+ No authentication required.
159
+
160
+ ### Private Files
161
+
162
+ Private files require a valid Better Auth session cookie:
163
+
164
+ ```
165
+ https://files.yourdomain.com/org_abc/documents/report.pdf
166
+ ```
167
+
168
+ The files worker:
169
+ 1. Validates the session token
170
+ 2. Checks the user's organization matches
171
+ 3. Verifies role permissions (if `readRoles` configured)
172
+ 4. Serves the file or returns 403
173
+
174
+ ## Generated Files
175
+
176
+ When file storage is configured, the compiler generates:
177
+
178
+ | File | Purpose |
179
+ |------|---------|
180
+ | `src/routes/storage.ts` | Storage API routes |
181
+ | `src/files.ts` | Files database schema (buckets, objects) |
182
+ | `cloudflare-workers/files/index.ts` | Files worker for serving |
183
+ | `cloudflare-workers/files/wrangler.toml` | Files worker config |
184
+
185
+ ## Deployment
186
+
187
+ After compiling:
188
+
189
+ 1. **Create the R2 bucket:**
190
+ ```bash
191
+ wrangler r2 bucket create my-app-files
192
+ ```
193
+
194
+ 2. **Create the files database:**
195
+ ```bash
196
+ wrangler d1 create my-app-files
197
+ ```
198
+
199
+ 3. **Run migrations:**
200
+ ```bash
201
+ wrangler d1 migrations apply my-app-files --local
202
+ wrangler d1 migrations apply my-app-files --remote
203
+ ```
204
+
205
+ 4. **Deploy the API:**
206
+ ```bash
207
+ wrangler deploy
208
+ ```
209
+
210
+ 5. **Deploy the files worker:**
211
+ ```bash
212
+ cd cloudflare-workers/files
213
+ wrangler deploy
214
+ ```
215
+
216
+ ## Configuration Reference
217
+
218
+ | Option | Type | Default | Description |
219
+ |--------|------|---------|-------------|
220
+ | `binding` | `string` | `R2_BUCKET` | R2 bucket binding name |
221
+ | `bucketName` | `string` | Required | R2 bucket name |
222
+ | `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding |
223
+ | `maxFileSize` | `number` | 10MB | Max upload size in bytes |
224
+ | `allowedTypes` | `string[]` | Images only | Allowed MIME types |
225
+ | `publicDomain` | `string` | - | Custom domain for files worker |
226
+
227
+ ## Security Model
228
+
229
+ - **Upload security**: Enforced by API worker (auth middleware, org check, role check)
230
+ - **Serve security**: Enforced by files worker (session validation, metadata RBAC)
231
+ - **Soft deletes**: Files are marked deleted in metadata but retained in R2
232
+ - **Tenant isolation**: All files are prefixed with organization ID