@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,652 @@
1
+ # CRUD Endpoints
2
+
3
+ Quickback automatically generates RESTful CRUD endpoints for each resource you define. This page covers the write side (create, update, delete, upsert) and lists collection-read endpoints. Read-side configuration lives under [`read:`](/compiler/definitions/read).
4
+
5
+ > **Migration note**: `crud.list` and `crud.get` are rejected at compile time in DSL v2. List-level access moves to [`read.access`](/compiler/definitions/read), and per-field projections move to named views under [`read.views`](/compiler/definitions/read#views-under-read-views). See the [migration table](/compiler/definitions/read#migrating-from-crud-list-crud-get).
6
+
7
+ ## Quick Reference
8
+
9
+ All endpoints require authentication. Include your session cookie or Bearer token:
10
+
11
+ ```bash
12
+ # List records
13
+ curl http://localhost:8787/api/v1/jobs \
14
+ -H "Authorization: Bearer <token>"
15
+
16
+ # Get a single record
17
+ curl http://localhost:8787/api/v1/jobs/job_123 \
18
+ -H "Authorization: Bearer <token>"
19
+
20
+ # Create a record
21
+ curl -X POST http://localhost:8787/api/v1/jobs \
22
+ -H "Authorization: Bearer <token>" \
23
+ -H "Content-Type: application/json" \
24
+ -d '{"title": "Senior Engineer", "department": "Engineering", "status": "open"}'
25
+
26
+ # Update a record
27
+ curl -X PATCH http://localhost:8787/api/v1/jobs/job_123 \
28
+ -H "Authorization: Bearer <token>" \
29
+ -H "Content-Type: application/json" \
30
+ -d '{"title": "Staff Engineer"}'
31
+
32
+ # Delete a record
33
+ curl -X DELETE http://localhost:8787/api/v1/jobs/job_123 \
34
+ -H "Authorization: Bearer <token>"
35
+
36
+ # List with filters, sorting, and pagination
37
+ curl "http://localhost:8787/api/v1/jobs?status=open&sort=createdAt:desc&limit=25&count=true" \
38
+ -H "Authorization: Bearer <token>"
39
+ ```
40
+
41
+ ## Endpoint Overview
42
+
43
+ For a resource named `jobs`, Quickback generates:
44
+
45
+ | Method | Endpoint | Description |
46
+ |--------|----------|-------------|
47
+ | `GET` | `/jobs` | List all records |
48
+ | `GET` | `/jobs/:id` | Get a single record |
49
+ | `POST` | `/jobs` | Create a new record |
50
+ | `POST` | `/jobs/batch` | Batch create multiple records |
51
+ | `PATCH` | `/jobs/:id` | Update a record |
52
+ | `PATCH` | `/jobs/batch` | Batch update multiple records |
53
+ | `DELETE` | `/jobs/:id` | Delete a record |
54
+ | `DELETE` | `/jobs/batch` | Batch delete multiple records |
55
+ | `PUT` | `/jobs/:id` | Upsert a record (requires config) |
56
+ | `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
57
+
58
+ ## List & Get Records
59
+
60
+ `GET /{resource}` and `GET /{resource}/:id` are part of the [read pipeline](/compiler/definitions/read). Configuration (access, pagination, view projections) lives under `read:`. Filtering, sorting, and pagination query parameters work the same on both endpoints — see [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params).
61
+
62
+ ```typescript
63
+ read: {
64
+ access: { roles: ['owner', 'hiring-manager', 'recruiter'] },
65
+ pageSize: 25,
66
+ maxPageSize: 100,
67
+ views: {
68
+ summary: { fields: ['id', 'title', 'status'], access: { roles: ['interviewer'] } },
69
+ },
70
+ }
71
+ ```
72
+
73
+ Calls a client makes:
74
+
75
+ ```bash
76
+ GET /jobs # Collection — gated by read.access
77
+ GET /jobs/:id # Single — gated by read.access (with ID-probe defense)
78
+ GET /jobs?view=summary # View dispatch
79
+ GET /jobs/views/summary # Explicit view path
80
+ ```
81
+
82
+ ### ID-probe defense on `/:id`
83
+
84
+ Single-record reads run a role-only access check **before** the firewall query, so an unauthorized caller can't tell apart "row exists in another tenant" from "row doesn't exist." See [Access ordering](/compiler/definitions/read#access-ordering-on-id) for details.
85
+
86
+ | Status | Description |
87
+ |--------|-------------|
88
+ | `401` | Not authenticated |
89
+ | `403` | Authenticated but role doesn't satisfy `read.access` |
90
+ | `404` | Authenticated and role passes, but firewall excluded the record (or it doesn't exist). Set [`firewallErrorMode: 'reveal'`](/compiler/definitions/firewall) to return 403 instead. |
91
+
92
+ ### FK Label Resolution
93
+
94
+ Foreign key columns are automatically enriched with `_label` fields containing the referenced table's display value. For example, `departmentId` gets a corresponding `department_label` field. See [Display Column](/compiler/definitions/schema#display-column) for details.
95
+
96
+ ## Create Record
97
+
98
+ ```
99
+ POST /jobs
100
+ Content-Type: application/json
101
+
102
+ {
103
+ "title": "Senior Engineer",
104
+ "department": "Engineering",
105
+ "status": "open",
106
+ "salaryMin": 120000,
107
+ "salaryMax": 180000
108
+ }
109
+ ```
110
+
111
+ Creates a new record. Only fields listed in `guards.createable` are accepted.
112
+
113
+ ### Response
114
+
115
+ ```json
116
+ {
117
+ "data": {
118
+ "id": "job_456",
119
+ "title": "Senior Engineer",
120
+ "department": "Engineering",
121
+ "status": "open",
122
+ "salaryMin": 120000,
123
+ "salaryMax": 180000,
124
+ "createdAt": "2024-01-15T11:00:00Z",
125
+ "createdBy": "user_789"
126
+ }
127
+ }
128
+ ```
129
+
130
+ ### Errors
131
+
132
+ | Status | Description |
133
+ |--------|-------------|
134
+ | `400` | Invalid field or missing required field |
135
+ | `403` | User lacks permission to create records |
136
+
137
+ ## Update Record
138
+
139
+ ```
140
+ PATCH /jobs/:id
141
+ Content-Type: application/json
142
+
143
+ {
144
+ "title": "Staff Engineer"
145
+ }
146
+ ```
147
+
148
+ Updates an existing record. Only fields listed in `guards.updatable` are accepted.
149
+
150
+ ### Response
151
+
152
+ ```json
153
+ {
154
+ "data": {
155
+ "id": "job_123",
156
+ "title": "Staff Engineer",
157
+ "modifiedAt": "2024-01-15T12:00:00Z",
158
+ "modifiedBy": "user_789"
159
+ }
160
+ }
161
+ ```
162
+
163
+ ### Errors
164
+
165
+ | Status | Description |
166
+ |--------|-------------|
167
+ | `400` | Invalid field or field not updatable |
168
+ | `403` | User lacks permission to update this record |
169
+ | `404` | Record not found |
170
+
171
+ ## Delete Record
172
+
173
+ ```
174
+ DELETE /jobs/:id
175
+ ```
176
+
177
+ Deletes a record. Behavior depends on the `delete.mode` configuration.
178
+
179
+ ### Soft Delete (default)
180
+
181
+ Sets `deletedAt` and `deletedBy` fields. Record remains in database but is filtered from queries.
182
+
183
+ #### Cascade
184
+
185
+ When a parent is soft-deleted, every child table that holds an FK to it — both **same-feature** children and **cross-feature** children (e.g. `applications` referencing `jobs` from a different feature directory) — receives the same `deletedAt` / `deletedBy` stamp in the same request. The cascade UPDATE always AND-merges the child's own firewall (`build<Child>FirewallConditions(ctx)`), so a delete in one tenant can never reach a child row in another tenant.
186
+
187
+ If a child column declared `.references(() => parent.id, { onDelete: '...' })`, the cascade respects that intent — only `cascade` and `set null` participate. FKs without `onDelete` are cascaded for backwards-compat with the legacy shape.
188
+
189
+ ### Hard Delete
190
+
191
+ Permanently removes the record from the database.
192
+
193
+ ### Response
194
+
195
+ ```json
196
+ {
197
+ "data": {
198
+ "id": "job_123",
199
+ "deleted": true
200
+ }
201
+ }
202
+ ```
203
+
204
+ ### Errors
205
+
206
+ | Status | Description |
207
+ |--------|-------------|
208
+ | `403` | User lacks permission to delete this record |
209
+ | `404` | Record not found |
210
+
211
+ ## Upsert Record (PUT)
212
+
213
+ ```
214
+ PUT /jobs/:id
215
+ Content-Type: application/json
216
+
217
+ {
218
+ "title": "Contract Recruiter",
219
+ "department": "Talent Acquisition",
220
+ "status": "open",
221
+ "externalId": "ext-123"
222
+ }
223
+ ```
224
+
225
+ Creates or updates a record by ID. Requires special configuration:
226
+
227
+ 1. `generateId: false` in database config
228
+ 2. `guards: false` in resource definition
229
+
230
+ ### Behavior
231
+
232
+ - If record exists: Updates all provided fields
233
+ - If record doesn't exist: Creates with the provided ID
234
+
235
+ ### Use Cases
236
+
237
+ - Syncing data from external systems
238
+ - Webhook handlers with external IDs
239
+ - Idempotent operations (safe to retry)
240
+
241
+ See [Guards documentation](/compiler/definitions/guards#putupsert-with-external-ids) for setup details.
242
+
243
+ ## Batch Operations
244
+
245
+ Quickback provides batch endpoints for efficient bulk operations. Batch operations automatically inherit from their corresponding CRUD operations and maintain full security layer consistency.
246
+
247
+ ### Batch Create Records
248
+
249
+ ```
250
+ POST /jobs/batch
251
+ Content-Type: application/json
252
+
253
+ {
254
+ "records": [
255
+ { "title": "Frontend Engineer", "department": "Engineering", "status": "open" },
256
+ { "title": "Product Designer", "department": "Design", "status": "draft" },
257
+ { "title": "Data Analyst", "department": "Analytics", "status": "open" }
258
+ ],
259
+ "options": {
260
+ "failFast": false
261
+ }
262
+ }
263
+ ```
264
+
265
+ Creates multiple records in a single request. Each record follows the same validation rules as single create operations.
266
+
267
+ #### Request Body
268
+
269
+ | Field | Type | Description |
270
+ |-------|------|-------------|
271
+ | `records` | Array | Array of record objects to create |
272
+ | `options.failFast` | Boolean | If `true`, stop on first error and roll back on tx-supporting providers (default: `false`) |
273
+
274
+ #### Response (Partial Success - Default)
275
+
276
+ ```json
277
+ {
278
+ "success": [
279
+ { "id": "job_1", "title": "Frontend Engineer", "department": "Engineering", "status": "open" },
280
+ { "id": "job_2", "title": "Product Designer", "department": "Design", "status": "draft" }
281
+ ],
282
+ "errors": [
283
+ {
284
+ "index": 2,
285
+ "record": { "title": "Data Analyst", "department": "Analytics", "status": "open" },
286
+ "error": {
287
+ "error": "Field cannot be set during creation",
288
+ "layer": "guards",
289
+ "code": "GUARD_FIELD_NOT_CREATEABLE",
290
+ "details": { "fields": ["status"] }
291
+ }
292
+ }
293
+ ],
294
+ "meta": {
295
+ "total": 3,
296
+ "succeeded": 2,
297
+ "failed": 1,
298
+ "failFast": false,
299
+ "transactional": false
300
+ }
301
+ }
302
+ ```
303
+
304
+ #### HTTP Status Codes
305
+
306
+ - `201` - All records created successfully
307
+ - `207` - Partial success (some records failed)
308
+ - `400` - `failFast: true` was set and one or more records failed
309
+
310
+ #### Batch Size Limit
311
+
312
+ Default: 100 records per request (configurable via `maxBatchSize`)
313
+
314
+ ### Batch Update Records
315
+
316
+ ```
317
+ PATCH /jobs/batch
318
+ Content-Type: application/json
319
+
320
+ {
321
+ "records": [
322
+ { "id": "job_1", "title": "Senior Frontend Engineer" },
323
+ { "id": "job_2", "department": "Product Design" },
324
+ { "id": "job_3", "status": "closed" }
325
+ ],
326
+ "options": {
327
+ "failFast": false
328
+ }
329
+ }
330
+ ```
331
+
332
+ Updates multiple records in a single request. All records must include an `id` field.
333
+
334
+ #### Request Body
335
+
336
+ | Field | Type | Description |
337
+ |-------|------|-------------|
338
+ | `records` | Array | Array of record objects with `id` and fields to update |
339
+ | `options.failFast` | Boolean | If `true`, stop on first error and roll back on tx-supporting providers (default: `false`) |
340
+
341
+ #### Response
342
+
343
+ ```json
344
+ {
345
+ "success": [
346
+ { "id": "job_1", "title": "Senior Frontend Engineer", "modifiedAt": "2024-01-15T14:00:00Z" },
347
+ { "id": "job_2", "department": "Product Design", "modifiedAt": "2024-01-15T14:00:00Z" }
348
+ ],
349
+ "errors": [
350
+ {
351
+ "index": 2,
352
+ "record": { "id": "job_3", "status": "closed" },
353
+ "error": {
354
+ "error": "Not found",
355
+ "layer": "firewall",
356
+ "code": "NOT_FOUND",
357
+ "details": { "id": "job_3" }
358
+ }
359
+ }
360
+ ],
361
+ "meta": {
362
+ "total": 3,
363
+ "succeeded": 2,
364
+ "failed": 1,
365
+ "failFast": false,
366
+ "transactional": false
367
+ }
368
+ }
369
+ ```
370
+
371
+ #### Features
372
+
373
+ - **Batch fetching**: Single database query for all IDs (with firewall)
374
+ - **Per-record access**: Access checks run with record context
375
+ - **Field validation**: Guards apply to each record individually
376
+
377
+ ### Batch Delete Records
378
+
379
+ ```
380
+ DELETE /jobs/batch
381
+ Content-Type: application/json
382
+
383
+ {
384
+ "ids": ["job_1", "job_2", "job_3"],
385
+ "options": {
386
+ "failFast": false
387
+ }
388
+ }
389
+ ```
390
+
391
+ Deletes multiple records in a single request. Supports both soft and hard delete modes.
392
+
393
+ #### Request Body
394
+
395
+ | Field | Type | Description |
396
+ |-------|------|-------------|
397
+ | `ids` | Array | Array of record IDs to delete |
398
+ | `options.failFast` | Boolean | If `true`, stop on first error and roll back on tx-supporting providers (default: `false`) |
399
+
400
+ #### Response (Soft Delete)
401
+
402
+ ```json
403
+ {
404
+ "success": [
405
+ { "id": "job_1", "deletedAt": "2024-01-15T15:00:00Z", "deletedBy": "user_789" },
406
+ { "id": "job_2", "deletedAt": "2024-01-15T15:00:00Z", "deletedBy": "user_789" }
407
+ ],
408
+ "errors": [
409
+ {
410
+ "index": 2,
411
+ "id": "job_3",
412
+ "error": {
413
+ "error": "Not found",
414
+ "layer": "firewall",
415
+ "code": "NOT_FOUND",
416
+ "details": { "id": "job_3" }
417
+ }
418
+ }
419
+ ],
420
+ "meta": {
421
+ "total": 3,
422
+ "succeeded": 2,
423
+ "failed": 1,
424
+ "failFast": false,
425
+ "transactional": false
426
+ }
427
+ }
428
+ ```
429
+
430
+ #### Delete Modes
431
+
432
+ - **Soft delete** (default): Sets `deletedAt`, `deletedBy`, `modifiedAt`, `modifiedBy` fields
433
+ - **Hard delete**: Permanently removes records from database
434
+
435
+ ### Batch Upsert Records
436
+
437
+ ```
438
+ PUT /jobs/batch
439
+ Content-Type: application/json
440
+
441
+ {
442
+ "records": [
443
+ { "id": "job_1", "title": "Updated Frontend Engineer", "department": "Engineering" },
444
+ { "id": "new_job", "title": "New Backend Engineer", "department": "Engineering", "status": "draft" }
445
+ ],
446
+ "options": {
447
+ "failFast": false
448
+ }
449
+ }
450
+ ```
451
+
452
+ Creates or updates multiple records in a single request. Creates if ID doesn't exist, updates if it does.
453
+
454
+ **Strict Requirements** (same as single PUT):
455
+ 1. `generateId: false` in database config (user provides IDs)
456
+ 2. `guards: false` in resource definition (no field restrictions)
457
+ 3. All records must include an `id` field
458
+
459
+ **Note**: System-managed fields (`createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`) are always protected and will be rejected if included in the request, regardless of guards configuration.
460
+
461
+ #### Request Body
462
+
463
+ | Field | Type | Description |
464
+ |-------|------|-------------|
465
+ | `records` | Array | Array of record objects with `id` and all fields |
466
+ | `options.failFast` | Boolean | If `true`, stop on first error and roll back on tx-supporting providers (default: `false`) |
467
+
468
+ #### Response
469
+
470
+ ```json
471
+ {
472
+ "success": [
473
+ { "id": "job_1", "title": "Updated Frontend Engineer", "department": "Engineering", "modifiedAt": "2024-01-15T16:00:00Z" },
474
+ { "id": "new_job", "title": "New Backend Engineer", "department": "Engineering", "status": "draft", "createdAt": "2024-01-15T16:00:00Z" }
475
+ ],
476
+ "errors": [],
477
+ "meta": {
478
+ "total": 2,
479
+ "succeeded": 2,
480
+ "failed": 0,
481
+ "atomic": false
482
+ }
483
+ }
484
+ ```
485
+
486
+ #### How It Works
487
+
488
+ 1. Batch existence check with firewall
489
+ 2. Split records into CREATE and UPDATE batches
490
+ 3. Validate new records with `validateCreate()`
491
+ 4. Validate existing records with `validateUpdate()`
492
+ 5. Check CREATE access for new records
493
+ 6. Check UPDATE access for existing records (per-record)
494
+ 7. Execute bulk insert and individual updates
495
+ 8. Return combined results
496
+
497
+ ### Batch Operation Features
498
+
499
+ #### Partial Success Mode (Default)
500
+
501
+ By default, batch operations use **partial success** mode:
502
+ - All records are processed independently
503
+ - Failed records go into `errors` array with detailed error information
504
+ - Successful records go into `success` array
505
+ - HTTP status `207 Multi-Status` if any errors, `201`/`200` if all success
506
+
507
+ ```json
508
+ {
509
+ "success": [ /* succeeded records */ ],
510
+ "errors": [
511
+ {
512
+ "index": 2,
513
+ "record": { /* original input */ },
514
+ "error": {
515
+ "error": "Human-readable message",
516
+ "layer": "guards",
517
+ "code": "GUARD_FIELD_NOT_CREATEABLE",
518
+ "details": { "fields": ["status"] },
519
+ "hint": "These fields are set automatically or must be omitted"
520
+ }
521
+ }
522
+ ],
523
+ "meta": {
524
+ "total": 10,
525
+ "succeeded": 8,
526
+ "failed": 2,
527
+ "atomic": false
528
+ }
529
+ }
530
+ ```
531
+
532
+ #### Fail-Fast Mode (Opt-in)
533
+
534
+ Set `options.failFast: true` to stop on the first error. On providers that
535
+ support transactions, the loop is wrapped in `db.transaction(...)` so prior
536
+ writes roll back. The response's `meta.transactional` field tells you
537
+ whether you got real rollback or just early-stop semantics — see
538
+ [Batch Operations: Transactional semantics](/compiler/targets/hono-api/using-the-api/batch-operations#transactional-semantics).
539
+
540
+ ```json
541
+ {
542
+ "records": [ /* ... */ ],
543
+ "options": {
544
+ "failFast": true
545
+ }
546
+ }
547
+ ```
548
+
549
+ On the first failure under `failFast: true`:
550
+ - Processing stops; no further records are attempted
551
+ - HTTP status `400 Bad Request`
552
+ - A single error is returned
553
+
554
+ ```json
555
+ {
556
+ "error": "Batch failed at index 2",
557
+ "layer": "validation",
558
+ "code": "BATCH_FAILFAST_STOPPED",
559
+ "details": {
560
+ "failedAt": 2,
561
+ "reason": { /* the actual error */ }
562
+ }
563
+ }
564
+ ```
565
+
566
+ #### Human-Readable Errors
567
+
568
+ All batch operation errors include:
569
+ - **Layer identification**: Which security layer rejected the request
570
+ - **Error code**: Machine-readable code for programmatic handling
571
+ - **Clear message**: Human-readable explanation
572
+ - **Details**: Contextual information (fields, IDs, reasons)
573
+ - **Helpful hints**: Actionable guidance for resolution
574
+
575
+ #### Performance Optimizations
576
+
577
+ - **Batch size limits**: Default 100 records (prevents memory exhaustion)
578
+ - **Single firewall query**: `WHERE id IN (...)` instead of N queries
579
+ - **Bulk operations**: Single INSERT for multiple records (CREATE, UPSERT)
580
+ - **O(1) lookups**: Map-based record lookup instead of Array.find()
581
+
582
+ #### Configuration
583
+
584
+ Batch operations are **auto-enabled** when corresponding CRUD operations exist:
585
+
586
+ ```typescript
587
+ // Auto-enabled - no configuration needed
588
+ crud: {
589
+ create: { access: { roles: ['recruiter'] } },
590
+ update: { access: { roles: ['recruiter'] } }
591
+ // batchCreate and batchUpdate automatically available
592
+ }
593
+
594
+ // Customize batch operations
595
+ crud: {
596
+ create: { access: { roles: ['recruiter'] } },
597
+ batchCreate: {
598
+ access: { roles: ['hiring-manager'] }, // Different access rules
599
+ maxBatchSize: 50, // Lower limit
600
+ allowFailFast: false // Disable failFast mode
601
+ }
602
+ }
603
+
604
+ // Disable batch operations
605
+ crud: {
606
+ create: { access: { roles: ['recruiter'] } },
607
+ batchCreate: false // Explicitly disable
608
+ }
609
+ ```
610
+
611
+ #### Security Layer Application
612
+
613
+ Batch operations maintain **full security layer consistency**:
614
+
615
+ 1. **Firewall**: Auto-apply ownership fields, batch fetch with isolation
616
+ 2. **Access**: Operation-level for CREATE, per-record for UPDATE/DELETE
617
+ 3. **Guards**: Per-record field validation (same rules as single operations)
618
+ 4. **Masking**: Applied to success array (respects user permissions)
619
+ 5. **Audit**: Single timestamp for entire batch for consistency
620
+
621
+ ## Authentication
622
+
623
+ All endpoints require authentication. Include your auth token in the request header:
624
+
625
+ ```
626
+ Authorization: Bearer <your-token>
627
+ ```
628
+
629
+ The user's context (userId, roles, organizationId) is extracted from the token and used to:
630
+
631
+ 1. Apply firewall filters (data isolation)
632
+ 2. Check access permissions
633
+ 3. Set audit fields (createdBy, modifiedBy)
634
+
635
+ ## Error Responses
636
+
637
+ All errors use a flat structure with contextual fields:
638
+
639
+ ```json
640
+ {
641
+ "error": "Insufficient permissions",
642
+ "layer": "access",
643
+ "code": "ACCESS_ROLE_REQUIRED",
644
+ "details": {
645
+ "required": ["hiring-manager"],
646
+ "current": ["interviewer"]
647
+ },
648
+ "hint": "Contact an administrator to grant necessary permissions"
649
+ }
650
+ ```
651
+
652
+ See [Errors](/compiler/targets/hono-api/using-the-api/errors) for the complete reference of error codes by security layer.