@quickback-dev/cli 0.38.0 → 0.40.0

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 (109) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.js +24 -24
  19. package/dist/docs/content.js.map +1 -1
  20. package/dist/examples/recruitment.tar.gz +0 -0
  21. package/dist/index.js +1 -1
  22. package/dist/lib/action-harvest.d.ts +48 -0
  23. package/dist/lib/action-harvest.d.ts.map +1 -0
  24. package/dist/lib/action-harvest.js +292 -0
  25. package/dist/lib/action-harvest.js.map +1 -0
  26. package/dist/lib/action-harvest.test.d.ts +2 -0
  27. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  28. package/dist/lib/action-harvest.test.js +112 -0
  29. package/dist/lib/action-harvest.test.js.map +1 -0
  30. package/dist/lib/api-client.d.ts +10 -0
  31. package/dist/lib/api-client.d.ts.map +1 -1
  32. package/dist/lib/api-client.js +17 -1
  33. package/dist/lib/api-client.js.map +1 -1
  34. package/dist/lib/api-client.test.js +19 -0
  35. package/dist/lib/api-client.test.js.map +1 -1
  36. package/dist/lib/artifact-routing.d.ts +1 -0
  37. package/dist/lib/artifact-routing.d.ts.map +1 -1
  38. package/dist/lib/artifact-routing.js +15 -3
  39. package/dist/lib/artifact-routing.js.map +1 -1
  40. package/dist/lib/artifact-routing.test.js +12 -1
  41. package/dist/lib/artifact-routing.test.js.map +1 -1
  42. package/dist/lib/file-loader.d.ts +1 -0
  43. package/dist/lib/file-loader.d.ts.map +1 -1
  44. package/dist/lib/file-loader.js +34 -1
  45. package/dist/lib/file-loader.js.map +1 -1
  46. package/dist/lib/file-loader.test.js +28 -4
  47. package/dist/lib/file-loader.test.js.map +1 -1
  48. package/dist/lib/prepare-state-output.d.ts +8 -0
  49. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  50. package/dist/lib/prepare-state-output.js +17 -0
  51. package/dist/lib/prepare-state-output.js.map +1 -0
  52. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  53. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  54. package/dist/lib/prepare-state-output.test.js +31 -0
  55. package/dist/lib/prepare-state-output.test.js.map +1 -0
  56. package/dist/skill/SKILL.md +1 -1
  57. package/dist/skill/docs/changelog.md +262 -0
  58. package/dist/skill/docs/compiler/config/agents.md +1 -1
  59. package/dist/skill/docs/compiler/config/auth.md +1 -1
  60. package/dist/skill/docs/compiler/config/index.md +8 -9
  61. package/dist/skill/docs/compiler/config/providers.md +3 -0
  62. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  63. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  64. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  65. package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
  66. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  67. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  68. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  69. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  70. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  71. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  72. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  73. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  74. package/dist/skill/docs/stack/cms/index.md +7 -7
  75. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  76. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  77. package/dist/skill/docs/stack/cms/security.md +6 -6
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
  79. package/dist/skill/docs/stack/storage/r2.md +142 -4
  80. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  81. package/dist/templates/registry.js +2 -2
  82. package/dist/templates/registry.js.map +1 -1
  83. package/package.json +1 -1
  84. package/src/examples/recruitment.tar.gz +0 -0
  85. package/src/skill/SKILL.md +1 -1
  86. package/src/skill/docs/changelog.md +262 -0
  87. package/src/skill/docs/compiler/config/agents.md +1 -1
  88. package/src/skill/docs/compiler/config/auth.md +1 -1
  89. package/src/skill/docs/compiler/config/index.md +8 -9
  90. package/src/skill/docs/compiler/config/providers.md +3 -0
  91. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  92. package/src/skill/docs/compiler/definitions/access.md +40 -33
  93. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  94. package/src/skill/docs/compiler/definitions/firewall.md +1 -1
  95. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  96. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  97. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  98. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  100. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  101. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  102. package/src/skill/docs/stack/cms/connecting.md +17 -16
  103. package/src/skill/docs/stack/cms/index.md +7 -7
  104. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  105. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  106. package/src/skill/docs/stack/cms/security.md +6 -6
  107. package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
  108. package/src/skill/docs/stack/storage/r2.md +142 -4
  109. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -1,6 +1,35 @@
1
1
  # File Storage (R2)
2
2
 
3
- Quickback provides built-in file storage using Cloudflare R2, with role-based access control and a dedicated files worker for serving.
3
+ Quickback provides built-in file storage using Cloudflare R2.
4
+
5
+ ## Two modes
6
+
7
+ `defineFileStorage("cloudflare-r2")` has two modes:
8
+
9
+ - **Presign-only (default)** — emits just the `ctx.storage` signer (presigned
10
+ PUT/GET URLs straight to R2). **No new D1, no `/storage/v1/*` endpoints, no
11
+ files worker.** You compute keys and store file references in your own table.
12
+ This is the recommended path for most apps and the lightest way to add
13
+ uploads — see [Presigned uploads](#presigned-uploads-recommended).
14
+ - **Managed (`managed: true`)** — adds the turnkey subsystem on top: a FILES_DB
15
+ metadata database (buckets + objects), the `/storage/v1/*` upload/download/
16
+ manage endpoints, and a public files worker for serving. Opt in only when you
17
+ want buckets/objects handled for you instead of bringing your own media table.
18
+
19
+ ```ts
20
+ // Presign-only (default) — ctx.storage against a bucket, nothing else
21
+ defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
22
+
23
+ // Managed subsystem — adds FILES_DB + /storage/v1/* + files worker
24
+ defineFileStorage("cloudflare-r2", { managed: true, bucketName: "my-app-files" })
25
+ ```
26
+
27
+ New projects can omit `bucketName` — it defaults to `<project>-media`, so the
28
+ only setup is `wrangler r2 bucket create <name>` once plus the R2 API-token
29
+ secrets. Existing projects set `bucketName` to a bucket they already have.
30
+
31
+ The sections below document the **managed** subsystem; for the default
32
+ presign-only path jump to [Presigned uploads](#presigned-uploads-recommended).
4
33
 
5
34
  ## Architecture
6
35
 
@@ -68,13 +97,21 @@ export default {
68
97
  | GET | `/bucket` | List buckets |
69
98
  | GET | `/bucket/:name` | Get bucket info |
70
99
  | DELETE | `/bucket/:name` | Delete bucket (must be empty) |
71
- | POST | `/object/:bucket/*path` | Upload file |
100
+ | POST | `/object/:bucket/*path` | Upload file (bytes through the Worker) |
101
+ | POST | `/presign/:bucket/*path` | **Presigned upload URL (bytes direct to R2)** |
102
+ | POST | `/confirm/:bucket/*path` | Confirm a presigned upload (reconcile size + etag) |
72
103
  | GET | `/object/:bucket/*path` | Download file |
73
104
  | HEAD | `/object/:bucket/*path` | Get file metadata |
74
105
  | DELETE | `/object/:bucket/*path` | Delete file (soft delete) |
75
106
  | GET | `/object` | List objects |
76
107
  | POST | `/url` | Get file URL for serving |
77
108
 
109
+ > For anything larger than a small image — video, audio, big PDFs — prefer the
110
+ > **presigned** path. The bytes go straight to R2, so you skip the Worker's
111
+ > request-body cap and don't burn Worker CPU streaming the upload. See
112
+ > [Presigned uploads](#presigned-uploads-recommended) below.
113
+
114
+
78
115
  ### Files Worker (files.yourdomain.com)
79
116
 
80
117
  | Method | Path | Auth Required |
@@ -145,6 +182,94 @@ Response:
145
182
  }
146
183
  ```
147
184
 
185
+ ## Presigned uploads (recommended)
186
+
187
+ Streaming bytes through the Worker (`POST /object`) is fine for small files, but
188
+ it puts every byte on the Worker's request path — subject to the body-size cap,
189
+ and billed as Worker CPU/duration. For media (video, audio, large PDFs), use a
190
+ **presigned URL**: the Worker runs all the access checks and hands back a
191
+ short-lived URL the client uploads to **directly**. The bytes never touch your
192
+ Worker.
193
+
194
+ ```bash
195
+ # 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)
196
+ curl -X POST https://api.example.com/storage/v1/presign/videos/clip.mp4 \
197
+ -H "Authorization: Bearer <token>" \
198
+ -H "Content-Type: application/json" \
199
+ -d '{ "contentType": "video/mp4", "size": 73400320 }'
200
+
201
+ # Response:
202
+ # {
203
+ # "id": "obj_abc",
204
+ # "key": "org_abc/videos/clip.mp4",
205
+ # "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
206
+ # "method": "PUT",
207
+ # "headers": { "Content-Type": "video/mp4" },
208
+ # "expiresAt": "2026-06-02T12:10:00.000Z"
209
+ # }
210
+
211
+ # 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
212
+ curl -X PUT "<uploadUrl>" -H "Content-Type: video/mp4" --data-binary @clip.mp4
213
+
214
+ # 3. Confirm — reconciles the recorded size + etag against what actually landed
215
+ curl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \
216
+ -H "Authorization: Bearer <token>"
217
+ ```
218
+
219
+ > If `contentType` is supplied at step 1 it is **bound into the signature** — the
220
+ > client MUST send exactly that `Content-Type` header on the PUT, or R2 rejects
221
+ > it. Omit it to let the client send any type.
222
+
223
+
224
+ ### Required secrets
225
+
226
+ Presigning uses R2's S3-compatible API, which needs an **R2 API token** — the
227
+ Workers bucket binding alone cannot presign. Create a token in the Cloudflare
228
+ dashboard (R2 → Manage API Tokens) and set:
229
+
230
+ ```bash
231
+ wrangler secret put R2_ACCOUNT_ID # your Cloudflare account id
232
+ wrangler secret put R2_ACCESS_KEY_ID # R2 API token access key id
233
+ wrangler secret put R2_SECRET_ACCESS_KEY # R2 API token secret
234
+ # Optional: wrangler secret put R2_S3_ENDPOINT # override the derived endpoint
235
+ ```
236
+
237
+ ### Signing from your own action
238
+
239
+ The same signer is exposed as `ctx.storage` inside any
240
+ [`defineAction`](/compiler/definitions/actions) — so you can author an upload endpoint that
241
+ runs your own access rules (org, team, relationship/scoped roles) and stores the
242
+ key in **your own table**, instead of the generic `buckets`/`objects` metadata:
243
+
244
+ ```typescript
245
+ export default defineAction({
246
+ path: '/event/:eventId/media/sign-upload',
247
+ method: 'POST',
248
+ input: z.object({ filename: z.string(), contentType: z.string() }),
249
+ access: { roles: ['admin', 'member', 'scope:event:attendee'] },
250
+ async execute({ input, ctx, db, storage }) {
251
+ // Tenant-scoped key — secure by construction
252
+ const key = `org/${ctx.activeOrgId}/event/${input.eventId}/${crypto.randomUUID()}-${input.filename}`;
253
+ const upload = await storage.signPutUrl(key, {
254
+ contentType: input.contentType,
255
+ expiresIn: 600,
256
+ });
257
+ await db.insert(images).values({ key, eventId: input.eventId /* … */ });
258
+ return { uploadUrl: upload.url, key, headers: upload.headers };
259
+ },
260
+ });
261
+ ```
262
+
263
+ `storage` exposes:
264
+
265
+ | Method | Returns | Use |
266
+ |--------|---------|-----|
267
+ | `signPutUrl(key, { contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 |
268
+ | `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |
269
+
270
+ This is the supported replacement for streaming a raw binary body through an
271
+ action — the JSON body parser and its ~1 MiB cap stay on for every other route.
272
+
148
273
  ## Serving Files
149
274
 
150
275
  ### Public Files
@@ -177,11 +302,16 @@ When file storage is configured, the compiler generates:
177
302
 
178
303
  | File | Purpose |
179
304
  |------|---------|
180
- | `src/routes/storage.ts` | Storage API routes |
181
- | `src/files.ts` | Files database schema (buckets, objects) |
305
+ | `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |
306
+ | `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |
307
+ | `src/files/schema.ts` | Files database schema (buckets, objects) |
182
308
  | `cloudflare-workers/files/index.ts` | Files worker for serving |
183
309
  | `cloudflare-workers/files/wrangler.toml` | Files worker config |
184
310
 
311
+ The compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your
312
+ `package.json` (used by the presigner) and the R2 presign secrets to your
313
+ generated `CloudflareBindings` type.
314
+
185
315
  ## Deployment
186
316
 
187
317
  After compiling:
@@ -213,6 +343,14 @@ After compiling:
213
343
  wrangler deploy
214
344
  ```
215
345
 
346
+ 6. **Set the R2 presign secrets** (only if you use presigned uploads — see
347
+ [Presigned uploads](#presigned-uploads-recommended)):
348
+ ```bash
349
+ wrangler secret put R2_ACCOUNT_ID
350
+ wrangler secret put R2_ACCESS_KEY_ID
351
+ wrangler secret put R2_SECRET_ACCESS_KEY
352
+ ```
353
+
216
354
  ## Configuration Reference
217
355
 
218
356
  | Option | Type | Default | Description |
@@ -4,28 +4,48 @@ Cloudflare R2 provides S3-compatible object storage for file uploads in the Quic
4
4
 
5
5
  ## Upload Flow
6
6
 
7
- The generated API provides a two-step upload process:
7
+ The generated API provides a two-step **presigned** upload — the file bytes go
8
+ directly to R2 and never stream through your Worker:
8
9
 
9
- 1. **Request a presigned URL** — Client calls the upload endpoint to get a time-limited URL
10
- 2. **Upload directly to R2** — Client uploads the file directly to R2 (bypasses your Worker)
11
- 3. **Store the reference** — The API records the file metadata in D1
10
+ 1. **Request a presigned URL** — Client calls `/storage/v1/presign/...`; the
11
+ Worker runs auth + bucket + role checks and returns a time-limited URL
12
+ 2. **Upload directly to R2** — Client `PUT`s the bytes to R2 (bypasses your Worker)
13
+ 3. **Confirm** — `/storage/v1/confirm/...` reconciles the recorded size + etag
12
14
 
13
15
  ```bash
14
- # 1. Request presigned upload URL
15
- curl -X POST https://api.example.com/api/v1/files/upload \
16
+ # 1. Request a presigned upload URL
17
+ curl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \
16
18
  -H "Authorization: Bearer <token>" \
17
19
  -H "Content-Type: application/json" \
18
- -d '{"filename": "report.pdf", "contentType": "application/pdf"}'
20
+ -d '{ "contentType": "application/pdf", "size": 248000 }'
19
21
 
20
22
  # Response:
21
- # { "uploadUrl": "https://bucket.r2.cloudflarestorage.com/...", "fileId": "file_abc123" }
22
-
23
- # 2. Upload directly to R2 using the presigned URL
23
+ # {
24
+ # "id": "obj_abc123",
25
+ # "key": "org_abc/documents/report.pdf",
26
+ # "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
27
+ # "method": "PUT",
28
+ # "headers": { "Content-Type": "application/pdf" },
29
+ # "expiresAt": "2026-06-02T12:10:00.000Z"
30
+ # }
31
+
32
+ # 2. Upload directly to R2 using the presigned URL (replay the returned headers)
24
33
  curl -X PUT "<uploadUrl>" \
25
34
  -H "Content-Type: application/pdf" \
26
35
  --data-binary @report.pdf
36
+
37
+ # 3. Confirm the upload
38
+ curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
39
+ -H "Authorization: Bearer <token>"
27
40
  ```
28
41
 
42
+ Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
43
+ and `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).
44
+
45
+ For uploads that should land in **your own table** (with your own access rules),
46
+ sign the URL from inside a `defineAction` via `ctx.storage` — see
47
+ [Signing from your own action](/stack/storage/r2#signing-from-your-own-action).
48
+
29
49
  ## Download Flow
30
50
 
31
51
  Files are served through your Worker with security checks applied:
@@ -82,9 +82,9 @@ export const TEMPLATE_REGISTRY = {
82
82
  // api-minimal-bun also hidden alongside the other bun templates.
83
83
  "blog-cloudflare": {
84
84
  name: "Blog / CMS Starter",
85
- description: "Single-tenant blog with public pages, admin-only editing, deployed to Cloudflare Workers",
85
+ description: "Blog/CMS starter with a pinned organization id, public pages, and admin-only editing on Cloudflare Workers",
86
86
  category: "api",
87
- tags: ["blog", "cms", "single-tenant", "cloudflare", "d1"],
87
+ tags: ["blog", "cms", "pinned-organization", "cloudflare", "d1"],
88
88
  author: "quickback",
89
89
  version: "1.0.0",
90
90
  includes: ["betterauth", "d1", "hono", "drizzle"],
@@ -1 +1 @@
1
- {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.38.0",
3
+ "version": "0.40.0",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
Binary file
@@ -214,7 +214,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
214
214
  - `output` — `build.outputDir`, custom dependencies
215
215
  - `domains` — multi-domain hostname routing (CMS / account / admin)
216
216
  - `spa` — single-worker SPA mount (your product app at the apex)
217
- - `single-tenant` — disable organizations
217
+ - `single-tenant` — pinned organization mode and migration away from removed `organizations: false`
218
218
  - `agents` — robots.txt, llms.txt, MCP, OAuth discovery
219
219
 
220
220
  **Stack — runtime services** (`docs/stack/<topic>.md`)
@@ -1,5 +1,267 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.40.0 — June 2, 2026
4
+
5
+ R2 file storage is now **presign-only by default**. Adding
6
+ `defineFileStorage("cloudflare-r2")` emits just the `ctx.storage` signer — no
7
+ FILES_DB database, no `/storage/v1/*` endpoints, no files worker. You sign
8
+ presigned URLs against a bucket and store references in your own table. The
9
+ turnkey managed subsystem is still available, now behind `managed: true`.
10
+
11
+ This decouples the lightweight primitive from the heavyweight subsystem so you
12
+ can add uploads without standing up a metadata database you don't use.
13
+
14
+ ### Presign-only by default; managed is opt-in
15
+
16
+ ```ts
17
+ // Presign-only (default) — ctx.storage against a bucket, nothing else
18
+ defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
19
+
20
+ // Managed subsystem — FILES_DB + /storage/v1/* + files worker
21
+ defineFileStorage("cloudflare-r2", { managed: true })
22
+ ```
23
+
24
+ - New projects can omit `bucketName` — it defaults to `<project>-media`, so
25
+ setup is one `wrangler r2 bucket create` plus the R2 API-token secrets.
26
+ - Existing projects set `bucketName` to a bucket they already have. Presign-only
27
+ emits **no** R2 bucket binding and **no** FILES_DB binding — nothing to
28
+ provision, nothing to migrate.
29
+
30
+ ### Per-call bucket + custom secret names
31
+
32
+ ```ts
33
+ // Sign against a different bucket than the configured default
34
+ await storage.signPutUrl(key, { bucket: "my-app-public", contentType });
35
+ ```
36
+
37
+ If your project already stores R2 credentials under different env-var names,
38
+ map them so the signer reads yours:
39
+
40
+ ```ts
41
+ defineFileStorage("cloudflare-r2", {
42
+ bucketName: "my-app-media",
43
+ presign: { accountIdEnv: "CF_ACCOUNT_ID", accessKeyIdEnv: "S3_KEY", secretAccessKeyEnv: "S3_SECRET" },
44
+ })
45
+ ```
46
+
47
+ ### Fixes
48
+
49
+ - `maxFileSize` now accepts a human string (`"100mb"`, `"5gb"`) as well as a
50
+ number of bytes — previously a string emitted invalid TypeScript.
51
+ - Presign-only no longer emits a stray `FILES_DB` `[[d1_databases]]` block (with
52
+ an invalid `database_id = "local-files"`) into `wrangler.toml`, which would
53
+ have made `wrangler deploy` reject the worker.
54
+
55
+ ## v0.39.1 — June 2, 2026
56
+
57
+ Deduplicate colliding OpenAPI `operationId`s. The auto-generated list id
58
+ `list<Resource>` collided when a user named an action `list<Resource>` (e.g.
59
+ `message_reactions` + an action `listMessageReactions`), producing a duplicate
60
+ operationId that failed OpenAPI validation and broke `api-types.gen.ts`. The
61
+ user's action keeps its id; the colliding auto-generated CRUD op is suffixed,
62
+ with a `[quickback:openapi]` warning per rename.
63
+
64
+ ## v0.39.0 — June 2, 2026
65
+
66
+ Media and large-binary uploads are now first-class. Instead of streaming file
67
+ bytes through your Worker — which hits the request-body cap and burns Worker
68
+ CPU/duration — an action mints a short-lived **presigned URL** and the client
69
+ uploads the bytes **directly to R2**. The Worker only signs; it never sits in
70
+ the data path. This is the supported way to author image/video/document upload
71
+ endpoints, and it survives every `quickback compile` with no generated-file
72
+ patching.
73
+
74
+ Requires R2 file storage (`defineFileStorage("cloudflare-r2", …)`).
75
+
76
+ ### `ctx.storage` — sign uploads from any action
77
+
78
+ When R2 file storage is configured, every `defineAction` execute receives a
79
+ typed `storage` signer. Your action runs all the usual security layers (auth,
80
+ roles, org/relationship scope), computes a tenant-scoped key, hands the client
81
+ an upload URL, and stores the key in **your own table** — no separate metadata
82
+ system required:
83
+
84
+ ```ts
85
+ export default defineAction({
86
+ path: "/event/:eventId/media/upload-file-binary",
87
+ method: "POST",
88
+ input: z.object({ filename: z.string(), contentType: z.string() }),
89
+ access: { roles: ["admin", "member", "scope:event:attendee"] },
90
+ async execute({ input, ctx, c, db, storage }) {
91
+ const eventId = c.req.param("eventId");
92
+ const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;
93
+ const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
94
+ await db.insert(images).values({ key, eventId });
95
+ return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };
96
+ },
97
+ });
98
+ ```
99
+
100
+ `storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns
101
+ `{ url, method, headers, key, expiresAt }`) and
102
+ `signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET
103
+ URL). Construction is zero-cost — actions that never touch `storage` pay
104
+ nothing.
105
+
106
+ ### Managed presign + confirm endpoints
107
+
108
+ For the zero-config path, the built-in storage API now exposes a presigned
109
+ upload alongside the existing through-Worker upload:
110
+
111
+ - `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope
112
+ checks, validates the declared `contentType` + `size` against bucket limits,
113
+ records a pending object row, and returns `{ id, key, uploadUrl, method,
114
+ headers, expiresAt }`
115
+ - `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and
116
+ etag against what actually landed in R2 (`HEAD`)
117
+
118
+ ### Setup: R2 API token
119
+
120
+ Presigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2
121
+ binding cannot presign on its own. Set three secrets:
122
+
123
+ ```bash
124
+ wrangler secret put R2_ACCOUNT_ID
125
+ wrangler secret put R2_ACCESS_KEY_ID
126
+ wrangler secret put R2_SECRET_ACCESS_KEY
127
+ ```
128
+
129
+ `aws4fetch` is added to the generated `package.json` automatically, and the R2
130
+ presign secrets are added to the generated `Env` type. If you pass `contentType`
131
+ to `signPutUrl`, the client must replay exactly that `Content-Type` header on
132
+ the `PUT`.
133
+
134
+ ### No raw-body action flag
135
+
136
+ Streaming a raw binary request body through an action is intentionally **not**
137
+ supported. Presigning delivers the same result — large files, no body cap —
138
+ without poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB
139
+ JSON cap stay intact for every other route.
140
+
141
+ ### Storage routes hardened
142
+
143
+ Enabling R2 file storage previously exposed several latent type errors in the
144
+ generated `/storage/v1/*` routes (dead references from an old multipart
145
+ refactor, JSON-string role columns treated as arrays, a few undefined
146
+ variables). The full storage surface now type-checks cleanly when file storage
147
+ is configured.
148
+
149
+ ## v0.38.1 — May 26, 2026
150
+
151
+ Custom action handlers get the same typed ergonomics as generated CRUD paths:
152
+ typed Cloudflare bindings on `env`, a first-class typed `realtime` helper when
153
+ realtime is enabled, and no more `createRealtime(...)` boilerplate inside every
154
+ action just to emit an explicit broadcast.
155
+
156
+ ### Neon compile output and local recompile state are now stable
157
+
158
+ The Neon + Cloudflare path now emits a correct runtime/output surface instead
159
+ of leaking SQLite-era state.
160
+
161
+ - `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon
162
+ projects
163
+ - repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle
164
+ state correctly, so `drizzle-kit` can report "No schema changes" instead of
165
+ regenerating duplicate `0000_*.sql` files
166
+ - stale root Drizzle migrations from earlier bad compiles are pruned during the
167
+ compile/sync path
168
+
169
+ ### Shared-target namespace hydration now works for bulk-grant lanes
170
+
171
+ Bulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit
172
+ the namespace's shared hydration target when every relationship lane points at
173
+ the same resource load shape.
174
+
175
+ That fixes the case where a namespace like:
176
+
177
+ ```ts
178
+ via: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]
179
+ ```
180
+
181
+ would authorize an org admin through the bulk lane but leave `ctx.event`
182
+ undefined, even though the sibling relationship lanes all hydrated the same
183
+ `events` row.
184
+
185
+ Runtime behavior is now split cleanly:
186
+
187
+ - **Shared target** — if all hydrating lanes share the same `loads`,
188
+ `exposeAs`, and resource key, hydration runs unconditionally after the gate
189
+ passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers
190
+ - **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,
191
+ hydration stays per-matched-lane to avoid cross-table false 404s
192
+
193
+ Standalone action typing now matches that runtime behavior too: shared-target
194
+ hydration remains non-optional, while distinct-target multi-lane hydration stays
195
+ optional.
196
+
197
+ ### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant
198
+
199
+ Quickback no longer treats `user.role === "admin"` as the platform-wide role.
200
+ The control-plane role is now `user.role === "appmanager"` (CMS shell, Better
201
+ Auth admin endpoints, support tooling), while `user.role === "sysadmin"`
202
+ remains the only true cross-tenant data-plane tier.
203
+
204
+ This also retires the `ADMIN` pseudo-role. Any `roles: ["ADMIN"]` usage now
205
+ fails the compile with migration guidance:
206
+
207
+ - `userRole: ["appmanager"]` for platform control-plane access
208
+ - `roles: ["admin"]` for org-membership admin access
209
+ - `roles: ["SYSADMIN"]` for true cross-tenant access
210
+
211
+ Runtime behavior now matches that split end-to-end:
212
+
213
+ - Better Auth's admin plugin is generated with `adminRoles: ["appmanager", "sysadmin"]`
214
+ - CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit
215
+ `sysadmin` where appropriate)
216
+ - unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only
217
+
218
+ ### Typed `env` + injected `realtime` in action handlers
219
+
220
+ The generated `<feature>/.quickback/define-action.ts` helper now types action
221
+ `env` from the project's runtime bindings surface instead of `any`, so custom
222
+ bindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB
223
+ bindings no longer need `(env as any)` casts inside action handlers.
224
+
225
+ When realtime is enabled in config, action handlers also receive a typed
226
+ `realtime` helper directly in `execute(...)`. It exposes the same
227
+ `insert/update/delete/broadcast` methods as `createRealtime(env)`, but without
228
+ the extra import or hand-rolled factory call in every custom action.
229
+
230
+ This is a DX-only change. The auto-broadcast boundary is unchanged: generated
231
+ CRUD routes still broadcast automatically, while custom action writes still
232
+ broadcast explicitly.
233
+
234
+ ### `generateId: "cuid"` docs now reflect the split runtime/schema behavior
235
+
236
+ Quickback's `cuid` strategy is now documented as the split path it actually is:
237
+ compiler-managed schema auto-injection keeps the `createId()` call site but may
238
+ back it with a file-local `crypto.randomUUID()` polyfill, while import-capable
239
+ runtime paths still emit real `createId()` usage.
240
+
241
+ That matters most for `compiler.injectId` and other schema-emission paths that
242
+ run in sandboxes where project `node_modules` are not visible. The generated
243
+ schema can safely keep:
244
+
245
+ ```ts
246
+ id: text("id").primaryKey().$defaultFn(() => createId())
247
+ ```
248
+
249
+ while satisfying the reference via:
250
+
251
+ ```ts
252
+ const createId = () => crypto.randomUUID();
253
+ ```
254
+
255
+ instead of importing `@paralleldrive/cuid2` inside the schema-generation
256
+ environment.
257
+
258
+ **Important nuance:** this is not a guarantee that every generated id is a true
259
+ cuid2 string. Auto-injected schema paths may produce UUID-shaped strings
260
+ through the polyfill, while runtime paths that can import helpers may still use
261
+ real `createId()`. If you need strict cuid2 shape everywhere, explicitly import
262
+ `createId` from `@paralleldrive/cuid2` in the authored schema file; the
263
+ compiler preserves that import and skips the polyfill.
264
+
3
265
  ## v0.38.0 — May 26, 2026
4
266
 
5
267
  **Per-matched-lane authorization** for multi-lane namespaces — across both the
@@ -70,7 +70,7 @@ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool na
70
70
  `tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
71
71
 
72
72
  - **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
73
- - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Admin-only endpoints don't appear for non-admins.
73
+ - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Platform-operator endpoints don't appear for callers outside the required user roles.
74
74
  - **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
75
75
  - **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
76
76
 
@@ -125,7 +125,7 @@ export default defineConfig({
125
125
  Both fields override compiler-emitted browser redirects in the CMS shell:
126
126
 
127
127
  - **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
128
- - **Authenticated user fails the `cms.access: 'admin'` role check** → `302 → <profileUrl>`
128
+ - **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
129
129
 
130
130
  The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
131
131