@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,70 @@
1
+ # Using KV
2
+
3
+ Cloudflare KV is used by the Quickback Stack for session storage, caching, and rate limiting.
4
+
5
+ ## Session Storage
6
+
7
+ Better Auth stores sessions in KV by default for fast edge-based lookups. This is auto-configured by the compiler — no setup needed.
8
+
9
+ ```typescript
10
+ // How sessions work internally (auto-generated)
11
+ // On login: session stored in KV
12
+ await kv.put(`session:${sessionToken}`, JSON.stringify(sessionData), {
13
+ expirationTtl: 60 * 60 * 24 * 7, // 7 days
14
+ });
15
+
16
+ // On each request: session retrieved from KV
17
+ const session = await kv.get(`session:${sessionToken}`, "json");
18
+ ```
19
+
20
+ Sessions are automatically:
21
+ - **Created** on sign-in (email/password, passkey, magic link, etc.)
22
+ - **Validated** on every authenticated request via the `Authorization: Bearer <token>` header
23
+ - **Expired** after the configured TTL (default: 7 days)
24
+ - **Deleted** on sign-out
25
+
26
+ ## Rate Limiting
27
+
28
+ KV powers the rate limiting middleware that protects auth endpoints:
29
+
30
+ ```typescript
31
+ // Rate limit key structure (auto-generated)
32
+ // Key: ratelimit:{ip}:{endpoint}
33
+ // Value: request count
34
+ // TTL: rate limit window (e.g., 60 seconds)
35
+ const key = `ratelimit:${ip}:${endpoint}`;
36
+ const count = await kv.get(key);
37
+ if (count && parseInt(count) > limit) {
38
+ return c.json({ error: "Too many requests" }, 429);
39
+ }
40
+ ```
41
+
42
+ See [Auth Security](/stack/auth/security) for rate limiting configuration options.
43
+
44
+ ## Caching
45
+
46
+ You can use KV in custom action handlers for caching frequently accessed data:
47
+
48
+ ```typescript
49
+ // In an action handler
50
+ execute: async ({ db, ctx }) => {
51
+ const kv = ctx.env.KV;
52
+
53
+ // Check cache first
54
+ const cached = await kv.get("expensive-query-result", "json");
55
+ if (cached) return cached;
56
+
57
+ // Compute and cache
58
+ const result = await db.select().from(analytics);
59
+ await kv.put("expensive-query-result", JSON.stringify(result), {
60
+ expirationTtl: 300, // 5 minutes
61
+ });
62
+
63
+ return result;
64
+ }
65
+ ```
66
+
67
+ ## See Also
68
+
69
+ - [KV Setup](/stack/storage/kv) — Namespace creation and wrangler bindings
70
+ - [Auth Security](/stack/auth/security) — Rate limiting and cookie security configuration
@@ -0,0 +1,55 @@
1
+ # Using R2
2
+
3
+ Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
4
+
5
+ ## Upload Flow
6
+
7
+ The generated API provides a two-step upload process:
8
+
9
+ 1. **Request a presigned URL** — Client calls the upload endpoint to get a time-limited URL
10
+ 2. **Upload directly to R2** — Client uploads the file directly to R2 (bypasses your Worker)
11
+ 3. **Store the reference** — The API records the file metadata in D1
12
+
13
+ ```bash
14
+ # 1. Request presigned upload URL
15
+ curl -X POST https://api.example.com/api/v1/files/upload \
16
+ -H "Authorization: Bearer <token>" \
17
+ -H "Content-Type: application/json" \
18
+ -d '{"filename": "report.pdf", "contentType": "application/pdf"}'
19
+
20
+ # Response:
21
+ # { "uploadUrl": "https://bucket.r2.cloudflarestorage.com/...", "fileId": "file_abc123" }
22
+
23
+ # 2. Upload directly to R2 using the presigned URL
24
+ curl -X PUT "<uploadUrl>" \
25
+ -H "Content-Type: application/pdf" \
26
+ --data-binary @report.pdf
27
+ ```
28
+
29
+ ## Download Flow
30
+
31
+ Files are served through your Worker with security checks applied:
32
+
33
+ ```bash
34
+ # Download a file (auth + firewall enforced)
35
+ curl https://api.example.com/api/v1/files/file_abc123/download \
36
+ -H "Authorization: Bearer <token>"
37
+ ```
38
+
39
+ The download endpoint:
40
+ 1. Validates the user's session
41
+ 2. Checks firewall — the file must belong to the user's organization
42
+ 3. Checks access — the user must have the required role
43
+ 4. Streams the file from R2
44
+
45
+ ## Role-Based Access
46
+
47
+ File access respects the same security layers as your API:
48
+
49
+ - **Firewall** — Users can only access files belonging to their organization
50
+ - **Access** — Role-based download permissions
51
+
52
+ ## See Also
53
+
54
+ - [R2 Setup](/stack/storage/r2) — Bucket creation, wrangler bindings, and configuration
55
+ - [Avatars](/stack/account-ui/features/avatars) — Avatar upload UI integration
@@ -0,0 +1,554 @@
1
+ # Automatic Embeddings
2
+
3
+ Quickback can automatically generate embeddings for your data using Cloudflare Queues and Workers AI. When configured, INSERT and UPDATE operations automatically enqueue embedding jobs that are processed asynchronously.
4
+
5
+ ## Enabling Embeddings
6
+
7
+ Add an `embeddings` configuration to your resource definition:
8
+
9
+ ```typescript
10
+ // quickback/features/jobs/jobs.ts
11
+ import { defineTable } from "@quickback/compiler";
12
+
13
+ export default defineTable(jobs, {
14
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
15
+
16
+ embeddings: {
17
+ fields: ['description'], // Fields to concatenate and embed
18
+ model: '@cf/baai/bge-base-en-v1.5', // Embedding model (optional)
19
+ onInsert: true, // Auto-embed on create (default: true)
20
+ onUpdate: ['description'], // Re-embed when these fields change
21
+ embeddingColumn: 'embedding', // Column to store embedding
22
+ metadata: ['department'], // Metadata for Vectorize index
23
+ },
24
+
25
+ crud: {
26
+ create: { access: { roles: ['recruiter'] } },
27
+ update: { access: { roles: ['recruiter'] } },
28
+ },
29
+ });
30
+ ```
31
+
32
+ ## Configuration Options
33
+
34
+ | Option | Type | Default | Description |
35
+ |--------|------|---------|-------------|
36
+ | `fields` | `string[]` | **Required** | Fields to concatenate and embed |
37
+ | `model` | `string` | `'@cf/baai/bge-base-en-v1.5'` | Workers AI embedding model |
38
+ | `onInsert` | `boolean` | `true` | Embed on INSERT operations |
39
+ | `onUpdate` | `boolean \| string[]` | `true` | Embed on UPDATE; array limits to specific fields |
40
+ | `embeddingColumn` | `string` | `'embedding'` | Column to store the embedding vector |
41
+ | `separator` | `string` | `' '` | Separator for joining multiple fields |
42
+ | `metadata` | `string[]` | `[]` | Fields to include in Vectorize metadata |
43
+
44
+ ### onUpdate Options
45
+
46
+ ```typescript
47
+ // Always re-embed on any update
48
+ onUpdate: true
49
+
50
+ // Never re-embed on update
51
+ onUpdate: false
52
+
53
+ // Only re-embed when specific fields change
54
+ onUpdate: ['description', 'title']
55
+ ```
56
+
57
+ ## How It Works
58
+
59
+ ```
60
+ ┌─────────────────────────────────────────────────────────────────────┐
61
+ │ Main API Worker │
62
+ │ │
63
+ │ ┌─────────────────────┐ ┌────────────────────┐ │
64
+ │ │ POST /jobs │ │ Queue Consumer │ │
65
+ │ │ │ │ │ │
66
+ │ │ 1. Auth middleware │ │ 1. Workers AI │ │
67
+ │ │ 2. Firewall │ │ embed() │ │
68
+ │ │ 3. Guards │ │ 2. D1 update() │ │
69
+ │ │ 4. Insert to D1 │ │ 3. Vectorize │ │
70
+ │ │ 5. Enqueue job ─────┼───▶│ upsert() │ │
71
+ │ └─────────────────────┘ └────────────────────┘ │
72
+ │ ▲ │
73
+ │ ┌─────────────────┴──────────────────┐ │
74
+ │ │ EMBEDDINGS_QUEUE │ │
75
+ │ └────────────────────────────────────┘ │
76
+ └─────────────────────────────────────────────────────────────────────┘
77
+ ```
78
+
79
+ 1. **API Request** - POST/PATCH arrives and passes through auth, firewall, guards
80
+ 2. **Database Insert** - Record is created/updated in D1
81
+ 3. **Enqueue Job** - Embedding job is sent to Cloudflare Queue
82
+ 4. **Queue Consumer** - Processes job asynchronously:
83
+ - Calls Workers AI to generate embedding
84
+ - Updates D1 with embedding vector
85
+ - Optionally upserts to Vectorize index
86
+
87
+ ## Security Model
88
+
89
+ **Security is enforced at enqueue time, not consume time:**
90
+
91
+ - Jobs are only enqueued after passing all security checks (auth, firewall, guards)
92
+ - The queue consumer is an internal process that executes pre-validated jobs
93
+ - If a user can't create a job posting, they can't trigger an embedding job
94
+
95
+ ## Generic Embeddings API
96
+
97
+ In addition to automatic embeddings on CRUD operations, Quickback generates a generic embeddings API endpoint that allows you to trigger embeddings on arbitrary content.
98
+
99
+ ### POST /api/v1/embeddings
100
+
101
+ Generate an embedding for any text content:
102
+
103
+ ```bash
104
+ curl -X POST https://your-api.workers.dev/api/v1/embeddings \
105
+ -H "Content-Type: application/json" \
106
+ -H "Cookie: better-auth.session_token=..." \
107
+ -d '{
108
+ "content": "Text to embed",
109
+ "model": "@cf/baai/bge-base-en-v1.5",
110
+ "table": "jobs",
111
+ "id": "job_123"
112
+ }'
113
+ ```
114
+
115
+ #### Request Body
116
+
117
+ | Field | Type | Required | Description |
118
+ |-------|------|----------|-------------|
119
+ | `content` | `string` | Yes | Text to generate embedding for |
120
+ | `model` | `string` | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
121
+ | `table` | `string` | No | Table to store embedding back to |
122
+ | `id` | `string` | Conditional | Record ID to update (required if `table` is specified) |
123
+
124
+ #### Response
125
+
126
+ ```json
127
+ {
128
+ "queued": true,
129
+ "jobId": "550e8400-e29b-41d4-a716-446655440000",
130
+ "table": "jobs",
131
+ "id": "job_123",
132
+ "model": "@cf/baai/bge-base-en-v1.5"
133
+ }
134
+ ```
135
+
136
+ ### GET /api/v1/embeddings/tables
137
+
138
+ List tables that have embeddings configured:
139
+
140
+ ```bash
141
+ curl https://your-api.workers.dev/api/v1/embeddings/tables \
142
+ -H "Cookie: better-auth.session_token=..."
143
+ ```
144
+
145
+ Response:
146
+
147
+ ```json
148
+ {
149
+ "tables": [
150
+ {
151
+ "name": "jobs",
152
+ "embeddingColumn": "embedding",
153
+ "model": "@cf/baai/bge-base-en-v1.5"
154
+ }
155
+ ]
156
+ }
157
+ ```
158
+
159
+ ### Authentication & Authorization
160
+
161
+ The generic embeddings API requires authentication and uses the `activeOrgId` from the user's context to enforce organization-level isolation. Embedding jobs are scoped to the user's current organization.
162
+
163
+ ### Use Cases
164
+
165
+ The generic embeddings API is useful for:
166
+
167
+ - **Batch embedding**: Embed content without going through CRUD routes
168
+ - **Re-embedding**: Force re-generation of embeddings for existing records
169
+ - **Preview embeddings**: Test embedding generation before persisting
170
+ - **External content**: Embed content that doesn't fit your defined schemas
171
+
172
+ ## Generated Files
173
+
174
+ When embeddings are configured, the compiler generates:
175
+
176
+ | File | Purpose |
177
+ |------|---------|
178
+ | `src/queue-consumer.ts` | Queue consumer handler for processing embedding jobs |
179
+ | `src/routes/embeddings.ts` | Generic embeddings API routes |
180
+ | `wrangler.toml` | Queue producer/consumer bindings, AI binding |
181
+ | `src/env.d.ts` | `EMBEDDINGS_QUEUE`, `AI` types |
182
+ | `src/index.ts` | Exports `queue` handler, mounts `/api/v1/embeddings` |
183
+
184
+ ### wrangler.toml additions
185
+
186
+ ```toml
187
+ # Embeddings Queue
188
+ [[queues.producers]]
189
+ queue = "your-app-embeddings-queue"
190
+ binding = "EMBEDDINGS_QUEUE"
191
+
192
+ [[queues.consumers]]
193
+ queue = "your-app-embeddings-queue"
194
+ max_batch_size = 10
195
+ max_batch_timeout = 30
196
+ max_retries = 3
197
+
198
+ # Workers AI
199
+ [ai]
200
+ binding = "AI"
201
+ ```
202
+
203
+ ## Multiple Fields
204
+
205
+ Embed multiple fields by concatenating them:
206
+
207
+ ```typescript
208
+ embeddings: {
209
+ fields: ['title', 'description', 'department'], // Joined with spaces by default
210
+ // ...
211
+ }
212
+ ```
213
+
214
+ Generated embedding text: `"${title} ${description} ${department}"`
215
+
216
+ ### Custom Separator
217
+
218
+ Use `separator` to control how fields are joined. This is useful for sentence boundary detection:
219
+
220
+ ```typescript
221
+ embeddings: {
222
+ fields: ['title', 'description'],
223
+ separator: '. ', // Join with period + space
224
+ // ...
225
+ }
226
+ ```
227
+
228
+ Generated code: `[result[0].title, result[0].description].filter(Boolean).join('. ')`
229
+
230
+ The `filter(Boolean)` ensures null or empty fields are excluded cleanly — no trailing separator when a field is absent.
231
+
232
+ ## Vectorize Integration
233
+
234
+ If you have a Vectorize index configured, embeddings are automatically upserted:
235
+
236
+ ```typescript
237
+ // quickback.config.ts
238
+ providers: {
239
+ database: {
240
+ config: {
241
+ vectorizeIndexName: 'jobs-embeddings', // Your Vectorize index
242
+ vectorizeBinding: 'VECTORIZE',
243
+ },
244
+ },
245
+ },
246
+ ```
247
+
248
+ The queue consumer will:
249
+ 1. Generate the embedding via Workers AI
250
+ 2. Store the vector in D1 (JSON string)
251
+ 3. Upsert to Vectorize with metadata
252
+
253
+ ### Vectorize Metadata
254
+
255
+ Include fields in Vectorize metadata for filtering:
256
+
257
+ ```typescript
258
+ embeddings: {
259
+ fields: ['description'],
260
+ metadata: ['department', 'organizationId', 'status'],
261
+ }
262
+ ```
263
+
264
+ Enables queries like:
265
+ ```typescript
266
+ const results = await env.VECTORIZE.query(vector, {
267
+ topK: 10,
268
+ filter: { department: 'engineering' }
269
+ });
270
+ ```
271
+
272
+ ## Schema Requirements
273
+
274
+ Your schema must include the embedding column:
275
+
276
+ ```typescript
277
+ // quickback/features/jobs/jobs.ts
278
+ import { feature, q } from "@quickback/compiler";
279
+
280
+ export default feature("jobs", {
281
+ columns: {
282
+ id: q.id(),
283
+ title: q.text().required(),
284
+ description: q.text().required(),
285
+ department: q.text().optional(),
286
+ status: q.text().required(),
287
+ organizationId: q.scope("organization"),
288
+
289
+ // Embedding column — stores JSON array of floats
290
+ embedding: q.text().optional(),
291
+ },
292
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
293
+ crud: { list: {}, get: {}, create: {}, update: {}, delete: {} },
294
+ });
295
+ ```
296
+
297
+ ## Supported Models
298
+
299
+ Any Workers AI embedding model can be used:
300
+
301
+ | Model | Dimensions | Notes |
302
+ |-------|------------|-------|
303
+ | `@cf/baai/bge-base-en-v1.5` | 768 | Default, good general-purpose |
304
+ | `@cf/baai/bge-small-en-v1.5` | 384 | Faster, smaller |
305
+ | `@cf/baai/bge-large-en-v1.5` | 1024 | Higher quality |
306
+
307
+ See [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/) for the full list.
308
+
309
+ ## Deployment
310
+
311
+ After compiling with embeddings:
312
+
313
+ 1. **Create the queue:**
314
+ ```bash
315
+ wrangler queues create your-app-embeddings-queue
316
+ ```
317
+
318
+ 2. **Deploy the worker:**
319
+ ```bash
320
+ wrangler deploy
321
+ ```
322
+
323
+ The single worker handles both HTTP requests and queue consumption.
324
+
325
+ ## Monitoring
326
+
327
+ Queue metrics are available in the Cloudflare dashboard:
328
+ - Messages enqueued
329
+ - Messages processed
330
+ - Retry count
331
+ - Consumer lag
332
+
333
+ Check queue health:
334
+ ```bash
335
+ wrangler queues list
336
+ wrangler queues consumer your-app-embeddings-queue
337
+ ```
338
+
339
+ ## Error Handling
340
+
341
+ Failed jobs are automatically retried (up to `max_retries`):
342
+
343
+ ```typescript
344
+ // In queue consumer
345
+ try {
346
+ const embedding = await env.AI.run(job.model, { text: job.content });
347
+ // ...
348
+ message.ack();
349
+ } catch (error) {
350
+ console.error('[Queue] Embedding job failed:', error);
351
+ message.retry(); // Will retry up to 3 times
352
+ }
353
+ ```
354
+
355
+ After max retries, the message is dead-lettered (if configured) or dropped.
356
+
357
+ ## Similarity Search Service
358
+
359
+ For applications that need typed similarity search with classification, you can define embedding search configurations using `defineEmbedding`. This generates a service layer with typed search functions.
360
+
361
+ ### Defining Search Configurations
362
+
363
+ Create a file in `services/embeddings/`:
364
+
365
+ ```typescript
366
+ // services/embeddings/job-similarity.ts
367
+ import { defineEmbedding } from '@quickback/compiler';
368
+
369
+ export default defineEmbedding({
370
+ name: 'job-similarity',
371
+ description: 'Find similar job postings by description content',
372
+
373
+ // Source configuration
374
+ source: 'jobs', // Table name
375
+ vectorIndex: 'VECTORIZE', // Binding name
376
+ model: '@cf/baai/bge-base-en-v1.5',
377
+
378
+ // Search configuration
379
+ search: {
380
+ threshold: 0.60, // Minimum similarity (default: 0.60)
381
+ limit: 10, // Max results (default: 10)
382
+ classify: {
383
+ DUPLICATE_POSTING: 0.90, // Score >= 0.90 = DUPLICATE_POSTING
384
+ SIMILAR_ROLE: 0.85, // Score >= 0.85 = SIMILAR_ROLE
385
+ RELATED: 0.75, // Score >= 0.75 = RELATED
386
+ },
387
+ filters: ['department', 'organizationId'], // Filterable fields
388
+ },
389
+
390
+ // Generation triggers (beyond CRUD)
391
+ triggers: {
392
+ onQueueMessage: 'embed_job', // Listen for queue messages
393
+ },
394
+ });
395
+ ```
396
+
397
+ ### Generated Service Layer
398
+
399
+ After compilation, a `createEmbeddings()` helper is generated in `src/lib/embeddings.ts`:
400
+
401
+ ```typescript
402
+ import { createEmbeddings } from '../lib/embeddings';
403
+
404
+ export const execute: ActionExecutor = async ({ ctx, input }) => {
405
+ const embeddings = createEmbeddings(ctx.env);
406
+
407
+ // Search with automatic classification
408
+ const similar = await embeddings.jobSimilarity.search(
409
+ 'Senior Full-Stack Engineer with React and Node.js experience',
410
+ {
411
+ department: 'engineering',
412
+ limit: 5,
413
+ threshold: 0.70,
414
+ }
415
+ );
416
+
417
+ // Returns: [{ id, score: 0.87, classification: 'SIMILAR_ROLE', metadata }]
418
+ for (const match of similar) {
419
+ console.log(`${match.classification}: ${match.id} (${match.score})`);
420
+ }
421
+
422
+ return { similar };
423
+ };
424
+ ```
425
+
426
+ ### Classification Thresholds
427
+
428
+ Results are automatically classified based on similarity score:
429
+
430
+ | Classification | Default Threshold | Meaning |
431
+ |----------------|-------------------|---------|
432
+ | `DUPLICATE_POSTING` | >= 0.90 | Near-identical job posting |
433
+ | `SIMILAR_ROLE` | >= 0.85 | Strongly similar role and requirements |
434
+ | `RELATED` | >= 0.75 | Topically related position |
435
+ | `NEW` | < 0.75 | No significant match |
436
+
437
+ Customize thresholds per use case:
438
+
439
+ ```typescript
440
+ search: {
441
+ classify: {
442
+ DUPLICATE_POSTING: 0.95, // Stricter duplicate detection
443
+ SIMILAR_ROLE: 0.88,
444
+ RELATED: 0.70, // Broader "related" category
445
+ },
446
+ }
447
+ ```
448
+
449
+ ### Gray Zone Detection
450
+
451
+ For cases where automatic classification isn't sufficient, use gray zone detection to get matches that need semantic evaluation:
452
+
453
+ ```typescript
454
+ const results = await embeddings.jobSimilarity.findWithGrayZone(
455
+ 'Some job description text',
456
+ { min: 0.60, max: 0.85 }
457
+ );
458
+
459
+ // Returns structured results:
460
+ // {
461
+ // high_confidence: [...], // Score >= 0.85 (auto-classified)
462
+ // gray_zone: [...] // 0.60 <= score < 0.85 (needs review)
463
+ // }
464
+
465
+ // Process high confidence matches automatically
466
+ for (const match of results.high_confidence) {
467
+ await markAsDuplicate(match.id);
468
+ }
469
+
470
+ // Queue gray zone for manual review
471
+ for (const match of results.gray_zone) {
472
+ await queueForReview(match.id, match.score);
473
+ }
474
+ ```
475
+
476
+ ### Generate Embeddings Directly
477
+
478
+ Generate embeddings without searching:
479
+
480
+ ```typescript
481
+ const embeddings = createEmbeddings(ctx.env);
482
+
483
+ // Get raw embedding vector
484
+ const vector = await embeddings.jobSimilarity.embed(
485
+ 'Text to embed'
486
+ );
487
+ // Returns: number[] (768 dimensions for bge-base)
488
+ ```
489
+
490
+ ### Multiple Search Configurations
491
+
492
+ Define different configurations for different use cases:
493
+
494
+ ```typescript
495
+ // services/embeddings/candidate-similarity.ts
496
+ export default defineEmbedding({
497
+ name: 'candidate-similarity',
498
+ description: 'Match candidates by resume content',
499
+ source: 'candidates',
500
+ search: {
501
+ threshold: 0.65,
502
+ limit: 20,
503
+ classify: {
504
+ DUPLICATE_POSTING: 0.92,
505
+ SIMILAR_ROLE: 0.80,
506
+ RELATED: 0.65,
507
+ },
508
+ filters: ['source'],
509
+ },
510
+ });
511
+
512
+ // services/embeddings/application-match.ts
513
+ export default defineEmbedding({
514
+ name: 'application-match',
515
+ description: 'Match applications to similar job postings',
516
+ source: 'applications',
517
+ search: {
518
+ threshold: 0.70,
519
+ limit: 5,
520
+ classify: {
521
+ DUPLICATE_POSTING: 0.95,
522
+ SIMILAR_ROLE: 0.90,
523
+ RELATED: 0.80,
524
+ },
525
+ filters: ['jobId', 'organizationId'],
526
+ },
527
+ });
528
+ ```
529
+
530
+ Usage:
531
+ ```typescript
532
+ const embeddings = createEmbeddings(ctx.env);
533
+
534
+ // Different search behaviors for different content types
535
+ const similarJobs = await embeddings.jobSimilarity.search(text, opts);
536
+ const similarCandidates = await embeddings.candidateSimilarity.search(text, opts);
537
+ const matchingApplications = await embeddings.applicationMatch.search(text, opts);
538
+ ```
539
+
540
+ ### Table-Level vs Service-Level
541
+
542
+ | Feature | Table-level (`defineTable`) | Service-level (`defineEmbedding`) |
543
+ |---------|----------------------------|----------------------------------|
544
+ | Auto-embed on INSERT | ✅ | ❌ |
545
+ | Auto-embed on UPDATE | ✅ | ❌ |
546
+ | Custom search functions | ❌ | ✅ |
547
+ | Classification thresholds | ❌ | ✅ |
548
+ | Gray zone detection | ❌ | ✅ |
549
+ | Filterable searches | ❌ | ✅ |
550
+ | Queue message triggers | ❌ | ✅ |
551
+
552
+ **Use both together:**
553
+ - `defineTable` with `embeddings` config for automatic embedding generation
554
+ - `defineEmbedding` for typed search functions with classification