@lupinum/better-convex-functions 0.1.0-rc.5 → 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.
Files changed (49) hide show
  1. package/README.md +1 -1
  2. package/dist/agent/AGENTS.md +3 -3
  3. package/dist/agent/pages/docs/build/agents/connect-chatgpt-and-claude.md +2 -2
  4. package/dist/agent/pages/docs/build/agents/mcp-application.md +5 -5
  5. package/dist/agent/pages/docs/build/agents/mcp-apps.md +1 -1
  6. package/dist/agent/pages/docs/build/agents/mcp.md +5 -6
  7. package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +1 -1
  8. package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +3 -3
  9. package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +1 -1
  10. package/dist/agent/pages/docs/build/authentication/company-sign-in.md +4 -4
  11. package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +4 -4
  12. package/dist/agent/pages/docs/build/authentication/social-sign-in.md +4 -4
  13. package/dist/agent/pages/docs/build/authentication/transactional-email.md +2 -2
  14. package/dist/agent/pages/docs/build/functions/start-here.md +1 -1
  15. package/dist/agent/pages/docs/build/functions/testing.md +1 -1
  16. package/dist/agent/pages/docs/get-started/add-authentication.md +205 -160
  17. package/dist/agent/pages/docs/get-started/choose-your-path.md +5 -5
  18. package/dist/agent/pages/docs/get-started/complete-and-delete.md +137 -0
  19. package/dist/agent/pages/docs/get-started/first-realtime-page.md +66 -35
  20. package/dist/agent/pages/docs/get-started/installation.md +105 -72
  21. package/dist/agent/pages/docs/get-started/next-steps.md +2 -0
  22. package/dist/agent/pages/docs/get-started/plain-vue.md +3 -4
  23. package/dist/agent/pages/docs/get-started/project-structure.md +9 -18
  24. package/dist/agent/pages/docs/get-started/protect-data.md +85 -36
  25. package/dist/agent/pages/docs/operations/deploy-to-vercel.md +7 -7
  26. package/dist/agent/pages/docs/operations/deployment.md +2 -2
  27. package/dist/agent/pages/docs/operations/environment-variables.md +5 -5
  28. package/dist/agent/pages/docs/operations/release-compatibility.md +7 -7
  29. package/dist/agent/pages/docs/operations/troubleshooting.md +5 -0
  30. package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +16 -11
  31. package/dist/agent/pages/docs/overview/comparison.md +2 -2
  32. package/dist/agent/pages/docs/overview/limitations.md +2 -2
  33. package/dist/agent/pages/docs/overview/who-it-is-for.md +5 -5
  34. package/dist/agent/pages/docs/recipes/guest-users.md +2 -2
  35. package/dist/agent/pages/docs/recipes/organization-permissions.md +1 -1
  36. package/dist/agent/pages/docs/reference/cli.md +46 -17
  37. package/dist/agent/pages/docs.md +1 -1
  38. package/dist/index.d.mts +2 -2
  39. package/dist/index.d.ts +2 -2
  40. package/dist/internal.d.mts +3 -3
  41. package/dist/internal.d.ts +3 -3
  42. package/dist/shared/{better-convex-functions.DsGObwSa.d.mts → better-convex-functions.Bdo4Aaov.d.mts} +1 -1
  43. package/dist/shared/{better-convex-functions.Dl1l23LJ.d.mts → better-convex-functions.BkEAj2tq.d.mts} +45 -45
  44. package/dist/shared/{better-convex-functions.Bv4-pb7M.d.ts → better-convex-functions.CMT57Zsz.d.ts} +45 -45
  45. package/dist/shared/{better-convex-functions.4SU2rwG2.d.ts → better-convex-functions.bhHIvhtY.d.ts} +1 -1
  46. package/dist/test.d.mts +1 -1
  47. package/dist/test.d.ts +1 -1
  48. package/package.json +2 -2
  49. package/dist/agent/pages/docs/get-started/add-a-mutation.md +0 -124
package/README.md CHANGED
@@ -39,7 +39,7 @@ The package imports only `convex`. It works with any frontend.
39
39
  ## Installation
40
40
 
41
41
  ```bash
42
- pnpm add @lupinum/better-convex-functions@next
42
+ pnpm add @lupinum/better-convex-functions
43
43
  ```
44
44
 
45
45
  ## Quick start
@@ -1,6 +1,6 @@
1
- # @lupinum/better-convex-functions 0.1.0-rc.5 documentation
1
+ # @lupinum/better-convex-functions 0.1.0 documentation
2
2
 
3
- These pages describe the installed version 0.1.0-rc.5. Prefer them over the
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
@@ -40,7 +40,7 @@ website and over knowledge of earlier versions: the API changed during the 1.0 b
40
40
  - [Choose your path](./pages/docs/get-started/choose-your-path.md)
41
41
  - [Installation](./pages/docs/get-started/installation.md)
42
42
  - [First real-time page](./pages/docs/get-started/first-realtime-page.md)
43
- - [Add a mutation](./pages/docs/get-started/add-a-mutation.md)
43
+ - [Complete and delete](./pages/docs/get-started/complete-and-delete.md)
44
44
  - [Add authentication](./pages/docs/get-started/add-authentication.md)
45
45
  - [Protect data](./pages/docs/get-started/protect-data.md)
46
46
  - [Project structure](./pages/docs/get-started/project-structure.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@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.3.1 zod@4.6.5
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
- This page describes the 1.0 release candidate (the `next` dist-tag). It implements the
29
- final MCP `2026-07-28` contract through exact `@modelcontextprotocol/server@2.3.1`.
30
- The protocol is stable; this integration remains prerelease until the 1.0
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@next @lupinum/better-convex-functions@next @modelcontextprotocol/server@2.3.1 zod@4.6.5
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
@@ -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.7, 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()`.
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>
@@ -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
  ```
@@ -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
 
@@ -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.7 @better-auth/core@1.7.7 @better-auth/oauth-provider@1.7.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.7 encrypts provider access and refresh tokens, but not every
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
@@ -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.
@@ -96,8 +96,8 @@ Without the `email` option, mail depends on `SITE_URL`:
96
96
 
97
97
  - **Loopback `SITE_URL`** (`http://localhost:3000`, `http://127.0.0.1:3000`):
98
98
  the dev outbox writes each code and link to the Convex function log, as
99
- `[better-convex dev outbox] email-otp to you@example.com: code 123456`.
100
- Read it with `pnpm exec better-convex convex logs`. `NODE_ENV` plays no part.
99
+ `[better-convex-nuxt dev outbox] email-otp to you@example.com: code 123456`.
100
+ Read it with `pnpm exec better-convex-nuxt convex logs`. `NODE_ENV` plays no part.
101
101
  - **Any other `SITE_URL`**: `createBetterConvexAuth` throws when the deployment
102
102
  must send mail (`emailOTP`, password verification or reset, organization
103
103
  invitations). The deploy fails and the previous version keeps running. Add the
@@ -45,7 +45,7 @@ an approval page and tests.
45
45
  ## Install
46
46
 
47
47
  ```bash
48
- pnpm add @lupinum/better-convex-functions@next @lupinum/better-convex-agents@next @modelcontextprotocol/server@2.3.1
48
+ pnpm add @lupinum/better-convex-functions @lupinum/better-convex-agents @modelcontextprotocol/server@2.3.1
49
49
  ```
50
50
 
51
51
  The application needs [Better Auth](../authentication/better-auth-setup.md)
@@ -67,7 +67,7 @@ Convex does not deploy files with two dots in the name, such as
67
67
  `test.setup.ts` and `leaks.test.ts`.
68
68
 
69
69
  The tests import `./_generated/api`. After you add a module or an export, run
70
- `pnpm exec better-convex convex codegen`. It needs a deployment; a local one
70
+ `pnpm exec better-convex-nuxt convex codegen`. It needs a deployment; a local one
71
71
  works without an account or network. See
72
72
  [Code generation without a cloud deployment](../../reference/cli.md#convex-code-generation-without-a-cloud-deployment).
73
73