@quickback-dev/cli 0.66.21 → 0.66.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/check.js +1 -1
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.js +82 -165
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +92 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +3 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +59 -0
- package/dist/lib/harness.d.ts.map +1 -0
- package/dist/lib/harness.js +178 -0
- package/dist/lib/harness.js.map +1 -0
- 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/start/template-blog.md +36 -58
- package/dist/skill/docs/start/templates.md +3 -3
- package/dist/skill/docs/tooling/claude-skill.md +10 -1
- package/dist/skill/docs/tooling/cli.md +5 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -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/dist/templates/registry.js +1 -1
- package/dist/templates/registry.js.map +1 -1
- 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/start/template-blog.md +36 -58
- package/src/skill/docs/start/templates.md +3 -3
- package/src/skill/docs/tooling/claude-skill.md +10 -1
- package/src/skill/docs/tooling/cli.md +5 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -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,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).
|
|
@@ -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).
|
|
@@ -14,7 +14,7 @@ export const TEMPLATE_REGISTRY = {
|
|
|
14
14
|
},
|
|
15
15
|
"todos-cloudflare": {
|
|
16
16
|
name: "Todos Example (Cloudflare)",
|
|
17
|
-
description: "Working todos example — schema with masking, two
|
|
17
|
+
description: "Working todos example — schema with masking, two transitions (complete / uncomplete), a named view, Better Auth, D1. Read the source as a learning template.",
|
|
18
18
|
tags: ["example", "todos", "actions", "cloudflare", "d1"],
|
|
19
19
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
20
20
|
preset: "cloudflare",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACjE,0BAA0B,EAAE;QACxB,IAAI,EAAE,+BAA+B;QACrC,WAAW,EAAE,qHAAqH;QAClI,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC;QAC1C,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,kBAAkB,EAAE;QAChB,IAAI,EAAE,4BAA4B;QAClC,WAAW,EAAE,
|
|
1
|
+
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.66.
|
|
3
|
+
"version": "0.66.23",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -471,24 +471,31 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
|
|
|
471
471
|
|
|
472
472
|
### Validation Error Response
|
|
473
473
|
|
|
474
|
+
Every action error is `application/problem+json` (see [Errors](/api/errors)).
|
|
475
|
+
An input that fails the action's schema:
|
|
476
|
+
|
|
474
477
|
```json
|
|
475
478
|
{
|
|
476
|
-
"
|
|
479
|
+
"type": "https://quickback.dev/problems/validation-error",
|
|
480
|
+
"title": "Validation error",
|
|
481
|
+
"status": 400,
|
|
482
|
+
"code": "VALIDATION_ERROR",
|
|
483
|
+
"detail": "Request body validation failed.",
|
|
484
|
+
"instance": "/api/v1/invoices/inv_123/refund",
|
|
477
485
|
"layer": "validation",
|
|
478
|
-
"code": "VALIDATION_FAILED",
|
|
479
486
|
"details": {
|
|
480
487
|
"fields": {
|
|
481
|
-
"amount": "
|
|
488
|
+
"amount": "Too small: expected number to be >0"
|
|
482
489
|
}
|
|
483
490
|
},
|
|
484
|
-
"
|
|
491
|
+
"pointer": "/amount"
|
|
485
492
|
}
|
|
486
493
|
```
|
|
487
494
|
|
|
488
495
|
### Error Handling
|
|
489
496
|
|
|
490
|
-
**Throw an `ActionError`.** The route handler catches it by name and returns
|
|
491
|
-
|
|
497
|
+
**Throw an `ActionError`.** The route handler catches it by name and returns a
|
|
498
|
+
problem+json body carrying your `code` and `details`, with your `statusCode`:
|
|
492
499
|
|
|
493
500
|
```typescript
|
|
494
501
|
import { ActionError } from "@quickback/compiler";
|
|
@@ -61,8 +61,12 @@ server-minted ids as usual.
|
|
|
61
61
|
"error": "Duplicate value",
|
|
62
62
|
"layer": "database",
|
|
63
63
|
"code": "DB_UNIQUE_VIOLATION",
|
|
64
|
-
"details": {
|
|
65
|
-
|
|
64
|
+
"details": {
|
|
65
|
+
"column": "jobId",
|
|
66
|
+
"columns": ["jobId", "candidateId"],
|
|
67
|
+
"fields": { "jobId": "Already taken", "candidateId": "Already taken" }
|
|
68
|
+
},
|
|
69
|
+
"hint": "A record with this \"jobId\" + \"candidateId\" already exists"
|
|
66
70
|
}
|
|
67
71
|
}
|
|
68
72
|
],
|
|
@@ -134,10 +134,61 @@ Single-record reads run a role-only access check **before** the firewall query,
|
|
|
134
134
|
|
|
135
135
|
| Status | Description |
|
|
136
136
|
|--------|-------------|
|
|
137
|
+
| `400` | `:id` isn't shaped like this table's ids (`INVALID_ID`) — see [Malformed ids](#malformed-ids-400-invalid_id) |
|
|
137
138
|
| `401` | Not authenticated |
|
|
138
139
|
| `403` | Authenticated but role doesn't satisfy `read.access` — **or** the role passes and the firewall excluded the record (`FIREWALL_NOT_FOUND`). This is the default: `firewallErrorMode` is `'reveal'`. |
|
|
139
140
|
| `404` | Same firewall miss, but on a resource that sets [`firewallErrorMode: 'hide'`](/define/firewall) to make an out-of-scope row indistinguishable from a nonexistent one. |
|
|
140
141
|
|
|
142
|
+
### Malformed ids (`400 INVALID_ID`)
|
|
143
|
+
|
|
144
|
+
Every record route — `GET`, `PATCH` (plain and [changeset](/define/changesets)),
|
|
145
|
+
`PUT`, `DELETE /:id`, and record actions at `/:id/<action>` — checks `:id`
|
|
146
|
+
against the table's id format and answers `400 INVALID_ID` before any database
|
|
147
|
+
work. A client gets "that's not an id" instead of a 403/404 that reads like a
|
|
148
|
+
missing row, and garbage never costs a round-trip.
|
|
149
|
+
|
|
150
|
+
The check runs **after** the auth gate (a `401` still wins) and **before** the
|
|
151
|
+
role-only access pre-check. That ordering adds nothing to the ID-probe channel
|
|
152
|
+
above: the verdict is a function of the URL string alone — identical whether or
|
|
153
|
+
not any row exists, in any tenant — and the id format is public (it is in every
|
|
154
|
+
id the API returns). Every well-formed id still goes through the pre-check and
|
|
155
|
+
the firewall exactly as before.
|
|
156
|
+
|
|
157
|
+
The accepted shape is everything the compiler could have minted for the table,
|
|
158
|
+
not just what it mints today:
|
|
159
|
+
|
|
160
|
+
| Id column / `generateId` | `:id` accepts |
|
|
161
|
+
|--------------------------|---------------|
|
|
162
|
+
| unset (the default) | UUID **or** anything `"prefixed"` accepts — before the default became `"uuid"`, unset projects minted prefixed ids, and those rows stay addressable. See [Upgrading](/configure/providers#id-generation-options) |
|
|
163
|
+
| `"uuid"` | UUID (any case) |
|
|
164
|
+
| `"cuid"` | cuid / cuid2 (lowercase letter + 1–31 lowercase alphanumerics) **or** UUID — schema auto-injection has backed `createId()` with `crypto.randomUUID()`, so existing rows can be UUIDs |
|
|
165
|
+
| `"nanoid"` | 21 URL-safe characters |
|
|
166
|
+
| `"short"` | 6 alphanumerics |
|
|
167
|
+
| `"prefixed"` | optional alphanumeric `<prefix>_` + 32 hex (dashes allowed) — **any** prefix, since it derives from the table name and a rename leaves old rows on the old one |
|
|
168
|
+
| `serial` / `bigserial` / `smallserial` column | positive integer (any integer under `generateId: false`) |
|
|
169
|
+
| other integer column | integer |
|
|
170
|
+
| Postgres `uuid` column | UUID, whatever the strategy |
|
|
171
|
+
|
|
172
|
+
Every id a client may supply on create (`allowClientIds`, below) passes this
|
|
173
|
+
check, so a created id is always addressable.
|
|
174
|
+
|
|
175
|
+
**Never checked** — the compiler can't know the format:
|
|
176
|
+
|
|
177
|
+
- `generateId: false` (ids are any client-supplied string — this is also the
|
|
178
|
+
only mode with `PUT /:id` upsert, so upsert ids are never rejected);
|
|
179
|
+
- an id column with an **authored** default (anything other than the
|
|
180
|
+
strategy's own `$defaultFn`), or a non-`id` primary key;
|
|
181
|
+
- other column types (`varchar`, `real`, …).
|
|
182
|
+
|
|
183
|
+
> The check trusts that every row's id has the current strategy's shape. That
|
|
184
|
+
> stops being true when `generateId` changed after rows were written, data was
|
|
185
|
+
> imported with foreign ids, or an action `db.insert`s a hand-made id. Those rows
|
|
186
|
+
> answer **400 instead of the row** — they become unreachable through `/:id`. Set
|
|
187
|
+
> [`validateIdParams: false`](/configure/providers#database-options) on the
|
|
188
|
+
> database config for such a project; routes then read `:id` as a plain string
|
|
189
|
+
> again (numeric primary keys keep their integer check).
|
|
190
|
+
|
|
191
|
+
|
|
141
192
|
### FK Label Resolution
|
|
142
193
|
|
|
143
194
|
Foreign key columns are automatically enriched with `_label` fields containing the referenced table's display value. The name is the FK column with a trailing `Id` stripped, plus `_label` — so `departmentId` gets `department_label`. Enrichment only happens when the referenced table declares a display column. See [Display Column](/define/schema#display-column) for details.
|
|
@@ -157,7 +208,10 @@ Content-Type: application/json
|
|
|
157
208
|
}
|
|
158
209
|
```
|
|
159
210
|
|
|
160
|
-
Creates a new record.
|
|
211
|
+
Creates a new record. With `guards`, only fields in `guards.createable` or
|
|
212
|
+
`guards.immutable` are accepted. Without `guards`, every column except the
|
|
213
|
+
primary key, audit columns, and firewall/scope columns is accepted. Either way,
|
|
214
|
+
a client-supplied `id` is accepted where the project takes one (see below).
|
|
161
215
|
Required columns (`.required()` with no default) must be present; nullable
|
|
162
216
|
columns may be omitted or sent as `null`. An empty string is **not** a blank —
|
|
163
217
|
`""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
|
|
@@ -197,12 +251,15 @@ client-generated and server-generated ids are indistinguishable in the table:
|
|
|
197
251
|
|
|
198
252
|
| `generateId` | Accepted shape | Client mints with |
|
|
199
253
|
|--------------|----------------|-------------------|
|
|
200
|
-
| `"uuid"` | UUID | `crypto.randomUUID()` |
|
|
254
|
+
| unset (the default) or `"uuid"` | UUID | `crypto.randomUUID()` |
|
|
201
255
|
| `"prefixed"` | `<prefix>_` + 32 hex chars (e.g. `job_550e8400…`) | `` `${prefix}_${crypto.randomUUID().replaceAll('-', '')}` `` |
|
|
202
256
|
| `"cuid"` | 24-char cuid2 | `createId()` from `@paralleldrive/cuid2` |
|
|
203
257
|
| `"nanoid"` | 21-char nanoid | `nanoid()` |
|
|
204
258
|
| `"short"` | 6 alphanumerics | matching `customAlphabet` call |
|
|
205
259
|
|
|
260
|
+
The server mints the same shape on every path: `POST /`, `POST /batch`, and
|
|
261
|
+
the schema default that an action's `db.insert()` falls back on.
|
|
262
|
+
|
|
206
263
|
What breaks, and how:
|
|
207
264
|
|
|
208
265
|
- A malformed id is a `400 VALIDATION_ERROR` at the Zod boundary.
|
|
@@ -216,8 +273,11 @@ What breaks, and how:
|
|
|
216
273
|
keys (the database owns the id).
|
|
217
274
|
|
|
218
275
|
Guards do not apply to the id: it is compiler-managed, so it does not need to
|
|
219
|
-
appear in `guards.createable`.
|
|
220
|
-
|
|
276
|
+
appear in `guards.createable`. The same rule holds under `generateId: false`,
|
|
277
|
+
where the id is **required** on `POST /`, `POST /batch` and a changeset
|
|
278
|
+
`POST` (root and owned-child inserts): guards check every other field, never
|
|
279
|
+
the id. `PUT /:id` and `PATCH` are unchanged — the id still comes from the
|
|
280
|
+
URL, never the body.
|
|
221
281
|
|
|
222
282
|
### Response
|
|
223
283
|
|
|
@@ -256,7 +316,9 @@ Content-Type: application/json
|
|
|
256
316
|
}
|
|
257
317
|
```
|
|
258
318
|
|
|
259
|
-
Updates an existing record.
|
|
319
|
+
Updates an existing record. With `guards`, only fields in `guards.updatable`
|
|
320
|
+
are accepted. Without `guards`, every column except the primary key, audit
|
|
321
|
+
columns, and firewall/scope columns is accepted.
|
|
260
322
|
Omit a key to leave that column untouched; send `null` to clear a nullable
|
|
261
323
|
column. `null` on a `.required()` column is a `400` — the DB would reject the
|
|
262
324
|
write, so the API does first.
|
|
@@ -279,7 +341,7 @@ patched ones) — there is no `data` wrapper:
|
|
|
279
341
|
|
|
280
342
|
| Status | Description |
|
|
281
343
|
|--------|-------------|
|
|
282
|
-
| `400` | Invalid field or field not updatable |
|
|
344
|
+
| `400` | Invalid field or field not updatable, or a malformed `:id` ([`INVALID_ID`](#malformed-ids-400-invalid_id)) |
|
|
283
345
|
| `403` | User lacks permission to update this record, or the firewall excluded it (default `firewallErrorMode: 'reveal'`) |
|
|
284
346
|
| `404` | Record excluded by the firewall when the resource sets `firewallErrorMode: 'hide'` |
|
|
285
347
|
| `412` | `If-Match` revision mismatch |
|
|
@@ -319,6 +381,7 @@ returned, in either mode:
|
|
|
319
381
|
|
|
320
382
|
| Status | Description |
|
|
321
383
|
|--------|-------------|
|
|
384
|
+
| `400` | Malformed `:id` ([`INVALID_ID`](#malformed-ids-400-invalid_id)) |
|
|
322
385
|
| `403` | User lacks permission to delete this record, or the firewall excluded it (default `firewallErrorMode: 'reveal'`) |
|
|
323
386
|
| `404` | Record excluded by the firewall when the resource sets `firewallErrorMode: 'hide'` |
|
|
324
387
|
| `412` | `If-Match` revision mismatch |
|
|
@@ -402,7 +465,7 @@ Creates multiple records in a single request. Each record follows the same valid
|
|
|
402
465
|
"error": "Field cannot be set during creation",
|
|
403
466
|
"layer": "guards",
|
|
404
467
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
405
|
-
"details": { "fields":
|
|
468
|
+
"details": { "fields": { "status": "cannot be set on create" } }
|
|
406
469
|
}
|
|
407
470
|
}
|
|
408
471
|
],
|
|
@@ -634,7 +697,7 @@ By default, batch operations use **partial success** mode:
|
|
|
634
697
|
"error": "Human-readable message",
|
|
635
698
|
"layer": "guards",
|
|
636
699
|
"code": "GUARD_FIELD_NOT_CREATEABLE",
|
|
637
|
-
"details": { "fields":
|
|
700
|
+
"details": { "fields": { "status": "cannot be set on create" } },
|
|
638
701
|
"hint": "These fields are set automatically or must be omitted"
|
|
639
702
|
}
|
|
640
703
|
}
|
|
@@ -688,7 +751,7 @@ On the first failure under `failFast: true`:
|
|
|
688
751
|
"details": {
|
|
689
752
|
"failedAt": 2,
|
|
690
753
|
"reason": "Field cannot be set during creation",
|
|
691
|
-
"errorDetails": { "fields":
|
|
754
|
+
"errorDetails": { "fields": { "status": "cannot be set on create" } }
|
|
692
755
|
},
|
|
693
756
|
"hint": "Records before index 2 were applied and are NOT rolled back. Inspect application state before retrying — re-sending the same batch may double-apply records that already succeeded."
|
|
694
757
|
}
|