@quickback-dev/cli 0.66.21 → 0.66.22
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/index.js +1 -1
- package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-prompts.js +11 -0
- package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +21 -51
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
- package/dist/lib/migrations/prompt-runner.js +6 -1
- package/dist/lib/migrations/prompt-runner.js.map +1 -1
- package/dist/skill/docs/api/actions.md +13 -6
- package/dist/skill/docs/api/batch-operations.md +6 -2
- package/dist/skill/docs/api/crud.md +72 -9
- package/dist/skill/docs/api/errors.md +78 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +6 -7
- package/dist/skill/docs/api/typescript.md +193 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +32 -7
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/guards.md +7 -2
- package/dist/skill/docs/define/masking.md +14 -0
- package/dist/skill/docs/define/read.md +3 -0
- package/dist/skill/docs/define/schema.md +13 -10
- package/dist/skill/docs/define/transitions.md +9 -4
- package/dist/skill/docs/index.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/payments/index.md +1 -1
- package/dist/skill/docs/start/frontend.md +278 -0
- package/dist/skill/docs/start/index.md +1 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +38 -9
- package/dist/skill/docs/tooling/troubleshooting.md +67 -0
- package/dist/skill/docs/ui/admin/actions.md +6 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
- package/dist/skill/docs/ui/admin/schema-format.md +74 -36
- package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
- package/dist/skill/docs/ui/admin/security.md +2 -2
- package/dist/skill/docs/ui/components/action-dialog.md +62 -0
- package/dist/skill/docs/ui/components/auth.md +90 -0
- package/dist/skill/docs/ui/components/index.md +48 -0
- package/dist/skill/docs/ui/components/install.md +118 -0
- package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
- package/dist/skill/docs/ui/components/resource-form.md +80 -0
- package/dist/skill/docs/ui/components/resource-table.md +46 -0
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +13 -6
- package/src/skill/docs/api/batch-operations.md +6 -2
- package/src/skill/docs/api/crud.md +72 -9
- package/src/skill/docs/api/errors.md +78 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +6 -7
- package/src/skill/docs/api/typescript.md +193 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +32 -7
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/guards.md +7 -2
- package/src/skill/docs/define/masking.md +14 -0
- package/src/skill/docs/define/read.md +3 -0
- package/src/skill/docs/define/schema.md +13 -10
- package/src/skill/docs/define/transitions.md +9 -4
- package/src/skill/docs/index.md +1 -0
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/payments/index.md +1 -1
- package/src/skill/docs/start/frontend.md +278 -0
- package/src/skill/docs/start/index.md +1 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +38 -9
- package/src/skill/docs/tooling/troubleshooting.md +67 -0
- package/src/skill/docs/ui/admin/actions.md +6 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/inline-editing.md +6 -2
- package/src/skill/docs/ui/admin/schema-format.md +74 -36
- package/src/skill/docs/ui/admin/schema-registry.md +22 -9
- package/src/skill/docs/ui/admin/security.md +2 -2
- package/src/skill/docs/ui/components/action-dialog.md +62 -0
- package/src/skill/docs/ui/components/auth.md +90 -0
- package/src/skill/docs/ui/components/index.md +48 -0
- package/src/skill/docs/ui/components/install.md +118 -0
- package/src/skill/docs/ui/components/quickback-provider.md +123 -0
- package/src/skill/docs/ui/components/resource-form.md +80 -0
- package/src/skill/docs/ui/components/resource-table.md +46 -0
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
The schema registry is a JSON file with a well-defined structure. Below are the complete TypeScript type definitions used by both the compiler (to generate) and the CMS (to consume).
|
|
4
4
|
|
|
5
|
+
The compiler's own definitions are emitted verbatim into
|
|
6
|
+
[`quickback.client.ts`](/api/typescript#fetch-client) as `SchemaRegistry`,
|
|
7
|
+
`TableMeta`, `ViewMeta`, `ValidationRule`, `ActionInputField` and friends —
|
|
8
|
+
import them from there rather than re-declaring them. Where the emitted type is
|
|
9
|
+
looser than the one shown here (`Record<string, unknown>` for `crud`,
|
|
10
|
+
`masking`, `firewall`), the shape below is what the CMS relies on.
|
|
11
|
+
|
|
5
12
|
## SchemaRegistry
|
|
6
13
|
|
|
7
14
|
The top-level type:
|
|
@@ -42,6 +49,7 @@ Full metadata for a single table:
|
|
|
42
49
|
interface TableMeta {
|
|
43
50
|
name: string;
|
|
44
51
|
dbName: string;
|
|
52
|
+
apiPath: string;
|
|
45
53
|
feature: string;
|
|
46
54
|
columns: ColumnMeta[];
|
|
47
55
|
firewall: Record<string, unknown>;
|
|
@@ -52,7 +60,7 @@ interface TableMeta {
|
|
|
52
60
|
upsert?: WriteOperationConfig | false;
|
|
53
61
|
guards: GuardsConfig;
|
|
54
62
|
masking: Record<string, MaskingRule>;
|
|
55
|
-
views: Record<string,
|
|
63
|
+
views: Record<string, ViewMeta>;
|
|
56
64
|
defaultView?: string;
|
|
57
65
|
requiresExplicitView?: true;
|
|
58
66
|
validation: Record<string, ValidationRule>;
|
|
@@ -65,6 +73,7 @@ interface TableMeta {
|
|
|
65
73
|
ownsRelations?: Record<string, OwnsRelation>;
|
|
66
74
|
ownedBy?: string;
|
|
67
75
|
readInclude?: string[];
|
|
76
|
+
emitsAfterCommit?: boolean;
|
|
68
77
|
routesDisabled?: string[];
|
|
69
78
|
}
|
|
70
79
|
|
|
@@ -79,8 +88,9 @@ interface OwnsRelation {
|
|
|
79
88
|
|
|
80
89
|
| Field | Description |
|
|
81
90
|
|-------|-------------|
|
|
82
|
-
| `name` | camelCase table name (e.g., `"accountCode"`) |
|
|
91
|
+
| `name` | camelCase table name (e.g., `"accountCode"`) — the key in `tables`, and in the client's `resources` |
|
|
83
92
|
| `dbName` | Snake_case SQL table name (e.g., `"account_code"`) |
|
|
93
|
+
| `apiPath` | Kebab-case URL segment (e.g., `"account-code"`) |
|
|
84
94
|
| `feature` | Parent feature name (e.g., `"accounting"`) |
|
|
85
95
|
| `columns` | Ordered array of column metadata |
|
|
86
96
|
| `firewall` | Tenant isolation config (organization, owner, softDelete, exception) |
|
|
@@ -101,6 +111,7 @@ interface OwnsRelation {
|
|
|
101
111
|
| `ownsRelations` | The [`owns`](/define/changesets) config verbatim — the CMS renders these as inline [owned-records sections](/ui/admin/owned-records) on the root's record page |
|
|
102
112
|
| `ownedBy` | Set on owned children: the aggregate-root table that owns this table |
|
|
103
113
|
| `readInclude` | The `read.include` allowlist — tokens fetchable via `?include=` |
|
|
114
|
+
| `emitsAfterCommit` | The aggregate root emits one CloudEvent after each changeset commit |
|
|
104
115
|
| `routesDisabled` | Ops declared `routes: false` — access exists (changeset admission) but no raw HTTP route, so the CMS suppresses New/Edit/Delete buttons and inline editing for them |
|
|
105
116
|
|
|
106
117
|
## ColumnMeta
|
|
@@ -174,7 +185,12 @@ interface AccessRule {
|
|
|
174
185
|
|
|
175
186
|
## GuardsConfig
|
|
176
187
|
|
|
177
|
-
Field-level control for create and update operations
|
|
188
|
+
Field-level control for create and update operations. `createable` and
|
|
189
|
+
`updatable` are the **resolved write policy**, not a copy of the table's
|
|
190
|
+
`guards` block: the compiler emits exactly the fields the generated `POST` /
|
|
191
|
+
`PATCH` routes accept — the same set the OpenAPI `<Table>Create` /
|
|
192
|
+
`<Table>Update` request bodies document. They are populated for every
|
|
193
|
+
resourceful table, including tables that declare no `guards`.
|
|
178
194
|
|
|
179
195
|
```typescript
|
|
180
196
|
interface GuardsConfig {
|
|
@@ -187,10 +203,13 @@ interface GuardsConfig {
|
|
|
187
203
|
|
|
188
204
|
| Field | Description |
|
|
189
205
|
|-------|-------------|
|
|
190
|
-
| `createable` | Fields
|
|
191
|
-
| `updatable` | Fields
|
|
192
|
-
| `immutable` |
|
|
193
|
-
| `protected` |
|
|
206
|
+
| `createable` | Fields `POST` accepts. With `guards`: `createable` plus `immutable`. Without: every column except the primary key. Both then drop audit columns, firewall/scope columns, and `protected` fields. Under `generateId: false` the client-supplied primary key is included; the optional id from `allowClientIds` is not. |
|
|
207
|
+
| `updatable` | Fields `PATCH` accepts. With `guards`: `updatable`. Without: every column except the primary key. Audit, firewall/scope, `immutable`, and `protected` fields are never included. |
|
|
208
|
+
| `immutable` | The declared `guards.immutable` list: set on create, never changed. |
|
|
209
|
+
| `protected` | The declared `guards.protected` map: fields only modifiable via the named actions. |
|
|
210
|
+
|
|
211
|
+
Columns with a default are included, since the route accepts them as optional.
|
|
212
|
+
Order follows `guards` when declared, otherwise column order.
|
|
194
213
|
|
|
195
214
|
## ActionMeta
|
|
196
215
|
|
|
@@ -244,9 +263,13 @@ interface CmsConfig {
|
|
|
244
263
|
|
|
245
264
|
interface ActionInputField {
|
|
246
265
|
name: string;
|
|
247
|
-
type: string;
|
|
266
|
+
type: string; // "string" | "number" | "boolean" | "enum" | "object" | "array<item>" | "unknown"
|
|
248
267
|
required: boolean;
|
|
249
268
|
default?: unknown;
|
|
269
|
+
enum?: Array<string | number | boolean>;
|
|
270
|
+
integer?: true;
|
|
271
|
+
nullable?: true;
|
|
272
|
+
description?: string;
|
|
250
273
|
}
|
|
251
274
|
```
|
|
252
275
|
|
|
@@ -275,33 +298,45 @@ If the action is already unambiguously table-scoped, the compiler can infer plac
|
|
|
275
298
|
|
|
276
299
|
### ActionInputField
|
|
277
300
|
|
|
301
|
+
One entry per top-level property of the action's input, derived from the
|
|
302
|
+
action's input **JSON Schema** — the same harvested `z.toJSONSchema()` output
|
|
303
|
+
that feeds OpenAPI and `Api.<x>.actions.<name>.Input` (a static parse of the
|
|
304
|
+
Zod source is the fallback when the harvest is unavailable). Enum values,
|
|
305
|
+
defaults and `.describe()` text survive.
|
|
306
|
+
|
|
278
307
|
| Field | Description |
|
|
279
308
|
|-------|-------------|
|
|
280
|
-
| `name` |
|
|
281
|
-
| `type` |
|
|
282
|
-
| `required` |
|
|
283
|
-
| `default` |
|
|
309
|
+
| `name` | Input property name |
|
|
310
|
+
| `type` | `"string"`, `"number"`, `"boolean"`, `"enum"`, `"object"`, `"array<item>"` (item type inside the brackets) or `"unknown"` |
|
|
311
|
+
| `required` | Listed in the schema's `required` and has no default |
|
|
312
|
+
| `default` | The schema default (`.default(x)`), pre-filled in the form |
|
|
313
|
+
| `enum` | Allowed values — `z.enum`, `z.literal`, or a union of literals |
|
|
314
|
+
| `integer` | `true` for `z.number().int()` (`type` stays `"number"`) |
|
|
315
|
+
| `nullable` | `true` when the field accepts `null` |
|
|
316
|
+
| `description` | The field's `.describe()` text |
|
|
284
317
|
|
|
285
|
-
##
|
|
318
|
+
## ViewMeta
|
|
286
319
|
|
|
287
320
|
Named column projection with access control:
|
|
288
321
|
|
|
289
322
|
```typescript
|
|
290
|
-
interface
|
|
323
|
+
interface ViewMeta {
|
|
291
324
|
fields: string[];
|
|
292
325
|
access: AccessRule;
|
|
293
|
-
query
|
|
294
|
-
filterable
|
|
295
|
-
searchable
|
|
326
|
+
query: {
|
|
327
|
+
filterable: string[] | null;
|
|
328
|
+
searchable: string[];
|
|
296
329
|
sortable?: string[];
|
|
297
330
|
defaultSort?: string;
|
|
298
331
|
};
|
|
332
|
+
aggregateOnly?: true;
|
|
299
333
|
}
|
|
300
334
|
```
|
|
301
335
|
|
|
302
336
|
| Field | Description |
|
|
303
337
|
|-------|-------------|
|
|
304
|
-
| `fields` |
|
|
338
|
+
| `fields` | The columns every row of this view carries, in order — always resolved (the view's projection, else every column; `[]` for an aggregate-only view), so a UI can lay out the view's columns before the first row arrives |
|
|
339
|
+
| `aggregateOnly` | `true` when the view returns only `aggregations`, no rows |
|
|
305
340
|
| `access` | Effective role-based access: the view override or inherited table `read.access` |
|
|
306
341
|
| `query` | Effective view query metadata. Explicit named-view allowlists are authoritative. Current registries materialize inherited `searchable` and q-table `filterable` defaults; `searchable: []` disables search, while `filterable: null` preserves raw Drizzle compatibility when no closed allowlist can be derived. |
|
|
307
342
|
|
|
@@ -361,44 +396,47 @@ interface MaskingRule {
|
|
|
361
396
|
|
|
362
397
|
| Type | Input | Output |
|
|
363
398
|
|------|-------|--------|
|
|
364
|
-
| `email` | `john@acme.com` | `j***@
|
|
365
|
-
| `phone` | `
|
|
366
|
-
| `ssn` | `123-45-6789` |
|
|
367
|
-
| `redact` |
|
|
399
|
+
| `email` | `john@acme.com` | `j***@a***.com` |
|
|
400
|
+
| `phone` | `555-123-4567` | `******4567` |
|
|
401
|
+
| `ssn` | `123-45-6789` | `*****6789` |
|
|
402
|
+
| `redact` | Anything | `[REDACTED]` |
|
|
403
|
+
|
|
404
|
+
A redacted non-string column (number, boolean, JSON, array) arrives as the
|
|
405
|
+
string `"[REDACTED]"` — see [Masking](/define/masking#non-string-columns).
|
|
368
406
|
|
|
369
407
|
## ValidationRule
|
|
370
408
|
|
|
371
|
-
Per-field validation constraints,
|
|
409
|
+
Per-field validation constraints, **read back from the Zod the API enforces**
|
|
410
|
+
on request bodies — the registry never advertises a rule the server doesn't
|
|
411
|
+
check. The CMS uses them to render the right control and validate before it
|
|
412
|
+
POSTs:
|
|
372
413
|
|
|
373
414
|
```typescript
|
|
374
415
|
interface ValidationRule {
|
|
375
|
-
|
|
416
|
+
enum?: string[];
|
|
376
417
|
maxLength?: number;
|
|
418
|
+
minLength?: number;
|
|
377
419
|
min?: number;
|
|
378
420
|
max?: number;
|
|
379
|
-
|
|
380
|
-
|
|
421
|
+
integer?: boolean;
|
|
422
|
+
pattern?: string;
|
|
381
423
|
url?: boolean;
|
|
424
|
+
email?: boolean;
|
|
382
425
|
}
|
|
383
426
|
```
|
|
384
427
|
|
|
385
428
|
| Rule | Emitted from |
|
|
386
429
|
|------|--------------|
|
|
387
430
|
| `enum` | `q.enum([...])`, or `text(..., { enum: [...] })` in raw Drizzle — the CMS renders a select |
|
|
388
|
-
| `url` | `q.url()` — the CMS renders a `url` input; the API
|
|
431
|
+
| `url` | `q.url()` — the CMS renders a `url` input; the API accepts only absolute `http(s)` URLs (so not `""`, `javascript:` or `data:`) |
|
|
389
432
|
| `maxLength` | `q.text({ maxLength })` / `q.url({ maxLength })` |
|
|
433
|
+
| `integer` | `q.int()`, `q.bigint()`, `q.smallint()` — whole numbers only |
|
|
434
|
+
| `min` / `max` | `q.bigint()` (±2^53−1, the JSON-safe range) and `q.smallint()` (−32768…32767), inclusive |
|
|
435
|
+
| `pattern` | `q.decimal({ precision, scale })` — the regex source the decimal string must match |
|
|
436
|
+
| `minLength` / `email` | Only when the enforced Zod carries `.min(n)` / `.email()`; no q column kind emits them today |
|
|
390
437
|
|
|
391
438
|
Columns with no constraints have no entry. Optional fields left blank in the CMS form are omitted from the request body rather than sent as `""` — the API accepts an optional field being absent, not empty.
|
|
392
439
|
|
|
393
|
-
| Field | Description |
|
|
394
|
-
|-------|-------------|
|
|
395
|
-
| `minLength` | Minimum string length |
|
|
396
|
-
| `maxLength` | Maximum string length |
|
|
397
|
-
| `min` | Minimum numeric value |
|
|
398
|
-
| `max` | Maximum numeric value |
|
|
399
|
-
| `enum` | Array of allowed string values |
|
|
400
|
-
| `email` | When `true`, validates email format |
|
|
401
|
-
|
|
402
440
|
## PageMeta
|
|
403
441
|
|
|
404
442
|
Full metadata for a custom page:
|
|
@@ -15,6 +15,17 @@ export default defineConfig({
|
|
|
15
15
|
});
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
+
## Serving and access
|
|
19
|
+
|
|
20
|
+
The registry is served, auth-gated, at `GET /api/v1/schema` — never bundled
|
|
21
|
+
into a frontend. The CMS loads it there; so does
|
|
22
|
+
[`api.schema()`](/api/typescript#fetch-client) in the generated fetch client,
|
|
23
|
+
which types the response as the compiler's own `SchemaRegistry`. The route
|
|
24
|
+
admits platform sysadmins by default; `cms.access: "member"` or, for a
|
|
25
|
+
frontend without the CMS,
|
|
26
|
+
[`schemaRegistry.access`](/configure#schema-registry-access) (`"member"` or
|
|
27
|
+
`"authenticated"`) opens it to your users.
|
|
28
|
+
|
|
18
29
|
## Output Shape
|
|
19
30
|
|
|
20
31
|
The top-level structure of `schema-registry.json`:
|
|
@@ -64,13 +75,13 @@ interface TableMeta {
|
|
|
64
75
|
delete?: WriteOperationConfig | false; // Flat delete config
|
|
65
76
|
upsert?: WriteOperationConfig | false; // Flat upsert config
|
|
66
77
|
guards: {
|
|
67
|
-
createable: string[]; //
|
|
68
|
-
updatable: string[]; //
|
|
78
|
+
createable: string[]; // Resolved: exactly what POST accepts (set even without `guards`)
|
|
79
|
+
updatable: string[]; // Resolved: exactly what PATCH accepts
|
|
69
80
|
immutable: string[]; // Fields locked after creation
|
|
70
81
|
protected: Record<string, string[]>; // Fields writable only via named actions/transitions
|
|
71
82
|
};
|
|
72
83
|
masking: Record<string, MaskingRule>; // Per-field masking rules
|
|
73
|
-
views: Record<string,
|
|
84
|
+
views: Record<string, ViewMeta>; // Named column projections
|
|
74
85
|
defaultView?: string; // Authored read.defaultView
|
|
75
86
|
requiresExplicitView?: true; // Named views exist with no default
|
|
76
87
|
validation: Record<string, ValidationRule>; // Per-field validation
|
|
@@ -83,19 +94,21 @@ interface TableMeta {
|
|
|
83
94
|
Each named view carries the effective read contract the CMS consumes:
|
|
84
95
|
|
|
85
96
|
```typescript
|
|
86
|
-
interface
|
|
87
|
-
fields: string[];
|
|
97
|
+
interface ViewMeta {
|
|
98
|
+
fields: string[]; // always resolved: the projection, else every column; [] if aggregate-only
|
|
88
99
|
access: AccessRule;
|
|
89
|
-
query
|
|
90
|
-
filterable
|
|
91
|
-
searchable
|
|
100
|
+
query: {
|
|
101
|
+
filterable: string[] | null;
|
|
102
|
+
searchable: string[];
|
|
92
103
|
sortable?: string[];
|
|
93
104
|
defaultSort?: string;
|
|
94
105
|
};
|
|
106
|
+
aggregateOnly?: true;
|
|
95
107
|
}
|
|
96
108
|
```
|
|
97
109
|
|
|
98
|
-
|
|
110
|
+
`fields` is always the resolved column list, so a table can render a view's
|
|
111
|
+
header before its first row arrives. For current registries, `access` is the view's explicit access rule or the
|
|
99
112
|
inherited table `read.access` when the view omits an override.
|
|
100
113
|
`query.searchable` is likewise the effective search allowlist: the explicit
|
|
101
114
|
view list when present, otherwise the compiler's eligible table search fields
|
|
@@ -13,7 +13,7 @@ cms: { access: "member" }
|
|
|
13
13
|
The shell is served to any signed-in caller so the SPA can explain who is and isn't admitted; the gates that carry data are:
|
|
14
14
|
|
|
15
15
|
1. **Account UI** — the profile CMS action is hidden for callers who wouldn't get in; admitted members select and activate an organization before navigation.
|
|
16
|
-
2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
16
|
+
2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement to a signed-in caller without the role, and `401 AUTH_MISSING` to an anonymous one. Without the registry there is no CMS.
|
|
17
17
|
3. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, or organization membership plus sysadmin in `"member"` mode.
|
|
18
18
|
4. **In-SPA gate** — the SPA renders the matching blocked, membership-picker, or sysadmin-scope screen before loading CMS data.
|
|
19
19
|
|
|
@@ -66,7 +66,7 @@ The row action menu also adapts — Edit and Delete entries only appear when the
|
|
|
66
66
|
|
|
67
67
|
## Guards
|
|
68
68
|
|
|
69
|
-
Guards control which fields appear in create and edit forms, and which cells are editable in Data Table mode.
|
|
69
|
+
Guards control which fields appear in create and edit forms, and which cells are editable in Data Table mode. The registry's `createable` / `updatable` lists are the compiler-resolved write policy, the exact fields the API accepts. A table without `guards` still gets full forms with every column except system and scope columns.
|
|
70
70
|
|
|
71
71
|
### Createable Fields
|
|
72
72
|
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# action-dialog
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
npx shadcn add @quickback/action-dialog
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { useState } from "react"
|
|
9
|
+
import { buttonVariants } from "@/components/ui/button"
|
|
10
|
+
import { ActionDialog } from "@/components/action-dialog"
|
|
11
|
+
|
|
12
|
+
function CloseJobButton({ id }: { id: string }) {
|
|
13
|
+
const [open, setOpen] = useState(false)
|
|
14
|
+
return (
|
|
15
|
+
<>
|
|
16
|
+
<button type="button" className={buttonVariants({ variant: "outline" })} onClick={() => setOpen(true)}>
|
|
17
|
+
Close
|
|
18
|
+
</button>
|
|
19
|
+
<ActionDialog table="jobs" action="close" id={id} open={open} onOpenChange={setOpen} />
|
|
20
|
+
</>
|
|
21
|
+
)
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The dialog is **controlled**. You own `open` and render your own trigger. It
|
|
26
|
+
ships no trigger, so it never needs base-ui's `render=` or Radix's `asChild`.
|
|
27
|
+
|
|
28
|
+
## Props
|
|
29
|
+
|
|
30
|
+
| Prop | Type | Description |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `table` | `string` | Schema-registry table name. Required. |
|
|
33
|
+
| `action` | `string` | Action name as declared on the table. Required. |
|
|
34
|
+
| `id` | `string` | Record id. Required for [record-bound actions](/define/actions/record-and-standalone). Leave it out for standalone ones. |
|
|
35
|
+
| `params` | `Record<string, string>` | Path parameters for standalone actions whose `path` has them. |
|
|
36
|
+
| `open` | `boolean` | Required. |
|
|
37
|
+
| `onOpenChange` | `(open: boolean) => void` | Required. |
|
|
38
|
+
| `onSuccess` | `(output: unknown) => void` | Called with the action's output. |
|
|
39
|
+
|
|
40
|
+
## Behavior
|
|
41
|
+
|
|
42
|
+
- **Inputs** come from the action's `inputFields` in the schema registry.
|
|
43
|
+
Enums render as selects, booleans as checkboxes, and numbers as number
|
|
44
|
+
inputs. Everything else renders as text. Array inputs take a
|
|
45
|
+
comma-separated list. Empty fields are left out of the input.
|
|
46
|
+
- **Title and description** come from the action's `cms.label` (else its
|
|
47
|
+
name) and its `description`.
|
|
48
|
+
- **Confirmation.** An action with [`cms.destructive`](/ui/admin/actions)
|
|
49
|
+
or `cms.confirm` asks before it runs. A string `confirm` is the message.
|
|
50
|
+
Otherwise the dialog asks `<Action> can't be undone. Continue?`
|
|
51
|
+
(destructive) or `Run <Action>?`. `confirm: false` never asks.
|
|
52
|
+
- **Access.** When the caller's [roles](/ui/components/quickback-provider#roles)
|
|
53
|
+
plainly fail the action's `access.roles`, the dialog shows
|
|
54
|
+
`Your role can't run <Action>.` instead of the form.
|
|
55
|
+
- **On success**, the dialog shows "Done." and the output as JSON. Every
|
|
56
|
+
cached query for the table is invalidated, so an open `ResourceTable`
|
|
57
|
+
refreshes.
|
|
58
|
+
- **On error**, the problem's `detail` shows at the top. Per-field messages
|
|
59
|
+
show under their inputs. Guard rejections, access denials (`403`), and
|
|
60
|
+
failed record preconditions all arrive this way.
|
|
61
|
+
- An unknown `action` shows `"<name>" is not an action on <Table>.` Calling a record-bound
|
|
62
|
+
action without `id` fails with `Action "<name>" on "<table>" needs a record id`.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Auth
|
|
2
|
+
|
|
3
|
+
The components never touch credentials. The emitted client you pass to
|
|
4
|
+
`<QuickbackProvider client>` decides how each request is authenticated.
|
|
5
|
+
|
|
6
|
+
| Mode | Use it for | Credential | Writes need |
|
|
7
|
+
|---|---|---|---|
|
|
8
|
+
| `auth: "cookie"` (default) | Browser apps | Better Auth session cookie, `credentials: "include"` | The page's origin in the trusted origins |
|
|
9
|
+
| `auth: "bearer"` | React Native, CLIs, servers | `Authorization: Bearer <token>` | Nothing extra. Bearer requests skip the CSRF origin check. |
|
|
10
|
+
|
|
11
|
+
## Browser: cookie
|
|
12
|
+
|
|
13
|
+
Sign in with Better Auth's own client. The session cookie it sets is what the
|
|
14
|
+
Quickback client sends.
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
import { createAuthClient } from "better-auth/react"
|
|
18
|
+
import { organizationClient } from "better-auth/client/plugins"
|
|
19
|
+
import { createClient } from "@/lib/quickback.client"
|
|
20
|
+
|
|
21
|
+
const baseURL = import.meta.env.VITE_API_URL // e.g. http://localhost:8787
|
|
22
|
+
|
|
23
|
+
export const auth = createAuthClient({
|
|
24
|
+
baseURL,
|
|
25
|
+
basePath: "/auth/v1",
|
|
26
|
+
plugins: [organizationClient()],
|
|
27
|
+
})
|
|
28
|
+
|
|
29
|
+
export const client = createClient({ baseUrl: baseURL })
|
|
30
|
+
|
|
31
|
+
await auth.signIn.email({ email, password })
|
|
32
|
+
// Tenant-scoped tables are firewalled to the session's active organization.
|
|
33
|
+
await auth.organization.setActive({ organizationId })
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The cookie only works if the API trusts your page's origin:
|
|
37
|
+
|
|
38
|
+
- **Same Worker (recommended).** Mount the built app with
|
|
39
|
+
[`apps.<name>`](/configure/domains#app-domains). It is then served on the
|
|
40
|
+
same origin as `/api` and `/auth`, and its hostname is trusted
|
|
41
|
+
automatically.
|
|
42
|
+
- **Local dev.** Until a project has a production domain, `http://localhost:5173`
|
|
43
|
+
(Vite), `:3000`, and `:8787` are trusted by default.
|
|
44
|
+
- **Anywhere else.** Add the origin to
|
|
45
|
+
[`trustedOrigins`](/configure#trusted-origins). A write from an untrusted
|
|
46
|
+
origin fails with `403 CSRF_ORIGIN_REJECTED`, and the browser blocks reads
|
|
47
|
+
through CORS.
|
|
48
|
+
|
|
49
|
+
## React Native and other non-browser clients: bearer
|
|
50
|
+
|
|
51
|
+
React Native has no cookie jar and sends no `Origin` header. Cookie-backed
|
|
52
|
+
writes therefore fail with `403 CSRF_ORIGIN_REJECTED`. Use the bearer lane
|
|
53
|
+
instead:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import * as SecureStore from "expo-secure-store"
|
|
57
|
+
import { createClient } from "@/lib/quickback.client"
|
|
58
|
+
|
|
59
|
+
const KEY = "quickback_session"
|
|
60
|
+
|
|
61
|
+
export const client = createClient({
|
|
62
|
+
baseUrl: "https://api.example.com",
|
|
63
|
+
auth: "bearer",
|
|
64
|
+
sessionStore: {
|
|
65
|
+
get: () => SecureStore.getItemAsync(KEY),
|
|
66
|
+
set: (token) => (token ? SecureStore.setItemAsync(KEY, token) : SecureStore.deleteItemAsync(KEY)),
|
|
67
|
+
},
|
|
68
|
+
})
|
|
69
|
+
|
|
70
|
+
// set-auth-token on /auth/v1/* is saved to sessionStore.
|
|
71
|
+
await client.request("POST", "/auth/v1/sign-in/email", { body: { email, password } })
|
|
72
|
+
await client.request("POST", "/auth/v1/organization/set-active", { body: { organizationId } })
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Sign in **through the client**, as above. It saves the `set-auth-token`
|
|
76
|
+
**header**: the signed `<token>.<signature>`. If you sign in with your own
|
|
77
|
+
`fetch`, store that header too, never the body's `token`. The body carries
|
|
78
|
+
the raw session id, and the generated API runs Better Auth's
|
|
79
|
+
`bearer({ requireSignature: true })`. An unsigned token is silently ignored:
|
|
80
|
+
`get-session` returns `null` and every API call answers `401`.
|
|
81
|
+
|
|
82
|
+
With `auth: "bearer"`, the client:
|
|
83
|
+
|
|
84
|
+
- sends `Authorization: Bearer <token>` and defaults `credentials` to `"omit"`;
|
|
85
|
+
- caches the short-lived JWT that API responses return in `set-auth-token`
|
|
86
|
+
(see [JWT optimization](/platform/auth/jwt-optimization));
|
|
87
|
+
- on a `401` with a cached JWT, drops the JWT and retries once with the
|
|
88
|
+
session token from `sessionStore`.
|
|
89
|
+
|
|
90
|
+
Full lane semantics: [Bearer lane](/api/typescript#bearer-lane-react-native-native-clients).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Components
|
|
2
|
+
|
|
3
|
+
Add tables, forms, and action dialogs for your API to your own React app with
|
|
4
|
+
`shadcn add`. There's no fork of the CMS and no admin framework involved. Each
|
|
5
|
+
component is a file in your repo, and you edit it like any other code.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Two layers
|
|
12
|
+
|
|
13
|
+
| Layer | Who owns it | Regenerated? | Knows the wire format? |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| `quickback.client.ts` | The compiler emits it (`client` config) | Every compile | **Yes. Only this file does.** |
|
|
16
|
+
| `quickback-provider`, `resource-table`, `resource-form`, `action-dialog` | You. `shadcn add` copies them into your repo | Never | No |
|
|
17
|
+
|
|
18
|
+
The components never build a URL, unwrap a list envelope, or parse
|
|
19
|
+
`application/problem+json`. They call the emitted
|
|
20
|
+
[fetch client](/api/typescript#fetch-client) and read the
|
|
21
|
+
[schema registry](/ui/admin/schema-registry) for column kinds, guards, and
|
|
22
|
+
action inputs. When the API changes shape, you recompile and only the client
|
|
23
|
+
changes. Your edits to the components survive.
|
|
24
|
+
|
|
25
|
+
## Base-ui only
|
|
26
|
+
|
|
27
|
+
The items target shadcn's **base-ui** styles (`base-nova`, `base-mira`, …).
|
|
28
|
+
Radix styles are not supported.
|
|
29
|
+
|
|
30
|
+
- They compose your own primitives (`button`, `dialog`, `table`, …) through
|
|
31
|
+
`registryDependencies`, using base-ui's `render=` prop where composition is
|
|
32
|
+
needed.
|
|
33
|
+
- They never use Radix's `asChild`. On a base-ui project, `shadcn add`
|
|
34
|
+
silently rewrites `asChild` to `render={<firstChild />}`. That still
|
|
35
|
+
typechecks but drops the other children.
|
|
36
|
+
- The namespace URL includes the style (`/r/{style}/{name}.json`), and only
|
|
37
|
+
`base-*` paths exist. A Radix project therefore fails at **install**, with a
|
|
38
|
+
`404` that names its style, before any file is written.
|
|
39
|
+
|
|
40
|
+
## Pages
|
|
41
|
+
|
|
42
|
+
- [Install](/ui/components/install): the `client` config, the `@quickback` namespace, and direct URLs
|
|
43
|
+
- [Auth](/ui/components/auth): cookie vs bearer, React Native
|
|
44
|
+
- [`quickback-provider`](/ui/components/quickback-provider): `<QuickbackProvider>` and the TanStack Query hooks
|
|
45
|
+
- [`resource-table`](/ui/components/resource-table): paginated, sortable, searchable list
|
|
46
|
+
- [`resource-form`](/ui/components/resource-form): create / edit form
|
|
47
|
+
- [`action-dialog`](/ui/components/action-dialog): run an action with its inputs
|
|
48
|
+
- [Build a frontend](/start/frontend): end-to-end guide
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Install
|
|
2
|
+
|
|
3
|
+
## Requirements
|
|
4
|
+
|
|
5
|
+
- A React app initialised with a shadcn **base-ui** style. `components.json` has `"style": "base-…"`. For a new Vite app:
|
|
6
|
+
`npx shadcn@latest init -t vite -b base -p nova`
|
|
7
|
+
- The `@/` import alias. The shadcn templates set it up.
|
|
8
|
+
- The emitted client at `@/lib/quickback.client`. Every item imports it from that path.
|
|
9
|
+
|
|
10
|
+
## 1. Emit the client into the frontend
|
|
11
|
+
|
|
12
|
+
In `quickback.config.ts`, point `client` at the frontend's `src/lib/`. Put
|
|
13
|
+
the `types` output next to it. The client imports `Api` and `Qb` from the
|
|
14
|
+
first `types` output by relative path, so keeping both inside the frontend
|
|
15
|
+
keeps its `tsconfig` self-contained.
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { defineConfig } from "@quickback/compiler";
|
|
19
|
+
|
|
20
|
+
export default defineConfig({
|
|
21
|
+
name: "my-app",
|
|
22
|
+
types: { output: "web/src/lib/quickback.gen.ts" },
|
|
23
|
+
client: "web/src/lib/quickback.client.ts",
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`client` requires `types`. The compile fails if `types` is `false`.
|
|
28
|
+
`quickback build` rewrites both files on every compile. Don't edit them. See
|
|
29
|
+
[Fetch client](/api/typescript#fetch-client) for the full client API.
|
|
30
|
+
|
|
31
|
+
The components read the schema registry from `GET /api/v1/schema`. By
|
|
32
|
+
default only platform sysadmins may read it. For a UI that other users use,
|
|
33
|
+
widen it with [`schemaRegistry.access`](/configure#schema-registry-access):
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
schemaRegistry: { access: "member" }, // any organization member
|
|
38
|
+
// schemaRegistry: { access: "authenticated" }, // any signed-in user (apps without organizations)
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Without this, every component shows a `403 CMS_ACCESS_DENIED` error. When
|
|
43
|
+
`cms` is also enabled, `schemaRegistry.access` must equal `cms.access`. The
|
|
44
|
+
route gates the CMS too, so widening one must not silently widen the other.
|
|
45
|
+
|
|
46
|
+
## 2. Add the registry
|
|
47
|
+
|
|
48
|
+
**Namespace (recommended).** Add the registry to the frontend's
|
|
49
|
+
`components.json`:
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"registries": {
|
|
54
|
+
"@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx shadcn add @quickback/quickback-provider @quickback/resource-table @quickback/resource-form @quickback/action-dialog
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
shadcn fills `{style}` from `components.json`. Only `base-*` style paths
|
|
64
|
+
exist, so a Radix project stops here with nothing written:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
The item at https://docs.quickback.dev/r/radix-nova/resource-table.json was not found. It may not exist at the registry.
|
|
68
|
+
Message:
|
|
69
|
+
[Quickback registry items support shadcn base-ui styles only; "radix-nova" is not one. See https://docs.quickback.dev/ui/components]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Direct URL.** Add one item without configuring the namespace:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npx shadcn add https://docs.quickback.dev/r/resource-table.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Direct URLs resolve `quickback-provider` for you, but they skip the style
|
|
79
|
+
check. Use them only on a base-ui project.
|
|
80
|
+
|
|
81
|
+
| URL | Serves |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `https://docs.quickback.dev/r/registry.json` | Registry index |
|
|
84
|
+
| `https://docs.quickback.dev/r/{name}.json` | One item (direct-URL installs) |
|
|
85
|
+
| `https://docs.quickback.dev/r/base-{style}/{name}.json` | One item (namespace installs) |
|
|
86
|
+
|
|
87
|
+
`{name}` is one of `quickback-provider`, `resource-table`, `resource-form`, `action-dialog`.
|
|
88
|
+
|
|
89
|
+
## 3. What gets installed
|
|
90
|
+
|
|
91
|
+
| Item | Files | Also installs |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| `quickback-provider` | `components/quickback-provider.tsx` | `@tanstack/react-query@^5` |
|
|
94
|
+
| `resource-table` | `components/resource-table.tsx` | `button`, `dropdown-menu`, `input`, `label`, `table`, `@remixicon/react` |
|
|
95
|
+
| `resource-form` | `components/resource-form.tsx` | `button`, `checkbox`, `combobox`, `input`, `label`, `native-select`, `textarea`, `@remixicon/react` |
|
|
96
|
+
| `action-dialog` | `components/action-dialog.tsx` | `button`, `checkbox`, `dialog`, `input`, `label`, `native-select`, `@remixicon/react` |
|
|
97
|
+
|
|
98
|
+
Every item except `quickback-provider` depends on it, so adding any one of
|
|
99
|
+
them pulls it in. Re-run `shadcn add` with `--overwrite` to take a newer
|
|
100
|
+
version. That replaces any local edits you made to those files.
|
|
101
|
+
|
|
102
|
+
## 4. Wire it up
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
// web/src/main.tsx
|
|
106
|
+
import { createClient } from "@/lib/quickback.client"
|
|
107
|
+
import { QuickbackProvider } from "@/components/quickback-provider"
|
|
108
|
+
|
|
109
|
+
const client = createClient({ baseUrl: import.meta.env.VITE_API_URL })
|
|
110
|
+
|
|
111
|
+
createRoot(document.getElementById("root")!).render(
|
|
112
|
+
<QuickbackProvider client={client}>
|
|
113
|
+
<App />
|
|
114
|
+
</QuickbackProvider>,
|
|
115
|
+
)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Next: [Auth](/ui/components/auth) to sign users in. For the whole flow, see [Build a frontend](/start/frontend).
|