@quickback-dev/cli 0.10.15 → 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,44 @@
1
+ # Vector & AI
2
+
3
+ The Quickback Stack integrates with Cloudflare Workers AI to automatically generate vector embeddings for semantic search. Embeddings are generated asynchronously via Cloudflare Queues and stored in both D1 (as JSON) and optionally in a Vectorize index for fast similarity search.
4
+
5
+ ## Two Levels of Configuration
6
+
7
+ | Level | API | Purpose |
8
+ |-------|-----|---------|
9
+ | Table-level | `embeddings` in `defineTable()` | Auto-embed on INSERT/UPDATE |
10
+ | Service-level | `defineEmbedding()` | Typed search functions with classification |
11
+
12
+ Use both together: table-level for auto-generation, service-level for search.
13
+
14
+ ## How It Works
15
+
16
+ ```
17
+ CRUD operation → Enqueue job → Queue consumer
18
+ │
19
+ ├─ Workers AI (generate embedding)
20
+ ├─ D1 (store vector as JSON)
21
+ └─ Vectorize (upsert for search)
22
+ ```
23
+
24
+ 1. A record is created or updated via the API
25
+ 2. The compiler auto-enqueues an embedding job to `EMBEDDINGS_QUEUE`
26
+ 3. The queue consumer generates the embedding using Workers AI
27
+ 4. The vector is stored in D1 and optionally upserted to Vectorize
28
+
29
+ ## Cloudflare Bindings
30
+
31
+ | Binding | Purpose |
32
+ |---------|---------|
33
+ | `AI` | Workers AI for embedding generation |
34
+ | `VECTORIZE` | Vectorize index for similarity search |
35
+ | `EMBEDDINGS_QUEUE` | Queue for async processing |
36
+
37
+ ## Default Model
38
+
39
+ The default embedding model is `@cf/baai/bge-base-en-v1.5` (768 dimensions). You can configure a different model per table.
40
+
41
+ ## Pages
42
+
43
+ - **[Automatic Embeddings](/stack/vector/embeddings)** — `defineTable()` embeddings config, queue consumer, Vectorize integration, and `defineEmbedding()` search service
44
+ - **[Using Embeddings](/stack/vector/using-embeddings)** — Embeddings API endpoints, semantic search, and practical usage
@@ -0,0 +1,186 @@
1
+ # Using Embeddings
2
+
3
+ This page covers the runtime API for working with embeddings — the generated endpoints, the search service, and practical usage patterns.
4
+
5
+ ## Embeddings API
6
+
7
+ When any feature has embeddings configured, the compiler generates these endpoints:
8
+
9
+ ### Generate Embedding
10
+
11
+ ```
12
+ POST /api/v1/embeddings
13
+ ```
14
+
15
+ Enqueue an embedding job for arbitrary content:
16
+
17
+ ```bash
18
+ curl -X POST https://api.example.com/api/v1/embeddings \
19
+ -H "Content-Type: application/json" \
20
+ -H "Cookie: better-auth.session_token=..." \
21
+ -d '{
22
+ "content": "Text to generate an embedding for",
23
+ "model": "@cf/baai/bge-base-en-v1.5",
24
+ "table": "jobs",
25
+ "id": "job_123"
26
+ }'
27
+ ```
28
+
29
+ **Request body:**
30
+
31
+ | Field | Type | Required | Description |
32
+ |-------|------|----------|-------------|
33
+ | `content` | string | Yes | Text to embed |
34
+ | `model` | string | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
35
+ | `table` | string | No | Table to store the embedding in |
36
+ | `id` | string | Conditional | Record ID (required when `table` is provided) |
37
+
38
+ **Response:**
39
+
40
+ ```json
41
+ {
42
+ "queued": true,
43
+ "jobId": "550e8400-e29b-41d4-a716-446655440000",
44
+ "table": "jobs",
45
+ "id": "job_123",
46
+ "model": "@cf/baai/bge-base-en-v1.5"
47
+ }
48
+ ```
49
+
50
+ This endpoint is useful for:
51
+ - Re-embedding existing records
52
+ - Embedding content that doesn't go through CRUD routes
53
+ - Batch embedding via scripts
54
+
55
+ ### List Embedding Tables
56
+
57
+ ```
58
+ GET /api/v1/embeddings/tables
59
+ ```
60
+
61
+ List tables that have embeddings configured:
62
+
63
+ ```json
64
+ {
65
+ "tables": [
66
+ {
67
+ "name": "jobs",
68
+ "embeddingColumn": "embedding",
69
+ "model": "@cf/baai/bge-base-en-v1.5"
70
+ }
71
+ ]
72
+ }
73
+ ```
74
+
75
+ ## Search Service
76
+
77
+ For typed similarity search with classification, use the `createEmbeddings()` service generated from `defineEmbedding()` configurations.
78
+
79
+ ### Basic Search
80
+
81
+ ```typescript
82
+ const embeddings = createEmbeddings(ctx.env);
83
+
84
+ const results = await embeddings.jobSimilarity.search(
85
+ "Senior backend engineer with distributed systems experience",
86
+ {
87
+ department: "Engineering",
88
+ limit: 5,
89
+ threshold: 0.70,
90
+ }
91
+ );
92
+
93
+ // Returns: [{ id, score, classification, metadata }]
94
+ for (const match of results) {
95
+ console.log(`${match.classification}: ${match.id} (score: ${match.score})`);
96
+ }
97
+ ```
98
+
99
+ ### Classification
100
+
101
+ Results are automatically classified based on similarity score:
102
+
103
+ | Classification | Default Threshold | Meaning |
104
+ |----------------|-------------------|---------|
105
+ | `DUPLICATE` | >= 0.90 | Near-identical job posting |
106
+ | `SIMILAR_ROLE` | >= 0.85 | Strongly similar role requirements |
107
+ | `RELATED` | >= 0.75 | Topically related position |
108
+ | `NEW` | < 0.75 | No significant match |
109
+
110
+ ### Gray Zone Detection
111
+
112
+ For cases where automatic classification isn't sufficient, use gray zone detection:
113
+
114
+ ```typescript
115
+ const results = await embeddings.jobSimilarity.findWithGrayZone(
116
+ "Full-stack developer with React and Node.js",
117
+ { min: 0.60, max: 0.85 }
118
+ );
119
+
120
+ // results.high_confidence — Score >= 0.85 (auto-classified)
121
+ // results.gray_zone — 0.60 <= score < 0.85 (needs review)
122
+ ```
123
+
124
+ ### Raw Embedding
125
+
126
+ Generate an embedding vector without searching:
127
+
128
+ ```typescript
129
+ const vector = await embeddings.jobSimilarity.embed("Text to embed");
130
+ // Returns: number[] (768 dimensions for bge-base)
131
+ ```
132
+
133
+ ## Vectorize Queries
134
+
135
+ If your project uses a Vectorize index, you can query it directly for custom search logic:
136
+
137
+ ```typescript
138
+ // Generate embedding for query text
139
+ const queryVector = await embeddings.jobSimilarity.embed(searchText);
140
+
141
+ // Query Vectorize with metadata filters
142
+ const results = await ctx.env.VECTORIZE.query(queryVector, {
143
+ topK: 10,
144
+ filter: {
145
+ department: "Engineering",
146
+ organizationId: ctx.activeOrgId,
147
+ },
148
+ });
149
+ ```
150
+
151
+ The `metadata` fields in your `defineTable` embeddings config are automatically included in the Vectorize index, enabling filtered searches.
152
+
153
+ ## Auto-Embed vs Manual
154
+
155
+ | Trigger | How | Use Case |
156
+ |---------|-----|----------|
157
+ | Auto (INSERT) | Compiler enqueues after successful create | Default behavior |
158
+ | Auto (UPDATE) | Compiler enqueues when watched fields change | Keeps embeddings fresh |
159
+ | Manual (API) | `POST /api/v1/embeddings` | Re-embedding, batch jobs |
160
+ | Manual (Queue) | `env.EMBEDDINGS_QUEUE.send(...)` | Custom pipelines |
161
+
162
+ ## Security
163
+
164
+ - The embeddings API requires authentication
165
+ - Jobs are scoped to the user's `activeOrgId`
166
+ - Embedding jobs are only enqueued after all security checks pass (auth, firewall, guards)
167
+ - The queue consumer is an internal process — it trusts pre-validated jobs
168
+
169
+ ## Supported Models
170
+
171
+ | Model | Dimensions | Notes |
172
+ |-------|------------|-------|
173
+ | `@cf/baai/bge-base-en-v1.5` | 768 | Default, good general-purpose |
174
+ | `@cf/baai/bge-small-en-v1.5` | 384 | Faster, smaller |
175
+ | `@cf/baai/bge-large-en-v1.5` | 1024 | Higher quality |
176
+
177
+ See [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/) for the full list.
178
+
179
+ ## Cloudflare Only
180
+
181
+ Embeddings require Cloudflare Workers AI and Queues. They are not available with the Bun or Node runtimes.
182
+
183
+ ## See Also
184
+
185
+ - [Automatic Embeddings](/stack/vector/embeddings) — `defineTable()` config, `defineEmbedding()` search service, and Vectorize integration
186
+ - [Queues](/stack/queues) — How embedding jobs are processed
@@ -0,0 +1,186 @@
1
+ # Inbound Webhooks
2
+
3
+ Inbound webhooks allow external services (Stripe, Paddle, GitHub, etc.) to notify your API of events. Quickback generates endpoints that verify signatures, deduplicate events, and dispatch to your handler functions via a Cloudflare Queue.
4
+
5
+ ## Endpoint
6
+
7
+ ```
8
+ POST /webhooks/v1/inbound/:provider
9
+ ```
10
+
11
+ The `:provider` parameter identifies which service sent the webhook (e.g., `stripe`, `paddle`, `github`). Each provider has its own signature verification logic.
12
+
13
+ ## How It Works
14
+
15
+ ```
16
+ External Service → POST /webhooks/v1/inbound/stripe
17
+ │
18
+ ├─ 1. Verify signature (HMAC-SHA256)
19
+ ├─ 2. Parse event (provider-specific)
20
+ ├─ 3. Deduplicate via externalId
21
+ ├─ 4. Store in webhook_events table
22
+ ├─ 5. Enqueue for async processing
23
+ └─ 6. Return 200 OK immediately
24
+
25
+ Queue Consumer
26
+ │
27
+ ├─ 1. Update status → 'processing'
28
+ ├─ 2. Call registered handlers
29
+ └─ 3. Update status → 'processed' or 'failed'
30
+ ```
31
+
32
+ The API returns `200 OK` immediately after enqueuing. Your handler logic runs asynchronously via the queue consumer, so external services don't time out waiting for your processing to complete.
33
+
34
+ ## Registering Handlers
35
+
36
+ Use `onWebhookEvent()` in your action code to register handlers for specific events:
37
+
38
+ ```typescript
39
+ onWebhookEvent("stripe:checkout.session.completed", async (ctx) => {
40
+ const { type, data, provider, env } = ctx;
41
+ await createSubscription(data, env);
42
+ });
43
+
44
+ // Wildcard — handle all events from a provider
45
+ onWebhookEvent("stripe:*", async (ctx) => {
46
+ console.log(`Received ${ctx.type} from ${ctx.provider}`);
47
+ });
48
+ ```
49
+
50
+ **Handler context:**
51
+
52
+ | Field | Type | Description |
53
+ |-------|------|-------------|
54
+ | `type` | `string` | Full event type (e.g., `stripe:checkout.session.completed`) |
55
+ | `data` | `unknown` | Parsed event payload |
56
+ | `provider` | `string` | Provider name (e.g., `stripe`) |
57
+ | `env` | `CloudflareBindings` | Cloudflare environment bindings |
58
+
59
+ **Execution order:**
60
+ 1. Specific handlers run first (exact match on event type)
61
+ 2. Wildcard handlers run after
62
+ 3. All matching handlers run in parallel
63
+ 4. If any handler throws, the message is retried
64
+
65
+ ## Signature Verification
66
+
67
+ Each provider verifies signatures differently. The secret is read from an environment variable.
68
+
69
+ ### Stripe
70
+
71
+ **Environment variable:** `STRIPE_WEBHOOK_SECRET`
72
+
73
+ Stripe uses HMAC-SHA256 with a timestamp-based signature:
74
+
75
+ ```
76
+ Stripe-Signature: t=1614556800,v1=abc123...
77
+ ```
78
+
79
+ The signed payload is `<timestamp>.<raw_body>`. Verification checks:
80
+ - HMAC matches
81
+ - Timestamp is within 5 minutes (prevents replay attacks)
82
+
83
+ ### Custom Providers
84
+
85
+ Providers implement this interface:
86
+
87
+ ```typescript
88
+ interface InboundProvider {
89
+ name: string;
90
+ verifySignature(payload: string, signature: string, secret: string): Promise<boolean>;
91
+ parseEvent(payload: string): {
92
+ type: string;
93
+ data: unknown;
94
+ externalId?: string;
95
+ };
96
+ }
97
+ ```
98
+
99
+ ## Idempotency
100
+
101
+ Events are deduplicated on the tuple `(provider, externalId)` (e.g., Stripe's `event.id`). The `webhook_events` table carries a **unique index** on this pair, and inbound delivery uses `INSERT … ON CONFLICT DO NOTHING` so concurrent deliveries collapse deterministically:
102
+
103
+ - The first delivery to win the race inserts the row, enqueues processing, and returns `{ received: true, eventId }`.
104
+ - Any concurrent delivery with the same `(provider, externalId)` short-circuits and returns `{ received: true, duplicate: true }` — the queue is **never** sent the duplicate, so handlers run exactly once.
105
+
106
+ Events without an `externalId` (NULL) are not deduplicated. SQLite treats NULLs as distinct in unique indexes, so providers that don't supply a stable event ID continue to insert one row per delivery.
107
+
108
+ ### Migrating an existing deployment
109
+
110
+ The unique index was added in v0.10.x. Existing deployments may have duplicate rows from before the constraint existed; drizzle-kit's migration will fail until they are cleaned up. Run this once before applying the migration:
111
+
112
+ ```sql
113
+ DELETE FROM webhook_events
114
+ WHERE rowid NOT IN (
115
+ SELECT MIN(rowid) FROM webhook_events
116
+ WHERE external_id IS NOT NULL
117
+ GROUP BY provider, external_id
118
+ );
119
+ ```
120
+
121
+ This keeps the earliest row for each `(provider, external_id)` pair and discards the duplicates.
122
+
123
+ ## Database Schema
124
+
125
+ Inbound events are stored in the `webhook_events` table:
126
+
127
+ | Column | Type | Description |
128
+ |--------|------|-------------|
129
+ | `id` | text | Primary key (`whe_<uuid>`) |
130
+ | `provider` | text | Provider name |
131
+ | `eventType` | text | Event type from provider |
132
+ | `externalId` | text | Provider's event ID (for deduplication) |
133
+ | `payload` | text | Raw JSON payload |
134
+ | `status` | text | `received`, `processing`, `processed`, `failed` |
135
+ | `attempts` | integer | Processing attempt count |
136
+ | `processedAt` | timestamp | When successfully processed |
137
+ | `error` | text | Error message if failed |
138
+ | `createdAt` | timestamp | When received |
139
+
140
+ ## Admin Routes
141
+
142
+ Two admin-only routes are generated for monitoring inbound webhooks:
143
+
144
+ ### List Events
145
+
146
+ ```
147
+ GET /webhooks/v1/inbound/events
148
+ ```
149
+
150
+ Returns recent inbound events with their status. Requires admin role.
151
+
152
+ ### Retry Failed Event
153
+
154
+ ```
155
+ POST /webhooks/v1/inbound/events/:id/retry
156
+ ```
157
+
158
+ Re-queues a failed event for processing. Requires admin role.
159
+
160
+ ## Error Handling
161
+
162
+ - **Invalid signature** — Returns `401 Unauthorized`, event not stored
163
+ - **Handler failure** — Event marked as `failed`, message retried (up to 3 times via queue)
164
+ - **All retries exhausted** — Event remains in `failed` status; use the admin retry endpoint to re-process manually
165
+
166
+ ## Configuration
167
+
168
+ Webhooks are enabled by setting `webhooksBinding` in your database config:
169
+
170
+ ```typescript
171
+ database: defineDatabase("cloudflare-d1", {
172
+ binding: "DB",
173
+ webhooksBinding: "WEBHOOKS_DB",
174
+ })
175
+ ```
176
+
177
+ Set the provider secret as a Wrangler secret:
178
+
179
+ ```bash
180
+ wrangler secret put STRIPE_WEBHOOK_SECRET
181
+ ```
182
+
183
+ ## See Also
184
+
185
+ - [Outbound Webhooks](/stack/webhooks/outbound) — Send webhooks when data changes
186
+ - [Queues](/stack/queues) — Background processing infrastructure
@@ -0,0 +1,36 @@
1
+ # Webhooks
2
+
3
+ Quickback supports both inbound and outbound webhooks for integrating with external services. Inbound webhooks receive events from providers like Stripe, while outbound webhooks notify your users' integrations when data changes.
4
+
5
+ ## Enabling Webhooks
6
+
7
+ Set `webhooksBinding` in your database provider config:
8
+
9
+ ```typescript
10
+ database: defineDatabase("cloudflare-d1", {
11
+ binding: "DB",
12
+ webhooksBinding: "WEBHOOKS_DB",
13
+ })
14
+ ```
15
+
16
+ This generates:
17
+ - Webhook database schema (3 tables: events, endpoints, deliveries)
18
+ - Inbound endpoint at `POST /webhooks/v1/inbound/:provider`
19
+ - Outbound endpoint management API at `/webhooks/v1/endpoints`
20
+ - Queue consumer for async delivery with retry
21
+ - HMAC-SHA256 payload signing (Stripe-compatible format)
22
+
23
+ ## Infrastructure
24
+
25
+ Webhooks use a Cloudflare Queue for reliable async processing:
26
+
27
+ | Component | Binding | Purpose |
28
+ |-----------|---------|---------|
29
+ | Queue | `WEBHOOKS_QUEUE` | Process inbound events and deliver outbound webhooks |
30
+ | Dead letter queue | `WEBHOOKS_DLQ` | Capture failed deliveries after max retries |
31
+ | Database | `WEBHOOKS_DB` | Store events, endpoints, and delivery records |
32
+
33
+ ## Pages
34
+
35
+ - [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from Stripe, Paddle, GitHub, etc.
36
+ - [Outbound Webhooks](/stack/webhooks/outbound) — Send signed webhooks when data changes