@quickback-dev/cli 0.18.0 → 0.34.1
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/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +25 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +17 -0
- package/dist/commands/migrations.d.ts.map +1 -0
- package/dist/commands/migrations.js +328 -0
- package/dist/commands/migrations.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +33 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +39 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +73 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +22 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +1118 -1
- package/dist/skill/docs/compiler/config/domains.md +70 -10
- package/dist/skill/docs/compiler/config/index.md +74 -3
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/single-tenant.md +1 -1
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +357 -3
- package/dist/skill/docs/compiler/definitions/actions.md +85 -8
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +2 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/hooks.md +4 -0
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +106 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +1057 -0
- package/src/skill/docs/compiler/config/domains.md +26 -0
- package/src/skill/docs/compiler/config/index.md +74 -3
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/single-tenant.md +1 -1
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +357 -3
- package/src/skill/docs/compiler/definitions/actions.md +85 -8
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +2 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/admin.md +2 -2
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/hooks.md +4 -0
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +60 -0
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +169 -0
- package/src/skill/docs/stack/auth/plugins/index.md +32 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- package/src/skill/docs/stack/account-ui/worker.md +0 -362
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# AWS SNS Plugin (SMS OTP)
|
|
2
|
+
|
|
3
|
+
`@quickback-dev/better-auth-aws-sns` is the SMS transport package Quickback wires into Better Auth's built-in `phoneNumber` plugin when you opt in to SMS OTP. It signs SNS `Publish` requests with AWS Signature V4 using the Web Crypto API — zero AWS SDK dependency, runs on Cloudflare Workers.
|
|
4
|
+
|
|
5
|
+
> **Why SMS?** Corporate email gateways aggressively filter or rewrite transactional auth emails (link previews, click-tracking, MITM scanners). For some user bases SMS is the most reliable channel for a six-digit code that has to land in under a minute.
|
|
6
|
+
|
|
7
|
+
## What it provides
|
|
8
|
+
|
|
9
|
+
The package itself does **not** register a Better Auth plugin. Better Auth's builtin [`phoneNumber`](https://www.better-auth.com/docs/plugins/phone-number) plugin owns the endpoints (`/auth/v1/phone-number/send-otp`, `/verify`, `/sign-in/phone-number`, password reset). This package fills the `sendOTP` / `sendPasswordResetOTP` callbacks and the `phoneNumberValidator` hook.
|
|
10
|
+
|
|
11
|
+
| Export | Purpose |
|
|
12
|
+
|--------|---------|
|
|
13
|
+
| `sendSMSWithSNS(config, { to, message })` | Publish to SNS with SigV4 + in-memory rate limit + E.164 validation. |
|
|
14
|
+
| `smsTemplates.otp` / `smsTemplates.passwordReset` | Short transactional SMS bodies (single GSM-7 segment). |
|
|
15
|
+
| `isValidE164(phone)` / `normalizeE164(phone)` | Phone number validators. Wired into Better Auth's `phoneNumberValidator`. |
|
|
16
|
+
|
|
17
|
+
## Enable in config
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";
|
|
21
|
+
|
|
22
|
+
export default defineConfig({
|
|
23
|
+
name: "my-app",
|
|
24
|
+
sms: {
|
|
25
|
+
provider: "aws-sns",
|
|
26
|
+
region: "us-east-1",
|
|
27
|
+
senderId: "MyApp", // optional — non-US countries only
|
|
28
|
+
smsType: "Transactional", // default
|
|
29
|
+
},
|
|
30
|
+
providers: {
|
|
31
|
+
runtime: defineRuntime("cloudflare"),
|
|
32
|
+
database: defineDatabase("cloudflare-d1"),
|
|
33
|
+
auth: defineAuth("better-auth", {
|
|
34
|
+
emailAndPassword: { enabled: true },
|
|
35
|
+
plugins: { phoneNumber: true },
|
|
36
|
+
}),
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The compiler:
|
|
42
|
+
|
|
43
|
+
1. Adds `@quickback-dev/better-auth-aws-sns` to the generated `package.json`.
|
|
44
|
+
2. Emits a `getSNSConfig(env)` helper in `src/lib/auth.ts`.
|
|
45
|
+
3. Wires the `phoneNumber` plugin with `sendOTP`, `sendPasswordResetOTP`, and `phoneNumberValidator: isValidE164`.
|
|
46
|
+
4. Drops `AWS_SNS_REGION` / `APP_NAME` (and `SMS_SENDER_ID` / `SMS_TYPE` when set) into `[vars]` in `wrangler.toml`.
|
|
47
|
+
5. Forwards `c.executionCtx` from the Hono handler so OTP sends use `waitUntil(...)` — Better Auth advises **not** awaiting `sendOTP` to keep SMS latency out of the response.
|
|
48
|
+
|
|
49
|
+
## What you get from Better Auth's `phoneNumber` plugin
|
|
50
|
+
|
|
51
|
+
Schema (added to your user table):
|
|
52
|
+
|
|
53
|
+
| Column | Type | Notes |
|
|
54
|
+
|--------|------|-------|
|
|
55
|
+
| `phoneNumber` | `string \| null` | E.164 format |
|
|
56
|
+
| `phoneNumberVerified` | `boolean` | Set on successful verify |
|
|
57
|
+
|
|
58
|
+
Endpoints:
|
|
59
|
+
|
|
60
|
+
| Method | Path | Purpose |
|
|
61
|
+
|--------|------|---------|
|
|
62
|
+
| `POST` | `/auth/v1/phone-number/send-otp` | Trigger an OTP SMS |
|
|
63
|
+
| `POST` | `/auth/v1/phone-number/verify` | Verify the OTP code |
|
|
64
|
+
| `POST` | `/auth/v1/sign-in/phone-number` | Phone + password sign-in |
|
|
65
|
+
| `POST` | `/auth/v1/phone-number/request-password-reset` | Send a reset OTP |
|
|
66
|
+
| `POST` | `/auth/v1/phone-number/reset-password` | Complete password reset |
|
|
67
|
+
|
|
68
|
+
Defaults: 6-digit codes, 300s expiry, 3 verify attempts (exceeding deletes the OTP and returns 403). See the [Better Auth plugin docs](https://www.better-auth.com/docs/plugins/phone-number) for the full option surface.
|
|
69
|
+
|
|
70
|
+
## Required environment variables
|
|
71
|
+
|
|
72
|
+
Wrangler `[vars]` (non-secret, emitted by the compiler):
|
|
73
|
+
|
|
74
|
+
| Name | Default | Notes |
|
|
75
|
+
|------|---------|-------|
|
|
76
|
+
| `AWS_SNS_REGION` | `us-east-1` | Any SNS-enabled region. |
|
|
77
|
+
| `APP_NAME` | `<your config.name>` | Appears in the SMS body. |
|
|
78
|
+
| `SMS_SENDER_ID` | — | Optional. Set only for non-US/CA traffic. |
|
|
79
|
+
| `SMS_TYPE` | `Transactional` | Override only to send promotional traffic. |
|
|
80
|
+
|
|
81
|
+
Secrets (set with `wrangler secret put`):
|
|
82
|
+
|
|
83
|
+
| Name | Required | Notes |
|
|
84
|
+
|------|----------|-------|
|
|
85
|
+
| `AWS_ACCESS_KEY_ID` | yes | IAM key with `sns:Publish`. Shared with SES if used. |
|
|
86
|
+
| `AWS_SECRET_ACCESS_KEY` | yes | Companion secret. |
|
|
87
|
+
|
|
88
|
+
## AWS prerequisites
|
|
89
|
+
|
|
90
|
+
Before SMS will actually deliver in production, do this in the AWS console:
|
|
91
|
+
|
|
92
|
+
1. **Pull out of the SNS sandbox.** New accounts can only send to verified numbers and have a low monthly cap. Submit a "Request production access" case from the SNS SMS Preferences page.
|
|
93
|
+
2. **Set a monthly spend cap.** SMS gets expensive fast — set a limit before you go live.
|
|
94
|
+
3. **US A2P (10DLC).** Long codes sending app-to-person SMS to US numbers must be registered with TCR (The Campaign Registry) via Pinpoint SMS Voice v2. Carrier filtering rejects unregistered A2P traffic. Allow several weeks for approval.
|
|
95
|
+
4. **Sender ID support.** Alphanumeric sender IDs work in many countries (UK, France, Germany, India, etc.) but **not** the US or Canada. Pick origination identities per country.
|
|
96
|
+
5. **IAM policy.** The access key needs `sns:Publish` on `*` plus `sns:SetSMSAttributes` if you want to manage the spend cap programmatically.
|
|
97
|
+
|
|
98
|
+
## Validation and rate limiting
|
|
99
|
+
|
|
100
|
+
- **E.164 only.** `isValidE164` rejects anything that's not `+[country code][7–14 digits]`. There is no automatic country-code inference — capture the country in your UI (e.g. `react-phone-number-input`).
|
|
101
|
+
- **Send-side rate limit.** The package's in-memory map caps sends per phone (hourly + daily) when `rateLimit` is set on the config. It's an isolate-local guard; for stricter limits put a KV-backed limiter in front of `/auth/v1/phone-number/send-otp`.
|
|
102
|
+
- **Verify-side rate limit.** Better Auth's `phoneNumber` plugin enforces 3 attempts before deleting the OTP. You can additionally tighten Quickback's per-route limit on `/auth/v1/phone-number/send-otp` via `auth.rateLimit.customRules`.
|
|
103
|
+
|
|
104
|
+
## Carrier filtering
|
|
105
|
+
|
|
106
|
+
Keep the SMS body short, transactional, and link-free. The default template is:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
Your <AppName> code is 123456. Expires in 5 min. Don't share it.
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
— under 80 characters, no URL, no marketing copy. Carriers filter long messages, links, and brand-imitation prefixes aggressively. If you customize the body, keep it under one GSM-7 segment (160 chars) to avoid multi-segment billing.
|
|
113
|
+
|
|
114
|
+
## Verifying the wiring
|
|
115
|
+
|
|
116
|
+
After compile, check the generated `src/lib/auth.ts`:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { sendSMSWithSNS, smsTemplates, isValidE164 } from "@quickback-dev/better-auth-aws-sns";
|
|
120
|
+
|
|
121
|
+
function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
|
|
122
|
+
|
|
123
|
+
function createAuth(env, cf, executionCtx) {
|
|
124
|
+
const fireAndForget = (p) => { /* waitUntil(p) */ };
|
|
125
|
+
|
|
126
|
+
return betterAuth({
|
|
127
|
+
plugins: [
|
|
128
|
+
phoneNumber({
|
|
129
|
+
phoneNumberValidator: isValidE164,
|
|
130
|
+
sendOTP: async ({ phoneNumber, code }) => {
|
|
131
|
+
fireAndForget(sendSMSWithSNS(getSNSConfig(env), {
|
|
132
|
+
to: phoneNumber,
|
|
133
|
+
message: smsTemplates.otp.message({ code, appName: ... }),
|
|
134
|
+
}));
|
|
135
|
+
},
|
|
136
|
+
// ...
|
|
137
|
+
}),
|
|
138
|
+
],
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
That's the contract: callbacks are fire-and-forget via `executionCtx.waitUntil`, never `await`ed.
|
|
144
|
+
|
|
145
|
+
## Sign-in flow
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
// 1. Request OTP
|
|
149
|
+
await fetch('/auth/v1/phone-number/send-otp', {
|
|
150
|
+
method: 'POST',
|
|
151
|
+
headers: { 'Content-Type': 'application/json' },
|
|
152
|
+
body: JSON.stringify({ phoneNumber: '+14155550100' }),
|
|
153
|
+
});
|
|
154
|
+
|
|
155
|
+
// 2. Verify the code the user types in
|
|
156
|
+
const res = await fetch('/auth/v1/phone-number/verify', {
|
|
157
|
+
method: 'POST',
|
|
158
|
+
headers: { 'Content-Type': 'application/json' },
|
|
159
|
+
body: JSON.stringify({ phoneNumber: '+14155550100', code: '123456' }),
|
|
160
|
+
});
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
For Better Auth's signed-in client SDK, use `authClient.phoneNumber.sendOtp(...)` / `authClient.phoneNumber.verify(...)`.
|
|
164
|
+
|
|
165
|
+
## Compliance reminders
|
|
166
|
+
|
|
167
|
+
- **TCPA (US).** Capture explicit opt-in for transactional SMS at signup; keep an audit trail. STOP / HELP keyword handling is mandatory for A2P traffic — SNS handles standard keywords automatically on registered origination numbers, but verify it's enabled.
|
|
168
|
+
- **GDPR (EU).** Phone numbers are personal data. Use Quickback's masking pillar to redact them in CMS views where appropriate.
|
|
169
|
+
- **Don't use SMS as your only second factor.** SIM-swap attacks are real; pair phone OTP with passkeys / TOTP for high-value accounts.
|
|
@@ -64,6 +64,38 @@ auth: defineAuth("better-auth", {
|
|
|
64
64
|
|
|
65
65
|
**Note:** If you send `Content-Type: application/json`, include a body (an empty `{}` is fine). This avoids request parsing errors in some clients.
|
|
66
66
|
|
|
67
|
+
### SMS OTP (with AWS SNS)
|
|
68
|
+
|
|
69
|
+
When `phoneNumber` is enabled, the compiler wires Better Auth's built-in `phoneNumber` plugin to AWS SNS for SMS delivery via [`@quickback-dev/better-auth-aws-sns`](/stack/auth/plugins/aws-sns). The plugin adds `phoneNumber` / `phoneNumberVerified` columns to the user table, handles OTP generation + storage + verify-attempt limits, and exposes endpoints for phone-only sign-in, phone+password sign-in, and password reset via SMS.
|
|
70
|
+
|
|
71
|
+
**Enable in config:**
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
export default defineConfig({
|
|
75
|
+
name: "my-app",
|
|
76
|
+
sms: {
|
|
77
|
+
provider: "aws-sns",
|
|
78
|
+
region: "us-east-1",
|
|
79
|
+
},
|
|
80
|
+
providers: {
|
|
81
|
+
runtime: defineRuntime("cloudflare"),
|
|
82
|
+
database: defineDatabase("cloudflare-d1"),
|
|
83
|
+
auth: defineAuth("better-auth", {
|
|
84
|
+
plugins: { phoneNumber: true },
|
|
85
|
+
}),
|
|
86
|
+
},
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Endpoints (managed by Better Auth):**
|
|
91
|
+
- `POST /auth/v1/phone-number/send-otp`
|
|
92
|
+
- `POST /auth/v1/phone-number/verify`
|
|
93
|
+
- `POST /auth/v1/sign-in/phone-number`
|
|
94
|
+
- `POST /auth/v1/phone-number/request-password-reset`
|
|
95
|
+
- `POST /auth/v1/phone-number/reset-password`
|
|
96
|
+
|
|
97
|
+
**Why use SMS:** corporate email gateways frequently break transactional auth emails (link rewriting, click-tracking, MITM scanners). SMS is the most reliable channel for a six-digit code that has to land in under a minute. See the [AWS SNS plugin page](/stack/auth/plugins/aws-sns) for IAM, 10DLC registration, and sender-ID details.
|
|
98
|
+
|
|
67
99
|
### AWS SES Plugin
|
|
68
100
|
|
|
69
101
|
This is a Quickback-provided Better Auth plugin for Email OTP and other transactional emails. It handles SES signing and delivery over the Web Crypto API so it runs in Cloudflare Workers without the AWS SDK. It is wired up only when you opt in via `email.provider: 'aws-ses'` — the default transport is Cloudflare Email Sending (`send_email` binding).
|
|
@@ -331,6 +363,80 @@ Better Auth's older `better-auth/plugins/mcp` is being deprecated in favour of `
|
|
|
331
363
|
|
|
332
364
|
Keep `apiKey` enabled alongside it — server-to-server flows (cron, scripts) want a static key; OAuth is for interactive clients.
|
|
333
365
|
|
|
366
|
+
### Custom plugins (escape hatch)
|
|
367
|
+
|
|
368
|
+
The named plugins above cover the curated set Quickback ships first-class wiring for. For anything else — third-party packages (`@better-auth-kit/audit`, …), Better Auth built-ins outside the registry, or project-local plugins — use `customPlugins`.
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
auth: defineAuth("better-auth", {
|
|
372
|
+
emailAndPassword: { enabled: true },
|
|
373
|
+
plugins: { passkey: true, organization: true },
|
|
374
|
+
customPlugins: [
|
|
375
|
+
// (1) Project-local plugin file at quickback/plugins/long-session.ts
|
|
376
|
+
{ from: "./plugins/long-session", export: "longSessionPlugin" },
|
|
377
|
+
// (2) Third-party npm package
|
|
378
|
+
{
|
|
379
|
+
from: "@better-auth-kit/audit",
|
|
380
|
+
export: "auditPlugin",
|
|
381
|
+
args: { events: ["sign-in"] },
|
|
382
|
+
dependencies: { "@better-auth-kit/audit": "^1.0.0" },
|
|
383
|
+
},
|
|
384
|
+
],
|
|
385
|
+
}),
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
Each entry in `customPlugins` is an explicit import descriptor. The compiler runs each through Zod, then emits an `import { <export> } from "<from>"` line in the generated `src/lib/auth.ts` and appends the call (or bare symbol) to the `plugins: [...]` array — after the named plugins, in declared order.
|
|
389
|
+
|
|
390
|
+
#### `from`
|
|
391
|
+
|
|
392
|
+
- **Relative path** (must start with `./` or `../`, must resolve under `./plugins/`): refers to a file you author in `quickback/plugins/`. The CLI auto-discovers `quickback/plugins/**/*.ts` and ships matching files; the compiler copies the source into the generated output at `src/plugins/<name>.ts` and rewrites the emitted import path. Files in `quickback/plugins/` that aren't referenced by any descriptor are uploaded but ignored — the compiler picks only what's needed.
|
|
393
|
+
- **Bare specifier** (any value not starting with `./` or `../`): treated as an npm import, emitted verbatim. Combine with `dependencies` so the package lands in the generated `package.json`.
|
|
394
|
+
|
|
395
|
+
#### `export`
|
|
396
|
+
|
|
397
|
+
The named export to import. Must be a valid JS identifier (e.g. `longSessionPlugin`, `auditPlugin`). Use the symbol's source name from the file or package — Quickback emits the import as-is.
|
|
398
|
+
|
|
399
|
+
#### `args` (optional)
|
|
400
|
+
|
|
401
|
+
- **Omitted** → emits the symbol uncalled (`plugins: [..., longSessionPlugin]`). Use this when your export is already a `BetterAuthPlugin` instance.
|
|
402
|
+
- **Provided** → emits a factory call with JSON-serialized args (`plugins: [..., auditPlugin({"events":["sign-in"]})]`). The value must be JSON-serializable; functions and other non-serializable values fail at compile time. (The user config crosses an HTTP boundary as JSON, so this constraint exists by construction.)
|
|
403
|
+
|
|
404
|
+
#### `dependencies` (optional)
|
|
405
|
+
|
|
406
|
+
`Record<string, string>` of npm packages and version specs. Merged into the generated `package.json` alongside the named-plugin deps. Only meaningful for bare-specifier `from` — relative-path entries don't need to declare anything.
|
|
407
|
+
|
|
408
|
+
#### Project-local plugin shape
|
|
409
|
+
|
|
410
|
+
A plugin file in `quickback/plugins/` is plain Better Auth — the compiler doesn't transform it. Author it like any other BA plugin and let TypeScript check it against the `BetterAuthPlugin` type:
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
// quickback/plugins/long-session.ts
|
|
414
|
+
import type { BetterAuthPlugin } from "better-auth";
|
|
415
|
+
|
|
416
|
+
export const longSessionPlugin = {
|
|
417
|
+
id: "long-session",
|
|
418
|
+
databaseHooks: {
|
|
419
|
+
session: {
|
|
420
|
+
create: {
|
|
421
|
+
before: async (session) => ({
|
|
422
|
+
data: {
|
|
423
|
+
...session,
|
|
424
|
+
// 5-year session for an event-app use case
|
|
425
|
+
expiresAt: new Date(Date.now() + 5 * 365 * 24 * 60 * 60 * 1000),
|
|
426
|
+
},
|
|
427
|
+
}),
|
|
428
|
+
},
|
|
429
|
+
},
|
|
430
|
+
},
|
|
431
|
+
} satisfies BetterAuthPlugin;
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
#### Out of scope
|
|
435
|
+
|
|
436
|
+
- **No schema generation.** If your plugin needs database tables, declare them as a Quickback feature — the compiler does not run schema introspection on custom plugins.
|
|
437
|
+
- **No conditional inclusion.** Every entry in `customPlugins` is always emitted. Gate environment-specific plugins inside the plugin file itself.
|
|
438
|
+
- **No name collision check against the named registry.** Duplicate registration is a Better Auth runtime concern, not a compile-time one — don't reach for `customPlugins` to override a named plugin's options; use the object form on `plugins` instead.
|
|
439
|
+
|
|
334
440
|
## Where This Runs
|
|
335
441
|
|
|
336
442
|
All Better Auth plugin routes are served under your auth base path:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.34.1",
|
|
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",
|