@quickback-dev/cli 0.9.5
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/README.md +7 -0
- package/dist/commands/claude.d.ts +13 -0
- package/dist/commands/claude.d.ts.map +1 -0
- package/dist/commands/claude.js +305 -0
- package/dist/commands/claude.js.map +1 -0
- package/dist/commands/compile.d.ts +18 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/compile.js +326 -0
- package/dist/commands/compile.js.map +1 -0
- package/dist/commands/create.d.ts +18 -0
- package/dist/commands/create.d.ts.map +1 -0
- package/dist/commands/create.js +798 -0
- package/dist/commands/create.js.map +1 -0
- package/dist/commands/cursor.d.ts +11 -0
- package/dist/commands/cursor.d.ts.map +1 -0
- package/dist/commands/cursor.js +156 -0
- package/dist/commands/cursor.js.map +1 -0
- package/dist/commands/docs.d.ts +10 -0
- package/dist/commands/docs.d.ts.map +1 -0
- package/dist/commands/docs.js +93 -0
- package/dist/commands/docs.js.map +1 -0
- package/dist/commands/example.d.ts +7 -0
- package/dist/commands/example.d.ts.map +1 -0
- package/dist/commands/example.js +153 -0
- package/dist/commands/example.js.map +1 -0
- package/dist/commands/init.d.ts +6 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +383 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/login.d.ts +16 -0
- package/dist/commands/login.d.ts.map +1 -0
- package/dist/commands/login.js +287 -0
- package/dist/commands/login.js.map +1 -0
- package/dist/commands/logout.d.ts +7 -0
- package/dist/commands/logout.d.ts.map +1 -0
- package/dist/commands/logout.js +19 -0
- package/dist/commands/logout.js.map +1 -0
- package/dist/commands/mcp.d.ts +21 -0
- package/dist/commands/mcp.d.ts.map +1 -0
- package/dist/commands/mcp.js +331 -0
- package/dist/commands/mcp.js.map +1 -0
- package/dist/commands/whoami.d.ts +7 -0
- package/dist/commands/whoami.d.ts.map +1 -0
- package/dist/commands/whoami.js +37 -0
- package/dist/commands/whoami.js.map +1 -0
- package/dist/cursor/quickback.mdc +277 -0
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +577 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/examples/recruitment.tar.gz +0 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +188 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/api-client.d.ts +103 -0
- package/dist/lib/api-client.d.ts.map +1 -0
- package/dist/lib/api-client.js +231 -0
- package/dist/lib/api-client.js.map +1 -0
- package/dist/lib/api-client.test.d.ts +2 -0
- package/dist/lib/api-client.test.d.ts.map +1 -0
- package/dist/lib/api-client.test.js +133 -0
- package/dist/lib/api-client.test.js.map +1 -0
- package/dist/lib/artifact-routing.d.ts +8 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -0
- package/dist/lib/artifact-routing.js +34 -0
- package/dist/lib/artifact-routing.js.map +1 -0
- package/dist/lib/artifact-routing.test.d.ts +2 -0
- package/dist/lib/artifact-routing.test.d.ts.map +1 -0
- package/dist/lib/artifact-routing.test.js +37 -0
- package/dist/lib/artifact-routing.test.js.map +1 -0
- package/dist/lib/async-utils.d.ts +6 -0
- package/dist/lib/async-utils.d.ts.map +1 -0
- package/dist/lib/async-utils.js +26 -0
- package/dist/lib/async-utils.js.map +1 -0
- package/dist/lib/auth.d.ts +55 -0
- package/dist/lib/auth.d.ts.map +1 -0
- package/dist/lib/auth.js +102 -0
- package/dist/lib/auth.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +108 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -0
- package/dist/lib/compiler-stubs.js +142 -0
- package/dist/lib/compiler-stubs.js.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts +2 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.js +123 -0
- package/dist/lib/drizzle-meta-routing.test.js.map +1 -0
- package/dist/lib/file-loader.d.ts +165 -0
- package/dist/lib/file-loader.d.ts.map +1 -0
- package/dist/lib/file-loader.js +577 -0
- package/dist/lib/file-loader.js.map +1 -0
- package/dist/lib/file-loader.test.d.ts +2 -0
- package/dist/lib/file-loader.test.d.ts.map +1 -0
- package/dist/lib/file-loader.test.js +75 -0
- package/dist/lib/file-loader.test.js.map +1 -0
- package/dist/lib/file-writer.d.ts +30 -0
- package/dist/lib/file-writer.d.ts.map +1 -0
- package/dist/lib/file-writer.js +122 -0
- package/dist/lib/file-writer.js.map +1 -0
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/markdown-renderer.d.ts +8 -0
- package/dist/lib/markdown-renderer.d.ts.map +1 -0
- package/dist/lib/markdown-renderer.js +151 -0
- package/dist/lib/markdown-renderer.js.map +1 -0
- package/dist/lib/shell.d.ts +15 -0
- package/dist/lib/shell.d.ts.map +1 -0
- package/dist/lib/shell.js +32 -0
- package/dist/lib/shell.js.map +1 -0
- package/dist/skill/SKILL.md +887 -0
- package/dist/skill/agents/quickback-specialist/AGENT.md +298 -0
- package/dist/templates/registry.d.ts +36 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +181 -0
- package/dist/templates/registry.js.map +1 -0
- package/package.json +55 -0
- package/src/cursor/quickback.mdc +277 -0
- package/src/examples/recruitment.tar.gz +0 -0
- package/src/skill/SKILL.md +887 -0
- package/src/skill/agents/quickback-specialist/AGENT.md +298 -0
|
@@ -0,0 +1,887 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: quickback
|
|
3
|
+
description: Quickback API engine documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, webhooks, or deployment
|
|
4
|
+
allowed-tools: Read, Grep, Glob
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Quickback
|
|
8
|
+
|
|
9
|
+
Quickback is two things:
|
|
10
|
+
|
|
11
|
+
1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
|
|
12
|
+
2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
|
|
13
|
+
|
|
14
|
+
The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
|
|
15
|
+
|
|
16
|
+
## Accessing Documentation
|
|
17
|
+
|
|
18
|
+
The fastest way to look up detailed docs is via the CLI:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
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
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
my-app/
|
|
56
|
+
├── quickback/
|
|
57
|
+
│ ├── quickback.config.ts
|
|
58
|
+
│ └── features/
|
|
59
|
+
│ └── {feature-name}/
|
|
60
|
+
│ ├── {table}.ts # Schema + security (defineTable)
|
|
61
|
+
│ ├── actions.ts # Custom actions (optional)
|
|
62
|
+
│ ├── handlers/ # Action handlers (optional)
|
|
63
|
+
│ └── pages/ # Custom CMS pages (optional)
|
|
64
|
+
│ └── {slug}.ts # definePage() call
|
|
65
|
+
├── src/ # ← compiled output
|
|
66
|
+
│ ├── index.ts # API entry (Hono)
|
|
67
|
+
│ └── apps/
|
|
68
|
+
│ ├── cms/ # ← CMS static assets (when cms: true)
|
|
69
|
+
│ │ ├── index.html
|
|
70
|
+
│ │ └── assets/
|
|
71
|
+
│ └── account/ # ← Account UI assets (when account: true/object)
|
|
72
|
+
│ ├── index.html
|
|
73
|
+
│ └── assets/
|
|
74
|
+
└── ...
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## quickback.config.ts
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
|
|
81
|
+
|
|
82
|
+
export default defineConfig({
|
|
83
|
+
name: "my-saas-app",
|
|
84
|
+
cms: true, // Embed CMS admin UI in compiled Worker (or { domain: "cms.example.com" })
|
|
85
|
+
account: { // Embed Account UI (auth, profile, orgs, admin) in compiled Worker
|
|
86
|
+
domain: "auth.example.com", // Optional: custom domain (served at / instead of /account/)
|
|
87
|
+
adminDomain: "admin.example.com", // Optional: separate admin domain
|
|
88
|
+
name: "My App",
|
|
89
|
+
companyName: "My Company",
|
|
90
|
+
tagline: "Build faster, ship sooner",
|
|
91
|
+
build: true, // Set false to skip SPA rebuild on subsequent compiles
|
|
92
|
+
auth: {
|
|
93
|
+
password: true, // Email/password login (default: false)
|
|
94
|
+
emailOTP: true, // Email OTP login (default: true)
|
|
95
|
+
passkey: true, // WebAuthn passkeys (default: true)
|
|
96
|
+
signup: true, // User registration (default: true)
|
|
97
|
+
organizations: true, // Multi-tenant org management (default: true)
|
|
98
|
+
admin: true, // Admin panel (default: true)
|
|
99
|
+
emailVerification: true, // Require email verification (default: true)
|
|
100
|
+
},
|
|
101
|
+
},
|
|
102
|
+
providers: {
|
|
103
|
+
runtime: defineRuntime("cloudflare"),
|
|
104
|
+
database: defineDatabase("cloudflare-d1"),
|
|
105
|
+
auth: defineAuth("better-auth"),
|
|
106
|
+
},
|
|
107
|
+
build: {
|
|
108
|
+
outputDir: "dist",
|
|
109
|
+
dependencies: {
|
|
110
|
+
"fast-xml-parser": "^4.5.0", // Third-party packages used in action handlers
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Minimal: `account: true` enables with all defaults. `account: { build: false }` skips rebuild on subsequent compiles.
|
|
117
|
+
|
|
118
|
+
## Compile Output and State Artifacts
|
|
119
|
+
|
|
120
|
+
- Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
|
|
121
|
+
- CMS assets → `src/apps/cms/` (served at `/cms/` or root on custom domain)
|
|
122
|
+
- Account UI assets → `src/apps/account/` (served at `/account/` or root on custom domain)
|
|
123
|
+
- Drizzle migration SQL and meta files live under `quickback/drizzle/...` — Quickback owns this state and never writes a project-root `drizzle/` folder
|
|
124
|
+
- Security contract reports are written to `quickback/reports/...`
|
|
125
|
+
|
|
126
|
+
## Automatic Audit Fields
|
|
127
|
+
|
|
128
|
+
Quickback automatically injects these fields into every table:
|
|
129
|
+
- `createdAt`, `modifiedAt`, `deletedAt` (timestamps)
|
|
130
|
+
- `createdBy`, `modifiedBy`, `deletedBy` (user IDs)
|
|
131
|
+
|
|
132
|
+
**Do NOT add these to your schema files.** They are auto-injected by the compiler.
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Feature Definitions
|
|
137
|
+
|
|
138
|
+
Features live in `quickback/features/{name}/` with one file per table.
|
|
139
|
+
|
|
140
|
+
Quickback offers **three co-equal authoring patterns** — all compile to the same generated runtime, the compiler dispatches per file:
|
|
141
|
+
|
|
142
|
+
- **`feature()`** (recommended default) — single default export, one import, everything in one call. Use for new code.
|
|
143
|
+
- **`q.table()` + `defineTable()`** — the two-export form. Same `q` DSL, more explicit. Use when you want the table identifier named before the default export.
|
|
144
|
+
- **Drizzle `sqliteTable()` / `pgTable()` + `defineTable()`** — interop with existing Drizzle code.
|
|
145
|
+
|
|
146
|
+
### Example: todos.ts (`feature()` — recommended default)
|
|
147
|
+
|
|
148
|
+
```typescript
|
|
149
|
+
import { feature, q } from "@quickback/compiler";
|
|
150
|
+
|
|
151
|
+
export default feature("todos", {
|
|
152
|
+
columns: {
|
|
153
|
+
id: q.id(),
|
|
154
|
+
title: q.text().required(),
|
|
155
|
+
description: q.text().optional(),
|
|
156
|
+
completed: q.bool().default(false),
|
|
157
|
+
userId: q.text().required(),
|
|
158
|
+
organizationId: q.text().required(),
|
|
159
|
+
},
|
|
160
|
+
firewall: { organization: {}, owner: {} },
|
|
161
|
+
crud: {
|
|
162
|
+
list: { access: { roles: ["member", "admin"] } },
|
|
163
|
+
get: { access: { roles: ["member", "admin"] } },
|
|
164
|
+
create: { access: { roles: ["member", "admin"] } },
|
|
165
|
+
update: { access: { roles: ["admin"] } },
|
|
166
|
+
delete: { access: { roles: ["admin"] }, mode: "soft" },
|
|
167
|
+
},
|
|
168
|
+
guards: {
|
|
169
|
+
createable: ["title", "description", "completed"],
|
|
170
|
+
updatable: ["title", "description", "completed"],
|
|
171
|
+
},
|
|
172
|
+
masking: {
|
|
173
|
+
userId: { type: "redact", show: { roles: ["admin"] } },
|
|
174
|
+
},
|
|
175
|
+
});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**q DSL quick reference:** column names default to snake_case of the JS key (`organizationId` → `organization_id`). `q.id()` emits a cuid2 primary key. Chainable modifiers: `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.references(() => other.id, { onDelete: 'cascade' })`.
|
|
179
|
+
|
|
180
|
+
The `feature()` form is compile-time sugar — the compiler expands it to `q.table()` + `defineTable()` internally. Use whichever reads best for the file.
|
|
181
|
+
|
|
182
|
+
### Example: same todos using the two-export form
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
186
|
+
|
|
187
|
+
export const todos = q.table("todos", {
|
|
188
|
+
id: q.id(),
|
|
189
|
+
title: q.text().required(),
|
|
190
|
+
completed: q.bool().default(false),
|
|
191
|
+
userId: q.text().required(),
|
|
192
|
+
organizationId: q.text().required(),
|
|
193
|
+
});
|
|
194
|
+
|
|
195
|
+
export default defineTable(todos, {
|
|
196
|
+
firewall: { organization: {}, owner: {} },
|
|
197
|
+
crud: { /* same as above */ },
|
|
198
|
+
guards: { /* same as above */ },
|
|
199
|
+
});
|
|
200
|
+
|
|
201
|
+
export type Todo = typeof todos.$infer;
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Example: same todos with Drizzle (for interop)
|
|
205
|
+
|
|
206
|
+
```typescript
|
|
207
|
+
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
|
|
208
|
+
import { defineTable } from "@quickback/compiler";
|
|
209
|
+
|
|
210
|
+
export const todos = sqliteTable("todos", {
|
|
211
|
+
id: text("id").primaryKey(),
|
|
212
|
+
title: text("title").notNull(),
|
|
213
|
+
completed: integer("completed", { mode: "boolean" }).default(false),
|
|
214
|
+
userId: text("user_id").notNull(),
|
|
215
|
+
organizationId: text("organization_id").notNull(),
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
export default defineTable(todos, {
|
|
219
|
+
firewall: { organization: {}, owner: {} },
|
|
220
|
+
crud: { /* same as above */ },
|
|
221
|
+
guards: { /* same as above */ },
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Internal/Junction Tables (No API)
|
|
226
|
+
|
|
227
|
+
Tables without a `defineTable()` / `feature()` default export get no API routes:
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
export const roomAmenities = q.table('roomAmenities', {
|
|
231
|
+
roomId: q.text().required(),
|
|
232
|
+
amenityId: q.text().required(),
|
|
233
|
+
});
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The compiler warns once per such table so you confirm the opt-out is intentional.
|
|
237
|
+
|
|
238
|
+
### Handlers use `q.*` for query helpers too
|
|
239
|
+
|
|
240
|
+
Custom action handlers query via the same `q` namespace:
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
// quickback/features/mail/handlers/inbound.ts
|
|
244
|
+
import { q } from "../../../lib/q";
|
|
245
|
+
import mailboxes from "../mailboxes";
|
|
246
|
+
import messages from "../messages";
|
|
247
|
+
|
|
248
|
+
export const execute = async ({ unsafeDb, input }) => {
|
|
249
|
+
const mailbox = await unsafeDb.query.mailboxes.findFirst({
|
|
250
|
+
where: q.eq(mailboxes.address, input.mailboxAddress),
|
|
251
|
+
});
|
|
252
|
+
// …
|
|
253
|
+
};
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Available: `q.and`, `q.or`, `q.not`, `q.eq`, `q.ne`, `q.gt`, `q.gte`, `q.lt`, `q.lte`, `q.like`, `q.ilike`, `q.inArray`, `q.notInArray`, `q.isNull`, `q.isNotNull`, `q.between`, `q.desc`, `q.asc`, `q.sql`. Pure re-export of Drizzle's query builder under the Quickback namespace — users can still `import { eq } from "drizzle-orm"` directly if they prefer.
|
|
257
|
+
|
|
258
|
+
### Explicit scope in unsafe handlers — `unsafeDb.scopeTo(...)`
|
|
259
|
+
|
|
260
|
+
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:
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
export const execute = async ({ unsafeDb, input }) => {
|
|
264
|
+
const [mailbox] = await unsafeDb.select().from(mailboxes)
|
|
265
|
+
.where(q.eq(mailboxes.id, input.mailboxId));
|
|
266
|
+
if (!mailbox) return { ok: false };
|
|
267
|
+
|
|
268
|
+
const db = unsafeDb.scopeTo({ organizationId: mailbox.organizationId });
|
|
269
|
+
await db.insert(messages).values({ mailboxId: mailbox.id, body: input.body });
|
|
270
|
+
return { ok: true };
|
|
271
|
+
};
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
`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.
|
|
275
|
+
|
|
276
|
+
### Import style
|
|
277
|
+
|
|
278
|
+
With `feature()`, tables are **default exports** — use default imports in actions/other files:
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
// features/applications/actions.ts
|
|
282
|
+
import applications from "./applications";
|
|
283
|
+
import { defineActions } from "@quickback/compiler";
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
With the two-export form, tables are **named exports** — use named imports:
|
|
287
|
+
|
|
288
|
+
```typescript
|
|
289
|
+
import { applications } from "./applications";
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Both produce the same typed handle.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## Input Hints
|
|
297
|
+
|
|
298
|
+
Control how the CMS renders form inputs. Key values:
|
|
299
|
+
|
|
300
|
+
| Hint | Renders As |
|
|
301
|
+
|------|-----------|
|
|
302
|
+
| `richtext` | Tiptap rich text editor (edit) / formatted HTML (view). Stores HTML. |
|
|
303
|
+
| `select` | Dropdown select |
|
|
304
|
+
| `textarea` | Multi-line text |
|
|
305
|
+
| `currency` | Currency input |
|
|
306
|
+
| `checkbox` | Checkbox toggle |
|
|
307
|
+
|
|
308
|
+
```typescript
|
|
309
|
+
inputHints: { description: "richtext", status: "select" }
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## Four Security Layers
|
|
315
|
+
|
|
316
|
+
Every API request passes through four layers in order:
|
|
317
|
+
|
|
318
|
+
```
|
|
319
|
+
Request → Firewall → Access → Guards → Database → Masking → Response
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
| Layer | Purpose | Failure |
|
|
323
|
+
|-------|---------|---------|
|
|
324
|
+
| **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
|
|
325
|
+
| **Access** | Role-based CRUD permissions (deny by default) | 403 |
|
|
326
|
+
| **Guards** | Field modification rules (protected/immutable fields) | 400 |
|
|
327
|
+
| **Masking** | PII redaction for unauthorized viewers | — |
|
|
328
|
+
|
|
329
|
+
### 1. Firewall — Data Isolation
|
|
330
|
+
|
|
331
|
+
Compiles WHERE clauses to isolate data by ownership. Auto-detects column names.
|
|
332
|
+
|
|
333
|
+
```typescript
|
|
334
|
+
firewall: {
|
|
335
|
+
organization: {}, // WHERE organizationId = ctx.activeOrgId
|
|
336
|
+
owner: { mode: 'optional' }, // AND (ownerId = ctx.userId OR ownerId IS NULL)
|
|
337
|
+
team: {}, // WHERE teamId = ctx.activeTeamId
|
|
338
|
+
softDelete: {}, // AND deletedAt IS NULL
|
|
339
|
+
exception: true, // No filtering (public resources)
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
Auto-detection:
|
|
344
|
+
- `organization` → looks for `organizationId` or `organization_id`
|
|
345
|
+
- `owner` → looks for `userId` or `user_id`
|
|
346
|
+
- `team` → looks for `teamId` or `team_id`
|
|
347
|
+
|
|
348
|
+
Column overrides:
|
|
349
|
+
|
|
350
|
+
```typescript
|
|
351
|
+
firewall: {
|
|
352
|
+
organization: {
|
|
353
|
+
column: 'tenant_id',
|
|
354
|
+
source: 'ctx.tenant.id',
|
|
355
|
+
},
|
|
356
|
+
}
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
Owner modes: default = strict (only own records), `optional` = own + NULL owner (admin pattern).
|
|
360
|
+
|
|
361
|
+
### 2. Access — Permission Checks
|
|
362
|
+
|
|
363
|
+
Role-based and record-based access control. Deny by default.
|
|
364
|
+
|
|
365
|
+
```typescript
|
|
366
|
+
crud: {
|
|
367
|
+
list: { access: { roles: ['member+'] } }, // member, admin, owner
|
|
368
|
+
get: { access: { roles: ['member+'] } },
|
|
369
|
+
create: { access: { roles: ['admin+'] } }, // admin, owner
|
|
370
|
+
update: {
|
|
371
|
+
access: {
|
|
372
|
+
or: [
|
|
373
|
+
{ roles: ['admin+'] },
|
|
374
|
+
{ record: { createdBy: { equals: '$ctx.userId' } } },
|
|
375
|
+
],
|
|
376
|
+
},
|
|
377
|
+
},
|
|
378
|
+
delete: { access: { roles: ['owner'] } }, // owner only
|
|
379
|
+
}
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
**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.
|
|
383
|
+
|
|
384
|
+
Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
|
|
385
|
+
|
|
386
|
+
Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
|
|
387
|
+
|
|
388
|
+
**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.
|
|
389
|
+
|
|
390
|
+
### 3. Guards — Field Protection
|
|
391
|
+
|
|
392
|
+
```typescript
|
|
393
|
+
guards: {
|
|
394
|
+
createable: ['name', 'description'], // Allowed on POST
|
|
395
|
+
updatable: ['description'], // Allowed on PATCH
|
|
396
|
+
immutable: ['invoiceNumber'], // Set once, never change
|
|
397
|
+
protected: { status: ['approve'] }, // Only via named actions
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
|
|
402
|
+
|
|
403
|
+
PUT/Upsert requires both `generateId: false` and `guards: false`.
|
|
404
|
+
|
|
405
|
+
### 4. Masking — PII Redaction
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
masking: {
|
|
409
|
+
ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
|
|
410
|
+
email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
|
|
411
|
+
}
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
|
|
415
|
+
|
|
416
|
+
Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## Views — Column-Level Security
|
|
421
|
+
|
|
422
|
+
Named projections that control which fields are visible based on role.
|
|
423
|
+
|
|
424
|
+
```typescript
|
|
425
|
+
views: {
|
|
426
|
+
summary: {
|
|
427
|
+
fields: ['id', 'name', 'email'],
|
|
428
|
+
access: { roles: ['member', 'admin'] },
|
|
429
|
+
},
|
|
430
|
+
full: {
|
|
431
|
+
fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
|
|
432
|
+
access: { roles: ['admin'] },
|
|
433
|
+
},
|
|
434
|
+
}
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
Generated endpoints: `GET /api/v1/{resource}/views/{viewName}`
|
|
438
|
+
|
|
439
|
+
---
|
|
440
|
+
|
|
441
|
+
## Validation
|
|
442
|
+
|
|
443
|
+
```typescript
|
|
444
|
+
validation: {
|
|
445
|
+
name: { minLength: 1, maxLength: 100 },
|
|
446
|
+
capacity: { min: 1, max: 1000 },
|
|
447
|
+
roomType: { enum: ['meeting', 'conference', 'breakout'] },
|
|
448
|
+
email: { email: true },
|
|
449
|
+
code: { pattern: '^[A-Z]{3}$' },
|
|
450
|
+
}
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## CMS Record Layouts
|
|
456
|
+
|
|
457
|
+
Control how fields are grouped on the CMS record detail page.
|
|
458
|
+
|
|
459
|
+
```typescript
|
|
460
|
+
layouts: {
|
|
461
|
+
default: {
|
|
462
|
+
sections: [
|
|
463
|
+
{ label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
|
|
464
|
+
{ label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
|
|
465
|
+
],
|
|
466
|
+
},
|
|
467
|
+
}
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## Account UI — Authentication & Account Management
|
|
475
|
+
|
|
476
|
+
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.
|
|
477
|
+
|
|
478
|
+
### What's Included
|
|
479
|
+
|
|
480
|
+
| Section | Pages |
|
|
481
|
+
|---------|-------|
|
|
482
|
+
| **Auth** | Login, signup, email OTP, forgot password, email verification |
|
|
483
|
+
| **Account** | Profile, devices/sessions, passkeys, account deletion |
|
|
484
|
+
| **Organizations** | Dashboard, org creation, member management, invitations, API keys, org settings |
|
|
485
|
+
| **Admin** | User management (search, create, ban/unban, reset passwords, view sessions) |
|
|
486
|
+
| **CLI** | Device authorization flow for `quickback login` |
|
|
487
|
+
|
|
488
|
+
### Enabling
|
|
489
|
+
|
|
490
|
+
```typescript
|
|
491
|
+
// Minimal
|
|
492
|
+
account: true
|
|
493
|
+
|
|
494
|
+
// Full config
|
|
495
|
+
account: {
|
|
496
|
+
domain: "auth.example.com",
|
|
497
|
+
adminDomain: "admin.example.com",
|
|
498
|
+
name: "My App",
|
|
499
|
+
companyName: "My Company",
|
|
500
|
+
tagline: "Build faster, ship sooner",
|
|
501
|
+
auth: {
|
|
502
|
+
password: true, // Email/password (default: false)
|
|
503
|
+
emailOTP: true, // Email OTP (default: true)
|
|
504
|
+
passkey: true, // WebAuthn passkeys (default: true)
|
|
505
|
+
signup: true, // Registration (default: true)
|
|
506
|
+
organizations: true, // Multi-tenant orgs (default: true)
|
|
507
|
+
admin: true, // Admin panel (default: true)
|
|
508
|
+
emailVerification: true, // Require email verification (default: true)
|
|
509
|
+
},
|
|
510
|
+
}
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
### Compile-Time Feature Gating
|
|
514
|
+
|
|
515
|
+
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.
|
|
516
|
+
|
|
517
|
+
### Routing
|
|
518
|
+
|
|
519
|
+
- **Unified domain (default):** Served at `/account/` alongside CMS at `/cms/` and API at `/api/`
|
|
520
|
+
- **Custom domain:** Served at root `/` on `auth.example.com`
|
|
521
|
+
- **Admin domain:** Admin routes served at root `/` on `admin.example.com`
|
|
522
|
+
- Cross-subdomain auth cookies auto-configured when multiple custom domains detected
|
|
523
|
+
|
|
524
|
+
### Skip Rebuild
|
|
525
|
+
|
|
526
|
+
```typescript
|
|
527
|
+
account: { build: false, /* ...other options */ }
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Skips the SPA build on subsequent compiles — useful when iterating on API features only.
|
|
531
|
+
|
|
532
|
+
### Standalone & Library Usage
|
|
533
|
+
|
|
534
|
+
Account UI also works outside the compiler:
|
|
535
|
+
- **Template:** Clone repo, configure `.env`, deploy as separate Worker
|
|
536
|
+
- **Library:** `npm install quickback-better-auth-account-ui` and import as React component
|
|
537
|
+
|
|
538
|
+
Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
|
|
539
|
+
|
|
540
|
+
---
|
|
541
|
+
|
|
542
|
+
## Actions — Custom Business Logic
|
|
543
|
+
|
|
544
|
+
Defined in a separate `actions.ts` file using `defineActions()`.
|
|
545
|
+
|
|
546
|
+
```typescript
|
|
547
|
+
import { todos } from './todos';
|
|
548
|
+
import { defineActions } from '@quickback/compiler';
|
|
549
|
+
import { z } from 'zod';
|
|
550
|
+
|
|
551
|
+
export default defineActions(todos, {
|
|
552
|
+
complete: {
|
|
553
|
+
description: "Mark todo as complete",
|
|
554
|
+
input: z.object({ completedAt: z.string().datetime().optional() }),
|
|
555
|
+
guard: { roles: ["member", "admin"], record: { completed: { equals: false } } },
|
|
556
|
+
execute: async ({ db, record, ctx, input }) => {
|
|
557
|
+
await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
|
|
558
|
+
return { success: true };
|
|
559
|
+
},
|
|
560
|
+
sideEffects: "sync",
|
|
561
|
+
},
|
|
562
|
+
archive: {
|
|
563
|
+
description: "Archive a todo",
|
|
564
|
+
input: z.object({}),
|
|
565
|
+
guard: { roles: ["admin"] },
|
|
566
|
+
handler: "./handlers/archive",
|
|
567
|
+
},
|
|
568
|
+
});
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
**Record-based** (default): `POST /api/v1/{resource}/:id/{action}`
|
|
572
|
+
**Standalone**: `standalone: true`, custom `path` and `method`
|
|
573
|
+
|
|
574
|
+
Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget)
|
|
575
|
+
|
|
576
|
+
### Actions-Only Features
|
|
577
|
+
|
|
578
|
+
Features that only contain standalone actions (no tables). Use `defineActions(null, { ... })`:
|
|
579
|
+
|
|
580
|
+
```typescript
|
|
581
|
+
// quickback/features/utilities/actions.ts
|
|
582
|
+
import { defineActions } from '@quickback/compiler';
|
|
583
|
+
import { z } from 'zod';
|
|
584
|
+
|
|
585
|
+
export default defineActions(null, {
|
|
586
|
+
healthCheck: {
|
|
587
|
+
standalone: true,
|
|
588
|
+
path: "/health",
|
|
589
|
+
method: "GET",
|
|
590
|
+
description: "Health check endpoint",
|
|
591
|
+
input: z.object({}),
|
|
592
|
+
guard: { roles: ["member", "admin"] },
|
|
593
|
+
handler: "./handlers/health-check",
|
|
594
|
+
},
|
|
595
|
+
});
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
All actions in an actions-only feature must have `standalone: true` (since there's no table for record-based actions).
|
|
599
|
+
|
|
600
|
+
---
|
|
601
|
+
|
|
602
|
+
## API Reference
|
|
603
|
+
|
|
604
|
+
### CRUD Operations
|
|
605
|
+
|
|
606
|
+
| Method | Endpoint | Description |
|
|
607
|
+
|--------|----------|-------------|
|
|
608
|
+
| `GET` | `/api/v1/{resource}` | List records |
|
|
609
|
+
| `GET` | `/api/v1/{resource}/:id` | Get single record |
|
|
610
|
+
| `POST` | `/api/v1/{resource}` | Create record |
|
|
611
|
+
| `PATCH` | `/api/v1/{resource}/:id` | Update record |
|
|
612
|
+
| `DELETE` | `/api/v1/{resource}/:id` | Delete record |
|
|
613
|
+
| `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
|
|
614
|
+
|
|
615
|
+
### Batch Operations
|
|
616
|
+
|
|
617
|
+
`POST|PATCH|DELETE|PUT /api/v1/{resource}/batch` with `{ "records": [...], "options": { "atomic": false } }`
|
|
618
|
+
|
|
619
|
+
### Query Parameters
|
|
620
|
+
|
|
621
|
+
| Feature | Syntax |
|
|
622
|
+
|---------|--------|
|
|
623
|
+
| Pagination | `?limit=50&offset=0` (max 100) |
|
|
624
|
+
| Filter | `?status=active`, `?amount.gt=100`, `?status.in=draft,pending` |
|
|
625
|
+
| Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
|
|
626
|
+
| Fields | `?fields=id,name,status` |
|
|
627
|
+
| Total count | `?total=true` |
|
|
628
|
+
| Search | `?search=conference` (OR'd LIKE across text columns) |
|
|
629
|
+
|
|
630
|
+
Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
|
|
631
|
+
|
|
632
|
+
### Response Format
|
|
633
|
+
|
|
634
|
+
```json
|
|
635
|
+
{
|
|
636
|
+
"data": [{ "id": "...", "title": "Todo 1" }],
|
|
637
|
+
"pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
|
|
638
|
+
}
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
### Error Responses
|
|
642
|
+
|
|
643
|
+
| Status | Layer | Meaning |
|
|
644
|
+
|--------|-------|---------|
|
|
645
|
+
| `401` | Auth | Invalid/expired session |
|
|
646
|
+
| `403` | Access | Insufficient permissions |
|
|
647
|
+
| `404` | Firewall | Record not found or outside scope |
|
|
648
|
+
| `400` | Guards | Invalid field modification |
|
|
649
|
+
|
|
650
|
+
---
|
|
651
|
+
|
|
652
|
+
## Database Dialects
|
|
653
|
+
|
|
654
|
+
| Stack | Import | Table Function |
|
|
655
|
+
|-------|--------|----------------|
|
|
656
|
+
| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
|
|
657
|
+
| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
|
|
658
|
+
| MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
|
|
659
|
+
|
|
660
|
+
---
|
|
661
|
+
|
|
662
|
+
# PART 2: THE QUICKBACK STACK
|
|
663
|
+
|
|
664
|
+
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.
|
|
665
|
+
|
|
666
|
+
```
|
|
667
|
+
┌─────────────────────────────────────────────────────────┐
|
|
668
|
+
│ QUICKBACK STACK ON CLOUDFLARE │
|
|
669
|
+
│ │
|
|
670
|
+
│ Workers — API runtime (Hono) │
|
|
671
|
+
│ D1 — SQLite database at the edge │
|
|
672
|
+
│ R2 — S3-compatible file storage │
|
|
673
|
+
│ KV — Distributed key-value store │
|
|
674
|
+
│ Durable Objects — Realtime WebSockets │
|
|
675
|
+
│ Queues — Background job processing │
|
|
676
|
+
│ Workers AI — Embeddings & vector search │
|
|
677
|
+
│ Better Auth — Authentication & organizations │
|
|
678
|
+
└─────────────────────────────────────────────────────────┘
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
## Authentication (Better Auth)
|
|
682
|
+
|
|
683
|
+
Built on Better Auth with multi-tenant organization support.
|
|
684
|
+
|
|
685
|
+
- Email/password, magic links, passkeys, email OTP
|
|
686
|
+
- Three org roles: `owner`, `admin`, `member`
|
|
687
|
+
- Session storage in KV namespace
|
|
688
|
+
- All auth routes at `/auth/v1/*`
|
|
689
|
+
- Extensible via Better Auth plugins
|
|
690
|
+
- **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`
|
|
691
|
+
- **Account UI** — pre-built SPA for login, signup, profile, orgs, admin (see Account UI section above)
|
|
692
|
+
|
|
693
|
+
```typescript
|
|
694
|
+
// Config
|
|
695
|
+
providers: {
|
|
696
|
+
auth: defineAuth("better-auth"),
|
|
697
|
+
}
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
|
|
701
|
+
|
|
702
|
+
## Database (D1)
|
|
703
|
+
|
|
704
|
+
SQLite at the edge with zero configuration. Multi-database pattern for independent scaling:
|
|
705
|
+
|
|
706
|
+
| Binding | Purpose |
|
|
707
|
+
|---------|---------|
|
|
708
|
+
| `DB` | Application data (features) |
|
|
709
|
+
| `AUTH_DB` | Auth sessions & users |
|
|
710
|
+
| `FILES_DB` | File metadata |
|
|
711
|
+
| `WEBHOOKS_DB` | Webhook tracking |
|
|
712
|
+
|
|
713
|
+
- Drizzle ORM for type-safe queries
|
|
714
|
+
- Auto-generated migrations on compile
|
|
715
|
+
- Application-layer security (firewall, access, guards, masking)
|
|
716
|
+
- Local dev with `.wrangler/state/`
|
|
717
|
+
- Neon Postgres available as alternative
|
|
718
|
+
|
|
719
|
+
```typescript
|
|
720
|
+
providers: {
|
|
721
|
+
database: defineDatabase("cloudflare-d1", {
|
|
722
|
+
splitDatabases: true,
|
|
723
|
+
}),
|
|
724
|
+
}
|
|
725
|
+
```
|
|
726
|
+
|
|
727
|
+
Docs: `quickback docs stack/database/d1` | https://docs.quickback.dev/stack/database/d1
|
|
728
|
+
|
|
729
|
+
## File Storage (R2)
|
|
730
|
+
|
|
731
|
+
S3-compatible object storage with built-in access control.
|
|
732
|
+
|
|
733
|
+
- Two-worker architecture: API worker (upload/manage) + Files worker (serve)
|
|
734
|
+
- Bucket-scoped access policies (public, organization, user)
|
|
735
|
+
- File metadata tracked in `FILES_DB`
|
|
736
|
+
- Soft deletes with org-level tenant isolation
|
|
737
|
+
- API at `/storage/v1/*`
|
|
738
|
+
|
|
739
|
+
Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
|
|
740
|
+
|
|
741
|
+
## KV Storage
|
|
742
|
+
|
|
743
|
+
Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
|
|
744
|
+
|
|
745
|
+
- Use cases: sessions, caching, rate limiting, feature flags
|
|
746
|
+
- Eventually consistent (60 second propagation)
|
|
747
|
+
- TTL/expiration support
|
|
748
|
+
|
|
749
|
+
Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
|
|
750
|
+
|
|
751
|
+
## Realtime (Durable Objects)
|
|
752
|
+
|
|
753
|
+
WebSocket connections for live updates via organization-scoped Durable Objects.
|
|
754
|
+
|
|
755
|
+
- CRUD event broadcasting (insert, update, delete)
|
|
756
|
+
- Custom broadcasts and event namespaces
|
|
757
|
+
- Role-based filtering and per-role field masking
|
|
758
|
+
- Session token or API key authentication
|
|
759
|
+
- Type-safe with `defineRealtime()` for custom events
|
|
760
|
+
- Endpoint: `/realtime/v1/websocket`
|
|
761
|
+
|
|
762
|
+
Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
|
|
763
|
+
|
|
764
|
+
## Queues (Background Processing)
|
|
765
|
+
|
|
766
|
+
Cloudflare Queues for reliable async job processing.
|
|
767
|
+
|
|
768
|
+
| Queue | Purpose |
|
|
769
|
+
|-------|---------|
|
|
770
|
+
| `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
|
|
771
|
+
| `WEBHOOKS_QUEUE` | Webhook delivery |
|
|
772
|
+
| Custom queues | Your background jobs |
|
|
773
|
+
|
|
774
|
+
- Custom handlers via `defineQueue()` in `services/queues/`
|
|
775
|
+
- Auto-retry up to 3 times, max batch 10, 30s timeout
|
|
776
|
+
- Chaining between queues
|
|
777
|
+
|
|
778
|
+
Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
|
|
779
|
+
|
|
780
|
+
## Vector & Embeddings (Workers AI)
|
|
781
|
+
|
|
782
|
+
Auto-generated embeddings for similarity search and classification.
|
|
783
|
+
|
|
784
|
+
- Table-level config via `embeddings` in `defineTable()`
|
|
785
|
+
- Service-level config via `defineEmbedding()`
|
|
786
|
+
- Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
|
|
787
|
+
- Async processing via `EMBEDDINGS_QUEUE`
|
|
788
|
+
- Vector storage in D1 + optional Vectorize index
|
|
789
|
+
- API: `/api/v1/embeddings`
|
|
790
|
+
|
|
791
|
+
Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
|
|
792
|
+
|
|
793
|
+
## Webhooks
|
|
794
|
+
|
|
795
|
+
### Inbound (Receiving)
|
|
796
|
+
|
|
797
|
+
Receive events from Stripe, Paddle, GitHub, etc. at `POST /webhooks/v1/inbound/:provider`
|
|
798
|
+
|
|
799
|
+
```typescript
|
|
800
|
+
import { onWebhookEvent } from './lib/webhooks';
|
|
801
|
+
|
|
802
|
+
onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
|
|
803
|
+
const { data, env } = ctx;
|
|
804
|
+
await createSubscription({ ... });
|
|
805
|
+
});
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
### Outbound (Sending)
|
|
809
|
+
|
|
810
|
+
Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
|
|
811
|
+
|
|
812
|
+
```typescript
|
|
813
|
+
import { emitWebhookEvent } from './lib/webhooks';
|
|
814
|
+
|
|
815
|
+
await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
Event patterns: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
|
|
819
|
+
Endpoint management: `/webhooks/v1/endpoints`
|
|
820
|
+
|
|
821
|
+
Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
|
|
822
|
+
|
|
823
|
+
---
|
|
824
|
+
|
|
825
|
+
# CLI Commands
|
|
826
|
+
|
|
827
|
+
| Command | Description |
|
|
828
|
+
|---------|-------------|
|
|
829
|
+
| `quickback create <template> <name>` | Create project from template |
|
|
830
|
+
| `quickback compile` | Compile definitions to output (copies CMS assets if `cms: true`) |
|
|
831
|
+
| `quickback docs [topic]` | Browse built-in documentation |
|
|
832
|
+
| `quickback login` | Authenticate for Pro templates |
|
|
833
|
+
| `quickback logout` | Clear stored credentials |
|
|
834
|
+
| `quickback whoami` | Show current auth status |
|
|
835
|
+
| `quickback claude install` | Install Claude Code skill |
|
|
836
|
+
| `quickback claude update` | Update to latest skill version |
|
|
837
|
+
|
|
838
|
+
## Available Templates
|
|
839
|
+
|
|
840
|
+
| Template | Stack | Status |
|
|
841
|
+
|----------|-------|--------|
|
|
842
|
+
| `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
|
|
843
|
+
| `bun` | Bun + SQLite + Better Auth | Free |
|
|
844
|
+
| `turso` | Turso/LibSQL + Better Auth | Pro |
|
|
845
|
+
|
|
846
|
+
## Development Workflow
|
|
847
|
+
|
|
848
|
+
```bash
|
|
849
|
+
quickback create cloudflare my-app # 1. Create project
|
|
850
|
+
# Define features in quickback/features/
|
|
851
|
+
quickback compile # 2. Compile
|
|
852
|
+
npm install && npm run dev # 3. Run
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
---
|
|
856
|
+
|
|
857
|
+
# Online Documentation
|
|
858
|
+
|
|
859
|
+
- [Getting Started](https://docs.quickback.dev/compiler/getting-started)
|
|
860
|
+
- [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
|
|
861
|
+
- [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
|
|
862
|
+
- [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
|
|
863
|
+
- [Access](https://docs.quickback.dev/compiler/definitions/access)
|
|
864
|
+
- [Guards](https://docs.quickback.dev/compiler/definitions/guards)
|
|
865
|
+
- [Masking](https://docs.quickback.dev/compiler/definitions/masking)
|
|
866
|
+
- [Views](https://docs.quickback.dev/compiler/definitions/views)
|
|
867
|
+
- [Actions](https://docs.quickback.dev/compiler/definitions/actions)
|
|
868
|
+
- [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
|
|
869
|
+
- [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
|
|
870
|
+
- [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
|
|
871
|
+
- [Stack Overview](https://docs.quickback.dev/stack)
|
|
872
|
+
- [D1 Database](https://docs.quickback.dev/stack/database/d1)
|
|
873
|
+
- [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
|
|
874
|
+
- [Realtime](https://docs.quickback.dev/stack/realtime)
|
|
875
|
+
- [Queues](https://docs.quickback.dev/stack/queues)
|
|
876
|
+
- [Embeddings](https://docs.quickback.dev/stack/vector)
|
|
877
|
+
- [Webhooks](https://docs.quickback.dev/stack/webhooks)
|
|
878
|
+
- [Account UI Overview](https://docs.quickback.dev/account-ui)
|
|
879
|
+
- [Account UI with Quickback](https://docs.quickback.dev/account-ui/with-quickback)
|
|
880
|
+
- [Account UI Standalone](https://docs.quickback.dev/account-ui/standalone)
|
|
881
|
+
- [Account UI Features](https://docs.quickback.dev/account-ui/features)
|
|
882
|
+
- [Account UI Environment Variables](https://docs.quickback.dev/account-ui/environment-variables)
|
|
883
|
+
- [Account UI Customization](https://docs.quickback.dev/account-ui/customization)
|
|
884
|
+
- [CMS Overview](https://docs.quickback.dev/cms)
|
|
885
|
+
- [CMS Dashboard](https://docs.quickback.dev/cms/dashboard)
|
|
886
|
+
- [CMS Custom Pages](https://docs.quickback.dev/cms/pages)
|
|
887
|
+
- [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)
|