@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
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# quickback-provider
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
npx shadcn add @quickback/quickback-provider
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Installs `components/quickback-provider.tsx` and `@tanstack/react-query@^5`.
|
|
8
|
+
The other items import their hooks from it.
|
|
9
|
+
|
|
10
|
+
## `<QuickbackProvider>`
|
|
11
|
+
|
|
12
|
+
```tsx
|
|
13
|
+
import { createClient } from "@/lib/quickback.client"
|
|
14
|
+
import { QuickbackProvider } from "@/components/quickback-provider"
|
|
15
|
+
|
|
16
|
+
const client = createClient({ baseUrl: "https://api.example.com" })
|
|
17
|
+
|
|
18
|
+
<QuickbackProvider client={client} roles={roles}>
|
|
19
|
+
<App />
|
|
20
|
+
</QuickbackProvider>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Description |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `client` | `Client` | The result of `createClient()` from the emitted `@/lib/quickback.client`. Required. |
|
|
26
|
+
| `roles` | `readonly string[]` | The signed-in caller's roles, e.g. the active organization member role from Better Auth. A UI hint only. See [Roles](#roles). |
|
|
27
|
+
| `realtime` | `{ subscribe(handler) => unsubscribe }` | Source of realtime frames for `useLive`. Defaults to `client.realtime` when the emitted client has one. |
|
|
28
|
+
| `queryClient` | `QueryClient` | Share your app's TanStack Query cache. Omit it and the provider creates one that retries network errors and `5xx` twice and never retries a `4xx`. |
|
|
29
|
+
| `children` | `ReactNode` | |
|
|
30
|
+
|
|
31
|
+
## Hooks
|
|
32
|
+
|
|
33
|
+
Every hook takes a **schema-registry table name** (`"jobs"`). The name is
|
|
34
|
+
resolved through the client's `resources` table, so generic UI never
|
|
35
|
+
hard-codes a URL. An unknown name throws `Unknown Quickback resource "<name>"`.
|
|
36
|
+
Calling a verb the table has no route for throws `"<table>" has no <verb> route`.
|
|
37
|
+
|
|
38
|
+
| Hook | Returns | Notes |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| `useQuickback()` | `Client` | The typed client. Use it for anything the hooks don't cover. |
|
|
41
|
+
| `useRoles()` | `readonly string[] \| undefined` | The `roles` passed to the provider. |
|
|
42
|
+
| `useSchema()` | query of `SchemaRegistry` | `GET /api/v1/schema`. Cached for the session. |
|
|
43
|
+
| `useTableMeta(table)` | `TableMeta \| undefined` | One table from the registry. `undefined` while the registry loads. |
|
|
44
|
+
| `useOps(table)` | `string[]` | The operations that have a route (`list`, `get`, `create`, …). |
|
|
45
|
+
| `useList(table, params?)` | query of `{ data, pagination }` | `params` takes [list params](/api/query-params), plus `view` to read a named view and `enabled`. Keeps the previous page while the next one loads. |
|
|
46
|
+
| `useInfiniteList(table, params?)` | infinite query | Pages with the keyset cursor (`nextCursor` → `startingAfter`). Falls back to offset when the server returns no cursor, for example when sorting on a masked column. |
|
|
47
|
+
| `useRecord(table, id)` | query of the record | Disabled while `id` is `undefined`. |
|
|
48
|
+
| `useCreate(table)` | mutation `(body) => row` | |
|
|
49
|
+
| `useUpdate(table)` | mutation `({ id, body }) => row` | |
|
|
50
|
+
| `useDelete(table)` | mutation `(id) => void` | |
|
|
51
|
+
| `useAction(table, action)` | mutation `({ id?, params?, input }) => output` | Record-bound actions need `id`. Standalone actions with path parameters need `params`. |
|
|
52
|
+
| `useLive(table, enabled = true)` | `boolean` | Refetches the table when a `postgres_changes` frame for it arrives. Returns whether a realtime source is wired up. |
|
|
53
|
+
| `useDebouncedValue(value, ms = 250)` | `T` | `value`, updated only after it stops changing for `ms`. |
|
|
54
|
+
|
|
55
|
+
Every mutation invalidates all of the table's cached queries.
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
import { useList, useUpdate } from "@/components/quickback-provider"
|
|
59
|
+
|
|
60
|
+
function OpenJobs() {
|
|
61
|
+
const jobs = useList("jobs", { filter: { status: "open" }, sort: "-createdAt", limit: 10 })
|
|
62
|
+
const update = useUpdate("jobs")
|
|
63
|
+
if (jobs.isPending) return <p>Loading…</p>
|
|
64
|
+
return jobs.data?.data.map((job) => (
|
|
65
|
+
<button key={String(job.id)} onClick={() => update.mutate({ id: String(job.id), body: { status: "closed" } })}>
|
|
66
|
+
Close {String(job.title)}
|
|
67
|
+
</button>
|
|
68
|
+
))
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The hooks are deliberately untyped by name (`Row = Record<string, unknown>`),
|
|
73
|
+
because they serve generic UI. For typed rows, call the client directly:
|
|
74
|
+
`useQuickback().jobs.list()` returns `Api.jobs.Row[]`.
|
|
75
|
+
|
|
76
|
+
## Roles
|
|
77
|
+
|
|
78
|
+
The emitted client has no session method, so the provider only knows the
|
|
79
|
+
caller's roles if you pass them. Read the role from your auth client:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
const member = auth.useActiveMember() // better-auth organizationClient()
|
|
83
|
+
<QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Roles are a **UI hint**. The API stays authoritative:
|
|
87
|
+
|
|
88
|
+
- **Masking.** A [masked](/define/masking) column is read-only unless the
|
|
89
|
+
roles satisfy its `show` rule. With no `roles`, every masked column is
|
|
90
|
+
read-only. A value that arrives masked (`[REDACTED]`, `j***@…`) is always
|
|
91
|
+
read-only.
|
|
92
|
+
- **Access.** When the roles plainly fail an operation's `access.roles`,
|
|
93
|
+
the form's Delete button is hidden and the action dialog shows a role
|
|
94
|
+
message instead of its form. The client can't decide hierarchy
|
|
95
|
+
(`member+`), `record`, or FGA rules, so those controls stay available and
|
|
96
|
+
the API answers.
|
|
97
|
+
|
|
98
|
+
## Realtime
|
|
99
|
+
|
|
100
|
+
`useLive(table)` refetches the table on its change frames. `ResourceTable`
|
|
101
|
+
calls it unless `live={false}`. The frames come from `client.realtime` when
|
|
102
|
+
the emitted client has one, which it does when the project enables
|
|
103
|
+
[realtime](/api/typescript#realtime). Otherwise pass any
|
|
104
|
+
`{ subscribe(handler) => unsubscribe }` source as `realtime`. See
|
|
105
|
+
[Using Realtime](/platform/realtime/using-realtime) for the ticket and
|
|
106
|
+
WebSocket handshake.
|
|
107
|
+
|
|
108
|
+
## Helpers
|
|
109
|
+
|
|
110
|
+
The other items use these, and you can too:
|
|
111
|
+
|
|
112
|
+
| Export | Description |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `describeError(error)` | `{ message, fields, status? }`. `message` is the problem's `detail`, then its `title`, then `error.message`. `fields` maps field names to messages, from [`QuickbackError.fields`](/api/typescript#fetch-client). |
|
|
115
|
+
| `isMasked(meta, column, roles, value?)` | Whether the column may reach these roles masked. |
|
|
116
|
+
| `canAccess(access, roles)` | Best-effort role check. Returns `true` for rules the client can't decide. |
|
|
117
|
+
| `canWrite(meta, op, roles)` | `canAccess` for `create` / `update` / `delete` from the registry. |
|
|
118
|
+
| `getDisplayColumn(tableMeta)` | The column that names a record: the table's `displayColumn`, else the first of `name`, `title`, `label`, … |
|
|
119
|
+
| `formatLabel(name)` / `columnLabel(name, col?)` | `salaryMin` → `Salary Min`. An FK column reads as its target: `companyId` → `Company`. |
|
|
120
|
+
| `REDACTED` | `"[REDACTED]"`, the value the API sends in place of a redacted value. |
|
|
121
|
+
|
|
122
|
+
Types: `TableMeta`, `ColumnMeta`, `ActionMeta` (all derived from the emitted
|
|
123
|
+
`SchemaRegistry`), `Row`, `Page`, `RealtimeSource`, and `RealtimeFrame`.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# resource-form
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
npx shadcn add @quickback/resource-form
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ResourceForm } from "@/components/resource-form"
|
|
9
|
+
|
|
10
|
+
// Create
|
|
11
|
+
<ResourceForm table="jobs" onSuccess={(row) => navigate(`/jobs/${row.id}`)} />
|
|
12
|
+
|
|
13
|
+
// Edit, with a confirmed Delete
|
|
14
|
+
<ResourceForm table="jobs" id={jobId} onSuccess={close} onCancel={close} onDeleted={close} />
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Description |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `table` | `string` | Schema-registry table name. Required. |
|
|
22
|
+
| `id` | `string` | Record id. Set it to edit that record (the form loads it first). Leave it out to create a new one. |
|
|
23
|
+
| `onSuccess` | `(row) => void` | Called with the saved record. The API's bare record, not an envelope. |
|
|
24
|
+
| `onCancel` | `() => void` | Shows a Cancel button when set. |
|
|
25
|
+
| `onDeleted` | `(id) => void` | Edit mode. Shows a Delete button that asks for confirmation inline, then calls this. See [Delete](#delete) for when the button is hidden. |
|
|
26
|
+
|
|
27
|
+
## Which fields appear
|
|
28
|
+
|
|
29
|
+
The form shows exactly the fields the API accepts:
|
|
30
|
+
|
|
31
|
+
- **Create** shows [`guards.createable`](/define/guards). **Edit** shows
|
|
32
|
+
`guards.updatable`.
|
|
33
|
+
- These fields are read-only, with persistent helper text saying why:
|
|
34
|
+
`guards.immutable` fields on edit, `guards.protected` fields ("Updated via
|
|
35
|
+
actions only"), and masked fields the caller's [roles](/ui/components/quickback-provider#roles)
|
|
36
|
+
can't see unmasked.
|
|
37
|
+
- The form needs the table's `create` (create mode) or `update` (edit mode)
|
|
38
|
+
route. Without it, submitting fails with `"<table>" has no create route`.
|
|
39
|
+
|
|
40
|
+
## Controls
|
|
41
|
+
|
|
42
|
+
| Column | Control |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `inputHints` entry `textarea` / `richtext` | Textarea |
|
|
45
|
+
| Enum validation | Select of the allowed values |
|
|
46
|
+
| FK (`.references()`) | Searchable combobox over the target table (see below) |
|
|
47
|
+
| `bool` | Checkbox |
|
|
48
|
+
| `timestamp` / `date` | Date-time / date input |
|
|
49
|
+
| `decimal` | Text input. `q.decimal()` is an exact decimal string, and a number input would round it. |
|
|
50
|
+
| `json` or array | Textarea (JSON) |
|
|
51
|
+
| `int`, `bigint`, `smallint`, `real` | Number input, with `min` / `max` from validation |
|
|
52
|
+
| `url` | URL input |
|
|
53
|
+
| `email` validation | Email input |
|
|
54
|
+
| anything else | Text input |
|
|
55
|
+
|
|
56
|
+
Constraints show as persistent helper text under the field
|
|
57
|
+
(`Up to 200 characters · Optional`), never as placeholder text.
|
|
58
|
+
|
|
59
|
+
**FK lookups** query the target table as you type (`?search=`, debounced)
|
|
60
|
+
and load more rows by cursor on demand, so there is no first-page cap. When
|
|
61
|
+
the target declares named views, it must set `read.defaultView`. Without it
|
|
62
|
+
the field is disabled with `<Target> needs read.defaultView to be looked up`.
|
|
63
|
+
|
|
64
|
+
## Validation and errors
|
|
65
|
+
|
|
66
|
+
- **Before submit**, the form checks the registry's `validation` block:
|
|
67
|
+
required (NOT NULL without a default on create, NOT NULL on edit),
|
|
68
|
+
`minLength` / `maxLength`, `min` / `max`, whole numbers for integer
|
|
69
|
+
columns, enum membership, URL, email, and `pattern`.
|
|
70
|
+
- **On submit**, create sends every non-blank value. Edit sends only the
|
|
71
|
+
fields you changed. A field you cleared is sent as `null`, which clears
|
|
72
|
+
it. It is never sent as `""`.
|
|
73
|
+
- **Server errors** show the problem's `detail` above the form. Per-field
|
|
74
|
+
messages from `QuickbackError.fields` are shown under their fields.
|
|
75
|
+
|
|
76
|
+
## Delete
|
|
77
|
+
|
|
78
|
+
The Delete button renders only when **all** of these hold: `onDeleted` is
|
|
79
|
+
set, the table has a `delete` route, and the caller's roles don't plainly
|
|
80
|
+
fail its `access.roles`. It asks for confirmation before calling the API.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# resource-table
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
npx shadcn add @quickback/resource-table
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { ResourceTable } from "@/components/resource-table"
|
|
9
|
+
|
|
10
|
+
<ResourceTable
|
|
11
|
+
table="jobs"
|
|
12
|
+
onRowClick={(row) => navigate(`/jobs/${row.id}`)}
|
|
13
|
+
rowActions={(row) => <CloseJobButton id={String(row.id)} />}
|
|
14
|
+
/>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Default | Description |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| `table` | `string` | required | Schema-registry table name. |
|
|
22
|
+
| `view` | `string` | — | Read through a named [view](/define/views). Omit it to read the collection route, which serves `read.defaultView` when the table sets one. |
|
|
23
|
+
| `columns` | `string[]` | every non-system column | Columns visible at first. Users toggle the rest from the column menu. |
|
|
24
|
+
| `pageSize` | `number` | `25` | Sent as `limit`. The server caps it at the table's `maxPageSize`. |
|
|
25
|
+
| `onRowClick` | `(row) => void` | — | Makes rows clickable. |
|
|
26
|
+
| `rowActions` | `(row) => ReactNode` | — | Renders a trailing cell per row, e.g. edit or action buttons. |
|
|
27
|
+
| `live` | `boolean` | `true` | Refetch on realtime change frames for this table (see [Realtime](/ui/components/quickback-provider#realtime)). Has no effect without a realtime source. |
|
|
28
|
+
| `className` | `string` | — | |
|
|
29
|
+
|
|
30
|
+
## Behavior
|
|
31
|
+
|
|
32
|
+
- **Columns** come from the view's declared `fields` when it has them, else
|
|
33
|
+
from the schema. The primary key, the tenant scope, and audit bookkeeping
|
|
34
|
+
(`createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`) start
|
|
35
|
+
hidden.
|
|
36
|
+
- **Pagination** uses the keyset cursor (`startingAfter` / `endingBefore`). It
|
|
37
|
+
falls back to offset when the server returns no cursor, for example when
|
|
38
|
+
sorting on a masked column.
|
|
39
|
+
- **Search** is debounced and sent as `?search=`. The box is hidden when the
|
|
40
|
+
view's `query.searchable` is empty, since the server would answer `400`.
|
|
41
|
+
- **Sorting** is by column header, sent as `?sort=`. The first load uses the
|
|
42
|
+
table's `defaultSort`.
|
|
43
|
+
- **States.** Loading, empty (`No records yet`, or `No records match "…"`),
|
|
44
|
+
and error with a retry button. The error shows the problem's `detail`.
|
|
45
|
+
- **Masked fields** render exactly what the API returns (`[REDACTED]`,
|
|
46
|
+
`***-**-1234`). The table can't see past [masking](/define/masking).
|