@quickback-dev/cli 0.13.0 → 0.16.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.
- 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 +13 -13
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/copy-public-assets.d.ts +34 -0
- package/dist/lib/copy-public-assets.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.js +118 -0
- package/dist/lib/copy-public-assets.js.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts +2 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.js +151 -0
- package/dist/lib/copy-public-assets.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +350 -1
- package/dist/skill/docs/compiler/config/index.md +18 -0
- package/dist/skill/docs/compiler/config/output.md +34 -0
- package/dist/skill/docs/compiler/definitions/access.md +180 -4
- package/dist/skill/docs/compiler/definitions/actions.md +145 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +73 -0
- package/dist/skill/docs/compiler/definitions/index.md +2 -0
- package/dist/skill/docs/compiler/definitions/masking.md +11 -0
- package/dist/skill/docs/compiler/definitions/read.md +8 -7
- package/dist/skill/docs/compiler/definitions/schema.md +9 -0
- package/dist/skill/docs/compiler/definitions/views.md +100 -12
- package/dist/skill/docs/compiler/getting-started/full-example.md +12 -11
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +8 -13
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +350 -1
- package/src/skill/docs/compiler/config/index.md +18 -0
- package/src/skill/docs/compiler/config/output.md +34 -0
- package/src/skill/docs/compiler/definitions/access.md +180 -4
- package/src/skill/docs/compiler/definitions/actions.md +145 -0
- package/src/skill/docs/compiler/definitions/firewall.md +73 -0
- package/src/skill/docs/compiler/definitions/index.md +2 -0
- package/src/skill/docs/compiler/definitions/masking.md +11 -0
- package/src/skill/docs/compiler/definitions/read.md +8 -7
- package/src/skill/docs/compiler/definitions/schema.md +9 -0
- package/src/skill/docs/compiler/definitions/views.md +100 -12
- package/src/skill/docs/compiler/getting-started/full-example.md +12 -11
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +8 -13
|
@@ -75,20 +75,18 @@ export default defineTable(candidates, {
|
|
|
75
75
|
|
|
76
76
|
## Generated Endpoints
|
|
77
77
|
|
|
78
|
-
Each view generates
|
|
78
|
+
Each named view generates a dedicated GET endpoint:
|
|
79
79
|
|
|
80
80
|
```
|
|
81
81
|
GET /api/v1/candidates # Full read - read.access fields
|
|
82
|
-
GET /api/v1/candidates
|
|
83
|
-
GET /api/v1/candidates/views/
|
|
84
|
-
GET /api/v1/candidates?view=full # hiring-manager/recruiter only
|
|
82
|
+
GET /api/v1/candidates/views/pipeline # interviewer/recruiter/etc.
|
|
83
|
+
GET /api/v1/candidates/views/full # hiring-manager/recruiter only
|
|
85
84
|
GET /api/v1/candidates/views/report # report fields
|
|
86
85
|
```
|
|
87
86
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
projection.
|
|
87
|
+
If `read.defaultView` is set, bare `GET /api/v1/candidates` can also resolve
|
|
88
|
+
to that named view. Without `defaultView`, bare `GET /api/v1/candidates`
|
|
89
|
+
returns `VIEW_REQUIRED` once views are declared.
|
|
92
90
|
|
|
93
91
|
## Query Parameters
|
|
94
92
|
|
|
@@ -227,6 +225,93 @@ read: {
|
|
|
227
225
|
| `/views/full` | interviewer | Yes | `j***@c******.com` |
|
|
228
226
|
| `/views/full` | recruiter | Yes | `jane@company.com` |
|
|
229
227
|
|
|
228
|
+
## Aggregations
|
|
229
|
+
|
|
230
|
+
Views can declare pre-computed aggregations that run alongside the row
|
|
231
|
+
query and surface as `aggregations: { ... }` on the response. This avoids a
|
|
232
|
+
custom standalone action for every "count of X grouped by Y" dashboard
|
|
233
|
+
tile — the firewall and view filters already in place drive the metric.
|
|
234
|
+
|
|
235
|
+
```typescript
|
|
236
|
+
read: {
|
|
237
|
+
access: { roles: ['owner', 'admin', 'member'] },
|
|
238
|
+
views: {
|
|
239
|
+
pipeline: {
|
|
240
|
+
fields: ['id', 'jobId', 'candidateId', 'status', 'appliedAt'],
|
|
241
|
+
aggregations: {
|
|
242
|
+
totalApplications: { fn: 'count' },
|
|
243
|
+
byStatus: { fn: 'groupBy', field: 'status' },
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
},
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Response now carries the aggregations alongside `data`:
|
|
251
|
+
|
|
252
|
+
```json
|
|
253
|
+
{
|
|
254
|
+
"data": [/* paginated rows */],
|
|
255
|
+
"view": "pipeline",
|
|
256
|
+
"pagination": { "count": 50, "page": 1, "pageSize": 50, "hasMore": true },
|
|
257
|
+
"aggregations": {
|
|
258
|
+
"totalApplications": 173,
|
|
259
|
+
"byStatus": {
|
|
260
|
+
"applied": 102,
|
|
261
|
+
"screening": 41,
|
|
262
|
+
"interview": 18,
|
|
263
|
+
"offer": 7,
|
|
264
|
+
"rejected": 5
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Supported aggregation functions
|
|
271
|
+
|
|
272
|
+
| `fn` | `field` | Returns | Example |
|
|
273
|
+
|---|---|---|---|
|
|
274
|
+
| `sum` | required, numeric | scalar number | `{ fn: 'sum', field: 'guestCount' }` |
|
|
275
|
+
| `avg` | required, numeric | scalar number | `{ fn: 'avg', field: 'salary' }` |
|
|
276
|
+
| `min` | required | scalar number | `{ fn: 'min', field: 'price' }` |
|
|
277
|
+
| `max` | required | scalar number | `{ fn: 'max', field: 'price' }` |
|
|
278
|
+
| `count` | optional | `COUNT(*)` if omitted, `COUNT(field)` (non-null) if given | `{ fn: 'count' }` |
|
|
279
|
+
| `count_distinct` | required | scalar number | `{ fn: 'count_distinct', field: 'sourceId' }` |
|
|
280
|
+
| `groupBy` | required | `{ value: count }` map | `{ fn: 'groupBy', field: 'status' }` |
|
|
281
|
+
|
|
282
|
+
`groupBy` always returns a count map keyed by the distinct values of `field`.
|
|
283
|
+
`NULL` values bucket under the literal string `"(none)"`. Other rollup
|
|
284
|
+
functions (`groupBy` + `sum` of another column) are deferred to a future
|
|
285
|
+
release.
|
|
286
|
+
|
|
287
|
+
### Filter and firewall inheritance
|
|
288
|
+
|
|
289
|
+
Aggregations always run over the **same** filtered, firewalled set as the
|
|
290
|
+
row query. Pagination is intentionally ignored — you get the value over
|
|
291
|
+
every matching record, not just the current page.
|
|
292
|
+
|
|
293
|
+
In practice: a request like
|
|
294
|
+
`GET /applications/views/pipeline?status=applied&jobId=job_123&limit=10`
|
|
295
|
+
returns the first 10 applied rows for that job, AND `byStatus` reflects
|
|
296
|
+
only that filtered set (which will be `{ applied: <total> }` since the
|
|
297
|
+
filter pinned the status). This is the only consistent default — divorcing
|
|
298
|
+
the metric from the user's filters would surprise.
|
|
299
|
+
|
|
300
|
+
### Constraints (compile-time)
|
|
301
|
+
|
|
302
|
+
- `field` must reference a real column on the table.
|
|
303
|
+
- `sum`/`avg` require numeric column types (`int`, `real`, `decimal`,
|
|
304
|
+
`numeric`, `bigint`). Non-numeric columns are rejected at compile time.
|
|
305
|
+
- The same masking opt-out gate that governs `query.{filterable, sortable,
|
|
306
|
+
searchable}` applies to aggregations: the view's roles must satisfy the
|
|
307
|
+
masking rule, otherwise the aggregation is rejected. (A `sum(salary)`
|
|
308
|
+
leaks structure across the masked set even when the row payload is
|
|
309
|
+
redacted.)
|
|
310
|
+
- Aggregation names cannot collide with the reserved response fields
|
|
311
|
+
`data`, `pagination`, `view`.
|
|
312
|
+
- No raw SQL `expr:` form. Column references only — declare a generated
|
|
313
|
+
column or write a custom action if you need arithmetic.
|
|
314
|
+
|
|
230
315
|
## Response Format
|
|
231
316
|
|
|
232
317
|
View responses include metadata about the view:
|
|
@@ -238,15 +323,18 @@ View responses include metadata about the view:
|
|
|
238
323
|
{ "id": "cnd_456", "name": "John Smith", "source": "referral" }
|
|
239
324
|
],
|
|
240
325
|
"view": "pipeline",
|
|
241
|
-
"fields": ["id", "name", "source"],
|
|
242
326
|
"pagination": {
|
|
243
|
-
"
|
|
244
|
-
"
|
|
245
|
-
"
|
|
327
|
+
"count": 2,
|
|
328
|
+
"page": 1,
|
|
329
|
+
"pageSize": 50,
|
|
330
|
+
"hasMore": false
|
|
246
331
|
}
|
|
247
332
|
}
|
|
248
333
|
```
|
|
249
334
|
|
|
335
|
+
When the view declares `aggregations`, the response also includes an
|
|
336
|
+
`aggregations: { ... }` field. See [Aggregations](#aggregations).
|
|
337
|
+
|
|
250
338
|
## Complete Example
|
|
251
339
|
|
|
252
340
|
```typescript
|
|
@@ -253,16 +253,17 @@ import { AuthErrors, AccessErrors, GuardErrors } from '../../lib/errors';
|
|
|
253
253
|
|
|
254
254
|
const app = new Hono();
|
|
255
255
|
|
|
256
|
-
// GET /candidates
|
|
256
|
+
// GET /candidates/views/:viewName — named view projection
|
|
257
257
|
const READ_ACCESS = { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] };
|
|
258
258
|
|
|
259
|
-
app.get('/', async (c) => {
|
|
259
|
+
app.get('/views/:viewName', async (c) => {
|
|
260
260
|
const ctx = c.get('ctx');
|
|
261
261
|
const db = c.get('db');
|
|
262
262
|
|
|
263
|
+
const viewName = c.req.param('viewName');
|
|
263
264
|
const params = Object.fromEntries(new URL(c.req.url).searchParams);
|
|
264
|
-
const view = VIEWS_CONFIG[
|
|
265
|
-
if (!view) return c.json({ error: '
|
|
265
|
+
const view = VIEWS_CONFIG[viewName as keyof typeof VIEWS_CONFIG];
|
|
266
|
+
if (!view) return c.json({ error: 'Unknown view', code: 'VIEW_NOT_FOUND' }, 400);
|
|
266
267
|
|
|
267
268
|
// Per-view access gate (falls back to read-level access)
|
|
268
269
|
if (!await evaluateAccess(view.access ?? READ_ACCESS, ctx)) {
|
|
@@ -273,7 +274,7 @@ app.get('/', async (c) => {
|
|
|
273
274
|
const results = await db.select(/* projected fields */).from(candidates)
|
|
274
275
|
.where(buildFirewallConditions(ctx));
|
|
275
276
|
|
|
276
|
-
return c.json({ data: maskCandidates(results, ctx), view:
|
|
277
|
+
return c.json({ data: maskCandidates(results, ctx), view: viewName });
|
|
277
278
|
});
|
|
278
279
|
|
|
279
280
|
// POST /candidates - Create with guards
|
|
@@ -383,10 +384,10 @@ Views control **which fields are returned**. Masking controls **what values are
|
|
|
383
384
|
|
|
384
385
|
| Endpoint | Role | `phone` in response? | `phone` value |
|
|
385
386
|
|----------|------|--------------------|-------------|
|
|
386
|
-
| `/candidates
|
|
387
|
-
| `/candidates
|
|
388
|
-
| `/candidates
|
|
389
|
-
| `/candidates
|
|
387
|
+
| `/candidates/views/pipeline` | interviewer | No | N/A |
|
|
388
|
+
| `/candidates/views/pipeline` | recruiter | No | N/A |
|
|
389
|
+
| `/candidates/views/full` | interviewer | No | N/A (no access) |
|
|
390
|
+
| `/candidates/views/full` | recruiter | Yes | `555-123-4567` |
|
|
390
391
|
|
|
391
392
|
### Guards Enforcement
|
|
392
393
|
|
|
@@ -417,8 +418,8 @@ POST /candidates
|
|
|
417
418
|
| `POST` | `/candidates` | hiring-manager, recruiter |
|
|
418
419
|
| `PATCH` | `/candidates/:id` | hiring-manager, recruiter |
|
|
419
420
|
| `DELETE` | `/candidates/:id` | hiring-manager |
|
|
420
|
-
| `GET` | `/candidates
|
|
421
|
-
| `GET` | `/candidates
|
|
421
|
+
| `GET` | `/candidates/views/pipeline` | owner, hiring-manager, recruiter, interviewer |
|
|
422
|
+
| `GET` | `/candidates/views/full` | hiring-manager, recruiter |
|
|
422
423
|
|
|
423
424
|
---
|
|
424
425
|
|
|
@@ -75,8 +75,7 @@ Calls a client makes:
|
|
|
75
75
|
```bash
|
|
76
76
|
GET /jobs # Collection — gated by read.access
|
|
77
77
|
GET /jobs/:id # Single — gated by read.access (with ID-probe defense)
|
|
78
|
-
GET /jobs
|
|
79
|
-
GET /jobs/views/summary # Explicit view path
|
|
78
|
+
GET /jobs/views/summary # Named view projection
|
|
80
79
|
```
|
|
81
80
|
|
|
82
81
|
### ID-probe defense on `/:id`
|
|
@@ -4,14 +4,14 @@ Views provide named column projections that limit which fields are returned in A
|
|
|
4
4
|
|
|
5
5
|
## Endpoints
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Named views are queried through a dedicated path endpoint:
|
|
8
8
|
|
|
9
9
|
```
|
|
10
|
-
GET /api/v1/{resource}
|
|
11
|
-
GET /api/v1/{resource}/views/{view-name} # Explicit path
|
|
10
|
+
GET /api/v1/{resource}/views/{view-name}
|
|
12
11
|
```
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
If you set `read.defaultView`, bare `GET /api/v1/{resource}` can still resolve
|
|
14
|
+
to that view. Named views themselves are addressed via `/views/{view-name}`.
|
|
15
15
|
|
|
16
16
|
## Example
|
|
17
17
|
|
|
@@ -39,11 +39,6 @@ export default defineTable(candidates, {
|
|
|
39
39
|
### Request
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
# Query-string form
|
|
43
|
-
curl '/api/v1/candidates?view=pipeline' \
|
|
44
|
-
-H "Authorization: Bearer <token>"
|
|
45
|
-
|
|
46
|
-
# Path form (equivalent)
|
|
47
42
|
curl /api/v1/candidates/views/pipeline \
|
|
48
43
|
-H "Authorization: Bearer <token>"
|
|
49
44
|
```
|
|
@@ -57,11 +52,11 @@ curl /api/v1/candidates/views/pipeline \
|
|
|
57
52
|
{ "id": "cand_002", "name": "Bob Martinez", "source": "referral" }
|
|
58
53
|
],
|
|
59
54
|
"view": "pipeline",
|
|
60
|
-
"fields": ["id", "name", "source"],
|
|
61
55
|
"pagination": {
|
|
62
|
-
"
|
|
63
|
-
"
|
|
64
|
-
"
|
|
56
|
+
"count": 2,
|
|
57
|
+
"page": 1,
|
|
58
|
+
"pageSize": 50,
|
|
59
|
+
"hasMore": false
|
|
65
60
|
}
|
|
66
61
|
}
|
|
67
62
|
```
|