@quickback-dev/cli 0.10.16 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (253) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +15 -10
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/skill/SKILL.md +142 -1051
  10. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  11. package/dist/skill/docs/changelog.md +1225 -0
  12. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  17. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  18. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  19. package/dist/skill/docs/compiler/config/agents.md +144 -0
  20. package/dist/skill/docs/compiler/config/auth.md +109 -0
  21. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  22. package/dist/skill/docs/compiler/config/domains.md +149 -0
  23. package/dist/skill/docs/compiler/config/index.md +419 -0
  24. package/dist/skill/docs/compiler/config/output.md +338 -0
  25. package/dist/skill/docs/compiler/config/providers.md +248 -0
  26. package/dist/skill/docs/compiler/config/security.md +255 -0
  27. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  28. package/dist/skill/docs/compiler/config/variables.md +157 -0
  29. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  30. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  31. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  32. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  33. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  34. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  36. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  37. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  38. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  39. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  40. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  41. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  42. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  43. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  44. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  45. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  46. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  47. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  48. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  49. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  50. package/dist/skill/docs/compiler/index.md +85 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  66. package/dist/skill/docs/compiler/targets/index.md +47 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  69. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  70. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  71. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  72. package/dist/skill/docs/index.md +77 -0
  73. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  74. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  75. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  76. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  77. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  78. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  79. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  80. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  81. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  82. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  83. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  84. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  85. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  86. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  87. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  88. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  89. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  90. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  91. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  92. package/dist/skill/docs/stack/auth/index.md +64 -0
  93. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  94. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  95. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  96. package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
  97. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  98. package/dist/skill/docs/stack/auth/security.md +455 -0
  99. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  100. package/dist/skill/docs/stack/cms/actions.md +199 -0
  101. package/dist/skill/docs/stack/cms/components.md +479 -0
  102. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  103. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  104. package/dist/skill/docs/stack/cms/index.md +158 -0
  105. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  106. package/dist/skill/docs/stack/cms/pages.md +275 -0
  107. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  108. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  109. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  110. package/dist/skill/docs/stack/cms/security.md +203 -0
  111. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  112. package/dist/skill/docs/stack/index.md +65 -0
  113. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  114. package/dist/skill/docs/stack/queues/index.md +56 -0
  115. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  116. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  117. package/dist/skill/docs/stack/realtime/index.md +73 -0
  118. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  119. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  120. package/dist/skill/docs/stack/storage/index.md +17 -0
  121. package/dist/skill/docs/stack/storage/kv.md +204 -0
  122. package/dist/skill/docs/stack/storage/r2.md +232 -0
  123. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  124. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  125. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  126. package/dist/skill/docs/stack/vector/index.md +44 -0
  127. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  128. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  129. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  130. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  131. package/package.json +1 -1
  132. package/src/skill/SKILL.md +142 -1051
  133. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  134. package/src/skill/docs/changelog.md +1225 -0
  135. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  136. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  137. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  138. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  139. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  140. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  141. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  142. package/src/skill/docs/compiler/config/agents.md +144 -0
  143. package/src/skill/docs/compiler/config/auth.md +109 -0
  144. package/src/skill/docs/compiler/config/bindings.md +176 -0
  145. package/src/skill/docs/compiler/config/domains.md +149 -0
  146. package/src/skill/docs/compiler/config/index.md +419 -0
  147. package/src/skill/docs/compiler/config/output.md +338 -0
  148. package/src/skill/docs/compiler/config/providers.md +248 -0
  149. package/src/skill/docs/compiler/config/security.md +255 -0
  150. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  151. package/src/skill/docs/compiler/config/variables.md +157 -0
  152. package/src/skill/docs/compiler/definitions/access.md +445 -0
  153. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  154. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  155. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  156. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  157. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  158. package/src/skill/docs/compiler/definitions/index.md +219 -0
  159. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  160. package/src/skill/docs/compiler/definitions/read.md +220 -0
  161. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  162. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  163. package/src/skill/docs/compiler/definitions/views.md +292 -0
  164. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  165. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  166. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  167. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  168. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  169. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  170. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  171. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  172. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  173. package/src/skill/docs/compiler/index.md +85 -0
  174. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  176. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  177. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  178. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  179. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  186. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  187. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  188. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  189. package/src/skill/docs/compiler/targets/index.md +47 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  191. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  192. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  193. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  194. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  195. package/src/skill/docs/index.md +77 -0
  196. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  197. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  198. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  199. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  200. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  201. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  202. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  203. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  204. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  205. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  206. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  207. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  208. package/src/skill/docs/stack/account-ui/index.md +147 -0
  209. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  210. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  211. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  212. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  213. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  214. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  215. package/src/skill/docs/stack/auth/index.md +64 -0
  216. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  217. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  218. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  219. package/src/skill/docs/stack/auth/plugins/index.md +340 -0
  220. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  221. package/src/skill/docs/stack/auth/security.md +455 -0
  222. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  223. package/src/skill/docs/stack/cms/actions.md +199 -0
  224. package/src/skill/docs/stack/cms/components.md +479 -0
  225. package/src/skill/docs/stack/cms/connecting.md +199 -0
  226. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  227. package/src/skill/docs/stack/cms/index.md +158 -0
  228. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  229. package/src/skill/docs/stack/cms/pages.md +275 -0
  230. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  231. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  232. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  233. package/src/skill/docs/stack/cms/security.md +203 -0
  234. package/src/skill/docs/stack/cms/table-views.md +142 -0
  235. package/src/skill/docs/stack/index.md +65 -0
  236. package/src/skill/docs/stack/queues/handlers.md +317 -0
  237. package/src/skill/docs/stack/queues/index.md +56 -0
  238. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  239. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  240. package/src/skill/docs/stack/realtime/index.md +73 -0
  241. package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  242. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  243. package/src/skill/docs/stack/storage/index.md +17 -0
  244. package/src/skill/docs/stack/storage/kv.md +204 -0
  245. package/src/skill/docs/stack/storage/r2.md +232 -0
  246. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  247. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  248. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  249. package/src/skill/docs/stack/vector/index.md +44 -0
  250. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  251. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  252. package/src/skill/docs/stack/webhooks/index.md +36 -0
  253. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,224 @@
1
+ # Errors
2
+
3
+ The generated API returns structured error responses with consistent fields across all security layers.
4
+
5
+ ## Status Codes
6
+
7
+ | Code | Meaning | When |
8
+ |------|---------|------|
9
+ | `200` | OK | Successful GET, PATCH, DELETE |
10
+ | `201` | Created | Successful POST |
11
+ | `207` | Multi-Status | Batch operation with mixed results |
12
+ | `400` | Bad Request | Guard violation, validation error, invalid input |
13
+ | `401` | Unauthorized | Missing or expired authentication |
14
+ | `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
15
+ | `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
16
+ | `429` | Too Many Requests | Rate limit exceeded |
17
+
18
+ ## Error Response Format
19
+
20
+ All errors use a flat structure with contextual fields:
21
+
22
+ ```json
23
+ {
24
+ "error": "Insufficient permissions",
25
+ "layer": "access",
26
+ "code": "ACCESS_ROLE_REQUIRED",
27
+ "details": {
28
+ "required": ["hiring-manager"],
29
+ "current": ["interviewer"]
30
+ },
31
+ "hint": "Contact an administrator to grant necessary permissions"
32
+ }
33
+ ```
34
+
35
+ | Field | Type | Description |
36
+ |-------|------|-------------|
37
+ | `error` | string | Human-readable error message |
38
+ | `layer` | string | Security layer that rejected the request |
39
+ | `code` | string | Machine-readable error code |
40
+ | `details` | object | Layer-specific context (optional) |
41
+ | `hint` | string | Actionable guidance for resolution (optional) |
42
+
43
+ ## Errors by Security Layer
44
+
45
+ ### Authentication (401)
46
+
47
+ Missing or invalid authentication tokens.
48
+
49
+ ```json
50
+ {
51
+ "error": "Authentication required",
52
+ "layer": "authentication",
53
+ "code": "AUTH_MISSING",
54
+ "hint": "Include Authorization header with Bearer token"
55
+ }
56
+ ```
57
+
58
+ **Error codes:**
59
+
60
+ | Code | Description |
61
+ |------|-------------|
62
+ | `AUTH_MISSING` | No Authorization header provided |
63
+ | `AUTH_INVALID_TOKEN` | Token is malformed or invalid |
64
+ | `AUTH_EXPIRED` | Token has expired |
65
+ | `AUTH_RATE_LIMITED` | Too many auth attempts |
66
+
67
+ ### Firewall (403)
68
+
69
+ Records outside the user's firewall scope return **403 Forbidden** by default with a structured error:
70
+
71
+ ```json
72
+ {
73
+ "error": "Record not found or not accessible",
74
+ "layer": "firewall",
75
+ "code": "FIREWALL_NOT_FOUND",
76
+ "hint": "Check the record ID and your organization membership"
77
+ }
78
+ ```
79
+
80
+ Firewall filtering is transparent — the query is scoped by `WHERE organizationId = ?` so inaccessible records simply don't appear in results.
81
+
82
+ **Error codes:**
83
+
84
+ | Code | Description |
85
+ |------|-------------|
86
+ | `FIREWALL_NOT_FOUND` | Record not found behind firewall (wrong org, soft-deleted, or doesn't exist) |
87
+ | `FIREWALL_ORG_ISOLATION` | Record belongs to a different organization |
88
+ | `FIREWALL_USER_ISOLATION` | Record belongs to another user |
89
+ | `FIREWALL_SOFT_DELETED` | Record has been soft deleted |
90
+
91
+ For security-hardened deployments, set `errorMode: 'hide'` in your firewall config to return opaque **404 Not Found** responses instead. This prevents attackers from distinguishing between "record exists but you can't access it" and "record doesn't exist".
92
+
93
+ ### Access (403)
94
+
95
+ Access violations return **403 Forbidden** when the user's role doesn't match the required roles for the operation.
96
+
97
+ ```json
98
+ {
99
+ "error": "Insufficient permissions",
100
+ "layer": "access",
101
+ "code": "ACCESS_ROLE_REQUIRED",
102
+ "details": {
103
+ "required": ["hiring-manager"],
104
+ "current": ["interviewer"]
105
+ },
106
+ "hint": "Contact an administrator to grant necessary permissions"
107
+ }
108
+ ```
109
+
110
+ **Error codes:**
111
+
112
+ | Code | Description |
113
+ |------|-------------|
114
+ | `ACCESS_ROLE_REQUIRED` | User doesn't have the required role |
115
+ | `ACCESS_CONDITION_FAILED` | Record-level access condition not met |
116
+ | `ACCESS_OWNERSHIP_REQUIRED` | User must own the record |
117
+ | `ACCESS_NO_ORG` | No active organization set |
118
+
119
+ ### Guards (400)
120
+
121
+ Guard violations return **400 Bad Request** when the request body contains fields that aren't allowed.
122
+
123
+ ```json
124
+ {
125
+ "error": "Field cannot be set during creation",
126
+ "layer": "guards",
127
+ "code": "GUARD_FIELD_NOT_CREATEABLE",
128
+ "details": {
129
+ "fields": ["stage"]
130
+ },
131
+ "hint": "These fields are set automatically or must be omitted"
132
+ }
133
+ ```
134
+
135
+ **Error codes:**
136
+
137
+ | Code | Description |
138
+ |------|-------------|
139
+ | `GUARD_FIELD_NOT_CREATEABLE` | Field not in `createable` list |
140
+ | `GUARD_FIELD_NOT_UPDATABLE` | Field not in `updatable` list |
141
+ | `GUARD_FIELD_PROTECTED` | Field is action-only (protected) |
142
+ | `GUARD_FIELD_IMMUTABLE` | Field cannot be modified after creation |
143
+ | `GUARD_SYSTEM_MANAGED` | System field (createdAt, modifiedAt, etc.) |
144
+
145
+ ### Masking
146
+
147
+ Masking doesn't produce errors — it silently transforms field values in the response.
148
+
149
+ ### Database
150
+
151
+ Surfaced when a SQL write fails *post-validation* — most often a `NOT NULL` or `UNIQUE` constraint hit at the storage layer (e.g. an FK target was deleted concurrently, or a unique column collided with another tenant's row). All four codes share the same `layer: "database"` so consumers can switch on the layer alone and treat the rest as one bucket.
152
+
153
+ ```json
154
+ {
155
+ "error": "Duplicate value",
156
+ "layer": "database",
157
+ "code": "DB_UNIQUE_VIOLATION",
158
+ "details": { "column": "email" },
159
+ "hint": "A record with this \"email\" already exists"
160
+ }
161
+ ```
162
+
163
+ **Error codes:**
164
+
165
+ | Code | Status | Description |
166
+ |------|--------|-------------|
167
+ | `DB_NOT_NULL_VIOLATION` | 400 | Required column was null at write time |
168
+ | `DB_UNIQUE_VIOLATION` | 409 | Unique constraint hit |
169
+ | `DB_INSERT_FAILED` | 500 | INSERT failed for an unrecognized reason |
170
+ | `DB_UPDATE_FAILED` | 500 | UPDATE failed for an unrecognized reason |
171
+
172
+ The `details.column` field is only present when the driver's error message identified the offending column (SQLite/D1 do; some PG variants don't).
173
+
174
+ ## Batch Errors
175
+
176
+ Batch operations can return:
177
+ - **201** — All records succeeded
178
+ - **207** — Partial success (some records failed)
179
+ - **400** — Atomic mode and at least one record failed (all rolled back)
180
+
181
+ ### Partial Success (207)
182
+
183
+ ```json
184
+ {
185
+ "success": [{ "id": "app_1", "candidateId": "cand_101", "stage": "applied" }],
186
+ "errors": [
187
+ {
188
+ "index": 1,
189
+ "record": { "candidateId": "cand_102", "jobId": "job_201", "stage": "interview" },
190
+ "error": {
191
+ "error": "Field cannot be set during creation",
192
+ "layer": "guards",
193
+ "code": "GUARD_FIELD_NOT_CREATEABLE",
194
+ "details": { "fields": ["stage"] },
195
+ "hint": "These fields are set automatically or must be omitted"
196
+ }
197
+ }
198
+ ],
199
+ "meta": { "total": 2, "succeeded": 1, "failed": 1, "atomic": false }
200
+ }
201
+ ```
202
+
203
+ ### Atomic Failure (400)
204
+
205
+ ```json
206
+ {
207
+ "error": "Batch operation failed in atomic mode",
208
+ "layer": "validation",
209
+ "code": "BATCH_ATOMIC_FAILED",
210
+ "details": {
211
+ "failedAt": 2,
212
+ "reason": { "error": "Not found", "code": "NOT_FOUND" }
213
+ },
214
+ "hint": "Transaction rolled back. Fix the error and retry the entire batch."
215
+ }
216
+ ```
217
+
218
+ **Batch error codes:**
219
+
220
+ | Code | Description |
221
+ |------|-------------|
222
+ | `BATCH_SIZE_EXCEEDED` | Too many records in a single request |
223
+ | `BATCH_ATOMIC_FAILED` | Atomic batch failed, all changes rolled back |
224
+ | `BATCH_MISSING_IDS` | Batch update/delete missing required IDs |
@@ -0,0 +1,37 @@
1
+ # Using the API
2
+
3
+ When you run `quickback compile`, Quickback generates a complete REST API from your definitions. This section covers how to use the generated endpoints.
4
+
5
+ ## Base URL
6
+
7
+ All generated endpoints are served under `/api/v1/`:
8
+
9
+ ```
10
+ https://your-api.com/api/v1/{resource}
11
+ ```
12
+
13
+ The resource name is derived from the filename: `jobs.ts` → `/api/v1/jobs`.
14
+
15
+ ## Endpoint Overview
16
+
17
+ For each resource with `export default defineTable(...)`:
18
+
19
+ | Method | Endpoint | Description |
20
+ |--------|----------|-------------|
21
+ | `GET` | `/api/v1/{resource}` | List records (paginated) |
22
+ | `GET` | `/api/v1/{resource}/:id` | Get single record |
23
+ | `POST` | `/api/v1/{resource}` | Create record |
24
+ | `PATCH` | `/api/v1/{resource}/:id` | Update record |
25
+ | `DELETE` | `/api/v1/{resource}/:id` | Delete record |
26
+ | `POST` | `/api/v1/{resource}/batch` | Batch create |
27
+ | `PATCH` | `/api/v1/{resource}/batch` | Batch update |
28
+ | `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
29
+
30
+ ## Guides
31
+
32
+ - [CRUD Endpoints](/compiler/targets/hono-api/using-the-api/crud) — Detailed CRUD endpoint reference
33
+ - [Query Parameters](/compiler/targets/hono-api/using-the-api/query-params) — Filtering, pagination, and sorting
34
+ - [Batch Operations](/compiler/targets/hono-api/using-the-api/batch-operations) — Bulk create, update, delete with atomic mode
35
+ - [Views API](/compiler/targets/hono-api/using-the-api/views-api) — Column-level projections
36
+ - [Actions API](/compiler/targets/hono-api/using-the-api/actions-api) — Custom business logic endpoints
37
+ - [Errors](/compiler/targets/hono-api/using-the-api/errors) — Error responses and HTTP status codes
@@ -0,0 +1,203 @@
1
+ # OpenAPI Spec
2
+
3
+ The compiler generates an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification from your feature definitions. By default it's both written to `openapi.json` at your project root and served as a runtime route.
4
+
5
+ ## Endpoint
6
+
7
+ ```
8
+ GET /openapi.json
9
+ ```
10
+
11
+ Returns the full OpenAPI spec as JSON.
12
+
13
+ ```bash
14
+ curl https://your-api.example.com/openapi.json
15
+ ```
16
+
17
+ ## What's included
18
+
19
+ The generated spec documents every route the compiler produces:
20
+
21
+ - CRUD endpoints (list, get, create, update, delete)
22
+ - Batch operations
23
+ - Views
24
+ - Actions (including standalone actions)
25
+ - Auth routes (`/api/auth/**`)
26
+ - Storage, embeddings, and webhook routes (when configured)
27
+
28
+ Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
29
+
30
+ ### Schema fidelity
31
+
32
+ The generated component schemas carry enough type information that strict validators (zod, openapi-typescript, openapi-fetch) produce non-optional, narrowed types out of the box:
33
+
34
+ - **`required[]` on response components** — every non-nullable column is listed, so generated SDKs treat them as guaranteed-present rather than optional.
35
+ - **Closed enums on `text(_, { enum: [...] })` columns** — emitted as `{ type: "string", enum: [...] }`, narrowing to a literal union in TS.
36
+ - **`Error.code` is a closed enum** — every `code` value the API can emit (`AUTH_MISSING`, `DB_UNIQUE_VIOLATION`, `BATCH_SIZE_EXCEEDED`, …) is enumerated so consumers can `switch` exhaustively.
37
+ - **ID `format`** — only emitted as `format: "uuid"` when your project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }`, keeping strict OpenAPI validators happy.
38
+
39
+ ### Action input schemas
40
+
41
+ Actions defined with [`defineAction({ input: z.object(...) })`](/compiler/definitions/actions) get their full input schema lifted into the operation's `requestBody`. Simple `z.object({...})` shapes are extracted at compile time; for discriminated unions, refinements, recursive schemas, and bare-identifier references (`input: createPersonInput`), the compiler runs your action file through Zod 4's native `z.toJSONSchema()` during compilation so the OpenAPI request body and the MCP tool's `inputSchema` round-trip exactly what your Zod expression declares — no static translator to maintain.
42
+
43
+ ## Configuration
44
+
45
+ Both generation and publishing default to `true`. You can control them independently in `quickback.config.ts`:
46
+
47
+ ```typescript
48
+ export default defineConfig({
49
+ name: "my-app",
50
+ // ...
51
+ openapi: {
52
+ generate: true, // write openapi.json to project root
53
+ publish: true, // serve GET /openapi.json at runtime
54
+ },
55
+ });
56
+ ```
57
+
58
+ | Option | Default | Description |
59
+ |--------|---------|-------------|
60
+ | `generate` | `true` | Write `openapi.json` to the project root during compilation |
61
+ | `publish` | `true` | Serve the spec at `GET /openapi.json` (requires `generate: true`) |
62
+ | `docs` | `false` | Mount an interactive API browser at `GET /docs` — `"scalar"`, `"swagger"`, or `false` |
63
+
64
+ Omitting the `openapi` key entirely is equivalent to `generate: true, publish: true, docs: false`.
65
+
66
+ ### Generate only (no runtime route)
67
+
68
+ ```typescript
69
+ openapi: {
70
+ generate: true,
71
+ publish: false,
72
+ }
73
+ ```
74
+
75
+ The file is still written so you can use it in CI or commit it to your repo, but no route is added to the app.
76
+
77
+ ### Disable entirely
78
+
79
+ ```typescript
80
+ openapi: {
81
+ generate: false,
82
+ }
83
+ ```
84
+
85
+ No file is written and no route is served.
86
+
87
+ ### Interactive API browser at `/docs`
88
+
89
+ Mount an in-browser API reference by setting `openapi.docs`:
90
+
91
+ ```typescript
92
+ openapi: {
93
+ docs: 'scalar', // or 'swagger'
94
+ }
95
+ ```
96
+
97
+ | Value | UI | Notes |
98
+ |---|---|---|
99
+ | `"scalar"` | [Scalar API Reference](https://scalar.com/) — modern, lightweight | Recommended default |
100
+ | `"swagger"` | [Swagger UI](https://swagger.io/tools/swagger-ui/) — the familiar standard | Good if your team expects it |
101
+ | `false` / unset | No `/docs` route | Default |
102
+
103
+ Both UIs are loaded from CDN in a generated static HTML route — **no npm package is added to your project, no Hono middleware is installed, and the runtime bundle stays the same size**. The flag is purely compile-time: it toggles whether a `/docs` route is emitted.
104
+
105
+ Requires `publish: true` (the default). When `publish` is off, `/docs` is silently skipped — there's no spec for it to read.
106
+
107
+ ## Usage with tools
108
+
109
+ ### Import into Postman
110
+
111
+ 1. Open Postman and click **Import**
112
+ 2. Paste the URL `https://your-api.example.com/openapi.json` or upload the file
113
+ 3. Postman creates a collection with every endpoint pre-configured
114
+
115
+ ### Generated TypeScript types (`api-types.gen.ts`)
116
+
117
+ The compiler emits `api-types.gen.ts` next to `openapi.json` by default — a fully typed view of every route, request body, and response, ready to import in client code:
118
+
119
+ ```typescript
120
+ import type { paths, components } from '../api-types.gen';
121
+
122
+ type Job = components['schemas']['Job'];
123
+ type ListJobsResponse = paths['/api/v1/jobs']['get']['responses']['200']['content']['application/json'];
124
+ ```
125
+
126
+ Pair it with [`openapi-fetch`](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) for a fully typed client:
127
+
128
+ ```typescript
129
+ import createClient from 'openapi-fetch';
130
+ import type { paths } from '../api-types.gen';
131
+
132
+ const client = createClient<paths>({ baseUrl: 'https://your-api.example.com' });
133
+ const { data, error } = await client.GET('/api/v1/jobs', { params: { query: { limit: 25 } } });
134
+ ```
135
+
136
+ #### Configuration
137
+
138
+ | `openapi.types` | Behavior |
139
+ |---|---|
140
+ | `true` (default) | Write `api-types.gen.ts` to the project root |
141
+ | `false` | Don't emit the types file |
142
+ | `"src/lib/api-types.ts"` | Custom output path (relative to project root) |
143
+
144
+ ```typescript
145
+ // quickback.config.ts
146
+ export default defineConfig({
147
+ // ...
148
+ openapi: {
149
+ types: 'src/lib/api-types.gen.ts', // emit straight into your client app
150
+ },
151
+ });
152
+ ```
153
+
154
+ The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. Skipped automatically when `openapi.generate` is `false`.
155
+
156
+ ### External viewer
157
+
158
+ Point any OpenAPI-compatible viewer at the endpoint:
159
+
160
+ ```
161
+ https://petstore.swagger.io/?url=https://your-api.example.com/openapi.json
162
+ ```
163
+
164
+ Or enable the in-project browser via the [`docs` config option](#interactive-api-browser-at-docs) above and visit `/docs` directly.
165
+
166
+ ## Example output (excerpt)
167
+
168
+ ```json
169
+ {
170
+ "openapi": "3.1.0",
171
+ "info": {
172
+ "title": "my-app API",
173
+ "version": "1.0.0"
174
+ },
175
+ "paths": {
176
+ "/api/v1/jobs": {
177
+ "get": {
178
+ "summary": "List jobs",
179
+ "operationId": "listJobs",
180
+ "parameters": [
181
+ { "name": "limit", "in": "query", "schema": { "type": "integer" } },
182
+ { "name": "offset", "in": "query", "schema": { "type": "integer" } }
183
+ ],
184
+ "responses": {
185
+ "200": {
186
+ "description": "Success",
187
+ "content": {
188
+ "application/json": {
189
+ "schema": {
190
+ "type": "object",
191
+ "properties": {
192
+ "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }
193
+ }
194
+ }
195
+ }
196
+ }
197
+ }
198
+ }
199
+ }
200
+ }
201
+ }
202
+ }
203
+ ```
@@ -0,0 +1,199 @@
1
+ # Query Parameters
2
+
3
+ The generated API supports filtering, pagination, sorting, field selection, search, and total count via query parameters on `GET` list endpoints.
4
+
5
+ ## Filter Operators
6
+
7
+ | Operator | Query Param | SQL Equivalent |
8
+ |----------|-------------|----------------|
9
+ | Equals | `?field=value` | `WHERE field = value` |
10
+ | Not equals | `?field.ne=value` | `WHERE field != value` |
11
+ | Greater than | `?field.gt=value` | `WHERE field > value` |
12
+ | Greater or equal | `?field.gte=value` | `WHERE field >= value` |
13
+ | Less than | `?field.lt=value` | `WHERE field < value` |
14
+ | Less or equal | `?field.lte=value` | `WHERE field <= value` |
15
+ | Pattern match | `?field.like=value` | `WHERE field LIKE '%value%'` |
16
+ | In list | `?field.in=a,b,c` | `WHERE field IN ('a','b','c')` |
17
+
18
+ ### Examples
19
+
20
+ ```bash
21
+ # Filter by status
22
+ GET /api/v1/jobs?status=open
23
+
24
+ # Range query
25
+ GET /api/v1/jobs?salaryMin.gte=100000&salaryMax.lte=200000
26
+
27
+ # Pattern matching
28
+ GET /api/v1/jobs?title.like=Engineer
29
+
30
+ # Multiple values
31
+ GET /api/v1/jobs?department.in=Engineering,Design,Product
32
+ ```
33
+
34
+ ## Pagination
35
+
36
+ | Parameter | Default | Description |
37
+ |-----------|---------|-------------|
38
+ | `limit` | `50` | Number of records to return (min: 1, max: 100) |
39
+ | `offset` | `0` | Number of records to skip |
40
+
41
+ ```bash
42
+ GET /api/v1/jobs?limit=25&offset=50
43
+ ```
44
+
45
+ The default `limit` can be configured per-resource in your definition:
46
+
47
+ ```typescript
48
+ crud: {
49
+ list: {
50
+ access: { roles: ["recruiter"] },
51
+ pageSize: 25, // Default limit
52
+ maxPageSize: 100, // Maximum allowed limit
53
+ },
54
+ },
55
+ ```
56
+
57
+ ### Response Shape
58
+
59
+ ```json
60
+ {
61
+ "data": [ /* records */ ],
62
+ "pagination": {
63
+ "limit": 25,
64
+ "offset": 50,
65
+ "count": 12
66
+ }
67
+ }
68
+ ```
69
+
70
+ - `count` — number of records returned on this page
71
+ - `total` — total matching records across all pages (only when `?total=true`, see below)
72
+
73
+ ## Sorting
74
+
75
+ Sort by one or more fields. Use the `-` prefix for descending order.
76
+
77
+ ### Multi-Sort (Recommended)
78
+
79
+ ```bash
80
+ # Sort by status ascending, then createdAt descending
81
+ GET /api/v1/jobs?sort=status,-createdAt
82
+
83
+ # Single field descending
84
+ GET /api/v1/jobs?sort=-createdAt
85
+
86
+ # Multiple fields
87
+ GET /api/v1/jobs?sort=department,-salaryMax,title
88
+ ```
89
+
90
+ | Prefix | Direction |
91
+ |--------|-----------|
92
+ | (none) | Ascending |
93
+ | `-` | Descending |
94
+
95
+ ### Legacy Format
96
+
97
+ The original `sort` + `order` format is still supported for backwards compatibility:
98
+
99
+ ```bash
100
+ GET /api/v1/jobs?sort=title&order=asc
101
+ ```
102
+
103
+ | Parameter | Values | Default | Description |
104
+ |-----------|--------|---------|-------------|
105
+ | `sort` | Any column name | `createdAt` | Field to sort by |
106
+ | `order` | `asc`, `desc` | `desc` | Sort direction |
107
+
108
+ When the multi-sort format is detected (comma or `-` prefix), the `order` parameter is ignored.
109
+
110
+ ## Field Selection
111
+
112
+ Select which columns to return using `?fields=`. Available on LIST and GET routes (not Views — they define their own field set).
113
+
114
+ ```bash
115
+ # Return only id, title, and status
116
+ GET /api/v1/jobs?fields=id,title,status
117
+
118
+ # Combine with other query params
119
+ GET /api/v1/jobs?fields=id,title,status&status=open&sort=-createdAt
120
+
121
+ # Single record
122
+ GET /api/v1/jobs/job_123?fields=id,title,salaryMin,salaryMax
123
+ ```
124
+
125
+ All columns are available including system columns (`id`, `organizationId`, `createdAt`, `modifiedAt`, etc.). Invalid field names are silently ignored. If no valid fields are provided, all columns are returned.
126
+
127
+ **Security**: Masking still applies to selected fields. Requesting `?fields=ssn` will return the masked value, not the raw data.
128
+
129
+ ## Total Count
130
+
131
+ Get the total number of matching records across all pages by adding `?total=true`. Available on LIST and VIEW routes.
132
+
133
+ ```bash
134
+ GET /api/v1/jobs?status=open&total=true
135
+ ```
136
+
137
+ ```json
138
+ {
139
+ "data": [ /* 25 records */ ],
140
+ "pagination": {
141
+ "limit": 25,
142
+ "offset": 0,
143
+ "count": 25,
144
+ "total": 142
145
+ }
146
+ }
147
+ ```
148
+
149
+ This is opt-in because it runs an additional `COUNT(*)` query. Only use it when you need the total (e.g., for pagination UI).
150
+
151
+ ## Search
152
+
153
+ Full-text search across all text columns using `?search=`. Available on LIST and VIEW routes.
154
+
155
+ ```bash
156
+ # Search across all text fields
157
+ GET /api/v1/jobs?search=engineer
158
+
159
+ # Combine with filters
160
+ GET /api/v1/jobs?search=engineer&status=open
161
+ ```
162
+
163
+ The search generates an OR'd `LIKE` condition across all `text()` columns in your schema:
164
+
165
+ ```sql
166
+ WHERE (title LIKE '%engineer%' OR department LIKE '%engineer%')
167
+ ```
168
+
169
+ Only columns defined with `text()` in your Drizzle schema are searchable. Non-text columns (integers, timestamps, UUIDs, blobs) are automatically excluded.
170
+
171
+ ## Complete Example
172
+
173
+ Combine all query parameters together:
174
+
175
+ ```bash
176
+ GET /api/v1/jobs?fields=id,title,status,salaryMin&status=open&salaryMin.gte=100000&search=engineer&sort=salaryMin,-createdAt&limit=10&offset=20&total=true
177
+ ```
178
+
179
+ This request:
180
+ 1. **Selects** only `id`, `title`, `status`, `salaryMin` fields
181
+ 2. **Filters** to open jobs with salaryMin >= 100000
182
+ 3. **Searches** text columns for "engineer"
183
+ 4. **Sorts** by salaryMin ascending, then createdAt descending
184
+ 5. **Paginates** with 10 results starting at offset 20
185
+ 6. **Counts** total matching records
186
+
187
+ ## Parameter Summary
188
+
189
+ | Parameter | Applies To | Description |
190
+ |-----------|-----------|-------------|
191
+ | `limit` | LIST, VIEW | Page size (default: 50, max: 100) |
192
+ | `offset` | LIST, VIEW | Skip N records |
193
+ | `sort` | LIST, VIEW | Sort fields (comma-separated, `-` prefix for desc) |
194
+ | `order` | LIST, VIEW | Legacy sort direction (`asc` or `desc`) |
195
+ | `fields` | LIST, GET | Comma-separated column names to return |
196
+ | `total` | LIST, VIEW | Set to `true` to include total count |
197
+ | `search` | LIST, VIEW | Search text across all text columns |
198
+ | `field=value` | LIST, VIEW | Filter by exact match |
199
+ | `field.op=value` | LIST, VIEW | Filter with operator (gt, gte, lt, lte, ne, like, in) |