@quickback-dev/cli 0.66.11 → 0.66.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +14 -0
- package/dist/commands/deploy.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +29 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +26 -2
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/deployment-target.test.js +37 -1
- package/dist/lib/deployment-target.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +1 -1
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/lib/migrations/plan.js +6 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts +16 -5
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js +32 -102
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +73 -1
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.test.js +95 -0
- package/dist/lib/migrations/postprocessors/index.test.js.map +1 -1
- package/dist/lib/migrations/postprocessors/trigger-sql.d.ts +18 -0
- package/dist/lib/migrations/postprocessors/trigger-sql.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/trigger-sql.js +63 -0
- package/dist/lib/migrations/postprocessors/trigger-sql.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +3 -0
- package/dist/skill/docs/define/schema.md +58 -6
- package/dist/skill/docs/define/triggers.md +143 -20
- package/dist/skill/docs/platform/auth/index.md +37 -16
- package/dist/skill/docs/platform/auth/plugins/subscriptions.md +25 -5
- package/dist/skill/docs/platform/database/neon.md +115 -18
- package/dist/skill/docs/platform/database/planetscale-postgres.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +75 -8
- package/dist/skill/docs/tooling/output.md +49 -5
- package/package.json +2 -1
- package/src/skill/docs/define/actions/scoped-db.md +3 -0
- package/src/skill/docs/define/schema.md +58 -6
- package/src/skill/docs/define/triggers.md +143 -20
- package/src/skill/docs/platform/auth/index.md +37 -16
- package/src/skill/docs/platform/auth/plugins/subscriptions.md +25 -5
- package/src/skill/docs/platform/database/neon.md +115 -18
- package/src/skill/docs/platform/database/planetscale-postgres.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +75 -8
- package/src/skill/docs/tooling/output.md +49 -5
|
@@ -11,11 +11,23 @@ Quickback provides built-in file storage using Cloudflare R2.
|
|
|
11
11
|
files worker.** You compute keys and store file references in your own table.
|
|
12
12
|
Use this when you already have a media table and only need to sign large or
|
|
13
13
|
confidential transfers — see [Presigned uploads](#presigned-uploads).
|
|
14
|
-
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a
|
|
15
|
-
metadata
|
|
14
|
+
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a
|
|
15
|
+
metadata store (buckets + objects), the `/storage/v1/*` upload/download/
|
|
16
16
|
manage endpoints, and a files worker for serving. Use this for listing photos,
|
|
17
17
|
avatars, and other files that should be **public-if-you-have-the-link**.
|
|
18
18
|
|
|
19
|
+
Managed mode works on every database provider. Where the metadata lives depends
|
|
20
|
+
on which one you chose:
|
|
21
|
+
|
|
22
|
+
| Database | Metadata store | Migrations |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `cloudflare-d1` | A second D1 database, bound as `FILES_DB` | Its own `drizzle.files.config.ts` and migration folder |
|
|
25
|
+
| `neon`, `planetscale-postgres` | A `files` schema in the **same** Postgres database as auth and feature data — no extra database, no binding | The project's single journal |
|
|
26
|
+
|
|
27
|
+
Nothing above the store moves: ids, object keys, JSON-encoded role and MIME
|
|
28
|
+
lists, ISO-8601 timestamps and soft deletion are identical, so every
|
|
29
|
+
`/storage/v1/*` request and response body is the same on both.
|
|
30
|
+
|
|
19
31
|
```ts
|
|
20
32
|
// Presign-only (default) — ctx.storage against a bucket, nothing else
|
|
21
33
|
defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
|
|
@@ -117,7 +129,7 @@ export default {
|
|
|
117
129
|
managed: true,
|
|
118
130
|
binding: 'R2_BUCKET',
|
|
119
131
|
bucketName: 'my-app-files',
|
|
120
|
-
filesBinding: 'FILES_DB',
|
|
132
|
+
filesBinding: 'FILES_DB', // cloudflare-d1 only; ignored on Postgres
|
|
121
133
|
maxFileSize: 10 * 1024 * 1024, // 10MB
|
|
122
134
|
allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
|
|
123
135
|
},
|
|
@@ -127,7 +139,7 @@ export default {
|
|
|
127
139
|
```
|
|
128
140
|
|
|
129
141
|
> `managed: true` is what turns on everything on this page — the `/storage/v1/*`
|
|
130
|
-
> routes, the files worker, and the
|
|
142
|
+
> routes, the files worker, and the metadata store. Without it R2
|
|
131
143
|
> file storage is **presign-only**: the compiler signs requests against the
|
|
132
144
|
> bucket by name and emits **no** bucket binding into `wrangler.toml`, so
|
|
133
145
|
> `binding` and `filesBinding` are ignored and `env.R2_BUCKET` is `undefined`
|
|
@@ -379,6 +391,17 @@ https://files.yourdomain.com/public/org_abc/listings/3f2a…-hero.jpg
|
|
|
379
391
|
Store that URL on the listing row. Send it to the public listing page. This is
|
|
380
392
|
the right model for property photos, avatars, and shareable media.
|
|
381
393
|
|
|
394
|
+
No session is required, but the request is not unconditional: the files worker
|
|
395
|
+
looks the key up in the metadata store and serves bytes only when a live
|
|
396
|
+
(not soft-deleted) object exists in a bucket whose `readScope` is `public`.
|
|
397
|
+
Anything else is a **404**, not a 403 — an anonymous caller must not be able to
|
|
398
|
+
probe for private keys. So a soft-deleted public object stops being served, and
|
|
399
|
+
a key that merely *starts with* `public/` proves nothing on its own.
|
|
400
|
+
|
|
401
|
+
Public responses still carry `Cache-Control: public, max-age=31536000,
|
|
402
|
+
immutable`, so a CDN or browser that already has the bytes keeps them. Soft
|
|
403
|
+
deletion is not a revocation mechanism for something already fetched.
|
|
404
|
+
|
|
382
405
|
### Session-gated private files
|
|
383
406
|
|
|
384
407
|
Private files require a valid Better Auth session cookie:
|
|
@@ -409,7 +432,9 @@ When file storage is configured, the compiler generates:
|
|
|
409
432
|
|------|---------|
|
|
410
433
|
| `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |
|
|
411
434
|
| `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |
|
|
412
|
-
| `src/files/schema.ts` | Files
|
|
435
|
+
| `src/files/schema.ts` | Files metadata schema (buckets, objects) — `sqliteTable` on D1, a `files` Postgres schema otherwise |
|
|
436
|
+
| `src/files/index.ts` | `createFilesDb` — the D1 binding handle, or the Postgres service-lane handle |
|
|
437
|
+
| `drizzle.files.config.ts` | Second migration target — **D1 only** |
|
|
413
438
|
| `cloudflare-workers/files/index.ts` | Files worker for serving |
|
|
414
439
|
| `cloudflare-workers/files/wrangler.toml` | Files worker config |
|
|
415
440
|
|
|
@@ -428,15 +453,20 @@ After compiling:
|
|
|
428
453
|
wrangler r2 bucket create my-app-files
|
|
429
454
|
```
|
|
430
455
|
|
|
431
|
-
2. **Create the files database
|
|
456
|
+
2. **Create the files database** — `cloudflare-d1` only. On Postgres the
|
|
457
|
+
metadata lives in the `files` schema of the database you already have:
|
|
432
458
|
```bash
|
|
433
459
|
wrangler d1 create my-app-files
|
|
434
460
|
```
|
|
435
461
|
|
|
436
462
|
3. **Run migrations:**
|
|
437
463
|
```bash
|
|
464
|
+
# cloudflare-d1
|
|
438
465
|
wrangler d1 migrations apply my-app-files --local
|
|
439
466
|
wrangler d1 migrations apply my-app-files --remote
|
|
467
|
+
|
|
468
|
+
# Postgres — the files schema is in the project's single journal
|
|
469
|
+
npm run db:migrate
|
|
440
470
|
```
|
|
441
471
|
|
|
442
472
|
4. **Deploy the API:**
|
|
@@ -450,6 +480,18 @@ After compiling:
|
|
|
450
480
|
wrangler deploy
|
|
451
481
|
```
|
|
452
482
|
|
|
483
|
+
`quickback deploy` ships the API Worker only and then prints this command —
|
|
484
|
+
managed file storage is two deployed Workers, and having shipped one but not
|
|
485
|
+
the other is a real state worth seeing.
|
|
486
|
+
|
|
487
|
+
On Postgres the files worker reads the **same** database over the **same**
|
|
488
|
+
transport as the API Worker: a `HYPERDRIVE` binding (already in its
|
|
489
|
+
`wrangler.toml`), or a `DATABASE_URL` secret you must also set on this
|
|
490
|
+
Worker:
|
|
491
|
+
```bash
|
|
492
|
+
cd cloudflare-workers/files && wrangler secret put DATABASE_URL # HTTP only
|
|
493
|
+
```
|
|
494
|
+
|
|
453
495
|
6. **Set the R2 presign secrets** only if you use signed PUT/GET. Public-bucket
|
|
454
496
|
uploads through `POST /object` do not need them. See
|
|
455
497
|
[Presigned uploads](#presigned-uploads):
|
|
@@ -459,15 +501,40 @@ After compiling:
|
|
|
459
501
|
wrangler secret put R2_SECRET_ACCESS_KEY
|
|
460
502
|
```
|
|
461
503
|
|
|
504
|
+
### Named environments deploy two Workers per target
|
|
505
|
+
|
|
506
|
+
A project with [named environments](/configure/domains) must name the files
|
|
507
|
+
Worker for every target. It is never derived: the script name is the deployed
|
|
508
|
+
identity, and Wrangler's `routes` key is inheritable, so a shared
|
|
509
|
+
`<project>-files` default would let `deploy --env dev` replace production's file
|
|
510
|
+
server and take its hostname.
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
environments: {
|
|
514
|
+
dev: { name: 'app-dev', filesWorker: { name: 'app-files-dev', domain: 'files-dev.example.com' }, /* … */ },
|
|
515
|
+
prod: { name: 'app', filesWorker: { name: 'app-files', domain: 'files.example.com' }, /* … */ },
|
|
516
|
+
}
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
The compile fails with the config path to fix when a target omits it, or when
|
|
520
|
+
two targets claim the same Worker name or hostname. Omitting
|
|
521
|
+
`filesWorker.domain` emits `routes = []` — the explicit workers.dev-only
|
|
522
|
+
opt-out. The files Worker reuses that environment's R2 bucket and database
|
|
523
|
+
bindings; it does not declare its own.
|
|
524
|
+
|
|
525
|
+
```bash
|
|
526
|
+
cd cloudflare-workers/files && npx wrangler deploy --env dev
|
|
527
|
+
```
|
|
528
|
+
|
|
462
529
|
## Configuration Reference
|
|
463
530
|
|
|
464
531
|
| Option | Type | Default | Description |
|
|
465
532
|
|--------|------|---------|-------------|
|
|
466
|
-
| `managed` | `boolean` | `false` | Opt into the
|
|
533
|
+
| `managed` | `boolean` | `false` | Opt into the metadata store + `/storage/v1/*` + files worker. Off = presign-only. |
|
|
467
534
|
| `bucketName` | `string` | `<project>-media` | R2 bucket the signer targets (override per-call with `signPutUrl(key, { bucket })`) |
|
|
468
535
|
| `presign` | `object` | - | Env-var name overrides: `{ accountIdEnv, accessKeyIdEnv, secretAccessKeyEnv, endpointEnv }` |
|
|
469
536
|
| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name (managed mode) |
|
|
470
|
-
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode) |
|
|
537
|
+
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode, `cloudflare-d1` only — Postgres uses the `files` schema of the single database and emits no binding) |
|
|
471
538
|
| `maxFileSize` | `number \| string` | 10MB | Max upload size — bytes or `"100mb"` (managed mode) |
|
|
472
539
|
| `allowedTypes` | `string[]` | Images only | Allowed MIME types (managed mode) |
|
|
473
540
|
| `publicDomain` | `string` | - | Custom domain for files worker (managed mode) |
|
|
@@ -288,18 +288,62 @@ src/
|
|
|
288
288
|
|
|
289
289
|
### File Storage (R2)
|
|
290
290
|
|
|
291
|
-
When `fileStorage` is configured:
|
|
291
|
+
When `fileStorage` is configured, presign-only mode emits just the signer:
|
|
292
292
|
|
|
293
293
|
```
|
|
294
294
|
src/
|
|
295
|
-
└──
|
|
296
|
-
└──
|
|
295
|
+
└── storage/
|
|
296
|
+
└── presign.ts # R2 presigned-URL signer (backs ctx.storage)
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`managed: true` adds the API routes, the metadata schema and a **second
|
|
300
|
+
deployed Worker** with its own `wrangler.toml`:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
src/
|
|
304
|
+
├── routes/storage.ts # File upload/download endpoints
|
|
305
|
+
└── files/
|
|
306
|
+
├── schema.ts # buckets + objects
|
|
307
|
+
└── index.ts # createFilesDb
|
|
308
|
+
cloudflare-workers/
|
|
309
|
+
└── files/ # SECOND Worker — deployed separately
|
|
310
|
+
├── index.ts # public + session-gated file serving
|
|
311
|
+
└── wrangler.toml # its own name, bindings and routes
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
`cloudflare-workers/**` is included in the generated `tsconfig.json`, so
|
|
315
|
+
`npm run typecheck` covers both entrypoints.
|
|
316
|
+
|
|
317
|
+
Where the metadata lives, and therefore what else is emitted, depends on the
|
|
318
|
+
database provider:
|
|
319
|
+
|
|
320
|
+
| Provider | Metadata store | Extra output |
|
|
321
|
+
|---|---|---|
|
|
322
|
+
| `cloudflare-d1` | A second D1 database bound as `FILES_DB` | `drizzle.files.config.ts` + `quickback/drizzle/files/` |
|
|
323
|
+
| `neon`, `planetscale-postgres` | A `files` schema in the same Postgres database | none — the tables ride the single journal at `quickback/drizzle/` |
|
|
324
|
+
|
|
325
|
+
```
|
|
297
326
|
quickback/drizzle/
|
|
298
|
-
└── files/ # File metadata migrations
|
|
327
|
+
└── files/ # File metadata migrations — cloudflare-d1 only
|
|
299
328
|
├── meta/
|
|
300
329
|
└── 0000_*.sql
|
|
301
330
|
```
|
|
302
331
|
|
|
332
|
+
Under named environments the second Worker needs its own identity, declared per
|
|
333
|
+
target and never derived — a shared default would make `deploy --env dev`
|
|
334
|
+
overwrite production's file server, and Wrangler's inheritable `routes` would
|
|
335
|
+
take its hostname with it:
|
|
336
|
+
|
|
337
|
+
```ts
|
|
338
|
+
environments: {
|
|
339
|
+
dev: { name: 'app-dev', filesWorker: { name: 'app-files-dev', domain: 'files-dev.example.com' }, /* … */ },
|
|
340
|
+
prod: { name: 'app', filesWorker: { name: 'app-files', domain: 'files.example.com' }, /* … */ },
|
|
341
|
+
}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Omitting `filesWorker.domain` emits `routes = []` for that target — the explicit
|
|
345
|
+
workers.dev-only opt-out, so it cannot inherit a sibling's hostname.
|
|
346
|
+
|
|
303
347
|
### Webhooks
|
|
304
348
|
|
|
305
349
|
When webhooks are enabled:
|
|
@@ -462,7 +506,7 @@ The CLI loads migration meta JSON from one location only — `<project>/quickbac
|
|
|
462
506
|
|
|
463
507
|
- `quickback/drizzle/auth/meta/`
|
|
464
508
|
- `quickback/drizzle/features/meta/`
|
|
465
|
-
- `quickback/drizzle/files/meta/`
|
|
509
|
+
- `quickback/drizzle/files/meta/` (cloudflare-d1 managed file storage)
|
|
466
510
|
- `quickback/drizzle/webhooks/meta/`
|
|
467
511
|
- `quickback/drizzle/audit/meta/`
|
|
468
512
|
- `quickback/drizzle/meta/` (single-database mode)
|