@lupinum/better-convex-agents 0.1.0-rc.5 → 0.2.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.
- package/README.md +1 -1
- package/dist/agent/AGENTS.md +7 -4
- package/dist/agent/pages/docs/build/agents/connect-chatgpt-and-claude.md +2 -2
- package/dist/agent/pages/docs/build/agents/mcp-application.md +5 -5
- package/dist/agent/pages/docs/build/agents/mcp-apps.md +1 -1
- package/dist/agent/pages/docs/build/agents/mcp.md +5 -6
- package/dist/agent/pages/docs/build/application-behavior/error-handling.md +40 -1
- package/dist/agent/pages/docs/build/authentication/account-deletion.md +73 -0
- package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +1 -1
- package/dist/agent/pages/docs/build/authentication/backend-authorization.md +6 -1
- package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +3 -3
- package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +4 -2
- package/dist/agent/pages/docs/build/authentication/company-sign-in.md +4 -4
- package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +4 -4
- package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +3 -0
- package/dist/agent/pages/docs/build/authentication/social-sign-in.md +4 -4
- package/dist/agent/pages/docs/build/authentication/transactional-email.md +45 -10
- package/dist/agent/pages/docs/build/files/private-downloads.md +126 -0
- package/dist/agent/pages/docs/build/files/storage-urls.md +8 -3
- package/dist/agent/pages/docs/build/files/upload-files.md +2 -2
- package/dist/agent/pages/docs/build/functions/limits-and-audit.md +142 -4
- package/dist/agent/pages/docs/build/functions/start-here.md +1 -1
- package/dist/agent/pages/docs/build/functions/testing.md +25 -1
- package/dist/agent/pages/docs/build/queries/loading-and-stale-data.md +1 -1
- package/dist/agent/pages/docs/build/queries/pagination.md +2 -2
- package/dist/agent/pages/docs/build/queries/reactive-arguments.md +46 -0
- package/dist/agent/pages/docs/build/server/server-convex.md +16 -1
- package/dist/agent/pages/docs/build/write-data/concurrent-operations.md +1 -1
- package/dist/agent/pages/docs/build/write-data/forms.md +1 -1
- package/dist/agent/pages/docs/build/write-data/multi-step-operations.md +1 -1
- package/dist/agent/pages/docs/build/write-data/optimistic-updates.md +1 -1
- package/dist/agent/pages/docs/get-started/add-authentication.md +213 -158
- package/dist/agent/pages/docs/get-started/choose-your-path.md +5 -5
- package/dist/agent/pages/docs/get-started/complete-and-delete.md +139 -0
- package/dist/agent/pages/docs/get-started/first-realtime-page.md +68 -35
- package/dist/agent/pages/docs/get-started/installation.md +108 -72
- package/dist/agent/pages/docs/get-started/next-steps.md +32 -0
- package/dist/agent/pages/docs/get-started/plain-vue.md +145 -44
- package/dist/agent/pages/docs/get-started/project-structure.md +9 -18
- package/dist/agent/pages/docs/get-started/protect-data.md +85 -36
- package/dist/agent/pages/docs/operations/before-launch.md +1 -1
- package/dist/agent/pages/docs/operations/deploy-to-vercel.md +7 -7
- package/dist/agent/pages/docs/operations/deployment.md +2 -2
- package/dist/agent/pages/docs/operations/environment-variables.md +5 -5
- package/dist/agent/pages/docs/operations/log-streams.md +128 -0
- package/dist/agent/pages/docs/operations/release-compatibility.md +7 -7
- package/dist/agent/pages/docs/operations/troubleshooting.md +5 -0
- package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +16 -11
- package/dist/agent/pages/docs/overview/comparison.md +2 -2
- package/dist/agent/pages/docs/overview/limitations.md +2 -2
- package/dist/agent/pages/docs/overview/who-it-is-for.md +5 -5
- package/dist/agent/pages/docs/recipes/dynamic-query-list.md +1 -1
- package/dist/agent/pages/docs/recipes/error-messages.md +1 -1
- package/dist/agent/pages/docs/recipes/guest-users.md +69 -17
- package/dist/agent/pages/docs/recipes/multiple-file-uploads.md +1 -1
- package/dist/agent/pages/docs/recipes/optimistic-todo-list.md +1 -1
- package/dist/agent/pages/docs/recipes/organization-permissions.md +1 -1
- package/dist/agent/pages/docs/recipes/realtime-feed.md +1 -1
- package/dist/agent/pages/docs/recipes/sign-in-link.md +129 -0
- package/dist/agent/pages/docs/reference/api-surface.md +11 -0
- package/dist/agent/pages/docs/reference/cli.md +46 -17
- package/dist/agent/pages/docs/reference/error-types.md +12 -2
- package/dist/agent/pages/docs/reference/operation-error-codes.md +15 -1
- package/dist/agent/pages/docs/reference/package-exports.md +3 -2
- package/dist/agent/pages/docs/reference/server-api.md +5 -1
- package/dist/agent/pages/docs.md +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.mjs +1 -1
- package/dist/internal.d.mts +1 -1
- package/dist/internal.d.ts +1 -1
- package/dist/internal.mjs +1 -1
- package/dist/mcp.mjs +4 -2
- package/dist/shared/{better-convex-agents.DWStY2mj.mjs → better-convex-agents.BAvd6ID4.mjs} +475 -393
- package/dist/shared/{better-convex-agents.Jrci7p3C.d.mts → better-convex-agents.l5qUkNCR.d.mts} +14 -2
- package/dist/shared/{better-convex-agents.Jrci7p3C.d.ts → better-convex-agents.l5qUkNCR.d.ts} +14 -2
- package/dist/test.d.mts +1 -1
- package/dist/test.d.ts +1 -1
- package/dist/test.mjs +1 -1
- package/package.json +4 -4
- package/dist/agent/pages/docs/get-started/add-a-mutation.md +0 -124
package/README.md
CHANGED
|
@@ -47,7 +47,7 @@ the standard OAuth challenge, and gives your tools the verified user as a typed
|
|
|
47
47
|
## Installation
|
|
48
48
|
|
|
49
49
|
```bash
|
|
50
|
-
pnpm add @lupinum/better-convex-agents
|
|
50
|
+
pnpm add @lupinum/better-convex-agents @lupinum/better-convex-functions @modelcontextprotocol/server@2.3.1
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
The two Lupinum packages are released together with the same version, and each
|
package/dist/agent/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# @lupinum/better-convex-agents 0.
|
|
1
|
+
# @lupinum/better-convex-agents 0.2.0 documentation
|
|
2
2
|
|
|
3
|
-
These pages describe the installed version 0.
|
|
3
|
+
These pages describe the installed version 0.2.0. Prefer them over the
|
|
4
4
|
website and over knowledge of earlier versions: the API changed during the 1.0 betas.
|
|
5
5
|
|
|
6
6
|
## Start here
|
|
@@ -36,7 +36,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
36
36
|
- [Choose your path](./pages/docs/get-started/choose-your-path.md)
|
|
37
37
|
- [Installation](./pages/docs/get-started/installation.md)
|
|
38
38
|
- [First real-time page](./pages/docs/get-started/first-realtime-page.md)
|
|
39
|
-
- [
|
|
39
|
+
- [Complete and delete](./pages/docs/get-started/complete-and-delete.md)
|
|
40
40
|
- [Add authentication](./pages/docs/get-started/add-authentication.md)
|
|
41
41
|
- [Protect data](./pages/docs/get-started/protect-data.md)
|
|
42
42
|
- [Project structure](./pages/docs/get-started/project-structure.md)
|
|
@@ -80,6 +80,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
80
80
|
- [Upload files](./pages/docs/build/files/upload-files.md)
|
|
81
81
|
- [Storage URLs](./pages/docs/build/files/storage-urls.md)
|
|
82
82
|
- [File validation and deletion](./pages/docs/build/files/validation-and-deletion.md)
|
|
83
|
+
- [Private downloads](./pages/docs/build/files/private-downloads.md)
|
|
83
84
|
- [Connection state](./pages/docs/build/application-behavior/connection-state.md)
|
|
84
85
|
- [Error handling](./pages/docs/build/application-behavior/error-handling.md)
|
|
85
86
|
- [Logging](./pages/docs/build/application-behavior/logging.md)
|
|
@@ -100,7 +101,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
100
101
|
- [Test your app](./pages/docs/build/functions/testing.md)
|
|
101
102
|
- [Cost](./pages/docs/build/functions/cost.md)
|
|
102
103
|
- [Threat model](./pages/docs/build/functions/threat-model.md)
|
|
103
|
-
- [Rate limits and
|
|
104
|
+
- [Rate limits, audit log and call events](./pages/docs/build/functions/limits-and-audit.md)
|
|
104
105
|
|
|
105
106
|
### Recipes
|
|
106
107
|
|
|
@@ -118,6 +119,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
118
119
|
- [Error messages](./pages/docs/recipes/error-messages.md)
|
|
119
120
|
- [Several file uploads](./pages/docs/recipes/multiple-file-uploads.md)
|
|
120
121
|
- [Guest users](./pages/docs/recipes/guest-users.md)
|
|
122
|
+
- [Sign-in link](./pages/docs/recipes/sign-in-link.md)
|
|
121
123
|
|
|
122
124
|
### Concepts
|
|
123
125
|
|
|
@@ -141,6 +143,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
141
143
|
- [Security model](./pages/docs/operations/security-model.md)
|
|
142
144
|
- [Upgrade to 1.0](./pages/docs/operations/upgrade-to-1-0.md)
|
|
143
145
|
- [Before your app goes live](./pages/docs/operations/before-launch.md)
|
|
146
|
+
- [Log streams and PostHog](./pages/docs/operations/log-streams.md)
|
|
144
147
|
|
|
145
148
|
### Reference
|
|
146
149
|
|
|
@@ -52,7 +52,7 @@ client registration is off, so the host cannot create a client itself.
|
|
|
52
52
|
|
|
53
53
|
1. Create the client:
|
|
54
54
|
```bash
|
|
55
|
-
pnpm exec better-convex convex run connections:createHostClient '{"host":"claude"}'
|
|
55
|
+
pnpm exec better-convex-nuxt convex run connections:createHostClient '{"host":"claude"}'
|
|
56
56
|
```
|
|
57
57
|
Record the returned `clientId`. The client accepts only Claude's fixed
|
|
58
58
|
callback and every scope in your profile.
|
|
@@ -80,7 +80,7 @@ middle of the setup.
|
|
|
80
80
|
callback ID.
|
|
81
81
|
3. Create the client with that callback:
|
|
82
82
|
```bash
|
|
83
|
-
pnpm exec better-convex convex run connections:createHostClient \
|
|
83
|
+
pnpm exec better-convex-nuxt convex run connections:createHostClient \
|
|
84
84
|
'{"host":"chatgpt","redirectUri":"https://chatgpt.com/connector_platform_oauth_redirect"}'
|
|
85
85
|
```
|
|
86
86
|
4. In **Advanced OAuth settings**, set **Registration method** to
|
|
@@ -31,7 +31,7 @@ every rule that the profile sets.
|
|
|
31
31
|
## Install the packages
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
|
-
pnpm add @lupinum/better-convex-agents
|
|
34
|
+
pnpm add @lupinum/better-convex-agents @lupinum/better-convex-functions @modelcontextprotocol/server@2.3.1 zod@4.6.5
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
`@better-auth/oauth-provider` is already installed with Better Auth support.
|
|
@@ -40,7 +40,7 @@ Keep `SITE_URL` equal to the public Nuxt origin. Convex supplies
|
|
|
40
40
|
|
|
41
41
|
## 1. Add the OAuth tables to the auth schema
|
|
42
42
|
|
|
43
|
-
`better-convex init` writes a local auth component in `convex/betterAuth/`.
|
|
43
|
+
`better-convex-nuxt auth init` writes a local auth component in `convex/betterAuth/`.
|
|
44
44
|
Its schema has no OAuth tables yet. Without them, every OAuth request fails
|
|
45
45
|
with `AUTH_MODEL_UNKNOWN`. Add the OAuth provider to the schema plugins:
|
|
46
46
|
|
|
@@ -68,12 +68,12 @@ export function createAuthSchemaPlugins(authIssuer: string) {
|
|
|
68
68
|
Keep the other entries as they are in your file. Then regenerate the schema:
|
|
69
69
|
|
|
70
70
|
```bash
|
|
71
|
-
pnpm exec better-convex auth schema \
|
|
71
|
+
pnpm exec better-convex-nuxt auth schema \
|
|
72
72
|
--config convex/betterAuth/schemaOptions.ts \
|
|
73
73
|
--output convex/betterAuth
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
-
Keep `pnpm exec better-convex convex dev` running so that Convex deploys the
|
|
76
|
+
Keep `pnpm exec better-convex-nuxt convex dev` running so that Convex deploys the
|
|
77
77
|
new tables. The schema plugin only adds tables. Step 2 turns on the OAuth
|
|
78
78
|
provider at runtime.
|
|
79
79
|
|
|
@@ -521,7 +521,7 @@ const { mutate: revoke, pending } = useConvexMutation(api.connections.revoke)
|
|
|
521
521
|
|
|
522
522
|
1. Deploy to a separate test environment with its own auth and proxy secrets,
|
|
523
523
|
as described in the [deployment guide](../../operations/deployment.md).
|
|
524
|
-
2. Run `pnpm exec better-convex convex run auth:ensureSigningKey '{}'`. Check
|
|
524
|
+
2. Run `pnpm exec better-convex-nuxt convex run auth:ensureSigningKey '{}'`. Check
|
|
525
525
|
that the returned `kid` appears at the public `/api/auth/jwks` endpoint
|
|
526
526
|
before anyone signs in.
|
|
527
527
|
3. Create a host client with `connections:createHostClient` and connect the
|
|
@@ -103,7 +103,7 @@ await writeFile(
|
|
|
103
103
|
}
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
Run `pnpm build:mcp-ui` before you run `pnpm exec better-convex convex dev`,
|
|
106
|
+
Run `pnpm build:mcp-ui` before you run `pnpm exec better-convex-nuxt convex dev`,
|
|
107
107
|
and commit the generated `convex/mcp/notesCardHtml.ts`. A production build
|
|
108
108
|
that deploys Convex, as in [Deploy to Vercel](../../operations/deploy-to-vercel.md),
|
|
109
109
|
deploys the committed file.
|
|
@@ -25,10 +25,9 @@ derives them from its operations, and `createMcpServer(auth, { name, agents })`
|
|
|
25
25
|
publishes them through the same transport: see [Tools and approvals](./tools-and-approvals.md)
|
|
26
26
|
and [The MCP door](./mcp-door.md).
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
release.
|
|
28
|
+
The integration implements the final MCP `2026-07-28` contract through exact
|
|
29
|
+
`@modelcontextprotocol/server@2.3.1`. The protocol is stable. The agents package is
|
|
30
|
+
still `0.x`, so a minor version can change its API.
|
|
32
31
|
|
|
33
32
|
The MCP entry does not depend on Nuxt, Nitro, Better Auth, or your
|
|
34
33
|
authorization rules. Better Auth is optional: `createBetterConvexAuth`
|
|
@@ -64,7 +63,7 @@ mutation, action, tool result, log, or iframe.
|
|
|
64
63
|
## Install
|
|
65
64
|
|
|
66
65
|
```bash
|
|
67
|
-
pnpm add @lupinum/better-convex-agents
|
|
66
|
+
pnpm add @lupinum/better-convex-agents @lupinum/better-convex-functions @modelcontextprotocol/server@2.3.1 zod@4.6.5
|
|
68
67
|
```
|
|
69
68
|
|
|
70
69
|
`@modelcontextprotocol/server` is an exact peer dependency of
|
|
@@ -83,7 +82,7 @@ is the complete, tested example.
|
|
|
83
82
|
`createBetterConvexAuth`. It configures PKCE public clients, consent,
|
|
84
83
|
ten-minute access tokens bound to your `/mcp` resource, and renewal that
|
|
85
84
|
ends with the Better Auth session. The auth component from
|
|
86
|
-
`better-convex init` also needs `oauthProvider()` in its schema plugins.
|
|
85
|
+
`better-convex-nuxt auth init` also needs `oauthProvider()` in its schema plugins.
|
|
87
86
|
2. **Mount the routes.** Register `/mcp` and its protected-resource metadata
|
|
88
87
|
route next to `auth.registerRoutes(http)`.
|
|
89
88
|
3. **Handle MCP.** Call `handleMcpRequest` once, and spread
|
|
@@ -61,6 +61,45 @@ async function archive() {
|
|
|
61
61
|
|
|
62
62
|
Use `code`, not message substrings, for decisions. A `server` error's `code` is the `data.code` of the `ConvexError`, and its `message` is the text the Convex function wrote in `data.message`. Show that message to the user only when the backend writes user-facing text.
|
|
63
63
|
|
|
64
|
+
## Show why and how to fix it
|
|
65
|
+
|
|
66
|
+
A Convex function can tell the user why it refused and what they can do. With `@lupinum/better-convex-functions`, pass `why` and `fix` to `fail`:
|
|
67
|
+
|
|
68
|
+
```ts [convex/documents.ts]
|
|
69
|
+
fail('INVALID_INPUT', 'The invoice could not be sent.', {
|
|
70
|
+
why: 'The client has no email address.',
|
|
71
|
+
fix: 'Add an email address in the client settings.',
|
|
72
|
+
})
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Without the functions package, put them in the error data: `throw new ConvexError({ code, message, why, fix })`.
|
|
76
|
+
|
|
77
|
+
The `ConvexCallError` then has `why` and `fix`:
|
|
78
|
+
|
|
79
|
+
```vue
|
|
80
|
+
<section v-if="error" role="alert">
|
|
81
|
+
<p>{{ error.message }}</p>
|
|
82
|
+
<p v-if="error.why">{{ error.why }}</p>
|
|
83
|
+
<p v-if="error.fix">{{ error.fix }}</p>
|
|
84
|
+
</section>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Write `why` and `fix` for the user. Do not build them from internal state, IDs, or the error text of another service. `NOT_FOUND` and `FAILED` take no help, and `fail` rejects it at compile time: `NOT_FOUND` must read like a missing row, and `FAILED` keeps its detail in the log. Agents that call the function through the MCP door receive the same `why` and `fix`. They get help only with the library's codes: for a code of your own, the MCP door answers `FAILED` without it. When work that a person approved fails, only its `code` and `message` are kept: the person who approved it and the agent that checks its request see no `why` or `fix`.
|
|
88
|
+
|
|
89
|
+
`why` and `fix` are server text in one language. When your app shows its own text for each `code`, for example in another language, keep that text for people. Then `why` and `fix` are for agents, and for a `code` that has no text of its own.
|
|
90
|
+
|
|
91
|
+
## Quote the request ID
|
|
92
|
+
|
|
93
|
+
When a Convex function fails, `error.requestId` holds the Convex request ID of the call. The Convex logs and log streams record the same ID. Show it with an unexpected failure, so that the user can quote it:
|
|
94
|
+
|
|
95
|
+
```vue
|
|
96
|
+
<p v-if="error?.requestId">Reference: {{ error.requestId }}</p>
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
To find the call, search for the ID in the logs of your Convex dashboard or in your log stream. On a local backend, `npx convex logs --jsonl` shows the `requestId` of each call; the log lines that `convex dev` prints do not. An unexpected failure (kind `unknown`) keeps its request ID, but not its text.
|
|
100
|
+
|
|
101
|
+
Better Convex reads the ID from the error text of Convex, which is not a stable Convex contract. When Convex changes that text, `requestId` is `undefined`.
|
|
102
|
+
|
|
64
103
|
## Library error codes
|
|
65
104
|
|
|
66
105
|
The codes that Better Convex raises itself include `IDENTITY_CHANGED`, `CANCELLED`, `FILE_TOO_LARGE`, `FILE_TYPE_NOT_ALLOWED`, `UPLOAD_IN_PROGRESS`, `SUBMIT_IN_PROGRESS`, `UNAUTHENTICATED`, `CLIENT_UNAVAILABLE`, `NETWORK_ERROR`, and `TIMEOUT`. The type `ConvexCallErrorCode` lists every code. Ignore `CANCELLED` when your own `cancel()` or `reset()` caused it. Do not retry `IDENTITY_CHANGED` automatically. See [error types](../../reference/error-types.md#convexcallerrorcode).
|
|
@@ -88,7 +127,7 @@ Vue/Nuxt error boundaries are appropriate for render failures or page-level inab
|
|
|
88
127
|
|
|
89
128
|
## Logging
|
|
90
129
|
|
|
91
|
-
Log the category, `functionName`, and safe correlation context. Do not log tokens, cookies, auth headers,
|
|
130
|
+
Log the category, `functionName`, `requestId`, and safe correlation context. Do not log tokens, cookies, auth headers,
|
|
92
131
|
raw upload bytes, or upstream error objects. `ConvexCallError` does not retain the raw upstream cause.
|
|
93
132
|
|
|
94
133
|
## Retry safety
|
|
@@ -131,3 +131,76 @@ Each step reads at most 100 rows or 4 MiB, deletes or patches them, and schedule
|
|
|
131
131
|
Erasure removes rows that your own tables hold. It does not reach files in storage, backups, logs, or other services. Remove those in `beforeDelete`, or in your own scheduled function.
|
|
132
132
|
|
|
133
133
|
Test it once with real data: create a person with rows in each mapped table, delete the account, run the scheduled steps, and check what is left. The starter's `convex/account.test.ts` shows how.
|
|
134
|
+
|
|
135
|
+
## Delete another user from a Convex function
|
|
136
|
+
|
|
137
|
+
An admin removes a member, or you act on an erasure request that reached you by
|
|
138
|
+
email. Call `auth.deleteUser(ctx, userId)` from an internal mutation, after your
|
|
139
|
+
own check of who may delete whom.
|
|
140
|
+
|
|
141
|
+
```ts [convex/members.ts]
|
|
142
|
+
import { ConvexError, v } from 'convex/values'
|
|
143
|
+
|
|
144
|
+
import { internal } from './_generated/api'
|
|
145
|
+
import { internalMutation, mutation } from './_generated/server'
|
|
146
|
+
import { auth } from './auth'
|
|
147
|
+
|
|
148
|
+
export const remove = mutation({
|
|
149
|
+
args: { authUserId: v.string() },
|
|
150
|
+
handler: async (ctx, args): Promise<null> => {
|
|
151
|
+
const caller = await auth.requireUser(ctx)
|
|
152
|
+
const me = await ctx.db
|
|
153
|
+
.query('users')
|
|
154
|
+
.withIndex('by_auth_id', (q) => q.eq('authId', caller.id))
|
|
155
|
+
.unique()
|
|
156
|
+
if (me?.role !== 'admin') throw new ConvexError({ code: 'FORBIDDEN' })
|
|
157
|
+
await ctx.runMutation(internal.members.deleteAuthUser, { authUserId: args.authUserId })
|
|
158
|
+
return null
|
|
159
|
+
},
|
|
160
|
+
})
|
|
161
|
+
|
|
162
|
+
export const deleteAuthUser = internalMutation({
|
|
163
|
+
args: { authUserId: v.string() },
|
|
164
|
+
handler: async (ctx, args): Promise<null> => {
|
|
165
|
+
await auth.deleteUser(ctx, args.authUserId)
|
|
166
|
+
return null
|
|
167
|
+
},
|
|
168
|
+
})
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The `users` table has a `role` field and the index `by_auth_id` on `authId`.
|
|
172
|
+
|
|
173
|
+
`auth.deleteUser` checks no permission. It deletes whichever user ID it gets, so
|
|
174
|
+
never pass an ID from the browser to it without a check like the one in `remove`.
|
|
175
|
+
|
|
176
|
+
It is the same deletion that `authClient.deleteUser()` does. The user's
|
|
177
|
+
sessions stop working at once. Better Auth then deletes the sessions, the
|
|
178
|
+
linked accounts and the auth user. Your `onDelete` triggers run for each of
|
|
179
|
+
these rows, so the user projection deletes the app user row and runs your
|
|
180
|
+
`erase` hook. The session limit above applies here too: sessions after the
|
|
181
|
+
first 64 are deleted later, without `onDelete` triggers. A user ID that does not
|
|
182
|
+
exist is not an error.
|
|
183
|
+
|
|
184
|
+
These steps belong to the person's own delete request and do not run here:
|
|
185
|
+
|
|
186
|
+
- `deleteUser.beforeDelete`. Do the same checks before you call
|
|
187
|
+
`deleteAuthUser`.
|
|
188
|
+
- The fresh session or password check, and the `delete-account` email.
|
|
189
|
+
- The `deleteUser.enabled` switch. `auth.deleteUser` works without it.
|
|
190
|
+
|
|
191
|
+
In a mutation, the deletion is one transaction. From an action it also works,
|
|
192
|
+
but each step is its own transaction; if one fails, call `auth.deleteUser`
|
|
193
|
+
again to finish. A query cannot delete: the call throws
|
|
194
|
+
`AUTH_DELETE_USER_REQUIRES_WRITABLE_CONTEXT`.
|
|
195
|
+
|
|
196
|
+
Cost: it reads the user, its sessions and its accounts in the auth component,
|
|
197
|
+
updates the user once so that every session stops working, and deletes the
|
|
198
|
+
accounts, up to 64 sessions and the user. Each deleted row runs your `onDelete`
|
|
199
|
+
trigger in the same transaction. Queries that read these auth rows for the user,
|
|
200
|
+
such as `getUser` in that person's open tabs, and queries that read the rows
|
|
201
|
+
your triggers change, update.
|
|
202
|
+
|
|
203
|
+
Do not call the component mutation `components.betterAuth.adapter.deleteOne`
|
|
204
|
+
for the user. It deletes the sessions and accounts too, but it does not run your
|
|
205
|
+
`onDelete` triggers. The app user row and the data that `erase` removes stay
|
|
206
|
+
behind.
|
|
@@ -23,7 +23,7 @@ const { status, pending, user, error, client, ready } = useConvexAuth()
|
|
|
23
23
|
|
|
24
24
|
`status` tells you whether a user is signed in, as Convex accepted it. `pending` is `true` while `status` is `'pending'`, which happens only before the first result. A sign-in or user switch keeps the previous `status` until Convex accepts the new session.
|
|
25
25
|
|
|
26
|
-
Use these refs for the signed-in user. They live as long as the app. With Better Auth 1.7.
|
|
26
|
+
Use these refs for the signed-in user. They live as long as the app. With Better Auth 1.7.12, do not mount `client.useSession()` in route components; remounting it can leave session state stale. `client` is the one integrated Better Auth client for sign-in, sign-out, and inferred plugin methods. It is never `null`, so you can destructure and read it anywhere. The real client exists only in the browser after the Convex runtime starts. During server rendering and before that point, calling one of its methods throws a `ConvexCallError` with code `CLIENT_UNAVAILABLE`. Call it from browser event handlers or `onMounted()`.
|
|
27
27
|
|
|
28
28
|
```vue
|
|
29
29
|
<template>
|
|
@@ -38,7 +38,9 @@ session.
|
|
|
38
38
|
## Authenticate an HTTP action
|
|
39
39
|
|
|
40
40
|
An HTTP action receives the browser's session cookie, not a Convex token. Wrap
|
|
41
|
-
it in `auth.sessionHttpAction` instead of reading the cookie yourself
|
|
41
|
+
it in `auth.sessionHttpAction` instead of reading the cookie yourself. To send
|
|
42
|
+
files, use a [private download route](../files/private-downloads.md)
|
|
43
|
+
instead:
|
|
42
44
|
|
|
43
45
|
```ts [convex/http.ts]
|
|
44
46
|
http.route({
|
|
@@ -59,6 +61,9 @@ gets `401` `UNAUTHENTICATED` or `403` `FORBIDDEN` and never reaches the
|
|
|
59
61
|
handler. Mount the route under `/api/auth/` so browser calls pass through the
|
|
60
62
|
auth proxy.
|
|
61
63
|
|
|
64
|
+
The auth proxy reads the whole response into memory and refuses a response
|
|
65
|
+
larger than 1 MiB. Do not send files through `sessionHttpAction`.
|
|
66
|
+
|
|
62
67
|
## Check the resource
|
|
63
68
|
|
|
64
69
|
```ts [convex/projects.ts]
|
|
@@ -32,7 +32,7 @@ See [Guest users](../../recipes/guest-users.md) for sign-in, linking, and cleanu
|
|
|
32
32
|
The organization and two-factor plugins add tables to the Better Auth
|
|
33
33
|
component. They need a local copy of the component inside your `convex/`
|
|
34
34
|
folder. The email OTP plugin adds no tables and works with the packaged
|
|
35
|
-
component. `pnpm exec better-convex init` creates the local component:
|
|
35
|
+
component. `pnpm exec better-convex-nuxt auth init` creates the local component:
|
|
36
36
|
|
|
37
37
|
| File | Purpose |
|
|
38
38
|
| --- | --- |
|
|
@@ -80,7 +80,7 @@ export function createAuthSchemaPlugins(authIssuer: string) {
|
|
|
80
80
|
|
|
81
81
|
The default of `requireEmailVerificationOnInvitation` is `true`. Setting it to `false` lets a person accept an invitation without proving the address; see [Organization permissions](../../recipes/organization-permissions.md).
|
|
82
82
|
|
|
83
|
-
Keep the `jwt` entry exactly as `better-convex init` wrote it. The library
|
|
83
|
+
Keep the `jwt` entry exactly as `better-convex-nuxt auth init` wrote it. The library
|
|
84
84
|
uses the same JWT settings at runtime.
|
|
85
85
|
|
|
86
86
|
## 2. Turn the plugin on in the server
|
|
@@ -108,7 +108,7 @@ whose `auth.api` has the organization endpoints, for example
|
|
|
108
108
|
Run the generator after every change to `schemaPlugins.ts`:
|
|
109
109
|
|
|
110
110
|
```bash
|
|
111
|
-
pnpm exec better-convex auth schema \
|
|
111
|
+
pnpm exec better-convex-nuxt auth schema \
|
|
112
112
|
--config convex/betterAuth/schemaOptions.ts \
|
|
113
113
|
--output convex/betterAuth
|
|
114
114
|
```
|
|
@@ -87,7 +87,9 @@ address. See
|
|
|
87
87
|
[Transactional auth email](./transactional-email.md#add-the-email-hook)
|
|
88
88
|
for a complete one. `internal.members.findInvite` is your own internal query. The callback
|
|
89
89
|
receives a read-only copy of the new user: `email`, `emailVerified`, `name`,
|
|
90
|
-
and `
|
|
90
|
+
`image`, and `isAnonymous`. `isAnonymous` is `true` for a guest from
|
|
91
|
+
[`experimental.anonymous`](../../recipes/guest-users.md) and `false` for every
|
|
92
|
+
other new user. It has no `id` yet, because Better Auth assigns it after the
|
|
91
93
|
callback. If you return an `id`, it must be a value that no Better Auth user
|
|
92
94
|
has; do not use it to attach a sign-up to an existing user.
|
|
93
95
|
|
|
@@ -196,7 +198,7 @@ Convex sets the built-in value itself:
|
|
|
196
198
|
| `BETTER_AUTH_SECRETS` | You | Versioned Better Auth secrets, newest version first |
|
|
197
199
|
| `BCN_AUTH_PROXY_IP_SECRET` | You | Private Nuxt-to-Convex client-IP signing secret |
|
|
198
200
|
|
|
199
|
-
In development, `better-convex init` sets `SITE_URL`, `BETTER_AUTH_SECRETS`,
|
|
201
|
+
In development, `better-convex-nuxt auth init` sets `SITE_URL`, `BETTER_AUTH_SECRETS`,
|
|
200
202
|
and `BCN_AUTH_PROXY_IP_SECRET` for you. It also writes the proxy secret to
|
|
201
203
|
`.env.local`, so Nuxt uses the same value.
|
|
202
204
|
|
|
@@ -139,9 +139,9 @@ Add the scope as **Default**, or as **Optional** and name it in `oidc.scopes`.
|
|
|
139
139
|
Store the IdP values in the Convex environment. Set them for each deployment:
|
|
140
140
|
|
|
141
141
|
```bash
|
|
142
|
-
pnpm exec better-convex convex env set OIDC_ISSUER https://sso.example.com/realms/acme
|
|
143
|
-
pnpm exec better-convex convex env set OIDC_CLIENT_ID acme-app
|
|
144
|
-
printf '%s' "$OIDC_CLIENT_SECRET" | pnpm exec better-convex convex env set OIDC_CLIENT_SECRET
|
|
142
|
+
pnpm exec better-convex-nuxt convex env set OIDC_ISSUER https://sso.example.com/realms/acme
|
|
143
|
+
pnpm exec better-convex-nuxt convex env set OIDC_CLIENT_ID acme-app
|
|
144
|
+
printf '%s' "$OIDC_CLIENT_SECRET" | pnpm exec better-convex-nuxt convex env set OIDC_CLIENT_SECRET
|
|
145
145
|
```
|
|
146
146
|
|
|
147
147
|
Do not print or commit the client secret.
|
|
@@ -665,7 +665,7 @@ Choose one of two setups.
|
|
|
665
665
|
|
|
666
666
|
**Local Convex deployment and local Keycloak.**
|
|
667
667
|
|
|
668
|
-
1. Create a local deployment with `pnpm exec better-convex convex dev --anonymous`.
|
|
668
|
+
1. Create a local deployment with `pnpm exec better-convex-nuxt convex dev --anonymous`.
|
|
669
669
|
2. Copy the Keycloak compose file from
|
|
670
670
|
[`test/fixtures/keycloak`](https://github.com/lupinum-dev/better-convex/tree/main/test/fixtures/keycloak)
|
|
671
671
|
in the repository. Set `KC_HOSTNAME=http://localhost:18080`.
|
|
@@ -39,7 +39,7 @@ Install Better Auth and the OAuth provider at the exact versions that the
|
|
|
39
39
|
module declares as peers:
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
pnpm add better-auth@1.7.
|
|
42
|
+
pnpm add better-auth@1.7.16 @better-auth/core@1.7.16 @better-auth/oauth-provider@1.7.16
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
Do not install another OAuth provider version or patch it in your
|
|
@@ -53,7 +53,7 @@ Mount exactly one component named `betterAuth`. It stores users, accounts, sessi
|
|
|
53
53
|
|
|
54
54
|
Your organizations, memberships, approvals, and resources stay in your own Convex tables. A user projection copied from Better Auth is display data. It does not store credentials or sessions.
|
|
55
55
|
|
|
56
|
-
`better-convex init` writes a [local auth component](./better-auth-plugins.md). Its schema has no OAuth tables until you add `oauthProvider()` to `convex/betterAuth/schemaPlugins.ts` and regenerate the schema. Step 1 of [Add MCP to your application](../agents/mcp-application.md) shows how. Generate the complete schema before the first write and mount it as `betterAuth`. Do not mount the packaged and the local component together.
|
|
56
|
+
`better-convex-nuxt auth init` writes a [local auth component](./better-auth-plugins.md). Its schema has no OAuth tables until you add `oauthProvider()` to `convex/betterAuth/schemaPlugins.ts` and regenerate the schema. Step 1 of [Add MCP to your application](../agents/mcp-application.md) shows how. Generate the complete schema before the first write and mount it as `betterAuth`. Do not mount the packaged and the local component together.
|
|
57
57
|
|
|
58
58
|
## Public URLs
|
|
59
59
|
|
|
@@ -183,7 +183,7 @@ only for a signed-in OAuth administrator. A missing session or user, `false`,
|
|
|
183
183
|
`undefined`, a thrown error, or a timeout denies the request. The factory fails
|
|
184
184
|
at startup when either profile does not keep the rules above.
|
|
185
185
|
|
|
186
|
-
Better Auth 1.7.
|
|
186
|
+
Better Auth 1.7.12 encrypts provider access and refresh tokens, but not every
|
|
187
187
|
provider ID token. The library encrypts ID tokens before it writes them to the
|
|
188
188
|
component and decrypts them only inside Better Auth. Your application code and
|
|
189
189
|
the browser cannot read provider tokens.
|
|
@@ -412,7 +412,7 @@ After you deploy the schema, functions, environment variables, and HTTP routes,
|
|
|
412
412
|
run:
|
|
413
413
|
|
|
414
414
|
```bash
|
|
415
|
-
pnpm exec better-convex convex run auth:ensureSigningKey '{}'
|
|
415
|
+
pnpm exec better-convex-nuxt convex run auth:ensureSigningKey '{}'
|
|
416
416
|
```
|
|
417
417
|
|
|
418
418
|
The action returns `{ created, kid }`. Running it again returns the existing
|
|
@@ -102,6 +102,9 @@ A code proves the address, so a person who signs in this way replaces any
|
|
|
102
102
|
password or session an earlier sign-up left on that address. Codes are stored
|
|
103
103
|
hashed.
|
|
104
104
|
|
|
105
|
+
To let people sign in with one tap from the email, put the code in a link. See
|
|
106
|
+
[Sign-in link](../../recipes/sign-in-link.md).
|
|
107
|
+
|
|
105
108
|
## Sign-out
|
|
106
109
|
|
|
107
110
|
```ts
|
|
@@ -44,10 +44,10 @@ environment, not in Nuxt. Set them for the deployment that `.env.local`
|
|
|
44
44
|
selects:
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
pnpm exec better-convex convex env set GITHUB_CLIENT_ID your-github-client-id
|
|
48
|
-
printf '%s' "$GITHUB_CLIENT_SECRET" | pnpm exec better-convex convex env set GITHUB_CLIENT_SECRET
|
|
49
|
-
pnpm exec better-convex convex env set GOOGLE_CLIENT_ID your-google-client-id
|
|
50
|
-
printf '%s' "$GOOGLE_CLIENT_SECRET" | pnpm exec better-convex convex env set GOOGLE_CLIENT_SECRET
|
|
47
|
+
pnpm exec better-convex-nuxt convex env set GITHUB_CLIENT_ID your-github-client-id
|
|
48
|
+
printf '%s' "$GITHUB_CLIENT_SECRET" | pnpm exec better-convex-nuxt convex env set GITHUB_CLIENT_SECRET
|
|
49
|
+
pnpm exec better-convex-nuxt convex env set GOOGLE_CLIENT_ID your-google-client-id
|
|
50
|
+
printf '%s' "$GOOGLE_CLIENT_SECRET" | pnpm exec better-convex-nuxt convex env set GOOGLE_CLIENT_SECRET
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
Do not print or commit the secrets.
|
|
@@ -90,18 +90,32 @@ Write the `verify-email` message so it says: "If you did not create an account,
|
|
|
90
90
|
ignore this email." See
|
|
91
91
|
[Password sign-in and access by email](./sign-in-and-sign-out.md#password-sign-in-and-access-by-email).
|
|
92
92
|
|
|
93
|
-
###
|
|
93
|
+
### Local development and the dev outbox
|
|
94
94
|
|
|
95
|
-
|
|
95
|
+
On a loopback `SITE_URL` (`http://localhost:3000`, `http://127.0.0.1:3000`)
|
|
96
|
+
without `siteOrigins`, the dev outbox writes each code and link to the Convex
|
|
97
|
+
function log, as
|
|
98
|
+
`[better-convex-nuxt dev outbox] email-otp to you@example.com: code 123456`.
|
|
99
|
+
Read it with `pnpm exec better-convex-nuxt convex logs`. `NODE_ENV` plays no part.
|
|
96
100
|
|
|
97
|
-
- **
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
101
|
+
- **Without the `email` option**, the log is the only delivery, so a new
|
|
102
|
+
project can sign in before it has a mail provider.
|
|
103
|
+
- **With the `email` option**, the library writes the log line first and then
|
|
104
|
+
calls your hook. You can test your templates and queue locally and still read
|
|
105
|
+
the code when the hook has no provider key.
|
|
106
|
+
|
|
107
|
+
On any other `SITE_URL`, the dev outbox never writes to the log, with or
|
|
108
|
+
without the hook. A cloud development deployment whose `SITE_URL` is
|
|
109
|
+
`http://localhost:3000` counts as local: everyone who can read its logs can
|
|
110
|
+
read the codes.
|
|
111
|
+
|
|
112
|
+
### No `email` option on a deployment
|
|
113
|
+
|
|
114
|
+
On a `SITE_URL` that is not loopback, `createBetterConvexAuth` throws when the
|
|
115
|
+
deployment must send mail (`emailOTP`, password verification or reset,
|
|
116
|
+
organization invitations) and has no `email` option. The deploy fails and the
|
|
117
|
+
previous version keeps running. Add the `email` option, or leave those features
|
|
118
|
+
out.
|
|
105
119
|
|
|
106
120
|
## Submit durable work
|
|
107
121
|
|
|
@@ -124,6 +138,27 @@ promise. Auth token creation and a later submission can be separate
|
|
|
124
138
|
transactions; test submission failure and safe user retries in the
|
|
125
139
|
application. Never include the credential-bearing message in an error.
|
|
126
140
|
|
|
141
|
+
### Codes and links wait in your queue
|
|
142
|
+
|
|
143
|
+
Until your queue sends the email, the code or link is stored in plain text.
|
|
144
|
+
Store it in a row of your own table, schedule the sending action with only the
|
|
145
|
+
row ID, and delete the row after the email is sent. Do not pass the code in the
|
|
146
|
+
arguments of a scheduled function: they stay in the `_scheduled_functions`
|
|
147
|
+
system table after the function runs, and people with access to the Convex
|
|
148
|
+
dashboard can read them.
|
|
149
|
+
|
|
150
|
+
These rules limit what a stored code can do:
|
|
151
|
+
|
|
152
|
+
- Better Auth stores the code hashed in the auth tables. This is the library
|
|
153
|
+
default (`storeOTP: 'hashed'`); another `emailOTP.storeOTP` value changes it.
|
|
154
|
+
With the default, only your queue holds the plain code.
|
|
155
|
+
- The code expires after `emailOTP.expiresIn` seconds, 300 by default. After
|
|
156
|
+
that, a stored code is worthless. Keep this value short.
|
|
157
|
+
- The code stops working after `emailOTP.allowedAttempts` wrong codes, 3 by
|
|
158
|
+
default.
|
|
159
|
+
|
|
160
|
+
A reset or verification link gives access in the same way until it expires.
|
|
161
|
+
|
|
127
162
|
## Configure the capabilities
|
|
128
163
|
|
|
129
164
|
The library sets the email callbacks of Better Auth. These options are
|