@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,323 @@
|
|
|
1
|
+
# Actions API
|
|
2
|
+
|
|
3
|
+
Actions provide custom endpoints beyond CRUD operations. They support input validation, access conditions, and multiple response types including streaming.
|
|
4
|
+
|
|
5
|
+
## Record-Based Actions
|
|
6
|
+
|
|
7
|
+
Record-based actions operate on a specific record identified by ID.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
POST /api/v1/{resource}/:id/{action-name}
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
### Request
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# With JSON body
|
|
17
|
+
curl -X POST /api/v1/applications/app_123/advance-stage \
|
|
18
|
+
-H "Authorization: Bearer <token>" \
|
|
19
|
+
-H "Content-Type: application/json" \
|
|
20
|
+
-d '{ "notes": "Strong technical interview, moving to offer stage" }'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The action's input schema validates the request body using Zod. Invalid input returns a 400 error.
|
|
24
|
+
|
|
25
|
+
### Response
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"success": true,
|
|
30
|
+
"data": {
|
|
31
|
+
"id": "app_123",
|
|
32
|
+
"stage": "offer",
|
|
33
|
+
"previousStage": "interview",
|
|
34
|
+
"notes": "Strong technical interview, moving to offer stage"
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Security Flow
|
|
40
|
+
|
|
41
|
+
1. **Authentication** — User must be logged in (401 if not)
|
|
42
|
+
2. **Firewall** — Record must exist and be accessible to the user (404 if not found or not owned)
|
|
43
|
+
3. **Access** — User must have the required role (403 if insufficient)
|
|
44
|
+
4. **Input validation** — Request body validated against the action's Zod schema (400 if invalid)
|
|
45
|
+
5. **Access conditions** — Record must match access conditions (400 if not met)
|
|
46
|
+
6. **Masking** — Applied to the response data
|
|
47
|
+
|
|
48
|
+
### Access Conditions
|
|
49
|
+
|
|
50
|
+
Actions can require the record to be in a specific state:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
// In actions.ts
|
|
54
|
+
reject: {
|
|
55
|
+
access: {
|
|
56
|
+
roles: ["owner", "hiring-manager", "recruiter"],
|
|
57
|
+
record: { stage: { notEquals: "rejected" } },
|
|
58
|
+
},
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
If the record doesn't match (`stage` is already `rejected`), the action returns 400.
|
|
63
|
+
|
|
64
|
+
## Standalone Actions
|
|
65
|
+
|
|
66
|
+
Standalone actions don't require a record ID. They're for operations that aren't tied to a specific record.
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
POST /api/v1/{resource}/{action-name}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Request
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
curl -X POST /api/v1/candidates/bulk-import \
|
|
76
|
+
-H "Authorization: Bearer <token>" \
|
|
77
|
+
-H "Content-Type: application/json" \
|
|
78
|
+
-d '{ "source": "LinkedIn", "candidates": [{"name": "Alice Johnson", "email": "alice@example.com"}, {"name": "Bob Martinez", "email": "bob@example.com"}] }'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Response
|
|
82
|
+
|
|
83
|
+
Same format as record-based actions. The difference is no record lookup or firewall check.
|
|
84
|
+
|
|
85
|
+
### Security Flow
|
|
86
|
+
|
|
87
|
+
1. **Authentication** — Required (401)
|
|
88
|
+
2. **Organization check** — For org-scoped resources, user must have an active organization (403)
|
|
89
|
+
3. **Access** — Role-based check (403)
|
|
90
|
+
4. **Scoped DB** — The `db` passed to the handler is auto-scoped based on table columns (org isolation, owner filtering, soft delete)
|
|
91
|
+
5. **Input validation** — Zod schema validation (400)
|
|
92
|
+
|
|
93
|
+
### Scoped Database
|
|
94
|
+
|
|
95
|
+
All actions (both standalone and record-based) receive a **scoped `db`** instance that automatically enforces security based on the table's columns:
|
|
96
|
+
|
|
97
|
+
- Tables with `organizationId` — org isolation (`WHERE organizationId = ?`)
|
|
98
|
+
- Tables with `ownerId` — owner isolation (`WHERE ownerId = ?`)
|
|
99
|
+
- Tables with `deletedAt` — soft delete filter (`WHERE deletedAt IS NULL`)
|
|
100
|
+
- `INSERT` operations auto-inject `organizationId` and `ownerId` from context
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
// Your handler receives a scoped db — no manual filtering needed
|
|
104
|
+
execute: async ({ db, ctx, input }) => {
|
|
105
|
+
// This query automatically includes WHERE organizationId = ? AND ownerId = ? AND deletedAt IS NULL
|
|
106
|
+
const items = await db.select().from(applications).where(eq(applications.stage, 'interview'));
|
|
107
|
+
|
|
108
|
+
// Inserts automatically include organizationId and ownerId
|
|
109
|
+
await db.insert(applications).values({ candidateId: input.candidateId, jobId: input.jobId, stage: 'applied' });
|
|
110
|
+
|
|
111
|
+
return items;
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If you need unscoped access (for example, audited platform admin operations), declare `unsafe` on the action:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
adminReport: {
|
|
119
|
+
unsafe: {
|
|
120
|
+
reason: 'Platform support report',
|
|
121
|
+
adminOnly: true,
|
|
122
|
+
crossTenant: true,
|
|
123
|
+
targetScope: 'all',
|
|
124
|
+
},
|
|
125
|
+
execute: async ({ db, unsafeDb, ctx, input }) => {
|
|
126
|
+
// unsafeDb bypasses scoped filters
|
|
127
|
+
const allOrgs = await unsafeDb.select().from(applications);
|
|
128
|
+
return allOrgs;
|
|
129
|
+
},
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Cross-tenant unsafe actions are generated with:
|
|
134
|
+
|
|
135
|
+
- Better Auth authentication required
|
|
136
|
+
- platform admin gate (`ctx.userRole === 'admin'`)
|
|
137
|
+
- mandatory audit logging on denial/success/error
|
|
138
|
+
|
|
139
|
+
Without unsafe mode, `unsafeDb` is `undefined`.
|
|
140
|
+
|
|
141
|
+
Raw SQL in action code is blocked by default at compile time. If you need it for a specific action, set `allowRawSql: true` on that action explicitly.
|
|
142
|
+
|
|
143
|
+
### Explicit scope with `unsafeDb.scopeTo`
|
|
144
|
+
|
|
145
|
+
Unsafe handlers often need to derive the tenant from somewhere other than the ambient request context — an inbound webhook reads it from a mailbox record, a cron job iterates over every organization, a background worker acts on behalf of a specific user. `unsafeDb.scopeTo({ organizationId?, userId?, teamId? })` returns a scoped db that applies the firewall with your explicit scope instead of `ctx`:
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
// Inbound mail webhook — PUBLIC + unsafe:true
|
|
149
|
+
ingestInbound: {
|
|
150
|
+
standalone: true,
|
|
151
|
+
access: { roles: ['PUBLIC'] },
|
|
152
|
+
unsafe: {
|
|
153
|
+
reason: 'Inbound mail webhook — tenant derived from mailbox record',
|
|
154
|
+
targetScope: 'organization',
|
|
155
|
+
},
|
|
156
|
+
input: z.object({ mailboxId: z.string(), body: z.string() }),
|
|
157
|
+
execute: async ({ unsafeDb, input }) => {
|
|
158
|
+
// Look up the mailbox without a tenant in ctx (unsafe handler, unscoped client)
|
|
159
|
+
const [mailbox] = await unsafeDb.select().from(mailboxes)
|
|
160
|
+
.where(eq(mailboxes.id, input.mailboxId));
|
|
161
|
+
if (!mailbox) return { ok: false };
|
|
162
|
+
|
|
163
|
+
// Pin scope to the mailbox's organization — every downstream query gets
|
|
164
|
+
// WHERE organizationId = mailbox.organizationId, inserts get it injected.
|
|
165
|
+
const db = unsafeDb.scopeTo({ organizationId: mailbox.organizationId });
|
|
166
|
+
await db.insert(messages).values({ mailboxId: mailbox.id, body: input.body });
|
|
167
|
+
return { ok: true };
|
|
168
|
+
},
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Why this is safer than hand-rolling `organizationId` on every query:
|
|
173
|
+
|
|
174
|
+
- The firewall still runs. `scopeTo` just tells it which scope to use.
|
|
175
|
+
- `insert().values()` auto-injects `organizationId` / `ownerId` / `teamId` per the scope.
|
|
176
|
+
- Soft-delete and team-isolation filters continue to apply unchanged.
|
|
177
|
+
- No chance of forgetting a `WHERE organizationId = ?` clause on a single query.
|
|
178
|
+
|
|
179
|
+
`x-unsafe: true` is emitted on each unsafe operation in `openapi.json`, and MCP tool lists prefix the description with `[UNSAFE]` and set `annotations.destructiveHint` so agents and reviewers can see at a glance which endpoints cross trust boundaries.
|
|
180
|
+
|
|
181
|
+
## Input Validation
|
|
182
|
+
|
|
183
|
+
Actions use Zod schemas for input validation. The schema is defined in your `actions.ts` file:
|
|
184
|
+
|
|
185
|
+
```typescript
|
|
186
|
+
import { z } from "zod";
|
|
187
|
+
import { defineActions } from "@quickback/compiler";
|
|
188
|
+
|
|
189
|
+
export default defineActions("applications", {
|
|
190
|
+
"advance-stage": {
|
|
191
|
+
type: "record",
|
|
192
|
+
input: z.object({
|
|
193
|
+
notes: z.string().optional(),
|
|
194
|
+
}),
|
|
195
|
+
access: {
|
|
196
|
+
roles: ["hiring-manager", "recruiter"],
|
|
197
|
+
record: { stage: { notEquals: "hired" } },
|
|
198
|
+
},
|
|
199
|
+
},
|
|
200
|
+
reject: {
|
|
201
|
+
type: "record",
|
|
202
|
+
input: z.object({
|
|
203
|
+
reason: z.string().min(1),
|
|
204
|
+
}),
|
|
205
|
+
access: {
|
|
206
|
+
roles: ["hiring-manager", "recruiter"],
|
|
207
|
+
record: { stage: { notEquals: "rejected" } },
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
});
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
When validation fails:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"error": "Validation failed",
|
|
218
|
+
"layer": "guards",
|
|
219
|
+
"code": "GUARD_VALIDATION_FAILED",
|
|
220
|
+
"details": {
|
|
221
|
+
"issues": [
|
|
222
|
+
{ "path": ["reason"], "message": "String must contain at least 1 character(s)" }
|
|
223
|
+
]
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## Response Types
|
|
229
|
+
|
|
230
|
+
Actions support three response types:
|
|
231
|
+
|
|
232
|
+
### JSON (Default)
|
|
233
|
+
|
|
234
|
+
Returns a JSON object wrapped in `{ success: true, data: ... }`. Masking is applied to the data.
|
|
235
|
+
|
|
236
|
+
### Streaming
|
|
237
|
+
|
|
238
|
+
For long-running operations, actions can return a streaming response:
|
|
239
|
+
|
|
240
|
+
```typescript
|
|
241
|
+
generateReport: {
|
|
242
|
+
type: "standalone",
|
|
243
|
+
responseType: "stream",
|
|
244
|
+
// ...
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The action handler returns a `ReadableStream` directly — no JSON wrapper.
|
|
249
|
+
|
|
250
|
+
### File
|
|
251
|
+
|
|
252
|
+
For file downloads, actions can return a raw `Response` object:
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
exportCsv: {
|
|
256
|
+
type: "record",
|
|
257
|
+
responseType: "file",
|
|
258
|
+
// ...
|
|
259
|
+
}
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## Action Handler
|
|
263
|
+
|
|
264
|
+
The compiler generates a handler skeleton. Your action receives:
|
|
265
|
+
|
|
266
|
+
```typescript
|
|
267
|
+
{
|
|
268
|
+
db, // Scoped database (auto-enforces org/owner/soft-delete filters)
|
|
269
|
+
unsafeDb, // Raw database (only available when unsafe mode is enabled)
|
|
270
|
+
ctx, // Auth context (user, session, org)
|
|
271
|
+
record, // The existing record (record-based only, undefined for standalone)
|
|
272
|
+
input, // Validated input from Zod schema
|
|
273
|
+
services, // Injected services
|
|
274
|
+
c, // Hono context
|
|
275
|
+
env, // Runtime bindings (Cloudflare env / process env). Alias for c.env.
|
|
276
|
+
}
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
## HTTP Methods
|
|
280
|
+
|
|
281
|
+
Actions default to `POST` but can use any HTTP method:
|
|
282
|
+
|
|
283
|
+
```typescript
|
|
284
|
+
getStatus: {
|
|
285
|
+
type: "record",
|
|
286
|
+
method: "GET",
|
|
287
|
+
// GET actions receive input from query parameters instead of body
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
When using `GET`, input is parsed from query parameters instead of the request body.
|
|
292
|
+
|
|
293
|
+
## Cascading Soft Delete
|
|
294
|
+
|
|
295
|
+
When soft-deleting a parent record, Quickback automatically soft-deletes related records in child/junction tables **within the same feature**. The compiler detects foreign key references at build time.
|
|
296
|
+
|
|
297
|
+
For example, if your feature has `jobs` and `applications` tables where `applications` has a `.references(() => jobs.id)`, deleting a job will also soft-delete all its applications:
|
|
298
|
+
|
|
299
|
+
```
|
|
300
|
+
DELETE /api/v1/jobs/job_123
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Generated code:
|
|
304
|
+
```typescript
|
|
305
|
+
// Soft delete parent
|
|
306
|
+
await db.update(jobs).set({ deletedAt: now, modifiedAt: now })
|
|
307
|
+
.where(and(buildFirewallConditions(ctx), eq(jobs.id, id)));
|
|
308
|
+
|
|
309
|
+
// Cascade soft delete to child tables
|
|
310
|
+
await db.update(applications).set({ deletedAt: now, modifiedAt: now })
|
|
311
|
+
.where(eq(applications.jobId, id));
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
**Cascade rules:**
|
|
315
|
+
- **Soft delete (default)**: Application-level cascade via generated UPDATE statements
|
|
316
|
+
- **Hard delete (`mode: 'hard'`)**: No compiler cascade — relies on DB-level `ON DELETE CASCADE`
|
|
317
|
+
- **Cross-feature**: No cascade — only within the same feature's tables
|
|
318
|
+
|
|
319
|
+
## See Also
|
|
320
|
+
|
|
321
|
+
- [Defining Actions](/compiler/definitions/actions) — How to define actions in your feature
|
|
322
|
+
- [Guards](/compiler/definitions/guards) — Guard conditions reference
|
|
323
|
+
- [Error Responses](/compiler/targets/hono-api/using-the-api/errors) — Error format reference
|
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
# Batch Operations
|
|
2
|
+
|
|
3
|
+
Batch operations let you create, update, or delete multiple records in a single request. They are **auto-enabled** when the corresponding CRUD operation exists in your definition.
|
|
4
|
+
|
|
5
|
+
## Available Endpoints
|
|
6
|
+
|
|
7
|
+
| Endpoint | Method | Auto-enabled When |
|
|
8
|
+
|----------|--------|-------------------|
|
|
9
|
+
| `/{resource}/batch` | `POST` | `crud.create` exists |
|
|
10
|
+
| `/{resource}/batch` | `PATCH` | `crud.update` exists |
|
|
11
|
+
| `/{resource}/batch` | `DELETE` | `crud.delete` exists |
|
|
12
|
+
| `/{resource}/batch` | `PUT` | `crud.put` exists |
|
|
13
|
+
|
|
14
|
+
To disable a batch operation, set it to `false` in your definition:
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
crud: {
|
|
18
|
+
create: { access: { roles: ['hiring-manager'] } },
|
|
19
|
+
batchCreate: false, // Disable batch create
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Batch Create
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
POST /api/v1/{resource}/batch
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Request
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"records": [
|
|
34
|
+
{ "candidateId": "cand_101", "jobId": "job_201", "stage": "applied", "notes": "Strong frontend background" },
|
|
35
|
+
{ "candidateId": "cand_101", "jobId": "job_202", "stage": "applied", "notes": "Also interested in backend role" },
|
|
36
|
+
{ "candidateId": "cand_102", "jobId": "job_201", "stage": "applied", "notes": "Referred by employee" }
|
|
37
|
+
],
|
|
38
|
+
"options": {
|
|
39
|
+
"failFast": false
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Response (201 or 207)
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"success": [
|
|
49
|
+
{ "id": "app_abc1", "candidateId": "cand_101", "jobId": "job_201", "stage": "applied", "createdAt": "2025-01-15T10:00:00Z" },
|
|
50
|
+
{ "id": "app_abc3", "candidateId": "cand_102", "jobId": "job_201", "stage": "applied", "createdAt": "2025-01-15T10:00:00Z" }
|
|
51
|
+
],
|
|
52
|
+
"errors": [
|
|
53
|
+
{
|
|
54
|
+
"index": 1,
|
|
55
|
+
"record": { "candidateId": "cand_101", "jobId": "job_202", "stage": "applied", "notes": "Also interested in backend role" },
|
|
56
|
+
"error": {
|
|
57
|
+
"error": "Database insert failed",
|
|
58
|
+
"layer": "validation",
|
|
59
|
+
"code": "INSERT_FAILED",
|
|
60
|
+
"details": { "reason": "UNIQUE constraint failed: applications.candidateId, applications.jobId" }
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
],
|
|
64
|
+
"meta": {
|
|
65
|
+
"total": 3,
|
|
66
|
+
"succeeded": 2,
|
|
67
|
+
"failed": 1,
|
|
68
|
+
"failFast": false,
|
|
69
|
+
"transactional": true
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- **201** — All records created successfully
|
|
75
|
+
- **207** — Partial success (some errors, some successes)
|
|
76
|
+
|
|
77
|
+
`POST /batch` uses a single bulk `INSERT`, so `meta.transactional` is `true` on every provider — the database guarantees the insert is atomic regardless of the `failFast` flag.
|
|
78
|
+
|
|
79
|
+
Fields applied automatically to each record:
|
|
80
|
+
- ID generation (UUID, prefixed, etc.)
|
|
81
|
+
- Ownership fields (`organizationId`, `ownerId`, `createdBy`)
|
|
82
|
+
- Audit fields (`createdAt`, `modifiedAt`)
|
|
83
|
+
- Default values and computed fields
|
|
84
|
+
|
|
85
|
+
## Batch Update
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
PATCH /api/v1/{resource}/batch
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Every record **must include an `id` field**.
|
|
92
|
+
|
|
93
|
+
### Request
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"records": [
|
|
98
|
+
{ "id": "app_abc1", "notes": "Passed phone screen, schedule onsite" },
|
|
99
|
+
{ "id": "app_abc2", "notes": "Moved to technical interview round" },
|
|
100
|
+
{ "id": "app_xyz9", "notes": "Hiring manager approved offer" }
|
|
101
|
+
],
|
|
102
|
+
"options": {
|
|
103
|
+
"failFast": false
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Response (200 or 207)
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"success": [
|
|
113
|
+
{ "id": "app_abc1", "notes": "Passed phone screen, schedule onsite", "modifiedAt": "2025-01-15T11:00:00Z" },
|
|
114
|
+
{ "id": "app_abc2", "notes": "Moved to technical interview round", "modifiedAt": "2025-01-15T11:00:00Z" }
|
|
115
|
+
],
|
|
116
|
+
"errors": [
|
|
117
|
+
{
|
|
118
|
+
"index": 2,
|
|
119
|
+
"record": { "id": "app_xyz9", "notes": "Hiring manager approved offer" },
|
|
120
|
+
"error": {
|
|
121
|
+
"error": "Not found",
|
|
122
|
+
"layer": "firewall",
|
|
123
|
+
"code": "NOT_FOUND",
|
|
124
|
+
"details": { "id": "app_xyz9" }
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
],
|
|
128
|
+
"meta": {
|
|
129
|
+
"total": 3,
|
|
130
|
+
"succeeded": 2,
|
|
131
|
+
"failed": 1,
|
|
132
|
+
"failFast": false,
|
|
133
|
+
"transactional": false
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Records that don't exist or aren't accessible through the firewall return a `NOT_FOUND` error. Guard rules (immutable, protected, not-updatable fields) are checked per record.
|
|
139
|
+
|
|
140
|
+
### Missing IDs
|
|
141
|
+
|
|
142
|
+
If any records are missing the `id` field, the entire request is rejected:
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"error": "Records missing required ID field",
|
|
147
|
+
"layer": "validation",
|
|
148
|
+
"code": "BATCH_MISSING_IDS",
|
|
149
|
+
"details": { "indices": [0, 2] },
|
|
150
|
+
"hint": "All records must include an ID field for batch update."
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Batch Delete
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
DELETE /api/v1/{resource}/batch
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Request
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"ids": ["app_abc1", "app_abc2", "app_abc3"],
|
|
165
|
+
"options": {
|
|
166
|
+
"failFast": false
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Note: Batch delete uses an `ids` array (not `records`).
|
|
172
|
+
|
|
173
|
+
### Response (200 or 207)
|
|
174
|
+
|
|
175
|
+
**Soft delete** (default):
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"success": [
|
|
180
|
+
{ "id": "app_abc1", "candidateId": "cand_101", "deletedAt": "2025-01-15T12:00:00Z" },
|
|
181
|
+
{ "id": "app_abc2", "candidateId": "cand_103", "deletedAt": "2025-01-15T12:00:00Z" }
|
|
182
|
+
],
|
|
183
|
+
"errors": [],
|
|
184
|
+
"meta": {
|
|
185
|
+
"total": 2,
|
|
186
|
+
"succeeded": 2,
|
|
187
|
+
"failed": 0,
|
|
188
|
+
"failFast": false,
|
|
189
|
+
"transactional": true
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`DELETE /batch` issues a single bulk `UPDATE … WHERE id IN (...)` (soft delete) or `DELETE … WHERE id IN (...)` (hard delete), so `meta.transactional` is `true` on every provider regardless of `failFast`.
|
|
195
|
+
|
|
196
|
+
**Hard delete**: Returns objects with only the `id` field (record data is deleted).
|
|
197
|
+
|
|
198
|
+
## Batch Upsert
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
PUT /api/v1/{resource}/batch
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Inserts new records or updates existing ones. Every record must include an `id` field.
|
|
205
|
+
|
|
206
|
+
**Note:** Batch upsert is only available when `generateId` is set to `false` (user-provided IDs) in your configuration.
|
|
207
|
+
|
|
208
|
+
### Request
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
{
|
|
212
|
+
"records": [
|
|
213
|
+
{ "id": "app_001", "candidateId": "cand_101", "jobId": "job_201", "stage": "screening", "notes": "Updated after phone screen" },
|
|
214
|
+
{ "id": "app_002", "candidateId": "cand_104", "jobId": "job_203", "stage": "applied", "notes": "New application from referral" }
|
|
215
|
+
],
|
|
216
|
+
"options": {
|
|
217
|
+
"failFast": false
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Response (201 or 207)
|
|
223
|
+
|
|
224
|
+
The compiler checks which IDs already exist and splits the batch into creates and updates. Create records get ownership and default fields; update records get only `modifiedAt`. Under `failFast: true`, both the bulk insert and the per-record updates run inside the same transaction — a failed update rolls back the inserts too on tx-supporting providers.
|
|
225
|
+
|
|
226
|
+
## Fail-Fast Mode
|
|
227
|
+
|
|
228
|
+
By default, batch operations use **partial success** mode — each record is processed independently, and failures don't affect other records.
|
|
229
|
+
|
|
230
|
+
Set `"failFast": true` to stop on the first error:
|
|
231
|
+
|
|
232
|
+
```json
|
|
233
|
+
{
|
|
234
|
+
"records": [...],
|
|
235
|
+
"options": {
|
|
236
|
+
"failFast": true
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Fail-Fast Failure Response (400)
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"error": "Batch failed at index 1",
|
|
246
|
+
"layer": "validation",
|
|
247
|
+
"code": "BATCH_FAILFAST_STOPPED",
|
|
248
|
+
"details": {
|
|
249
|
+
"failedAt": 1,
|
|
250
|
+
"reason": "Database insert failed",
|
|
251
|
+
"errorDetails": { "reason": "UNIQUE constraint failed" }
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Transactional Semantics
|
|
257
|
+
|
|
258
|
+
The behavior of `failFast: true` depends on whether your database provider
|
|
259
|
+
supports transactions. The response's `meta.transactional` flag tells you
|
|
260
|
+
which guarantee you actually got — inspect it in clients that care about
|
|
261
|
+
rollback.
|
|
262
|
+
|
|
263
|
+
### Per-Provider Matrix
|
|
264
|
+
|
|
265
|
+
| Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
|
|
266
|
+
|----------|----------|-----------|----------------------|----------|
|
|
267
|
+
| `PATCH /batch` (update) | postgres / supabase / neon / libsql / better-sqlite3 / bun-sqlite | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
|
|
268
|
+
| `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
|
|
269
|
+
| `PATCH /batch` (update) | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — D1 has no `db.transaction`. Records before the failure stay committed. |
|
|
270
|
+
| `PUT /batch` (upsert) | tx-supporting | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
|
|
271
|
+
| `PUT /batch` (upsert) | cloudflare-d1 | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
|
|
272
|
+
| `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
|
|
273
|
+
| `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
|
|
274
|
+
|
|
275
|
+
### Reading `meta.transactional` in clients
|
|
276
|
+
|
|
277
|
+
```typescript
|
|
278
|
+
const res = await fetch('/api/v1/jobs/batch', {
|
|
279
|
+
method: 'PATCH',
|
|
280
|
+
body: JSON.stringify({ records, options: { failFast: true } }),
|
|
281
|
+
});
|
|
282
|
+
const body = await res.json();
|
|
283
|
+
|
|
284
|
+
if (!body.meta.transactional && body.errors.length > 0) {
|
|
285
|
+
// Some records succeeded before the failure and remain committed.
|
|
286
|
+
// Compensate via the success array if needed.
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
### Embeddings and Realtime
|
|
291
|
+
|
|
292
|
+
When a resource has `embeddings` or `realtime` configured, queue messages
|
|
293
|
+
and broadcasts are emitted **after** the transaction commits. A
|
|
294
|
+
rolled-back batch produces no orphan embedding jobs.
|
|
295
|
+
|
|
296
|
+
## Batch Size Limit
|
|
297
|
+
|
|
298
|
+
The default maximum batch size is **100 records**. Requests exceeding the limit are rejected:
|
|
299
|
+
|
|
300
|
+
```json
|
|
301
|
+
{
|
|
302
|
+
"error": "Batch size limit exceeded",
|
|
303
|
+
"layer": "validation",
|
|
304
|
+
"code": "BATCH_SIZE_EXCEEDED",
|
|
305
|
+
"details": { "max": 100, "actual": 250 },
|
|
306
|
+
"hint": "Maximum 100 records allowed per batch. Split into multiple requests."
|
|
307
|
+
}
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
## Configuration
|
|
311
|
+
|
|
312
|
+
Batch operations inherit access control from their corresponding CRUD operation. You can override per-batch settings:
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
export default defineTable(applications, {
|
|
316
|
+
crud: {
|
|
317
|
+
create: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
318
|
+
update: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
319
|
+
delete: { access: { roles: ['hiring-manager'] }, mode: 'soft' },
|
|
320
|
+
|
|
321
|
+
// Override batch-specific settings
|
|
322
|
+
batchCreate: {
|
|
323
|
+
access: { roles: ['hiring-manager'] }, // More restrictive than single create
|
|
324
|
+
maxBatchSize: 50, // Default: 100
|
|
325
|
+
allowFailFast: true, // Default: true
|
|
326
|
+
},
|
|
327
|
+
batchUpdate: {
|
|
328
|
+
maxBatchSize: 100,
|
|
329
|
+
allowFailFast: true,
|
|
330
|
+
},
|
|
331
|
+
batchDelete: {
|
|
332
|
+
access: { roles: ['hiring-manager'] },
|
|
333
|
+
maxBatchSize: 100,
|
|
334
|
+
allowFailFast: true,
|
|
335
|
+
},
|
|
336
|
+
|
|
337
|
+
// Disable a batch operation entirely
|
|
338
|
+
batchUpsert: false,
|
|
339
|
+
},
|
|
340
|
+
});
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
## Security
|
|
344
|
+
|
|
345
|
+
All security pillars apply to batch operations:
|
|
346
|
+
|
|
347
|
+
1. **Authentication** — Required for all batch endpoints (401 if missing)
|
|
348
|
+
2. **Firewall** — Applied per-record for update/delete/upsert (not applicable to create)
|
|
349
|
+
3. **Access** — Role-based check using the batch operation's access config
|
|
350
|
+
4. **Guards** — Per-record validation (createable/updatable/immutable fields)
|
|
351
|
+
5. **Masking** — Applied to all records in the success array before response
|
|
352
|
+
|
|
353
|
+
## See Also
|
|
354
|
+
|
|
355
|
+
- [CRUD Endpoints](/compiler/targets/hono-api/using-the-api/crud) — Single-record operations
|
|
356
|
+
- [Error Responses](/compiler/targets/hono-api/using-the-api/errors) — Error format reference
|
|
357
|
+
- [Guards](/compiler/definitions/guards) — Field-level write protection
|