@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
|
@@ -161,7 +161,14 @@ export default defineAction({
|
|
|
161
161
|
|
|
162
162
|
## Referencing Users / Org Members (Assignees)
|
|
163
163
|
|
|
164
|
-
|
|
164
|
+
The **caller's** identity is already on the request — `ctx.userId`,
|
|
165
|
+
`ctx.activeOrgId`, `ctx.roles`, `ctx.userRole`. Do not query `AUTH_DB` for
|
|
166
|
+
the acting user.
|
|
167
|
+
|
|
168
|
+
Assignee-style features need to validate that a *submitted* `userId` is
|
|
169
|
+
actually a member of the caller's organization. The scoped `db` never
|
|
170
|
+
includes Better Auth tables — that is by design. Reach AUTH_DB from an
|
|
171
|
+
**action** via `c.get("authDb")` and the generated `getOrgMemberRole` helper:
|
|
165
172
|
|
|
166
173
|
```typescript
|
|
167
174
|
// quickback/features/projects/actions/assign.ts
|
|
@@ -189,7 +196,15 @@ export default defineAction({
|
|
|
189
196
|
});
|
|
190
197
|
```
|
|
191
198
|
|
|
192
|
-
Store the assignee as a plain text column (e.g. `assigneeId: q.text().optional()`) — don't name it `userId`. `userId` is *not* auto-detected as an owner column on feature tables (that column is `ownerId`), but the compiler flags it: an error if it's the only candidate column on the table, a warning alongside a detected isolation column. Rename to `assigneeId`, or declare `firewall: { owner: { column: "userId" } }` if the column really is the row's owner. See [Firewall](/define/firewall).
|
|
199
|
+
Store the assignee as a plain text column (e.g. `assigneeId: q.text().optional()`) — don't name it `userId`, and **never** `.references(() => users.id)`. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. A SQL FK across those databases is not possible, and drizzle-kit fails generating features migrations. `userId` is *not* auto-detected as an owner column on feature tables (that column is `ownerId`), but the compiler flags it: an error if it's the only candidate column on the table, a warning alongside a detected isolation column. Rename to `assigneeId`, or declare `firewall: { owner: { column: "userId" } }` if the column really is the row's owner. See [Firewall](/define/firewall) and [Schema → References](/define/schema).
|
|
200
|
+
|
|
201
|
+
On D1 the Better Auth tables are `user`, `organization`, and `member` — not
|
|
202
|
+
`organization_membership`. For a richer query from an `actions/` file, import
|
|
203
|
+
those from `../../../auth/schema` and query `c.get("authDb")`. Account hooks
|
|
204
|
+
get `{ authDb, authSchema }` injected ([Auth Hooks](/ui/account/hooks)).
|
|
205
|
+
Trigger `handler:` args are `{ ctx, db, env }` — `db` is features only; there
|
|
206
|
+
is no `c` and no `authDb`. Prefer `ctx`. Do not import `../../auth/schema`
|
|
207
|
+
from a table file ([Triggers](/define/triggers)).
|
|
193
208
|
|
|
194
209
|
## Admin-Only Status Field
|
|
195
210
|
|
|
@@ -216,7 +216,7 @@ Depending on your configuration, the compiler may also generate bindings for:
|
|
|
216
216
|
|
|
217
217
|
By default, the Cloudflare template separates auth tables from application tables:
|
|
218
218
|
|
|
219
|
-
- **`AUTH_DB`** — Better Auth tables (`
|
|
219
|
+
- **`AUTH_DB`** — Better Auth tables (`user`, `session`, `account`, `organization`, `member`)
|
|
220
220
|
- **`DB`** — Your feature tables (`todos`, etc.)
|
|
221
221
|
|
|
222
222
|
This keeps auth data isolated and allows independent scaling. Each database gets its own migration directory:
|
|
@@ -372,7 +372,7 @@ quickback compile
|
|
|
372
372
|
|
|
373
373
|
The API key takes precedence over stored credentials from `quickback login`.
|
|
374
374
|
|
|
375
|
-
You can create API keys from your [Quickback account](https://account.quickback.dev/
|
|
375
|
+
You can create API keys from your [Quickback account](https://account.quickback.dev/api-keys). Each key is scoped to your organization.
|
|
376
376
|
|
|
377
377
|
### Custom Compiler URL
|
|
378
378
|
|
|
@@ -22,7 +22,7 @@ For non-interactive environments (CI/CD, scripts), use an API key:
|
|
|
22
22
|
QUICKBACK_API_KEY=your_api_key quickback compile
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
Create API keys from your [Quickback account](https://account.quickback.dev/
|
|
25
|
+
Create API keys from your [Quickback account](https://account.quickback.dev/api-keys). Each key is scoped to your organization.
|
|
26
26
|
|
|
27
27
|
The API key takes precedence over stored credentials from `quickback login`.
|
|
28
28
|
|
|
@@ -67,6 +67,34 @@ If a hint is missing, compile now fails loudly with the exact key path to add, f
|
|
|
67
67
|
- `Expected hint key: compiler.migrations.renames.tables["events_v2"]`
|
|
68
68
|
- `Expected hint key: compiler.migrations.renames.columns["events"]["summary_text"]`
|
|
69
69
|
|
|
70
|
+
## `Critical command failed: Generate features database migrations`
|
|
71
|
+
|
|
72
|
+
drizzle-kit could not load the generated **features** schema. The usual cause on
|
|
73
|
+
D1 (`splitDatabases: true`) is a feature column that `.references()` a Better
|
|
74
|
+
Auth table:
|
|
75
|
+
|
|
76
|
+
{/* doc-compile: skip — illegal one-liner, not a host feature */}
|
|
77
|
+
```typescript
|
|
78
|
+
userId: q.text().required().references(() => users.id, { onDelete: 'cascade' }) // illegal
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`users` / `user` / `organization` / `member` live in `AUTH_DB`. Features live in
|
|
82
|
+
`DB`. SQLite cannot FK across them, and drizzle-kit cannot resolve `users` when
|
|
83
|
+
generating features migrations.
|
|
84
|
+
|
|
85
|
+
A Start chat compile (`complete=false`) still succeeds — it never runs
|
|
86
|
+
drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
|
|
87
|
+
|
|
88
|
+
Store the Better Auth id as plain text:
|
|
89
|
+
|
|
90
|
+
{/* doc-compile: skip — one-liner, not a host feature */}
|
|
91
|
+
```typescript
|
|
92
|
+
userId: q.text().required()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`.references()` is only for another feature table in `DB`. See
|
|
96
|
+
[Schema → References](/define/schema).
|
|
97
|
+
|
|
70
98
|
## "Could not load organizations"
|
|
71
99
|
|
|
72
100
|
This can happen if your session token expired or if the API is temporarily unavailable. Re-login:
|
|
@@ -378,7 +378,7 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
|
|
|
378
378
|
| `POST /{action}` | Standalone actions defined |
|
|
379
379
|
|
|
380
380
|
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
381
|
-
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set.
|
|
381
|
+
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. The standard API shape
|
|
382
382
|
selects semantics and leaves these paths alone.
|
|
383
383
|
|
|
384
384
|
## Migrations
|
|
@@ -93,7 +93,7 @@ setAppConfig({
|
|
|
93
93
|
| `privacy` | "Privacy Policy" | Footer link text |
|
|
94
94
|
| `support` | "Contact Support" | Footer link text |
|
|
95
95
|
| `company` | (from `VITE_COMPANY_NAME`) | Footer company name |
|
|
96
|
-
| `organizations` | "Organizations" | Navigation and page titles |
|
|
96
|
+
| `organizations` | "Organizations" | Navigation and page titles. Profile and the user menu prefix this as **Manage …** (`Manage Organizations`). |
|
|
97
97
|
|
|
98
98
|
## Custom Messages
|
|
99
99
|
|
|
@@ -1,21 +1,23 @@
|
|
|
1
1
|
# API Key Management
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
API keys are a user credential. Manage them at `/api-keys`, linked from `/profile`. The `apiKey` plugin is on by default.
|
|
4
4
|
|
|
5
5
|
## Creating API Keys
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
7
|
+
- Custom name
|
|
8
|
+
- Shown once at creation — copy it then
|
|
9
|
+
- Scoped to an organization via `metadata.organizationId` so the key inherits your role in that tenant
|
|
10
|
+
- One organization: stamped automatically
|
|
11
|
+
- Several organizations: pick one when creating
|
|
12
12
|
|
|
13
13
|
## Managing Keys
|
|
14
14
|
|
|
15
|
-
-
|
|
16
|
-
- See last-used timestamp
|
|
15
|
+
- List every key you own (not filtered to the current org)
|
|
16
|
+
- See last-used timestamp and which organization the key is scoped to
|
|
17
17
|
- Revoke individual keys
|
|
18
18
|
|
|
19
|
+
`/$slug/api-keys` redirects here so old bookmarks still work.
|
|
20
|
+
|
|
19
21
|
## Related
|
|
20
22
|
|
|
21
23
|
- [API Keys Auth](/platform/auth/api-keys) — Server-side API key authentication
|
|
@@ -171,10 +171,10 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
|
|
|
171
171
|
|
|
172
172
|
**When enabled:**
|
|
173
173
|
- "Continue with Google" button on the login and signup pages
|
|
174
|
-
- Google row
|
|
174
|
+
- Google row on `/connected-accounts` (linked from **Manage Connected Accounts** on `/profile`)
|
|
175
175
|
|
|
176
176
|
**When disabled:**
|
|
177
|
-
- No social sign-in button, no Connected Accounts
|
|
177
|
+
- No social sign-in button, no **Manage Connected Accounts** link, no `/connected-accounts` page
|
|
178
178
|
|
|
179
179
|
**Requirements:**
|
|
180
180
|
- Google OAuth credentials configured on the Better Auth side
|
|
@@ -187,14 +187,14 @@ VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
|
|
|
187
187
|
|
|
188
188
|
**When enabled:**
|
|
189
189
|
- "Continue with Cloudflare" button on the login and signup pages
|
|
190
|
-
- Cloudflare rows
|
|
190
|
+
- Cloudflare rows on `/connected-accounts` — unlike
|
|
191
191
|
Google, more than one Cloudflare identity can be linked to the same user
|
|
192
192
|
(**Connect another Cloudflare account**), and every linked identity signs
|
|
193
193
|
in to this user. Link work and personal Cloudflare logins here so each one
|
|
194
194
|
doesn't mint its own separate account.
|
|
195
195
|
|
|
196
196
|
**When disabled:**
|
|
197
|
-
- No Cloudflare sign-in button, no Connected Accounts
|
|
197
|
+
- No Cloudflare sign-in button, no **Manage Connected Accounts** link, no `/connected-accounts` page
|
|
198
198
|
|
|
199
199
|
**Requirements:**
|
|
200
200
|
- `socialProviders.cloudflare.enabled` in the auth config (Cloudflare rides
|
|
@@ -256,10 +256,11 @@ VITE_ENABLE_ORGANIZATIONS=false # default: false
|
|
|
256
256
|
```
|
|
257
257
|
|
|
258
258
|
**When enabled:**
|
|
259
|
-
-
|
|
260
|
-
- Organization management pages
|
|
259
|
+
- `/dashboard` lists organizations and pending invitations
|
|
260
|
+
- Organization management pages (`/$slug`)
|
|
261
261
|
- Member invitations and roles
|
|
262
262
|
- `/organizations/*` routes
|
|
263
|
+
- Sign-in still lands on `/profile`; **Manage Organizations** opens `/dashboard`
|
|
263
264
|
|
|
264
265
|
**When disabled:**
|
|
265
266
|
- Single-user mode only
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Organizations
|
|
2
2
|
|
|
3
|
-
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
|
|
3
|
+
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. `/dashboard` is that surface: the organizations you belong to and pending invitations. **Manage Organizations** on `/profile` (and in the user menu) opens it. Personal account settings live on `/profile`. The profile **Go to…** picker opens the tenant app using `account.appUrl` and `account.tenantPattern` — see [Customization](/ui/account/customization#tenant-url-patterns). Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
|
|
4
4
|
|
|
5
5
|
## Organization CRUD
|
|
6
6
|
|
|
@@ -45,7 +45,6 @@ the business decision.
|
|
|
45
45
|
|
|
46
46
|
This surface is deliberately explicit and narrow. It requires all of:
|
|
47
47
|
|
|
48
|
-
- `contract.version: "v2"`
|
|
49
48
|
- Cloudflare Workers
|
|
50
49
|
- one Neon database using `connectionMode: "hyperdrive"`
|
|
51
50
|
- the Better Auth `emailOtp` plugin with effective `disableSignUp: true`
|
|
@@ -220,6 +219,8 @@ type HookCtx = {
|
|
|
220
219
|
|
|
221
220
|
`authDb` is the load-bearing piece: hooks must write to the auth DB via Drizzle directly. See the [CSRF caveat](#csrf-caveat-server-side-org-create) below. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
|
|
222
221
|
|
|
222
|
+
This injection is unique to account hooks. Actions reach AUTH_DB via `c.get("authDb")` ([Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb)). Trigger handlers on a table file get neither — use `ctx` for the acting user, and do not import `../../auth/schema` from the table file.
|
|
223
|
+
|
|
223
224
|
The atomic email-OTP hook additionally receives `db` (the transaction-bound
|
|
224
225
|
full application Drizzle client), `schema` (the full generated application
|
|
225
226
|
schema), and `atomicRoute: "emailOtpSignIn"`. In a single-database Neon project,
|
|
@@ -8,13 +8,15 @@ Account UI is a single React SPA that contains three distinct sections:
|
|
|
8
8
|
|
|
9
9
|
### Account (every user)
|
|
10
10
|
|
|
11
|
-
Login, signup, profile editing, password management, device sessions, email changes, and account deletion. This is what every user interacts with.
|
|
11
|
+
Login, signup, profile editing, password management, device sessions, email changes, and account deletion. This is what every user interacts with. After sign-in, Account UI lands on `/profile`.
|
|
12
|
+
|
|
13
|
+
When organizations are enabled, `/profile` has **Manage Organizations** (the `/dashboard` org list and invites) and a **Go to…** control that opens the tenant app. The URL is `account.appUrl` plus `account.tenantPattern` with the org slug substituted (the same `getTenantUrl` used on the org dashboard). One org is a single button; several orgs is a picker. The control is hidden when those config values cannot produce a URL.
|
|
12
14
|
|
|
13
15
|
Served on its own domain (e.g., `auth.example.com`) or at `/account/` when embedded alongside the CMS.
|
|
14
16
|
|
|
15
17
|
### Organization Management (multi-tenant)
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
`/dashboard` is org management — org list, pending invitations, and the path into org settings (`/$slug`). Personal account settings stay on `/profile`. Only available when `auth.organizations` is enabled.
|
|
18
20
|
|
|
19
21
|
### Admin Panel (admin users only)
|
|
20
22
|
|
|
@@ -86,7 +88,7 @@ Auth feature flags control which pages are included in the bundle:
|
|
|
86
88
|
| `auth.password` | Password login, inline password change on profile |
|
|
87
89
|
| `auth.emailOTP` | Email OTP login flow, email-based password reset |
|
|
88
90
|
| `auth.passkey` | Passkey setup and management |
|
|
89
|
-
| `auth.organizations` |
|
|
91
|
+
| `auth.organizations` | `/dashboard` (org list + invitations), org creation, member management |
|
|
90
92
|
| `auth.admin` | Admin panel (user management) |
|
|
91
93
|
|
|
92
94
|
When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and navigation entries for it are hidden. The Account SPA ships as one generic prebuilt bundle; flags decide which surfaces exist for your project.
|
|
@@ -95,9 +97,10 @@ When a flag is `false`, the corresponding routes **guard themselves at runtime**
|
|
|
95
97
|
|
|
96
98
|
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, magic links, email verification, password reset
|
|
97
99
|
- **Account Management** — Profile editing, avatar upload, password changes, device/session management, account deletion
|
|
100
|
+
- **Connected Accounts** — Link Google and Cloudflare logins from `/connected-accounts` (linked from profile)
|
|
98
101
|
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, and org settings
|
|
99
102
|
- **Admin Panel** — User management dashboard with search, create, ban/unban, password reset, and session viewing
|
|
100
|
-
- **API Keys** — Generate and manage API keys
|
|
103
|
+
- **API Keys** — Generate and manage API keys from `/api-keys` (linked from profile)
|
|
101
104
|
- **CLI Authorization** — Device authorization flow for `quickback login`
|
|
102
105
|
|
|
103
106
|
## Next Steps
|
|
@@ -68,7 +68,7 @@ auth: {
|
|
|
68
68
|
password: true, // Email/password login + inline password change
|
|
69
69
|
emailOTP: false, // Email OTP login flow
|
|
70
70
|
passkey: true, // WebAuthn passkey setup + management
|
|
71
|
-
organizations: true, //
|
|
71
|
+
organizations: true, // /dashboard org list, org management, invitations
|
|
72
72
|
admin: true, // Admin panel (user management)
|
|
73
73
|
}
|
|
74
74
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.66.1",
|
|
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",
|
package/src/skill/SKILL.md
CHANGED
|
@@ -273,9 +273,17 @@ throw new ActionError("Not enough balance", "INSUFFICIENT_FUNDS", 400, { availab
|
|
|
273
273
|
|
|
274
274
|
Constructor: `(message, code, statusCode = 400, details?)`. Do **NOT** throw Hono's `HTTPException` — it isn't unwrapped and surfaces as a 500 `ACTION_EXECUTION_FAILED`. Returning `c.json({...}, 400)` directly also works (the executor receives `c`).
|
|
275
275
|
|
|
276
|
-
## Reaching auth tables (org members, users)
|
|
276
|
+
## Reaching auth tables (org members, users)
|
|
277
277
|
|
|
278
|
-
The scoped `db`
|
|
278
|
+
The scoped feature `db` never includes Better Auth tables — that is by design.
|
|
279
|
+
`AUTH_DB` is a separate Drizzle client.
|
|
280
|
+
|
|
281
|
+
**Caller identity — use `ctx`, do not query AUTH_DB.** `ctx.userId`,
|
|
282
|
+
`ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request
|
|
283
|
+
(there is no `ctx.orgId`).
|
|
284
|
+
|
|
285
|
+
To check that a *submitted* userId is a member of the caller's org, use the
|
|
286
|
+
Hono context's auth DB plus the generated helper — from an **action**:
|
|
279
287
|
|
|
280
288
|
```ts
|
|
281
289
|
import { getOrgMemberRole } from "../../../lib/org-access";
|
|
@@ -284,7 +292,14 @@ const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activ
|
|
|
284
292
|
if (!role) throw new ActionError("Not a member of this organization", "NOT_A_MEMBER", 400);
|
|
285
293
|
```
|
|
286
294
|
|
|
287
|
-
|
|
295
|
+
That is the native membership check. For a richer query from an `actions/`
|
|
296
|
+
file, import tables from `../../../auth/schema`. On D1 the tables are `user`,
|
|
297
|
+
`organization`, and `member` — not `organization_membership`.
|
|
298
|
+
|
|
299
|
+
Account hooks get `{ authDb, authSchema }` injected. Trigger `handler:` args
|
|
300
|
+
are `{ ctx, db, env }` — `db` is features only; there is no `c` and no
|
|
301
|
+
`authDb`. Prefer `ctx` for the acting user. Do not import `../../auth/schema`
|
|
302
|
+
from a table file to reach AUTH_DB.
|
|
288
303
|
|
|
289
304
|
---
|
|
290
305
|
|
|
@@ -286,7 +286,7 @@ fail-fast per-record loop, `meta.transactional: false`.
|
|
|
286
286
|
| `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
|
|
287
287
|
| `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
|
|
288
288
|
| `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
|
|
289
|
-
| [Changeset](/define/changesets) (`application/vnd.quickback.changeset+json
|
|
289
|
+
| [Changeset](/define/changesets) (`application/vnd.quickback.changeset+json`) | tx-supporting (postgres, neon over websocket/hyperdrive) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
|
|
290
290
|
| [Changeset](/define/changesets) | cloudflare-d1, neon over http (Cloudflare default) | n/a | `false` | Deterministic parent-first fail-fast — the first op failure stops the changeset; already-applied ops stay committed (a consistent, independently-authorized prefix). |
|
|
291
291
|
|
|
292
292
|
### Reading `meta.transactional` in clients
|
|
@@ -117,7 +117,7 @@ GET /jobs/views/summary # Named view projection
|
|
|
117
117
|
`view` names the projection behind the response and is `null` for the default
|
|
118
118
|
collection read. `total` and `totalPages` join `pagination` only when the
|
|
119
119
|
request passed `?total=true`. A view that declares aggregations adds a
|
|
120
|
-
top-level `aggregations` object;
|
|
120
|
+
top-level `aggregations` object; `?include=` adds a top-level
|
|
121
121
|
`included` map. See
|
|
122
122
|
[Query Parameters](/api/query-params).
|
|
123
123
|
|
|
@@ -6,7 +6,7 @@ When you run `quickback compile`, Quickback generates a complete REST API from y
|
|
|
6
6
|
|
|
7
7
|
Generated endpoints use the contract selected in `quickback.config.ts`. The
|
|
8
8
|
backward-compatible default is `/api/v1/`; projects with
|
|
9
|
-
`contract: {
|
|
9
|
+
`contract: { routes: "v2" }` use `/api/v2/` (and `/auth/v2/` for Better Auth):
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
https://your-api.com/api/v1/{resource}
|
|
@@ -233,21 +233,18 @@ This request:
|
|
|
233
233
|
| `field.op=value` | LIST, VIEW | Filter with operator (gt, gte, lt, lte, ne, like, in) |
|
|
234
234
|
| `starting_after` | LIST, VIEW | Opaque keyset cursor — rows strictly after the boundary |
|
|
235
235
|
| `ending_before` | LIST, VIEW | Opaque keyset cursor — rows strictly before the boundary |
|
|
236
|
-
| `include` | LIST, VIEW, GET | FK-graph embedding (
|
|
237
|
-
| `fields[<fk>]` | LIST, VIEW, GET | Sparse fields for an embedded include target
|
|
236
|
+
| `include` | LIST, VIEW, GET | FK-graph embedding (allowlisted — see below) |
|
|
237
|
+
| `fields[<fk>]` | LIST, VIEW, GET | Sparse fields for an embedded include target |
|
|
238
238
|
|
|
239
|
-
## Include & Sparse Fields
|
|
239
|
+
## Include & Sparse Fields
|
|
240
240
|
|
|
241
|
-
|
|
242
|
-
|
|
241
|
+
A resource can allowlist FK columns for **FK-graph embedding**, collapsing
|
|
242
|
+
client-side N+1 fetches:
|
|
243
243
|
|
|
244
|
-
{/* doc-compile: skip — needs contract v2 at the project level; the gate's HARNESS_CONFIG pins v1 */}
|
|
245
244
|
```ts title="quickback/features/orders/order-items.ts"
|
|
246
245
|
import { feature, q } from "@quickback/compiler";
|
|
247
246
|
import { orders } from "../orders/orders";
|
|
248
247
|
|
|
249
|
-
// quickback.config.ts must pin the v2 contract for `read.include` to compile:
|
|
250
|
-
// export default defineConfig({ contract: { version: "v2" }, /* … */ });
|
|
251
248
|
export default feature("orderItems", {
|
|
252
249
|
columns: {
|
|
253
250
|
id: q.id(),
|
|
@@ -8,6 +8,92 @@ The current release series. Older entries are archived by version range:
|
|
|
8
8
|
- [v0.20 – v0.29](/changelog/v0.2x)
|
|
9
9
|
- [v0.18 and earlier](/changelog/v0.1x)
|
|
10
10
|
|
|
11
|
+
## Unreleased — the standard API shape
|
|
12
|
+
|
|
13
|
+
### BREAKING: `contract.version` is retired
|
|
14
|
+
|
|
15
|
+
There is one standard API shape, so there is nothing to select. Pinning
|
|
16
|
+
`contract.version` is now a **compile error** on either value.
|
|
17
|
+
|
|
18
|
+
**Delete that one line and keep `contract.routes` if you have it.** `routes`
|
|
19
|
+
is the surviving axis and is what decides whether your URLs read `/api/v1` or
|
|
20
|
+
`/api/v2` — removing it would move them.
|
|
21
|
+
|
|
22
|
+
{/* doc-compile: skip — config fragment, not a compilable project */}
|
|
23
|
+
```typescript
|
|
24
|
+
contract: { version: "v2", routes: "v1" } // before
|
|
25
|
+
contract: { routes: "v1" } // after — same URLs, same behavior
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Deleting `version: "v2"` changes **no** behavior: it selected what is now
|
|
29
|
+
simply the standard shape. Deleting `version: "v1"` is a real migration — see
|
|
30
|
+
[the contract page](/platform/api-contract#contractversion-is-retired) for the
|
|
31
|
+
four behaviors that pin opted out of, all now unconditional.
|
|
32
|
+
|
|
33
|
+
### BREAKING: CloudEvents `type` is reverse-DNS prefixed
|
|
34
|
+
|
|
35
|
+
Realtime `postgres_changes` and `view_changes` frames now carry a
|
|
36
|
+
`dev.quickback.` prefix on the CloudEvents `type`:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
myapp.registrations.insert → dev.quickback.myapp.registrations.insert
|
|
40
|
+
myapp.view.agendaBoard.changed → dev.quickback.myapp.view.agendaBoard.changed
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**`qbframe` is the supported discriminator — do not match on `type`.** Its
|
|
44
|
+
shape is not a stable contract; `qbframe` (`"broadcast"` / `"postgres_changes"`
|
|
45
|
+
/ `"view_changes"`) is. A client switching on `type` breaks here.
|
|
46
|
+
|
|
47
|
+
**Author-supplied broadcast event names are unchanged.** A named-invalidation
|
|
48
|
+
frame's `type` is still your `wireName` verbatim — that vocabulary is yours,
|
|
49
|
+
not ours to prefix.
|
|
50
|
+
|
|
51
|
+
`/asyncapi.json` documents the new `type` patterns, and its `info.version` is
|
|
52
|
+
now the event-document version rather than a contract version.
|
|
53
|
+
|
|
54
|
+
### BREAKING: outbound webhooks are Standard Webhooks only
|
|
55
|
+
|
|
56
|
+
The legacy `X-Webhook-Signature` / `X-Webhook-Event` / `X-Webhook-Delivery`
|
|
57
|
+
headers and the Stripe-format `signPayload` / `verifySignature` pair are gone
|
|
58
|
+
from the generated project — including from the public webhooks module's
|
|
59
|
+
exports. Receivers must verify with `webhook-signature`. This is the one
|
|
60
|
+
change a **receiver** absorbs without any config change of its own, so tell
|
|
61
|
+
your endpoint partners.
|
|
62
|
+
|
|
63
|
+
### BREAKING: `include` and `fields[...]` are reserved query params
|
|
64
|
+
|
|
65
|
+
`?include=` is always available now (where allowlisted), which makes `include`
|
|
66
|
+
a reserved parameter and any `fields[`-prefixed key reserved too. **A column
|
|
67
|
+
literally named `include` is no longer filterable** via `?include=…`. Unknown
|
|
68
|
+
`?fields=` and `fields[<fk>]=` names return **400** instead of being dropped.
|
|
69
|
+
|
|
70
|
+
### Fixed: scoped projects without `auth.jwt` could not admit their own scope tokens
|
|
71
|
+
|
|
72
|
+
Scope admission used to be emitted only inside the JWT credential lane, so a
|
|
73
|
+
project with `authz.scopes` and no `auth.jwt` minted scope tokens that no
|
|
74
|
+
generated code could accept — 401 on every presentation, with no diagnostic.
|
|
75
|
+
Live since v0.64.0, when that lane stopped being on by default.
|
|
76
|
+
|
|
77
|
+
Admission is now emitted whenever the project declares scopes, independent of
|
|
78
|
+
`auth.jwt`. **No config change is needed** — and declaring scopes does not
|
|
79
|
+
open the credential surface: no `POST /token` route, no identity fast-path,
|
|
80
|
+
no bearer fast-path unless you separately declare `auth.jwt`.
|
|
81
|
+
|
|
82
|
+
This covers **sessionless** scope tokens (`ctx.mintScope`). A token minted
|
|
83
|
+
from a session — `POST /scope/v1/enter`, or a namespace with
|
|
84
|
+
`mintScope: true` — carries user claims rather than the scope-only marker, so
|
|
85
|
+
without `auth.jwt` it still cannot be admitted: 200 from the mint, 401 on
|
|
86
|
+
presentation. The compiler now warns instead of failing silently. Declare
|
|
87
|
+
`auth: { jwt: {} }` if you use those routes.
|
|
88
|
+
|
|
89
|
+
### CMS and Account consume CloudEvents frames as-is
|
|
90
|
+
|
|
91
|
+
The bundled SPAs no longer invert realtime frames back into a private
|
|
92
|
+
`{ type, table, event }` shape, and they no longer sniff `/api/v2` to pick
|
|
93
|
+
the broadcast URL. They match on `qbframe`, read `data` / `qbseq`, and take
|
|
94
|
+
`/broadcast/v1` or `/broadcast/v2` from the injected runtime config — the
|
|
95
|
+
same prefixes the worker actually mounts.
|
|
96
|
+
|
|
11
97
|
## v0.65.x — August 16, 2026
|
|
12
98
|
|
|
13
99
|
### Passkeys no longer silently degrade to `rpID: 'localhost'`
|
|
@@ -161,7 +247,7 @@ total lost `required`, with sampled paths.
|
|
|
161
247
|
|
|
162
248
|
An unset `contract.version` resolves to `'v1'` today. That default becomes
|
|
163
249
|
`'v2'` in **v0.64.0**. See the
|
|
164
|
-
[contract matrix](/platform/api-contract#
|
|
250
|
+
[contract matrix](/platform/api-contract#contractversion-is-retired).
|
|
165
251
|
|
|
166
252
|
> v0.64.0 shipped this **without** moving any URLs — semantics and routes became
|
|
167
253
|
> independent axes, so `/api/v1` stays put. This entry originally said the flip
|
|
@@ -24,20 +24,28 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
|
|
|
24
24
|
|
|
25
25
|
Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
|
|
26
26
|
|
|
27
|
-
> **This JWT surface is opt-in
|
|
27
|
+
> **This JWT surface is opt-in**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
>
|
|
31
|
-
>
|
|
32
|
-
>
|
|
33
|
-
>
|
|
34
|
-
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
35
|
-
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
36
|
-
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
37
|
-
> available.
|
|
29
|
+
> Quickback emits this custom JWT surface only when `auth.jwt` is present. Omit
|
|
30
|
+
> it and the generated output has no generic `/api/v1/token` endpoint, no
|
|
31
|
+
> identity JWT mint, and no Bearer-JWT instructions in `llms.txt` or RFC 8414
|
|
32
|
+
> discovery metadata. Better Auth cookie and signed session-token bearer
|
|
33
|
+
> authentication remain available.
|
|
38
34
|
>
|
|
39
|
-
>
|
|
40
|
-
>
|
|
35
|
+
> **Scopes are the exception.** A project that declares
|
|
36
|
+
> [`authz.scopes`](/define/scopes) always emits `src/lib/jwt.ts` (scope tokens
|
|
37
|
+
> are signed JWTs) *and* a scope-only verification block that admits them —
|
|
38
|
+
> without the token endpoint or the identity fast-path. Declaring scopes does
|
|
39
|
+
> not open the credential surface.
|
|
40
|
+
>
|
|
41
|
+
> One gap to know about: that block admits **sessionless** scope tokens
|
|
42
|
+
> (`ctx.mintScope`). A token minted from a session — `POST /scope/v1/enter`, or
|
|
43
|
+
> a namespace with `mintScope: true` — carries user claims instead of the
|
|
44
|
+
> scope-only marker, and without `auth.jwt` nothing can admit it, so the caller
|
|
45
|
+
> gets 200 from the mint and 401 when presenting it. The compiler warns. Declare
|
|
46
|
+
> `auth: { jwt: {} }` if you rely on those routes.
|
|
47
|
+
>
|
|
48
|
+
> Use `auth: { jwt: {} }` to opt into the defaults documented below.
|
|
41
49
|
|
|
42
50
|
|
|
43
51
|
### Security posture at a glance
|
|
@@ -146,7 +146,7 @@ When the compiler builds the Account SPA, it excludes route files for disabled f
|
|
|
146
146
|
|
|
147
147
|
| Feature Flag | Routes Excluded When `false` |
|
|
148
148
|
|-------------|------------------------------|
|
|
149
|
-
| `auth.organizations` |
|
|
149
|
+
| `auth.organizations` | `/dashboard` (org list + invitations), organization CRUD, org switching (`$slug`) |
|
|
150
150
|
| `auth.passkey` | Passkey management and setup |
|
|
151
151
|
| `auth.admin` | Admin panel routes |
|
|
152
152
|
|