@quickback-dev/cli 0.10.16 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (253) 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.d.ts.map +1 -1
  5. package/dist/docs/content.js +15 -10
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/skill/SKILL.md +142 -1051
  10. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  11. package/dist/skill/docs/changelog.md +1225 -0
  12. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  17. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  18. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  19. package/dist/skill/docs/compiler/config/agents.md +144 -0
  20. package/dist/skill/docs/compiler/config/auth.md +109 -0
  21. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  22. package/dist/skill/docs/compiler/config/domains.md +149 -0
  23. package/dist/skill/docs/compiler/config/index.md +419 -0
  24. package/dist/skill/docs/compiler/config/output.md +338 -0
  25. package/dist/skill/docs/compiler/config/providers.md +248 -0
  26. package/dist/skill/docs/compiler/config/security.md +255 -0
  27. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  28. package/dist/skill/docs/compiler/config/variables.md +157 -0
  29. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  30. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  31. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  32. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  33. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  34. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  36. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  37. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  38. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  39. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  40. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  41. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  42. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  43. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  44. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  45. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  46. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  47. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  48. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  49. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  50. package/dist/skill/docs/compiler/index.md +85 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  66. package/dist/skill/docs/compiler/targets/index.md +47 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  69. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  70. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  71. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  72. package/dist/skill/docs/index.md +77 -0
  73. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  74. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  75. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  76. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  77. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  78. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  79. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  80. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  81. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  82. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  83. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  84. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  85. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  86. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  87. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  88. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  89. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  90. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  91. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  92. package/dist/skill/docs/stack/auth/index.md +64 -0
  93. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  94. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  95. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  96. package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
  97. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  98. package/dist/skill/docs/stack/auth/security.md +455 -0
  99. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  100. package/dist/skill/docs/stack/cms/actions.md +199 -0
  101. package/dist/skill/docs/stack/cms/components.md +479 -0
  102. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  103. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  104. package/dist/skill/docs/stack/cms/index.md +158 -0
  105. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  106. package/dist/skill/docs/stack/cms/pages.md +275 -0
  107. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  108. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  109. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  110. package/dist/skill/docs/stack/cms/security.md +203 -0
  111. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  112. package/dist/skill/docs/stack/index.md +65 -0
  113. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  114. package/dist/skill/docs/stack/queues/index.md +56 -0
  115. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  116. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  117. package/dist/skill/docs/stack/realtime/index.md +73 -0
  118. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  119. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  120. package/dist/skill/docs/stack/storage/index.md +17 -0
  121. package/dist/skill/docs/stack/storage/kv.md +204 -0
  122. package/dist/skill/docs/stack/storage/r2.md +232 -0
  123. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  124. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  125. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  126. package/dist/skill/docs/stack/vector/index.md +44 -0
  127. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  128. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  129. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  130. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  131. package/package.json +1 -1
  132. package/src/skill/SKILL.md +142 -1051
  133. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  134. package/src/skill/docs/changelog.md +1225 -0
  135. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  136. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  137. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  138. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  139. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  140. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  141. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  142. package/src/skill/docs/compiler/config/agents.md +144 -0
  143. package/src/skill/docs/compiler/config/auth.md +109 -0
  144. package/src/skill/docs/compiler/config/bindings.md +176 -0
  145. package/src/skill/docs/compiler/config/domains.md +149 -0
  146. package/src/skill/docs/compiler/config/index.md +419 -0
  147. package/src/skill/docs/compiler/config/output.md +338 -0
  148. package/src/skill/docs/compiler/config/providers.md +248 -0
  149. package/src/skill/docs/compiler/config/security.md +255 -0
  150. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  151. package/src/skill/docs/compiler/config/variables.md +157 -0
  152. package/src/skill/docs/compiler/definitions/access.md +445 -0
  153. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  154. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  155. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  156. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  157. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  158. package/src/skill/docs/compiler/definitions/index.md +219 -0
  159. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  160. package/src/skill/docs/compiler/definitions/read.md +220 -0
  161. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  162. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  163. package/src/skill/docs/compiler/definitions/views.md +292 -0
  164. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  165. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  166. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  167. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  168. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  169. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  170. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  171. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  172. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  173. package/src/skill/docs/compiler/index.md +85 -0
  174. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  176. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  177. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  178. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  179. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  186. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  187. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  188. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  189. package/src/skill/docs/compiler/targets/index.md +47 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  191. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  192. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  193. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  194. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  195. package/src/skill/docs/index.md +77 -0
  196. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  197. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  198. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  199. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  200. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  201. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  202. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  203. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  204. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  205. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  206. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  207. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  208. package/src/skill/docs/stack/account-ui/index.md +147 -0
  209. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  210. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  211. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  212. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  213. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  214. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  215. package/src/skill/docs/stack/auth/index.md +64 -0
  216. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  217. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  218. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  219. package/src/skill/docs/stack/auth/plugins/index.md +340 -0
  220. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  221. package/src/skill/docs/stack/auth/security.md +455 -0
  222. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  223. package/src/skill/docs/stack/cms/actions.md +199 -0
  224. package/src/skill/docs/stack/cms/components.md +479 -0
  225. package/src/skill/docs/stack/cms/connecting.md +199 -0
  226. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  227. package/src/skill/docs/stack/cms/index.md +158 -0
  228. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  229. package/src/skill/docs/stack/cms/pages.md +275 -0
  230. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  231. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  232. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  233. package/src/skill/docs/stack/cms/security.md +203 -0
  234. package/src/skill/docs/stack/cms/table-views.md +142 -0
  235. package/src/skill/docs/stack/index.md +65 -0
  236. package/src/skill/docs/stack/queues/handlers.md +317 -0
  237. package/src/skill/docs/stack/queues/index.md +56 -0
  238. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  239. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  240. package/src/skill/docs/stack/realtime/index.md +73 -0
  241. package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  242. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  243. package/src/skill/docs/stack/storage/index.md +17 -0
  244. package/src/skill/docs/stack/storage/kv.md +204 -0
  245. package/src/skill/docs/stack/storage/r2.md +232 -0
  246. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  247. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  248. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  249. package/src/skill/docs/stack/vector/index.md +44 -0
  250. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  251. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  252. package/src/skill/docs/stack/webhooks/index.md +36 -0
  253. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -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
@@ -0,0 +1,281 @@
1
+ # Outbound Webhooks
2
+
3
+ Outbound webhooks notify external services when events happen in your API. Users register webhook endpoints, subscribe to event types, and receive signed HTTP POST requests when events are emitted.
4
+
5
+ ## Overview
6
+
7
+ Outbound webhooks are a multi-step system:
8
+
9
+ 1. **Users register endpoints** via the REST API
10
+ 2. **Your code emits events** using `emitWebhookEvent()`
11
+ 3. **Quickback queues deliveries** for each matching endpoint
12
+ 4. **The queue consumer delivers** with retry and exponential backoff
13
+ 5. **Payloads are signed** with HMAC-SHA256 (Stripe-compatible format)
14
+
15
+ ## Emitting Events
16
+
17
+ Call `emitWebhookEvent()` in your actions or custom routes:
18
+
19
+ ```typescript
20
+ import { emitWebhookEvent } from '../lib/webhooks/emit';
21
+
22
+ // After creating a user
23
+ const newUser = await db.insert(users).values(data).returning();
24
+
25
+ await emitWebhookEvent(
26
+ "user.created",
27
+ newUser[0],
28
+ { organizationId: ctx.activeOrgId },
29
+ env
30
+ );
31
+ ```
32
+
33
+ **Parameters:**
34
+
35
+ | Parameter | Type | Description |
36
+ |-----------|------|-------------|
37
+ | `eventType` | `string` | Event name (e.g., `user.created`) |
38
+ | `payload` | `unknown` | Event data (auto-wrapped with metadata) |
39
+ | `options` | `object` | `{ organizationId?, userId? }` — scope for endpoint matching |
40
+ | `env` | `CloudflareBindings` | Cloudflare environment bindings |
41
+
42
+ **Note:** The compiler does NOT auto-emit events after CRUD operations. You must call `emitWebhookEvent()` explicitly where you want webhooks triggered.
43
+
44
+ ## Event Types
45
+
46
+ Quickback provides recommended event naming conventions:
47
+
48
+ | Category | Events |
49
+ |----------|--------|
50
+ | User | `user.created`, `user.updated`, `user.deleted` |
51
+ | Subscription | `subscription.created`, `subscription.updated`, `subscription.cancelled`, `subscription.renewed` |
52
+ | Organization | `organization.created`, `organization.updated`, `organization.deleted`, `organization.member_added`, `organization.member_removed` |
53
+ | File | `file.uploaded`, `file.deleted` |
54
+
55
+ You can emit any custom event type — these are conventions, not restrictions.
56
+
57
+ ## Payload Format
58
+
59
+ The emitted payload is wrapped automatically:
60
+
61
+ ```json
62
+ {
63
+ "type": "user.created",
64
+ "data": {
65
+ "id": "usr_abc123",
66
+ "name": "Jane Doe",
67
+ "email": "jane@example.com"
68
+ },
69
+ "createdAt": "2025-01-15T10:00:00.000Z"
70
+ }
71
+ ```
72
+
73
+ ## Payload Signing
74
+
75
+ Every delivery is signed with HMAC-SHA256 using the endpoint's secret. The signature format is Stripe-compatible:
76
+
77
+ ```
78
+ X-Webhook-Signature: t=1705312800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
79
+ ```
80
+
81
+ **Signed payload:** `<timestamp>.<json_body>`
82
+
83
+ **Additional headers:**
84
+
85
+ | Header | Description |
86
+ |--------|-------------|
87
+ | `X-Webhook-Signature` | `t=<timestamp>,v1=<hmac>` |
88
+ | `X-Webhook-Event` | Event type (e.g., `user.created`) |
89
+ | `X-Webhook-Delivery` | Delivery ID for tracking |
90
+ | `Content-Type` | `application/json` |
91
+
92
+ ### Verifying Signatures (Consumer Side)
93
+
94
+ ```typescript
95
+ import { createHmac, timingSafeEqual } from 'crypto';
96
+
97
+ function verifyWebhook(payload: string, signature: string, secret: string): boolean {
98
+ const [tPart, v1Part] = signature.split(',');
99
+ const timestamp = tPart.replace('t=', '');
100
+ const expectedSig = v1Part.replace('v1=', '');
101
+
102
+ // Check timestamp (5 minute tolerance)
103
+ const age = Date.now() / 1000 - parseInt(timestamp);
104
+ if (age > 300) return false;
105
+
106
+ const signed = `${timestamp}.${payload}`;
107
+ const computed = createHmac('sha256', secret).update(signed).digest('hex');
108
+ return timingSafeEqual(Buffer.from(computed), Buffer.from(expectedSig));
109
+ }
110
+ ```
111
+
112
+ ## Endpoint Management API
113
+
114
+ ### Register an Endpoint
115
+
116
+ ```
117
+ POST /webhooks/v1/endpoints
118
+ ```
119
+
120
+ ```json
121
+ {
122
+ "name": "My Integration",
123
+ "url": "https://example.com/webhook",
124
+ "events": ["user.created", "subscription.*"]
125
+ }
126
+ ```
127
+
128
+ **Response (201):**
129
+
130
+ ```json
131
+ {
132
+ "id": "wep_abc123",
133
+ "name": "My Integration",
134
+ "url": "https://example.com/webhook",
135
+ "secret": "whsec_a1b2c3d4...",
136
+ "events": ["user.created", "subscription.*"],
137
+ "enabled": true,
138
+ "createdAt": "2025-01-15T10:00:00.000Z"
139
+ }
140
+ ```
141
+
142
+ The `secret` is only returned on creation. Store it securely.
143
+
144
+ ### Event Pattern Matching
145
+
146
+ Endpoints subscribe to events using patterns:
147
+
148
+ | Pattern | Matches |
149
+ |---------|---------|
150
+ | `user.created` | Exact match only |
151
+ | `user.*` | All user events |
152
+ | `*` | All events |
153
+
154
+ ### Other Endpoints
155
+
156
+ | Method | Path | Description |
157
+ |--------|------|-------------|
158
+ | `GET` | `/webhooks/v1/endpoints` | List your endpoints |
159
+ | `GET` | `/webhooks/v1/endpoints/:id` | Get endpoint details (secret masked) |
160
+ | `PATCH` | `/webhooks/v1/endpoints/:id` | Update endpoint (name, url, events, enabled) |
161
+ | `DELETE` | `/webhooks/v1/endpoints/:id` | Delete endpoint |
162
+ | `GET` | `/webhooks/v1/endpoints/:id/deliveries` | List delivery attempts |
163
+ | `POST` | `/webhooks/v1/endpoints/:id/test` | Send a test event |
164
+ | `POST` | `/webhooks/v1/endpoints/:id/rotate-secret` | Generate a new signing secret |
165
+ | `GET` | `/webhooks/v1/events` | List available event types |
166
+
167
+ ### Access Control
168
+
169
+ Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries.
170
+
171
+ ### URL Validation (anti-SSRF)
172
+
173
+ Registered URLs are validated at registration and again before each delivery attempt. The default policy rejects:
174
+
175
+ - Any scheme other than `https:` (matches Stripe, GitHub, and Slack webhook conventions)
176
+ - Loopback hosts (`localhost`, `127.0.0.1`, `::1`)
177
+ - Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`)
178
+ - RFC 1918 private ranges (`10/8`, `172.16/12`, `192.168/16`), `169.254/16`, and `0.0.0.0/8`
179
+ - Hosts ending in `.internal` or `.local`
180
+
181
+ Plaintext `http:` is rejected by default. To allow `http:` (e.g. for a self-hosted dev environment without TLS), set `webhookAllowInsecure: true` on the database provider config:
182
+
183
+ ```ts
184
+ // quickback.config.ts
185
+ providers: {
186
+ database: {
187
+ name: 'cloudflare-d1',
188
+ config: {
189
+ webhooksBinding: 'WEBHOOKS_DB',
190
+ webhookAllowInsecure: true, // dev/self-host only
191
+ },
192
+ },
193
+ }
194
+ ```
195
+
196
+ The other validation rules (private/loopback/metadata blocking) still apply when this flag is on.
197
+
198
+ ### Redirect Handling
199
+
200
+ Outbound delivery uses `redirect: "manual"` — the runtime refuses to follow 3xx responses. A redirect is treated as a **terminal** delivery failure (no retry), and the redirect target is recorded in the `responseBody`. This protects signed payloads from being bounced to a different host than the one the user registered.
201
+
202
+ If your endpoint legitimately needs to relocate, update the `url` on the endpoint record instead of relying on a 301/302.
203
+
204
+ ## Delivery and Retry
205
+
206
+ Deliveries are processed asynchronously via a Cloudflare Queue.
207
+
208
+ **Success:** HTTP 2xx response marks the delivery as `delivered`.
209
+
210
+ **Failure:** HTTP 4xx/5xx or network errors trigger retries with exponential backoff:
211
+
212
+ | Attempt | Delay |
213
+ |---------|-------|
214
+ | 1st retry | ~2 seconds |
215
+ | 2nd retry | ~4 seconds |
216
+ | 3rd retry (final) | ~8 seconds |
217
+
218
+ Maximum backoff is capped at 1 hour. After 3 failed attempts, the delivery is marked as `failed`.
219
+
220
+ **Disabled endpoints:** If an endpoint is disabled or deleted between emission and delivery, the delivery is marked as failed immediately.
221
+
222
+ ### Delivery Record
223
+
224
+ Each delivery attempt is tracked in the `webhook_deliveries` table:
225
+
226
+ | Field | Description |
227
+ |-------|-------------|
228
+ | `status` | `pending`, `delivered`, or `failed` |
229
+ | `attempts` | Number of delivery attempts |
230
+ | `responseStatus` | HTTP status from last attempt |
231
+ | `responseBody` | Response body (truncated to 1000 chars) |
232
+ | `lastAttemptAt` | Timestamp of last attempt |
233
+ | `nextRetryAt` | When the next retry will occur |
234
+
235
+ ## Infrastructure
236
+
237
+ ### Queue Configuration
238
+
239
+ Outbound webhooks use a dedicated Cloudflare Queue:
240
+
241
+ ```toml
242
+ # Auto-generated in wrangler.toml
243
+ [[queues.producers]]
244
+ queue = "my-app-webhooks-queue"
245
+ binding = "WEBHOOKS_QUEUE"
246
+
247
+ [[queues.consumers]]
248
+ queue = "my-app-webhooks-queue"
249
+ max_batch_size = 10
250
+ max_batch_timeout = 30
251
+ max_retries = 3
252
+ dead_letter_queue = "my-app-webhooks-dlq"
253
+ ```
254
+
255
+ ### Dead Letter Queue
256
+
257
+ Failed webhook deliveries (after all retries) are sent to a dead letter queue for investigation:
258
+
259
+ ```toml
260
+ [[queues.consumers]]
261
+ queue = "my-app-webhooks-dlq"
262
+ max_batch_size = 1
263
+ ```
264
+
265
+ ## Enabling Webhooks
266
+
267
+ Set `webhooksBinding` in your database provider config:
268
+
269
+ ```typescript
270
+ database: defineDatabase("cloudflare-d1", {
271
+ binding: "DB",
272
+ webhooksBinding: "WEBHOOKS_DB",
273
+ })
274
+ ```
275
+
276
+ This generates the webhook database schema, routes, queue consumer, and all supporting code.
277
+
278
+ ## See Also
279
+
280
+ - [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from external services
281
+ - [Queues](/stack/queues) — Background processing infrastructure