@quickback-dev/cli 0.18.0 → 0.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +25 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/migrations.d.ts +17 -0
  5. package/dist/commands/migrations.d.ts.map +1 -0
  6. package/dist/commands/migrations.js +328 -0
  7. package/dist/commands/migrations.js.map +1 -0
  8. package/dist/docs/content.d.ts.map +1 -1
  9. package/dist/docs/content.js +33 -63
  10. package/dist/docs/content.js.map +1 -1
  11. package/dist/index.js +7 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/lib/api-client.d.ts +17 -0
  14. package/dist/lib/api-client.d.ts.map +1 -1
  15. package/dist/lib/api-client.js.map +1 -1
  16. package/dist/lib/file-loader.d.ts +39 -0
  17. package/dist/lib/file-loader.d.ts.map +1 -1
  18. package/dist/lib/file-loader.js +73 -0
  19. package/dist/lib/file-loader.js.map +1 -1
  20. package/dist/lib/file-loader.test.js +22 -1
  21. package/dist/lib/file-loader.test.js.map +1 -1
  22. package/dist/skill/docs/changelog.md +1118 -1
  23. package/dist/skill/docs/compiler/config/domains.md +70 -10
  24. package/dist/skill/docs/compiler/config/index.md +74 -3
  25. package/dist/skill/docs/compiler/config/output.md +1 -1
  26. package/dist/skill/docs/compiler/config/providers.md +6 -12
  27. package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
  28. package/dist/skill/docs/compiler/config/variables.md +0 -30
  29. package/dist/skill/docs/compiler/definitions/access.md +357 -3
  30. package/dist/skill/docs/compiler/definitions/actions.md +85 -8
  31. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  32. package/dist/skill/docs/compiler/index.md +15 -34
  33. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  34. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  35. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  36. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  37. package/dist/skill/docs/compiler/targets/index.md +6 -34
  38. package/dist/skill/docs/index.md +2 -5
  39. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  40. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  41. package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
  42. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  43. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  44. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  45. package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
  46. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  47. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  48. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  49. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  50. package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
  51. package/package.json +1 -1
  52. package/src/skill/docs/changelog.md +1057 -0
  53. package/src/skill/docs/compiler/config/domains.md +26 -0
  54. package/src/skill/docs/compiler/config/index.md +74 -3
  55. package/src/skill/docs/compiler/config/providers.md +6 -12
  56. package/src/skill/docs/compiler/config/single-tenant.md +1 -1
  57. package/src/skill/docs/compiler/config/variables.md +0 -30
  58. package/src/skill/docs/compiler/definitions/access.md +357 -3
  59. package/src/skill/docs/compiler/definitions/actions.md +85 -8
  60. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  61. package/src/skill/docs/compiler/index.md +15 -34
  62. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  63. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  64. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  65. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  66. package/src/skill/docs/compiler/targets/index.md +6 -34
  67. package/src/skill/docs/index.md +2 -5
  68. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  69. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  70. package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
  71. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  72. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  73. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  74. package/src/skill/docs/stack/account-ui/hooks.md +4 -0
  75. package/src/skill/docs/stack/account-ui/index.md +5 -43
  76. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  77. package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
  78. package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
  79. package/src/skill/docs/stack/auth/plugins/index.md +32 -0
  80. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  81. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  82. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  83. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  85. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  86. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  87. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  88. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  89. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  90. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  91. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  92. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  93. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -127,7 +127,7 @@ export default defineAction({
127
127
  | `access` | Yes | Access control (roles, record conditions, or function) |
128
128
  | `execute` | Yes | Inline async arrow function (`async (ctx) => { … }`) |
129
129
  | `path` | Standalone only | Custom route path. Presence of `path` makes the action standalone. |
130
- | `method` | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: POST) |
130
+ | `method` | No | HTTP method: GET, POST, PUT, PATCH, DELETE (default: POST). GET actions parse `input` from query params; all other methods parse from the JSON body. See [GET vs POST for input](#get-vs-post-for-input). |
131
131
  | `responseType` | No | Response format: json, stream, file (default: json) |
132
132
  | `sideEffects` | No | Hint for AI tools: `'sync'`, `'async'`, or `'fire-and-forget'` |
133
133
  | `allowRawSql` | No | Explicit compile-time opt-in for raw SQL in execute code |
@@ -304,9 +304,9 @@ land in `success[]` masked the same way the single-record response is.
304
304
 
305
305
  | Provider | failFast | transactional | Behavior |
306
306
  |---|---|---|---|
307
- | postgres / supabase / neon / libsql / sqlite drivers | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
307
+ | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
308
308
  | (any) | `false` | `false` | Independent per-record outcomes, partial success |
309
- | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed |
309
+ | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed (D1 has no `db.transaction`) |
310
310
 
311
311
  **Constraints:**
312
312
 
@@ -404,6 +404,50 @@ export default defineAction({
404
404
  });
405
405
  ```
406
406
 
407
+ ### GET vs POST for input
408
+
409
+ GET actions read `input` from URL query parameters; every other method (POST,
410
+ PUT, PATCH, DELETE) reads from the JSON body. The Zod schema is the same in
411
+ both cases — the compiler picks the right parser based on `method`.
412
+
413
+ ```typescript
414
+ // GET — input populated from ?q=…&limit=…
415
+ defineAction({
416
+ method: "GET",
417
+ path: "/search",
418
+ input: z.object({
419
+ q: z.string(),
420
+ limit: z.coerce.number().int().positive().max(100).default(20),
421
+ }),
422
+ access: { roles: ["AUTHENTICATED"] },
423
+ async execute({ input }) {
424
+ // input is { q: string, limit: number } — fully typed.
425
+ },
426
+ });
427
+ ```
428
+
429
+ Repeated query keys (`?tag=a&tag=b`) come through as arrays automatically;
430
+ single values stay as strings. Use Zod's `.coerce.number()` /
431
+ `.coerce.boolean()` when you want typed primitives from the parsed strings.
432
+
433
+ **Use POST when input is structured.** GET requests cannot carry a JSON body
434
+ in any of the surfaces Quickback APIs are commonly called from:
435
+
436
+ - Browsers throw on `fetch(url, { method: 'GET', body })`.
437
+ - CDNs and caches key on URL+method; a GET with a body either gets the body
438
+ stripped at the edge or cache-collides with semantically different requests.
439
+ - OpenAPI client generators (axios, openapi-fetch, openapi-typescript-codegen)
440
+ refuse to emit GET-with-body, so the generated SDKs break.
441
+ - The MCP agent surface treats GET as parameter-only — agents calling a GET
442
+ action will only see what the URL exposes.
443
+
444
+ If your action takes nested objects, arrays of objects, or large inputs that
445
+ don't serialize cleanly to a query string, set `method: "POST"`. POST doesn't
446
+ imply "this writes data" — it's the right method whenever the request body is
447
+ load-bearing. Use the response shape (`responseType: "json"`, or just the data
448
+ your handler returns) to convey read semantics; HTTP method choice is about
449
+ input transport, not action intent.
450
+
407
451
  ## Access Configuration
408
452
 
409
453
  Access controls who can execute an action and under what conditions.
@@ -502,13 +546,46 @@ access: async (ctx, record) => {
502
546
  }
503
547
  ```
504
548
 
505
- ### Relationship-roles in actions (v1 limitation)
549
+ ### Relationship-roles in actions
550
+
551
+ **v0.19+** — standalone actions now support relationship-roles in `access.roles` directly. Declare the relationship under `authz.relationships` with optional `loads` / `exposeAs` for ctx hydration, and reference the role by name on the action:
552
+
553
+ ```ts
554
+ // quickback.config.ts
555
+ authz: {
556
+ relationships: {
557
+ attendeeOf: {
558
+ from: 'guests',
559
+ subject: { column: 'userId', equals: 'ctx.userId' },
560
+ resource: { column: 'eventId' },
561
+ where: { status: 'confirmed' },
562
+ loads: 'events',
563
+ exposeAs: 'event',
564
+ },
565
+ },
566
+ roles: { attendee: { via: 'attendeeOf' } },
567
+ }
568
+
569
+ // features/chat/actions/getInbox.ts
570
+ export default defineAction({
571
+ path: '/chat/get-inbox',
572
+ input: z.object({ eventId: z.number().int().positive() }),
573
+ access: { roles: ['admin', 'member', 'attendee'] },
574
+ execute: async ({ db, ctx, input }) => {
575
+ // The resolver already verified attendance and loaded ctx.event.
576
+ // No hand-rolled `SELECT … FROM guests WHERE …` needed.
577
+ },
578
+ });
579
+ ```
580
+
581
+ The action's surface (path params + input fields) must expose the relationship's `resource.column`. At v0.19 a missing key emits a `[quickback:authz]` warning and skips resolver emission; at v0.20 it becomes a compile error. See [Access — standalone actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019) for the full mechanism.
506
582
 
507
- Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in action access blocks**. The compiler refuses to build with a clear error message because the binding semantics — which input field or which loaded record's column to check the relationship against — differ between record-actions and standalone-actions and require explicit declaration not yet wired in v1.
583
+ **Record-based actions** are NOT yet supported — the runtime evaluator fail-closes (403) on relationship arms reached without an inline gate. Until inline emission for record-based actions lands, either:
508
584
 
509
- The runtime evaluator fails closed on unrecognized relationship arms, so silent grants are impossible.
585
+ - Set `firewall: { exception: true }` on the action and gate manually in `execute()`, OR
586
+ - Apply the relationship at the resource's firewall layer (worked example below).
510
587
 
511
- **Workaround**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
588
+ **Resource-layer workaround for record-based actions**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
512
589
 
513
590
  ```typescript
514
591
  // quickback.config.ts
@@ -543,7 +620,7 @@ actions: {
543
620
 
544
621
  This pattern composes cleanly: the firewall guarantees the caller has the relationship to the record being acted on; the action's access list keeps the role surface obvious.
545
622
 
546
- A future `actions.<name>.relationshipBindings` declaration is on the roadmap to remove this limitation. See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture.
623
+ See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture, including `loads` / `exposeAs` and the `firewall: { exception: true }` escape hatch.
547
624
 
548
625
  ## Scoped Database
549
626
 
@@ -95,7 +95,7 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, cuid for libsql/bun-sqlite, `crypto.randomUUID()` for supabase, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
99
99
 
100
100
  ### q.scope() — tenant scope columns
101
101
 
@@ -123,10 +123,7 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
123
123
 
124
124
  ### Naming Convention
125
125
 
126
- By default, `q` picks the SQL column name from the JS key using the target database's conventional casing:
127
-
128
- - **Postgres family (Supabase, Neon, D1)** → `snake_case` (`organizationId` → `organization_id`)
129
- - **SQLite family (bun-sqlite, better-sqlite3, libsql)** → `camelCase` (`organizationId` → `organizationId`)
126
+ By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
130
127
 
131
128
  You can override for any project by setting `namingConvention` on the database provider config:
132
129
 
@@ -135,10 +132,9 @@ You can override for any project by setting `namingConvention` on the database p
135
132
  export default {
136
133
  providers: {
137
134
  database: {
138
- name: 'bun-sqlite',
135
+ name: 'cloudflare-d1',
139
136
  config: {
140
- path: './data/app.db',
141
- namingConvention: 'snake_case', // force snake_case everywhere
137
+ namingConvention: 'camelCase', // keep JS-style names in the SQL
142
138
  },
143
139
  },
144
140
  },
@@ -661,7 +657,7 @@ export default defineConfig({
661
657
 
662
658
  Use the Drizzle dialect that matches your database provider:
663
659
 
664
- ### SQLite (D1, Turso, better-sqlite3)
660
+ ### SQLite (Cloudflare D1)
665
661
 
666
662
  ```typescript
667
663
  import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
@@ -675,7 +671,7 @@ export const jobs = sqliteTable('jobs', {
675
671
  });
676
672
  ```
677
673
 
678
- ### PostgreSQL (Supabase, Neon)
674
+ ### PostgreSQL (Neon)
679
675
 
680
676
  ```typescript
681
677
  import { pgTable, text, serial, jsonb, boolean } from 'drizzle-orm/pg-core';
@@ -1,62 +1,44 @@
1
1
  # Quickback Compiler
2
2
 
3
- The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits production-ready output for your chosen target.
3
+ The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits a production Hono application for the **Quickback Stack** on Cloudflare.
4
4
 
5
5
  ```
6
- defineTable() ─┐ ┌─► Hono API (Cloudflare D1 / Neon)
7
- ├─► quickback compile┤
8
- defineActions()─┘ └─► RLS policies (Supabase)
6
+ defineTable() ─┐
7
+ ├─► quickback compile ─► Hono API on Cloudflare
8
+ defineActions()─┘ (D1 or Neon)
9
9
  ```
10
10
 
11
- The same definitions, the same DSL — pick the target that fits where you're deploying.
12
-
13
11
  ## What the compiler does
14
12
 
15
13
  When you run `quickback compile`, it:
16
14
 
17
15
  1. **Reads your definitions** — every `defineTable()`, `defineActions()`, and `defineConfig()` in your project
18
16
  2. **Validates security** — firewall, access, guards, and masking are checked for consistency
19
- 3. **Generates target output** — Hono routes + middleware + types + OpenAPI + MCP, or RLS migrations + helper functions
17
+ 3. **Generates output** — Hono routes + middleware + types + OpenAPI spec + MCP server + security artifacts
20
18
  4. **Emits database migrations** — runs `drizzle-kit generate` for schema changes
21
19
 
22
20
  ```
23
21
  quickback/
24
- ├── quickback.config.ts # Compiler configuration (target + providers)
22
+ ├── quickback.config.ts # Compiler configuration (providers, options)
25
23
  └── features/
26
24
  └── jobs/
27
25
  ├── jobs.ts # defineTable(...)
28
26
  └── actions.ts # defineActions(...)
29
27
  ```
30
28
 
31
- ## Two compile targets
32
-
33
- ### [Quickback for Hono API](/compiler/targets/hono-api)
29
+ ## The target: Hono on Cloudflare
34
30
 
35
- Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
31
+ [Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL via Hyperdrive.
36
32
 
37
33
  ```typescript
38
34
  providers: {
39
35
  runtime: defineRuntime('cloudflare'),
40
- database: defineDatabase('cloudflare-d1'),
36
+ database: defineDatabase('cloudflare-d1'), // or 'neon'
41
37
  auth: defineAuth('better-auth'),
42
38
  }
43
39
  ```
44
40
 
45
- ### [Quickback for Supabase](/compiler/targets/supabase-rls)
46
-
47
- Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your existing app code.
48
-
49
- ```typescript
50
- providers: {
51
- runtime: defineRuntime('supabase'),
52
- database: defineDatabase('supabase'),
53
- auth: defineAuth('supabase-auth'),
54
- }
55
- ```
56
-
57
- ## The shared core
58
-
59
- Whichever target you pick, the **input language is the same**:
41
+ ## The DSL
60
42
 
61
43
  - **[Definitions](/compiler/definitions)** — Schema, Firewall, Access, Guards, Masking, Views, Actions
62
44
  - **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
@@ -73,13 +55,12 @@ You don't run the compiler binary locally — it runs as a hosted service:
73
55
 
74
56
  1. **Define resources** in `quickback/features/`
75
57
  2. **Compile** with `quickback compile`
76
- 3. **Apply migrations** for your provider
77
- 4. **Test locally** with `npm run dev`
78
- 5. **Deploy** with `npm run deploy` (Hono target) or `supabase db push` (Supabase target)
58
+ 3. **Apply migrations** with `wrangler d1 migrations apply`
59
+ 4. **Test locally** with `wrangler dev`
60
+ 5. **Deploy** with `wrangler deploy`
79
61
 
80
62
  ## Next steps
81
63
 
82
64
  - [Getting Started](/compiler/getting-started) — Create your first project
83
- - [Definitions](/compiler/definitions) — The shared DSL
84
- - [Quickback for Hono API](/compiler/targets/hono-api) — Compile to a Hono app
85
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — Compile to RLS policies
65
+ - [Definitions](/compiler/definitions) — The DSL
66
+ - [Quickback for Hono API](/compiler/targets/hono-api) — Generated output reference
@@ -90,5 +90,4 @@ Your `wrangler.toml` needs these bindings:
90
90
 
91
91
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Step-by-step setup guide with full wrangler.toml configuration
92
92
  - [D1 Database](/compiler/targets/hono-api/database/d1) — D1 setup, multi-database pattern, and security architecture
93
- - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL with RLS
94
- - [Supabase Integration](/compiler/targets/supabase-rls) — Alternative: Supabase with RLS
93
+ - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL via Hyperdrive
@@ -141,4 +141,3 @@ src/
141
141
 
142
142
  - [D1](/compiler/targets/hono-api/database/d1) — SQLite at the edge
143
143
  - [Providers](/compiler/config/providers) — All database provider options
144
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — A different Postgres+RLS path that uses Supabase Auth instead of Better Auth
@@ -99,6 +99,25 @@ All actions (both standalone and record-based) receive a **scoped `db`** instanc
99
99
  - Tables with `deletedAt` — soft delete filter (`WHERE deletedAt IS NULL`)
100
100
  - `INSERT` operations auto-inject `organizationId` and `ownerId` from context
101
101
 
102
+ #### `userId` vs `ownerId` on feature tables
103
+
104
+ Use `ownerId` (not `userId`) for the row-owner column on a feature table. The compiler:
105
+
106
+ - Auto-firewalls reads on `ownerId` (`WHERE ownerId = ctx.userId`).
107
+ - Auto-stamps `ownerId` on insert from `ctx.userId`.
108
+ - Treats a `userId` column on a feature table as **informational** — almost always "a user this row references" (member, contact, invitee), not "the row owner."
109
+
110
+ A `userId` column on a feature table emits a compile-time warning. To resolve it:
111
+
112
+ - **Rename to `ownerId`** if the column controls access (most common case).
113
+ - **Rename to `linkedUserId`** (or similar) if the column is informational — explicit naming prevents future confusion.
114
+ - **Declare explicit firewall** if `userId` really is the access column on that table:
115
+ ```ts
116
+ firewall: [{ field: 'userId', equals: 'ctx.userId' }]
117
+ ```
118
+
119
+ Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) use `userId` by convention. Those are not feature tables and don't pass through the auto-firewall — the warning only fires on resources you define in your `quickback/` folder.
120
+
102
121
  ```typescript
103
122
  // Your handler receives a scoped db — no manual filtering needed
104
123
  execute: async ({ db, ctx, input }) => {
@@ -264,7 +264,7 @@ rollback.
264
264
 
265
265
  | Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
266
266
  |----------|----------|-----------|----------------------|----------|
267
- | `PATCH /batch` (update) | postgres / supabase / neon / libsql / better-sqlite3 / bun-sqlite | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
267
+ | `PATCH /batch` (update) | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
268
268
  | `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
269
269
  | `PATCH /batch` (update) | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — D1 has no `db.transaction`. Records before the failure stay committed. |
270
270
  | `PUT /batch` (upsert) | tx-supporting | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
@@ -1,47 +1,19 @@
1
1
  # Compile Targets
2
2
 
3
- The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits production output for the target you choose.
3
+ The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits a production Hono application for the **Quickback Stack** on Cloudflare.
4
4
 
5
- ## The two targets
5
+ ## [Quickback for Hono API](/compiler/targets/hono-api)
6
6
 
7
- ### [Quickback for Hono API](/compiler/targets/hono-api)
8
-
9
- Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
7
+ Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server, security artifacts. Pair with **Cloudflare D1** for SQLite at the edge or **Neon** for full PostgreSQL via Hyperdrive.
10
8
 
11
9
  ```typescript
12
10
  providers: {
13
11
  runtime: defineRuntime('cloudflare'),
14
- database: defineDatabase('cloudflare-d1'),
12
+ database: defineDatabase('cloudflare-d1'), // or 'neon'
15
13
  auth: defineAuth('better-auth'),
16
14
  }
17
15
  ```
18
16
 
19
- Use this target when you want Quickback to generate the entire API surface, not just security policies.
20
-
21
- ### [Quickback for Supabase](/compiler/targets/supabase-rls)
22
-
23
- Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your application code.
24
-
25
- ```typescript
26
- providers: {
27
- runtime: defineRuntime('supabase'),
28
- database: defineDatabase('supabase'),
29
- auth: defineAuth('supabase-auth'),
30
- }
31
- ```
32
-
33
- Use this target when you're already on Supabase and want a typed DSL for RLS.
34
-
35
- ## At a glance
36
-
37
- | | Hono API | Supabase RLS |
38
- |---|----------|--------------|
39
- | What's generated | Routes, middleware, types, OpenAPI, MCP, RLS (Neon only) | RLS policies + helper functions only |
40
- | Database | Cloudflare D1 or Neon Postgres | Supabase Postgres |
41
- | Auth | Better Auth | Supabase Auth |
42
- | Application code | Compiler-generated | You write your own |
43
- | Deployment | `wrangler deploy` (or any Hono runtime) | `supabase db push` |
44
-
45
- ## The shared core
17
+ ## The DSL
46
18
 
47
- Whichever target you pick, the input is the same. See [Definitions](/compiler/definitions) for the DSL that powers both.
19
+ See [Definitions](/compiler/definitions) for the schema + security DSL — the same input drives every output the compiler emits.
@@ -1,6 +1,6 @@
1
1
  # Quickback Documentation
2
2
 
3
- Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API or PostgreSQL Row Level Security policies. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
3
+ Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API running on Cloudflare Workers, plus the Account UI and CMS that ride alongside it. The Quickback Stack is the Supabase alternative on Cloudflare.
4
4
 
5
5
  ## Quick start
6
6
 
@@ -49,12 +49,9 @@ Request → Firewall → Access → Guards → Masking → Response
49
49
 
50
50
  ### Quickback Compiler
51
51
 
52
- [**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to one of two targets:
52
+ [**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to a complete Hono application on Cloudflare:
53
53
 
54
54
  - **[Quickback for Hono API](/compiler/targets/hono-api)** — A complete Hono application on Cloudflare D1 or Neon, with CRUD, batch endpoints, OpenAPI, and an MCP server.
55
- - **[Quickback for Supabase](/compiler/targets/supabase-rls)** — PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
56
-
57
- The same `defineTable()` definitions work for both targets.
58
55
 
59
56
  **Start here:**
60
57
  - **[Getting Started](/compiler/getting-started)** — Create your first project
@@ -1,18 +1,6 @@
1
1
  # Customization
2
2
 
3
- Customize the Account UI to match your brand and messaging.
4
-
5
- **Standalone (template):** Configure via environment variables, edit `src/config/app.ts` directly, or use `setAppConfig()` for runtime overrides.
6
-
7
- **Library (npm):** Configure entirely via `setAppConfig()`. Import it from `quickback-better-auth-account-ui` instead of `@/config/app`.
8
-
9
- > **Library imports**
10
- >
11
- > All `setAppConfig` examples below use the standalone import path (`@/config/app`). If you're using library mode, replace with:
12
- > ```ts
13
- > import { setAppConfig } from 'quickback-better-auth-account-ui';
14
- > ```
15
-
3
+ Customize the Account UI to match your brand and messaging. Branding is driven by the `account` block in `quickback.config.ts` and the environment variables the compiler bakes in at build time.
16
4
 
17
5
  ## Branding
18
6
 
@@ -373,6 +361,6 @@ import './custom-styles.css'; // Your overrides
373
361
 
374
362
  ## Next Steps
375
363
 
376
- - **[Worker Setup](/stack/account-ui/worker)** - Deploy your customized UI
364
+ - **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles your customized UI
377
365
  - **[Environment Variables](/stack/account-ui/environment-variables)** - Complete configuration reference
378
366
  - **[Feature Flags](/stack/account-ui/features)** - Enable/disable features
@@ -167,6 +167,11 @@ VITE_ENABLE_FILE_UPLOADS=false
167
167
  ```bash
168
168
  # Enable multi-tenant organizations (default: true)
169
169
  ENABLE_ORGANIZATIONS=true
170
+
171
+ # Enable Teams (sub-groups within an organization) (default: false)
172
+ # Auto-set to true when the BA config has organization({ teams: { enabled: true } }).
173
+ # When false the Teams tab is hidden and the auth client doesn't expose team APIs.
174
+ VITE_ENABLE_ORG_TEAMS=false
170
175
  ```
171
176
 
172
177
  ### Admin Features
@@ -218,6 +223,7 @@ ENABLE_PASSKEY=true
218
223
  ENABLE_EMAIL_OTP=true
219
224
  ENABLE_PASSWORD=false
220
225
  ENABLE_ORGANIZATIONS=true
226
+ VITE_ENABLE_ORG_TEAMS=true
221
227
  ENABLE_ADMIN=true
222
228
  VITE_ENABLE_FILE_UPLOADS=true
223
229
  DISABLE_EMAIL_STATUS_CHECK=false
@@ -322,4 +328,4 @@ Check the browser console for configuration warnings.
322
328
 
323
329
  - **[Feature Flags](/stack/account-ui/features)** - Detailed feature configuration
324
330
  - **[Customization](/stack/account-ui/customization)** - Customize labels and messages
325
- - **[Worker Setup](/stack/account-ui/worker)** - Deploy to Cloudflare
331
+ - **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles Account UI
@@ -32,10 +32,10 @@ When `auth.admin` is `false` (the default), admin routes are excluded from the S
32
32
 
33
33
  The admin panel is restricted to users with `role: "admin"` on their Better Auth user record. Non-admin users are redirected away from `/admin`.
34
34
 
35
- To grant admin access to a user, use the Better Auth admin API:
35
+ To grant admin access to a user, use the Better Auth admin plugin:
36
36
 
37
37
  ```bash
38
- curl -X POST https://api.example.com/admin/v1/set-role \
38
+ curl -X POST https://api.example.com/auth/v1/admin/set-role \
39
39
  -H "Authorization: Bearer $TOKEN" \
40
40
  -H "Content-Type: application/json" \
41
41
  -d '{ "userId": "user_123", "role": "admin" }'
@@ -13,9 +13,7 @@ account: {
13
13
  }
14
14
  ```
15
15
 
16
- The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` into the Account SPA's
17
- build env. For standalone Account UI deployments (built outside the
18
- compiler), set `VITE_ENABLE_FILE_UPLOADS=true` in `.env` directly.
16
+ The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` into the Account SPA's build env.
19
17
 
20
18
  ## Upload Flow
21
19
 
@@ -27,7 +25,7 @@ compiler), set `VITE_ENABLE_FILE_UPLOADS=true` in `.env` directly.
27
25
 
28
26
  ## Requirements
29
27
 
30
- - `account.fileUploads: true` (or `VITE_ENABLE_FILE_UPLOADS=true` for standalone)
28
+ - `account.fileUploads: true`
31
29
  - R2 bucket or S3-compatible storage configured
32
30
  - Upload endpoints available in your API
33
31
 
@@ -288,4 +288,4 @@ DISABLE_EMAIL_STATUS_CHECK=true # Allow test emails
288
288
 
289
289
  - **[Environment Variables](/stack/account-ui/environment-variables)** - Complete variable reference
290
290
  - **[Customization](/stack/account-ui/customization)** - Customize UI text and labels
291
- - **[Worker Setup](/stack/account-ui/worker)** - Deploy your configuration
291
+ - **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds Account UI into your Worker
@@ -1,27 +1,47 @@
1
1
  # Organizations
2
2
 
3
- Account UI provides a complete organization management interface when `ENABLE_ORGANIZATIONS=true`.
3
+ Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
4
4
 
5
5
  ## Organization CRUD
6
6
 
7
- - Create new organizations
8
- - Update organization name and settings
9
- - Delete organizations (owner only)
7
+ - Create new organizations, with `checkSlug` debounce on the slug field
8
+ - Update name, **slug** (rename navigates to the new URL), **metadata** (JSON object), and logo
9
+ - Delete organizations — gated on the `organization:delete` permission (default: owner)
10
10
 
11
11
  ## Member Management
12
12
 
13
- - Invite members by email
13
+ - Invite members by email (with an optional team picker when teams are enabled)
14
14
  - Assign roles: **owner**, **admin**, **member**
15
- - Remove members
16
- - Transfer ownership
15
+ - Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
16
+ - Leave the organization
17
+
18
+ > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above."
17
19
 
18
20
  ## Invitations
19
21
 
20
- - Pending invitation list
21
- - Resend invitations
22
- - Cancel invitations
22
+ - Pending invitation list, per organization
23
+ - Resend, cancel (per-org), accept, and reject (per-user)
24
+ - Pending invites across organizations land on the user's `/dashboard`
25
+ - Invitations carry an optional `teamId` when teams are enabled — the invitee joins that team on accept
23
26
 
24
- > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above."
27
+ ## Teams
28
+
29
+ Set `organization({ teams: { enabled: true } })` in your Better Auth config. The compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the SPA exposes:
30
+
31
+ - **Teams tab** on each organization, split into "Your teams" and "Other teams"
32
+ - **Team detail** page with member roster, add/remove members
33
+ - **Active-team picker** in the organization header — switches `session.activeTeamId` via `setActiveTeam`, so server-side handlers can scope by team
34
+ - **Team-aware invitations** — when sending an invite, optionally pick a team; the member is added on accept
35
+
36
+ Per-team actions (create / rename / delete / add-member / remove-member) gate on the `team:create`, `team:update`, and `team:delete` permissions from Better Auth's default statements.
37
+
38
+ ## Permission-aware UI
39
+
40
+ Account UI uses Better Auth's `checkRolePermission` API instead of hardcoded role checks. The `OrganizationContext` exposes a `can(resource, action)` helper that handles the default statements (`organization`, `member`, `invitation`, `team`, `ac`) and respects any custom roles you've registered via the BA `ac` option.
41
+
42
+ Multi-role users — Better Auth stores multiple roles as a comma-separated string — are handled by checking each role independently; the action is allowed if any one of them grants it.
43
+
44
+ This means projects that ship custom roles get a UI that matches what their server actually authorizes, without modifying the Account SPA.
25
45
 
26
46
  ## Related
27
47
 
@@ -12,6 +12,7 @@ quickback/
12
12
  after-user-create.ts
13
13
  before-user-create.ts
14
14
  after-session-create.ts
15
+ after-admin-user-create.ts
15
16
  ```
16
17
 
17
18
  Each file has a single default export — an `async (entity, ctx) => ...` function. The filename determines which Better Auth event the hook fires on.
@@ -23,6 +24,9 @@ Each file has a single default export — an `async (entity, ctx) => ...` functi
23
24
  | `before-user-create.ts` | `databaseHooks.user.create.before` | `User` | `void \| { data?: Partial<User> }` |
24
25
  | `after-user-create.ts` | `databaseHooks.user.create.after` | `User` | `void` |
25
26
  | `after-session-create.ts` | `databaseHooks.session.create.after` | `Session` | `void` |
27
+ | `after-admin-user-create.ts` | `databaseHooks.user.create.after` (filtered) | `User` | `void` |
28
+
29
+ `after-admin-user-create.ts` is a **virtual event** — it wires into the same Better Auth `user.create.after` slot as the generic `after-user-create.ts`, but the compiler wraps the call in a runtime filter on the BA context path so it only fires when the row was created via the admin plugin's `POST /admin/create-user` endpoint. Use it for first-time-user provisioning (welcome email, default org assignment) without inspecting `_baCtx?.context?.path` by hand. The generic `after-user-create.ts` still runs for every signup, including admin-created ones.
26
30
 
27
31
  Filenames outside this set are a hard compile-time error so a typo never silently disables a hook. Add events by extending [`apps/compiler/src/parser/hooks.ts`](https://github.com/paulstenhouse/quickback-compiler) (and the matching CLI mirror).
28
32