@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1192 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +67 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1192 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +228 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +67 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- 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
|