@quickback-dev/cli 0.65.1 → 0.66.1
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/compile.d.ts +1 -1
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -0
- package/dist/commands/compile.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +14 -6
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +26 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle.js +6 -1
- package/dist/lib/migrations/drizzle.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +3 -0
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +5 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +6 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/skill/SKILL.md +18 -3
- package/dist/skill/docs/api/batch-operations.md +1 -1
- package/dist/skill/docs/api/crud.md +1 -1
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/query-params.md +5 -8
- package/dist/skill/docs/changelog/index.md +87 -1
- package/dist/skill/docs/configure/auth.md +20 -12
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +19 -29
- package/dist/skill/docs/configure/providers.md +6 -4
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/define/access.md +3 -0
- package/dist/skill/docs/define/actions/defining.md +2 -2
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +23 -6
- package/dist/skill/docs/define/changesets.md +7 -8
- package/dist/skill/docs/define/feature.md +3 -2
- package/dist/skill/docs/define/firewall.md +2 -0
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/read.md +2 -2
- package/dist/skill/docs/define/relationships.md +7 -0
- package/dist/skill/docs/define/schema.md +21 -1
- package/dist/skill/docs/define/triggers.md +14 -3
- package/dist/skill/docs/platform/api-contract/index.md +52 -42
- package/dist/skill/docs/platform/auth/api-keys.md +1 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +13 -1
- package/dist/skill/docs/platform/database/neon.md +1 -1
- package/dist/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/dist/skill/docs/platform/realtime/index.md +8 -10
- package/dist/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/dist/skill/docs/platform/realtime/using-realtime.md +62 -36
- package/dist/skill/docs/platform/webhooks/outbound.md +4 -5
- package/dist/skill/docs/start/deploy-browser.md +2 -2
- package/dist/skill/docs/start/deploy-owner-access.md +49 -50
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/patterns.md +17 -2
- package/dist/skill/docs/start/template-cloudflare.md +1 -1
- package/dist/skill/docs/tooling/cli.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/dist/skill/docs/tooling/output.md +1 -1
- package/dist/skill/docs/ui/account/customization.md +1 -1
- package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/index.md +7 -6
- package/dist/skill/docs/ui/account/features/organizations.md +1 -1
- package/dist/skill/docs/ui/account/hooks.md +2 -1
- package/dist/skill/docs/ui/account/index.md +7 -4
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +18 -3
- package/src/skill/docs/api/batch-operations.md +1 -1
- package/src/skill/docs/api/crud.md +1 -1
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/query-params.md +5 -8
- package/src/skill/docs/changelog/index.md +87 -1
- package/src/skill/docs/configure/auth.md +20 -12
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +19 -29
- package/src/skill/docs/configure/providers.md +6 -4
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/define/access.md +3 -0
- package/src/skill/docs/define/actions/defining.md +2 -2
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/record-and-standalone.md +1 -1
- package/src/skill/docs/define/actions/scoped-db.md +23 -6
- package/src/skill/docs/define/changesets.md +7 -8
- package/src/skill/docs/define/feature.md +3 -2
- package/src/skill/docs/define/firewall.md +2 -0
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/read.md +2 -2
- package/src/skill/docs/define/relationships.md +7 -0
- package/src/skill/docs/define/schema.md +21 -1
- package/src/skill/docs/define/triggers.md +14 -3
- package/src/skill/docs/platform/api-contract/index.md +52 -42
- package/src/skill/docs/platform/auth/api-keys.md +1 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +1 -1
- package/src/skill/docs/platform/database/d1.md +13 -1
- package/src/skill/docs/platform/database/neon.md +1 -1
- package/src/skill/docs/platform/realtime/durable-objects.md +69 -36
- package/src/skill/docs/platform/realtime/index.md +8 -10
- package/src/skill/docs/platform/realtime/named-invalidations.md +23 -9
- package/src/skill/docs/platform/realtime/using-realtime.md +62 -36
- package/src/skill/docs/platform/webhooks/outbound.md +4 -5
- package/src/skill/docs/start/deploy-browser.md +2 -2
- package/src/skill/docs/start/deploy-owner-access.md +49 -50
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/patterns.md +17 -2
- package/src/skill/docs/start/template-cloudflare.md +1 -1
- package/src/skill/docs/tooling/cli.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +28 -0
- package/src/skill/docs/tooling/output.md +1 -1
- package/src/skill/docs/ui/account/customization.md +1 -1
- package/src/skill/docs/ui/account/features/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/index.md +7 -6
- package/src/skill/docs/ui/account/features/organizations.md +1 -1
- package/src/skill/docs/ui/account/hooks.md +2 -1
- package/src/skill/docs/ui/account/index.md +7 -4
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
|
@@ -94,9 +94,9 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
94
94
|
| Field | Type | Description |
|
|
95
95
|
|-------|------|-------------|
|
|
96
96
|
| `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/configure/domains) |
|
|
97
|
-
| `contract` | `{
|
|
97
|
+
| `contract` | `{ routes?: "v1" \| "v2" }` | `routes` selects the URL prefix and nothing else (default `"v1"`). See [API Contract](/platform/api-contract#one-axis-routes). |
|
|
98
98
|
| `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/configure/domains) |
|
|
99
|
-
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals
|
|
99
|
+
| `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`, `domain`) — see [Access](/define/access#role-hierarchy) and [Delegated principals](#delegated-principals) |
|
|
100
100
|
| `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `rules`, `tenants`, `permissions`, `arrows`) — see [Access](/define/authz-roles#centrally-defined-access-rules) and [Permissions](/define/permissions). `rules` = named gates (who + `record:` + firewall lanes under one name); `tenants` = named tenant anchors (`{ column, equals }`, referenced as `{ tenant: '<name>' }` in firewalls and `tenant: '<name>'` in auth-view includes). Root `authz` is the GLOBAL vocabulary level — names scoped to one concept belong in that concept's [feature area](/define/areas) (`_area.ts`), and root bodies may reference root-declared names only |
|
|
101
101
|
| `requires` | `string[]` | Capability floor (fail-closed guard). Declare `['feature-areas']` when the project uses `features/**/_area.ts` — an area-unaware CLI/compiler then refuses the compile instead of silently dropping nested features. See [Feature areas](/define/areas#the-capability-floor-requires-feature-areas) |
|
|
102
102
|
| `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
|
|
@@ -119,17 +119,16 @@ Every optional top-level key the config accepts is listed below. You never have
|
|
|
119
119
|
| `dev` | `object` | Local development settings (`port`, `api`, `cms`, `account`, `hostnames`) — see [Variables](/configure/variables) |
|
|
120
120
|
| `preset` | `string` | Inherit defaults from a named preset |
|
|
121
121
|
|
|
122
|
-
## Public contract
|
|
122
|
+
## Public contract routes
|
|
123
123
|
|
|
124
|
-
|
|
125
|
-
`
|
|
126
|
-
`routes: "v2"` to move the URLs:
|
|
124
|
+
`contract.routes` selects the URL prefix and nothing else. It defaults to
|
|
125
|
+
`"v1"`; set `"v2"` to move the URLs:
|
|
127
126
|
|
|
128
127
|
```typescript
|
|
129
128
|
export default defineConfig({
|
|
130
129
|
name: "my-app",
|
|
131
130
|
template: "hono",
|
|
132
|
-
contract: {
|
|
131
|
+
contract: { routes: "v2" },
|
|
133
132
|
providers: cloudflare({}),
|
|
134
133
|
});
|
|
135
134
|
```
|
|
@@ -141,8 +140,12 @@ and dedicated-domain shortcuts follow. When CMS or Account is enabled Quickback
|
|
|
141
140
|
bakes those paths into the SPA build and injects them at runtime. Quickback
|
|
142
141
|
does not expose a mixed v1/v2 URL surface from one compiled Worker.
|
|
143
142
|
|
|
144
|
-
|
|
145
|
-
|
|
143
|
+
`contract.version` is retired — there is one standard API shape. Pinning it is
|
|
144
|
+
a compile error; delete that line and keep `routes`. See
|
|
145
|
+
[API Contract](/platform/api-contract#contractversion-is-retired) for what
|
|
146
|
+
changes if you were pinned to `version: "v1"`.
|
|
147
|
+
|
|
148
|
+
Action input-schema fidelity is a compile gate since v0.63.0. The CLI must
|
|
146
149
|
successfully harvest `z.toJSONSchema(action.input)` for every authored action;
|
|
147
150
|
partial or missing harvests fail with the exact action file keys, bundle or
|
|
148
151
|
evaluation phase, and underlying local error. Dependencies are resolved from
|
|
@@ -151,26 +154,13 @@ ancestor installs, so an isolated `quickback/` definition tree can use a
|
|
|
151
154
|
sibling `src/` runtime without a workspace-root symlink. The compiler enforces
|
|
152
155
|
the same invariant at its shared input boundary, including
|
|
153
156
|
`POST /compile?complete=false`, so validation-only or raw API calls cannot
|
|
154
|
-
bypass it.
|
|
155
|
-
|
|
156
|
-
The version selection also moves the event and read surfaces:
|
|
157
|
-
|
|
158
|
-
| Surface | v1 (pinned) | v2 (flagship) |
|
|
159
|
-
|---|---|---|
|
|
160
|
-
| Realtime data frames (`/broadcast/*`) | raw frames, byte-stable | CloudEvents 1.0 envelopes at DO egress ([realtime](/platform/realtime)) |
|
|
161
|
-
| Outbound webhook signing | Standard Webhooks headers **plus** legacy `X-Webhook-*` | Standard Webhooks **only** |
|
|
162
|
-
| `?include=` FK-graph embedding | not available | available where a resource/view allowlists it |
|
|
163
|
-
| Bare `?fields=` / `fields[<fk>]=` unknown names | silent drop / n/a | 400 on both |
|
|
164
|
-
|
|
165
|
-
See [API Contract](/platform/api-contract) for the full v1 → v2 matrix and
|
|
166
|
-
migration sequencing.
|
|
157
|
+
bypass it.
|
|
167
158
|
|
|
168
|
-
## Delegated principals
|
|
159
|
+
## Delegated principals
|
|
169
160
|
|
|
170
161
|
`auth.principals` defines non-account authority such as an event pass or a
|
|
171
|
-
short-lived event session. It
|
|
162
|
+
short-lived event session. It requires both of:
|
|
172
163
|
|
|
173
|
-
- `contract: { version: "v2" }`
|
|
174
164
|
- the Cloudflare runtime
|
|
175
165
|
- Neon with `connectionMode: "hyperdrive"`
|
|
176
166
|
|
|
@@ -182,7 +172,6 @@ principal types cannot share a scheme.
|
|
|
182
172
|
export default defineConfig({
|
|
183
173
|
name: "attend-v2",
|
|
184
174
|
template: "hono",
|
|
185
|
-
contract: { version: "v2" },
|
|
186
175
|
auth: {
|
|
187
176
|
principals: {
|
|
188
177
|
event_pass: {
|
|
@@ -500,7 +489,7 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
500
489
|
When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
|
|
501
490
|
|
|
502
491
|
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
-
when `contract.routes` is `"v2"` (the URL axis —
|
|
492
|
+
when `contract.routes` is `"v2"` (the URL axis — the standard shape does
|
|
504
493
|
not move these)
|
|
505
494
|
- `/storage/*` — R2 file storage
|
|
506
495
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
@@ -631,7 +620,8 @@ account: {
|
|
|
631
620
|
|--------|------|-------------|
|
|
632
621
|
| `domain` | `string` | Custom domain for Account UI (e.g., `auth.example.com`) |
|
|
633
622
|
| `adminDomain` | `string` | Custom domain for admin-only access (e.g., `admin.example.com`). Serves the same Account SPA — the client-side router handles admin routing. |
|
|
634
|
-
| `appUrl` | `string` |
|
|
623
|
+
| `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for the profile **Go to…** picker. Independent from `domain`. A deploy-target `APP_URL` can override this at serve time. |
|
|
624
|
+
| `tenantPattern` | `string` | URL pattern for a tenant, with `{slug}` substituted. Default `/{slug}`. Relative patterns are resolved against `appUrl`; a full `https://{slug}.example.com` pattern is used as-is. Baked as `VITE_TENANT_URL_PATTERN`. |
|
|
635
625
|
| `name` | `string` | App display name shown on login, profile, and email templates |
|
|
636
626
|
| `companyName` | `string` | Company name for branding |
|
|
637
627
|
| `tagline` | `string` | App tagline shown on login page |
|
|
@@ -649,7 +639,7 @@ Control which authentication features are exposed. Disabled features are exclude
|
|
|
649
639
|
| `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
|
|
650
640
|
| `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
|
|
651
641
|
| `auth.signup` | `boolean` | `true` | `emailAndPassword.disableSignUp` (inverted) | Self-service account registration — false hides the UI **and** rejects the server endpoint with 403 |
|
|
652
|
-
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (dashboard, invitations, roles). Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
|
|
642
|
+
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (`/dashboard` org list, invitations, roles). Sign-in lands on `/profile`. Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
|
|
653
643
|
| `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
|
|
654
644
|
| `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
|
|
655
645
|
|
|
@@ -105,7 +105,7 @@ single Postgres database with no bindings or split mode (see
|
|
|
105
105
|
| `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |
|
|
106
106
|
| `auditBinding` | `string` | `"AUDIT_DB"` | Binding name for the security audit database |
|
|
107
107
|
| `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
|
|
108
|
-
| `auditDatabaseId` | `string` | — |
|
|
108
|
+
| `auditDatabaseId` | `string` | — | D1 database ID for audit events. Optional at compile time — a placeholder is emitted and `quickback deploy` / the Start broker create the database and splice the real id back |
|
|
109
109
|
| `experimentalRemote` | `{ auth?, features?, audit?, webhooks?, files? }` | `{}` | Per-binding `experimental_remote = true` flag for `wrangler dev` (see [below](#sharing-deployed-d1-in-dev-experimental_remote)) |
|
|
110
110
|
| `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
|
|
111
111
|
| `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
|
|
@@ -127,7 +127,9 @@ connection modes, RLS, and the migration workflow.
|
|
|
127
127
|
|
|
128
128
|
Cross-tenant `unsafe` actions (see [Actions → Unsafe mode](/define/actions/scoped-db#unsafe-mode)) write mandatory audit events. Those events land in a dedicated D1 database — separate from your features DB — so audit history stays isolated from application data and can't be tampered with through a normal CRUD route.
|
|
129
129
|
|
|
130
|
-
You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe action.
|
|
130
|
+
You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe, `PUBLIC`, or hard-delete action. Leave `auditDatabaseId` unset until deploy: compile emits a placeholder, and `quickback deploy` (or the Start Cloudflare card) creates the D1 and writes the id back. Do not put an empty string in the config.
|
|
131
|
+
|
|
132
|
+
To override defaults:
|
|
131
133
|
|
|
132
134
|
```typescript
|
|
133
135
|
providers: {
|
|
@@ -139,7 +141,7 @@ providers: {
|
|
|
139
141
|
}
|
|
140
142
|
```
|
|
141
143
|
|
|
142
|
-
The binding name must match what your Worker reads at runtime. If you don't declare any unsafe actions, no audit DB is provisioned and these options have no effect.
|
|
144
|
+
The binding name must match what your Worker reads at runtime. If you don't declare any unsafe, `PUBLIC`, or hard-delete actions, no audit DB is provisioned and these options have no effect.
|
|
143
145
|
|
|
144
146
|
#### Setting Database IDs for Deployment
|
|
145
147
|
|
|
@@ -215,7 +217,7 @@ providers: {
|
|
|
215
217
|
}
|
|
216
218
|
```
|
|
217
219
|
|
|
218
|
-
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`.
|
|
220
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. The path is the only thing `routes` moves — frame format is unaffected.
|
|
219
221
|
|
|
220
222
|
`wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
|
|
221
223
|
|
|
@@ -25,9 +25,13 @@ export default defineConfig({
|
|
|
25
25
|
});
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
> **
|
|
28
|
+
> **The organization must exist**
|
|
29
29
|
>
|
|
30
|
-
> `pinnedOrganizationId`
|
|
30
|
+
> `pinnedOrganizationId` is the Better Auth organization id the compiled Worker hard-codes. The compiler does not insert that row.
|
|
31
|
+
>
|
|
32
|
+
> A **browser deploy** from Quickback Start does: the broker writes `organization.id` as this exact string, seeds `user.role = "sysadmin"`, and seats that user as `owner` of the org. `org_default` is a valid id — use it when you do not have a pre-existing org.
|
|
33
|
+
>
|
|
34
|
+
> A **CLI deploy** (`quickback deploy`) does not seed AUTH_DB. Create the organization yourself (or deploy once through Start) so the pin points at a real row.
|
|
31
35
|
|
|
32
36
|
|
|
33
37
|
## Removed Single-Tenant Settings
|
|
@@ -96,7 +100,7 @@ This is the intended replacement for the old single-tenant CMS flow.
|
|
|
96
100
|
## Migration from Single-Tenant Mode
|
|
97
101
|
|
|
98
102
|
1. Remove `features.organizations: false`.
|
|
99
|
-
2. Add `features.pinnedOrganizationId: "<
|
|
103
|
+
2. Add `features.pinnedOrganizationId: "<org-id>"`. On a Start deploy, that string is the org the broker inserts — `"org_default"` is fine. On a CLI deploy, it must already exist in AUTH_DB.
|
|
100
104
|
3. Remove any assumptions that `ctx.roles` mirrors `user.role`.
|
|
101
105
|
4. If you need platform-wide roles, keep those checks on `userRole`, not `roles`.
|
|
102
106
|
|
|
@@ -23,6 +23,9 @@ Start here. **Most apps need only the first row** — this page, and nothing bel
|
|
|
23
23
|
> declare a relationship to ask "is this person in the org?" — a relationship's `from:` must
|
|
24
24
|
> be one of *your* feature tables, and the compiler rejects one pointing at Better Auth's
|
|
25
25
|
> `organization_memberships`. See [the authorization ladder](/define#the-authorization-ladder).
|
|
26
|
+
>
|
|
27
|
+
> To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
|
|
28
|
+
> see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
26
29
|
|
|
27
30
|
|
|
28
31
|
## Basic Usage
|
|
@@ -83,7 +83,7 @@ Zod 4's `z.toJSONSchema`. It does not call `execute`; the hosted compiler never
|
|
|
83
83
|
evaluates project code. The output contract feeds OpenAPI and
|
|
84
84
|
`Api.<feature>.actions.<action>.Output` in `quickback.gen.ts`.
|
|
85
85
|
|
|
86
|
-
**Every action input must produce a schema
|
|
86
|
+
**Every action input must produce a schema.** Since
|
|
87
87
|
v0.63.0 a failed harvest fails the compile, naming the exact action, whether
|
|
88
88
|
bundling or evaluation failed, and the underlying local error. Output remains
|
|
89
89
|
optional.
|
|
@@ -160,7 +160,7 @@ see [Error Handling](/api/actions#error-handling) for what actually happens.
|
|
|
160
160
|
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
161
161
|
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
162
162
|
those segments to the OpenAPI `{param}` form before applying the schema, so
|
|
163
|
-
|
|
163
|
+
completeness uses the same route key as the emitted OpenAPI and MCP
|
|
164
164
|
surfaces. The same normalization applies when a record resource path contains
|
|
165
165
|
namespace parameters.
|
|
166
166
|
|
|
@@ -169,7 +169,7 @@ is not supported.
|
|
|
169
169
|
- **[Defining actions](/define/actions/defining)** — the action file, its configuration options, protected fields, and refs
|
|
170
170
|
- **[Record and standalone actions](/define/actions/record-and-standalone)** — the two shapes, and what `path:` changes
|
|
171
171
|
- **[Access](/define/actions/access)** — roles, record conditions, context substitution, relationship-roles
|
|
172
|
-
- **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, unsafe mode, raw SQL policy, sharing code
|
|
172
|
+
- **[Scoped database](/define/actions/scoped-db)** — the firewalled `db` handle, AUTH_DB vs `ctx`, unsafe mode, raw SQL policy, sharing code
|
|
173
173
|
- **[Examples](/define/actions/examples)** — end-to-end action files
|
|
174
174
|
|
|
175
175
|
Related: **[Transitions](/define/transitions)** for state-machine policy,
|
|
@@ -138,7 +138,7 @@ single-record endpoint (`POST /:id/{action}`) or write a standalone action.
|
|
|
138
138
|
|
|
139
139
|
The generated OpenAPI document and MCP tools reuse that exact action schema
|
|
140
140
|
in both places: as the single-record request body and as the bulk wrapper's
|
|
141
|
-
nested `input` property.
|
|
141
|
+
nested `input` property. Quickback considers the action's
|
|
142
142
|
schema harvest complete only after both operations are patched. This also
|
|
143
143
|
holds when the table filename and declared table name use different casing or
|
|
144
144
|
separators (for example, `event-guests.ts` exporting `event_guests`); the
|
|
@@ -32,7 +32,7 @@ async execute({ db, ctx, input }) {
|
|
|
32
32
|
|
|
33
33
|
### Delegated principals and `databaseAccess`
|
|
34
34
|
|
|
35
|
-
On a
|
|
35
|
+
On a Cloudflare + Neon Hyperdrive project, an action can admit a
|
|
36
36
|
configured delegated principal with `access.principals`:
|
|
37
37
|
|
|
38
38
|
```typescript
|
|
@@ -448,9 +448,14 @@ with the transition's "from" precondition for transition actions.
|
|
|
448
448
|
|
|
449
449
|
#### Reaching Better Auth tables (`authDb`)
|
|
450
450
|
|
|
451
|
-
The scoped `db`
|
|
452
|
-
|
|
453
|
-
|
|
451
|
+
The scoped `db` is the **features** database. Better Auth tables never appear
|
|
452
|
+
on it — that is by design. `AUTH_DB` is a separate Drizzle client.
|
|
453
|
+
|
|
454
|
+
**Caller identity — use `ctx`, do not query `AUTH_DB`.** `ctx.userId`,
|
|
455
|
+
`ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request.
|
|
456
|
+
|
|
457
|
+
To check that a *submitted* user id is an org member (assignee-style
|
|
458
|
+
features), use `c.get("authDb")` plus the generated `getOrgMemberRole` helper:
|
|
454
459
|
|
|
455
460
|
```typescript
|
|
456
461
|
// features/projects/actions/assign.ts — validate a userId is an org member
|
|
@@ -481,6 +486,18 @@ export default defineAction({
|
|
|
481
486
|
```
|
|
482
487
|
|
|
483
488
|
`c.get("authDb")` is the Drizzle connection to the auth database (in dual-DB
|
|
484
|
-
mode it's a separate D1 from your features).
|
|
485
|
-
|
|
489
|
+
mode it's a separate D1 from your features). That is the native membership
|
|
490
|
+
check.
|
|
491
|
+
|
|
492
|
+
For a richer query, use the same `authDb` and import tables from
|
|
493
|
+
`../../../auth/schema` — from an **`actions/` file**. On D1 the tables are
|
|
494
|
+
`user`, `organization`, and `member` — not `organization_membership`. (Neon
|
|
495
|
+
exports the Better Auth CLI's plural names: `users`, `organizations`,
|
|
496
|
+
`members`.)
|
|
497
|
+
|
|
498
|
+
| Surface | AUTH_DB handle | Notes |
|
|
499
|
+
|---|---|---|
|
|
500
|
+
| Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
|
|
501
|
+
| [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
|
|
502
|
+
| Trigger `handler:` | **none** | Args are `{ ctx, db, env }` — `db` is features only. There is no `c`. Prefer `ctx` for the acting user. Do not import `../../auth/schema` from the table file to reach AUTH_DB; that path used to compile and then fail package-mode wrangler. Check another user's membership in an action. |
|
|
486
503
|
|
|
@@ -7,12 +7,11 @@ compiler was missing — which relations are **compositions** (owned by this
|
|
|
7
7
|
root) vs **references** (independent entities) — and the compiler generates
|
|
8
8
|
the whole write path.
|
|
9
9
|
|
|
10
|
-
Changesets are a **contract v2** capability (`contract: { version: "v2" }`).
|
|
11
10
|
Declaring `owns` on a v1-pinned project is a compile error.
|
|
12
11
|
|
|
13
12
|
## Declaring the boundary — `owns`
|
|
14
13
|
|
|
15
|
-
{/* doc-compile: skip —
|
|
14
|
+
{/* doc-compile: skip — the fence is the `owns` boundary only: columns/firewall/guards/masking/read are elided, and it names three sibling tables (`tasks`, `people`, `taskChecklistItems`) it deliberately does not repeat. */}
|
|
16
15
|
```ts title="quickback/features/projects/projects.ts"
|
|
17
16
|
export default feature("projects", {
|
|
18
17
|
// ...columns, firewall, guards, masking, read...
|
|
@@ -70,9 +69,9 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
69
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
70
|
have. No subpath.
|
|
72
71
|
|
|
73
|
-
Paths below use the default `/api/v1` prefix. Changesets are a
|
|
72
|
+
Paths below use the default `/api/v1` prefix. Changesets are a
|
|
74
73
|
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
-
moving your URLs — set [`contract.routes`](/platform/api-contract#
|
|
74
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#one-axis-routes)
|
|
76
75
|
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
76
|
|
|
78
77
|
- `PATCH /api/v1/<resource>/:id` with
|
|
@@ -212,7 +211,7 @@ stamping (`createdBy` / `modifiedBy`) rides the same chokepoint. The only gap is
|
|
|
212
211
|
`afterDelete`, which the soft-delete stamp can't see — identical to the plain
|
|
213
212
|
DELETE route's own limitation. (`sql:` triggers fire on every path regardless,
|
|
214
213
|
as always.) This is the parity the trigger docs promise: a generated
|
|
215
|
-
|
|
214
|
+
changeset is a compiler write surface, not one of the
|
|
216
215
|
queue/cron/raw-SQL bypasses that skip handler hooks.
|
|
217
216
|
|
|
218
217
|
Compile-time, fail-closed (everything throws, nothing normalizes silently):
|
|
@@ -244,7 +243,7 @@ Compile-time, fail-closed (everything throws, nothing normalizes silently):
|
|
|
244
243
|
the wire parser reserves those payload keys, so such a relation would be
|
|
245
244
|
silently unreachable on the wire.
|
|
246
245
|
- One aggregate root per table, acyclic graph, bounded depth, declared child
|
|
247
|
-
ops only, soft-delete children only
|
|
246
|
+
ops only, soft-delete children only.
|
|
248
247
|
|
|
249
248
|
## `afterCommit` — emit a realtime signal after the changeset commits
|
|
250
249
|
|
|
@@ -255,7 +254,7 @@ strictly **after** the transaction commits, riding the existing
|
|
|
255
254
|
[named-invalidation / Broadcaster egress](/platform/realtime/named-invalidations)
|
|
256
255
|
(so it inherits the CloudEvents envelope + AsyncAPI description for free).
|
|
257
256
|
|
|
258
|
-
{/* doc-compile: skip — project-config
|
|
257
|
+
{/* doc-compile: skip — project-config prerequisite this fence cannot carry: the `broadcast` event `attendRealtime.mobileBundleChanged.travelUpdated` plus its `thisEvent` delivery profile must be declared in a realtime registry under `services/realtime/`. Columns/firewall/read/crud are elided to `// ...` and the owned child table is not repeated. */}
|
|
259
258
|
```ts title="quickback/features/travel/lodging-reservations.ts"
|
|
260
259
|
export default defineTable(lodgingReservations, {
|
|
261
260
|
// ...firewall / read / crud ...
|
|
@@ -423,7 +422,7 @@ authored actions delegate through when they still need residue logic
|
|
|
423
422
|
(preconditions, server-side transforms, notifications) around the aggregate
|
|
424
423
|
write:
|
|
425
424
|
|
|
426
|
-
{/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a
|
|
425
|
+
{/* doc-compile: skip — the fence imports `../projects.changeset`, a module the compiler only generates for a root that declares `owns`, which this fence does not carry, so the import cannot resolve. `description` / `input` / `access` are elided to `// ...` on purpose — the point is the delegation seam. */}
|
|
427
426
|
```ts title="quickback/features/projects/actions/importBoard.ts"
|
|
428
427
|
// Action files are compiled into the feature directory, next to the
|
|
429
428
|
// generated module — the relative import resolves at runtime.
|
|
@@ -187,11 +187,12 @@ For everything action-related — record vs standalone, conflict rules, the gene
|
|
|
187
187
|
## Composition vs reference — `owns`
|
|
188
188
|
|
|
189
189
|
A schema-level FK (`references:` / `.references()`) says "this row points at
|
|
190
|
-
that row." It does **not** say who owns whom.
|
|
190
|
+
that row." It does **not** say who owns whom. `.references()` may only target
|
|
191
|
+
another **feature table in the same database** — never Better Auth `users` /
|
|
192
|
+
`user` / `organization` / `member` (those live in `AUTH_DB`). When a set of child rows has no
|
|
191
193
|
lifecycle of its own — junction memberships, normalized phones/emails, line
|
|
192
194
|
items — declare the composition with `owns` on the root table:
|
|
193
195
|
|
|
194
|
-
{/* doc-compile: skip — project-config prerequisite: `owns` is a contract-v2 capability (the prose below says so) and needs `contract: { version: 'v2' }` in quickback.config.ts; the gate's harness config pins v1. The file is otherwise whole. */}
|
|
195
196
|
```ts
|
|
196
197
|
export default feature("projects", {
|
|
197
198
|
columns: {
|
|
@@ -90,6 +90,8 @@ An explicit predicate on a custom-named column is honoured **on that table** via
|
|
|
90
90
|
|
|
91
91
|
If `userId` is genuinely informational, rename it to something that says so (`linkedUserId`, `assigneeId`, `inviteeId`) and the warning goes away.
|
|
92
92
|
|
|
93
|
+
Do **not** turn that column into a SQL FK to Better Auth. `.references(() => users.id)` (or `user`) is illegal across split D1s (`AUTH_DB` vs `DB`) and deploy fails with `Generate features database migrations`. Store it as `q.text().required()`. See [Schema → References](/define/schema).
|
|
94
|
+
|
|
93
95
|
## Predicate Shape
|
|
94
96
|
|
|
95
97
|
```typescript
|
|
@@ -17,7 +17,7 @@ Quickback is a **backend compiler**. You write definition files, and Quickback c
|
|
|
17
17
|
- **Don't** create a `workspaces` / `teams` / `tenants` table.
|
|
18
18
|
- **Don't** create a membership or `*_members` table.
|
|
19
19
|
- **Do** put `organizationId: q.scope("organization")` on every tenant-scoped table — the firewall is auto-derived from it.
|
|
20
|
-
- Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`.
|
|
20
|
+
- Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. Do not query AUTH_DB for the **acting** user. To check that a *submitted* user id belongs to the org, query AUTH_DB from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
21
21
|
- Create a tenant with `POST /auth/v1/organization/create` and switch with `POST /auth/v1/organization/set-active` — not a custom action.
|
|
22
22
|
|
|
23
23
|
If your product calls it something else, that's a **label, not a schema decision** — the Account UI renames the organization surfaces for you (see [Account → Customization](/ui/account/customization)).
|
|
@@ -233,7 +233,7 @@ export default defineTable(balanceSnapshots, {
|
|
|
233
233
|
|
|
234
234
|
## Aggregate Reads
|
|
235
235
|
|
|
236
|
-
Reading a parent **with** its owned relations rides
|
|
236
|
+
Reading a parent **with** its owned relations rides `?include=`,
|
|
237
237
|
which accepts two kinds of tokens in the same `read.include` allowlist:
|
|
238
238
|
|
|
239
239
|
- **FK columns** (`?include=vendorId`) — forward embeds: the target rows the
|
|
@@ -242,7 +242,7 @@ which accepts two kinds of tokens in the same `read.include` allowlist:
|
|
|
242
242
|
reader: the changeset root's owned **child rows**, pivoting on the root PK
|
|
243
243
|
and matching the child's declared `fk` column.
|
|
244
244
|
|
|
245
|
-
{/* doc-compile: skip —
|
|
245
|
+
{/* doc-compile: skip — the fence names a `noteReactions` child table it deliberately does not repeat. */}
|
|
246
246
|
```typescript
|
|
247
247
|
export default defineTable(notes, {
|
|
248
248
|
owns: { reactions: { table: 'noteReactions', fk: 'noteId' } },
|
|
@@ -10,6 +10,8 @@ isn't in your org.
|
|
|
10
10
|
> A relationship's `from:` must be one of *your* feature tables — the compiler rejects one
|
|
11
11
|
> pointing at Better Auth's `organization_memberships`, `organizations`, or `user`. Org
|
|
12
12
|
> membership is already decided before your handler runs and is available as `ctx.roles`.
|
|
13
|
+
> To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
|
|
14
|
+
> see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
13
15
|
>
|
|
14
16
|
> A relationship's `where:` also takes **scalar equality only** (`string | number |
|
|
15
17
|
> boolean`). `where: { role: ['admin','owner'] }` is not valid — declare one relationship
|
|
@@ -53,6 +55,11 @@ export default defineConfig({
|
|
|
53
55
|
});
|
|
54
56
|
```
|
|
55
57
|
|
|
58
|
+
> **userId is not a SQL FK to Better Auth**
|
|
59
|
+
>
|
|
60
|
+
> `subject: { column: 'userId', equals: 'ctx.userId' }` matches a **plain text** column on your join table. Do not write `.references(() => users.id)` (or `user`, `organization`, `member`) on that column. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. SQLite cannot FK across those databases, and drizzle-kit fails generating features migrations with `Critical command failed: Generate features database migrations`. Store it as `userId: q.text().required()`. See [Schema → References](/define/schema).
|
|
61
|
+
|
|
62
|
+
|
|
56
63
|
> **The `from:` table needs its own defineTable**
|
|
57
64
|
>
|
|
58
65
|
> A relationship resolves through the `from:` table's **generated resource module**
|
|
@@ -82,7 +82,27 @@ A few mechanics to know:
|
|
|
82
82
|
- **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
|
|
83
83
|
- **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
|
|
84
84
|
- **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
|
|
85
|
-
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path.
|
|
85
|
+
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
|
|
86
|
+
|
|
87
|
+
> **Never FK Better Auth tables**
|
|
88
|
+
>
|
|
89
|
+
> `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
|
|
90
|
+
>
|
|
91
|
+
> `Critical command failed: Generate features database migrations`
|
|
92
|
+
>
|
|
93
|
+
> A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
|
|
94
|
+
>
|
|
95
|
+
> A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
|
|
96
|
+
>
|
|
97
|
+
> {/* doc-compile: skip — two-column excerpt, not a host feature */}
|
|
98
|
+
> ```typescript
|
|
99
|
+
> userId: q.text().required(), // ctx.userId — no .references()
|
|
100
|
+
> channelId: q.text().required().references(() => channels.id, { onDelete: 'cascade' }),
|
|
101
|
+
> ```
|
|
102
|
+
>
|
|
103
|
+
> `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
104
|
+
|
|
105
|
+
|
|
86
106
|
- **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
|
|
87
107
|
|
|
88
108
|
### Column Types
|
|
@@ -106,6 +106,15 @@ Live Views, with full application context:
|
|
|
106
106
|
handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) => { ... }
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
+
The `db` a handler receives is the **features** database. There is no `c` and
|
|
110
|
+
no `authDb`. Prefer `ctx.userId`, `ctx.activeOrgId`, `ctx.roles`, and
|
|
111
|
+
`ctx.userRole` for the acting user.
|
|
112
|
+
|
|
113
|
+
Do **not** import `../../auth/schema` from the table file to reach AUTH_DB —
|
|
114
|
+
that import used to survive compile and then fail package-mode wrangler with
|
|
115
|
+
`Could not resolve`. Checking that another user is an org member belongs in
|
|
116
|
+
an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
117
|
+
|
|
109
118
|
- **`before*` hooks are synchronous.** Return a partial object to merge
|
|
110
119
|
into the write payload, or throw to reject — the write never executes and
|
|
111
120
|
the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
|
|
@@ -116,9 +125,11 @@ handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) =>
|
|
|
116
125
|
`TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
|
|
117
126
|
already persisted (no transactions on D1), so clients must not blind-retry.
|
|
118
127
|
- Handlers must be **inline arrow/function expressions**. Imports they
|
|
119
|
-
reference are hoisted into the generated registry
|
|
120
|
-
|
|
121
|
-
as
|
|
128
|
+
reference are hoisted into the generated registry (`src/lib/trigger-hooks.ts`)
|
|
129
|
+
with relative paths rewritten from the table file — including dynamic
|
|
130
|
+
`import("…")` inside the handler. Write them as they resolve next to the
|
|
131
|
+
table. Each table's drizzle object is auto-imported under its authored
|
|
132
|
+
name — so this works as written:
|
|
122
133
|
|
|
123
134
|
```typescript
|
|
124
135
|
import { eq } from 'drizzle-orm';
|