@quickback-dev/cli 0.10.15 → 0.10.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,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