@quickback-dev/cli 0.66.20 → 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/commands/migrate.js +2 -2
- package/dist/commands/migrate.js.map +1 -1
- 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 +86 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +8 -7
- package/dist/skill/docs/api/typescript.md +196 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +37 -9
- package/dist/skill/docs/define/actions/defining.md +16 -7
- package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/dist/skill/docs/define/actions/scoped-db.md +18 -3
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/firewall.md +39 -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/relationships.md +9 -0
- package/dist/skill/docs/define/schema.md +14 -10
- package/dist/skill/docs/define/transitions.md +12 -5
- package/dist/skill/docs/define/triggers.md +2 -1
- 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/database/neon.md +110 -30
- 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/cli.md +28 -7
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +42 -11
- 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 +86 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +8 -7
- package/src/skill/docs/api/typescript.md +196 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +37 -9
- package/src/skill/docs/define/actions/defining.md +16 -7
- package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/src/skill/docs/define/actions/scoped-db.md +18 -3
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/firewall.md +39 -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/relationships.md +9 -0
- package/src/skill/docs/define/schema.md +14 -10
- package/src/skill/docs/define/transitions.md +12 -5
- package/src/skill/docs/define/triggers.md +2 -1
- 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/database/neon.md +110 -30
- 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/cli.md +28 -7
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +42 -11
- 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
|
@@ -42,11 +42,16 @@ so an extra database silently splits the bootstrap: the roles look right in
|
|
|
42
42
|
separating. Two apps means two Neon projects, not two databases.
|
|
43
43
|
|
|
44
44
|
Mixing providers — for example D1 for auth with Neon for features — is not
|
|
45
|
-
supported. The per-service config form is
|
|
45
|
+
supported. The per-service config form is a type error under `quickback check`
|
|
46
|
+
(the config type has no `auth` / `features` keys) and is rejected at compile
|
|
47
|
+
time:
|
|
46
48
|
|
|
47
49
|
```
|
|
48
|
-
providers.database service-map form is not supported in v2.
|
|
49
|
-
Configure
|
|
50
|
+
providers.database service-map form is not supported in v2 ({ auth, features } is the retired v1 shape).
|
|
51
|
+
Configure ONE database provider — auth and feature data share it:
|
|
52
|
+
database: defineDatabase("cloudflare-d1", { ... }) or database: { name: "neon", config: { ... } }.
|
|
53
|
+
On D1, auth keeps its own database by default (splitDatabases: true);
|
|
54
|
+
name the bindings with authBinding / featuresBinding.
|
|
50
55
|
```
|
|
51
56
|
|
|
52
57
|
## Configuration
|
|
@@ -599,8 +604,12 @@ WITH CHECK (
|
|
|
599
604
|
|
|
600
605
|
### The soft-delete lane
|
|
601
606
|
|
|
602
|
-
`deleted_at IS NULL` keeps soft-deleted rows out of every caller's reach.
|
|
603
|
-
|
|
607
|
+
`deleted_at IS NULL` keeps soft-deleted rows out of every caller's reach. It is
|
|
608
|
+
in the scope policy of every table that carries `deleted_at`, exactly where the
|
|
609
|
+
API firewall adds its own `isNull(deletedAt)` — including a `firewall: [...]`
|
|
610
|
+
array that never mentions `deletedAt` (declare a predicate on `deletedAt`
|
|
611
|
+
yourself to take it over). On its own it also blocks the delete that put them
|
|
612
|
+
there.
|
|
604
613
|
|
|
605
614
|
PostgreSQL applies a SELECT-applicable policy's `USING` expression to the **new**
|
|
606
615
|
row of an `UPDATE`, not only the existing one, whenever the statement reads the
|
|
@@ -819,6 +828,17 @@ USING (owner_id = auth.user_id())
|
|
|
819
828
|
WITH CHECK (owner_id = auth.user_id());
|
|
820
829
|
```
|
|
821
830
|
|
|
831
|
+
**Relationship-scoped** (`{ field: 'projectId', via: 'projectMemberOf' }`) — see
|
|
832
|
+
[Relationship arms in SQL](#relationship-arms-in-sql):
|
|
833
|
+
|
|
834
|
+
```sql
|
|
835
|
+
CREATE POLICY "tasks_scope" ON "app"."tasks" FOR ALL TO quickback
|
|
836
|
+
USING (organization_id = public.get_active_org_id()
|
|
837
|
+
AND project_id IN (SELECT r.project_id FROM public.qb_rel_project_member_of() r))
|
|
838
|
+
WITH CHECK (organization_id = public.get_active_org_id()
|
|
839
|
+
AND project_id IN (SELECT r.project_id FROM public.qb_rel_project_member_of() r));
|
|
840
|
+
```
|
|
841
|
+
|
|
822
842
|
**Exception tables** (`firewall: [{ exception: true }]`) — no scope predicate,
|
|
823
843
|
so the restrictive deny-anon policy is the only fence left:
|
|
824
844
|
|
|
@@ -827,6 +847,77 @@ CREATE POLICY "categories_all" ON "app"."categories" FOR ALL TO quickback
|
|
|
827
847
|
USING (true) WITH CHECK (true);
|
|
828
848
|
```
|
|
829
849
|
|
|
850
|
+
### Relationship arms in SQL
|
|
851
|
+
|
|
852
|
+
Every relationship lookup is enforced by the database, and the generated API
|
|
853
|
+
reads through the same place. Each declared relationship gets one helper,
|
|
854
|
+
emitted in the RLS migration ahead of the policies that call it:
|
|
855
|
+
|
|
856
|
+
```sql
|
|
857
|
+
CREATE OR REPLACE FUNCTION public.qb_rel_project_member_of()
|
|
858
|
+
RETURNS SETOF "app"."project_members"
|
|
859
|
+
LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
|
|
860
|
+
AS $$
|
|
861
|
+
SELECT a.*
|
|
862
|
+
FROM "app"."project_members" a
|
|
863
|
+
WHERE a."user_id" = auth.user_id()
|
|
864
|
+
AND a."deleted_at" IS NULL
|
|
865
|
+
$$;
|
|
866
|
+
ALTER FUNCTION public.qb_rel_project_member_of() OWNER TO quickback_owner;
|
|
867
|
+
REVOKE ALL ON FUNCTION public.qb_rel_project_member_of() FROM PUBLIC;
|
|
868
|
+
GRANT EXECUTE ON FUNCTION public.qb_rel_project_member_of() TO quickback;
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
The scope policy calls it as
|
|
872
|
+
`"project_id" IN (SELECT r."project_id" FROM public.qb_rel_project_member_of() r)`,
|
|
873
|
+
and so does the generated API: a firewall `via:` arm, a relationship-role access
|
|
874
|
+
check, the action resolver's match row, the `/scope/v1/enter` probe and the
|
|
875
|
+
ws-ticket probe all read the caller's relationship rows from the helper, never
|
|
876
|
+
from the relationship table under its own policy.
|
|
877
|
+
|
|
878
|
+
- **Same lookup as D1.** The body is the relationship subquery the API runs on
|
|
879
|
+
D1: the subject column against the caller's claim, the `where:` literals
|
|
880
|
+
(SQL-quoted), and the related table's soft-delete filter — the API's
|
|
881
|
+
`skipTenantScopes` body. Multi-hop (`hops`) relationships join the same chain
|
|
882
|
+
and return the first hop's rows.
|
|
883
|
+
- **Why `SECURITY DEFINER`.** Under the relationship table's own policy the
|
|
884
|
+
lookup would recurse for a relationship that reads the table it protects
|
|
885
|
+
(`projectMemberOf` on `project_members`), and the table's tenant scope would
|
|
886
|
+
zero a caller with no active org — the case the API skips on purpose. The
|
|
887
|
+
helper runs as `quickback_owner`, which reads the related table through one
|
|
888
|
+
`<table>_quickback_owner_read` policy (`FOR SELECT TO quickback_owner USING (true)`).
|
|
889
|
+
Feature tables `FORCE ROW LEVEL SECURITY`, so the owner needs it; it grants
|
|
890
|
+
nothing new — an owner can always lift `FORCE` on its own table — and the
|
|
891
|
+
runtime role `quickback` is not a member of `quickback_owner`.
|
|
892
|
+
- **Locked down.** `search_path = ''` and fully-qualified names; `EXECUTE` is
|
|
893
|
+
revoked from `PUBLIC` and granted to `quickback` only. The caller comes from
|
|
894
|
+
the transaction's claims, so a lookup on the service handle (no caller)
|
|
895
|
+
returns nothing.
|
|
896
|
+
- **Evaluated once per statement.** The helper takes no arguments, so
|
|
897
|
+
`col IN (SELECT … FROM helper() r)` is an uncorrelated subquery — one hashed
|
|
898
|
+
subplan per statement, the same InitPlan discipline as the claim helpers. A
|
|
899
|
+
per-row `helper(row.col)` call could never be inlined.
|
|
900
|
+
- **Returns the table's own rows.** One helper serves every projection a lookup
|
|
901
|
+
needs (the resource column, the tenant columns the action resolver stamps,
|
|
902
|
+
scope sub-keys), and `CREATE OR REPLACE` stays valid as the table's columns
|
|
903
|
+
change. A helper whose relationship now returns a different table is dropped
|
|
904
|
+
first — with the generated policies that call it, which the same migration
|
|
905
|
+
re-creates.
|
|
906
|
+
- **Tenant binding.** Beside an org arm in an `any:` group the arm becomes
|
|
907
|
+
`(project_id IN (SELECT …) AND (organization_id = <active org> OR <no active org>))`
|
|
908
|
+
— exactly where the API applies the same binding.
|
|
909
|
+
- **Permissions.** A `{ permission }` arm expands as the API expands it; arrow
|
|
910
|
+
hops become `qb_arrow_…` helpers (recursive arrows are a `maxDepth`-bounded
|
|
911
|
+
closure that re-checks the tenant on every row), called by the API too.
|
|
912
|
+
- **Still API-only.** Literal status filters (a conjunct would refuse
|
|
913
|
+
status-changing updates, because PostgreSQL checks an UPDATE's new row against
|
|
914
|
+
the read policy) and claims the Worker never writes into the transaction —
|
|
915
|
+
`ctx.scope.<kind>.<subKey>`, area anchors such as `ctx.event.id`, and
|
|
916
|
+
relationships whose `subject` binds one. These lower to `true` in the policy,
|
|
917
|
+
and the API keeps the table query for such a relationship.
|
|
918
|
+
|
|
919
|
+
Helpers no compile references any more are dropped at the end of the migration.
|
|
920
|
+
|
|
830
921
|
### Helper functions
|
|
831
922
|
|
|
832
923
|
| Function | Purpose |
|
|
@@ -963,31 +1054,20 @@ is a compile error everywhere, not a Neon-only concern.
|
|
|
963
1054
|
|
|
964
1055
|
### How the read is served
|
|
965
1056
|
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
caller claims + the RLS backstop** — they resolve to policies RLS *can* express.
|
|
981
|
-
- The swap is gated on a non-empty firewall carrying the reachability predicate;
|
|
982
|
-
a service-handle read with no WHERE is a compile error (it would return every
|
|
983
|
-
tenant's rows). Fail closed.
|
|
984
|
-
- It applies to the **collection `GET /`, `GET /:id`, and views** alike. **Writes
|
|
985
|
-
are unchanged** — creates/updates/deletes keep caller claims and the RLS
|
|
986
|
-
backstop.
|
|
987
|
-
|
|
988
|
-
The **same config compiles identically on D1**, where there is no RLS to bypass:
|
|
989
|
-
the read handlers keep `c.get('db')` and the app-layer reachability WHERE was
|
|
990
|
-
already the whole story.
|
|
1057
|
+
Reads keep the **caller-claims** handle and the full RLS backstop, on Neon as
|
|
1058
|
+
everywhere else. The reachability WHERE (`buildFirewallConditions(...)`) and the
|
|
1059
|
+
resource's scope policy both call the relationship's
|
|
1060
|
+
[helper](#relationship-arms-in-sql), which walks the hop chain without the
|
|
1061
|
+
intermediate tables' tenant policies — so an attendee with no active org gets
|
|
1062
|
+
exactly their reachable rows, from the API and from the database alike.
|
|
1063
|
+
|
|
1064
|
+
Earlier releases routed these reads through the service-role handle
|
|
1065
|
+
(`createServiceDb`) instead, because the multi-hop join read the intermediate
|
|
1066
|
+
tables under their own tenant scopes and came back empty. That bypassed RLS for
|
|
1067
|
+
the whole read; the routing is gone.
|
|
1068
|
+
|
|
1069
|
+
The **same config compiles identically on D1**: the read handlers keep
|
|
1070
|
+
`c.get('db')`, and the app-layer reachability WHERE runs the join directly.
|
|
991
1071
|
|
|
992
1072
|
## Webhooks on Neon
|
|
993
1073
|
|
|
@@ -39,7 +39,7 @@ Condition 2 is broader than it may look, and deliberately so. There is no
|
|
|
39
39
|
per-provider inbound webhook configuration surface: the inbound route registers
|
|
40
40
|
exactly one provider, Stripe, so *any* project that turned webhooks on is a
|
|
41
41
|
project that can receive Stripe events. The same condition adds `stripe` to the
|
|
42
|
-
generated `package.json` (pinned at `^22.
|
|
42
|
+
generated `package.json` (pinned at `^22.6.1`), so the dependency and the client
|
|
43
43
|
can never disagree about whether Stripe is in play.
|
|
44
44
|
|
|
45
45
|
> **Accepted over-trigger.** A project that only *receives* Stripe webhooks and
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
# Build a frontend
|
|
2
|
+
|
|
3
|
+
This guide builds a React app that lists, creates, edits, and closes jobs
|
|
4
|
+
against your API. It uses the [components](/ui/components) (shadcn registry
|
|
5
|
+
items) on top of the emitted [fetch client](/api/typescript#fetch-client).
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
my-app/
|
|
9
|
+
├── quickback.config.ts
|
|
10
|
+
├── quickback/features/jobs/ # your API definitions
|
|
11
|
+
├── src/ # generated Worker (never edit)
|
|
12
|
+
└── web/ # your React app (you own it)
|
|
13
|
+
└── src/lib/
|
|
14
|
+
├── quickback.client.ts # emitted every compile
|
|
15
|
+
└── quickback.gen.ts # emitted every compile
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 1. Scaffold the app
|
|
19
|
+
|
|
20
|
+
From the project root, create a Vite app with a shadcn **base-ui** style. The
|
|
21
|
+
components don't support Radix styles.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx shadcn@latest init -t vite -b base -p nova -n web
|
|
25
|
+
cd web && npm install better-auth && cd ..
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 2. Emit the client into it
|
|
29
|
+
|
|
30
|
+
Add three keys to the scaffolded config and keep everything else:
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
// quickback.config.ts
|
|
34
|
+
import { defineConfig } from "@quickback/compiler";
|
|
35
|
+
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
// …name, providers, etc. from the scaffold
|
|
38
|
+
types: { output: "web/src/lib/quickback.gen.ts" },
|
|
39
|
+
client: "web/src/lib/quickback.client.ts",
|
|
40
|
+
// The components read GET /api/v1/schema. Its default ("sysadmin")
|
|
41
|
+
// would 403 every other user; "member" admits organization members.
|
|
42
|
+
schemaRegistry: { access: "member" },
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The client imports its types from the first `types` output, so both files
|
|
47
|
+
live inside `web/`.
|
|
48
|
+
|
|
49
|
+
## 3. Define the API
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// quickback/features/jobs/jobs.ts
|
|
53
|
+
import { feature, q } from "@quickback/compiler";
|
|
54
|
+
|
|
55
|
+
export default feature("jobs", {
|
|
56
|
+
columns: {
|
|
57
|
+
id: q.id(),
|
|
58
|
+
title: q.text().required(),
|
|
59
|
+
department: q.text().required(),
|
|
60
|
+
status: q.text().default("open").required(),
|
|
61
|
+
salaryMin: q.int().optional(),
|
|
62
|
+
organizationId: q.scope("organization"),
|
|
63
|
+
...q.audit(),
|
|
64
|
+
...q.softDelete(),
|
|
65
|
+
},
|
|
66
|
+
guards: {
|
|
67
|
+
createable: ["title", "department", "salaryMin"],
|
|
68
|
+
updatable: ["title", "department", "salaryMin"],
|
|
69
|
+
protected: { status: ["close"] },
|
|
70
|
+
},
|
|
71
|
+
read: { access: { roles: ["owner", "admin", "member"] } },
|
|
72
|
+
create: { access: { roles: ["owner", "admin"] } },
|
|
73
|
+
update: { access: { roles: ["owner", "admin"] } },
|
|
74
|
+
delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
// quickback/features/jobs/actions/close.ts
|
|
78
|
+
import { z } from "zod";
|
|
79
|
+
import { eq } from "drizzle-orm";
|
|
80
|
+
import { defineAction, jobs } from "../.quickback/define-action";
|
|
81
|
+
|
|
82
|
+
export default defineAction({
|
|
83
|
+
description: "Close the job to new applications",
|
|
84
|
+
input: z.object({ reason: z.string().optional() }),
|
|
85
|
+
access: { roles: ["owner", "admin"], record: { status: { equals: "open" } } },
|
|
86
|
+
async execute({ db, record }) {
|
|
87
|
+
const [row] = await db
|
|
88
|
+
.update(jobs)
|
|
89
|
+
.set({ status: "closed" })
|
|
90
|
+
.where(eq(jobs.id, record.id))
|
|
91
|
+
.returning();
|
|
92
|
+
return row;
|
|
93
|
+
},
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`status` is `protected`: the form shows it disabled, and only `close` can
|
|
98
|
+
change it.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
quickback build # writes src/ and web/src/lib/quickback.{client,gen}.ts
|
|
102
|
+
npm run dev # API on http://localhost:8787
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## 4. Add the components
|
|
106
|
+
|
|
107
|
+
In `web/components.json`, add the registry:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"registries": {
|
|
112
|
+
"@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
cd web
|
|
119
|
+
npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
|
|
120
|
+
npx shadcn add dialog
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
This installs `quickback-provider` too, since every item depends on it.
|
|
124
|
+
|
|
125
|
+
## 5. Sign in and render
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
// web/src/lib/api.ts
|
|
129
|
+
import { createAuthClient } from "better-auth/react"
|
|
130
|
+
import { organizationClient } from "better-auth/client/plugins"
|
|
131
|
+
import { createClient } from "@/lib/quickback.client"
|
|
132
|
+
|
|
133
|
+
const baseURL = import.meta.env.VITE_API_URL ?? "http://localhost:8787"
|
|
134
|
+
|
|
135
|
+
export const auth = createAuthClient({ baseURL, basePath: "/auth/v1", plugins: [organizationClient()] })
|
|
136
|
+
export const client = createClient({ baseUrl: baseURL })
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```tsx
|
|
140
|
+
// web/src/App.tsx
|
|
141
|
+
import { useState } from "react"
|
|
142
|
+
import { auth, client } from "@/lib/api"
|
|
143
|
+
import { buttonVariants } from "@/components/ui/button"
|
|
144
|
+
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"
|
|
145
|
+
import { QuickbackProvider } from "@/components/quickback-provider"
|
|
146
|
+
import { ResourceTable } from "@/components/resource-table"
|
|
147
|
+
import { ResourceForm } from "@/components/resource-form"
|
|
148
|
+
import { ActionDialog } from "@/components/action-dialog"
|
|
149
|
+
|
|
150
|
+
export default function App() {
|
|
151
|
+
const session = auth.useSession()
|
|
152
|
+
const member = auth.useActiveMember()
|
|
153
|
+
if (session.isPending) return null
|
|
154
|
+
if (!session.data) return <SignIn />
|
|
155
|
+
// Roles are a UI hint (masking, hiding Delete); the API stays authoritative.
|
|
156
|
+
return (
|
|
157
|
+
<QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
|
|
158
|
+
<Jobs />
|
|
159
|
+
</QuickbackProvider>
|
|
160
|
+
)
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function SignIn() {
|
|
164
|
+
const [error, setError] = useState<string>()
|
|
165
|
+
async function submit(form: FormData) {
|
|
166
|
+
const res = await auth.signIn.email({
|
|
167
|
+
email: String(form.get("email")),
|
|
168
|
+
password: String(form.get("password")),
|
|
169
|
+
})
|
|
170
|
+
if (res.error) return setError(res.error.message)
|
|
171
|
+
// Tables are firewalled to the active organization — pick one.
|
|
172
|
+
const orgs = await auth.organization.list()
|
|
173
|
+
const org = orgs.data?.[0] ?? (await auth.organization.create({ name: "Acme", slug: `acme-${Date.now()}` })).data
|
|
174
|
+
if (org) await auth.organization.setActive({ organizationId: org.id })
|
|
175
|
+
}
|
|
176
|
+
return (
|
|
177
|
+
<form action={submit} className="mx-auto flex max-w-sm flex-col gap-2 p-6">
|
|
178
|
+
<label>Email <input name="email" type="email" required /></label>
|
|
179
|
+
<label>Password <input name="password" type="password" required /></label>
|
|
180
|
+
<button className={buttonVariants()}>Sign in</button>
|
|
181
|
+
{error && <p role="alert">{error}</p>}
|
|
182
|
+
</form>
|
|
183
|
+
)
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function Jobs() {
|
|
187
|
+
const [editing, setEditing] = useState<string | null>() // undefined closed, null create
|
|
188
|
+
const [closing, setClosing] = useState<string>()
|
|
189
|
+
const done = () => setEditing(undefined)
|
|
190
|
+
|
|
191
|
+
return (
|
|
192
|
+
<main className="mx-auto flex max-w-5xl flex-col gap-4 p-6">
|
|
193
|
+
<button className={buttonVariants()} onClick={() => setEditing(null)}>New job</button>
|
|
194
|
+
|
|
195
|
+
<ResourceTable
|
|
196
|
+
table="jobs"
|
|
197
|
+
onRowClick={(row) => setEditing(String(row.id))}
|
|
198
|
+
rowActions={(row) => (
|
|
199
|
+
<button className={buttonVariants({ variant: "outline", size: "sm" })} onClick={() => setClosing(String(row.id))}>
|
|
200
|
+
Close
|
|
201
|
+
</button>
|
|
202
|
+
)}
|
|
203
|
+
/>
|
|
204
|
+
|
|
205
|
+
<Dialog open={editing !== undefined} onOpenChange={(open) => !open && done()}>
|
|
206
|
+
<DialogContent>
|
|
207
|
+
<DialogHeader><DialogTitle>{editing ? "Edit job" : "New job"}</DialogTitle></DialogHeader>
|
|
208
|
+
{editing !== undefined && (
|
|
209
|
+
<ResourceForm table="jobs" id={editing ?? undefined} onSuccess={done} onCancel={done} onDeleted={done} />
|
|
210
|
+
)}
|
|
211
|
+
</DialogContent>
|
|
212
|
+
</Dialog>
|
|
213
|
+
|
|
214
|
+
<ActionDialog
|
|
215
|
+
table="jobs"
|
|
216
|
+
action="close"
|
|
217
|
+
id={closing}
|
|
218
|
+
open={closing !== undefined}
|
|
219
|
+
onOpenChange={(open) => !open && setClosing(undefined)}
|
|
220
|
+
/>
|
|
221
|
+
</main>
|
|
222
|
+
)
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Create an account first. Either `POST /auth/v1/sign-up/email` as in the
|
|
227
|
+
[quickstart](/start/quickstart#test-your-api), or add a sign-up form with
|
|
228
|
+
`auth.signUp.email`. Then run the app:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
npm run dev # http://localhost:5173
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
The browser sends the Better Auth session cookie with every request.
|
|
235
|
+
`http://localhost:5173` is a trusted origin by default until the project has
|
|
236
|
+
a production domain, so writes pass the CSRF check. See
|
|
237
|
+
[Auth](/ui/components/auth) for the rules, and for bearer tokens in React
|
|
238
|
+
Native.
|
|
239
|
+
|
|
240
|
+
What you get for free:
|
|
241
|
+
|
|
242
|
+
- **Only permitted fields.** The form shows `guards.createable` /
|
|
243
|
+
`updatable`, and `status` stays locked.
|
|
244
|
+
- **Errors inline.** A guard or validation `400` shows under its field. A
|
|
245
|
+
`403` shows the problem's `detail`.
|
|
246
|
+
- **Close only when open.** The action's `record` precondition runs on the
|
|
247
|
+
server. Closing a closed job shows the rejection in the dialog.
|
|
248
|
+
- **Role-aware.** Delete and `close` both require `owner` or `admin`. A
|
|
249
|
+
`member` therefore sees no Delete button, and the Close dialog shows a role
|
|
250
|
+
message instead of its form. The API enforces the same rules either way.
|
|
251
|
+
|
|
252
|
+
## 6. Ship it on the same Worker
|
|
253
|
+
|
|
254
|
+
Serve the built app from the API's own Worker. It shares the API's origin, so
|
|
255
|
+
it needs no CORS setup, and its hostname is trusted automatically.
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
cd web && VITE_API_URL=https://app.example.com npm run build && cd ..
|
|
259
|
+
rm -rf quickback/apps/web && cp -r web/dist quickback/apps/web
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
// quickback.config.ts — add alongside the rest
|
|
264
|
+
apps: {
|
|
265
|
+
web: { domain: "app.example.com" },
|
|
266
|
+
},
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`quickback build` copies `quickback/apps/web/` into the Worker's assets, then
|
|
270
|
+
`quickback deploy` ships both. See
|
|
271
|
+
[App domains](/configure/domains#app-domains). To host the app elsewhere
|
|
272
|
+
instead, add its origin to [`trustedOrigins`](/configure#trusted-origins).
|
|
273
|
+
|
|
274
|
+
## Next
|
|
275
|
+
|
|
276
|
+
- [Components](/ui/components): every prop and hook
|
|
277
|
+
- [Fetch client](/api/typescript#fetch-client): typed calls beyond the components
|
|
278
|
+
- [Query parameters](/api/query-params): what `useList` params map to
|
|
@@ -36,6 +36,7 @@ quickback/
|
|
|
36
36
|
- **[Define](/define)** — the DSL: schema, the security pillars, reads, writes, actions
|
|
37
37
|
- **[Configure](/configure)** — `quickback.config.ts`, providers, domains, bindings
|
|
38
38
|
- **[Use the API](/api)** — what the generated endpoints look like
|
|
39
|
+
- **[Build a frontend](/start/frontend)** — a React app on your API with the typed client and shadcn components
|
|
39
40
|
|
|
40
41
|
The rest of this page is the vocabulary the other pages assume.
|
|
41
42
|
|
|
@@ -135,7 +135,29 @@ generated typing surfaces:
|
|
|
135
135
|
surface. `import { feature, q, defineTable, defineConfig } from
|
|
136
136
|
"@quickback/compiler"` resolves in table files and `quickback.config.ts`,
|
|
137
137
|
so a bad builder call or an unknown resource-config key is a type error at
|
|
138
|
-
the desk, not a compile-round-trip later.
|
|
138
|
+
the desk, not a compile-round-trip later. `services/` files' `import {
|
|
139
|
+
defineQueue } from "quickback"` resolves to the same surface, and provider
|
|
140
|
+
entries type-check in both forms the build accepts — `defineDatabase(...)`
|
|
141
|
+
or the literal `{ name: "neon", config: { … } }`.
|
|
142
|
+
|
|
143
|
+
The check resolves imports the way the build does, so a clean check is not
|
|
144
|
+
undone by the compile:
|
|
145
|
+
|
|
146
|
+
- **Named table imports from feature files** —
|
|
147
|
+
`import { mailboxes } from "../../mailboxes/mailboxes"` in an action, a
|
|
148
|
+
`lib/` file, or a queue handler. A `feature()` file has only a default
|
|
149
|
+
export; the build points that path at the generated table module, and
|
|
150
|
+
`quickback/.quickback/feature-tables.d.ts` gives the check the same named
|
|
151
|
+
export, typed from the generated schema.
|
|
152
|
+
- **Queue handlers' dynamic imports** — `await import("./features/…")` is
|
|
153
|
+
written against the generated `src/` (the handler body is inlined into
|
|
154
|
+
`src/queue-consumer.ts`); the tsconfig's `rootDirs` resolves it there too.
|
|
155
|
+
- **Service handler contexts** — queue, schedule and email handlers get the
|
|
156
|
+
`db`, `env` and `services` the generated runners pass them: your project's
|
|
157
|
+
Drizzle handle, `CloudflareBindings` and `Services`
|
|
158
|
+
(`quickback/.quickback/service-runtime.d.ts`). A wrong column on a
|
|
159
|
+
`db.select()` result or an undeclared binding is a check error, as it is in
|
|
160
|
+
the build.
|
|
139
161
|
|
|
140
162
|
No compile, no server: this is your editor's view of the source, on demand.
|
|
141
163
|
|
|
@@ -145,11 +167,10 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
|
|
|
145
167
|
the check resolves against. Re-run `quickback build` after schema changes so
|
|
146
168
|
they track your tables.
|
|
147
169
|
|
|
148
|
-
|
|
149
|
-
(`import { tickets } from "
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
`quickback migrate helper-imports` rewrites the safe cases for you.
|
|
170
|
+
Within a feature, the single helper import
|
|
171
|
+
(`import { defineAction, tickets } from "../.quickback/define-action"`) is
|
|
172
|
+
still the tidier form; `quickback migrate helper-imports` rewrites the safe
|
|
173
|
+
cases for you.
|
|
153
174
|
|
|
154
175
|
### Synchronize Managed Columns
|
|
155
176
|
|
|
@@ -190,7 +211,7 @@ quickback migrate helper-imports [--dry-run] # single typed helper import
|
|
|
190
211
|
|
|
191
212
|
```ts
|
|
192
213
|
import { defineAction } from "../.quickback/define-action";
|
|
193
|
-
import { applications } from "../applications"; //
|
|
214
|
+
import { applications } from "../applications"; // second import, same feature
|
|
194
215
|
```
|
|
195
216
|
|
|
196
217
|
— to the single typed import the helpers are designed for:
|
|
@@ -94,6 +94,12 @@ A failed generate or postprocessor leaves existing migration history untouched.
|
|
|
94
94
|
Do not use raw `drizzle-kit generate` as an equivalent workaround for an auth
|
|
95
95
|
upgrade: it skips Quickback's OAuth client backfills and resource-grant cleanup.
|
|
96
96
|
|
|
97
|
+
`drizzle-kit exited after answering a rename prompt without writing a migration`
|
|
98
|
+
means the generator process ended mid-prompt. A prompt only appears when there
|
|
99
|
+
is a schema diff, so this is always a failure: nothing was written and the
|
|
100
|
+
existing history is untouched. Re-run the build; if it repeats, report it with
|
|
101
|
+
the Drizzle output from the error.
|
|
102
|
+
|
|
97
103
|
## `Critical command failed: Generate features database migrations`
|
|
98
104
|
|
|
99
105
|
drizzle-kit could not load the generated **features** schema. The usual cause on
|
|
@@ -50,8 +50,10 @@ src/
|
|
|
50
50
|
# Authored-tree typing (regenerated on every compile, gitignored)
|
|
51
51
|
quickback/tsconfig.json # Typechecks the authored quickback/ tree (`quickback check`)
|
|
52
52
|
quickback/.quickback/
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
├── compiler/ # @quickback/compiler declaration snapshot — resolves
|
|
54
|
+
│ └── … # `import { feature, q, defineTable } from "@quickback/compiler"`
|
|
55
|
+
├── feature-tables.d.ts # Named table exports of feature() files, typed from the generated schema
|
|
56
|
+
└── service-runtime.d.ts # db / env / services types for queue, schedule and email handlers (when any exist)
|
|
55
57
|
quickback/features/{feature}/
|
|
56
58
|
└── .quickback/
|
|
57
59
|
└── define-action.ts # Authored-tree twin of the typed helper below
|
|
@@ -257,6 +259,16 @@ projects acquire build and deployment fixes without losing unrelated tooling.
|
|
|
257
259
|
|
|
258
260
|
These files are generated only when the corresponding features are configured:
|
|
259
261
|
|
|
262
|
+
### TypeScript artifacts
|
|
263
|
+
|
|
264
|
+
| File | Emitted | Config |
|
|
265
|
+
|------|---------|--------|
|
|
266
|
+
| `quickback.gen.ts` | By default | [`types`](/api/typescript#configuration) |
|
|
267
|
+
| `api-types.gen.ts` | By default | [`openapi.types`](/api/openapi) |
|
|
268
|
+
| `quickback.client.ts` | Opt-in | [`client`](/api/typescript#fetch-client) — a zero-dependency `fetch` client typed by `quickback.gen.ts`; the [components](/ui/components) build on it |
|
|
269
|
+
|
|
270
|
+
All three sit outside `src/`, and each accepts a custom path or a list of paths.
|
|
271
|
+
|
|
260
272
|
### Database provider setup files
|
|
261
273
|
|
|
262
274
|
Every compile emits an environment example named for the configured provider.
|
|
@@ -410,6 +422,15 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
|
|
|
410
422
|
|
|
411
423
|
The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
|
|
412
424
|
|
|
425
|
+
### Data Remediation Report
|
|
426
|
+
|
|
427
|
+
`reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
|
|
428
|
+
|
|
429
|
+
- **SQLite / D1:** a count of rows whose `.defaultNow()` or audit timestamp holds the `1970-01-01T00:00:00.000Z` epoch sentinel, per column, with a commented-out repair `UPDATE` where the row has a separate `created_at` to approximate from.
|
|
430
|
+
- **Every dialect:** per `q.url()` column, the rows whose value is not an `http(s)` URL (`javascript:`, `data:`, …).
|
|
431
|
+
|
|
432
|
+
How to run it and what the repair means: [Troubleshooting → Data issues](/tooling/troubleshooting#data-issues).
|
|
433
|
+
|
|
413
434
|
### Realtime
|
|
414
435
|
|
|
415
436
|
When any feature has `realtime` configured:
|
|
@@ -457,24 +478,28 @@ The compiler separates schemas into two files:
|
|
|
457
478
|
|
|
458
479
|
## Generated Routes
|
|
459
480
|
|
|
460
|
-
For each
|
|
481
|
+
For each table with routes, the compiler generates `src/features/{feature}/{table}.routes.ts` containing:
|
|
461
482
|
|
|
462
483
|
| Route | Generated When |
|
|
463
484
|
|-------|----------------|
|
|
464
|
-
| `GET /` | `
|
|
465
|
-
| `GET /:id` | `
|
|
485
|
+
| `GET /` | [`read`](/define/read) declared |
|
|
486
|
+
| `GET /:id` | [`read`](/define/read) declared |
|
|
487
|
+
| `GET /views/{name}` | `read.views.{name}` declared |
|
|
466
488
|
| `POST /` | `crud.create` configured |
|
|
467
489
|
| `PATCH /:id` | `crud.update` configured |
|
|
468
490
|
| `DELETE /:id` | `crud.delete` configured |
|
|
469
|
-
| `PUT /:id` | `crud.put` configured |
|
|
470
|
-
| `POST /batch` | `crud.create` exists (auto-enabled) |
|
|
471
|
-
| `PATCH /batch` | `crud.update` exists (auto-enabled) |
|
|
472
|
-
| `DELETE /batch` | `crud.delete` exists (auto-enabled) |
|
|
473
|
-
| `PUT /batch` | `crud.
|
|
474
|
-
| `GET /views/{name}` | `views` configured |
|
|
491
|
+
| `PUT /:id` | `crud.put` configured, with `generateId: false` and `guards: false` |
|
|
492
|
+
| `POST /batch` | `crud.create` exists (auto-enabled; `crud.batchCreate: false` opts out) |
|
|
493
|
+
| `PATCH /batch` | `crud.update` exists (auto-enabled; `crud.batchUpdate: false` opts out) |
|
|
494
|
+
| `DELETE /batch` | `crud.delete` exists (auto-enabled; `crud.batchDelete: false` opts out) |
|
|
495
|
+
| `PUT /batch` | `crud.batchUpsert`, or `crud.create` + `crud.update` when `PUT` is enabled |
|
|
475
496
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
476
497
|
| `POST /{action}` | Standalone actions defined |
|
|
477
498
|
|
|
499
|
+
`crud.list` and `crud.get` are rejected at compile time — collection and
|
|
500
|
+
single-record reads come from `read`. A verb with `routes: false` or mapped to
|
|
501
|
+
an action (`crud.create.action`) emits no raw route and no batch variant.
|
|
502
|
+
|
|
478
503
|
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
479
504
|
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. The standard API shape
|
|
480
505
|
selects semantics and leaves these paths alone.
|
|
@@ -541,6 +566,12 @@ is drift on a live database with no clean fix-forward.
|
|
|
541
566
|
Only `meta/_journal.json` is expected to change, because that is where a new
|
|
542
567
|
entry lands.
|
|
543
568
|
|
|
569
|
+
The generated header and footer comments count as part of the file. New
|
|
570
|
+
migrations are stamped with the current header; an existing one keeps the
|
|
571
|
+
header it was first stamped with, byte for byte, because deploy ledgers hash
|
|
572
|
+
applied migrations. See [Troubleshooting](/tooling/troubleshooting#recompile-changed-the-comments-at-the-top-of-an-old-migration)
|
|
573
|
+
if an earlier compiler already rewrote one.
|
|
574
|
+
|
|
544
575
|
> If `quickback migrations doctor` reports snapshot drift — more journal entries
|
|
545
576
|
> than snapshot files — that drift came from your project's history, not from
|
|
546
577
|
> compiling. Compile does not delete snapshots it was never given.
|