@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.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,192 @@
1
+ # Getting Started
2
+
3
+ Get started with Quickback in minutes. This guide shows you how to define a complete table with security configuration.
4
+
5
+ ## Install the CLI
6
+
7
+ ```bash
8
+ npm install -g @quickback-dev/cli
9
+ ```
10
+
11
+ ## Create a Project
12
+
13
+ ```bash
14
+ quickback create cloudflare my-app
15
+ cd my-app
16
+ ```
17
+
18
+ This scaffolds a complete project with:
19
+ - `quickback.config.ts` — Project configuration
20
+ - `quickback/features/` — Your table definitions
21
+ - Example feature with full security configuration
22
+
23
+ **Available templates:**
24
+ - `cloudflare` — Cloudflare Workers + D1 + Better Auth (free)
25
+ - `blog` — Single-tenant blog (PUBLIC reads, admin writes) (free)
26
+ - `empty` — Cloudflare scaffold, no example features (free)
27
+ - `multi-tenant` — Full SaaS with orgs, teams, billing (pro)
28
+
29
+ ## File Structure
30
+
31
+ Each table gets its own file with schema and security config together:
32
+
33
+ ```
34
+ quickback/
35
+ ├── quickback.config.ts
36
+ └── features/
37
+ └── jobs/
38
+ ├── jobs.ts # Table + security config
39
+ ├── applications.ts # Related table + config
40
+ ├── actions.ts # Custom actions (optional)
41
+ └── handlers/ # Action handlers (optional)
42
+ └── close-job.ts
43
+ ```
44
+
45
+ ## Complete Example
46
+
47
+ Here's a complete `jobs` table with all security layers in a single `feature()` call:
48
+
49
+ ```typescript
50
+ // quickback/features/jobs/jobs.ts
51
+ import { feature, q } from '@quickback/compiler';
52
+
53
+ export default feature('jobs', {
54
+ columns: {
55
+ id: q.id(),
56
+ title: q.text().required(),
57
+ department: q.text().required(),
58
+ status: q.text().default('draft').required(), // draft | open | closed
59
+ salaryMin: q.int().optional(),
60
+ salaryMax: q.int().optional(),
61
+ // Ownership — required for firewall data isolation
62
+ organizationId: q.scope("organization"),
63
+ },
64
+
65
+ // 1. FIREWALL — Data isolation
66
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
67
+
68
+ // 2. GUARDS — Field modification rules
69
+ guards: {
70
+ createable: ["title", "department", "status", "salaryMin", "salaryMax"],
71
+ updatable: ["title", "department", "status"],
72
+ },
73
+
74
+ // 3. READ — Collection + per-id GET (gates GET / and GET /:id)
75
+ read: {
76
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
77
+ pageSize: 25,
78
+ },
79
+
80
+ // 4. CRUD — Write operations
81
+ crud: {
82
+ create: { access: { roles: ["owner", "hiring-manager"] } },
83
+ update: { access: { roles: ["owner", "hiring-manager"] } },
84
+ delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
85
+ },
86
+ });
87
+ ```
88
+
89
+ One import, one export, every security layer declared in one place. Secure by default — no CRUD routes ship until you opt in with `crud: { … }`.
90
+
91
+ ### Alternatives — same result, different shape
92
+
93
+ If you'd rather split the table declaration from the security config (e.g. to reference the table in an action file), use the two-export form. Identical output:
94
+
95
+ ```typescript
96
+ import { q, defineTable } from '@quickback/compiler';
97
+
98
+ export const jobs = q.table('jobs', {
99
+ id: q.id(),
100
+ title: q.text().required(),
101
+ // … same columns
102
+ });
103
+
104
+ export default defineTable(jobs, {
105
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
106
+ // … same config
107
+ });
108
+
109
+ export type Job = typeof jobs.$infer;
110
+ ```
111
+
112
+ Or if you're interop'ing with existing Drizzle schemas, you can author with `sqliteTable` / `pgTable` directly — the compiler dispatches per file, and all forms can coexist in the same project.
113
+
114
+ See [feature() — single-export sugar](/compiler/definitions/feature) and [Schema: choosing between `q` and Drizzle](/compiler/definitions/schema#choosing-between-q-and-drizzle) for the full picture.
115
+
116
+ ## What Each Layer Does
117
+
118
+ 1. **Firewall**: Automatically adds `WHERE organizationId = ?` to every query. Users in Org A can never see Org B's data.
119
+ 2. **Guards**: Controls which fields can be modified — `createable` for POST, `updatable` for PATCH, `protected` for action-only fields.
120
+ 3. **CRUD Access**: Role-based access control for each operation. All roles can read, only hiring managers can write.
121
+
122
+ ## Compile and Run
123
+
124
+ ```bash
125
+ # Log in (first time only)
126
+ quickback login
127
+
128
+ # Compile your definitions
129
+ quickback compile
130
+
131
+ # Run locally
132
+ npm run dev
133
+ ```
134
+
135
+ ## Generated Endpoints
136
+
137
+ Quickback generates these endpoints from the example above:
138
+
139
+ | Method | Endpoint | Description |
140
+ |--------|----------|-------------|
141
+ | `GET` | `/api/v1/jobs` | List jobs (all roles) |
142
+ | `GET` | `/api/v1/jobs/:id` | Get single job |
143
+ | `POST` | `/api/v1/jobs` | Create job (hiring managers only) |
144
+ | `PATCH` | `/api/v1/jobs/:id` | Update job (hiring managers only) |
145
+ | `DELETE` | `/api/v1/jobs/:id` | Soft delete job (hiring managers only) |
146
+
147
+ ## Test Your API
148
+
149
+ After `quickback compile` and `npm run dev`, your API is running locally. Open a second terminal and try these requests:
150
+
151
+ ```bash
152
+ # 1. Create a user account
153
+ curl -X POST http://localhost:8787/api/auth/sign-up/email \
154
+ -H "Content-Type: application/json" \
155
+ -d '{"email": "admin@example.com", "password": "securepassword123", "name": "Admin"}'
156
+
157
+ # 2. Sign in and get a session token
158
+ curl -X POST http://localhost:8787/api/auth/sign-in/email \
159
+ -H "Content-Type: application/json" \
160
+ -d '{"email": "admin@example.com", "password": "securepassword123"}'
161
+ # → Response includes a session token in Set-Cookie header
162
+
163
+ # 3. Create a record (use the session cookie from step 2)
164
+ curl -X POST http://localhost:8787/api/v1/jobs \
165
+ -H "Content-Type: application/json" \
166
+ -H "Cookie: better-auth.session_token=<token>" \
167
+ -d '{"title": "Senior Engineer", "department": "Engineering", "status": "open"}'
168
+
169
+ # 4. List records
170
+ curl http://localhost:8787/api/v1/jobs \
171
+ -H "Cookie: better-auth.session_token=<token>"
172
+ ```
173
+
174
+ > Cloudflare templates run on port `8787` (wrangler dev). Check your terminal output for the exact URL.
175
+
176
+
177
+ ## Next Steps
178
+
179
+ - [Template Walkthroughs](/compiler/getting-started/templates) — Detailed setup guides
180
+ - [Full Example](/compiler/getting-started/full-example) — Complete resource walkthrough
181
+ - [Database Schema](/compiler/definitions/schema) — Column types, relations, audit fields
182
+ - [Firewall](/compiler/definitions/firewall) — Data isolation patterns
183
+ - [Access](/compiler/definitions/access) — Role & condition-based control
184
+ - [Guards](/compiler/definitions/guards) — Field modification rules
185
+ - [Masking](/compiler/definitions/masking) — Field redaction for sensitive data
186
+ - [Actions](/compiler/definitions/actions) — Custom business logic endpoints
187
+
188
+ ## See Also
189
+
190
+ - [Quickback Stack](/stack) — The runtime environment where your compiled API runs (D1, KV, R2, auth)
191
+ - [Account UI](/stack/account-ui) — Pre-built authentication and account management UI
192
+ - [Using the API](/compiler/targets/hono-api/using-the-api) — CRUD endpoints, filtering, and batch operations
@@ -0,0 +1,225 @@
1
+ # Common Patterns
2
+
3
+ Quick recipes for common scenarios. Each pattern shows the complete `defineTable` configuration.
4
+
5
+ ## Public Read, Authenticated Write
6
+
7
+ A job board where all team members can browse open positions but only hiring managers can create or edit jobs:
8
+
9
+ ```typescript
10
+ // quickback/features/jobs/jobs.ts
11
+ export default defineTable(jobs, {
12
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
13
+ guards: {
14
+ createable: ["title", "department", "status", "salaryMin", "salaryMax"],
15
+ updatable: ["title", "department", "status"],
16
+ },
17
+ read: {
18
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
19
+ },
20
+ crud: {
21
+ create: { access: { roles: ["owner", "hiring-manager"] } },
22
+ update: { access: { roles: ["owner", "hiring-manager"] } },
23
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
24
+ },
25
+ });
26
+ ```
27
+
28
+ ## User-Scoped Personal Data
29
+
30
+ Interview notes that belong to a specific interviewer. Each interviewer only sees their own notes:
31
+
32
+ ```typescript
33
+ // Schema includes both organizationId AND ownerId (q DSL)
34
+ import { q, defineTable } from "@quickback/compiler";
35
+
36
+ export const interviewNotes = q.table("interview_notes", {
37
+ id: q.id(),
38
+ candidateId: q.text().required(),
39
+ content: q.text().required(),
40
+ rating: q.int().optional(),
41
+ organizationId: q.scope("organization"),
42
+ ownerId: q.text().required(),
43
+ });
44
+
45
+ export default defineTable(interviewNotes, {
46
+ firewall: [
47
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
48
+ { field: 'ownerId', equals: 'ctx.userId' }, // Only the interviewer can see their own notes
49
+ ],
50
+ guards: {
51
+ createable: ["candidateId", "content", "rating"],
52
+ updatable: ["content", "rating"],
53
+ },
54
+ read: {
55
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
56
+ },
57
+ crud: {
58
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
59
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
60
+ delete: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
61
+ },
62
+ });
63
+ ```
64
+
65
+ The owner predicate (`{ field: 'ownerId', equals: 'ctx.userId' }`) means even hiring managers can only see notes they authored. To let hiring managers see all notes regardless of author, drop the owner predicate from the firewall and gate per-id access via record conditions instead.
66
+
67
+ ## Multi-Table Feature with Internal Tables
68
+
69
+ A feature with a main table exposed via API and a junction table used only in actions:
70
+
71
+ ```typescript
72
+ // quickback/features/applications/applications.ts — exposed via API
73
+ export default defineTable(applications, {
74
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
75
+ guards: {
76
+ createable: ["candidateId", "jobId", "stage", "notes"],
77
+ updatable: ["notes"],
78
+ },
79
+ read: {
80
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
81
+ },
82
+ crud: {
83
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
84
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
85
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
86
+ },
87
+ });
88
+ ```
89
+
90
+ ```typescript
91
+ // quickback/features/applications/interview-scores.ts — internal, no API routes
92
+ // No default export = no routes generated
93
+ export const interviewScores = sqliteTable("interview_scores", {
94
+ applicationId: text("application_id").notNull(),
95
+ interviewerId: text("interviewer_id").notNull(),
96
+ score: integer("score").notNull(),
97
+ feedback: text("feedback"),
98
+ organizationId: text("organization_id").notNull(), // Always scope junction tables
99
+ });
100
+ ```
101
+
102
+ ```typescript
103
+ // quickback/features/applications/actions.ts — uses the internal table
104
+ import { defineActions } from "@quickback/compiler";
105
+ import { applications } from "./applications";
106
+ import { interviewScores } from "./interview-scores";
107
+
108
+ export default defineActions(applications, {
109
+ submitScore: {
110
+ type: "record",
111
+ input: z.object({ score: z.number().min(1).max(5), feedback: z.string() }),
112
+ access: { roles: ["owner", "hiring-manager", "interviewer"] },
113
+ execute: async ({ db, record, input, ctx }) => {
114
+ await db.insert(interviewScores).values({
115
+ applicationId: record.id,
116
+ interviewerId: ctx.userId,
117
+ score: input.score,
118
+ feedback: input.feedback,
119
+ });
120
+ return record;
121
+ },
122
+ },
123
+ });
124
+ ```
125
+
126
+ ## Admin-Only Status Field
127
+
128
+ A field that only hiring managers can modify, but everyone can see:
129
+
130
+ ```typescript
131
+ export default defineTable(applications, {
132
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
133
+ guards: {
134
+ createable: ["candidateId", "jobId", "notes"],
135
+ updatable: ["notes"], // Recruiters can only update notes
136
+ protected: ["stage"], // Stage can only be changed via actions
137
+ },
138
+ read: {
139
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
140
+ },
141
+ crud: {
142
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
143
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
144
+ delete: { access: { roles: ["hiring-manager"] } },
145
+ },
146
+ });
147
+ ```
148
+
149
+ Then create an action that hiring managers use to change stage:
150
+
151
+ ```typescript
152
+ // quickback/features/applications/actions.ts
153
+ export default defineActions(applications, {
154
+ advanceStage: {
155
+ type: "record",
156
+ input: z.object({ stage: z.enum(["applied", "screening", "interview", "offer", "hired", "rejected"]) }),
157
+ access: { roles: ["hiring-manager"] },
158
+ execute: async ({ db, record, input }) => {
159
+ await db.update(applications).set({ stage: input.stage }).where(eq(applications.id, record.id));
160
+ return { ...record, stage: input.stage };
161
+ },
162
+ },
163
+ });
164
+ ```
165
+
166
+ ## Sensitive Data with Role-Based Masking
167
+
168
+ A candidate record where PII is masked differently per role:
169
+
170
+ ```typescript
171
+ export default defineTable(candidates, {
172
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
173
+ guards: {
174
+ createable: ["name", "email", "phone", "resumeUrl", "source"],
175
+ updatable: ["name", "phone"],
176
+ },
177
+ masking: {
178
+ email: { type: "email", show: { roles: ["hiring-manager", "recruiter"] } },
179
+ phone: { type: "phone", show: { roles: ["hiring-manager", "recruiter"] } },
180
+ },
181
+ read: {
182
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
183
+ },
184
+ crud: {
185
+ create: { access: { roles: ["hiring-manager", "recruiter"] } },
186
+ update: { access: { roles: ["hiring-manager", "recruiter"] } },
187
+ delete: { access: { roles: ["hiring-manager"] } },
188
+ },
189
+ });
190
+ ```
191
+
192
+ | Role | email | phone |
193
+ |------|-------|-------|
194
+ | hiring-manager | `jane@example.com` | `555-123-4567` |
195
+ | recruiter | `jane@example.com` | `555-123-4567` |
196
+ | interviewer | `j***@e******.com` | `***-***-4567` |
197
+
198
+ ## External System Sync
199
+
200
+ An import table for syncing candidates from an external ATS via PUT/upsert:
201
+
202
+ ```typescript
203
+ // quickback/features/ats-imports/ats-imports.ts
204
+ export default defineTable(atsImports, {
205
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
206
+ guards: {
207
+ createable: ["externalId", "source", "candidateName", "candidateEmail", "rawPayload"],
208
+ updatable: ["candidateName", "candidateEmail", "rawPayload", "syncedAt"],
209
+ },
210
+ read: {
211
+ access: { roles: ["owner", "hiring-manager"] },
212
+ },
213
+ crud: {
214
+ create: { access: { roles: ["owner", "hiring-manager"] } },
215
+ update: { access: { roles: ["owner", "hiring-manager"] } },
216
+ delete: { access: { roles: ["owner"] } },
217
+ },
218
+ });
219
+ ```
220
+
221
+ ## See Also
222
+
223
+ - [Full Example](/compiler/getting-started/full-example) — Complete walkthrough with generated code
224
+ - [Firewall](/compiler/definitions/firewall) — All data isolation options
225
+ - [Actions](/compiler/definitions/actions) — Custom business logic
@@ -0,0 +1,280 @@
1
+ # Blog Template
2
+
3
+ The blog template creates a single-tenant backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts via Better Auth's admin plugin.
4
+
5
+ This template uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, no `organizationId` columns. Roles come from `user.role` instead of org membership.
6
+
7
+ ## Create the Project
8
+
9
+ ```bash
10
+ quickback create blog my-site
11
+ cd my-site
12
+ ```
13
+
14
+ This scaffolds a project with:
15
+
16
+ ```
17
+ my-site/
18
+ ├── quickback/
19
+ │ ├── quickback.config.ts # Single-tenant config
20
+ │ └── features/
21
+ │ └── posts/
22
+ │ ├── posts.ts # Schema + security (defineTable)
23
+ │ └── actions.ts # Publish/unpublish actions
24
+ ├── src/ # Compiled output (generated)
25
+ ├── package.json
26
+ ├── tsconfig.json
27
+ ├── wrangler.toml
28
+ └── drizzle.config.ts
29
+ ```
30
+
31
+ ## Generated Configuration
32
+
33
+ ### quickback.config.ts
34
+
35
+ ```typescript
36
+ export default {
37
+ name: "my-site",
38
+ template: "hono",
39
+ features: {
40
+ organizations: false,
41
+ },
42
+ providers: {
43
+ runtime: { name: "cloudflare", config: {} },
44
+ database: {
45
+ name: "cloudflare-d1",
46
+ config: { binding: "DB" },
47
+ },
48
+ auth: { name: "better-auth", config: {} },
49
+ },
50
+ };
51
+ ```
52
+
53
+ Key difference from the multi-tenant templates: `organizations: false` disables the Better Auth organization plugin. See [Single-Tenant Mode](/compiler/config/single-tenant) for details.
54
+
55
+ ### Posts Feature (posts.ts)
56
+
57
+ The template includes a `posts` feature with public read access and admin-only write access:
58
+
59
+ ```typescript
60
+ import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
61
+ import { defineTable } from "@quickback/compiler";
62
+
63
+ export const posts = sqliteTable("posts", {
64
+ id: text("id").primaryKey(),
65
+ title: text("title").notNull(),
66
+ slug: text("slug").notNull().unique(),
67
+ content: text("content"),
68
+ excerpt: text("excerpt"),
69
+ status: text("status").notNull().default("draft"),
70
+ publishedAt: text("published_at"),
71
+ ownerId: text("owner_id").notNull(),
72
+ });
73
+
74
+ export default defineTable(posts, {
75
+ firewall: [
76
+ { field: 'ownerId', equals: 'ctx.userId' },
77
+ { field: 'deletedAt', isNull: true },
78
+ ],
79
+ guards: {
80
+ createable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
81
+ updatable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
82
+ immutable: ["id", "ownerId"],
83
+ },
84
+ read: {
85
+ access: { roles: ["PUBLIC"] },
86
+ },
87
+ crud: {
88
+ create: { access: { roles: ["admin"] } },
89
+ update: { access: { roles: ["admin"] } },
90
+ delete: { access: { roles: ["admin"] }, mode: "soft" },
91
+ },
92
+ });
93
+ ```
94
+
95
+ - **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
96
+ - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `role: "admin"` (set via Better Auth's admin plugin)
97
+ - **`owner`** firewall scope tracks who created each post via `ownerId`
98
+ - **`softDelete`** marks posts as deleted rather than removing them from the database
99
+
100
+ ### Post Actions (actions.ts)
101
+
102
+ The template includes publish/unpublish actions with guard conditions:
103
+
104
+ ```typescript
105
+ import { posts } from './posts';
106
+ import { defineActions } from '@quickback/compiler';
107
+ import { z } from 'zod';
108
+
109
+ export default defineActions(posts, {
110
+ publish: {
111
+ description: "Publish a draft post",
112
+ input: z.object({}),
113
+ guard: {
114
+ roles: ["admin"],
115
+ record: { status: { equals: "draft" } },
116
+ },
117
+ sideEffects: "sync",
118
+ },
119
+ unpublish: {
120
+ description: "Revert a published post to draft",
121
+ input: z.object({}),
122
+ guard: {
123
+ roles: ["admin"],
124
+ record: { status: { equals: "published" } },
125
+ },
126
+ sideEffects: "sync",
127
+ },
128
+ });
129
+ ```
130
+
131
+ These actions are admin-only and include record-level guards — you can only publish drafts and unpublish published posts.
132
+
133
+ ## Setup Steps
134
+
135
+ ### 1. Install Dependencies
136
+
137
+ ```bash
138
+ npm install
139
+ ```
140
+
141
+ ### 2. Log In to the Compiler
142
+
143
+ ```bash
144
+ quickback login
145
+ ```
146
+
147
+ ### 3. Compile Your Definitions
148
+
149
+ ```bash
150
+ quickback compile
151
+ ```
152
+
153
+ ### 4. Create D1 Database
154
+
155
+ The blog template uses a single D1 database (no split databases):
156
+
157
+ ```bash
158
+ npx wrangler d1 create my-site
159
+ ```
160
+
161
+ Copy the database ID from the output and update your `wrangler.toml`:
162
+
163
+ ```toml
164
+ [[d1_databases]]
165
+ binding = "DB"
166
+ database_name = "my-site"
167
+ database_id = "paste-id-here"
168
+ ```
169
+
170
+ ### 5. Run Migrations (Local)
171
+
172
+ ```bash
173
+ npm run db:migrate:local
174
+ ```
175
+
176
+ ### 6. Start Development Server
177
+
178
+ ```bash
179
+ npm run dev
180
+ ```
181
+
182
+ Your API is running at `http://localhost:8787`.
183
+
184
+ ## Using the API
185
+
186
+ ### Public Endpoints (No Auth Required)
187
+
188
+ ```bash
189
+ # List all posts
190
+ curl http://localhost:8787/api/v1/posts
191
+
192
+ # Get a single post
193
+ curl http://localhost:8787/api/v1/posts/post-id-here
194
+ ```
195
+
196
+ ### Admin Endpoints (Auth Required)
197
+
198
+ ```bash
199
+ # Create a post (admin only)
200
+ curl -X POST http://localhost:8787/api/v1/posts \
201
+ -H "Authorization: Bearer $TOKEN" \
202
+ -H "Content-Type: application/json" \
203
+ -d '{"title": "Hello World", "slug": "hello-world", "content": "..."}'
204
+
205
+ # Publish a post (admin only)
206
+ curl -X POST http://localhost:8787/api/v1/posts/post-id/actions/publish \
207
+ -H "Authorization: Bearer $TOKEN"
208
+ ```
209
+
210
+ ### Pairing with a Frontend
211
+
212
+ Since this is a JSON API, pair it with any frontend framework:
213
+
214
+ ```typescript
215
+ // Astro, Next.js, SvelteKit, etc.
216
+ const posts = await fetch('https://api.mysite.com/api/v1/posts').then(r => r.json());
217
+
218
+ // Admin operations require authentication
219
+ const res = await fetch('https://api.mysite.com/api/v1/posts', {
220
+ method: 'POST',
221
+ headers: {
222
+ 'Authorization': `Bearer ${token}`,
223
+ 'Content-Type': 'application/json',
224
+ },
225
+ body: JSON.stringify({ title: 'New Post', slug: 'new-post', content: '...' }),
226
+ });
227
+ ```
228
+
229
+ ## Adding More Features
230
+
231
+ Add new content types by creating feature directories. For example, a `pages` feature for static pages:
232
+
233
+ ```typescript
234
+ // quickback/features/pages/pages.ts
235
+ import { sqliteTable, text } from "drizzle-orm/sqlite-core";
236
+ import { defineTable } from "@quickback/compiler";
237
+
238
+ export const pages = sqliteTable("pages", {
239
+ id: text("id").primaryKey(),
240
+ title: text("title").notNull(),
241
+ slug: text("slug").notNull().unique(),
242
+ content: text("content"),
243
+ ownerId: text("owner_id").notNull(),
244
+ });
245
+
246
+ export default defineTable(pages, {
247
+ firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
248
+ read: {
249
+ access: { roles: ["PUBLIC"] },
250
+ },
251
+ crud: {
252
+ create: { access: { roles: ["admin"] } },
253
+ update: { access: { roles: ["admin"] } },
254
+ delete: { access: { roles: ["admin"] } },
255
+ },
256
+ });
257
+ ```
258
+
259
+ Then recompile:
260
+
261
+ ```bash
262
+ quickback compile
263
+ ```
264
+
265
+ ## Deploying to Production
266
+
267
+ ```bash
268
+ # Apply remote migrations
269
+ npm run db:migrate:remote
270
+
271
+ # Deploy to Cloudflare
272
+ npm run deploy
273
+ ```
274
+
275
+ ## Next Steps
276
+
277
+ - [Single-Tenant Mode](/compiler/config/single-tenant) — How single-tenant mode works
278
+ - [Access Control](/compiler/definitions/access) — PUBLIC role and role-based permissions
279
+ - [Custom Actions](/compiler/definitions/actions) — Add business logic beyond CRUD
280
+ - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Multi-tenant alternative