@lupinum/better-convex-agents 0.1.0-rc.4 → 0.1.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 +4 -3
- 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/agents/tools-and-approvals.md +3 -1
- package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +1 -1
- package/dist/agent/pages/docs/build/authentication/better-auth-plugin-support.md +8 -5
- package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +3 -3
- package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +3 -3
- package/dist/agent/pages/docs/build/authentication/company-sign-in.md +710 -0
- package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +51 -16
- package/dist/agent/pages/docs/build/authentication/overview.md +1 -0
- package/dist/agent/pages/docs/build/authentication/route-protection.md +13 -3
- package/dist/agent/pages/docs/build/authentication/social-sign-in.md +8 -4
- package/dist/agent/pages/docs/build/authentication/transactional-email.md +2 -2
- package/dist/agent/pages/docs/build/functions/internal-operations.md +57 -8
- package/dist/agent/pages/docs/build/functions/limits-and-audit.md +31 -7
- package/dist/agent/pages/docs/build/functions/policy-and-roles.md +7 -2
- package/dist/agent/pages/docs/build/functions/row-rules.md +13 -4
- package/dist/agent/pages/docs/build/functions/start-here.md +8 -5
- package/dist/agent/pages/docs/build/functions/testing.md +8 -5
- package/dist/agent/pages/docs/build/functions/threat-model.md +9 -1
- package/dist/agent/pages/docs/build/queries/loading-and-stale-data.md +33 -11
- package/dist/agent/pages/docs/build/queries/pagination.md +1 -1
- package/dist/agent/pages/docs/build/queries/queries.md +16 -4
- package/dist/agent/pages/docs/build/write-data/forms.md +79 -0
- package/dist/agent/pages/docs/concepts/glossary.md +1 -1
- package/dist/agent/pages/docs/concepts/ssr-hydration-realtime.md +22 -4
- package/dist/agent/pages/docs/get-started/add-authentication.md +205 -160
- package/dist/agent/pages/docs/get-started/choose-your-path.md +5 -5
- package/dist/agent/pages/docs/get-started/complete-and-delete.md +137 -0
- package/dist/agent/pages/docs/get-started/first-realtime-page.md +66 -35
- package/dist/agent/pages/docs/get-started/installation.md +105 -72
- package/dist/agent/pages/docs/get-started/next-steps.md +2 -0
- package/dist/agent/pages/docs/get-started/plain-vue.md +3 -4
- 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 +6 -5
- 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/release-compatibility.md +8 -8
- package/dist/agent/pages/docs/operations/security-model.md +21 -2
- package/dist/agent/pages/docs/operations/troubleshooting.md +5 -0
- package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +21 -15
- package/dist/agent/pages/docs/overview/comparison.md +2 -2
- package/dist/agent/pages/docs/overview/limitations.md +25 -2
- package/dist/agent/pages/docs/overview/who-it-is-for.md +5 -5
- package/dist/agent/pages/docs/recipes/guest-users.md +2 -2
- package/dist/agent/pages/docs/recipes/organization-permissions.md +1 -1
- package/dist/agent/pages/docs/reference/cli.md +46 -17
- package/dist/agent/pages/docs/reference/composables.md +4 -4
- package/dist/agent/pages/docs/reference/error-types.md +3 -1
- package/dist/agent/pages/docs/reference/package-exports.md +1 -1
- package/dist/agent/pages/docs.md +1 -1
- package/dist/index.mjs +1 -1
- package/dist/internal.mjs +1 -1
- package/dist/mcp.mjs +1 -1
- package/dist/shared/{better-convex-agents.DOwA1EO9.mjs → better-convex-agents.DWStY2mj.mjs} +7 -5
- 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.0
|
|
1
|
+
# @lupinum/better-convex-agents 0.1.0 documentation
|
|
2
2
|
|
|
3
|
-
These pages describe the installed version 0.1.0
|
|
3
|
+
These pages describe the installed version 0.1.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)
|
|
@@ -72,6 +72,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
|
|
|
72
72
|
- [Cacheable public pages](./pages/docs/build/authentication/cacheable-public-pages.md)
|
|
73
73
|
- [Several sites on one deployment](./pages/docs/build/authentication/multiple-site-origins.md)
|
|
74
74
|
- [Account deletion](./pages/docs/build/authentication/account-deletion.md)
|
|
75
|
+
- [Company sign-in (OIDC)](./pages/docs/build/authentication/company-sign-in.md)
|
|
75
76
|
- [serverConvex](./pages/docs/build/server/server-convex.md)
|
|
76
77
|
- [Server routes](./pages/docs/build/server/server-routes.md)
|
|
77
78
|
- [Webhooks and jobs](./pages/docs/build/server/webhooks-and-jobs.md)
|
|
@@ -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
|
|
@@ -83,7 +83,9 @@ export const { activity } = tools
|
|
|
83
83
|
|
|
84
84
|
`functions` must be `internal.<this module>`. When `createMcpServer` loads, a
|
|
85
85
|
tool that is not exported fails, with the missing names in the message. An
|
|
86
|
-
operation in a module that you do not pass to `defineTools` has no tool.
|
|
86
|
+
operation in a module that you do not pass to `defineTools` has no tool. The
|
|
87
|
+
[launch check](../functions/testing.md#launch-check) names each such
|
|
88
|
+
operation that has a `tool` field.
|
|
87
89
|
|
|
88
90
|
Every tool's action must be in at least one scope of the policy; `defineTools` throws for a tool whose action is in none.
|
|
89
91
|
|
|
@@ -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>
|
|
@@ -23,18 +23,21 @@ The browser client accepts only the matching client plugins in
|
|
|
23
23
|
| Plugin | Server option | Client plugin | Status | Notes |
|
|
24
24
|
| --- | --- | --- | --- | --- |
|
|
25
25
|
| Organization | `organization` | `organizationClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. Teams work with `teams: { enabled: true }`. Invitation email goes through the `email` hook. Accepting an invitation needs a verified email by default. |
|
|
26
|
-
| Two-factor | `twoFactor` | `twoFactorClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. One-time codes go through the `email` hook. Rejected together with `emailOTP` or `
|
|
26
|
+
| Two-factor | `twoFactor` | `twoFactorClient()` from `better-auth/client/plugins` | Supported | Needs a local auth component. One-time codes go through the `email` hook. Turning it on ends the person's other sessions. Rejected together with `emailOTP`, `socialProviders`, or `oidc`, because those sign-ins skip the second factor. |
|
|
27
27
|
| Email OTP | `emailOTP` | `emailOTPClient()` from `better-auth/client/plugins` | Supported | Needs the `email` hook (a loopback `SITE_URL` logs codes instead). Codes are stored hashed. `changeEmail` and unknown keys are rejected. Adds no tables. |
|
|
28
28
|
| OAuth provider | `oauth.mcp` | `oauthProviderClient()` from `@better-auth/oauth-provider/client` | Supported for MCP | Only the MCP profile. A local auth component also needs it in the schema plugins. Dynamic client registration, UserInfo, and OpenID Connect discovery are off. See [Delegated OAuth and MCP](./delegated-oauth-and-mcp.md). |
|
|
29
29
|
| JWT | None | None | Built in | The library always installs it. It stores the keys that sign Convex session tokens and OAuth access tokens. You cannot configure it. |
|
|
30
30
|
| Anonymous | `experimental.anonymous` | `anonymousClient()` from `better-auth/client/plugins` | Experimental | Needs a local auth component. Cannot be combined with `twoFactor`. See [Guest users](../../recipes/guest-users.md). |
|
|
31
31
|
| Any other plugin, for example admin, API key, passkey, magic link, username, OAuth popup, or phone number | Rejected | Rejected | Not supported | The factory rejects `plugins`, and the client rejects unknown plugin IDs. |
|
|
32
32
|
|
|
33
|
-
Email and password sign-in, email verification,
|
|
34
|
-
|
|
35
|
-
`emailVerification`, and `
|
|
36
|
-
[Social sign-in](./social-sign-in.md)
|
|
33
|
+
Email and password sign-in, email verification, social providers, and company
|
|
34
|
+
sign-in are core options, not plugins. Configure them with `emailAndPassword`,
|
|
35
|
+
`emailVerification`, `socialProviders`, and `oidc`. See
|
|
36
|
+
[Social sign-in](./social-sign-in.md),
|
|
37
|
+
[Company sign-in](./company-sign-in.md), and
|
|
37
38
|
[Transactional auth email](./transactional-email.md).
|
|
39
|
+
The Better Auth `genericOAuth` plugin stays rejected; use `oidc` for an OpenID
|
|
40
|
+
Connect identity provider.
|
|
38
41
|
|
|
39
42
|
## Options the library sets for you
|
|
40
43
|
|
|
@@ -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
|
```
|
|
@@ -150,8 +150,8 @@ setup.
|
|
|
150
150
|
`createBetterConvexAuth` rejects an unknown option key when the module loads.
|
|
151
151
|
This includes unknown keys in `session`, `account`, `account.accountLinking`,
|
|
152
152
|
and `emailOTP` (`emailOTP.changeEmail` is rejected). It also rejects
|
|
153
|
-
`twoFactor` together with `emailOTP` or `
|
|
154
|
-
sign-ins skip the second factor. A deployment that must send mail (email codes,
|
|
153
|
+
`twoFactor` together with `emailOTP`, `socialProviders`, or `oidc`, because
|
|
154
|
+
those sign-ins skip the second factor. A deployment that must send mail (email codes,
|
|
155
155
|
password verification or reset, organization invitations) and has no `email`
|
|
156
156
|
option fails here too, unless `SITE_URL` is a loopback origin; see
|
|
157
157
|
[Transactional email](./transactional-email.md). The factory sets `plugins`, `database`,
|
|
@@ -196,7 +196,7 @@ Convex sets the built-in value itself:
|
|
|
196
196
|
| `BETTER_AUTH_SECRETS` | You | Versioned Better Auth secrets, newest version first |
|
|
197
197
|
| `BCN_AUTH_PROXY_IP_SECRET` | You | Private Nuxt-to-Convex client-IP signing secret |
|
|
198
198
|
|
|
199
|
-
In development, `better-convex init` sets `SITE_URL`, `BETTER_AUTH_SECRETS`,
|
|
199
|
+
In development, `better-convex-nuxt auth init` sets `SITE_URL`, `BETTER_AUTH_SECRETS`,
|
|
200
200
|
and `BCN_AUTH_PROXY_IP_SECRET` for you. It also writes the proxy secret to
|
|
201
201
|
`.env.local`, so Nuxt uses the same value.
|
|
202
202
|
|