@quickback-dev/cli 0.64.1 → 0.65.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 (73) hide show
  1. package/dist/codex/AGENTS.md +290 -0
  2. package/dist/commands/codex.d.ts +16 -0
  3. package/dist/commands/codex.d.ts.map +1 -0
  4. package/dist/commands/codex.js +159 -0
  5. package/dist/commands/codex.js.map +1 -0
  6. package/dist/commands/init.d.ts +6 -0
  7. package/dist/commands/init.d.ts.map +1 -0
  8. package/dist/commands/init.js +405 -0
  9. package/dist/commands/init.js.map +1 -0
  10. package/dist/docs/content.d.ts.map +1 -1
  11. package/dist/docs/content.js +94 -159
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +1 -1
  14. package/dist/lib/action-harvest.d.ts.map +1 -1
  15. package/dist/lib/action-harvest.js +6 -1
  16. package/dist/lib/action-harvest.js.map +1 -1
  17. package/dist/lib/action-harvest.test.js +19 -0
  18. package/dist/lib/action-harvest.test.js.map +1 -1
  19. package/dist/lib/compiler-stubs.d.ts +10 -0
  20. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  21. package/dist/lib/compiler-stubs.js +16 -0
  22. package/dist/lib/compiler-stubs.js.map +1 -1
  23. package/dist/lib/file-writer.js +23 -0
  24. package/dist/lib/file-writer.js.map +1 -1
  25. package/dist/lib/file-writer.test.js +25 -0
  26. package/dist/lib/file-writer.test.js.map +1 -1
  27. package/dist/lib/sweep-stale.d.ts +25 -0
  28. package/dist/lib/sweep-stale.d.ts.map +1 -0
  29. package/dist/lib/sweep-stale.js +179 -0
  30. package/dist/lib/sweep-stale.js.map +1 -0
  31. package/dist/lib/sweep-stale.test.d.ts +2 -0
  32. package/dist/lib/sweep-stale.test.d.ts.map +1 -0
  33. package/dist/lib/sweep-stale.test.js +130 -0
  34. package/dist/lib/sweep-stale.test.js.map +1 -0
  35. package/dist/skill/docs/api/actions.md +6 -20
  36. package/dist/skill/docs/changelog/index.md +23 -2
  37. package/dist/skill/docs/configure/bindings.md +1 -1
  38. package/dist/skill/docs/configure/domains.md +4 -2
  39. package/dist/skill/docs/configure/variables.md +2 -2
  40. package/dist/skill/docs/define/actions/defining.md +12 -0
  41. package/dist/skill/docs/define/authz-roles.md +52 -0
  42. package/dist/skill/docs/platform/auth/plugins/aws-ses.md +6 -18
  43. package/dist/skill/docs/platform/auth/plugins/aws-sns.md +4 -4
  44. package/dist/skill/docs/platform/auth/plugins/index.md +21 -1
  45. package/dist/skill/docs/platform/auth/plugins/subscriptions.md +297 -0
  46. package/dist/skill/docs/platform/payments/dev-loop.md +228 -0
  47. package/dist/skill/docs/platform/payments/index.md +158 -0
  48. package/dist/skill/docs/platform/payments/one-off-checkout.md +266 -0
  49. package/dist/skill/docs/platform/realtime/index.md +2 -1
  50. package/dist/skill/docs/platform/realtime/using-realtime.md +7 -5
  51. package/dist/skill/docs/platform/storage/r2.md +12 -0
  52. package/dist/skill/docs/platform/webhooks/inbound.md +5 -2
  53. package/dist/skill/docs/start/template-cloudflare.md +1 -1
  54. package/package.json +1 -1
  55. package/src/skill/docs/api/actions.md +6 -20
  56. package/src/skill/docs/changelog/index.md +23 -2
  57. package/src/skill/docs/configure/bindings.md +1 -1
  58. package/src/skill/docs/configure/domains.md +4 -2
  59. package/src/skill/docs/configure/variables.md +2 -2
  60. package/src/skill/docs/define/actions/defining.md +12 -0
  61. package/src/skill/docs/define/authz-roles.md +52 -0
  62. package/src/skill/docs/platform/auth/plugins/aws-ses.md +6 -18
  63. package/src/skill/docs/platform/auth/plugins/aws-sns.md +4 -4
  64. package/src/skill/docs/platform/auth/plugins/index.md +21 -1
  65. package/src/skill/docs/platform/auth/plugins/subscriptions.md +297 -0
  66. package/src/skill/docs/platform/payments/dev-loop.md +228 -0
  67. package/src/skill/docs/platform/payments/index.md +158 -0
  68. package/src/skill/docs/platform/payments/one-off-checkout.md +266 -0
  69. package/src/skill/docs/platform/realtime/index.md +2 -1
  70. package/src/skill/docs/platform/realtime/using-realtime.md +7 -5
  71. package/src/skill/docs/platform/storage/r2.md +12 -0
  72. package/src/skill/docs/platform/webhooks/inbound.md +5 -2
  73. package/src/skill/docs/start/template-cloudflare.md +1 -1
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Stale-file sweep for generated output trees.
3
+ *
4
+ * `src/` is hermetic — every file there is emitted by the compiler and
5
+ * carries the "Generated by quickback.dev" header. When a feature is
6
+ * removed/renamed or a generator stops emitting a file, the orphaned file
7
+ * lingers under merge-only writes and can mask bugs (dead routes, ghost
8
+ * imports, mismatched types, stale schemas the user assumes are current).
9
+ *
10
+ * This helper walks a target dir, deletes any file whose path isn't in the
11
+ * compiler's manifest *and* carries the generated-header marker, then
12
+ * collapses the empty directories left behind. Files without the marker are
13
+ * preserved (defence against accidentally nuking hand-authored content that
14
+ * snuck into a generated tree).
15
+ *
16
+ * Before any deletes, it copies the target dir into a timestamped archive
17
+ * under `archiveDir` (when provided). The archive is uncompressed (just a
18
+ * recursive copy via Node's built-in fs.cp) so it's trivially inspectable
19
+ * and recoverable with `cp -r`. Old archives beyond `archiveKeep` are
20
+ * pruned. The archive is skipped entirely on no-op compiles where no
21
+ * orphans were found.
22
+ */
23
+ import { promises as fs } from 'fs';
24
+ import { join, relative, sep } from 'path';
25
+ const GENERATED_MARKER = 'Generated by quickback.dev';
26
+ const HEADER_PROBE_BYTES = 512;
27
+ const DEFAULT_ARCHIVE_KEEP = 3;
28
+ /**
29
+ * OS / editor noise that every contributor accidentally drops into checked-out
30
+ * trees. These files are *never* compiler output and *never* user-authored
31
+ * content the user cares about — silently skip them rather than warning the
32
+ * user every compile that ".DS_Store has no Quickback header".
33
+ */
34
+ const SILENT_IGNORE_BASENAMES = new Set([
35
+ '.DS_Store',
36
+ 'Thumbs.db',
37
+ '.localized',
38
+ ]);
39
+ /**
40
+ * Sweep stale generated files under `targetDir`. Paths in `manifest` are
41
+ * relative to `outputDir` (matching the wire shape the compiler returns).
42
+ */
43
+ export async function sweepStaleGeneratedFiles(outputDir, targetDir, manifest, options = {}) {
44
+ const result = { deleted: [], preserved: [] };
45
+ const fullTarget = join(outputDir, targetDir);
46
+ if (!(await pathExists(fullTarget)))
47
+ return result;
48
+ const manifestSet = new Set();
49
+ for (const p of manifest)
50
+ manifestSet.add(normalizePath(p));
51
+ const skipNormalized = [...(options.skipPrefixes ?? [])].map(normalizePath);
52
+ const isSkipped = (relPath) => skipNormalized.some((sp) => relPath === sp || relPath.startsWith(sp + '/'));
53
+ const onDisk = [];
54
+ await collectFiles(fullTarget, outputDir, onDisk);
55
+ // First pass: identify deletions without acting, so the archive captures
56
+ // the pre-delete state and runs only when there's something to lose.
57
+ const toDelete = [];
58
+ for (const relPath of onDisk) {
59
+ if (manifestSet.has(relPath))
60
+ continue;
61
+ if (isSkipped(relPath))
62
+ continue;
63
+ const base = relPath.slice(relPath.lastIndexOf('/') + 1);
64
+ if (SILENT_IGNORE_BASENAMES.has(base))
65
+ continue;
66
+ const fullPath = join(outputDir, relPath);
67
+ if (await fileHasMarker(fullPath, GENERATED_MARKER)) {
68
+ toDelete.push(relPath);
69
+ }
70
+ else {
71
+ result.preserved.push(relPath);
72
+ }
73
+ }
74
+ if (toDelete.length === 0)
75
+ return result;
76
+ if (options.archiveDir) {
77
+ result.archivePath = await archiveDirectory(fullTarget, options.archiveDir, basename(targetDir));
78
+ await pruneArchives(options.archiveDir, basename(targetDir), options.archiveKeep ?? DEFAULT_ARCHIVE_KEEP);
79
+ }
80
+ for (const relPath of toDelete) {
81
+ await fs.unlink(join(outputDir, relPath));
82
+ result.deleted.push(relPath);
83
+ }
84
+ await removeEmptyDirs(fullTarget);
85
+ return result;
86
+ }
87
+ async function archiveDirectory(srcDir, archiveBase, prefix) {
88
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '');
89
+ const dest = join(archiveBase, `${prefix}-${stamp}`);
90
+ await fs.mkdir(archiveBase, { recursive: true });
91
+ // fs.cp with recursive copies the tree, preserves dir structure, no deps.
92
+ await fs.cp(srcDir, dest, { recursive: true, force: true });
93
+ return dest;
94
+ }
95
+ async function pruneArchives(archiveBase, prefix, keep) {
96
+ if (!(await pathExists(archiveBase)))
97
+ return;
98
+ const entries = await fs.readdir(archiveBase);
99
+ const stamped = entries.filter((e) => e.startsWith(`${prefix}-`)).sort().reverse();
100
+ const stale = stamped.slice(keep);
101
+ for (const old of stale) {
102
+ await fs.rm(join(archiveBase, old), { recursive: true, force: true }).catch(() => { });
103
+ }
104
+ }
105
+ async function pathExists(p) {
106
+ try {
107
+ await fs.access(p);
108
+ return true;
109
+ }
110
+ catch {
111
+ return false;
112
+ }
113
+ }
114
+ async function collectFiles(dir, outputDir, into) {
115
+ let entries;
116
+ try {
117
+ entries = await fs.readdir(dir, { withFileTypes: true });
118
+ }
119
+ catch {
120
+ return;
121
+ }
122
+ for (const entry of entries) {
123
+ const full = join(dir, entry.name);
124
+ if (entry.isDirectory()) {
125
+ await collectFiles(full, outputDir, into);
126
+ }
127
+ else if (entry.isFile()) {
128
+ into.push(normalizePath(relative(outputDir, full)));
129
+ }
130
+ }
131
+ }
132
+ async function fileHasMarker(path, marker) {
133
+ let handle = null;
134
+ try {
135
+ handle = await fs.open(path, 'r');
136
+ const buf = Buffer.alloc(HEADER_PROBE_BYTES);
137
+ const { bytesRead } = await handle.read(buf, 0, HEADER_PROBE_BYTES, 0);
138
+ return buf.subarray(0, bytesRead).toString('utf8').includes(marker);
139
+ }
140
+ catch {
141
+ return false;
142
+ }
143
+ finally {
144
+ if (handle)
145
+ await handle.close();
146
+ }
147
+ }
148
+ async function removeEmptyDirs(dir) {
149
+ let entries;
150
+ try {
151
+ entries = await fs.readdir(dir, { withFileTypes: true });
152
+ }
153
+ catch {
154
+ return;
155
+ }
156
+ for (const entry of entries) {
157
+ if (entry.isDirectory()) {
158
+ await removeEmptyDirs(join(dir, entry.name));
159
+ }
160
+ }
161
+ try {
162
+ const after = await fs.readdir(dir);
163
+ if (after.length === 0) {
164
+ await fs.rmdir(dir).catch(() => { });
165
+ }
166
+ }
167
+ catch {
168
+ /* ignore */
169
+ }
170
+ }
171
+ function normalizePath(p) {
172
+ return sep === '/' ? p : p.split(sep).join('/');
173
+ }
174
+ function basename(p) {
175
+ const norm = normalizePath(p).replace(/\/+$/, '');
176
+ const idx = norm.lastIndexOf('/');
177
+ return idx >= 0 ? norm.slice(idx + 1) : norm;
178
+ }
179
+ //# sourceMappingURL=sweep-stale.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sweep-stale.js","sourceRoot":"","sources":["../../src/lib/sweep-stale.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=sweep-stale.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sweep-stale.test.d.ts","sourceRoot":"","sources":["../../src/lib/sweep-stale.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,130 @@
1
+ import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
2
+ import { promises as fs } from 'fs';
3
+ import { join, sep } from 'path';
4
+ import { tmpdir } from 'os';
5
+ import { sweepStaleGeneratedFiles } from './sweep-stale.js';
6
+ const HEADER = '/**\n * Generated by quickback.dev\n */\n';
7
+ const PLAIN = '// hand-authored content\n';
8
+ let tmp;
9
+ beforeEach(async () => {
10
+ tmp = await fs.mkdtemp(join(tmpdir(), 'sweep-stale-'));
11
+ });
12
+ afterEach(async () => {
13
+ await fs.rm(tmp, { recursive: true, force: true }).catch(() => { });
14
+ });
15
+ async function writeFile(rel, content) {
16
+ const full = join(tmp, ...rel.split('/'));
17
+ await fs.mkdir(join(full, '..'), { recursive: true });
18
+ await fs.writeFile(full, content);
19
+ }
20
+ async function fileExists(rel) {
21
+ try {
22
+ await fs.access(join(tmp, ...rel.split('/')));
23
+ return true;
24
+ }
25
+ catch {
26
+ return false;
27
+ }
28
+ }
29
+ describe('sweepStaleGeneratedFiles', () => {
30
+ // User story: As a developer who renames a feature, I want stale generator
31
+ // output from the old name to disappear so my project tree reflects only
32
+ // what the current config produces — no ghost routes/types lingering.
33
+ test('deletes generated files not in the manifest', async () => {
34
+ await writeFile('src/features/old/schema.ts', HEADER);
35
+ await writeFile('src/features/new/schema.ts', HEADER);
36
+ const result = await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts']);
37
+ expect(result.deleted.sort()).toEqual(['src/features/old/schema.ts']);
38
+ expect(await fileExists('src/features/old/schema.ts')).toBe(false);
39
+ expect(await fileExists('src/features/new/schema.ts')).toBe(true);
40
+ });
41
+ // User story: As a developer who pasted a personal note into src/, I want
42
+ // the sweep to leave my hand-authored file alone — the header check is the
43
+ // line between "compiler owns this" and "the user owns this".
44
+ test('preserves files without the generated-header marker', async () => {
45
+ await writeFile('src/features/new/notes.md', PLAIN);
46
+ await writeFile('src/features/new/schema.ts', HEADER);
47
+ const result = await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts']);
48
+ expect(result.deleted).toEqual([]);
49
+ expect(result.preserved).toEqual(['src/features/new/notes.md']);
50
+ expect(await fileExists('src/features/new/notes.md')).toBe(true);
51
+ });
52
+ // User story: As a developer running quickback compile back-to-back with no
53
+ // changes, I want the sweep to be a fast no-op — no spurious archive dirs
54
+ // littering the repo every time I recompile.
55
+ test('does not archive when nothing is stale', async () => {
56
+ await writeFile('src/features/new/schema.ts', HEADER);
57
+ const archiveDir = join(tmp, 'quickback', '.archives');
58
+ const result = await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts'], {
59
+ archiveDir,
60
+ });
61
+ expect(result.deleted).toEqual([]);
62
+ expect(result.archivePath).toBeUndefined();
63
+ expect(await fileExists('quickback/.archives')).toBe(false);
64
+ });
65
+ // User story: As a developer about to lose 30 generator-emitted files in a
66
+ // sweep, I want a snapshot of src/ saved automatically so I can recover if
67
+ // the compiler stopped emitting something I was depending on.
68
+ test('archives src/ before deleting when orphans are present', async () => {
69
+ await writeFile('src/features/old/schema.ts', HEADER);
70
+ await writeFile('src/features/new/schema.ts', HEADER);
71
+ const archiveDir = join(tmp, 'quickback', '.archives');
72
+ const result = await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts'], {
73
+ archiveDir,
74
+ });
75
+ expect(result.deleted).toEqual(['src/features/old/schema.ts']);
76
+ expect(result.archivePath).toBeDefined();
77
+ // Archive should contain a copy of the pre-sweep tree.
78
+ const archived = await fs.readdir(result.archivePath, { recursive: true });
79
+ const flat = archived.map((p) => (sep === '/' ? p : p.split(sep).join('/')));
80
+ expect(flat).toContain('features/old/schema.ts');
81
+ expect(flat).toContain('features/new/schema.ts');
82
+ });
83
+ // User story: As a developer who refactors aggressively over a week, I want
84
+ // older snapshots pruned automatically so the .archives folder doesn't
85
+ // balloon — last 3 generations is enough to walk back from a regret.
86
+ test('prunes old archives, keeping most recent N', async () => {
87
+ const archiveDir = join(tmp, 'archives');
88
+ await fs.mkdir(archiveDir, { recursive: true });
89
+ // Pre-seed 5 fake archives with sortable names.
90
+ for (const stamp of ['src-0001', 'src-0002', 'src-0003', 'src-0004']) {
91
+ await fs.mkdir(join(archiveDir, stamp));
92
+ }
93
+ await writeFile('src/features/old/schema.ts', HEADER);
94
+ await writeFile('src/features/new/schema.ts', HEADER);
95
+ await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts'], {
96
+ archiveDir,
97
+ archiveKeep: 3,
98
+ });
99
+ const remaining = (await fs.readdir(archiveDir)).filter((d) => d.startsWith('src-'));
100
+ expect(remaining.length).toBe(3);
101
+ // Newest survives — pruning is alphabetical-descending.
102
+ expect(remaining).toContain('src-0004');
103
+ expect(remaining).not.toContain('src-0001');
104
+ });
105
+ // User story: As a developer with SPA bundles in src/apps/cms/assets/, I want
106
+ // the sweep to leave that subtree alone — the upstream code wipes it
107
+ // wholesale before each write, so the per-file header probe would be
108
+ // wasted work.
109
+ test('respects skipPrefixes (SPA asset dirs)', async () => {
110
+ await writeFile('src/apps/cms/assets/main-abc123.js', HEADER);
111
+ await writeFile('src/apps/cms/assets/main-def456.js', HEADER);
112
+ const result = await sweepStaleGeneratedFiles(tmp, 'src', ['src/apps/cms/assets/main-def456.js'], {
113
+ skipPrefixes: ['src/apps/cms/assets'],
114
+ });
115
+ expect(result.deleted).toEqual([]);
116
+ expect(await fileExists('src/apps/cms/assets/main-abc123.js')).toBe(true);
117
+ });
118
+ // User story: As a developer with a now-empty src/features/old/ after a
119
+ // sweep, I don't want the bare directory hanging around — the file tree
120
+ // should match the manifest, including its shape.
121
+ test('removes empty directories left after deletion', async () => {
122
+ await writeFile('src/features/old/schema.ts', HEADER);
123
+ await writeFile('src/features/old/routes.ts', HEADER);
124
+ await writeFile('src/features/new/schema.ts', HEADER);
125
+ await sweepStaleGeneratedFiles(tmp, 'src', ['src/features/new/schema.ts']);
126
+ expect(await fileExists('src/features/old')).toBe(false);
127
+ expect(await fileExists('src/features/new')).toBe(true);
128
+ });
129
+ });
130
+ //# sourceMappingURL=sweep-stale.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sweep-stale.test.js","sourceRoot":"","sources":["../../src/lib/sweep-stale.test.ts"],"names":[],"mappings":"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"}
@@ -462,24 +462,8 @@ await db.update(applications).set({ deletedAt: now, modifiedAt: now })
462
462
 
463
463
  ### Error Handling
464
464
 
465
- **Option 1: Return a JSON error response** (recommended for most cases)
466
-
467
- Since action handlers receive the Hono context (`c`), you can return error responses directly:
468
-
469
- ```typescript
470
- async execute({ ctx, record, input, c }) {
471
- if (record.stage === 'hired') {
472
- return c.json({
473
- error: 'Cannot modify a hired application',
474
- code: 'ALREADY_HIRED',
475
- details: { currentStage: record.stage },
476
- }, 400);
477
- }
478
- // ... continue
479
- }
480
- ```
481
-
482
- **Option 2: Throw an ActionError**
465
+ **Throw an `ActionError`.** The route handler catches it by name and returns
466
+ `{ error, code, details }` with your `statusCode`:
483
467
 
484
468
  ```typescript
485
469
  import { ActionError } from "@quickback/compiler";
@@ -494,9 +478,11 @@ async execute({ ctx, record, input }) {
494
478
  }
495
479
  ```
496
480
 
497
- The `ActionError` constructor signature is `(message, code, statusCode = 400, details?)`. The compile step rewrites the `@quickback/compiler` import to the generated runtime class (`src/lib/types.ts`), and the route handler catches it by name and returns `{ error, code, details }` with your `statusCode`.
481
+ The `ActionError` constructor signature is `(message, code, statusCode = 400, details?)`. The compile step rewrites the `@quickback/compiler` import to the generated runtime class (`src/lib/types.ts`); the generated per-feature helper (`.quickback/define-action`) re-exports the same classes, so importing `ActionError` from the same module as `defineAction` also works.
482
+
483
+ **Do not return an error response from `execute`.** The generated route wraps whatever `execute` resolves to in the success response — `c.json(result)` — so a returned `c.json({ error }, 400)` is not passed through: the `Response` object itself is JSON-serialized and the client receives `{}` with status **200**. A raw `Response` return is honored only when the action declares `responseType: 'stream'` or `'file'`. Errors leave `execute` by throwing; the declared [`output`](/define/actions#declaring-action-outputs) describes the success body only.
498
484
 
499
- > Do **not** throw Hono's `HTTPException` from an action — the route handler doesn't unwrap it, so it surfaces as an unhandled **500 ACTION_EXECUTION_FAILED**. Use `ActionError` (or return `c.json(...)` directly) for clean 4xx responses.
485
+ > Do **not** throw Hono's `HTTPException` from an action — the route handler doesn't unwrap it, so it surfaces as an unhandled **500 ACTION_EXECUTION_FAILED**. Use `ActionError` for clean 4xx responses.
500
486
 
501
487
 
502
488
  ## See Also
@@ -8,6 +8,24 @@ The current release series. Older entries are archived by version range:
8
8
  - [v0.20 – v0.29](/changelog/v0.2x)
9
9
  - [v0.18 and earlier](/changelog/v0.1x)
10
10
 
11
+ ## v0.65.0 — August 16, 2026
12
+
13
+ ### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
14
+
15
+ The compiler now vendors the AWS SES, AWS SNS, combo-auth, and
16
+ upgrade-anonymous plugin sources into generated projects at
17
+ `src/plugins/<name>/`, completing what the subscriptions plugin started in
18
+ v0.64: **no generated project installs a `@quickback-dev/*` package from npm.**
19
+ The plugin code ships with the compiler that wires it, so the emitted callers
20
+ (`getSESConfig`, OTP callbacks, `upgradeAnonymous()` calls) can never skew from
21
+ the plugin version they were generated against — and upgrades arrive by
22
+ recompiling, not by `npm update`.
23
+
24
+ Recompile and the dependencies disappear from `package.json`; no config
25
+ changes needed. The `@quickback-dev/better-auth-*` npm packages are being
26
+ retired from the registry — the vendored source in your project is the
27
+ supported copy.
28
+
11
29
  ## v0.64.0 — August 15, 2026
12
30
 
13
31
  ### `contract.version` defaults to v2 — and no longer moves your URLs
@@ -53,8 +71,11 @@ URLs do not move. These do:
53
71
  - `?include=`, aggregate changesets (`owns`), and delegated principals become
54
72
  available without a pin.
55
73
 
56
- Pin `contract: { version: "v1" }` to opt out. Every compile that leaves
57
- `contract.version` unset warns once, naming what changed.
74
+ Pin `contract: { version: "v1" }` to opt out. A pre-v0.64 project that leaves
75
+ `contract.version` unset gets a one-time notice naming what changed — the
76
+ generated `wrangler.toml` header records the resolved version in a
77
+ `# quickback:contract` stamp, so new projects and projects that have already
78
+ compiled on v2 stay warning-free without restating the default.
58
79
 
59
80
  ### Action-schema harvest no longer keys on contract version
60
81
 
@@ -234,7 +234,7 @@ Binding names that clash with compiler-owned bindings are rejected at validation
234
234
  | `AUDIT_DB` | always (cross-tenant unsafe-action audit) |
235
235
  | `WEBHOOKS_DB`, `WEBHOOKS_QUEUE` | a webhooks binding is configured |
236
236
  | `KV` | always |
237
- | `R2_BUCKET`, `FILES_DB` | `fileStorage: defineFileStorage("cloudflare-r2")` |
237
+ | `R2_BUCKET`, `FILES_DB` | **managed** file storage — `defineFileStorage("cloudflare-r2", { managed: true })`. Presign-only R2 (the default) emits no bucket binding, so both names stay free for you to declare here. |
238
238
  | `VECTORIZE` | a Vectorize index is configured |
239
239
  | `BROADCASTER` | realtime is enabled |
240
240
  | `EMAIL` | `email: { provider: "cloudflare" }` |
@@ -264,7 +264,9 @@ Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified
264
264
  The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
265
265
 
266
266
  - Apps hostname middleware serves the SPA at root.
267
- - CORS / Better Auth `trustedOrigins` trusts requests whose `Origin` hostname matches.
267
+ - CORS trusts requests whose `Origin` hostname matches.
268
+ - Better Auth's own origin check (independent of CORS) trusts each hostname as
269
+ an `https://` origin — an entry with an explicit scheme is used verbatim.
268
270
 
269
271
  Empty or unset means no extension and zero behavior change for production.
270
272
 
@@ -278,7 +280,7 @@ EXTRA_APP_HOSTS = "app-preview.example.com,pr-42.example.com"
278
280
  wrangler secret put EXTRA_APP_HOSTS --env preview
279
281
  ```
280
282
 
281
- Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends both the apps allowlist and the CORS allowlist.
283
+ Mirrors the existing `BETTER_AUTH_URL` auto-trust behavior, where the deployed worker auto-trusts its own configured base origin without needing an explicit `trustedOrigins` entry. With `EXTRA_APP_HOSTS`, one env var extends all three allowlists — apps, CORS, and Better Auth's `trustedOrigins`. (Earlier v0.64 output stopped at the CORS layer: preflight passed, then Better Auth's own check rejected the origin. On older output, recompile — or set `BETTER_AUTH_URL` on the deploy target, since Better Auth always trusts its own base URL.)
282
284
 
283
285
  > **Multi-app deploys**
284
286
  >
@@ -50,13 +50,13 @@ These are configured as bindings in `wrangler.toml`, not environment variables.
50
50
  | `DB` | D1 Database | Feature tables (dual mode) |
51
51
  | `DATABASE` | D1 Database | All tables (single DB mode) |
52
52
  | `KV` | KV Namespace | Key-value storage |
53
- | `R2_BUCKET` | R2 Bucket | File storage (if configured) |
53
+ | `R2_BUCKET` | R2 Bucket | File storage (managed mode only — `managed: true`) |
54
54
  | `AI` | Workers AI | Embedding generation (if configured) |
55
55
  | `VECTORIZE` | Vectorize | Vector similarity search (if configured) |
56
56
  | `EMBEDDINGS_QUEUE` | Queue | Async embedding jobs (if configured) |
57
57
  | `WEBHOOKS_DB` | D1 Database | Webhook events (if configured) |
58
58
  | `WEBHOOKS_QUEUE` | Queue | Webhook delivery (if configured) |
59
- | `FILES_DB` | D1 Database | File metadata (if R2 configured) |
59
+ | `FILES_DB` | D1 Database | File metadata (managed mode only — `managed: true`) |
60
60
  | `BROADCASTER` | Durable Object | Realtime Broadcaster DO (if configured) |
61
61
  | `EMAIL` | send_email | Cloudflare Email Service (if email configured) |
62
62
 
@@ -145,6 +145,18 @@ evaluated for real, so a derivation in that file happens to work. Whether it
145
145
  works depends on unrelated content in the table file — declare the shape
146
146
  instead.
147
147
 
148
+ **`output` describes the success path only.** Error responses never pass
149
+ through it: throw
150
+ [`ActionError`](/api/actions#error-handling) and the route returns
151
+ `{ error, code, details }` with your status code — that error envelope is part
152
+ of the generated contract already, so do not fold error variants into
153
+ `output`. The one exception is an endpoint whose *success* body is
154
+ deliberately a status report (a webhook receiver acknowledging
155
+ `{ received: false, reason }`, say) — that is a union of success shapes, and
156
+ declaring it as `z.discriminatedUnion(...)` in `output` is correct. Do not
157
+ return an error object (or a `Response`) from `execute` to signal failure —
158
+ see [Error Handling](/api/actions#error-handling) for what actually happens.
159
+
148
160
  Parameterized standalone paths use Hono's `:param` syntax in authored source,
149
161
  for example `path: "/events/:eventId/check-in"`. The harvest planner converts
150
162
  those segments to the OpenAPI `{param}` form before applying the schema, so
@@ -157,6 +157,58 @@ Inside `authz.roles` / gate `who` bodies, `+` hierarchy sugar is banned — writ
157
157
  A `roles: [...]` name that matches nothing declared is fail-closed at runtime (it never grants) but historically silent. The compiler now emits a warning-level `AUTHZ_UNKNOWN_ROLE_NAME` diagnostic for any name that is not a provider/hierarchy role, pseudo-role, scoped role, or declared role/rule — a typo'd gate name is visible at compile time without breaking projects that use dynamic auth-provider role names. The heuristic runs only for projects that use the authz naming system (any of `authz.roles`, `authz.rules`, or `authz.scopes` declared); projects outside it keep the pre-existing silent-passthrough behavior for dynamic role names.
158
158
 
159
159
 
160
+ ## Subscription tiers
161
+
162
+ When the [subscriptions plugin](/platform/auth/plugins/subscriptions) is enabled, every tier you declare becomes an ordinary role string — `pro` becomes `tier_pro` — and the auth middleware stamps it into the caller's roles alongside their organization roles. There is no new access key and no new syntax: tiers compose in `authz.roles` exactly like everything else on this page.
163
+
164
+ ```typescript
165
+ // quickback.config.ts
166
+ export default defineConfig({
167
+ // ...providers, with plugins: { subscriptions: { tiers: { free: {...}, pro: {...} } } }
168
+ authz: {
169
+ roles: {
170
+ // `tier_pro` is stamped by the middleware — you never declare it.
171
+ paid: { roles: ['tier_pro'] },
172
+ // Compose it like any other name:
173
+ paidStaff: { and: [{ roles: ['paid'] }, { roles: ['admin', 'owner'] }] },
174
+ },
175
+ },
176
+ });
177
+ ```
178
+
179
+ ```typescript
180
+ // any feature
181
+ import { q, defineTable } from '@quickback/compiler';
182
+
183
+ export const reports = q.table('reports', {
184
+ id: q.id(),
185
+ title: q.text().required(),
186
+ organizationId: q.scope('organization'),
187
+ ...q.audit(),
188
+ ...q.softDelete(),
189
+ });
190
+
191
+ export default defineTable(reports, {
192
+ read: {
193
+ access: { roles: ['owner', 'admin', 'member'] },
194
+ views: {
195
+ // Pro and Enterprise subscribers; nobody else.
196
+ forecast: { fields: ['id', 'title'], access: { roles: ['paid'] } },
197
+ },
198
+ },
199
+ });
200
+ ```
201
+
202
+ **`tier_pro` means "pro or better".** A granting subscription stamps its own tier *and every tier below it* in your declared order, so an Enterprise subscriber carries `['tier_enterprise', 'tier_pro', 'tier_free']`. Gate on the lowest tier that should get in and higher tiers follow automatically — there is no hierarchy to configure, because tier order is already the order you declared them in.
203
+
204
+ **A caller with no subscription gets no tier roles at all** — not even `tier_free`. The base tier describes what checkout sells, not what a signed-up user is; only an actual subscription row with a granting status stamps anything. So `roles: ['tier_free']` means "someone who holds a free-tier subscription", and "any logged-in user" is still `AUTHENTICATED`.
205
+
206
+ Tier names are reserved. Declaring `authz.roles.tier_pro` is a compile error — it would shadow the stamped role rather than gate on it — and so is a tier whose derived name collides with a pseudo-role, a provider role, or an `auth.roleHierarchy` entry. Give the gate its own name, as `paid` does above.
207
+
208
+ Two independent bounds decide whether a subscription grants: its **status** (only `active` and `trialing` do) and its **expiry**. A row whose `expiresAt` passed more than 48 hours ago stops granting whatever its status claims — that grace window absorbs the normal renewal lag, while still bounding a row whose status froze because a webhook never arrived. A row with no `expiresAt` at all (admin-created, no Stripe period) keeps granting.
209
+
210
+ A downgrade is immediate on session auth. On a JWT it lasts until the token expires — one `auth.jwt.expiresIn` for a plain bearer, up to 15 minutes plus one TTL for a scope-bearing one, and `expiresIn` has no upper bound. For which statuses grant, which transports carry tier roles, and the full staleness picture, see [Entitlements](/platform/auth/plugins/subscriptions#entitlements-gating-access-on-tier).
211
+
160
212
  ## Outgrown this?
161
213
 
162
214
  If the answer depends on a row in one of *your* domain tables ("is this caller a
@@ -1,16 +1,14 @@
1
1
  # AWS SES Plugin
2
2
 
3
- `@quickback-dev/better-auth-aws-ses` is a Better Auth plugin that sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
3
+ Quickback's AWS SES plugin sends transactional emails via AWS SES. It handles AWS Signature V4 signing, HTML/text email templates, and rate limiting — designed to work in Cloudflare Workers (no Node.js `aws-sdk` dependency).
4
4
 
5
5
  > **Cloudflare Email is the default.** As of the Cloudflare Email Sending public beta, the zero-config `send_email` binding is Quickback's default transport for Cloudflare deploys — no API keys, no SES setup. See [Email Configuration](/configure#email-configuration). Use AWS SES when you need it (non-Cloudflare runtimes, existing SES infra, or specific deliverability/compliance requirements).
6
6
 
7
7
  ## Installation
8
8
 
9
- ```bash
10
- npm install @quickback-dev/better-auth-aws-ses
11
- ```
9
+ None. The compiler bundles the plugin source and emits it into your project at `src/plugins/aws-ses/` — it is **not** an npm dependency, and upgrades arrive by recompiling, not by `npm update`.
12
10
 
13
- This plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
11
+ The plugin is wired up only when you explicitly opt in via `email.provider: 'aws-ses'` in your Quickback config. Without that, `email.provider` defaults to `'cloudflare'` and the Cloudflare Email helper is used instead.
14
12
 
15
13
  ## Email Types
16
14
 
@@ -95,16 +93,16 @@ Recognized keys:
95
93
  | `'forget-password'` | Password reset request — and admin-bootstrap if `welcome` isn't set |
96
94
  | `'welcome'` | **Synthetic** — routed when `forget-password` fires for a user with no credential row yet (the admin-plugin → bootstrap flow). Without it, those sends fall through to `forget-password`. |
97
95
 
98
- Missing keys fall through to the built-in defaults from `@quickback-dev/better-auth-aws-ses`. The compiler stages each referenced file into `src/email-templates/<name>.ts` and wires the default import in `src/lib/auth.ts` — the template function is called inline from `sendVerificationOTP`, so it has access to whatever modules the file imports.
96
+ Missing keys fall through to the built-in defaults from the vendored plugin (`src/plugins/aws-ses/`). The compiler stages each referenced file into `src/email-templates/<name>.ts` and wires the default import in `src/lib/auth.ts` — the template function is called inline from `sendVerificationOTP`, so it has access to whatever modules the file imports.
99
97
 
100
98
  > **Provider scope.** Overrides are only honored when `email.provider: 'aws-ses'`. The Cloudflare Email path uses the helper's own template pipeline and ignores `plugins.emailOtp.templates`.
101
99
 
102
100
  ## Configuration
103
101
 
104
- ### Server Plugin
102
+ The compiler wires the plugin into `src/lib/auth.ts` automatically. The generated `getSESConfig(env)` maps environment to the vendored plugin's options:
105
103
 
106
104
  ```typescript
107
- import { awsSESPlugin } from "@quickback-dev/better-auth-aws-ses";
105
+ import { awsSESPlugin } from "../plugins/aws-ses";
108
106
 
109
107
  const auth = betterAuth({
110
108
  plugins: [
@@ -122,16 +120,6 @@ const auth = betterAuth({
122
120
  });
123
121
  ```
124
122
 
125
- ### Client Plugin
126
-
127
- ```typescript
128
- import { awsSESClientPlugin } from "@quickback-dev/better-auth-aws-ses/client";
129
-
130
- const authClient = createAuthClient({
131
- plugins: [awsSESClientPlugin()],
132
- });
133
- ```
134
-
135
123
  ## Required Environment Variables
136
124
 
137
125
  | Variable | Description |