@quickback-dev/cli 0.10.16 → 0.10.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1192 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +67 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1192 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +228 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +67 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
package/dist/skill/SKILL.md
CHANGED
|
@@ -1,240 +1,104 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: quickback
|
|
3
|
-
description: Quickback
|
|
4
|
-
allowed-tools: Read, Grep, Glob
|
|
3
|
+
description: Quickback documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, the Stack runtime services, or deployment
|
|
4
|
+
allowed-tools: Read, Grep, Glob, Edit, Write
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Quickback
|
|
8
8
|
|
|
9
|
-
Quickback is
|
|
9
|
+
Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript; compile them into either a Hono API or PostgreSQL Row Level Security policies. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
|
|
11
|
+
It's two products:
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
## 1. Quickback Compiler — the build tool
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
Define schema + security in TypeScript. Compile to one of two targets:
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
- **Quickback for Hono API** — Cloudflare D1 or Neon. Full Hono application with CRUD, batch endpoints, OpenAPI, and an MCP server.
|
|
18
|
+
- **Quickback for Supabase** — PostgreSQL Row Level Security policies. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
quickback docs # List all available topics
|
|
22
|
-
quickback docs <topic> # Show docs for a specific topic
|
|
23
|
-
quickback docs firewall # Example: firewall docs
|
|
24
|
-
quickback docs cms/record-layouts # Example: CMS record layouts
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Full online docs: https://docs.quickback.dev
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
# PART 1: THE COMPILER
|
|
32
|
-
|
|
33
|
-
The compiler takes your TypeScript definitions and generates API routes, middleware, migrations, typed SDKs, OpenAPI specs, and AI tool definitions.
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
┌─────────────────────────────────────────────────────────┐
|
|
37
|
-
│ YOU DEFINE (in TypeScript) │
|
|
38
|
-
│ • Drizzle schema (your data models) │
|
|
39
|
-
│ • Security layers (Firewall, Access, Guards, Masking) │
|
|
40
|
-
│ • Views, Validation, Layouts │
|
|
41
|
-
│ • Actions (your business operations) │
|
|
42
|
-
├─────────────────────────────────────────────────────────┤
|
|
43
|
-
│ QUICKBACK COMPILES TO │
|
|
44
|
-
│ • Database migrations (via Drizzle) │
|
|
45
|
-
│ • API route handlers (Hono) │
|
|
46
|
-
│ • Typed client SDK for your frontend │
|
|
47
|
-
│ • AI tool definitions │
|
|
48
|
-
│ • OpenAPI specification │
|
|
49
|
-
└─────────────────────────────────────────────────────────┘
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Project Structure
|
|
20
|
+
The same `defineTable()` definitions work for both targets. The compiler runs as a remote service at `compiler.quickback.dev` (override with `QUICKBACK_API_URL`) — the CLI is a thin client that sends config + features and writes the generated files.
|
|
53
21
|
|
|
54
|
-
|
|
55
|
-
my-app/
|
|
56
|
-
├── quickback/
|
|
57
|
-
│ ├── quickback.config.ts
|
|
58
|
-
│ └── features/
|
|
59
|
-
│ └── {feature-name}/
|
|
60
|
-
│ ├── {table}.ts # Schema + security (defineTable)
|
|
61
|
-
│ ├── actions/ # One file per action — defineAction({...})
|
|
62
|
-
│ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
|
|
63
|
-
│ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
|
|
64
|
-
│ ├── lib/ # Feature-local helpers, copied verbatim (optional)
|
|
65
|
-
│ └── pages/ # Custom CMS pages (optional)
|
|
66
|
-
│ └── {slug}.ts # definePage() call
|
|
67
|
-
├── src/ # ← compiled output
|
|
68
|
-
│ ├── index.ts # API entry (Hono)
|
|
69
|
-
│ └── apps/
|
|
70
|
-
│ ├── cms/ # ← CMS static assets (when cms: true)
|
|
71
|
-
│ │ ├── index.html
|
|
72
|
-
│ │ └── assets/
|
|
73
|
-
│ └── account/ # ← Account UI assets (when account: true/object)
|
|
74
|
-
│ ├── index.html
|
|
75
|
-
│ └── assets/
|
|
76
|
-
└── ...
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
## quickback.config.ts
|
|
80
|
-
|
|
81
|
-
```typescript
|
|
82
|
-
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
|
|
83
|
-
|
|
84
|
-
export default defineConfig({
|
|
85
|
-
name: "my-saas-app",
|
|
86
|
-
cms: true, // Embed CMS admin UI in compiled Worker (or { domain: "cms.example.com" })
|
|
87
|
-
account: { // Embed Account UI (auth, profile, orgs, admin) in compiled Worker
|
|
88
|
-
domain: "auth.example.com", // Optional: custom domain (served at / instead of /account/)
|
|
89
|
-
adminDomain: "admin.example.com", // Optional: separate admin domain
|
|
90
|
-
name: "My App",
|
|
91
|
-
companyName: "My Company",
|
|
92
|
-
tagline: "Build faster, ship sooner",
|
|
93
|
-
build: true, // Set false to skip SPA rebuild on subsequent compiles
|
|
94
|
-
auth: {
|
|
95
|
-
password: true, // Email/password login (default: true)
|
|
96
|
-
emailOTP: true, // Email OTP login (default: false)
|
|
97
|
-
passkey: true, // WebAuthn passkeys (default: false)
|
|
98
|
-
signup: true, // User registration (default: true)
|
|
99
|
-
organizations: true, // Multi-tenant org management UI (default: false; the orgs plugin itself is enabled by `features.organizations` which defaults true)
|
|
100
|
-
admin: true, // Admin panel (default: true)
|
|
101
|
-
emailVerification: true, // Require email verification (default: true)
|
|
102
|
-
},
|
|
103
|
-
},
|
|
104
|
-
providers: {
|
|
105
|
-
runtime: defineRuntime("cloudflare"),
|
|
106
|
-
database: defineDatabase("cloudflare-d1"),
|
|
107
|
-
auth: defineAuth("better-auth"),
|
|
108
|
-
},
|
|
109
|
-
build: {
|
|
110
|
-
outputDir: "dist",
|
|
111
|
-
dependencies: {
|
|
112
|
-
"fast-xml-parser": "^4.5.0", // Third-party packages used in action handlers
|
|
113
|
-
},
|
|
114
|
-
},
|
|
115
|
-
});
|
|
116
|
-
```
|
|
22
|
+
## 2. Quickback Stack — the runtime services
|
|
117
23
|
|
|
118
|
-
|
|
24
|
+
Everything you need around the compiled API for a complete Supabase alternative on Cloudflare:
|
|
119
25
|
|
|
120
|
-
|
|
26
|
+
| Service | What it gives you | Implementation |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| **Auth** | Email OTP, passkeys, password, Google OAuth, organizations, admin | Better Auth |
|
|
29
|
+
| **Storage** | KV (sessions, cache) and R2 (files) | Cloudflare KV + R2 |
|
|
30
|
+
| **Realtime** | WebSocket for live updates | Durable Objects |
|
|
31
|
+
| **Queues** | Background jobs, webhook delivery | Cloudflare Queues |
|
|
32
|
+
| **Vector & AI** | Embeddings, semantic search | Workers AI |
|
|
33
|
+
| **Webhooks** | Signed inbound, retried outbound | Hono + Queues |
|
|
34
|
+
| **CMS** | Schema-driven admin UI | Embedded SPA |
|
|
35
|
+
| **Account UI** | Login, profile, orgs, admin | Embedded SPA |
|
|
121
36
|
|
|
122
|
-
|
|
37
|
+
Everything runs on the user's own Cloudflare account — no Quickback infrastructure between them and their data.
|
|
123
38
|
|
|
124
|
-
|
|
39
|
+
---
|
|
125
40
|
|
|
126
|
-
|
|
41
|
+
## Quickstart
|
|
127
42
|
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
queues: {
|
|
135
|
-
producers: [{ binding: 'JOBS', queue: 'jobs' }],
|
|
136
|
-
consumers: [{ queue: 'jobs', maxBatchSize: 10 }],
|
|
137
|
-
},
|
|
138
|
-
durableObjects: [{ binding: 'CHAT', className: 'ChatRoom' }],
|
|
139
|
-
vars: { FEATURE_X: 'true' },
|
|
140
|
-
},
|
|
141
|
-
});
|
|
43
|
+
```bash
|
|
44
|
+
npm install -g @quickback-dev/cli
|
|
45
|
+
quickback create cloudflare my-app
|
|
46
|
+
cd my-app
|
|
47
|
+
quickback compile
|
|
48
|
+
wrangler deploy
|
|
142
49
|
```
|
|
143
50
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
`cms: true` defaults to `access: 'admin'` — only users with `user.role === 'admin'` can enter the CMS. Non-admins are redirected to `/account/profile`. Override with `cms: { access: 'user' }` to open the CMS to all authenticated users.
|
|
147
|
-
|
|
148
|
-
### Account fileUploads
|
|
149
|
-
|
|
150
|
-
`account.fileUploads: true` shows the avatar upload UI on the profile page. Defaults to `false`; enabling it requires R2 configured for storage.
|
|
151
|
-
|
|
152
|
-
## Compile Output and State Artifacts
|
|
153
|
-
|
|
154
|
-
- Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
|
|
155
|
-
- CMS assets → `src/apps/cms/` (served at `/cms/` or root on custom domain)
|
|
156
|
-
- Account UI assets → `src/apps/account/` (served at `/account/` or root on custom domain)
|
|
157
|
-
- Drizzle migration SQL and meta files live under `quickback/drizzle/...` — Quickback owns this state and never writes a project-root `drizzle/` folder
|
|
158
|
-
- Security contract reports are written to `quickback/reports/...`
|
|
159
|
-
|
|
160
|
-
## Automatic Audit Fields
|
|
161
|
-
|
|
162
|
-
Quickback injects four **audit columns** into every table at compile time, and the runtime hard-stamps them on every write:
|
|
51
|
+
Three concept files do most of the work:
|
|
163
52
|
|
|
164
|
-
- `
|
|
165
|
-
- `
|
|
53
|
+
- `quickback.config.ts` — project config (template, providers, account UI, CMS, etc.)
|
|
54
|
+
- `quickback/features/<feature>/<table>.ts` — table schema + security in one file via `feature()` (or `defineTable` for Drizzle interop)
|
|
55
|
+
- `quickback/features/<feature>/actions/<name>.ts` — custom endpoints via `defineAction()` (one file per action)
|
|
166
56
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
**Do NOT add any of these six to your schema files.** They are injected by the compiler.
|
|
170
|
-
|
|
171
|
-
### Caller contract (write through the request-context `db`)
|
|
172
|
-
|
|
173
|
-
The wrapper around `db` overwrites all four audit fields on every `.insert().values()` and `.set()` call — caller-supplied values are silently dropped. So in custom actions:
|
|
174
|
-
|
|
175
|
-
✅ INSERT — set `id` and domain fields only:
|
|
57
|
+
---
|
|
176
58
|
|
|
177
|
-
|
|
178
|
-
await db.insert(records).values({ id: createId(), name: input.name });
|
|
179
|
-
```
|
|
59
|
+
## The security model
|
|
180
60
|
|
|
181
|
-
|
|
61
|
+
Every API request passes through four pillars (the "Definitions"):
|
|
182
62
|
|
|
183
|
-
```ts
|
|
184
|
-
await db.update(records).set({ status: 'closed' }).where(...);
|
|
185
63
|
```
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
64
|
+
Request → Firewall → Access → Guards → Database → Masking → Response
|
|
65
|
+
│ │ │ │
|
|
66
|
+
│ │ │ └── Hide PII fields
|
|
67
|
+
│ │ └── Block field modifications on writes
|
|
68
|
+
│ └── Check roles & record-level conditions
|
|
69
|
+
└── WHERE-clause data isolation (org / owner / team / soft-delete)
|
|
191
70
|
```
|
|
192
71
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
### Actor convention (`ctx.userId` for non-user writes)
|
|
196
|
-
|
|
197
|
-
The wrapper throws `audit-wrapper: <op> reached without ctx.userId` if a write reaches it without a userId. For user-driven requests, auth middleware fills it in. For non-user entry points, mint a synthetic actor id at the boundary:
|
|
198
|
-
|
|
199
|
-
| Boundary | Actor id |
|
|
72
|
+
| Pillar | Purpose |
|
|
200
73
|
|---|---|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
|
205
|
-
| Out-of-band operator script | `system:script-<name>` |
|
|
74
|
+
| **Firewall** | Compiled WHERE clauses — scope reads/writes to the caller's org, owner, or team. |
|
|
75
|
+
| **Access** | Role-based + record-level permissions; **deny by default**. |
|
|
76
|
+
| **Guards** | Field-write protection: `createable`, `updatable`, `immutable`, `protected` (action-only). |
|
|
77
|
+
| **Masking** | PII redaction; auto-applied for sensitive column names. |
|
|
206
78
|
|
|
207
|
-
**
|
|
79
|
+
Plus **Views** (named projections with their own access) and **Actions** (custom endpoints with declarative access, transitions, unsafe escape hatch).
|
|
208
80
|
|
|
209
|
-
|
|
81
|
+
**Secure by default.** Nothing is reachable until you explicitly open it. A fresh resource definition produces 401/403 for every caller that isn't an admin.
|
|
210
82
|
|
|
211
|
-
|
|
83
|
+
For the full reference, run `quickback docs compiler/definitions` (or any specific pillar: `firewall`, `access`, `guards`, `masking`, `views`, `actions`).
|
|
212
84
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
Features live in `quickback/features/{name}/` with one file per table.
|
|
216
|
-
|
|
217
|
-
Quickback offers **three co-equal authoring patterns** — all compile to the same generated runtime, the compiler dispatches per file:
|
|
218
|
-
|
|
219
|
-
- **`feature()`** (recommended default) — single default export, one import, everything in one call. Use for new code.
|
|
220
|
-
- **`q.table()` + `defineTable()`** — the two-export form. Same `q` DSL, more explicit. Use when you want the table identifier named before the default export.
|
|
221
|
-
- **Drizzle `sqliteTable()` / `pgTable()` + `defineTable()`** — interop with existing Drizzle code.
|
|
85
|
+
---
|
|
222
86
|
|
|
223
|
-
|
|
87
|
+
## A complete feature
|
|
224
88
|
|
|
225
|
-
```
|
|
89
|
+
```ts
|
|
90
|
+
// quickback/features/todos/todos.ts
|
|
226
91
|
import { feature, q } from "@quickback/compiler";
|
|
227
92
|
|
|
228
93
|
export default feature("todos", {
|
|
229
94
|
columns: {
|
|
230
95
|
id: q.id(),
|
|
231
96
|
title: q.text().required(),
|
|
232
|
-
description: q.text({ maxLength: 1000 }).optional(),
|
|
233
97
|
completed: q.bool().default(false),
|
|
234
98
|
ownerId: q.scope("owner"), // → ctx.userId, auto-firewalled, auto-populated
|
|
235
99
|
organizationId: q.scope("organization"), // → ctx.activeOrgId, same
|
|
236
100
|
},
|
|
237
|
-
// firewall
|
|
101
|
+
// firewall + soft-delete derived from q.scope() above:
|
|
238
102
|
// [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
239
103
|
// { field: 'ownerId', equals: 'ctx.userId' },
|
|
240
104
|
// { field: 'deletedAt', isNull: true }]
|
|
@@ -245,910 +109,137 @@ export default feature("todos", {
|
|
|
245
109
|
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
246
110
|
},
|
|
247
111
|
guards: {
|
|
248
|
-
createable: ["title", "
|
|
249
|
-
updatable: ["title", "
|
|
250
|
-
},
|
|
251
|
-
});
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
The `feature()` form is compile-time sugar — the compiler expands it to `q.table()` + `defineTable()` internally. Use whichever reads best for the file.
|
|
255
|
-
|
|
256
|
-
### q DSL — column types
|
|
257
|
-
|
|
258
|
-
Column names default to snake_case of the JS key (`organizationId` → `organization_id`). Override with the positional name string or the `sqlName` option.
|
|
259
|
-
|
|
260
|
-
| Builder | SQL | Zod | Notes |
|
|
261
|
-
|---|---|---|---|
|
|
262
|
-
| `q.id()` | `text('id').primaryKey()` | `z.string()` | cuid2 by default; ID style follows `database.generateId` |
|
|
263
|
-
| `q.text(name?)` / `q.text({ sqlName?, maxLength? })` | `text(...)` | `z.string()` (`.max(n)` if `maxLength`) | options form adds zod max-length only — SQL stays unconstrained |
|
|
264
|
-
| `q.url({ sqlName?, maxLength? })` | `text(...)` | `z.string().url()` | rejects `javascript:` / `data:` / non-URL strings at the API edge |
|
|
265
|
-
| `q.int(name?)` | `integer(...)` | `z.number().int()` | |
|
|
266
|
-
| `q.bool(name?)` | `boolean(...)` (sqlite: integer mode) | `z.boolean()` | |
|
|
267
|
-
| `q.uuid(name?)` | `uuid(...)` (sqlite: text) | `z.string().uuid()` | |
|
|
268
|
-
| `q.timestamp(name?)` | `timestamp(...)` (sqlite: text ISO) | `z.coerce.date()` | |
|
|
269
|
-
| `q.json(zodType?)` | `jsonb(...)` (sqlite: text mode) | `z.unknown()` or your zod | pass a zod schema for typed JSON |
|
|
270
|
-
| `q.enum(['a','b'])` | `text(..., { enum })` | `z.enum([...])` | |
|
|
271
|
-
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` | tenant-scope column — see Firewall |
|
|
272
|
-
|
|
273
|
-
**Chainable modifiers:** `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.filterable(false)` / `.searchable(false)` / `.references(() => other.id, { onDelete: 'cascade' })`.
|
|
274
|
-
|
|
275
|
-
`.filterable(false)` and `.searchable(false)` are capability opt-outs — every text column is filter/search-eligible by default; chain `false` to remove a column from `?<col>=` filters or the `?search=` OR'd LIKE scan. Masked columns are always excluded from `?search` regardless (see Masking).
|
|
276
|
-
|
|
277
|
-
### Composite indexes & uniques on `feature()`
|
|
278
|
-
|
|
279
|
-
Single-column indexes go on the column (`q.text().index()`). Composite ones go at the top level — the sugar forwards them into the same `q.table` opts:
|
|
280
|
-
|
|
281
|
-
```typescript
|
|
282
|
-
export default feature("memberships", {
|
|
283
|
-
columns: { userId: q.scope("owner"), organizationId: q.scope("organization"), role: q.text() },
|
|
284
|
-
indexes: [{ name: "memberships_user_org_idx", columns: ["userId", "organizationId"] }],
|
|
285
|
-
unique: [{ columns: ["userId", "organizationId"] }],
|
|
286
|
-
// ... read / crud / guards
|
|
287
|
-
});
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
**Auto-indexes:** the compiler emits the indexes you'd otherwise author by hand. Don't pre-declare these — they'll be deduped:
|
|
291
|
-
|
|
292
|
-
| Trigger | Index emitted |
|
|
293
|
-
|---|---|
|
|
294
|
-
| Tenant col (`organizationId` / `userId`) + `deletedAt` | composite `(<isolation>, deletedAt)` |
|
|
295
|
-
| Any FK (`.references(...)`) | single-col `(<fk>)` (D1/SQLite don't auto-index FKs) |
|
|
296
|
-
| Any column in a view's `read.query.sortable` | single-col `(<col>)` |
|
|
297
|
-
|
|
298
|
-
### Example: same todos using the two-export form
|
|
299
|
-
|
|
300
|
-
```typescript
|
|
301
|
-
import { q, defineTable } from "@quickback/compiler";
|
|
302
|
-
|
|
303
|
-
export const todos = q.table("todos", {
|
|
304
|
-
id: q.id(),
|
|
305
|
-
title: q.text().required(),
|
|
306
|
-
completed: q.bool().default(false),
|
|
307
|
-
ownerId: q.scope("owner"),
|
|
308
|
-
organizationId: q.scope("organization"),
|
|
309
|
-
});
|
|
310
|
-
|
|
311
|
-
export default defineTable(todos, {
|
|
312
|
-
// firewall auto-derived from q.scope() — same as the feature() example
|
|
313
|
-
read: { /* same as above */ },
|
|
314
|
-
crud: { /* same as above */ },
|
|
315
|
-
guards: { /* same as above */ },
|
|
316
|
-
});
|
|
317
|
-
|
|
318
|
-
export type Todo = typeof todos.$infer;
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
### Example: same todos with Drizzle (for interop)
|
|
322
|
-
|
|
323
|
-
When bringing forward existing Drizzle code, declare a regular column. Auto-detection by **name** (`organizationId`, `ownerId`, `teamId`, `userId`) still picks it up — `q.scope()` semantics (auto-firewall, systemManaged, auto-populate) apply because they key off the firewall predicate, not the column DSL.
|
|
324
|
-
|
|
325
|
-
```typescript
|
|
326
|
-
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
|
|
327
|
-
import { defineTable } from "@quickback/compiler";
|
|
328
|
-
|
|
329
|
-
export const todos = sqliteTable("todos", {
|
|
330
|
-
id: text("id").primaryKey(),
|
|
331
|
-
title: text("title").notNull(),
|
|
332
|
-
completed: integer("completed", { mode: "boolean" }).default(false),
|
|
333
|
-
userId: text("user_id").notNull(),
|
|
334
|
-
organizationId: text("organization_id").notNull(),
|
|
335
|
-
});
|
|
336
|
-
|
|
337
|
-
export default defineTable(todos, {
|
|
338
|
-
// firewall auto-derived from column names; declare explicitly only if names don't match
|
|
339
|
-
read: { /* same as above */ },
|
|
340
|
-
crud: { /* same as above */ },
|
|
341
|
-
guards: { /* same as above */ },
|
|
342
|
-
});
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
### Internal/Junction Tables (No API)
|
|
346
|
-
|
|
347
|
-
Tables without a `defineTable()` / `feature()` default export get no API routes:
|
|
348
|
-
|
|
349
|
-
```typescript
|
|
350
|
-
export const roomAmenities = q.table('roomAmenities', {
|
|
351
|
-
roomId: q.text().required(),
|
|
352
|
-
amenityId: q.text().required(),
|
|
353
|
-
});
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
The compiler warns once per such table so you confirm the opt-out is intentional.
|
|
357
|
-
|
|
358
|
-
### Action files use `q.*` for query helpers too
|
|
359
|
-
|
|
360
|
-
Action `execute` functions query via the same `q` namespace:
|
|
361
|
-
|
|
362
|
-
```typescript
|
|
363
|
-
// quickback/features/mail/actions/inbound.ts
|
|
364
|
-
import { defineAction } from "../.quickback/define-action";
|
|
365
|
-
import { q } from "../../../lib/q";
|
|
366
|
-
import { mailboxes } from "../mailboxes";
|
|
367
|
-
import { messages } from "../messages";
|
|
368
|
-
|
|
369
|
-
export default defineAction({
|
|
370
|
-
description: "Process inbound mail",
|
|
371
|
-
path: "/inbound",
|
|
372
|
-
/* ... */
|
|
373
|
-
async execute({ unsafeDb, input }) {
|
|
374
|
-
const mailbox = await unsafeDb.query.mailboxes.findFirst({
|
|
375
|
-
where: q.eq(mailboxes.address, input.mailboxAddress),
|
|
376
|
-
});
|
|
377
|
-
// …
|
|
112
|
+
createable: ["title", "completed"],
|
|
113
|
+
updatable: ["title", "completed"],
|
|
378
114
|
},
|
|
379
115
|
});
|
|
380
116
|
```
|
|
381
117
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
### Explicit scope in unsafe handlers — `unsafeDb.scopeTo(...)`
|
|
385
|
-
|
|
386
|
-
When an unsafe handler (webhook, cron, bulk importer) knows its tenant out-of-band, call `scopeTo` instead of hand-rolling `organizationId` on every query. The firewall runs unchanged with a synthesized ctx:
|
|
387
|
-
|
|
388
|
-
```typescript
|
|
389
|
-
export const execute = async ({ unsafeDb, input }) => {
|
|
390
|
-
const [mailbox] = await unsafeDb.select().from(mailboxes)
|
|
391
|
-
.where(q.eq(mailboxes.id, input.mailboxId));
|
|
392
|
-
if (!mailbox) return { ok: false };
|
|
393
|
-
|
|
394
|
-
const db = unsafeDb.scopeTo({ organizationId: mailbox.organizationId });
|
|
395
|
-
await db.insert(messages).values({ mailboxId: mailbox.id, body: input.body });
|
|
396
|
-
return { ok: true };
|
|
397
|
-
};
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
`scopeTo` accepts `{ organizationId?, userId?, teamId? }` — any subset. Missing keys fall back to the ambient `ctx` values. Every downstream `.select/.update/.delete` gets a `WHERE` scope clause; every `.insert().values()` auto-injects the scope columns. Reach for this any time an unsafe handler needs scoped writes — it is the canonical way to keep tenant isolation while the handler bypasses the request ctx.
|
|
401
|
-
|
|
402
|
-
### Import style
|
|
403
|
-
|
|
404
|
-
With `feature()`, tables are **default exports** — use default imports:
|
|
405
|
-
|
|
406
|
-
```typescript
|
|
407
|
-
// features/applications/actions/advance.ts
|
|
408
|
-
import applications from "../applications";
|
|
409
|
-
import { defineAction } from "../.quickback/define-action";
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
With the two-export form (`defineTable`), tables are **named exports** — use named imports:
|
|
413
|
-
|
|
414
|
-
```typescript
|
|
415
|
-
import { applications } from "../applications";
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
Both produce the same typed handle.
|
|
419
|
-
|
|
420
|
-
---
|
|
421
|
-
|
|
422
|
-
## Input Hints
|
|
423
|
-
|
|
424
|
-
Control how the CMS renders form inputs. Key values:
|
|
425
|
-
|
|
426
|
-
| Hint | Renders As |
|
|
427
|
-
|------|-----------|
|
|
428
|
-
| `richtext` | Tiptap rich text editor (edit) / formatted HTML (view). Stores HTML. |
|
|
429
|
-
| `select` | Dropdown select |
|
|
430
|
-
| `textarea` | Multi-line text |
|
|
431
|
-
| `currency` | Currency input |
|
|
432
|
-
| `checkbox` | Checkbox toggle |
|
|
433
|
-
|
|
434
|
-
```typescript
|
|
435
|
-
inputHints: { description: "richtext", status: "select" }
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
---
|
|
439
|
-
|
|
440
|
-
## Four Security Layers
|
|
441
|
-
|
|
442
|
-
Every API request passes through four layers in order:
|
|
443
|
-
|
|
444
|
-
```
|
|
445
|
-
Request → Firewall → Access → Guards → Database → Masking → Response
|
|
446
|
-
```
|
|
447
|
-
|
|
448
|
-
| Layer | Purpose | Failure |
|
|
449
|
-
|-------|---------|---------|
|
|
450
|
-
| **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
|
|
451
|
-
| **Access** | Role-based CRUD permissions (deny by default) | 403 |
|
|
452
|
-
| **Guards** | Field modification rules (protected/immutable fields) | 400 |
|
|
453
|
-
| **Masking** | PII redaction for unauthorized viewers | — |
|
|
454
|
-
|
|
455
|
-
### 1. Firewall — Data Isolation
|
|
456
|
-
|
|
457
|
-
Compiles WHERE clauses to isolate data by ownership. Predicates are AND'd together.
|
|
458
|
-
|
|
459
|
-
```typescript
|
|
460
|
-
firewall: [
|
|
461
|
-
{ field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
|
|
462
|
-
{ field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
|
|
463
|
-
{ field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
|
|
464
|
-
{ field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL (soft-delete filter)
|
|
465
|
-
]
|
|
466
|
-
|
|
467
|
-
// Public/system resources opt out of tenant scoping (soft-delete still applied):
|
|
468
|
-
firewall: [{ exception: true }]
|
|
469
|
-
```
|
|
470
|
-
|
|
471
|
-
**Recommended: declare scope columns with `q.scope()`** — auto-derives the firewall predicate AND marks the column `systemManaged` (rejected from client input) AND auto-populates from ctx on insert/upsert. Zero ambiguity in the source:
|
|
472
|
-
|
|
473
|
-
```typescript
|
|
474
|
-
columns: {
|
|
475
|
-
organizationId: q.scope("organization"), // → ctx.activeOrgId
|
|
476
|
-
ownerId: q.scope("owner"), // → ctx.userId
|
|
477
|
-
teamId: q.scope("team"), // → ctx.activeTeamId
|
|
478
|
-
}
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
**Auto-derivation by name** (Drizzle interop, when the `firewall:` block is omitted): the compiler scans column names and emits the same predicates.
|
|
482
|
-
|
|
483
|
-
| Column name in schema | Predicate emitted |
|
|
484
|
-
|---|---|
|
|
485
|
-
| `organizationId` / `organisationId` | `{ field: '...', equals: 'ctx.activeOrgId' }` |
|
|
486
|
-
| `userId` (or `ownerId`) | `{ field: '...', equals: 'ctx.userId' }` |
|
|
487
|
-
| `teamId` | `{ field: 'teamId', equals: 'ctx.activeTeamId' }` |
|
|
488
|
-
| `deletedAt` (present whenever the resource uses soft delete, which is the default) | `{ field: 'deletedAt', isNull: true }` |
|
|
489
|
-
|
|
490
|
-
- Exactly one isolation column → auto-derived.
|
|
491
|
-
- Two or more → compile-time error; declare `firewall: [...]` explicitly OR use `q.scope()` to lock semantics in the source.
|
|
492
|
-
- Zero columns AND no PUBLIC route → compile-time error ("missing isolation column").
|
|
493
|
-
|
|
494
|
-
**Custom column / context source**: just write the predicate explicitly.
|
|
495
|
-
|
|
496
|
-
```typescript
|
|
497
|
-
firewall: [
|
|
498
|
-
{ field: 'tenantId', equals: 'ctx.activeOrgId' },
|
|
499
|
-
{ field: 'status', in: ['active', 'pending'] }, // literal value, not ctx-derived
|
|
500
|
-
]
|
|
501
|
-
```
|
|
502
|
-
|
|
503
|
-
**Predicate operators**: `equals` (column = ctx.* or literal), `isNull: true` (column IS NULL), `in: [...]` (column IN ...), `{ exception: true }` (opt out of tenant scoping).
|
|
504
|
-
|
|
505
|
-
### 2. Access — Permission Checks
|
|
506
|
-
|
|
507
|
-
Role-based and record-based access control. Deny by default.
|
|
508
|
-
|
|
509
|
-
DSL v2 separates **reads** (collection + per-id GET) from **mutations**. The unified `read` block owns `GET /` AND `GET /:id` AND views; mutations live under `crud.create/update/delete`.
|
|
510
|
-
|
|
511
|
-
```typescript
|
|
512
|
-
read: {
|
|
513
|
-
access: { roles: ['member+'] }, // gates GET / and GET /:id
|
|
514
|
-
query: {
|
|
515
|
-
sortable: ['createdAt', 'status'], // ?sort= allowlist (defaults to all cols)
|
|
516
|
-
searchable: ['title', 'body'], // ?search= OR'd LIKE allowlist
|
|
517
|
-
filterable: ['status', 'priority'], // ?<col>= allowlist
|
|
518
|
-
},
|
|
519
|
-
views: {
|
|
520
|
-
summary: {
|
|
521
|
-
fields: ['id', 'title', 'status'],
|
|
522
|
-
access: { roles: ['member+'] },
|
|
523
|
-
query: { sortable: ['title'] }, // per-view overrides allowed
|
|
524
|
-
},
|
|
525
|
-
full: {
|
|
526
|
-
fields: ['id', 'title', 'status', 'body', 'internalNotes'],
|
|
527
|
-
access: { roles: ['admin+'] },
|
|
528
|
-
},
|
|
529
|
-
},
|
|
530
|
-
},
|
|
531
|
-
crud: {
|
|
532
|
-
create: { access: { roles: ['admin+'] } },
|
|
533
|
-
update: {
|
|
534
|
-
access: {
|
|
535
|
-
or: [
|
|
536
|
-
{ roles: ['admin+'] },
|
|
537
|
-
{ record: { createdBy: { equals: '$ctx.userId' } } },
|
|
538
|
-
],
|
|
539
|
-
},
|
|
540
|
-
},
|
|
541
|
-
delete: { access: { roles: ['owner'] } },
|
|
542
|
-
}
|
|
543
|
-
```
|
|
544
|
-
|
|
545
|
-
**Generated read endpoints:**
|
|
546
|
-
- `GET /api/v1/{resource}` — gated by `read.access`
|
|
547
|
-
- `GET /api/v1/{resource}/:id` — gated by `read.access` (single-record GET inherits)
|
|
548
|
-
- `GET /api/v1/{resource}?view=summary` — view dispatch under `?view=`
|
|
549
|
-
- `GET /api/v1/{resource}/views/summary` — explicit view path
|
|
550
|
-
|
|
551
|
-
> **DSL v2 migration:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`. A bare `crud: { list: {} }` becomes `read: {}`.
|
|
552
|
-
|
|
553
|
-
**Role hierarchy**: Configure `auth.roleHierarchy` in your config (e.g., `['member', 'admin', 'owner']`) and use the `+` suffix to mean "this role and above". `"member+"` expands to `["member", "admin", "owner"]` at compile time. Roles without `+` are exact matches.
|
|
554
|
-
|
|
555
|
-
Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
|
|
556
|
-
|
|
557
|
-
Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
|
|
558
|
-
|
|
559
|
-
**Special role `PUBLIC`**: Use `roles: ["PUBLIC"]` for unauthenticated access (contact forms, webhooks). Every PUBLIC invocation is mandatory audit logged. The wildcard `"*"` is not supported and will fail at compile time.
|
|
560
|
-
|
|
561
|
-
### 3. Guards — Field Protection
|
|
562
|
-
|
|
563
|
-
```typescript
|
|
564
|
-
guards: {
|
|
565
|
-
createable: ['name', 'description'], // Allowed on POST
|
|
566
|
-
updatable: ['description'], // Allowed on PATCH
|
|
567
|
-
immutable: ['invoiceNumber'], // Set once, never change
|
|
568
|
-
protected: { status: ['approve'] }, // Only via named actions
|
|
569
|
-
}
|
|
570
|
-
```
|
|
571
|
-
|
|
572
|
-
System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
|
|
573
|
-
|
|
574
|
-
PUT/Upsert requires both `generateId: false` and `guards: false`.
|
|
575
|
-
|
|
576
|
-
### 4. Masking — PII Redaction
|
|
577
|
-
|
|
578
|
-
```typescript
|
|
579
|
-
masking: {
|
|
580
|
-
ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
|
|
581
|
-
email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
|
|
582
|
-
}
|
|
583
|
-
```
|
|
584
|
-
|
|
585
|
-
Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
|
|
586
|
-
|
|
587
|
-
Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
|
|
588
|
-
|
|
589
|
-
**Search/filter gating.** Masked columns are dropped from `?search` by default — letting an unauthorized caller substring-search a masked SSN trivially leaks digit positions. To re-enable search on a masked column for callers who *can* see it unmasked, list it under a view's `read.query.searchable`. The compiler validates the intersection at compile time.
|
|
590
|
-
|
|
591
|
-
---
|
|
592
|
-
|
|
593
|
-
## Views — Column-Level Security
|
|
594
|
-
|
|
595
|
-
Named projections that control which fields are visible based on role.
|
|
596
|
-
|
|
597
|
-
```typescript
|
|
598
|
-
views: {
|
|
599
|
-
summary: {
|
|
600
|
-
fields: ['id', 'name', 'email'],
|
|
601
|
-
access: { roles: ['member', 'admin'] },
|
|
602
|
-
},
|
|
603
|
-
full: {
|
|
604
|
-
fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
|
|
605
|
-
access: { roles: ['admin'] },
|
|
606
|
-
},
|
|
607
|
-
}
|
|
608
|
-
```
|
|
609
|
-
|
|
610
|
-
Generated endpoints: `GET /api/v1/{resource}/views/{viewName}`
|
|
611
|
-
|
|
612
|
-
---
|
|
613
|
-
|
|
614
|
-
## Validation
|
|
615
|
-
|
|
616
|
-
```typescript
|
|
617
|
-
validation: {
|
|
618
|
-
name: { minLength: 1, maxLength: 100 },
|
|
619
|
-
capacity: { min: 1, max: 1000 },
|
|
620
|
-
roomType: { enum: ['meeting', 'conference', 'breakout'] },
|
|
621
|
-
email: { email: true },
|
|
622
|
-
code: { pattern: '^[A-Z]{3}$' },
|
|
623
|
-
}
|
|
624
|
-
```
|
|
625
|
-
|
|
626
|
-
---
|
|
627
|
-
|
|
628
|
-
## CMS Record Layouts
|
|
629
|
-
|
|
630
|
-
Control how fields are grouped on the CMS record detail page.
|
|
631
|
-
|
|
632
|
-
```typescript
|
|
633
|
-
layouts: {
|
|
634
|
-
default: {
|
|
635
|
-
sections: [
|
|
636
|
-
{ label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
|
|
637
|
-
{ label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
|
|
638
|
-
],
|
|
639
|
-
},
|
|
640
|
-
}
|
|
641
|
-
```
|
|
642
|
-
|
|
643
|
-
Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
|
|
644
|
-
|
|
645
|
-
---
|
|
646
|
-
|
|
647
|
-
## Account UI — Authentication & Account Management
|
|
648
|
-
|
|
649
|
-
A complete pre-built SPA for login, signup, profile, organizations, and admin. Built from source at compile time (inside Docker) with your config baked in.
|
|
650
|
-
|
|
651
|
-
### What's Included
|
|
652
|
-
|
|
653
|
-
| Section | Pages |
|
|
654
|
-
|---------|-------|
|
|
655
|
-
| **Auth** | Login, signup, email OTP, forgot password, email verification |
|
|
656
|
-
| **Account** | Profile, devices/sessions, passkeys, account deletion |
|
|
657
|
-
| **Organizations** | Dashboard, org creation, member management, invitations, API keys, org settings |
|
|
658
|
-
| **Admin** | User management (search, create, ban/unban, reset passwords, view sessions) |
|
|
659
|
-
| **CLI** | Device authorization flow for `quickback login` |
|
|
660
|
-
|
|
661
|
-
### Enabling
|
|
662
|
-
|
|
663
|
-
```typescript
|
|
664
|
-
// Minimal
|
|
665
|
-
account: true
|
|
666
|
-
|
|
667
|
-
// Full config
|
|
668
|
-
account: {
|
|
669
|
-
domain: "auth.example.com",
|
|
670
|
-
adminDomain: "admin.example.com",
|
|
671
|
-
name: "My App",
|
|
672
|
-
companyName: "My Company",
|
|
673
|
-
tagline: "Build faster, ship sooner",
|
|
674
|
-
auth: {
|
|
675
|
-
password: true, // Email/password (default: false)
|
|
676
|
-
emailOTP: true, // Email OTP (default: true)
|
|
677
|
-
passkey: true, // WebAuthn passkeys (default: true)
|
|
678
|
-
signup: true, // Registration (default: true)
|
|
679
|
-
organizations: true, // Multi-tenant orgs (default: true)
|
|
680
|
-
admin: true, // Admin panel (default: true)
|
|
681
|
-
emailVerification: true, // Require email verification (default: true)
|
|
682
|
-
},
|
|
683
|
-
}
|
|
684
|
-
```
|
|
685
|
-
|
|
686
|
-
### Compile-Time Feature Gating
|
|
687
|
-
|
|
688
|
-
Disabled features are **removed before the Vite build** — route files are excluded from source, so they never appear in the JavaScript bundle. Not runtime checks.
|
|
689
|
-
|
|
690
|
-
### Routing
|
|
691
|
-
|
|
692
|
-
- **Unified domain (default):** Served at `/account/` alongside CMS at `/cms/` and API at `/api/`
|
|
693
|
-
- **Custom domain:** Served at root `/` on `auth.example.com`
|
|
694
|
-
- **Admin domain:** Admin routes served at root `/` on `admin.example.com`
|
|
695
|
-
- Cross-subdomain auth cookies auto-configured when multiple custom domains detected
|
|
696
|
-
|
|
697
|
-
### Skip Rebuild
|
|
698
|
-
|
|
699
|
-
```typescript
|
|
700
|
-
account: { build: false, /* ...other options */ }
|
|
701
|
-
```
|
|
702
|
-
|
|
703
|
-
Skips the SPA build on subsequent compiles — useful when iterating on API features only.
|
|
704
|
-
|
|
705
|
-
### Standalone & Library Usage
|
|
706
|
-
|
|
707
|
-
Account UI also works outside the compiler:
|
|
708
|
-
- **Template:** Clone repo, configure `.env`, deploy as separate Worker
|
|
709
|
-
- **Library:** `npm install quickback-better-auth-account-ui` and import as React component
|
|
710
|
-
|
|
711
|
-
Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
|
|
712
|
-
|
|
713
|
-
---
|
|
714
|
-
|
|
715
|
-
## Actions — Custom Business Logic
|
|
716
|
-
|
|
717
|
-
Defined with `defineAction()` (singular). Per-action permissions live under `access:` (same shape as resource-level access).
|
|
718
|
-
|
|
719
|
-
**One file per action.** Each action is its own module under the feature's `actions/` directory:
|
|
720
|
-
|
|
721
|
-
- `actions/<name>.ts` — binds to the feature's primary table (the `<feature>.ts` file at the feature root). If `path:` is set, becomes a standalone action.
|
|
722
|
-
- `actions/<table>/<name>.ts` — binds to the sibling table file `<table>.ts` at the feature root. Use this in multi-table features.
|
|
723
|
-
|
|
724
|
-
The action's filename (sans `.ts`) is the action name AND the URL segment. Uniqueness is enforced per **`(bound table, name)` pair** — sibling-bound actions on different tables may share a verb (e.g. `actions/episodes/publish.ts` + `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish`). The compiler errors only when two action files would mount at the same URL.
|
|
725
|
-
|
|
726
|
-
For shared Zod schemas or helpers, put them under `<feature>/lib/` and import from each action file.
|
|
727
|
-
|
|
728
|
-
**Retired layouts** (rejected at load time with migration guidance): `actions.ts` (bundle), `_feature.ts`, `handlers/` directory, `defineActions(table, {...})`, `defineActions(null, {...})`, `*-actions.ts` / `*.actions.ts` filenames.
|
|
729
|
-
|
|
730
|
-
`execute:` must be an **async arrow function** (`async (ctx) => { … }`). `async function` declarations and non-async forms are rejected at parse time.
|
|
731
|
-
|
|
732
|
-
```typescript
|
|
733
|
-
// features/todos/actions/complete.ts
|
|
118
|
+
```ts
|
|
119
|
+
// quickback/features/todos/actions/complete.ts
|
|
734
120
|
import { z } from "zod";
|
|
735
121
|
import { defineAction } from "../.quickback/define-action";
|
|
736
|
-
import
|
|
737
|
-
import todos from "../todos"; // default import: feature() exports
|
|
738
|
-
// import { todos } from "../todos"; // named import: two-export form
|
|
122
|
+
import todos from "../todos";
|
|
739
123
|
|
|
740
124
|
export default defineAction({
|
|
741
125
|
description: "Mark todo as complete",
|
|
742
|
-
input: z.object({
|
|
743
|
-
access: {
|
|
744
|
-
|
|
126
|
+
input: z.object({}),
|
|
127
|
+
access: {
|
|
128
|
+
roles: ["member", "admin"],
|
|
129
|
+
record: { completed: { equals: false } },
|
|
130
|
+
},
|
|
745
131
|
async execute({ db, record, whereRecord, auditFields }) {
|
|
746
132
|
await db.update(todos)
|
|
747
133
|
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
748
|
-
.where(whereRecord!(todos));
|
|
134
|
+
.where(whereRecord!(todos));
|
|
749
135
|
return { success: true };
|
|
750
136
|
},
|
|
751
137
|
});
|
|
752
138
|
```
|
|
753
139
|
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
Action options: `path`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`, `cms`.
|
|
758
|
-
|
|
759
|
-
### `whereRecord(table)` — explicit, scope-safe WHERE
|
|
760
|
-
|
|
761
|
-
In record-based actions, `whereRecord(table)` returns a Drizzle expression that AND-merges the resource's firewall + soft-delete + `eq(table.id, record.id)`. Use it for protected-field writes — even if a future refactor swaps `db` for an unscoped client, the WHERE stays explicit. `whereRecord` is `undefined` for standalone actions.
|
|
762
|
-
|
|
763
|
-
### `transition` — state-machine policy on protected fields
|
|
764
|
-
|
|
765
|
-
For protected fields that follow a state machine (status, lifecycle, fulfilment), enforce the *from/to pair*, not just the current state. Without `transition`, an `advance` action whose access allows `status in ['applied', 'screening']` will happily run `applied → offer` (a skip) or `screening → applied` (a regression).
|
|
766
|
-
|
|
767
|
-
```typescript
|
|
768
|
-
// features/applications/actions/advance.ts
|
|
769
|
-
import { z } from "zod";
|
|
770
|
-
import { defineAction } from "../.quickback/define-action";
|
|
771
|
-
import { applications } from "../applications";
|
|
772
|
-
|
|
773
|
-
export default defineAction({
|
|
774
|
-
description: "Move application forward",
|
|
775
|
-
input: z.object({ nextStatus: z.enum(['screening', 'interview', 'offer']) }),
|
|
776
|
-
access: { roles: ['owner', 'admin'] },
|
|
777
|
-
transition: {
|
|
778
|
-
field: 'status',
|
|
779
|
-
via: 'nextStatus', // read target from input.nextStatus
|
|
780
|
-
fromTo: {
|
|
781
|
-
applied: ['screening'],
|
|
782
|
-
screening: ['interview'],
|
|
783
|
-
interview: ['offer'],
|
|
784
|
-
},
|
|
785
|
-
},
|
|
786
|
-
async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },
|
|
787
|
-
});
|
|
788
|
-
```
|
|
789
|
-
|
|
790
|
-
```typescript
|
|
791
|
-
// features/applications/actions/hire.ts
|
|
792
|
-
import { z } from "zod";
|
|
793
|
-
import { defineAction } from "../.quickback/define-action";
|
|
794
|
-
import { applications } from "../applications";
|
|
795
|
-
|
|
796
|
-
export default defineAction({
|
|
797
|
-
description: "Finalize an offer",
|
|
798
|
-
input: z.object({}),
|
|
799
|
-
access: { roles: ['owner'] },
|
|
800
|
-
transition: {
|
|
801
|
-
field: 'status',
|
|
802
|
-
to: 'hired', // fixed target — same value every call
|
|
803
|
-
fromTo: { offer: ['hired'] },
|
|
804
|
-
},
|
|
805
|
-
async execute({ db, record, auditFields, whereTransition }) { /* … */ },
|
|
806
|
-
});
|
|
807
|
-
```
|
|
808
|
-
|
|
809
|
-
Exactly one of `via` or `to` must be provided. On a bad transition the runtime returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with `field`, `current`, `target`, `allowedTargets`. The same 409 fires when a plain `access.record` precondition fails (was 403 before — splitting it lets clients tell *"you can't do this"* from *"you can't do this **yet**"*).
|
|
810
|
-
|
|
811
|
-
### `unsafe` — bypass scoped DB filters (object form, with mandatory audit)
|
|
812
|
-
|
|
813
|
-
For platform-level support / cross-tenant operations, opt out of the scoped DB. The object form is required for new code — it makes the policy explicit and forces an audit reason:
|
|
814
|
-
|
|
815
|
-
```typescript
|
|
816
|
-
// features/admin/actions/admin-report.ts
|
|
817
|
-
import { z } from "zod";
|
|
818
|
-
import { defineAction } from "../.quickback/define-action";
|
|
819
|
-
import { applications } from "../../applications/applications";
|
|
820
|
-
|
|
821
|
-
export default defineAction({
|
|
822
|
-
description: "Cross-org hiring report",
|
|
823
|
-
path: "/admin/cross-org-report",
|
|
824
|
-
input: z.object({ startDate: z.string() }),
|
|
825
|
-
access: { roles: ['owner'] },
|
|
826
|
-
unsafe: {
|
|
827
|
-
reason: "Support investigation for enterprise customer",
|
|
828
|
-
adminOnly: true, // default true — gates on ctx.userRole === 'admin'
|
|
829
|
-
crossTenant: true, // default true — bypasses firewall
|
|
830
|
-
targetScope: 'all', // 'all' | 'organization'
|
|
831
|
-
},
|
|
832
|
-
async execute({ db, unsafeDb, ctx, input }) {
|
|
833
|
-
// db is still scoped (safety net for accidental writes)
|
|
834
|
-
// unsafeDb bypasses scoped filters
|
|
835
|
-
return await unsafeDb.select().from(applications);
|
|
836
|
-
},
|
|
837
|
-
});
|
|
838
|
-
```
|
|
839
|
-
|
|
840
|
-
Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`.
|
|
841
|
-
|
|
842
|
-
### Soft-delete cascade (cross-feature)
|
|
843
|
-
|
|
844
|
-
When a parent is soft-deleted, every child table that holds an FK to it — both **same-feature** and **cross-feature** children — receives the same `deletedAt` / `deletedBy` stamp. The cascade UPDATE always AND-merges the child's own firewall, so a delete in one tenant never reaches a child row in another tenant. FKs declared with `onDelete: 'cascade'` or `'set null'` participate; FKs without `onDelete` are cascaded for backwards compat.
|
|
845
|
-
|
|
846
|
-
### Actions-Only Features
|
|
847
|
-
|
|
848
|
-
A feature directory with no top-level `*.ts` files is "tableless" — every action under `actions/` must be standalone (have `path:`). Use this for utility endpoints like webhooks, reports, or integrations.
|
|
849
|
-
|
|
850
|
-
```typescript
|
|
851
|
-
// quickback/features/utilities/actions/health-check.ts
|
|
852
|
-
import { z } from "zod";
|
|
853
|
-
import { defineAction } from "../.quickback/define-action";
|
|
854
|
-
|
|
855
|
-
export default defineAction({
|
|
856
|
-
description: "Health check endpoint",
|
|
857
|
-
path: "/health",
|
|
858
|
-
method: "GET",
|
|
859
|
-
input: z.object({}),
|
|
860
|
-
access: { roles: ["member", "admin"] },
|
|
861
|
-
async execute() {
|
|
862
|
-
return { ok: true };
|
|
863
|
-
},
|
|
864
|
-
});
|
|
865
|
-
```
|
|
140
|
+
For the schema column types: `quickback docs compiler/definitions/schema`.
|
|
141
|
+
For action shapes (record-based vs standalone, transitions, `unsafe:`): `quickback docs compiler/definitions/actions`.
|
|
142
|
+
For Drizzle interop (existing `sqliteTable` schemas): `quickback docs compiler/definitions/feature`.
|
|
866
143
|
|
|
867
144
|
---
|
|
868
145
|
|
|
869
|
-
##
|
|
870
|
-
|
|
871
|
-
### CRUD Operations
|
|
872
|
-
|
|
873
|
-
| Method | Endpoint | Description |
|
|
874
|
-
|--------|----------|-------------|
|
|
875
|
-
| `GET` | `/api/v1/{resource}` | List records |
|
|
876
|
-
| `GET` | `/api/v1/{resource}/:id` | Get single record |
|
|
877
|
-
| `POST` | `/api/v1/{resource}` | Create record |
|
|
878
|
-
| `PATCH` | `/api/v1/{resource}/:id` | Update record |
|
|
879
|
-
| `DELETE` | `/api/v1/{resource}/:id` | Delete record |
|
|
880
|
-
| `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
|
|
881
|
-
|
|
882
|
-
### Batch Operations
|
|
146
|
+
## Defaults the compiler applies
|
|
883
147
|
|
|
884
|
-
|
|
148
|
+
Before flagging "missing X", check whether a default already covers it:
|
|
885
149
|
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
| Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
|
|
893
|
-
| Fields | `?fields=id,name,status` |
|
|
894
|
-
| Total count | `?total=true` |
|
|
895
|
-
| Search | `?search=conference` (OR'd LIKE across text columns) |
|
|
896
|
-
|
|
897
|
-
Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
|
|
898
|
-
|
|
899
|
-
### Response Format
|
|
900
|
-
|
|
901
|
-
```json
|
|
902
|
-
{
|
|
903
|
-
"data": [{ "id": "...", "title": "Todo 1" }],
|
|
904
|
-
"pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
|
|
905
|
-
}
|
|
906
|
-
```
|
|
907
|
-
|
|
908
|
-
### Error Responses
|
|
909
|
-
|
|
910
|
-
| Status | Layer | Meaning |
|
|
911
|
-
|--------|-------|---------|
|
|
912
|
-
| `401` | Auth | Invalid/expired session |
|
|
913
|
-
| `403` | Access | Insufficient permissions |
|
|
914
|
-
| `404` | Firewall | Record not found or outside scope |
|
|
915
|
-
| `400` | Guards | Invalid field modification |
|
|
916
|
-
|
|
917
|
-
---
|
|
918
|
-
|
|
919
|
-
## Database Dialects
|
|
920
|
-
|
|
921
|
-
| Stack | Import | Table Function |
|
|
922
|
-
|-------|--------|----------------|
|
|
923
|
-
| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
|
|
924
|
-
| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
|
|
925
|
-
| MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
|
|
150
|
+
- **Soft-delete is the default.** `deletedAt` / `deletedBy` are auto-injected at the SQL layer; firewall auto-AND-merges `deletedAt IS NULL`. Opt out with `crud.delete.mode: 'hard'`.
|
|
151
|
+
- **Audit fields auto-injected.** `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` — never declare them in user code. The audit-wrapper auto-populates `createdBy` / `modifiedBy` from `ctx.userId`.
|
|
152
|
+
- **Sensitive columns auto-masked.** `email`, `phone`, `ssn`, `password`, `creditCard`, etc. get `show: { or: 'owner', roles: ['admin'] }` by default; falls back to `roles: ['admin']` only when there's no `ownerId` column. Absence of a `masking:` block does NOT mean plain-text — it means the compiler-default is in effect. Declare `masking:` only to override.
|
|
153
|
+
- **Firewall auto-derived** for tables with a single isolation column (e.g., `organizationId` only).
|
|
154
|
+
- **Soft-delete cascade** reaches cross-feature children with each child's own firewall AND-merged.
|
|
155
|
+
- **Reserved keys in `access.record`.** `and`, `or`, `roles`, `userRole` are rejected inside `record:` at compile time — those go on the parent access node.
|
|
926
156
|
|
|
927
157
|
---
|
|
928
158
|
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
The Quickback Stack is a production-ready backend platform built entirely on Cloudflare's edge infrastructure. It's a Supabase alternative where everything runs on your own Cloudflare account — your data, your infrastructure, global edge performance.
|
|
932
|
-
|
|
933
|
-
```
|
|
934
|
-
┌─────────────────────────────────────────────────────────┐
|
|
935
|
-
│ QUICKBACK STACK ON CLOUDFLARE │
|
|
936
|
-
│ │
|
|
937
|
-
│ Workers — API runtime (Hono) │
|
|
938
|
-
│ D1 — SQLite database at the edge │
|
|
939
|
-
│ R2 — S3-compatible file storage │
|
|
940
|
-
│ KV — Distributed key-value store │
|
|
941
|
-
│ Durable Objects — Realtime WebSockets │
|
|
942
|
-
│ Queues — Background job processing │
|
|
943
|
-
│ Workers AI — Embeddings & vector search │
|
|
944
|
-
│ Better Auth — Authentication & organizations │
|
|
945
|
-
└─────────────────────────────────────────────────────────┘
|
|
946
|
-
```
|
|
947
|
-
|
|
948
|
-
## Authentication (Better Auth)
|
|
949
|
-
|
|
950
|
-
Built on Better Auth with multi-tenant organization support.
|
|
951
|
-
|
|
952
|
-
- Email/password, magic links, passkeys, email OTP
|
|
953
|
-
- Three org roles: `owner`, `admin`, `member`
|
|
954
|
-
- Session storage in KV namespace
|
|
955
|
-
- All auth routes at `/auth/v1/*`
|
|
956
|
-
- Extensible via Better Auth plugins
|
|
957
|
-
- **JWT fast-path** — authenticated API requests validate via HMAC-SHA256 JWT (0 DB queries). Tokens mint and rotate automatically; session cookies are the source of truth. Separate from Better Auth's `jwt` plugin (opt-in, for JWKS/external identity). See `quickback docs stack/auth/jwt-optimization`
|
|
958
|
-
- **Account UI** — pre-built SPA for login, signup, profile, orgs, admin (see Account UI section above)
|
|
159
|
+
## The scoped DB — what it does and doesn't do
|
|
959
160
|
|
|
960
|
-
|
|
961
|
-
// Config
|
|
962
|
-
providers: {
|
|
963
|
-
auth: defineAuth("better-auth"),
|
|
964
|
-
}
|
|
965
|
-
```
|
|
966
|
-
|
|
967
|
-
Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
|
|
161
|
+
The action context's `db` is a Drizzle wrapper that:
|
|
968
162
|
|
|
969
|
-
|
|
163
|
+
- **Does** auto-AND the resource's firewall WHERE clause into every `select` / `update` / `delete`.
|
|
164
|
+
- **Does** route soft-delete `delete()` calls to a `deletedAt` / `deletedBy` UPDATE.
|
|
165
|
+
- **Does NOT** auto-populate insert values. `db.insert(table).values({...})` writes whatever you pass — pass `organizationId` (and any other isolation columns) explicitly. Audit fields ARE auto-populated; tenant-scope columns are not.
|
|
970
166
|
|
|
971
|
-
|
|
167
|
+
For unscoped writes (cross-tenant support, platform admin), use the `unsafe:` object form on the action — it forces an audit reason and gates on platform admin role.
|
|
972
168
|
|
|
973
|
-
|
|
974
|
-
|---------|---------|
|
|
975
|
-
| `DB` | Application data (features) |
|
|
976
|
-
| `AUTH_DB` | Auth sessions & users |
|
|
977
|
-
| `FILES_DB` | File metadata |
|
|
978
|
-
| `WEBHOOKS_DB` | Webhook tracking |
|
|
169
|
+
---
|
|
979
170
|
|
|
980
|
-
|
|
981
|
-
- Auto-generated migrations on compile
|
|
982
|
-
- Application-layer security (firewall, access, guards, masking)
|
|
983
|
-
- Local dev with `.wrangler/state/`
|
|
984
|
-
- Neon Postgres available as alternative
|
|
171
|
+
## Quickback CLI (commands the user runs)
|
|
985
172
|
|
|
986
|
-
```
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
}),
|
|
991
|
-
}
|
|
173
|
+
```bash
|
|
174
|
+
quickback compile # compile project (prompts to log in if not authenticated)
|
|
175
|
+
quickback create <template> # new project from template
|
|
176
|
+
quickback login # authenticate via browser device flow
|
|
992
177
|
```
|
|
993
178
|
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
## File Storage (R2)
|
|
997
|
-
|
|
998
|
-
S3-compatible object storage with built-in access control.
|
|
999
|
-
|
|
1000
|
-
- Two-worker architecture: API worker (upload/manage) + Files worker (serve)
|
|
1001
|
-
- Bucket-scoped access policies (public, organization, user)
|
|
1002
|
-
- File metadata tracked in `FILES_DB`
|
|
1003
|
-
- Soft deletes with org-level tenant isolation
|
|
1004
|
-
- API at `/storage/v1/*`
|
|
1005
|
-
|
|
1006
|
-
Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
|
|
1007
|
-
|
|
1008
|
-
## KV Storage
|
|
1009
|
-
|
|
1010
|
-
Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
|
|
1011
|
-
|
|
1012
|
-
- Use cases: sessions, caching, rate limiting, feature flags
|
|
1013
|
-
- Eventually consistent (60 second propagation)
|
|
1014
|
-
- TTL/expiration support
|
|
1015
|
-
|
|
1016
|
-
Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
|
|
1017
|
-
|
|
1018
|
-
## Realtime (Durable Objects)
|
|
1019
|
-
|
|
1020
|
-
WebSocket connections for live updates via organization-scoped Durable Objects.
|
|
1021
|
-
|
|
1022
|
-
- CRUD event broadcasting (insert, update, delete)
|
|
1023
|
-
- Custom broadcasts and event namespaces
|
|
1024
|
-
- Role-based filtering and per-role field masking
|
|
1025
|
-
- Session token or API key authentication
|
|
1026
|
-
- Type-safe with `defineRealtime()` for custom events
|
|
1027
|
-
- Endpoint: `/realtime/v1/websocket`
|
|
1028
|
-
|
|
1029
|
-
Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
|
|
1030
|
-
|
|
1031
|
-
## Queues (Background Processing)
|
|
1032
|
-
|
|
1033
|
-
Cloudflare Queues for reliable async job processing.
|
|
179
|
+
The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
|
|
1034
180
|
|
|
1035
|
-
|
|
1036
|
-
|-------|---------|
|
|
1037
|
-
| `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
|
|
1038
|
-
| `WEBHOOKS_QUEUE` | Webhook delivery |
|
|
1039
|
-
| Custom queues | Your background jobs |
|
|
181
|
+
This skill does not have shell access — surface CLI commands to the user as instructions, don't try to run them.
|
|
1040
182
|
|
|
1041
|
-
|
|
1042
|
-
- Auto-retry up to 3 times, max batch 10, 30s timeout
|
|
1043
|
-
- Chaining between queues
|
|
1044
|
-
|
|
1045
|
-
Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
|
|
1046
|
-
|
|
1047
|
-
## Vector & Embeddings (Workers AI)
|
|
1048
|
-
|
|
1049
|
-
Auto-generated embeddings for similarity search and classification.
|
|
1050
|
-
|
|
1051
|
-
- Table-level config via `embeddings` in `defineTable()`
|
|
1052
|
-
- Service-level config via `defineEmbedding()`
|
|
1053
|
-
- Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
|
|
1054
|
-
- Async processing via `EMBEDDINGS_QUEUE`
|
|
1055
|
-
- Vector storage in D1 + optional Vectorize index
|
|
1056
|
-
- API: `/api/v1/embeddings`
|
|
1057
|
-
|
|
1058
|
-
Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
|
|
1059
|
-
|
|
1060
|
-
## Webhooks
|
|
1061
|
-
|
|
1062
|
-
### Inbound (Receiving)
|
|
183
|
+
---
|
|
1063
184
|
|
|
1064
|
-
|
|
185
|
+
## Looking up details
|
|
1065
186
|
|
|
1066
|
-
|
|
1067
|
-
import { onWebhookEvent } from './lib/webhooks';
|
|
187
|
+
The full documentation is bundled alongside this `SKILL.md` as plain markdown files. To pull reference material on demand:
|
|
1068
188
|
|
|
1069
|
-
onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
|
|
1070
|
-
const { data, env } = ctx;
|
|
1071
|
-
await createSubscription({ ... });
|
|
1072
|
-
});
|
|
1073
189
|
```
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
|
|
1078
|
-
|
|
1079
|
-
```typescript
|
|
1080
|
-
import { emitWebhookEvent } from './lib/webhooks';
|
|
1081
|
-
|
|
1082
|
-
await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
|
|
190
|
+
Glob: docs/**/*.md # discover topics
|
|
191
|
+
Read: docs/compiler/definitions/firewall.md
|
|
192
|
+
Grep: "deletedAt" docs/ # search across the whole docs tree
|
|
1083
193
|
```
|
|
1084
194
|
|
|
1085
|
-
|
|
1086
|
-
Endpoint management: `/webhooks/v1/endpoints`
|
|
1087
|
-
|
|
1088
|
-
Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
|
|
1089
|
-
|
|
1090
|
-
---
|
|
1091
|
-
|
|
1092
|
-
# CLI Commands
|
|
195
|
+
The path layout mirrors the public docs site (https://docs.quickback.dev). Open any topic file for the authoritative reference; the skill body above is intentionally just orientation.
|
|
1093
196
|
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
197
|
+
**Compiler — definitions** (`docs/compiler/definitions/<topic>.md`)
|
|
198
|
+
- `schema` — column types, `q.text/int/bool/uuid/timestamp/json/scope/...`, FKs, indexes
|
|
199
|
+
- `feature` — `feature()` shape, `q.scope()`, soft delete, audit fields
|
|
200
|
+
- `firewall` — predicates, scope detection, exceptions
|
|
201
|
+
- `access` — roles, record predicates, role hierarchy, `PUBLIC`, pseudo-roles
|
|
202
|
+
- `guards` — createable / updatable / immutable / protected
|
|
203
|
+
- `masking` — types, `show:`, search/filter gating, auto-detection
|
|
204
|
+
- `read` — `read.access`, `read.views`, `read.query`, pagination + filtering
|
|
205
|
+
- `views` — named projections with column-level access
|
|
206
|
+
- `actions` — record-based vs standalone, transitions, `unsafe:`, `whereRecord(table)`
|
|
207
|
+
- `validation` — minLength, max, enum, pattern, email
|
|
208
|
+
- `concepts` — secure-by-default, defense in depth, request flow
|
|
1104
209
|
|
|
1105
|
-
|
|
210
|
+
**Compiler — config** (`docs/compiler/config/<topic>.md`)
|
|
211
|
+
- `providers` — runtime / database / auth provider selection
|
|
212
|
+
- `variables` — env vars, secrets
|
|
213
|
+
- `bindings` — extra Cloudflare bindings (queues, R2, etc.)
|
|
214
|
+
- `output` — `build.outputDir`, custom dependencies
|
|
215
|
+
- `domains` — multi-domain hostname routing (CMS / account / admin)
|
|
216
|
+
- `spa` — single-worker SPA mount (your product app at the apex)
|
|
217
|
+
- `single-tenant` — disable organizations
|
|
218
|
+
- `agents` — robots.txt, llms.txt, MCP, OAuth discovery
|
|
1106
219
|
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
220
|
+
**Stack — runtime services** (`docs/stack/<topic>.md`)
|
|
221
|
+
- `auth` — Better Auth integration, JWT optimization, plugins, device-auth, security
|
|
222
|
+
- `storage/{kv,r2}` — using KV and R2 in actions
|
|
223
|
+
- `realtime` — Durable Objects, WebSocket
|
|
224
|
+
- `queues` — handlers, retries, dead-letter
|
|
225
|
+
- `vector/embeddings` — auto-embedding columns, semantic search
|
|
226
|
+
- `webhooks/{inbound,outbound}` — signed inbound, retried outbound
|
|
227
|
+
- `cms` — schema-driven admin UI, dashboard, record layouts, table views, schema registry
|
|
228
|
+
- `account-ui` — login, profile, orgs, admin, passkeys, API keys, CLI authorize, with Quickback or standalone
|
|
1112
229
|
|
|
1113
|
-
|
|
230
|
+
**Getting started** (`docs/compiler/getting-started/<topic>.md`)
|
|
231
|
+
- `templates` — full template list
|
|
232
|
+
- `template-cloudflare` — recommended starting point
|
|
233
|
+
- `full-example` — top-to-bottom walkthrough
|
|
234
|
+
- `hand-crafted` — building from `template-empty`
|
|
235
|
+
- `patterns` — common multi-tenant / hierarchical / public patterns
|
|
1114
236
|
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
```
|
|
1121
|
-
|
|
1122
|
-
---
|
|
237
|
+
**Cloud / CLI** (`docs/compiler/cloud-compiler/<topic>.md`)
|
|
238
|
+
- `cli` — full CLI reference
|
|
239
|
+
- `authentication` — login flow, API keys, sessions
|
|
240
|
+
- `endpoints` — POST /compile, GET /templates, GET /health
|
|
241
|
+
- `local-compiler` — running the compiler locally in Docker
|
|
1123
242
|
|
|
1124
|
-
|
|
243
|
+
**Other** — `docs/changelog.md`, `docs/compiler/claude-code-skill.md`
|
|
1125
244
|
|
|
1126
|
-
|
|
1127
|
-
- [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
|
|
1128
|
-
- [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
|
|
1129
|
-
- [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
|
|
1130
|
-
- [Access](https://docs.quickback.dev/compiler/definitions/access)
|
|
1131
|
-
- [Guards](https://docs.quickback.dev/compiler/definitions/guards)
|
|
1132
|
-
- [Masking](https://docs.quickback.dev/compiler/definitions/masking)
|
|
1133
|
-
- [Views](https://docs.quickback.dev/compiler/definitions/views)
|
|
1134
|
-
- [Actions](https://docs.quickback.dev/compiler/definitions/actions)
|
|
1135
|
-
- [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
|
|
1136
|
-
- [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
|
|
1137
|
-
- [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
|
|
1138
|
-
- [Stack Overview](https://docs.quickback.dev/stack)
|
|
1139
|
-
- [D1 Database](https://docs.quickback.dev/stack/database/d1)
|
|
1140
|
-
- [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
|
|
1141
|
-
- [Realtime](https://docs.quickback.dev/stack/realtime)
|
|
1142
|
-
- [Queues](https://docs.quickback.dev/stack/queues)
|
|
1143
|
-
- [Embeddings](https://docs.quickback.dev/stack/vector)
|
|
1144
|
-
- [Webhooks](https://docs.quickback.dev/stack/webhooks)
|
|
1145
|
-
- [Account UI Overview](https://docs.quickback.dev/account-ui)
|
|
1146
|
-
- [Account UI with Quickback](https://docs.quickback.dev/account-ui/with-quickback)
|
|
1147
|
-
- [Account UI Standalone](https://docs.quickback.dev/account-ui/standalone)
|
|
1148
|
-
- [Account UI Features](https://docs.quickback.dev/account-ui/features)
|
|
1149
|
-
- [Account UI Environment Variables](https://docs.quickback.dev/account-ui/environment-variables)
|
|
1150
|
-
- [Account UI Customization](https://docs.quickback.dev/account-ui/customization)
|
|
1151
|
-
- [CMS Overview](https://docs.quickback.dev/cms)
|
|
1152
|
-
- [CMS Dashboard](https://docs.quickback.dev/cms/dashboard)
|
|
1153
|
-
- [CMS Custom Pages](https://docs.quickback.dev/cms/pages)
|
|
1154
|
-
- [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)
|
|
245
|
+
For online navigation: <https://docs.quickback.dev>.
|