@quickback-dev/cli 0.70.43 → 0.72.2
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/build.d.ts.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +5 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +79 -2
- package/dist/skill/docs/configure/auth.md +10 -2
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +14 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +39 -0
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/jwt-optimization.md +16 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +7 -7
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +5 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +79 -2
- package/src/skill/docs/configure/auth.md +10 -2
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +14 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +39 -0
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/jwt-optimization.md +16 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -36,7 +36,7 @@ When `auth.admin` is `false` (the default), the admin surface does not exist for
|
|
|
36
36
|
- **Create an organization** — you name the **owner**; the operator creating it is deliberately not seated (see below)
|
|
37
37
|
- **Seat, re-role and remove members** — manage a tenant's roster without joining it
|
|
38
38
|
|
|
39
|
-
These run on `/auth/v1/admin
|
|
39
|
+
These run on `/api/v1/operator/organizations` (under `/auth/v1/admin/*` before 0.72; see [Moved routes](/api#moved-routes-072)), emitted by Quickback because Better Auth's organization plugin cannot serve them: every one of its endpoints resolves through the *caller's* membership, and an operator administers organizations it does not belong to. Put them behind [Cloudflare Access](/configure/cloudflare-access#the-operator-plane) with one path rule.
|
|
40
40
|
|
|
41
41
|
> **Users sign themselves up.** Self-serve signup stays on — a new account simply has no organization, and lands on a screen saying so until someone invites or seats them. What operators control is *organizations*, not accounts.
|
|
42
42
|
|
|
@@ -56,7 +56,7 @@ The admin panel is restricted to platform roles on the Better Auth user record:
|
|
|
56
56
|
>
|
|
57
57
|
> Equal tier is allowed, so an appmanager can still make another appmanager (the example below). Only a `sysadmin` can grant `sysadmin`.
|
|
58
58
|
>
|
|
59
|
-
>
|
|
59
|
+
> Seating a member (`PUT /api/v1/operator/organizations/:id/members/:userId`) refuses to seat its caller with `403 OPERATOR_SELF_SEAT`: operators are never seated by their own control-plane calls.
|
|
60
60
|
|
|
61
61
|
|
|
62
62
|
To grant operator access to a user:
|
|
@@ -89,7 +89,7 @@ providers: {
|
|
|
89
89
|
},
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/
|
|
92
|
+
With it on, an `appmanager` or `sysadmin` whose session was **not** established by a passkey assertion or a two-factor verification is treated as a plain `user` for that request. Every operator surface refuses with `403 MFA_REQUIRED`: the CMS and `/api/v1/schema`, the `/api/v1/operator/*` routes, Better Auth's own admin endpoints (`list-users`, `set-role`, `ban-user`), and the sysadmin cross-tenant bypass. The Account UI keeps working, so the enrolment path is short:
|
|
93
93
|
|
|
94
94
|
1. Sign in with a password (or magic link / OTP) as usual.
|
|
95
95
|
2. Register a passkey at `/account/passkeys/setup`.
|
|
@@ -97,6 +97,8 @@ With it on, an `appmanager` or `sysadmin` whose session was **not** established
|
|
|
97
97
|
|
|
98
98
|
How it works: the compiler adds a `session.amr` column (RFC 8176, *Authentication Methods Reference*) and a `session.create.before` hook that stamps `passkey` when the session comes from `/passkey/verify-authentication` and `mfa` when it comes from `/two-factor/verify-*`. Nothing else sets it, and it is not client-settable. The auth middleware reads it on the session lane and copies it into the JWT fast-path claims, so bearer callers are gated identically.
|
|
99
99
|
|
|
100
|
+
Cloudflare Access is recommended additionally for `/api/v1/operator`. It does not replace `operatorMfa`: Better Auth admin endpoints and the other operator powers still need the application second factor. Configuring Access with `operatorMfa` off emits a compile warning.
|
|
101
|
+
|
|
100
102
|
Things to know:
|
|
101
103
|
|
|
102
104
|
- **Requires `passkey` or `twoFactor`.** The compile fails otherwise: without a second factor to enrol, every operator would be locked out.
|
|
@@ -142,6 +142,10 @@ before calling `quickback/hooks/resolve-oauth-context.ts`. Use this trusted
|
|
|
142
142
|
server hook when tenant selection cannot be derived solely from the session's
|
|
143
143
|
active organization.
|
|
144
144
|
|
|
145
|
+
It never runs for an [instance-bound token](/define/scopes#instance-bound-oauth-tokens)
|
|
146
|
+
(audience = a scope kind's resource): that principal is confined to one
|
|
147
|
+
instance and gets no tenant context.
|
|
148
|
+
|
|
145
149
|
```ts title="quickback/hooks/resolve-oauth-context.ts"
|
|
146
150
|
import type { OAuthContextResolver } from '@quickback/compiler';
|
|
147
151
|
|
|
@@ -328,7 +332,7 @@ type HookCtx = {
|
|
|
328
332
|
};
|
|
329
333
|
```
|
|
330
334
|
|
|
331
|
-
`authDb` is the
|
|
335
|
+
`authDb` is the Drizzle connection to the auth DB. Read through it freely; for writes, prefer Better Auth's API (`auth.api.*`; `ctx.auth` in actions), which runs Better Auth's own hooks and revokes sessions. A direct insert, update, or delete on a Better Auth table is flagged [`ACTION_AUTH_DB_WRITE`](/define/diagnostics#action_auth_db_write) — in `hooks/` as a **warning**, never a compile error. Where no endpoint fits, such as the server-side org create below (see the [CSRF caveat](#csrf-caveat-server-side-org-create)), keep the write and mark it with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>`. `authSchema` is the namespace export of the generated auth schema module; destructure the tables you need.
|
|
332
336
|
|
|
333
337
|
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.
|
|
334
338
|
|
|
@@ -393,6 +397,7 @@ export default async (user, { authDb, authSchema }) => {
|
|
|
393
397
|
.where(eq(organization.id, orgId));
|
|
394
398
|
if (existing.length > 0) return;
|
|
395
399
|
|
|
400
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: server-side org create has no Origin for auth.api.createOrganization
|
|
396
401
|
await authDb.insert(organization).values({
|
|
397
402
|
id: orgId,
|
|
398
403
|
name: `${user.name ?? 'Personal'} Workspace`,
|
|
@@ -400,6 +405,7 @@ export default async (user, { authDb, authSchema }) => {
|
|
|
400
405
|
createdAt: new Date(),
|
|
401
406
|
});
|
|
402
407
|
|
|
408
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: membership for the org created above, same reason
|
|
403
409
|
await authDb.insert(member).values({
|
|
404
410
|
id: crypto.randomUUID(),
|
|
405
411
|
userId: user.id,
|
|
@@ -430,6 +436,7 @@ export default async (newSession, { authDb, authSchema }) => {
|
|
|
430
436
|
|
|
431
437
|
if (memberships.length === 0) return;
|
|
432
438
|
|
|
439
|
+
// quickback-allow ACTION_AUTH_DB_WRITE: setActiveOrganization needs a request; this hook has none
|
|
433
440
|
await authDb
|
|
434
441
|
.update(session)
|
|
435
442
|
.set({ activeOrganizationId: memberships[0].organizationId })
|
|
@@ -458,7 +465,7 @@ The compiler-generated wrapper merges your `data` onto the original entity, so y
|
|
|
458
465
|
|
|
459
466
|
`POST /auth/v1/organization/create` (and Better Auth's `auth.api.createOrganization(...)` server helper) require an `Origin` header. A hook running inside `databaseHooks.user.create.after` is server-side — there is no incoming request, so no `Origin`. Calling those APIs from a hook may also validate `Origin` internally and reject.
|
|
460
467
|
|
|
461
|
-
**
|
|
468
|
+
**Here, direct Drizzle writes via `authDb` are the working path.** Mark each with `// quickback-allow ACTION_AUTH_DB_WRITE: <reason>` so the warning records why. Treat the org/member tables as your source of truth and let the SPA call the BA API for user-initiated org creation.
|
|
462
469
|
|
|
463
470
|
## Generated output
|
|
464
471
|
|
|
@@ -217,7 +217,7 @@ The shell is served to any signed-in caller, and the SPA resolves one of six sta
|
|
|
217
217
|
| State | Screen |
|
|
218
218
|
|-------|--------|
|
|
219
219
|
| Not signed in | Redirect to sign-in (the one redirect that remains — it is where you were going anyway) |
|
|
220
|
-
| `sysadmin`, no tenant chosen | Tenant picker, filterable, with **All organizations** as a first-class choice |
|
|
220
|
+
| `sysadmin`, no tenant chosen | Tenant picker (from `GET /api/v1/operator/organizations`), filterable, with **All organizations** as a first-class choice |
|
|
221
221
|
| `sysadmin`, tenant chosen | The CMS, scoped to that tenant |
|
|
222
222
|
| `appmanager`, `access: "sysadmin"` | *"The CMS shows organization data"* → **Go to admin** |
|
|
223
223
|
| Anyone else, `access: "sysadmin"` | *"This CMS is restricted"* — names the config value that would admit them |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.72.2",
|
|
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",
|
|
@@ -46,22 +46,22 @@
|
|
|
46
46
|
"bundle:examples": "npx tsx scripts/bundle-examples.ts"
|
|
47
47
|
},
|
|
48
48
|
"dependencies": {
|
|
49
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
50
|
-
"zod": "^3.25.76",
|
|
49
|
+
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
51
50
|
"esbuild": "^0.27.2",
|
|
52
51
|
"ora": "^9.0.0",
|
|
53
52
|
"picocolors": "^1.0.0",
|
|
54
|
-
"prompts": "^2.4.2"
|
|
53
|
+
"prompts": "^2.4.2",
|
|
54
|
+
"zod": "^4.6.7"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@quickback-dev/schema-engine": "workspace:*",
|
|
58
58
|
"@types/node": "^22.7.5",
|
|
59
59
|
"@types/prompts": "^2.4.9",
|
|
60
60
|
"bun-types": "^1.3.5",
|
|
61
|
-
"tsx": "^4.19.0",
|
|
62
|
-
"typescript": "^5.9.0",
|
|
63
61
|
"drizzle-kit": "0.31.10",
|
|
64
|
-
"drizzle-orm": "0.45.2"
|
|
62
|
+
"drizzle-orm": "0.45.2",
|
|
63
|
+
"tsx": "^4.19.0",
|
|
64
|
+
"typescript": "^5.9.0"
|
|
65
65
|
},
|
|
66
66
|
"peerDependencies": {
|
|
67
67
|
"typescript": ">=5.0.0 <7"
|
|
@@ -327,6 +327,77 @@ When validation fails you get an RFC 9457 Problem Details document
|
|
|
327
327
|
Malformed JSON returns `INVALID_JSON` (400); a body over the 1 MiB cap returns
|
|
328
328
|
`PAYLOAD_TOO_LARGE` (413).
|
|
329
329
|
|
|
330
|
+
## Paginated actions
|
|
331
|
+
|
|
332
|
+
An action that declares [`pagination`](/define/actions/defining#paginated-actions-pagination)
|
|
333
|
+
reads the collection-read parameter names and answers the collection-read
|
|
334
|
+
envelope. Forward only; one base table.
|
|
335
|
+
|
|
336
|
+
### Request
|
|
337
|
+
|
|
338
|
+
| Parameter | Default | Description |
|
|
339
|
+
|-----------|---------|-------------|
|
|
340
|
+
| `limit` | the declared default (`50`) | Page size, clamped to `[1, max]` (`100` unless declared) |
|
|
341
|
+
| `starting_after` | — | `pagination.nextCursor` of the previous page. Omit for the first page |
|
|
342
|
+
| `sort` | the declared default | One of the action's named sorts |
|
|
343
|
+
|
|
344
|
+
A GET action reads them from the query string; any other method from the
|
|
345
|
+
JSON body (declare them with `pageInput()` so the body schema keeps them).
|
|
346
|
+
The action's own fields travel beside them and are part of the cursor's
|
|
347
|
+
context.
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
GET /api/v1/messages/list?conversationId=c_123&limit=50
|
|
351
|
+
GET /api/v1/messages/list?conversationId=c_123&limit=50&starting_after=eyJ2IjoyLCJjIjoi…
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### Response
|
|
355
|
+
|
|
356
|
+
```json
|
|
357
|
+
{
|
|
358
|
+
"data": [ /* rows, masked for the caller */ ],
|
|
359
|
+
"pagination": {
|
|
360
|
+
"count": 50,
|
|
361
|
+
"pageSize": 50,
|
|
362
|
+
"hasMore": true,
|
|
363
|
+
"nextCursor": "eyJ2IjoyLCJjIjoi…",
|
|
364
|
+
"sort": "recent"
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
- `count` — rows on this page; `pageSize` — the resolved limit
|
|
370
|
+
- `hasMore` — from a `limit + 1` probe, so a final page that exactly fills
|
|
371
|
+
the limit reports `false`
|
|
372
|
+
- `nextCursor` — pass back as `starting_after`; `null` on the final page
|
|
373
|
+
- `sort` — the named sort the page was produced under
|
|
374
|
+
|
|
375
|
+
An action may return domain fields beside `data` and `pagination`; a
|
|
376
|
+
non-paginated action's response is unchanged.
|
|
377
|
+
|
|
378
|
+
### Cursors
|
|
379
|
+
|
|
380
|
+
A cursor is opaque and versioned. It carries the boundary row's sort-key
|
|
381
|
+
values and a hash of the action, table, sort and input it was minted for —
|
|
382
|
+
it is encoded, not encrypted, and it never authorizes: every page re-runs
|
|
383
|
+
access, the table firewall, soft-delete filtering and masking, so a cursor
|
|
384
|
+
from another caller or tenant yields that caller's own rows, nothing more.
|
|
385
|
+
A sort over a masked column is only offered to callers who may see it.
|
|
386
|
+
|
|
387
|
+
Validation failures are RFC 9457 problems, never a silent restart at page one:
|
|
388
|
+
|
|
389
|
+
| Status | `code` | When |
|
|
390
|
+
|--------|--------|------|
|
|
391
|
+
| `400` | `PAGINATION_INVALID_CURSOR` | Malformed, truncated, over 2048 characters, wrong version, wrong number of values, or a value of the wrong type |
|
|
392
|
+
| `400` | `PAGINATION_CURSOR_MISMATCH` | A cursor minted for another action, table, sort or input |
|
|
393
|
+
| `400` | `PAGINATION_INVALID_SORT` | `sort` is not one of the action's named sorts |
|
|
394
|
+
| `403` | `PAGINATION_SORT_NOT_VISIBLE` | A sort key is masked for this caller |
|
|
395
|
+
|
|
396
|
+
Pages are not a snapshot. A row inserted, updated or deleted between two
|
|
397
|
+
requests can shift the boundary: under a mutable sort a row may appear twice
|
|
398
|
+
or be missed. Reconnect checkpoints and change history are a
|
|
399
|
+
[realtime](/platform/realtime) concern, not a pagination one.
|
|
400
|
+
|
|
330
401
|
## Response Types
|
|
331
402
|
|
|
332
403
|
Actions support three response types:
|
|
@@ -466,9 +537,9 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
|
|
|
466
537
|
|
|
467
538
|
| Status | Description |
|
|
468
539
|
|--------|-------------|
|
|
469
|
-
| `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes) |
|
|
540
|
+
| `400` | Invalid input / validation error (also `GUARD_FIELD_PROTECTED` for direct protected-field writes; `PAGINATION_INVALID_CURSOR`, `PAGINATION_CURSOR_MISMATCH`, `PAGINATION_INVALID_SORT` on [paginated actions](#paginated-actions)) |
|
|
470
541
|
| `401` | Not authenticated |
|
|
471
|
-
| `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`) |
|
|
542
|
+
| `403` | Access role check failed (`ACCESS_ROLE_REQUIRED`); a masked sort key on a paginated action (`PAGINATION_SORT_NOT_VISIBLE`) |
|
|
472
543
|
| `404` | Record not found (record-based actions) |
|
|
473
544
|
| `409` | Record is in the wrong state for this action — `access.record` predicate or `transition` policy failed (`ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`) |
|
|
474
545
|
| `500` | Handler execution error |
|
|
@@ -314,9 +314,11 @@ transport with Neon's hyperdrive mode.
|
|
|
314
314
|
| Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
|
|
315
315
|
|----------|----------|-----------|----------------------|----------|
|
|
316
316
|
| `PATCH /batch` (update) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
|
|
317
|
+
| `PATCH /batch` (update) | [tenant table](/configure/tenant-databases) (`tenancy.isolation: 'durable-object'`) | `true` | `true` | `ctx.storage.transaction()` in the organization's Durable Object wraps the loop. Any failure rolls back ALL writes in the batch. |
|
|
317
318
|
| `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
|
|
318
319
|
| `PATCH /batch` (update) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Fail-fast loop without rollback — the driver has no `db.transaction`. Records before the failure stay committed. |
|
|
319
320
|
| `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
|
|
321
|
+
| `PUT /batch` (upsert) | [tenant table](/configure/tenant-databases) | `true` | `true` | Bulk insert + per-record update share one Durable Object transaction. |
|
|
320
322
|
| `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
|
|
321
323
|
| `POST /batch` (create) | (any) | (any) | `true` | One bulk `INSERT` — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
|
|
322
324
|
| `DELETE /batch` | (any) | (any) | `true` | One bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
|
|
@@ -46,10 +46,13 @@ When ETags are enabled, GET responses include:
|
|
|
46
46
|
```
|
|
47
47
|
Content-Type: application/json
|
|
48
48
|
ETag: W/"a1b2c3d4e5f60718"
|
|
49
|
-
Cache-Control: no-cache
|
|
49
|
+
Cache-Control: private, no-cache
|
|
50
|
+
Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion
|
|
50
51
|
```
|
|
51
52
|
|
|
52
|
-
`Cache-Control: no-cache` means the browser
|
|
53
|
+
`Cache-Control: private, no-cache` means the browser **must revalidate** on every request, but can use its cached copy if the ETag matches, and no shared cache may store the response. This is the correct behavior for authenticated APIs — data is always fresh, but unchanged responses avoid re-transfer.
|
|
54
|
+
|
|
55
|
+
Every other JSON response produced under a cookie, bearer token, or [Cloudflare Access](/configure/cloudflare-access) assertion (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion`, so a proxy can never serve one user's body to another.
|
|
53
56
|
|
|
54
57
|
## Client usage
|
|
55
58
|
|
|
@@ -55,6 +55,13 @@ For a resource named `jobs`, Quickback generates:
|
|
|
55
55
|
| `PUT` | `/jobs/:id` | Upsert a record (requires config) |
|
|
56
56
|
| `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
|
|
57
57
|
|
|
58
|
+
A table a namespace claims mounts these under the namespace prefix
|
|
59
|
+
(`/event/:eventId/jobs`), and every row they read or write is confined to the instance in the URL
|
|
60
|
+
(see [Claimed tables are pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance)). With [`legacy`](/define/areas#keeping-the-old-url-legacy) it also keeps
|
|
61
|
+
each one at its pre-claim base (`/jobs`, `/jobs/:id`, …) as a deprecated forward: same method, same
|
|
62
|
+
body, one instance per request, org members only, with `Deprecation`, `Sunset` and `Link` response
|
|
63
|
+
headers.
|
|
64
|
+
|
|
58
65
|
## Replace a generated verb with an action
|
|
59
66
|
|
|
60
67
|
Map `create`, `update`, or `delete` to a named action when the public URL
|
|
@@ -225,6 +232,11 @@ columns may be omitted or sent as `null`. An empty string is **not** a blank —
|
|
|
225
232
|
`""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
|
|
226
233
|
`q.int()`).
|
|
227
234
|
|
|
235
|
+
On a table a namespace claims, the instance column (`eventId` under
|
|
236
|
+
`/event/:eventId/jobs`) is stamped from the URL. Omit it; a body value must
|
|
237
|
+
equal the URL instance or the create answers `400 INSTANCE_MISMATCH`. The same
|
|
238
|
+
rule applies to each `POST /batch` record and to the insert branch of `PUT`.
|
|
239
|
+
|
|
228
240
|
### Client-supplied IDs (optimistic updates)
|
|
229
241
|
|
|
230
242
|
Set `allowClientIds: true` on the database config to let `POST /` and
|
|
@@ -373,6 +385,7 @@ wrapper:
|
|
|
373
385
|
| Status | Description |
|
|
374
386
|
|--------|-------------|
|
|
375
387
|
| `400` | Invalid field or missing required field |
|
|
388
|
+
| `400` | `INSTANCE_MISMATCH` — on a claimed table, the body's instance column names another instance than the URL |
|
|
376
389
|
| `403` | User lacks permission to create records |
|
|
377
390
|
| `409` | Client-supplied `id` (with `allowClientIds: true`) already exists |
|
|
378
391
|
| `409` | `IDEMPOTENCY_ROW_CONFLICT` — a [row token](#row-token-idempotency) or client id already belongs to a different record |
|
|
@@ -198,6 +198,7 @@ Access violations return **403 Forbidden** when the user's role doesn't match th
|
|
|
198
198
|
| `ACCESS_OWNERSHIP_REQUIRED` | User must own the record |
|
|
199
199
|
| `ACCESS_NO_ORG` | No active organization set |
|
|
200
200
|
| `ACCESS_KEY_SCOPE_REQUIRED` | A [scoped API key](/platform/auth/api-keys#scopes) does not cover this route and method. `details.required` lists the scope that would admit it (empty outside the API base, which scoped keys never reach); `details.current` is the key's scopes |
|
|
201
|
+
| `ACCESS_DENIED` | A token bound to one instance was used for another (namespace, tenant and realtime ticket routes), or the caller's credential does not admit an operator surface |
|
|
201
202
|
| `ENTITLEMENT_REQUIRED` | An action's [`requires:`](/define/actions/defining#json-key-writes-and-requires) JSON key did not hold for the record. `details: { column, key }`. Checked before `execute` |
|
|
202
203
|
| `ACCESS_NO_ARM` | The action declares [`access.arms`](/define/actions/access#arms-conditioned-on-input-accessarms) and no arm's `when` matches the validated input |
|
|
203
204
|
|
|
@@ -361,9 +362,11 @@ reports these `DB_*` codes per id, or as the `failFast` response), bulk
|
|
|
361
362
|
actions, and changesets.
|
|
362
363
|
|
|
363
364
|
`DB_INSERT_FAILED`, `DB_UPDATE_FAILED` and `DB_DELETE_FAILED` are the fallback
|
|
364
|
-
for a failure that matches no known constraint. The
|
|
365
|
+
for a failure that matches no known constraint. The driver message (D1 or
|
|
365
366
|
Postgres text, which can name tables, columns, and SQL fragments) is always
|
|
366
|
-
logged with `console.error
|
|
367
|
+
logged with `console.error` — with bound values redacted (see
|
|
368
|
+
[Bound values never leave the database](#bound-values-never-leave-the-database))
|
|
369
|
+
— and the production body carries no `details`:
|
|
367
370
|
|
|
368
371
|
```json
|
|
369
372
|
{
|
|
@@ -374,14 +377,110 @@ logged with `console.error`, and the production body carries no `details`:
|
|
|
374
377
|
}
|
|
375
378
|
```
|
|
376
379
|
|
|
377
|
-
The
|
|
380
|
+
The (redacted) message appears as `details.reason` only when the worker runs with
|
|
378
381
|
[`EXPOSE_ERROR_STACK`](#exposing-error-details-in-dev--staging) set.
|
|
379
382
|
|
|
383
|
+
### Bound values never leave the database
|
|
384
|
+
|
|
385
|
+
A database error can carry the row it was writing: drizzle reports every driver
|
|
386
|
+
failure as `Failed query: <sql>` followed by `params: <values>`, and Postgres
|
|
387
|
+
inlines values into its own text (`Key (email)=(…) already exists`,
|
|
388
|
+
`Failing row contains (…)`). Every place the generated API records an error —
|
|
389
|
+
`console.error` in CRUD, batch, changeset and action catches, the global
|
|
390
|
+
`onError`, queue consumers, webhook event and delivery rows, `afterCommit`
|
|
391
|
+
failures, the `error_message` column of `audit_events`, and the
|
|
392
|
+
`EXPOSE_ERROR_STACK` bodies, and Better Auth's own logger (the generated
|
|
393
|
+
`betterAuth({ logger })`, which covers endpoint failures and the database
|
|
394
|
+
adapter) — passes it through `redactError` in the generated `src/lib/errors.ts`
|
|
395
|
+
first. Only the values are removed:
|
|
396
|
+
|
|
397
|
+
| Driver text | Logged / stored as |
|
|
398
|
+
|---|---|
|
|
399
|
+
| `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: acc_1,usr_1,$argon2id$…` | `Failed query: insert into "account" ("id", "user_id", "password") values (?, ?, ?)`<br/>`params: [string(5), string(5), string(97)]` |
|
|
400
|
+
| `UNIQUE constraint failed: account.user_id` (D1, libsql) | unchanged |
|
|
401
|
+
| `duplicate key value violates unique constraint "users_email_key"`, `detail: Key (email)=(x@y.com) already exists.` (Postgres) | message unchanged; `detail: Key (email)=(<redacted>) already exists.` |
|
|
402
|
+
| `Failing row contains (r1, x@y.com, …)` | `Failing row contains (<redacted>)` |
|
|
403
|
+
| `invalid input syntax for type uuid: "…"` | `invalid input syntax for type uuid: "<redacted>"` |
|
|
404
|
+
| `Key (lower(email::text))=(…)` (expression index), `conflicts with existing key (…)=(…)` (exclusion constraint) | `=(<redacted>)` |
|
|
405
|
+
| `value "…" is out of range for type integer`, `date/time field value out of range: "…"`, `malformed array literal: "…"`, `Token "…" is invalid.` | the quoted literal becomes `"<redacted>"`; quoted constraint, relation, column and table names stay |
|
|
406
|
+
|
|
407
|
+
The SQL with its placeholders, table, column and constraint names, the driver
|
|
408
|
+
code (`SQLITE_CONSTRAINT_UNIQUE`, `23505`), the parameter count and each
|
|
409
|
+
parameter's type and length stay, so the log line still tells you which
|
|
410
|
+
statement failed and why; the `requestId` correlates it with the response,
|
|
411
|
+
and the global error log line also carries the driver `code` and `causeCode`.
|
|
412
|
+
Driver text past 16 KB is cut and marked `[truncated]`, so a hostile value can't
|
|
413
|
+
make redaction slow.
|
|
414
|
+
Classification is unaffected — the `DB_*` codes above are computed from the
|
|
415
|
+
original error. Your own code can call `redactError(error)` from
|
|
416
|
+
`src/lib/errors` before logging a caught error.
|
|
417
|
+
|
|
380
418
|
`ENCRYPTION_UNREADABLE` always carries `details: { table, column, id }` — the
|
|
381
419
|
row whose stored ciphertext is malformed, was not written under the caller's
|
|
382
420
|
organization key, was copied from another column or table, or names a key
|
|
383
421
|
version the organization does not have. Rewriting the field repairs the row.
|
|
384
422
|
|
|
423
|
+
### Legacy forwards
|
|
424
|
+
|
|
425
|
+
A [legacy forward](/define/areas#keeping-the-old-url-legacy) answers these itself, before it
|
|
426
|
+
dispatches; every other response is the successor route's. Each carries the `Deprecation`,
|
|
427
|
+
`Sunset` and `Link` headers.
|
|
428
|
+
|
|
429
|
+
| Code | Status | Meaning |
|
|
430
|
+
|------|--------|---------|
|
|
431
|
+
| `LEGACY_ORG_REQUIRED` | 403 | The caller has no active organization, is an instance-bound OAuth token or a scope-only principal, or (database per tenant) its active organization is not the tenant. Call the successor URL in `Link`. |
|
|
432
|
+
| `LEGACY_INSTANCE_REQUIRED` | 400 | The request names no instance: no `?C=` (or a repeated / `?C.<op>=` one) on a collection, no `C` in the body, or an id that is not a valid instance id. |
|
|
433
|
+
| `LEGACY_INSTANCE_MISMATCH` | 400 | The request names more than one instance (a batch spanning instances, or a body `C` that disagrees with `?C=`). |
|
|
434
|
+
|
|
435
|
+
An instance outside the caller's organization answers the namespace gate's
|
|
436
|
+
`403 ACCESS_ROLE_REQUIRED`; a row outside it answers the table's firewall miss
|
|
437
|
+
(`403 FIREWALL_NOT_FOUND`, or `404` with `firewallErrorMode: 'hide'`).
|
|
438
|
+
|
|
439
|
+
### Claimed tables
|
|
440
|
+
|
|
441
|
+
A table a namespace claims is [pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance).
|
|
442
|
+
|
|
443
|
+
| Code | Status | Meaning |
|
|
444
|
+
|------|--------|---------|
|
|
445
|
+
| `INSTANCE_MISMATCH` | 400 | A create body (or a batch record) sends the instance column with a value other than the instance in the URL. `layer: "validation"`, `details: { field, param }` (plus `index` for a batch record). Omit the column: it is taken from the URL. |
|
|
446
|
+
|
|
447
|
+
### Tenancy (database per tenant)
|
|
448
|
+
|
|
449
|
+
With `tenancy.isolation: 'durable-object'`, responses about an organization's own database carry `layer: "tenancy"` and one of these codes. See [Database per Tenant](/configure/tenant-databases).
|
|
450
|
+
|
|
451
|
+
| Code | Meaning |
|
|
452
|
+
|------|---------|
|
|
453
|
+
| `TENANT_REQUIRED` | The route reads an organization's own database but the request names no organization (or names an invalid id) |
|
|
454
|
+
| `TENANT_MISMATCH` | The principal does not belong to the tenant object it reached |
|
|
455
|
+
| `TENANT_SCOPE_MISMATCH` | A scope claim names a different tenant than the request |
|
|
456
|
+
| `TENANT_AMBIGUOUS` | The instance resolves to more than one organization; set an active organization |
|
|
457
|
+
| `TENANT_UNAVAILABLE` | The organization database or directory is unavailable; retry (`Retry-After`) |
|
|
458
|
+
| `TENANT_OVERLOADED` | The organization database is overloaded; retry after `Retry-After` |
|
|
459
|
+
| `TENANT_DEPTH_EXCEEDED` | Subrequest depth limit exceeded calling the organization database (508) |
|
|
460
|
+
| `TENANT_ADMISSION_UNAVAILABLE` | Scope admission could not be checked right now; retry |
|
|
461
|
+
| `TENANT_LOOKUP_UNAVAILABLE` | The tenant lookup index could not be read; retry |
|
|
462
|
+
| `TENANT_LOOKUP_PENDING` | The instance is not indexed to a tenant yet; retry |
|
|
463
|
+
| `TENANT_NOT_PROVISIONED` | The organization has no tenant database registered (operator routes other than archive refuse it) |
|
|
464
|
+
| `TENANT_ARCHIVED` | The organization is archived (423); an operator can unarchive it |
|
|
465
|
+
| `TENANT_PURGED` | The organization's data was purged (410) |
|
|
466
|
+
| `TENANT_MIGRATION_FAILED` | The organization database failed to migrate (503); `details` names the migration |
|
|
467
|
+
| `TENANT_JURISDICTION_MISMATCH` | The registry row was written under another jurisdiction |
|
|
468
|
+
| `TENANT_RPC_VERSION_MISMATCH` | The edge and tenant Workers disagree on the RPC contract; deploy the tenant Worker first |
|
|
469
|
+
| `TENANT_AUTHORIZATION_EPOCH_CHANGED` | A restore advanced the tenant's authorization epoch; credentials issued before it are refused |
|
|
470
|
+
| `TENANT_RESTORE_PENDING` | A restore is pending or unreconciled; sync or cancel it first |
|
|
471
|
+
| `TENANT_RESTORE_TOO_LARGE` | Operator restore: the dump exceeds the restore limit (413) |
|
|
472
|
+
| `TENANT_OPERATION_FAILED` | Operator route refused or failed (409); `detail` says why |
|
|
473
|
+
| `TENANT_COMMAND_INVALID` | A tenant command request failed its schema |
|
|
474
|
+
| `TENANT_COMMAND_FINGERPRINT_MISMATCH` | A tenant command was compiled against a different contract |
|
|
475
|
+
| `TENANT_COMMAND_REPLY_INVALID` | The tenant object answered a command with a malformed reply |
|
|
476
|
+
| `TENANT_JOB_INVALID` | A tenant job message is invalid |
|
|
477
|
+
| `TENANT_JOB_CALL_ONLY` | A result job was delivered instead of called (callTenantJob) |
|
|
478
|
+
| `TENANT_JOB_FAILED` | A called tenant job failed |
|
|
479
|
+
| `TENANT_JOB_REPLY_INVALID` | The tenant object answered a job call with a malformed reply |
|
|
480
|
+
| `TENANT_JOB_RESULT_INVALID` | A tenant job result is not serializable |
|
|
481
|
+
| `TENANT_JOB_RESULT_TOO_LARGE` | A tenant job result exceeds the size limit |
|
|
482
|
+
| `TENANT_TABLE_ON_EDGE` | Edge code queried a tenant table (500, a compile-placement bug) |
|
|
483
|
+
|
|
385
484
|
## Batch Errors
|
|
386
485
|
|
|
387
486
|
Batch operations can return:
|
|
@@ -465,7 +564,7 @@ fetch timeout, a third-party API error), the route returns
|
|
|
465
564
|
`ACTION_EXECUTION_FAILED`. The production body is generic: it carries
|
|
466
565
|
only the error class name in `details.name` (so callers can branch on
|
|
467
566
|
e.g. `TypeError` vs a fetch timeout) — never the underlying message,
|
|
468
|
-
cause, or stack frames. The
|
|
567
|
+
cause, or stack frames. The error is logged server-side with bound database values redacted.
|
|
469
568
|
|
|
470
569
|
```json
|
|
471
570
|
{
|
|
@@ -489,8 +588,8 @@ cause, or stack frames. The raw error is always logged server-side.
|
|
|
489
588
|
|
|
490
589
|
Uncaught throws that escape every route handler land in the global
|
|
491
590
|
`onError` and return `INTERNAL_ERROR`. Same contract: the production
|
|
492
|
-
body is generic, and the
|
|
493
|
-
logged via `console.error` keyed by the `requestId` in the body — so
|
|
591
|
+
body is generic, and the error (message, cause chain, stack), with bound
|
|
592
|
+
database values redacted, is logged via `console.error` keyed by the `requestId` in the body — so
|
|
494
593
|
the response → log correlation is one grep.
|
|
495
594
|
|
|
496
595
|
```json
|
|
@@ -525,11 +624,13 @@ When set, the global 500 and `ACTION_EXECUTION_FAILED` bodies forward
|
|
|
525
624
|
the underlying error message plus `details.cause` (cause-chain
|
|
526
625
|
message), `details.frames` (top three stack frames with absolute paths
|
|
527
626
|
sanitized to basename + line number), and `details.stack` (the full
|
|
528
|
-
unsanitized stack trace). The same switch adds `details.reason` (the
|
|
627
|
+
unsanitized stack trace). The same switch adds `details.reason` (the
|
|
529
628
|
error message) to the database fallbacks (`DB_INSERT_FAILED`,
|
|
530
629
|
`DB_UPDATE_FAILED`, `DB_DELETE_FAILED`), `ACCESS_AUDIT_LOG_FAILED`, the
|
|
531
|
-
`INTERNAL_ERROR` bodies of the auth handler
|
|
532
|
-
routes, and uses the
|
|
630
|
+
`INTERNAL_ERROR` bodies of the auth handler, operator `/admin/*` routes,
|
|
631
|
+
and storage upload, presign, and confirm routes, and uses the redacted message as the `TRIGGER_AFTER_FAILED` error text.
|
|
533
632
|
Without it, none of those bodies carry anything derived from the thrown
|
|
534
|
-
error.
|
|
633
|
+
error. With it, they still never carry a bound value — the message, cause and
|
|
634
|
+
stack go through the same [redaction](#bound-values-never-leave-the-database)
|
|
635
|
+
as the server log. `1` and `true` turn it on; any other value leaves it off. Leave it
|
|
535
636
|
unset in production.
|
|
@@ -33,6 +33,30 @@ For each resource with `export default defineTable(...)`:
|
|
|
33
33
|
| `PATCH` | `/api/v1/{resource}/batch` | Batch update |
|
|
34
34
|
| `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
|
|
35
35
|
|
|
36
|
+
## Moved routes (0.72)
|
|
37
|
+
|
|
38
|
+
Better Auth owns `/auth/v1/*`. Quickback's own routes there moved under the API base in 0.72 (plan 031 Q7), so a Better Auth upgrade or plugin cannot collide with them and a Cloudflare Access path rule can cover the operator plane in one prefix. The prefix follows `contract.routes` (`/api/v2/…` on v2).
|
|
39
|
+
|
|
40
|
+
| Before 0.72 | Since 0.72 | Emitted when |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `GET /auth/v1/admin/list-organizations` | `GET /api/v1/operator/organizations` | `cms.sysadmin` or `account.auth.admin` |
|
|
43
|
+
| `GET /auth/v1/admin/get-organization?organizationId=:id` | `GET /api/v1/operator/organizations/:id` | same |
|
|
44
|
+
| `POST /auth/v1/admin/create-organization` | `POST /api/v1/operator/organizations` | same |
|
|
45
|
+
| `POST /auth/v1/admin/set-organization-member` `{ organizationId, userId, role }` | `PUT /api/v1/operator/organizations/:id/members/:userId` `{ role }` | same |
|
|
46
|
+
| `POST /auth/v1/admin/remove-organization-member` `{ organizationId, userId }` | `DELETE /api/v1/operator/organizations/:id/members/:userId` | same |
|
|
47
|
+
| `GET /auth/v1/organization/roster` | `GET /api/v1/organization/roster` | `auth.organizationRoster` |
|
|
48
|
+
| `GET /auth/v1/ses/status` | `GET /api/v1/auth/email-status` | always |
|
|
49
|
+
|
|
50
|
+
Response bodies are unchanged. The old paths keep working through 0.72.x and are removed in 0.73.0:
|
|
51
|
+
|
|
52
|
+
- The old `GET`s answer `308 Permanent Redirect` to the new path (the query string is kept; `get-organization?organizationId=X` redirects to `/operator/organizations/X`).
|
|
53
|
+
- The old `POST`s cannot redirect, because two of them changed verb. They run the same handler as the new route.
|
|
54
|
+
- Both add `Deprecation: true` and `Link: <new path>; rel="successor-version"`, and the Worker logs `[quickback] deprecated route <method> <path>` once per isolate per path. Grep your logs for it before upgrading to 0.73.
|
|
55
|
+
|
|
56
|
+
The bundled CMS and Account SPAs call the new paths. The OpenAPI document lists `GET /api/v1/auth/email-status` (operationId `getEmailStatus`, marked `x-quickback-auth-surface`, so like every auth endpoint it stays out of the MCP catalogue unless `agents.mcp.exposeAuthTools` is on, where the tool `auth__sesStatus` is now `auth__getEmailStatus`); the aliases are not advertised. A feature or table that would mount over one of these routes (`/api/v1/operator`, `/api/v1/auth`, `/api/v1/organization` with the roster on) is a compile error.
|
|
57
|
+
|
|
58
|
+
`ses/status` note: after 0.73.0, an `aws-ses` project's vendored Better Auth plugin answers `/auth/v1/ses/status` itself, with a different body (`provider: 'aws-ses'`, plus `region` and `fromEmail`). Use `email-status`.
|
|
59
|
+
|
|
36
60
|
## Guides
|
|
37
61
|
|
|
38
62
|
- [CRUD Endpoints](/api/crud) — Detailed CRUD endpoint reference
|
|
@@ -24,6 +24,14 @@ The generated spec documents every route the compiler produces:
|
|
|
24
24
|
- Actions (including standalone actions)
|
|
25
25
|
- Auth routes (`/api/auth/**`)
|
|
26
26
|
- Storage and webhook routes (when configured)
|
|
27
|
+
- [Legacy forwards](/define/areas#keeping-the-old-url-legacy) of namespace-claimed tables and actions, as `deprecated: true` operations
|
|
28
|
+
|
|
29
|
+
A legacy operation is its successor's operation at the old path: operationId `<successor>Legacy`,
|
|
30
|
+
the successor's path params dropped, a required `?C=` query param on collections, the
|
|
31
|
+
`Deprecation` / `Sunset` / `Link` response headers, and
|
|
32
|
+
`x-quickback-legacy-forward: { successor, successorPath, deprecated, sunset, instance }`. The
|
|
33
|
+
`LEGACY_*` codes join the `Error.code` enum. Generated clients see `@deprecated`. The MCP tool list
|
|
34
|
+
and the generated client SDK skip legacy operations: new code targets the successor.
|
|
27
35
|
|
|
28
36
|
Each endpoint includes request/response schemas derived from your Drizzle column types, access control metadata, and error responses.
|
|
29
37
|
|
|
@@ -102,6 +102,12 @@ currently wired into the emitted route.
|
|
|
102
102
|
|
|
103
103
|
There is no `limit` or `offset` member in `pagination`.
|
|
104
104
|
|
|
105
|
+
Custom actions that declare [`pagination`](/define/actions/defining#paginated-actions-pagination)
|
|
106
|
+
answer the same envelope (`data` + `pagination` with `count`, `pageSize`,
|
|
107
|
+
`hasMore`, `nextCursor`, `sort`) and read the same `limit` / `starting_after`
|
|
108
|
+
names, forward-only and with strictly validated cursors — see
|
|
109
|
+
[Paginated actions](/api/actions#paginated-actions).
|
|
110
|
+
|
|
105
111
|
## Sorting
|
|
106
112
|
|
|
107
113
|
Sort by one or more fields. Use the `-` prefix for descending order.
|