@quickback-dev/cli 0.39.1 → 0.40.2

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.
@@ -2,53 +2,78 @@
2
2
 
3
3
  Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
4
4
 
5
- ## Upload Flow
5
+ By default `defineFileStorage("cloudflare-r2")` is **presign-only**: you get the
6
+ `ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints shown
7
+ further down only exist in the [managed subsystem](/stack/storage/r2#two-modes)
8
+ (`managed: true`).
9
+
10
+ ## Upload Flow (default — `ctx.storage`)
11
+
12
+ Write a normal `defineAction` that signs a presigned URL and stores the key in
13
+ **your own table**. Bytes go directly to R2 — the Worker only signs.
14
+
15
+ ```ts
16
+ export default defineAction({
17
+ path: "/media/sign-upload",
18
+ method: "POST",
19
+ input: z.object({ filename: z.string(), contentType: z.string() }),
20
+ access: { roles: ["member"] },
21
+ async execute({ input, ctx, db, storage }) {
22
+ const key = `org/${ctx.activeOrgId}/${crypto.randomUUID()}-${input.filename}`;
23
+ const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
24
+ await db.insert(media).values({ key /* … */ });
25
+ return { uploadUrl: upload.url, key, headers: upload.headers };
26
+ },
27
+ });
28
+ ```
29
+
30
+ ```bash
31
+ # 1. Ask your action for a signed URL (your auth/roles run here)
32
+ curl -X POST https://api.example.com/api/v1/media/sign-upload \
33
+ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
34
+ -d '{ "filename": "report.pdf", "contentType": "application/pdf" }'
35
+ # → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Type": "application/pdf" } }
36
+
37
+ # 2. Upload the bytes straight to R2 (replay the returned headers)
38
+ curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
39
+ ```
40
+
41
+ `storage.signPutUrl(key, { contentType?, expiresIn?, bucket? })` returns
42
+ `{ url, method, headers, key, expiresAt }`; `storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })`
43
+ returns a presigned GET URL. Pass `bucket` to target a bucket other than the
44
+ configured default.
45
+
46
+ Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
47
+ and `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).
6
48
 
7
- The generated API provides a two-step **presigned** upload — the file bytes go
8
- directly to R2 and never stream through your Worker:
49
+ ## Upload Flow (managed mode — `/storage/v1/*`)
9
50
 
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
51
+ With `managed: true`, the generated API also exposes turnkey presigned
52
+ endpoints backed by the FILES_DB metadata system:
14
53
 
15
54
  ```bash
16
55
  # 1. Request a presigned upload URL
17
56
  curl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \
18
- -H "Authorization: Bearer <token>" \
19
- -H "Content-Type: application/json" \
57
+ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
20
58
  -d '{ "contentType": "application/pdf", "size": 248000 }'
59
+ # → { "id": "obj_abc", "key": "...", "uploadUrl": "...", "headers": {...}, "expiresAt": "..." }
60
+
61
+ # 2. Upload directly to R2
62
+ curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
21
63
 
22
- # Response:
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)
33
- curl -X PUT "<uploadUrl>" \
34
- -H "Content-Type: application/pdf" \
35
- --data-binary @report.pdf
36
-
37
- # 3. Confirm the upload
64
+ # 3. Confirm (reconciles size + etag)
38
65
  curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
39
66
  -H "Authorization: Bearer <token>"
40
67
  ```
41
68
 
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
-
49
69
  ## Download Flow
50
70
 
51
- Files are served through your Worker with security checks applied:
71
+ In **presign-only** mode, mint a short-lived download URL with
72
+ `storage.signGetUrl(key, { downloadFilename })` from your action and hand it to
73
+ the client — the bytes come straight from R2.
74
+
75
+ In **managed** mode, files are also served through the worker with security
76
+ checks applied:
52
77
 
53
78
  ```bash
54
79
  # Download a file (auth + firewall enforced)