@quickback-dev/cli 0.66.14 → 0.66.16
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/schema.d.ts +1 -1
- package/dist/commands/schema.d.ts.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 +28 -7
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/file-loader.js +1 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +79 -4
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/staging.js.map +1 -1
- package/dist/lib/schema-sync/index.d.ts +1 -1
- package/dist/lib/schema-sync/index.d.ts.map +1 -1
- package/dist/lib/schema-sync/index.js +10 -4
- package/dist/lib/schema-sync/index.js.map +1 -1
- package/dist/schema-engine/index.js.map +1 -1
- package/dist/schema-engine/source-sync.d.ts +1 -1
- package/dist/schema-engine/source-sync.d.ts.map +1 -1
- package/dist/skill/docs/api/batch-operations.md +1 -1
- package/dist/skill/docs/api/typescript.md +102 -4
- package/dist/skill/docs/define/actions/defining.md +23 -11
- package/dist/skill/docs/define/feature.md +10 -0
- package/dist/skill/docs/define/masking.md +13 -0
- package/dist/skill/docs/define/schema.md +9 -1
- package/dist/skill/docs/index.md +2 -0
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +5 -0
- package/dist/skill/docs/tooling/cli.md +3 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +17 -0
- package/dist/skill/docs/ui/account/environment-variables.md +5 -4
- package/dist/skill/docs/ui/account/features/index.md +14 -9
- package/dist/skill/docs/ui/account/hooks.md +12 -5
- package/package.json +1 -1
- package/src/skill/docs/api/batch-operations.md +1 -1
- package/src/skill/docs/api/typescript.md +102 -4
- package/src/skill/docs/define/actions/defining.md +23 -11
- package/src/skill/docs/define/feature.md +10 -0
- package/src/skill/docs/define/masking.md +13 -0
- package/src/skill/docs/define/schema.md +9 -1
- package/src/skill/docs/index.md +2 -0
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +5 -0
- package/src/skill/docs/tooling/cli.md +3 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +17 -0
- package/src/skill/docs/ui/account/environment-variables.md +5 -4
- package/src/skill/docs/ui/account/features/index.md +14 -9
- package/src/skill/docs/ui/account/hooks.md +12 -5
- package/dist/commands/build.test.d.ts +0 -2
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/build.test.js +0 -201
- package/dist/commands/build.test.js.map +0 -1
- package/dist/commands/canary.test.d.ts +0 -2
- package/dist/commands/canary.test.d.ts.map +0 -1
- package/dist/commands/canary.test.js +0 -100
- package/dist/commands/canary.test.js.map +0 -1
- package/dist/commands/deploy.test.d.ts +0 -2
- package/dist/commands/deploy.test.d.ts.map +0 -1
- package/dist/commands/deploy.test.js +0 -139
- package/dist/commands/deploy.test.js.map +0 -1
- package/dist/commands/migrate.test.d.ts +0 -2
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrate.test.js +0 -283
- package/dist/commands/migrate.test.js.map +0 -1
- package/dist/commands/migrations.test.d.ts +0 -2
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.js +0 -162
- package/dist/commands/migrations.test.js.map +0 -1
- package/dist/commands/push.test.d.ts +0 -2
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/push.test.js +0 -76
- package/dist/commands/push.test.js.map +0 -1
- package/dist/commands/schema.test.d.ts +0 -2
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/commands/schema.test.js +0 -137
- package/dist/commands/schema.test.js.map +0 -1
- package/dist/docs/index.test.d.ts +0 -2
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/docs/index.test.js +0 -51
- package/dist/docs/index.test.js.map +0 -1
- package/dist/lib/action-harvest.test.d.ts +0 -2
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.js +0 -645
- package/dist/lib/action-harvest.test.js.map +0 -1
- package/dist/lib/api-client.test.d.ts +0 -2
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.js +0 -373
- package/dist/lib/api-client.test.js.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts +0 -2
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.js +0 -48
- package/dist/lib/artifact-routing.test.js.map +0 -1
- package/dist/lib/auth.test.d.ts +0 -2
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/auth.test.js +0 -19
- package/dist/lib/auth.test.js.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts +0 -2
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.js +0 -76
- package/dist/lib/compile-next-steps.test.js.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts +0 -2
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.js +0 -67
- package/dist/lib/compiler-floor.test.js.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts +0 -2
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.js +0 -246
- package/dist/lib/config-id-splice.test.js.map +0 -1
- package/dist/lib/config-sync.test.d.ts +0 -2
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.js +0 -151
- package/dist/lib/config-sync.test.js.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts +0 -2
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.js +0 -151
- package/dist/lib/copy-public-assets.test.js.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts +0 -2
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.js +0 -170
- package/dist/lib/copy-source-apps.test.js.map +0 -1
- package/dist/lib/deployment-target.test.d.ts +0 -2
- package/dist/lib/deployment-target.test.d.ts.map +0 -1
- package/dist/lib/deployment-target.test.js +0 -63
- package/dist/lib/deployment-target.test.js.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts +0 -2
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.js +0 -136
- package/dist/lib/drizzle-meta-routing.test.js.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts +0 -2
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.js +0 -58
- package/dist/lib/file-loader-typescript-fallback.test.js.map +0 -1
- package/dist/lib/file-loader.test.d.ts +0 -2
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.js +0 -475
- package/dist/lib/file-loader.test.js.map +0 -1
- package/dist/lib/file-writer.test.d.ts +0 -2
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.js +0 -131
- package/dist/lib/file-writer.test.js.map +0 -1
- package/dist/lib/migrations/command-runner.test.d.ts +0 -2
- package/dist/lib/migrations/command-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/command-runner.test.js +0 -19
- package/dist/lib/migrations/command-runner.test.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts +0 -2
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.js +0 -135
- package/dist/lib/migrations/drizzle-prompts.test.js.map +0 -1
- package/dist/lib/migrations/drizzle-wrapper.test.d.ts +0 -2
- package/dist/lib/migrations/drizzle-wrapper.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle-wrapper.test.js +0 -64
- package/dist/lib/migrations/drizzle-wrapper.test.js.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts +0 -2
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.js +0 -71
- package/dist/lib/migrations/drizzle.test.js.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts +0 -2
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.js +0 -270
- package/dist/lib/migrations/executor.test.js.map +0 -1
- package/dist/lib/migrations/headless-generate.test.d.ts +0 -2
- package/dist/lib/migrations/headless-generate.test.d.ts.map +0 -1
- package/dist/lib/migrations/headless-generate.test.js +0 -167
- package/dist/lib/migrations/headless-generate.test.js.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts +0 -2
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.js +0 -81
- package/dist/lib/migrations/inventory.test.js.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts +0 -2
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.js +0 -35
- package/dist/lib/migrations/lock.test.js.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts +0 -2
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.js +0 -32
- package/dist/lib/migrations/paths.test.js.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts +0 -2
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.js +0 -104
- package/dist/lib/migrations/plan.test.js.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts +0 -2
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.js +0 -393
- package/dist/lib/migrations/postprocessors/index.test.js.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts +0 -2
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.js +0 -135
- package/dist/lib/migrations/prompt-runner.test.js.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts +0 -2
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.js +0 -73
- package/dist/lib/migrations/staging.test.js.map +0 -1
- package/dist/lib/neon-canary.test.d.ts +0 -2
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.js +0 -186
- package/dist/lib/neon-canary.test.js.map +0 -1
- package/dist/lib/neon-target.test.d.ts +0 -2
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.js +0 -122
- package/dist/lib/neon-target.test.js.map +0 -1
- package/dist/lib/neon.test.d.ts +0 -2
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/neon.test.js +0 -154
- package/dist/lib/neon.test.js.map +0 -1
- package/dist/lib/prepare-output.test.d.ts +0 -2
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.js +0 -105
- package/dist/lib/prepare-output.test.js.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts +0 -2
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.js +0 -111
- package/dist/lib/prepare-state-output.test.js.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts +0 -2
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.js +0 -216
- package/dist/lib/schema-sync/index.test.js.map +0 -1
- package/dist/lib/shell.test.d.ts +0 -2
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/shell.test.js +0 -73
- package/dist/lib/shell.test.js.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts +0 -2
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.js +0 -347
- package/dist/lib/wrangler-resources.test.js.map +0 -1
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
`feature()` is **the** way to write a Quickback feature: one file, one default export, the table and its security contract together. It expands at compile time into `q.table()` + `defineTable()`, which stays available for the cases that need it — see [When to use which](#when-to-use-which).
|
|
4
4
|
|
|
5
|
+
The name must be a string literal and the configuration must be an inline object
|
|
6
|
+
with an explicit `columns: { … }` object. Missing columns, configuration spreads,
|
|
7
|
+
and referenced configuration objects produce a compile error; elided examples
|
|
8
|
+
must be filled in before compiling.
|
|
9
|
+
|
|
5
10
|
## Quick reference
|
|
6
11
|
|
|
7
12
|
One object. Everything a table exposes is a key in it, and every key is optional
|
|
@@ -48,6 +53,11 @@ feature("name", {
|
|
|
48
53
|
| Semantic search over the table | `embeddings` | [Embeddings](/platform/vector/using-embeddings) |
|
|
49
54
|
| The CMS to render it well | `displayColumn`, `defaultSort`, `inputHints`, `layouts` | [CMS](/ui/admin/table-views) |
|
|
50
55
|
|
|
56
|
+
A resource's `path` sits under the API prefix (default `/api/v1`). Leading and
|
|
57
|
+
trailing slashes are normalized: `path: "accounting-settings"` and
|
|
58
|
+
`path: "/accounting-settings/"` both produce `/api/v1/accounting-settings`.
|
|
59
|
+
CRUD routes, mapped actions, OpenAPI, and action-schema harvest use the same path.
|
|
60
|
+
|
|
51
61
|
The rest of this page is the form itself; [One object, not just
|
|
52
62
|
CRUD](#one-object-not-just-crud) shows the non-CRUD keys filled in.
|
|
53
63
|
|
|
@@ -250,6 +250,19 @@ The schema slot remains reserved for a future batched async-mask pipeline, so
|
|
|
250
250
|
adding that execution mode will not require changing the surrounding masking
|
|
251
251
|
shape.
|
|
252
252
|
|
|
253
|
+
### Masked columns in the type tree
|
|
254
|
+
|
|
255
|
+
Masking is visible to the compiler, not just the runtime. In
|
|
256
|
+
[`quickback.gen.ts`](/api/typescript#masked-columns) a table with masking
|
|
257
|
+
rules reads as `Row<Role>`: the masked column is `Qb.Masked<T>` unless the
|
|
258
|
+
named role is in `show.roles`, so a type never promises a value the API will
|
|
259
|
+
redact.
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
declare const row: Api.customers.Row; // ssn: Qb.Masked<string> | null
|
|
263
|
+
declare const admin: Api.customers.Row<"admin">; // ssn: string | null
|
|
264
|
+
```
|
|
265
|
+
|
|
253
266
|
## Query Gate (filter / sort / search)
|
|
254
267
|
|
|
255
268
|
Masking has a second concern beyond hiding values in the response: a non-admin caller could enumerate masked PII via the query string — e.g. `?filter=email:like:%@target.com` — and infer presence even when the response payload is redacted. The `query` allowlist closes this:
|
|
@@ -227,6 +227,11 @@ If you have an existing Drizzle schema you're bringing forward — or need a dia
|
|
|
227
227
|
| Neon, PlanetScale Postgres, PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
|
|
228
228
|
| MySQL (`planetscale`, `mysql`) — dialect only, no registered provider | `drizzle-orm/mysql-core` | `mysqlTable` |
|
|
229
229
|
|
|
230
|
+
For PostgreSQL targets, the compiler places feature tables in the `app` database
|
|
231
|
+
schema. It initializes the generated schema binding before any table declarations,
|
|
232
|
+
including when several authored table files are combined and retain imports between
|
|
233
|
+
tables. Keep authoring with `pgTable`; the compiler handles schema qualification.
|
|
234
|
+
|
|
230
235
|
```typescript
|
|
231
236
|
// quickback/features/jobs/jobs.ts
|
|
232
237
|
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
|
|
@@ -795,7 +800,10 @@ For LIST endpoints, labels are batch-resolved efficiently — one query per FK c
|
|
|
795
800
|
Declare every feature-table foreign key in the schema with `.references()`.
|
|
796
801
|
That one declaration creates the database relationship and gives the API,
|
|
797
802
|
schema registry, and CMS the same target for label resolution and
|
|
798
|
-
selector/typeahead controls
|
|
803
|
+
selector/typeahead controls, and brands the column with the target table's
|
|
804
|
+
`Id` in [`quickback.gen.ts`](/api/typescript#table-types). The resource-level
|
|
805
|
+
`references:` map and the `<table>Id` naming convention resolve the same
|
|
806
|
+
way for the CMS and the type tree, but create no database constraint:
|
|
799
807
|
|
|
800
808
|
{/* doc-compile: skip — cross-table column excerpt; the complete table forms appear at the top of this page. */}
|
|
801
809
|
```typescript
|
package/dist/skill/docs/index.md
CHANGED
|
@@ -43,6 +43,8 @@ Request → Firewall → Access → Guards → Masking → Response
|
|
|
43
43
|
|
|
44
44
|
**Secure by default.** Nothing is accessible until you explicitly open it up. See [Definitions](/define) for the full security model.
|
|
45
45
|
|
|
46
|
+
**Typed on both sides.** Every compile emits [`quickback.gen.ts`](/api/typescript): branded IDs, `Insert`/`Update` shapes that mirror the guards, role-aware `Row<Role>` types for masked columns, and action outputs that the generated routes enforce at runtime.
|
|
47
|
+
|
|
46
48
|
---
|
|
47
49
|
|
|
48
50
|
## The two products
|
|
@@ -10,6 +10,11 @@ None. The compiler bundles the plugin source and emits it into your project at `
|
|
|
10
10
|
|
|
11
11
|
The plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
|
|
12
12
|
|
|
13
|
+
> **SES only sends through the emailOtp plugin**
|
|
14
|
+
>
|
|
15
|
+
> The compiler wires SES into Better Auth via the `emailOtp` plugin's send callback. With `email.provider: 'aws-ses'` and no `emailOtp` plugin, password-reset, email-verification, and organization-invitation emails are not sent — the compiler warns, and it rejects `requireEmailVerification: true` outright in that shape (no user could ever verify). Add `"emailOtp"` to `providers.auth.config.plugins` (or `account.auth.emailOTP: true`).
|
|
16
|
+
|
|
17
|
+
|
|
13
18
|
## Email Types
|
|
14
19
|
|
|
15
20
|
The plugin handles 8 email types:
|
|
@@ -374,7 +374,9 @@ quickback build
|
|
|
374
374
|
|
|
375
375
|
The CLI parses your feature files with the TypeScript compiler API, and falls back to a **regex** table detector when it can't. That fallback feeds schema sync, firewall analysis, masking detection, and migration generation — a weaker parser for the input that drives your security pillars.
|
|
376
376
|
|
|
377
|
-
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7
|
|
377
|
+
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7`** — both 5.x and 6.x expose the classic compiler API. TypeScript 7 (the native port) resolves its main entry to a module exporting only `version` — parsing moved to the explicitly-unstable `typescript/unstable/*` subpaths — so it cannot drive the AST parser, and the CLI says so by name rather than degrading quietly.
|
|
378
|
+
|
|
379
|
+
Compiled projects pin TypeScript 7 for `tsc`, which typechecks generated output correctly. Add a 6.x devDependency alongside it if you want `quickback schema sync` in that project.
|
|
378
380
|
|
|
379
381
|
Set `QUICKBACK_STRICT_PARSE=1` in CI so a regex-parsed build fails the pipeline instead of shipping:
|
|
380
382
|
|
|
@@ -101,6 +101,23 @@ cd apps/compiler-cloud && bash deploy.sh
|
|
|
101
101
|
|
|
102
102
|
## Troubleshooting
|
|
103
103
|
|
|
104
|
+
### Image dependency or startup check fails
|
|
105
|
+
|
|
106
|
+
The Docker build installs the compiler's dependencies with a frozen lockfile,
|
|
107
|
+
then starts the compiler and checks `/health`. A missing startup dependency
|
|
108
|
+
or startup crash therefore fails the image build before deployment.
|
|
109
|
+
|
|
110
|
+
Every package imported by compiler code at runtime must be declared in
|
|
111
|
+
`apps/compiler/package.json` under `dependencies`. A package available through
|
|
112
|
+
another workspace's install is not necessarily available in the image. Keep
|
|
113
|
+
`apps/compiler/bun.lock` in sync with the Dockerfile's isolated workspace
|
|
114
|
+
(`apps/compiler/package.json` plus `packages/deploy-contract`); do not bypass a
|
|
115
|
+
frozen-lockfile failure with an unlocked install. The compiler's
|
|
116
|
+
`compiler-image-imports.test.ts` check also enforces this import boundary during
|
|
117
|
+
`pnpm verify`. That command also builds Quickback's API and marketing site, so
|
|
118
|
+
you can catch their TypeScript and CSS build failures before triggering a
|
|
119
|
+
deployment. CI runs the same build checks.
|
|
120
|
+
|
|
104
121
|
### Container not starting
|
|
105
122
|
|
|
106
123
|
```bash
|
|
@@ -149,7 +149,7 @@ Enable or disable features using boolean environment variables. **Every flag car
|
|
|
149
149
|
|---|---|---|
|
|
150
150
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
151
151
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
152
|
-
| `VITE_ENABLE_ADMIN` | `admin` | `
|
|
152
|
+
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
153
153
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
154
154
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
155
155
|
| `VITE_ENABLE_EMAIL_OTP` | `emailOTP` | `false` |
|
|
@@ -157,13 +157,14 @@ Enable or disable features using boolean environment variables. **Every flag car
|
|
|
157
157
|
| `VITE_ENABLE_GOOGLE_OAUTH` | `googleOAuth` | `false` |
|
|
158
158
|
| `VITE_ENABLE_SUBSCRIPTIONS` | `subscriptions` | `false` |
|
|
159
159
|
| `VITE_ENABLE_REALTIME` | `realtime` | `false` |
|
|
160
|
+
| `VITE_ENABLE_API_KEYS` | `apiKeys` | `true` |
|
|
160
161
|
|
|
161
162
|
### `appConfig.auth`
|
|
162
163
|
|
|
163
164
|
| Variable | `auth` key | Default |
|
|
164
165
|
|---|---|---|
|
|
165
166
|
| `VITE_ENABLE_SIGNUP` | `enableSignup` | `true` |
|
|
166
|
-
| `VITE_ENABLE_EMAIL_VERIFICATION` | `requireEmailVerification` | `
|
|
167
|
+
| `VITE_ENABLE_EMAIL_VERIFICATION` | `requireEmailVerification` | `false` |
|
|
167
168
|
| `VITE_DISABLE_EMAIL_STATUS_CHECK` | `disableEmailStatusCheck` | `false` |
|
|
168
169
|
|
|
169
170
|
> **Password is on, passkey and OTP are off**
|
|
@@ -176,7 +177,7 @@ Enable or disable features using boolean environment variables. **Every flag car
|
|
|
176
177
|
```bash
|
|
177
178
|
# Authentication
|
|
178
179
|
VITE_ENABLE_SIGNUP=true # default: true
|
|
179
|
-
VITE_ENABLE_EMAIL_VERIFICATION=
|
|
180
|
+
VITE_ENABLE_EMAIL_VERIFICATION=false # default: false — matches the server (Better Auth requireEmailVerification)
|
|
180
181
|
VITE_DISABLE_EMAIL_STATUS_CHECK=false # default: false — inverted sense
|
|
181
182
|
VITE_ENABLE_PASSWORD=true # default: true
|
|
182
183
|
VITE_ENABLE_PASSKEY=false # default: false
|
|
@@ -195,7 +196,7 @@ VITE_ENABLE_ORG_TEAMS=false # default: false
|
|
|
195
196
|
# When false the Teams tab is hidden and the auth client doesn't expose team APIs.
|
|
196
197
|
|
|
197
198
|
# Admin
|
|
198
|
-
VITE_ENABLE_ADMIN=
|
|
199
|
+
VITE_ENABLE_ADMIN=false # default: false — the compiler always emits it explicitly
|
|
199
200
|
```
|
|
200
201
|
|
|
201
202
|
Per-flag behaviour is documented under [Feature Flags](/ui/account/features).
|
|
@@ -11,13 +11,13 @@ Control which features are available in your Account UI deployment using feature
|
|
|
11
11
|
|
|
12
12
|
### `appConfig.features`
|
|
13
13
|
|
|
14
|
-
These
|
|
14
|
+
These eleven flags populate `appConfig.features` and are the ones `isFeatureEnabled()` accepts.
|
|
15
15
|
|
|
16
16
|
| Variable | `features` key | Default |
|
|
17
17
|
|---|---|---|
|
|
18
18
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
19
19
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
20
|
-
| `VITE_ENABLE_ADMIN` | `admin` | `
|
|
20
|
+
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
21
21
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
22
22
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
23
23
|
| `VITE_ENABLE_EMAIL_OTP` | `emailOTP` | `false` |
|
|
@@ -25,6 +25,7 @@ These ten flags populate `appConfig.features` and are the ones `isFeatureEnabled
|
|
|
25
25
|
| `VITE_ENABLE_GOOGLE_OAUTH` | `googleOAuth` | `false` |
|
|
26
26
|
| `VITE_ENABLE_SUBSCRIPTIONS` | `subscriptions` | `false` |
|
|
27
27
|
| `VITE_ENABLE_REALTIME` | `realtime` | `false` |
|
|
28
|
+
| `VITE_ENABLE_API_KEYS` | `apiKeys` | `true` |
|
|
28
29
|
|
|
29
30
|
### `appConfig.auth`
|
|
30
31
|
|
|
@@ -33,12 +34,12 @@ Three further flags configure the signup and email flows. They live on `appConfi
|
|
|
33
34
|
| Variable | `auth` key | Default |
|
|
34
35
|
|---|---|---|
|
|
35
36
|
| `VITE_ENABLE_SIGNUP` | `enableSignup` | `true` |
|
|
36
|
-
| `VITE_ENABLE_EMAIL_VERIFICATION` | `requireEmailVerification` | `
|
|
37
|
+
| `VITE_ENABLE_EMAIL_VERIFICATION` | `requireEmailVerification` | `false` |
|
|
37
38
|
| `VITE_DISABLE_EMAIL_STATUS_CHECK` | `disableEmailStatusCheck` | `false` |
|
|
38
39
|
|
|
39
40
|
> **Password is on, passkey and OTP are off**
|
|
40
41
|
>
|
|
41
|
-
> The out-of-the-box posture is email + password only. Passkey, email OTP, organizations, and Google OAuth all default to `false` — you opt in.
|
|
42
|
+
> The out-of-the-box posture is email + password only. Passkey, email OTP, organizations, admin, and Google OAuth all default to `false` — you opt in. API keys default to `true` in a standalone build; a compiled project always emits the flag from whether the `apiKey` plugin is listed.
|
|
42
43
|
|
|
43
44
|
|
|
44
45
|
> **These are the SPA's built-in defaults — the compiler overrides most of them**
|
|
@@ -48,7 +49,8 @@ Three further flags configure the signup and email flows. They live on `appConfi
|
|
|
48
49
|
> Two derivations are worth knowing because they do not match the built-in default:
|
|
49
50
|
>
|
|
50
51
|
> - **`organizations` resolves to `true`** unless you set `account.auth.organizations: false`, so a compiled project has organizations on even though the SPA default is `false`.
|
|
51
|
-
> - **`admin
|
|
52
|
+
> - **`admin`, `apiKeys`, and `emailVerification` are always emitted as explicit booleans**, never left to the SPA default — the generic bundle carries every route and gates it on the injected flag, so "unset" must arrive as a hard `false`.
|
|
53
|
+
> - **Password reset needs `emailOTP`.** The Account UI's reset flow is code-based (`/forgot-password` sends a one-time code), so a password-only project shows no "Forgot your password?" link and the compiler warns that users have no self-serve recovery. Set `account.auth.emailOTP: true` to enable it.
|
|
52
54
|
|
|
53
55
|
|
|
54
56
|
## Authentication Features
|
|
@@ -74,10 +76,10 @@ Controls whether new users can register.
|
|
|
74
76
|
### Email Verification
|
|
75
77
|
|
|
76
78
|
```bash
|
|
77
|
-
VITE_ENABLE_EMAIL_VERIFICATION=
|
|
79
|
+
VITE_ENABLE_EMAIL_VERIFICATION=false # default: false
|
|
78
80
|
```
|
|
79
81
|
|
|
80
|
-
Controls the email verification flow.
|
|
82
|
+
Controls the email verification flow. The default matches the server (Better Auth `requireEmailVerification` is off unless you set it); a compiled project always emits this flag explicitly.
|
|
81
83
|
|
|
82
84
|
**When enabled:**
|
|
83
85
|
- Users must verify email before full access
|
|
@@ -122,10 +124,12 @@ VITE_ENABLE_PASSWORD=true # default: true
|
|
|
122
124
|
- Email + password fields on login page
|
|
123
125
|
- Password field on signup page
|
|
124
126
|
- Traditional username/password authentication
|
|
127
|
+
- "Forgot your password?" link and profile "Change Password" — only when `VITE_ENABLE_EMAIL_OTP` is also on, because the reset flow is code-based. Without OTP the profile offers an in-session "Update Password" dialog only.
|
|
125
128
|
|
|
126
129
|
**When disabled:**
|
|
127
130
|
- No password fields shown
|
|
128
131
|
- Users authenticate via email OTP or passkey
|
|
132
|
+
- The server's password endpoints are off too — the compiler emits the flag from `emailAndPassword.enabled`
|
|
129
133
|
|
|
130
134
|
### Passkey Login
|
|
131
135
|
|
|
@@ -158,6 +162,7 @@ VITE_ENABLE_EMAIL_OTP=false # default: false
|
|
|
158
162
|
- Users can receive one-time passwords via email
|
|
159
163
|
- Alternative to password login
|
|
160
164
|
- `/email-otp` route available
|
|
165
|
+
- Enables the `/forgot-password` reset flow when password auth is also on
|
|
161
166
|
|
|
162
167
|
**When disabled:**
|
|
163
168
|
- No email OTP option
|
|
@@ -290,7 +295,7 @@ Sub-groups within an organization. Auto-set to `true` by the compiler when your
|
|
|
290
295
|
### Admin Panel
|
|
291
296
|
|
|
292
297
|
```bash
|
|
293
|
-
VITE_ENABLE_ADMIN=
|
|
298
|
+
VITE_ENABLE_ADMIN=false # default: false
|
|
294
299
|
```
|
|
295
300
|
|
|
296
301
|
**When enabled:**
|
|
@@ -323,7 +328,7 @@ VITE_ENABLE_ORGANIZATIONS=false
|
|
|
323
328
|
VITE_ENABLE_ADMIN=false
|
|
324
329
|
```
|
|
325
330
|
|
|
326
|
-
Simple email/password authentication for apps that do not need advanced auth methods.
|
|
331
|
+
Simple email/password authentication for apps that do not need advanced auth methods. These are the built-in defaults. Note there is no self-serve password reset in this shape — add `VITE_ENABLE_EMAIL_OTP=true` for that.
|
|
327
332
|
|
|
328
333
|
### Maximum Security
|
|
329
334
|
|
|
@@ -137,14 +137,21 @@ server hook when tenant selection cannot be derived solely from the session's
|
|
|
137
137
|
active organization.
|
|
138
138
|
|
|
139
139
|
```ts title="quickback/hooks/resolve-oauth-context.ts"
|
|
140
|
-
|
|
140
|
+
import type { OAuthContextResolver } from '@quickback/compiler';
|
|
141
|
+
|
|
142
|
+
const resolveContext: OAuthContextResolver = async (
|
|
143
|
+
{ claims, session, user, request, baseContext },
|
|
144
|
+
{ authDb, authSchema, env },
|
|
145
|
+
) => {
|
|
141
146
|
return {
|
|
142
|
-
activeOrgId: session.activeOrganizationId ??
|
|
143
|
-
activeTeamId: session.activeTeamId ??
|
|
144
|
-
tenantId: session.activeOrganizationId ??
|
|
145
|
-
roles:
|
|
147
|
+
activeOrgId: session.activeOrganizationId ?? undefined,
|
|
148
|
+
activeTeamId: session.activeTeamId ?? undefined,
|
|
149
|
+
tenantId: session.activeOrganizationId ?? undefined,
|
|
150
|
+
roles: baseContext.roles,
|
|
146
151
|
};
|
|
147
152
|
};
|
|
153
|
+
|
|
154
|
+
export default resolveContext;
|
|
148
155
|
```
|
|
149
156
|
|
|
150
157
|
The returned object is merged into the standard `AppContext`. The compiler
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.66.
|
|
3
|
+
"version": "0.66.16",
|
|
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",
|
|
@@ -216,7 +216,7 @@ PUT /api/v1/{resource}/batch
|
|
|
216
216
|
|
|
217
217
|
Inserts new records or updates existing ones. Every record must include an `id` field.
|
|
218
218
|
|
|
219
|
-
**Note:** Batch upsert
|
|
219
|
+
**Note:** Batch upsert requires both `generateId: false` (user-provided IDs) in your database configuration and `guards: false` on the table. Explicitly enabling `crud.batchUpsert` without both settings is a compile error. Use `crud.batchUpdate` for guarded updates.
|
|
220
220
|
|
|
221
221
|
### Request
|
|
222
222
|
|
|
@@ -42,8 +42,18 @@ Each resource table exposes:
|
|
|
42
42
|
| `actions.<name>.Input` | The action's Zod input contract |
|
|
43
43
|
| `actions.<name>.Output` | The declared Zod output contract, or `unknown` |
|
|
44
44
|
|
|
45
|
+
Column types follow the wire, not the storage: `q.bool()` and
|
|
46
|
+
`integer(..., { mode: "boolean" })` are `boolean`, `integer(..., { mode: "timestamp" })`
|
|
47
|
+
and `q.timestamp()` are ISO `string`, `q.json()` is `unknown`, enum columns
|
|
48
|
+
are literal unions, and nullable columns add `| null`.
|
|
49
|
+
|
|
45
50
|
Primary and foreign keys are branded by default. That makes accidentally passing a candidate ID where a job ID is required a TypeScript error, while both values remain ordinary strings or numbers at runtime.
|
|
46
51
|
|
|
52
|
+
A column is a foreign key here by the same rule the CMS and `?include=` use:
|
|
53
|
+
a Drizzle `.references()`, an entry in the resource's `references:` map
|
|
54
|
+
(`{ vendorId: 'contact' }`), or the `<table>Id` naming convention when a
|
|
55
|
+
table of that name exists.
|
|
56
|
+
|
|
47
57
|
```typescript
|
|
48
58
|
function loadJob(id: Api.jobs.Id) {}
|
|
49
59
|
|
|
@@ -57,6 +67,53 @@ At an untyped boundary, validate the value and cast it once:
|
|
|
57
67
|
const jobId = routeParams.id as Api.jobs.Id;
|
|
58
68
|
```
|
|
59
69
|
|
|
70
|
+
### Auth references
|
|
71
|
+
|
|
72
|
+
Columns that point at a Better Auth principal are branded too, even though
|
|
73
|
+
those tables are not part of your project: tenant scopes (`q.scope('organization')`,
|
|
74
|
+
`q.scope('owner')`, `q.scope('team')`), the audit stamps (`createdBy`,
|
|
75
|
+
`modifiedBy`, `deletedBy`), and any `.references('user' | 'organization' | 'team')`
|
|
76
|
+
column.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
declare const job: Api.jobs.Row;
|
|
80
|
+
|
|
81
|
+
job.organizationId; // Qb.OrganizationId
|
|
82
|
+
job.createdBy; // Qb.UserId | null
|
|
83
|
+
|
|
84
|
+
function notify(userId: Qb.UserId) {}
|
|
85
|
+
notify(job.organizationId); // TypeScript error — an org id is not a user id
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Masked columns
|
|
89
|
+
|
|
90
|
+
[Masking](/define/masking) rewrites a column's value for callers outside its
|
|
91
|
+
`show.roles`. A plain `string` type would promise a value the runtime does not
|
|
92
|
+
deliver, so tables with masking rules take a `Role` type parameter on their
|
|
93
|
+
read shapes: `Row<Role>`, `ListResponse<Role>`, `columns.<name><Role>`, and
|
|
94
|
+
`views.<name>.Item<Role>` / `Response<Role>`. Writes (`Insert`, `Update`) are
|
|
95
|
+
unchanged — clients send real values.
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
// jobs.ts: masking: { internalNotes: { type: 'redact', show: { roles: ['admin'] } } }
|
|
99
|
+
declare const anyone: Api.jobs.Row; // Role defaults to never
|
|
100
|
+
declare const admin: Api.jobs.Row<"admin">;
|
|
101
|
+
declare const member: Api.jobs.Row<"member">;
|
|
102
|
+
|
|
103
|
+
anyone.internalNotes; // Qb.Masked<string> | null — may be redacted
|
|
104
|
+
admin.internalNotes; // string | null — revealed
|
|
105
|
+
member.internalNotes; // Qb.Masked<string> | null
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`Qb.Masked<T>` is a brand on the wire primitive: it is still assignable to
|
|
109
|
+
`T` (a masked email is meant to be rendered), but it is not `T`, so a
|
|
110
|
+
function that requires the real value cannot silently accept the default row.
|
|
111
|
+
Name the role you fetched with to get the revealed type; a union role
|
|
112
|
+
(`Row<"member" | "admin">`) yields `T | Qb.Masked<T>`.
|
|
113
|
+
|
|
114
|
+
`show: { or: 'owner' }` reveals by record ownership, which no type parameter
|
|
115
|
+
can see, so those columns stay `Masked` for every role outside `show.roles`.
|
|
116
|
+
|
|
60
117
|
## Reading collections
|
|
61
118
|
|
|
62
119
|
List and view responses share one envelope: rows under `data`, pagination
|
|
@@ -82,7 +139,19 @@ aggregations }` with no rows or pagination.
|
|
|
82
139
|
|
|
83
140
|
## Declaring action outputs
|
|
84
141
|
|
|
85
|
-
Add an optional `output` Zod schema to make an action end-to-end typed
|
|
142
|
+
Add an optional `output` Zod schema to make an action end-to-end typed. An
|
|
143
|
+
action that returns a row of a resource table declares it with `row(<table>)`
|
|
144
|
+
from the feature's helper — its `Output` is that table's `Row`, and OpenAPI
|
|
145
|
+
references the table's component:
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
import { defineAction, row, applications } from "../.quickback/define-action";
|
|
149
|
+
|
|
150
|
+
// Output = Api.applications.Row
|
|
151
|
+
output: row(applications)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
For any other shape, write the schema out:
|
|
86
155
|
|
|
87
156
|
{/* doc-compile: skip — project-config prerequisite: the `recruiter+` gate needs `recruiter` in `auth.roleHierarchy`, and the gate compiles every fence against one fixed harness config whose roles are member/admin/owner. The file is otherwise whole. */}
|
|
88
157
|
|
|
@@ -106,7 +175,34 @@ export default defineAction({
|
|
|
106
175
|
});
|
|
107
176
|
```
|
|
108
177
|
|
|
109
|
-
The generated feature helper checks `execute` against the declared output
|
|
178
|
+
The generated feature helper checks `execute` against the declared output at
|
|
179
|
+
compile time, and the generated route **parses the result through it at
|
|
180
|
+
runtime** (`output.parse(result)`) before responding. The declared type is
|
|
181
|
+
therefore the wire truth, not an annotation: keys the schema does not declare
|
|
182
|
+
are stripped, and a result that does not satisfy the schema is a 500 rather
|
|
183
|
+
than a silently different payload. This holds for `allowRawSql` actions too —
|
|
184
|
+
the raw query is unchecked, but what leaves the action is not. Actions with
|
|
185
|
+
`responseType: 'stream'` or `'file'` return their result untouched.
|
|
186
|
+
|
|
187
|
+
The CLI harvests both schemas locally without invoking `execute`; the resulting contract feeds `quickback.gen.ts`, OpenAPI, and `api-types.gen.ts`.
|
|
188
|
+
|
|
189
|
+
## Types are not transport
|
|
190
|
+
|
|
191
|
+
`quickback.gen.ts` is `import type` only: it describes the API, it does not
|
|
192
|
+
call it. A hand-rolled `fetch` still returns `any`, and nothing checks that
|
|
193
|
+
the URL you typed exists. For a client whose route table is the contract, use
|
|
194
|
+
`api-types.gen.ts` with [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/):
|
|
195
|
+
paths, methods, parameters, and response bodies are checked at the call site,
|
|
196
|
+
and both artifacts come from the same compiler model, so they cannot drift
|
|
197
|
+
from each other.
|
|
198
|
+
|
|
199
|
+
```typescript
|
|
200
|
+
import createClient from "openapi-fetch";
|
|
201
|
+
import type { paths } from "../api-types.gen";
|
|
202
|
+
|
|
203
|
+
const api = createClient<paths>({ baseUrl: "https://api.example.com" });
|
|
204
|
+
const { data } = await api.GET("/api/v1/jobs/{id}", { params: { path: { id } } });
|
|
205
|
+
```
|
|
110
206
|
|
|
111
207
|
## Configuration
|
|
112
208
|
|
|
@@ -119,7 +215,9 @@ export default defineConfig({
|
|
|
119
215
|
});
|
|
120
216
|
```
|
|
121
217
|
|
|
122
|
-
Use a custom path, fan out identical copies to colocated apps
|
|
218
|
+
Use a custom path, fan out identical copies to colocated apps (a monorepo
|
|
219
|
+
sibling such as `../packages/shared/src/quickback.gen.ts` is allowed; absolute
|
|
220
|
+
paths are not), disable branding, or turn the artifact off:
|
|
123
221
|
|
|
124
222
|
```typescript
|
|
125
223
|
export default defineConfig({
|
|
@@ -138,7 +236,7 @@ export default defineConfig({
|
|
|
138
236
|
| `true` or omitted | Write `quickback.gen.ts` |
|
|
139
237
|
| `false` | Do not emit the first-party type tree |
|
|
140
238
|
| `"src/lib/quickback.gen.ts"` | Write to one custom path |
|
|
141
|
-
| `["quickback.gen.ts", "
|
|
239
|
+
| `["quickback.gen.ts", "../packages/shared/src/quickback.gen.ts"]` | Fan out identical copies, including outside the project |
|
|
142
240
|
| `{ output, brandIds: false }` | Configure paths and use structural IDs |
|
|
143
241
|
|
|
144
242
|
`api-types.gen.ts` remains available through `openapi.types` for `openapi-fetch` and third-party OpenAPI tools. The two artifacts are independent: disabling OpenAPI types does not disable the first-party tree.
|
|
@@ -149,32 +149,44 @@ OpenAPI success response becomes `{}` and
|
|
|
149
149
|
`Api.<feature>.actions.<action>.Output` becomes `unknown`. The compile still
|
|
150
150
|
succeeds — it warns, naming how many actions are affected.
|
|
151
151
|
|
|
152
|
-
**
|
|
153
|
-
|
|
152
|
+
**An action that returns a row declares it with `row(<table>)`**, imported
|
|
153
|
+
from the same helper as `defineAction`. **Any other shape is a literal Zod
|
|
154
|
+
schema.** Do not derive a schema from a table yourself:
|
|
154
155
|
|
|
155
156
|
```typescript
|
|
156
|
-
|
|
157
|
-
output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
|
|
157
|
+
import { defineAction, row, tickets } from "../.quickback/define-action";
|
|
158
158
|
|
|
159
|
-
//
|
|
159
|
+
// Returns one ticket: Output = Api.tickets.Row, OpenAPI = the Tickets component.
|
|
160
|
+
output: row(tickets)
|
|
161
|
+
|
|
162
|
+
// Any other shape — write it out.
|
|
160
163
|
output: z.object({
|
|
161
164
|
tickets: z.array(z.object({ id: z.string(), name: z.string(), priceCents: z.number() })),
|
|
162
165
|
})
|
|
166
|
+
|
|
167
|
+
// Silently produces an EMPTY contract — do not do this.
|
|
168
|
+
output: z.object({ tickets: z.array(createSelectSchema(ticketTypes)) })
|
|
163
169
|
```
|
|
164
170
|
|
|
171
|
+
`row(table)` is compiler-recognised: the harvester records which table it
|
|
172
|
+
was handed, and the compiler resolves that to the table's `Row` type in
|
|
173
|
+
`quickback.gen.ts` and to its resource component in OpenAPI (the table must
|
|
174
|
+
be a `defineTable()` resource — anything else is a compile error). At
|
|
175
|
+
runtime it is a real Zod object built from the table's columns.
|
|
176
|
+
|
|
165
177
|
The harvest substitutes inert proxies for table modules, so anything that
|
|
166
178
|
derives a schema by enumerating a table's columns — `createSelectSchema` and
|
|
167
179
|
every equivalent — enumerates **zero** columns. It does not throw. It returns a
|
|
168
180
|
valid, empty object schema, which is then published as the documented success
|
|
169
181
|
response. The compiler warns when a declared `output:` resolves to an empty
|
|
170
182
|
object, but the warning is the only signal; the compile passes and the spec
|
|
171
|
-
looks fine.
|
|
183
|
+
looks fine. `row()` exists so you never need that derivation.
|
|
172
184
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
185
|
+
**A declared `output:` is enforced.** The generated route parses `execute`'s
|
|
186
|
+
result through it before responding, so the published contract is what
|
|
187
|
+
actually leaves the action: undeclared keys are stripped, and a result that
|
|
188
|
+
does not satisfy the schema is a 500. See
|
|
189
|
+
[Declaring action outputs](/api/typescript#declaring-action-outputs).
|
|
178
190
|
|
|
179
191
|
**`output` describes the success path only.** Error responses never pass
|
|
180
192
|
through it: throw
|
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
`feature()` is **the** way to write a Quickback feature: one file, one default export, the table and its security contract together. It expands at compile time into `q.table()` + `defineTable()`, which stays available for the cases that need it — see [When to use which](#when-to-use-which).
|
|
4
4
|
|
|
5
|
+
The name must be a string literal and the configuration must be an inline object
|
|
6
|
+
with an explicit `columns: { … }` object. Missing columns, configuration spreads,
|
|
7
|
+
and referenced configuration objects produce a compile error; elided examples
|
|
8
|
+
must be filled in before compiling.
|
|
9
|
+
|
|
5
10
|
## Quick reference
|
|
6
11
|
|
|
7
12
|
One object. Everything a table exposes is a key in it, and every key is optional
|
|
@@ -48,6 +53,11 @@ feature("name", {
|
|
|
48
53
|
| Semantic search over the table | `embeddings` | [Embeddings](/platform/vector/using-embeddings) |
|
|
49
54
|
| The CMS to render it well | `displayColumn`, `defaultSort`, `inputHints`, `layouts` | [CMS](/ui/admin/table-views) |
|
|
50
55
|
|
|
56
|
+
A resource's `path` sits under the API prefix (default `/api/v1`). Leading and
|
|
57
|
+
trailing slashes are normalized: `path: "accounting-settings"` and
|
|
58
|
+
`path: "/accounting-settings/"` both produce `/api/v1/accounting-settings`.
|
|
59
|
+
CRUD routes, mapped actions, OpenAPI, and action-schema harvest use the same path.
|
|
60
|
+
|
|
51
61
|
The rest of this page is the form itself; [One object, not just
|
|
52
62
|
CRUD](#one-object-not-just-crud) shows the non-CRUD keys filled in.
|
|
53
63
|
|
|
@@ -250,6 +250,19 @@ The schema slot remains reserved for a future batched async-mask pipeline, so
|
|
|
250
250
|
adding that execution mode will not require changing the surrounding masking
|
|
251
251
|
shape.
|
|
252
252
|
|
|
253
|
+
### Masked columns in the type tree
|
|
254
|
+
|
|
255
|
+
Masking is visible to the compiler, not just the runtime. In
|
|
256
|
+
[`quickback.gen.ts`](/api/typescript#masked-columns) a table with masking
|
|
257
|
+
rules reads as `Row<Role>`: the masked column is `Qb.Masked<T>` unless the
|
|
258
|
+
named role is in `show.roles`, so a type never promises a value the API will
|
|
259
|
+
redact.
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
declare const row: Api.customers.Row; // ssn: Qb.Masked<string> | null
|
|
263
|
+
declare const admin: Api.customers.Row<"admin">; // ssn: string | null
|
|
264
|
+
```
|
|
265
|
+
|
|
253
266
|
## Query Gate (filter / sort / search)
|
|
254
267
|
|
|
255
268
|
Masking has a second concern beyond hiding values in the response: a non-admin caller could enumerate masked PII via the query string — e.g. `?filter=email:like:%@target.com` — and infer presence even when the response payload is redacted. The `query` allowlist closes this:
|
|
@@ -227,6 +227,11 @@ If you have an existing Drizzle schema you're bringing forward — or need a dia
|
|
|
227
227
|
| Neon, PlanetScale Postgres, PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
|
|
228
228
|
| MySQL (`planetscale`, `mysql`) — dialect only, no registered provider | `drizzle-orm/mysql-core` | `mysqlTable` |
|
|
229
229
|
|
|
230
|
+
For PostgreSQL targets, the compiler places feature tables in the `app` database
|
|
231
|
+
schema. It initializes the generated schema binding before any table declarations,
|
|
232
|
+
including when several authored table files are combined and retain imports between
|
|
233
|
+
tables. Keep authoring with `pgTable`; the compiler handles schema qualification.
|
|
234
|
+
|
|
230
235
|
```typescript
|
|
231
236
|
// quickback/features/jobs/jobs.ts
|
|
232
237
|
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
|
|
@@ -795,7 +800,10 @@ For LIST endpoints, labels are batch-resolved efficiently — one query per FK c
|
|
|
795
800
|
Declare every feature-table foreign key in the schema with `.references()`.
|
|
796
801
|
That one declaration creates the database relationship and gives the API,
|
|
797
802
|
schema registry, and CMS the same target for label resolution and
|
|
798
|
-
selector/typeahead controls
|
|
803
|
+
selector/typeahead controls, and brands the column with the target table's
|
|
804
|
+
`Id` in [`quickback.gen.ts`](/api/typescript#table-types). The resource-level
|
|
805
|
+
`references:` map and the `<table>Id` naming convention resolve the same
|
|
806
|
+
way for the CMS and the type tree, but create no database constraint:
|
|
799
807
|
|
|
800
808
|
{/* doc-compile: skip — cross-table column excerpt; the complete table forms appear at the top of this page. */}
|
|
801
809
|
```typescript
|
package/src/skill/docs/index.md
CHANGED
|
@@ -43,6 +43,8 @@ Request → Firewall → Access → Guards → Masking → Response
|
|
|
43
43
|
|
|
44
44
|
**Secure by default.** Nothing is accessible until you explicitly open it up. See [Definitions](/define) for the full security model.
|
|
45
45
|
|
|
46
|
+
**Typed on both sides.** Every compile emits [`quickback.gen.ts`](/api/typescript): branded IDs, `Insert`/`Update` shapes that mirror the guards, role-aware `Row<Role>` types for masked columns, and action outputs that the generated routes enforce at runtime.
|
|
47
|
+
|
|
46
48
|
---
|
|
47
49
|
|
|
48
50
|
## The two products
|
|
@@ -10,6 +10,11 @@ None. The compiler bundles the plugin source and emits it into your project at `
|
|
|
10
10
|
|
|
11
11
|
The plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
|
|
12
12
|
|
|
13
|
+
> **SES only sends through the emailOtp plugin**
|
|
14
|
+
>
|
|
15
|
+
> The compiler wires SES into Better Auth via the `emailOtp` plugin's send callback. With `email.provider: 'aws-ses'` and no `emailOtp` plugin, password-reset, email-verification, and organization-invitation emails are not sent — the compiler warns, and it rejects `requireEmailVerification: true` outright in that shape (no user could ever verify). Add `"emailOtp"` to `providers.auth.config.plugins` (or `account.auth.emailOTP: true`).
|
|
16
|
+
|
|
17
|
+
|
|
13
18
|
## Email Types
|
|
14
19
|
|
|
15
20
|
The plugin handles 8 email types:
|
|
@@ -374,7 +374,9 @@ quickback build
|
|
|
374
374
|
|
|
375
375
|
The CLI parses your feature files with the TypeScript compiler API, and falls back to a **regex** table detector when it can't. That fallback feeds schema sync, firewall analysis, masking detection, and migration generation — a weaker parser for the input that drives your security pillars.
|
|
376
376
|
|
|
377
|
-
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7
|
|
377
|
+
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7`** — both 5.x and 6.x expose the classic compiler API. TypeScript 7 (the native port) resolves its main entry to a module exporting only `version` — parsing moved to the explicitly-unstable `typescript/unstable/*` subpaths — so it cannot drive the AST parser, and the CLI says so by name rather than degrading quietly.
|
|
378
|
+
|
|
379
|
+
Compiled projects pin TypeScript 7 for `tsc`, which typechecks generated output correctly. Add a 6.x devDependency alongside it if you want `quickback schema sync` in that project.
|
|
378
380
|
|
|
379
381
|
Set `QUICKBACK_STRICT_PARSE=1` in CI so a regex-parsed build fails the pipeline instead of shipping:
|
|
380
382
|
|