@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.
Files changed (84) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  3. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  5. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  6. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  7. package/dist/lib/migrations/file-envelopes.js +21 -51
  8. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  9. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  10. package/dist/lib/migrations/prompt-runner.js +6 -1
  11. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  12. package/dist/skill/docs/api/actions.md +13 -6
  13. package/dist/skill/docs/api/batch-operations.md +6 -2
  14. package/dist/skill/docs/api/crud.md +72 -9
  15. package/dist/skill/docs/api/errors.md +78 -6
  16. package/dist/skill/docs/api/openapi.md +1 -1
  17. package/dist/skill/docs/api/query-params.md +6 -7
  18. package/dist/skill/docs/api/typescript.md +193 -0
  19. package/dist/skill/docs/configure/index.md +36 -2
  20. package/dist/skill/docs/configure/providers.md +32 -7
  21. package/dist/skill/docs/define/changesets.md +2 -0
  22. package/dist/skill/docs/define/guards.md +7 -2
  23. package/dist/skill/docs/define/masking.md +14 -0
  24. package/dist/skill/docs/define/read.md +3 -0
  25. package/dist/skill/docs/define/schema.md +13 -10
  26. package/dist/skill/docs/define/transitions.md +9 -4
  27. package/dist/skill/docs/index.md +1 -0
  28. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  29. package/dist/skill/docs/platform/payments/index.md +1 -1
  30. package/dist/skill/docs/start/frontend.md +278 -0
  31. package/dist/skill/docs/start/index.md +1 -0
  32. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  33. package/dist/skill/docs/tooling/output.md +38 -9
  34. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  35. package/dist/skill/docs/ui/admin/actions.md +6 -2
  36. package/dist/skill/docs/ui/admin/index.md +1 -1
  37. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  38. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  39. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  40. package/dist/skill/docs/ui/admin/security.md +2 -2
  41. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  42. package/dist/skill/docs/ui/components/auth.md +90 -0
  43. package/dist/skill/docs/ui/components/index.md +48 -0
  44. package/dist/skill/docs/ui/components/install.md +118 -0
  45. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  46. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  47. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  48. package/package.json +1 -1
  49. package/src/skill/docs/api/actions.md +13 -6
  50. package/src/skill/docs/api/batch-operations.md +6 -2
  51. package/src/skill/docs/api/crud.md +72 -9
  52. package/src/skill/docs/api/errors.md +78 -6
  53. package/src/skill/docs/api/openapi.md +1 -1
  54. package/src/skill/docs/api/query-params.md +6 -7
  55. package/src/skill/docs/api/typescript.md +193 -0
  56. package/src/skill/docs/configure/index.md +36 -2
  57. package/src/skill/docs/configure/providers.md +32 -7
  58. package/src/skill/docs/define/changesets.md +2 -0
  59. package/src/skill/docs/define/guards.md +7 -2
  60. package/src/skill/docs/define/masking.md +14 -0
  61. package/src/skill/docs/define/read.md +3 -0
  62. package/src/skill/docs/define/schema.md +13 -10
  63. package/src/skill/docs/define/transitions.md +9 -4
  64. package/src/skill/docs/index.md +1 -0
  65. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  66. package/src/skill/docs/platform/payments/index.md +1 -1
  67. package/src/skill/docs/start/frontend.md +278 -0
  68. package/src/skill/docs/start/index.md +1 -0
  69. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  70. package/src/skill/docs/tooling/output.md +38 -9
  71. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  72. package/src/skill/docs/ui/admin/actions.md +6 -2
  73. package/src/skill/docs/ui/admin/index.md +1 -1
  74. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  75. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  76. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  77. package/src/skill/docs/ui/admin/security.md +2 -2
  78. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  79. package/src/skill/docs/ui/components/auth.md +90 -0
  80. package/src/skill/docs/ui/components/index.md +48 -0
  81. package/src/skill/docs/ui/components/install.md +118 -0
  82. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  83. package/src/skill/docs/ui/components/resource-form.md +80 -0
  84. 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, ViewConfig>;
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 that can be set during record creation |
191
- | `updatable` | Fields that can be modified on existing records |
192
- | `immutable` | Fields that can be set on create but never changed |
193
- | `protected` | Fields only modifiable via named actions (field name to action names) |
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` | Field identifier |
281
- | `type` | Zod type string: `"string"`, `"number"`, `"boolean"`, `"array<string>"` |
282
- | `required` | Whether the field must be provided |
283
- | `default` | Default value pre-filled in the form |
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
- ## ViewConfig
318
+ ## ViewMeta
286
319
 
287
320
  Named column projection with access control:
288
321
 
289
322
  ```typescript
290
- interface ViewConfig {
323
+ interface ViewMeta {
291
324
  fields: string[];
292
325
  access: AccessRule;
293
- query?: {
294
- filterable?: string[] | null;
295
- searchable?: string[];
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` | Array of column names to include in this view |
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***@acme.com` |
365
- | `phone` | `(555) 123-4567` | `***-***-4567` |
366
- | `ssn` | `123-45-6789` | `***-**-6789` |
367
- | `redact` | Any string | `------` |
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, mirrored from the Zod the API enforces on request bodies so the CMS can render the right control and validate before it POSTs:
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
- minLength?: number;
416
+ enum?: string[];
376
417
  maxLength?: number;
418
+ minLength?: number;
377
419
  min?: number;
378
420
  max?: number;
379
- enum?: string[];
380
- email?: boolean;
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 rejects anything `new URL()` can't parse, including `""` |
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[]; // Fields allowed on create
68
- updatable: string[]; // Fields allowed on update
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, ViewConfig>; // Named column projections
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 ViewConfig {
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?: string[] | null;
91
- searchable?: string[];
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
- For current registries, `access` is the view's explicit access rule or the
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).