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