@quickback-dev/cli 0.16.5 → 0.17.1
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/README.md +7 -3
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +12 -48
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.d.ts +20 -0
- package/dist/commands/create.d.ts.map +1 -1
- package/dist/commands/create.js +216 -151
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/login.d.ts +4 -2
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +25 -17
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/start.d.ts +20 -0
- package/dist/commands/start.d.ts.map +1 -0
- package/dist/commands/start.js +163 -0
- package/dist/commands/start.js.map +1 -0
- package/dist/commands/whoami.d.ts.map +1 -1
- package/dist/commands/whoami.js +5 -4
- package/dist/commands/whoami.js.map +1 -1
- package/dist/docs/content.js +37 -37
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +27 -10
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +15 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/auth.d.ts +39 -3
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +57 -3
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/drizzle-meta-routing.test.js +16 -3
- package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +6 -4
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +30 -27
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +16 -7
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +145 -0
- package/dist/skill/docs/compiler/config/providers.md +87 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
- package/dist/skill/docs/compiler/definitions/access.md +43 -57
- package/dist/skill/docs/compiler/definitions/feature.md +7 -11
- package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
- package/dist/skill/docs/compiler/definitions/guards.md +16 -18
- package/dist/skill/docs/compiler/definitions/index.md +10 -14
- package/dist/skill/docs/compiler/definitions/masking.md +6 -6
- package/dist/skill/docs/compiler/definitions/read.md +6 -11
- package/dist/skill/docs/compiler/definitions/schema.md +18 -18
- package/dist/skill/docs/compiler/definitions/views.md +3 -5
- package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/dist/skill/docs/compiler/getting-started/index.md +23 -20
- package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
- package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/dist/skill/docs/compiler/troubleshooting.md +10 -0
- package/dist/skill/docs/stack/auth/security.md +69 -0
- package/dist/skill/docs/stack/cms/actions.md +28 -0
- package/dist/skill/docs/stack/cms/connecting.md +2 -2
- package/dist/skill/docs/stack/cms/index.md +2 -2
- package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
- package/dist/skill/docs/stack/cms/schema-format.md +33 -3
- package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
- package/dist/skill/docs/stack/cms/security.md +10 -12
- package/dist/skill/docs/stack/cms/table-views.md +1 -1
- package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/dist/skill/docs/stack/realtime/index.md +20 -3
- package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/dist/skill/docs/stack/vector/embeddings.md +7 -6
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +145 -0
- package/src/skill/docs/compiler/config/providers.md +87 -0
- package/src/skill/docs/compiler/config/single-tenant.md +5 -11
- package/src/skill/docs/compiler/definitions/access.md +43 -57
- package/src/skill/docs/compiler/definitions/feature.md +7 -11
- package/src/skill/docs/compiler/definitions/firewall.md +2 -4
- package/src/skill/docs/compiler/definitions/guards.md +16 -18
- package/src/skill/docs/compiler/definitions/index.md +10 -14
- package/src/skill/docs/compiler/definitions/masking.md +6 -6
- package/src/skill/docs/compiler/definitions/read.md +6 -11
- package/src/skill/docs/compiler/definitions/schema.md +18 -18
- package/src/skill/docs/compiler/definitions/views.md +3 -5
- package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/src/skill/docs/compiler/getting-started/index.md +23 -20
- package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +3 -5
- package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/src/skill/docs/compiler/troubleshooting.md +10 -0
- package/src/skill/docs/stack/auth/security.md +69 -0
- package/src/skill/docs/stack/cms/actions.md +28 -0
- package/src/skill/docs/stack/cms/connecting.md +2 -2
- package/src/skill/docs/stack/cms/index.md +2 -2
- package/src/skill/docs/stack/cms/record-layouts.md +19 -19
- package/src/skill/docs/stack/cms/schema-format.md +33 -3
- package/src/skill/docs/stack/cms/schema-registry.md +22 -2
- package/src/skill/docs/stack/cms/security.md +10 -12
- package/src/skill/docs/stack/cms/table-views.md +1 -1
- package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/src/skill/docs/stack/realtime/index.md +20 -3
- package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/src/skill/docs/stack/vector/embeddings.md +7 -6
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Access - Role & Condition-Based Access Control
|
|
2
2
|
|
|
3
|
-
Define who can perform
|
|
3
|
+
Define who can perform read and write operations and under what conditions.
|
|
4
4
|
|
|
5
5
|
## Basic Usage
|
|
6
6
|
|
|
@@ -24,11 +24,9 @@ export default defineTable(applications, {
|
|
|
24
24
|
read: {
|
|
25
25
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
26
26
|
},
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
31
|
-
},
|
|
27
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
28
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
29
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
32
30
|
});
|
|
33
31
|
```
|
|
34
32
|
|
|
@@ -51,10 +49,8 @@ Then in your resource definitions:
|
|
|
51
49
|
|
|
52
50
|
```typescript
|
|
53
51
|
read: { access: { roles: ["member+"] } }, // member, admin, owner
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
57
|
-
}
|
|
52
|
+
create: { access: { roles: ["admin+"] } }, // admin, owner
|
|
53
|
+
delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
58
54
|
```
|
|
59
55
|
|
|
60
56
|
The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
|
|
@@ -118,11 +114,9 @@ access: {
|
|
|
118
114
|
|
|
119
115
|
// CMS-internal resource: only platform admins
|
|
120
116
|
read: { access: { userRole: ['admin'] } },
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
delete: { access: { userRole: ['admin'] } },
|
|
125
|
-
}
|
|
117
|
+
create: { access: { userRole: ['admin'] } },
|
|
118
|
+
update: { access: { userRole: ['admin'] } },
|
|
119
|
+
delete: { access: { userRole: ['admin'] } },
|
|
126
120
|
```
|
|
127
121
|
|
|
128
122
|
When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
|
|
@@ -153,7 +147,7 @@ access: { roles: ["PUBLIC"] }
|
|
|
153
147
|
|
|
154
148
|
**Important:**
|
|
155
149
|
- `PUBLIC` skips authentication and role checks — anyone can call the endpoint
|
|
156
|
-
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads,
|
|
150
|
+
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
|
|
157
151
|
- **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
|
|
158
152
|
- Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
|
|
159
153
|
- The wildcard `"*"` is **not supported** — using it throws a compile-time error
|
|
@@ -172,9 +166,7 @@ The firewall WHERE clause is always enforced. If no `organizationId` is provided
|
|
|
172
166
|
export default defineTable(listings, {
|
|
173
167
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
174
168
|
read: { access: { roles: ["PUBLIC"] } }, // Public browsing + detail
|
|
175
|
-
|
|
176
|
-
create: { access: { roles: ["admin", "member"] } }, // Auth required to create
|
|
177
|
-
},
|
|
169
|
+
create: { access: { roles: ["admin", "member"] } }, // Auth required to create
|
|
178
170
|
});
|
|
179
171
|
```
|
|
180
172
|
|
|
@@ -196,11 +188,9 @@ Use `roles: ["USER"]` for resources where each user only sees their own records.
|
|
|
196
188
|
export default defineTable(todos, {
|
|
197
189
|
firewall: [{ field: 'userId', equals: 'ctx.userId' }],
|
|
198
190
|
read: { access: { roles: ["USER"] } },
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
delete: { access: { roles: ["USER"] } },
|
|
203
|
-
},
|
|
191
|
+
create: { access: { roles: ["USER"] } },
|
|
192
|
+
update: { access: { roles: ["USER"] } },
|
|
193
|
+
delete: { access: { roles: ["USER"] } },
|
|
204
194
|
});
|
|
205
195
|
```
|
|
206
196
|
|
|
@@ -444,9 +434,9 @@ The validator and resolver reject:
|
|
|
444
434
|
- `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
|
|
445
435
|
- Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
|
|
446
436
|
|
|
447
|
-
## Read &
|
|
437
|
+
## Read & Write Configuration
|
|
448
438
|
|
|
449
|
-
Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under `
|
|
439
|
+
Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
|
|
450
440
|
|
|
451
441
|
```typescript
|
|
452
442
|
read: {
|
|
@@ -462,35 +452,33 @@ read: {
|
|
|
462
452
|
},
|
|
463
453
|
}
|
|
464
454
|
|
|
465
|
-
|
|
455
|
+
create: {
|
|
466
456
|
// CREATE - POST /resource
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
stage: 'applied',
|
|
471
|
-
},
|
|
457
|
+
access: { roles: ["owner", "hiring-manager", "recruiter"] },
|
|
458
|
+
defaults: { // Default values for new records
|
|
459
|
+
stage: 'applied',
|
|
472
460
|
},
|
|
461
|
+
},
|
|
473
462
|
|
|
463
|
+
update: {
|
|
474
464
|
// UPDATE - PATCH /resource/:id
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
]
|
|
481
|
-
},
|
|
465
|
+
access: {
|
|
466
|
+
or: [
|
|
467
|
+
{ roles: ["hiring-manager", "recruiter"] },
|
|
468
|
+
{ roles: ["interviewer"], record: { stage: { equals: "interview" } } }
|
|
469
|
+
]
|
|
482
470
|
},
|
|
471
|
+
},
|
|
483
472
|
|
|
473
|
+
delete: {
|
|
484
474
|
// DELETE - DELETE /resource/:id
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
},
|
|
475
|
+
access: { roles: ["owner", "hiring-manager"] },
|
|
476
|
+
mode: "soft", // 'soft' (default) or 'hard'
|
|
477
|
+
},
|
|
489
478
|
|
|
479
|
+
upsert: {
|
|
490
480
|
// PUT - PUT /resource/:id (only when generateId: false + guards: false)
|
|
491
|
-
|
|
492
|
-
access: { roles: ["hiring-manager", "sync-service"] },
|
|
493
|
-
},
|
|
481
|
+
access: { roles: ["hiring-manager", "sync-service"] },
|
|
494
482
|
}
|
|
495
483
|
```
|
|
496
484
|
|
|
@@ -601,17 +589,15 @@ access: {
|
|
|
601
589
|
For complex access logic that can't be expressed declaratively, use a function:
|
|
602
590
|
|
|
603
591
|
```typescript
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
return membership.canEdit;
|
|
614
|
-
}
|
|
592
|
+
update: {
|
|
593
|
+
access: async (ctx, record) => {
|
|
594
|
+
// Custom logic - return true to allow, false to deny
|
|
595
|
+
if (ctx.roles.includes('admin')) return true;
|
|
596
|
+
if (record.ownerId === ctx.userId) return true;
|
|
597
|
+
|
|
598
|
+
// Check custom business logic
|
|
599
|
+
const membership = await checkTeamMembership(ctx.userId, record.teamId);
|
|
600
|
+
return membership.canEdit;
|
|
615
601
|
}
|
|
616
602
|
}
|
|
617
603
|
```
|
|
@@ -19,11 +19,9 @@ export const contacts = q.table("contacts", {
|
|
|
19
19
|
export default defineTable(contacts, {
|
|
20
20
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
21
21
|
read: { access: { roles: ["member+"] } },
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
26
|
-
},
|
|
22
|
+
create: { access: { roles: ["member+"] } },
|
|
23
|
+
update: { access: { roles: ["member+"] } },
|
|
24
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
27
25
|
guards: { createable: ["address", "name"] },
|
|
28
26
|
});
|
|
29
27
|
|
|
@@ -44,11 +42,9 @@ export default feature("contacts", {
|
|
|
44
42
|
},
|
|
45
43
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
46
44
|
read: { access: { roles: ["member+"] } },
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
51
|
-
},
|
|
45
|
+
create: { access: { roles: ["member+"] } },
|
|
46
|
+
update: { access: { roles: ["member+"] } },
|
|
47
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
52
48
|
guards: { createable: ["address", "name"] },
|
|
53
49
|
});
|
|
54
50
|
```
|
|
@@ -57,7 +53,7 @@ Type inference still works — `typeof import("./contacts").default.$infer` give
|
|
|
57
53
|
|
|
58
54
|
## How it works
|
|
59
55
|
|
|
60
|
-
`feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts,
|
|
56
|
+
`feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts, generated routes, OpenAPI, MCP tools, RLS emission — runs on the same Drizzle source it always did. Zero runtime cost; zero semantic difference from `q.table()` + `defineTable()`.
|
|
61
57
|
|
|
62
58
|
That means:
|
|
63
59
|
|
|
@@ -341,10 +341,8 @@ export default defineTable(jobs, {
|
|
|
341
341
|
// via record-level access conditions on /:id
|
|
342
342
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
343
343
|
},
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
// (single-record GET inherits read.access, with optional record-level overrides)
|
|
347
|
-
},
|
|
344
|
+
// Use record conditions to allow public jobs OR owned jobs on GET /:id
|
|
345
|
+
// (single-record GET inherits read.access, with optional record-level overrides)
|
|
348
346
|
// ...
|
|
349
347
|
});
|
|
350
348
|
```
|
|
@@ -29,9 +29,9 @@ export default defineTable(applications, {
|
|
|
29
29
|
},
|
|
30
30
|
immutable: ["appliedAt", "candidateId", "jobId"],
|
|
31
31
|
},
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
},
|
|
32
|
+
create: { /* ... */ },
|
|
33
|
+
update: { /* ... */ },
|
|
34
|
+
delete: { /* ... */ },
|
|
35
35
|
});
|
|
36
36
|
```
|
|
37
37
|
|
|
@@ -59,7 +59,7 @@ guards: {
|
|
|
59
59
|
|------|------------------|
|
|
60
60
|
| `createable` | Fields allowed in create (POST) request body |
|
|
61
61
|
| `updatable` | Fields allowed in update (PATCH) request body |
|
|
62
|
-
| `protected` | Fields blocked from
|
|
62
|
+
| `protected` | Fields blocked from direct writes, only modifiable via named actions |
|
|
63
63
|
| `immutable` | Fields allowed on create, blocked on all updates |
|
|
64
64
|
|
|
65
65
|
**Combining lists:**
|
|
@@ -130,21 +130,21 @@ guards: {
|
|
|
130
130
|
guards: false // Only system fields protected
|
|
131
131
|
```
|
|
132
132
|
|
|
133
|
-
When `guards: false` is set, all user-defined fields become writable via
|
|
133
|
+
When `guards: false` is set, all user-defined fields become writable via direct create/update/upsert operations. This is useful for:
|
|
134
134
|
- External sync scenarios where you need full field control
|
|
135
135
|
- Batch upsert operations where field restrictions would be limiting
|
|
136
136
|
- Simple tables where field-level protection isn't needed
|
|
137
137
|
|
|
138
|
-
##
|
|
138
|
+
## Upsert with External IDs
|
|
139
139
|
|
|
140
|
-
When you disable guards AND use client-provided IDs, you unlock
|
|
140
|
+
When you disable guards AND use client-provided IDs, you unlock upsert operations. This is designed for **syncing data from external systems**.
|
|
141
141
|
|
|
142
|
-
### Requirements for
|
|
142
|
+
### Requirements for Upsert
|
|
143
143
|
|
|
144
144
|
1. `generateId: false` in database config (client provides IDs)
|
|
145
145
|
2. `guards: false` in resource definition
|
|
146
146
|
|
|
147
|
-
### How
|
|
147
|
+
### How Upsert Works
|
|
148
148
|
|
|
149
149
|
```
|
|
150
150
|
PUT /resource/:id
|
|
@@ -158,7 +158,7 @@ PUT /resource/:id
|
|
|
158
158
|
// quickback.config.ts
|
|
159
159
|
export default {
|
|
160
160
|
database: {
|
|
161
|
-
generateId: false, // Client provides IDs (enables
|
|
161
|
+
generateId: false, // Client provides IDs (enables upsert)
|
|
162
162
|
// Other options: 'uuid' | 'cuid' | 'nanoid' | 'short' | 'prefixed' | 'serial'
|
|
163
163
|
}
|
|
164
164
|
};
|
|
@@ -171,10 +171,8 @@ export default {
|
|
|
171
171
|
export default defineTable(atsImports, {
|
|
172
172
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
173
173
|
guards: false, // Disables field restrictions
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
access: { roles: ['hiring-manager', 'sync-service'] }
|
|
177
|
-
}
|
|
174
|
+
upsert: {
|
|
175
|
+
access: { roles: ['hiring-manager', 'sync-service'] }
|
|
178
176
|
},
|
|
179
177
|
});
|
|
180
178
|
```
|
|
@@ -192,7 +190,7 @@ So `guards: false` only opens up user-defined business fields. Tenant scope and
|
|
|
192
190
|
|
|
193
191
|
## Ownership Auto-Population
|
|
194
192
|
|
|
195
|
-
When
|
|
193
|
+
When upsert creates a new record, ownership fields are auto-set from context:
|
|
196
194
|
|
|
197
195
|
```typescript
|
|
198
196
|
// Client sends: PUT /ats-imports/ext-123 { candidateName: "Jane Doe" }
|
|
@@ -208,9 +206,9 @@ When PUT creates a new record, ownership fields are auto-set from context:
|
|
|
208
206
|
}
|
|
209
207
|
```
|
|
210
208
|
|
|
211
|
-
## Use Cases for
|
|
209
|
+
## Use Cases for Upsert/External IDs
|
|
212
210
|
|
|
213
|
-
| Use Case | Why
|
|
211
|
+
| Use Case | Why upsert? |
|
|
214
212
|
|----------|----------|
|
|
215
213
|
| External API sync | External system controls the ID |
|
|
216
214
|
| Webhook handlers | Events come with their own IDs |
|
|
@@ -220,7 +218,7 @@ When PUT creates a new record, ownership fields are auto-set from context:
|
|
|
220
218
|
|
|
221
219
|
## ID Generation Options
|
|
222
220
|
|
|
223
|
-
| `generateId` |
|
|
221
|
+
| `generateId` | Upsert Available? | Notes |
|
|
224
222
|
|--------------|----------------|-------|
|
|
225
223
|
| `'uuid'` | No | Server generates UUID |
|
|
226
224
|
| `'cuid'` | No | Server generates CUID |
|
|
@@ -59,24 +59,22 @@ export default defineTable(candidates, {
|
|
|
59
59
|
read: {
|
|
60
60
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
61
61
|
},
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
66
|
-
},
|
|
62
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
63
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
64
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
67
65
|
});
|
|
68
66
|
|
|
69
67
|
export type Candidate = typeof candidates.$inferSelect;
|
|
70
68
|
```
|
|
71
69
|
|
|
72
70
|
**Key points:**
|
|
73
|
-
- Tables with `export default defineTable(...)` →
|
|
71
|
+
- Tables with `export default defineTable(...)` → resource routes generated
|
|
74
72
|
- Tables without default export → internal/junction tables (no routes)
|
|
75
73
|
- Route path derived from filename: `applications.ts` → `/api/v1/applications`
|
|
76
74
|
|
|
77
75
|
> **1 Resource = 1 Security Boundary**
|
|
78
76
|
>
|
|
79
|
-
> Each `defineTable()` defines its own complete security boundary — its own firewall (who sees the data), access rules (role requirements), guards (field validation), and masking (redaction). These are compiled into a single resource file that wraps all
|
|
77
|
+
> Each `defineTable()` defines its own complete security boundary — its own firewall (who sees the data), access rules (role requirements), guards (field validation), and masking (redaction). These are compiled into a single resource file that wraps all generated routes for that table.
|
|
80
78
|
>
|
|
81
79
|
> A table **without** `defineTable()` is a supporting table — used internally by actions or handlers, but never exposed as its own API endpoint. See [Internal Tables](/compiler/definitions/schema#internal-tables-no-routes) for details.
|
|
82
80
|
|
|
@@ -116,17 +114,15 @@ For relationship-based row visibility (e.g. "user can see this event because the
|
|
|
116
114
|
|
|
117
115
|
### 2. Access (CRUD Permissions)
|
|
118
116
|
|
|
119
|
-
Access controls **which operations** a user can perform. It checks roles and record conditions. Reads (`GET /` and `GET /:id`) live under `read:`; writes live under `
|
|
117
|
+
Access controls **which operations** a user can perform. It checks roles and record conditions. Reads (`GET /` and `GET /:id`) live under `read:`; writes live under top-level `create:`, `update:`, `delete:`, and `upsert:`.
|
|
120
118
|
|
|
121
119
|
```typescript
|
|
122
120
|
read: {
|
|
123
121
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
124
122
|
},
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
129
|
-
}
|
|
123
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
124
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
125
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
130
126
|
```
|
|
131
127
|
|
|
132
128
|
[Learn more about Access →](/compiler/definitions/access)
|
|
@@ -213,7 +209,7 @@ All options are optional — omit them and Quickback uses sensible defaults (aut
|
|
|
213
209
|
|
|
214
210
|
1. [Database Schema](/compiler/definitions/schema) — Define your tables
|
|
215
211
|
2. [Firewall](/compiler/definitions/firewall) — Set up data isolation
|
|
216
|
-
3. [Access](/compiler/definitions/access) — Configure
|
|
212
|
+
3. [Access](/compiler/definitions/access) — Configure read and write permissions
|
|
217
213
|
4. [Guards](/compiler/definitions/guards) — Control field modifications
|
|
218
214
|
5. [Masking](/compiler/definitions/masking) — Hide sensitive data
|
|
219
215
|
6. [Views](/compiler/definitions/views) — Column-level security
|
|
@@ -84,7 +84,9 @@ export default feature('candidates', {
|
|
|
84
84
|
phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
|
|
85
85
|
},
|
|
86
86
|
read: { access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] } },
|
|
87
|
-
|
|
87
|
+
create: { /* ... */ },
|
|
88
|
+
update: { /* ... */ },
|
|
89
|
+
delete: { /* ... */ },
|
|
88
90
|
});
|
|
89
91
|
```
|
|
90
92
|
|
|
@@ -243,10 +245,8 @@ export default feature('candidates', {
|
|
|
243
245
|
},
|
|
244
246
|
},
|
|
245
247
|
},
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
delete: { access: { roles: ['owner'] }, mode: 'soft' },
|
|
250
|
-
},
|
|
248
|
+
create: { access: { roles: ['admin+'] } },
|
|
249
|
+
update: { access: { roles: ['admin+'] } },
|
|
250
|
+
delete: { access: { roles: ['owner'] }, mode: 'soft' },
|
|
251
251
|
});
|
|
252
252
|
```
|
|
@@ -39,11 +39,9 @@ export default defineTable(customers, {
|
|
|
39
39
|
},
|
|
40
40
|
},
|
|
41
41
|
},
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
delete: { access: { roles: ['admin'] }, mode: 'soft' },
|
|
46
|
-
},
|
|
42
|
+
create: { access: { roles: ['admin'] } },
|
|
43
|
+
update: { access: { roles: ['admin'] } },
|
|
44
|
+
delete: { access: { roles: ['admin'] }, mode: 'soft' },
|
|
47
45
|
});
|
|
48
46
|
```
|
|
49
47
|
|
|
@@ -190,9 +188,7 @@ read: {
|
|
|
190
188
|
},
|
|
191
189
|
},
|
|
192
190
|
}
|
|
193
|
-
|
|
194
|
-
create: { access: { roles: ['admin'] } },
|
|
195
|
-
}
|
|
191
|
+
create: { access: { roles: ['admin'] } }
|
|
196
192
|
```
|
|
197
193
|
|
|
198
194
|
Clients that previously hit `GET /:id` to retrieve only summary fields now
|
|
@@ -202,14 +198,13 @@ full masked record.
|
|
|
202
198
|
|
|
203
199
|
## Read-Only Resources
|
|
204
200
|
|
|
205
|
-
A resource that exposes only reads is valid with
|
|
206
|
-
no `crud` block at all):
|
|
201
|
+
A resource that exposes only reads is valid with no write-operation blocks at all:
|
|
207
202
|
|
|
208
203
|
```typescript
|
|
209
204
|
export default defineTable(balanceSnapshots, {
|
|
210
205
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
211
206
|
read: { access: { roles: ['member', 'admin'] } },
|
|
212
|
-
// no
|
|
207
|
+
// no create/update/delete/upsert — no writes
|
|
213
208
|
});
|
|
214
209
|
```
|
|
215
210
|
|
|
@@ -28,14 +28,12 @@ export default feature('jobs', {
|
|
|
28
28
|
createable: ["title", "department", "status", "salaryMin", "salaryMax"],
|
|
29
29
|
updatable: ["title", "department", "status"],
|
|
30
30
|
},
|
|
31
|
-
crud: {
|
|
32
|
-
create: { access: { roles: ["owner", "hiring-manager"] } },
|
|
33
|
-
update: { access: { roles: ["owner", "hiring-manager"] } },
|
|
34
|
-
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
35
|
-
},
|
|
36
31
|
read: {
|
|
37
32
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
38
33
|
},
|
|
34
|
+
create: { access: { roles: ["owner", "hiring-manager"] } },
|
|
35
|
+
update: { access: { roles: ["owner", "hiring-manager"] } },
|
|
36
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
39
37
|
});
|
|
40
38
|
```
|
|
41
39
|
|
|
@@ -59,8 +57,10 @@ export const jobs = q.table('jobs', {
|
|
|
59
57
|
|
|
60
58
|
export default defineTable(jobs, {
|
|
61
59
|
guards: { /* ... */ },
|
|
62
|
-
crud: { /* ... */ },
|
|
63
60
|
read: { /* ... */ },
|
|
61
|
+
create: { /* ... */ },
|
|
62
|
+
update: { /* ... */ },
|
|
63
|
+
delete: { /* ... */ },
|
|
64
64
|
});
|
|
65
65
|
|
|
66
66
|
export type Job = typeof jobs.$infer;
|
|
@@ -182,7 +182,9 @@ export default defineTable(jobs, {
|
|
|
182
182
|
createable: ["title", "department", "status", "salaryMin", "salaryMax"],
|
|
183
183
|
updatable: ["title", "department", "status"],
|
|
184
184
|
},
|
|
185
|
-
|
|
185
|
+
create: { /* ... */ },
|
|
186
|
+
update: { /* ... */ },
|
|
187
|
+
delete: { /* ... */ },
|
|
186
188
|
});
|
|
187
189
|
|
|
188
190
|
export type Job = typeof jobs.$inferSelect;
|
|
@@ -253,13 +255,13 @@ quickback/
|
|
|
253
255
|
```
|
|
254
256
|
|
|
255
257
|
**Key points:**
|
|
256
|
-
- Tables with `export default defineTable(...)` get
|
|
258
|
+
- Tables with `export default defineTable(...)` get resource routes generated
|
|
257
259
|
- Tables without a default export are internal (no routes, used for joins/relations)
|
|
258
260
|
- Route paths are derived from filenames: `applications.ts` → `/api/v1/applications`
|
|
259
261
|
|
|
260
262
|
### defineTable vs defineResource
|
|
261
263
|
|
|
262
|
-
- **`defineTable`** — The standard function for defining tables with
|
|
264
|
+
- **`defineTable`** — The standard function for defining tables with generated API routes
|
|
263
265
|
- **`defineResource`** — Deprecated. Still works but emits a warning during compilation. Use `defineTable` instead.
|
|
264
266
|
|
|
265
267
|
```typescript
|
|
@@ -269,7 +271,7 @@ export default defineTable(jobs, { /* config */ });
|
|
|
269
271
|
|
|
270
272
|
## 1 Resource = 1 Security Boundary
|
|
271
273
|
|
|
272
|
-
Each `defineTable()` call defines a complete, self-contained security boundary. The security config you write — firewall, access, guards, and masking — is compiled into a single resource file that wraps all
|
|
274
|
+
Each `defineTable()` call defines a complete, self-contained security boundary. The security config you write — firewall, access, guards, and masking — is compiled into a single resource file that wraps all generated routes for that table.
|
|
273
275
|
|
|
274
276
|
This is a deliberate design choice. Mixing two resources with different security rules in one configuration would create ambiguity about which firewall, access, or masking rules apply to which table. By keeping it 1:1, there's never any question.
|
|
275
277
|
|
|
@@ -287,7 +289,7 @@ For junction tables or internal data structures that shouldn't have API routes,
|
|
|
287
289
|
```typescript
|
|
288
290
|
// quickback/features/jobs/interview-scores.ts
|
|
289
291
|
|
|
290
|
-
// @quickback-internal — child table, no
|
|
292
|
+
// @quickback-internal — child table, no routes intentionally.
|
|
291
293
|
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
|
|
292
294
|
|
|
293
295
|
export const interviewScores = sqliteTable('interview_scores', {
|
|
@@ -297,7 +299,7 @@ export const interviewScores = sqliteTable('interview_scores', {
|
|
|
297
299
|
organizationId: text('organization_id').notNull(), // Scope junction tables for cascade soft-deletes
|
|
298
300
|
});
|
|
299
301
|
|
|
300
|
-
// No default export = no
|
|
302
|
+
// No default export = no routes generated
|
|
301
303
|
```
|
|
302
304
|
|
|
303
305
|
These internal tables still participate in the database schema and migrations — they just don't get API routes or security configuration. Without the `@quickback-internal` marker the compiler emits a warning per table, since the missing `defineTable` is more often a bug than a deliberate choice.
|
|
@@ -314,8 +316,6 @@ The compiler automatically injects the four **[audit fields](#audit-fields)** (`
|
|
|
314
316
|
> Unlike audit fields, the `id` column is your responsibility today. The CRUD/action route generators, FK probing, access checks, and OpenAPI emission all assume every queryable table has a single string-typed `id` column. Tables that omit it — or use a non-`id` single PK (`userId.primaryKey()`) or a compound `primaryKey({ columns: [...] })` constraint — parse fine but produce broken generated code downstream.
|
|
315
317
|
>
|
|
316
318
|
> Use `q.id()` (preferred) or `id: text("id").primaryKey()` / `id: integer("id").primaryKey({ autoIncrement: true })` on every table that participates in routes. For internal tables marked `// @quickback-internal`, the constraint doesn't apply.
|
|
317
|
-
>
|
|
318
|
-
> This asymmetry is being closed in **v0.14.8** — `injectIdField` will run unconditionally alongside audit injection, including on junction tables. See the [v0.14.7 changelog](/docs/changelog#coming-next--id-field-auto-injection-v0148) for the migration plan.
|
|
319
319
|
|
|
320
320
|
|
|
321
321
|
## Audit Fields
|
|
@@ -415,14 +415,14 @@ This turns off both layers — schema injection and the runtime wrapper.
|
|
|
415
415
|
| `deletedAt` | timestamp | Set when the record is soft-deleted |
|
|
416
416
|
| `deletedBy` | text | Actor that performed the soft delete (`ctx.userId`) |
|
|
417
417
|
|
|
418
|
-
The compiler injects them only when the resource uses soft delete — i.e. when neither `
|
|
418
|
+
The compiler injects them only when the resource uses soft delete — i.e. when neither `delete.mode` nor `delete.batch.mode` is explicitly `'hard'`. Soft is the default, so most tables get the columns. Tables with both delete paths set to `'hard'` skip them entirely, which also drops the `isNull(deletedAt)` predicate from the firewall WHERE clause.
|
|
419
419
|
|
|
420
420
|
```typescript
|
|
421
421
|
// soft delete (default) — table gets deletedAt + deletedBy
|
|
422
|
-
|
|
422
|
+
delete: {}
|
|
423
423
|
|
|
424
424
|
// hard delete — no deletedAt/deletedBy columns, no soft-delete predicate
|
|
425
|
-
|
|
425
|
+
delete: { mode: 'hard', batch: { mode: 'hard' } }
|
|
426
426
|
```
|
|
427
427
|
|
|
428
428
|
### Caller contract
|
|
@@ -701,6 +701,6 @@ export const jobs = pgTable('jobs', {
|
|
|
701
701
|
## Next Steps
|
|
702
702
|
|
|
703
703
|
- [Configure the firewall](/compiler/definitions/firewall) for data isolation
|
|
704
|
-
- [Set up access control](/compiler/definitions/access) for
|
|
704
|
+
- [Set up access control](/compiler/definitions/access) for read and write operations
|
|
705
705
|
- [Define guards](/compiler/definitions/guards) for field modification rules
|
|
706
706
|
- [Add custom actions](/compiler/definitions/actions) for business logic
|
|
@@ -371,10 +371,8 @@ export default defineTable(jobs, {
|
|
|
371
371
|
},
|
|
372
372
|
},
|
|
373
373
|
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
delete: { access: { roles: ['owner', 'hiring-manager'] } },
|
|
378
|
-
},
|
|
374
|
+
create: { access: { roles: ['owner', 'hiring-manager'] } },
|
|
375
|
+
update: { access: { roles: ['owner', 'hiring-manager'] } },
|
|
376
|
+
delete: { access: { roles: ['owner', 'hiring-manager'] } },
|
|
379
377
|
});
|
|
380
378
|
```
|
|
@@ -6,7 +6,7 @@ This example shows a complete resource definition using all five security layers
|
|
|
6
6
|
|
|
7
7
|
A `candidates` resource for a multi-tenant recruitment application with:
|
|
8
8
|
- Organization-level data isolation
|
|
9
|
-
- Role-based
|
|
9
|
+
- Role-based write permissions
|
|
10
10
|
- Field-level write protection
|
|
11
11
|
- PII masking for sensitive fields
|
|
12
12
|
- Column-level views for different access levels
|
|
@@ -57,12 +57,10 @@ export default feature('candidates', {
|
|
|
57
57
|
},
|
|
58
58
|
},
|
|
59
59
|
|
|
60
|
-
//
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
delete: { access: { roles: ['hiring-manager'] }, mode: 'hard' },
|
|
65
|
-
},
|
|
60
|
+
// WRITE OPERATIONS
|
|
61
|
+
create: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
62
|
+
update: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
63
|
+
delete: { access: { roles: ['hiring-manager'] }, mode: 'hard' },
|
|
66
64
|
});
|
|
67
65
|
```
|
|
68
66
|
|
|
@@ -211,7 +209,7 @@ export function maskCandidates<T extends Record<string, any>>(
|
|
|
211
209
|
return records.map(r => maskCandidate(r, ctx));
|
|
212
210
|
}
|
|
213
211
|
|
|
214
|
-
//
|
|
212
|
+
// Write access configuration (internal normalized shape)
|
|
215
213
|
export const CRUD_ACCESS = {
|
|
216
214
|
create: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
217
215
|
update: { access: { roles: ['hiring-manager', 'recruiter'] } },
|
|
@@ -89,11 +89,9 @@ export default defineTable(candidates, {
|
|
|
89
89
|
read: {
|
|
90
90
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
91
91
|
},
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
|
|
96
|
-
},
|
|
92
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
93
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
94
|
+
delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
|
|
97
95
|
});
|
|
98
96
|
```
|
|
99
97
|
|