@lupinum/better-convex-functions 0.0.0-stage → 0.1.0-rc.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 (133) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +154 -3
  3. package/dist/agent/AGENTS.md +156 -0
  4. package/dist/agent/pages/docs/build/agents/connect-chatgpt-and-claude.md +175 -0
  5. package/dist/agent/pages/docs/build/agents/limits.md +63 -0
  6. package/dist/agent/pages/docs/build/agents/mcp-application.md +537 -0
  7. package/dist/agent/pages/docs/build/agents/mcp-apps.md +250 -0
  8. package/dist/agent/pages/docs/build/agents/mcp-door.md +168 -0
  9. package/dist/agent/pages/docs/build/agents/mcp.md +547 -0
  10. package/dist/agent/pages/docs/build/agents/tools-and-approvals.md +288 -0
  11. package/dist/agent/pages/docs/build/application-behavior/connection-state.md +89 -0
  12. package/dist/agent/pages/docs/build/application-behavior/devtools.md +51 -0
  13. package/dist/agent/pages/docs/build/application-behavior/error-handling.md +94 -0
  14. package/dist/agent/pages/docs/build/application-behavior/logging.md +69 -0
  15. package/dist/agent/pages/docs/build/application-behavior/on-demand-client.md +83 -0
  16. package/dist/agent/pages/docs/build/application-behavior/performance.md +77 -0
  17. package/dist/agent/pages/docs/build/authentication/account-deletion.md +126 -0
  18. package/dist/agent/pages/docs/build/authentication/auth-state-and-user.md +66 -0
  19. package/dist/agent/pages/docs/build/authentication/backend-authorization.md +115 -0
  20. package/dist/agent/pages/docs/build/authentication/better-auth-plugin-support.md +67 -0
  21. package/dist/agent/pages/docs/build/authentication/better-auth-plugins.md +165 -0
  22. package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +253 -0
  23. package/dist/agent/pages/docs/build/authentication/cacheable-public-pages.md +67 -0
  24. package/dist/agent/pages/docs/build/authentication/custom-user-fields.md +97 -0
  25. package/dist/agent/pages/docs/build/authentication/delegated-oauth-and-mcp.md +465 -0
  26. package/dist/agent/pages/docs/build/authentication/multiple-site-origins.md +62 -0
  27. package/dist/agent/pages/docs/build/authentication/overview.md +64 -0
  28. package/dist/agent/pages/docs/build/authentication/route-protection.md +113 -0
  29. package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +85 -0
  30. package/dist/agent/pages/docs/build/authentication/social-sign-in.md +193 -0
  31. package/dist/agent/pages/docs/build/authentication/transactional-email.md +121 -0
  32. package/dist/agent/pages/docs/build/authentication/user-synchronization.md +149 -0
  33. package/dist/agent/pages/docs/build/files/storage-urls.md +69 -0
  34. package/dist/agent/pages/docs/build/files/upload-files.md +250 -0
  35. package/dist/agent/pages/docs/build/files/validation-and-deletion.md +70 -0
  36. package/dist/agent/pages/docs/build/functions/cost.md +100 -0
  37. package/dist/agent/pages/docs/build/functions/internal-operations.md +227 -0
  38. package/dist/agent/pages/docs/build/functions/limits-and-audit.md +143 -0
  39. package/dist/agent/pages/docs/build/functions/policy-and-roles.md +191 -0
  40. package/dist/agent/pages/docs/build/functions/row-rules.md +253 -0
  41. package/dist/agent/pages/docs/build/functions/start-here.md +316 -0
  42. package/dist/agent/pages/docs/build/functions/testing.md +476 -0
  43. package/dist/agent/pages/docs/build/functions/threat-model.md +106 -0
  44. package/dist/agent/pages/docs/build/queries/loading-and-stale-data.md +69 -0
  45. package/dist/agent/pages/docs/build/queries/pagination.md +203 -0
  46. package/dist/agent/pages/docs/build/queries/queries.md +148 -0
  47. package/dist/agent/pages/docs/build/queries/reactive-arguments.md +95 -0
  48. package/dist/agent/pages/docs/build/queries/ssr-options.md +83 -0
  49. package/dist/agent/pages/docs/build/server/credentials-and-security.md +82 -0
  50. package/dist/agent/pages/docs/build/server/server-convex.md +163 -0
  51. package/dist/agent/pages/docs/build/server/server-routes.md +111 -0
  52. package/dist/agent/pages/docs/build/server/webhooks-and-jobs.md +192 -0
  53. package/dist/agent/pages/docs/build/write-data/actions.md +74 -0
  54. package/dist/agent/pages/docs/build/write-data/concurrent-operations.md +77 -0
  55. package/dist/agent/pages/docs/build/write-data/forms.md +82 -0
  56. package/dist/agent/pages/docs/build/write-data/multi-step-operations.md +108 -0
  57. package/dist/agent/pages/docs/build/write-data/mutations.md +135 -0
  58. package/dist/agent/pages/docs/build/write-data/optimistic-updates.md +133 -0
  59. package/dist/agent/pages/docs/concepts/authentication-and-identity.md +106 -0
  60. package/dist/agent/pages/docs/concepts/design-decisions.md +100 -0
  61. package/dist/agent/pages/docs/concepts/errors-and-failures.md +116 -0
  62. package/dist/agent/pages/docs/concepts/glossary.md +126 -0
  63. package/dist/agent/pages/docs/concepts/mental-model.md +76 -0
  64. package/dist/agent/pages/docs/concepts/query-ownership-and-caching.md +65 -0
  65. package/dist/agent/pages/docs/concepts/request-lifecycle.md +68 -0
  66. package/dist/agent/pages/docs/concepts/server-and-client-boundaries.md +105 -0
  67. package/dist/agent/pages/docs/concepts/ssr-hydration-realtime.md +80 -0
  68. package/dist/agent/pages/docs/get-started/add-a-mutation.md +122 -0
  69. package/dist/agent/pages/docs/get-started/add-authentication.md +264 -0
  70. package/dist/agent/pages/docs/get-started/choose-your-path.md +98 -0
  71. package/dist/agent/pages/docs/get-started/first-realtime-page.md +101 -0
  72. package/dist/agent/pages/docs/get-started/installation.md +151 -0
  73. package/dist/agent/pages/docs/get-started/next-steps.md +77 -0
  74. package/dist/agent/pages/docs/get-started/plain-vue.md +299 -0
  75. package/dist/agent/pages/docs/get-started/project-structure.md +70 -0
  76. package/dist/agent/pages/docs/get-started/protect-data.md +123 -0
  77. package/dist/agent/pages/docs/operations/before-launch.md +69 -0
  78. package/dist/agent/pages/docs/operations/deploy-to-vercel.md +165 -0
  79. package/dist/agent/pages/docs/operations/deployment.md +129 -0
  80. package/dist/agent/pages/docs/operations/environment-variables.md +105 -0
  81. package/dist/agent/pages/docs/operations/release-compatibility.md +87 -0
  82. package/dist/agent/pages/docs/operations/security-model.md +80 -0
  83. package/dist/agent/pages/docs/operations/troubleshooting.md +105 -0
  84. package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +805 -0
  85. package/dist/agent/pages/docs/overview/comparison.md +88 -0
  86. package/dist/agent/pages/docs/overview/introduction.md +79 -0
  87. package/dist/agent/pages/docs/overview/limitations.md +86 -0
  88. package/dist/agent/pages/docs/overview/who-it-is-for.md +61 -0
  89. package/dist/agent/pages/docs/recipes/authenticated-server-route.md +62 -0
  90. package/dist/agent/pages/docs/recipes/component-testing.md +196 -0
  91. package/dist/agent/pages/docs/recipes/dynamic-query-list.md +62 -0
  92. package/dist/agent/pages/docs/recipes/error-messages.md +112 -0
  93. package/dist/agent/pages/docs/recipes/file-upload-form.md +80 -0
  94. package/dist/agent/pages/docs/recipes/guest-users.md +186 -0
  95. package/dist/agent/pages/docs/recipes/infinite-scroll.md +78 -0
  96. package/dist/agent/pages/docs/recipes/multiple-file-uploads.md +97 -0
  97. package/dist/agent/pages/docs/recipes/optimistic-todo-list.md +104 -0
  98. package/dist/agent/pages/docs/recipes/organization-permissions.md +217 -0
  99. package/dist/agent/pages/docs/recipes/protected-dashboard.md +89 -0
  100. package/dist/agent/pages/docs/recipes/public-and-private-data.md +68 -0
  101. package/dist/agent/pages/docs/recipes/realtime-feed.md +177 -0
  102. package/dist/agent/pages/docs/recipes/time-based-data.md +88 -0
  103. package/dist/agent/pages/docs/reference/api-surface.md +150 -0
  104. package/dist/agent/pages/docs/reference/cli.md +79 -0
  105. package/dist/agent/pages/docs/reference/composables.md +446 -0
  106. package/dist/agent/pages/docs/reference/error-types.md +280 -0
  107. package/dist/agent/pages/docs/reference/experimental.md +46 -0
  108. package/dist/agent/pages/docs/reference/module-configuration.md +208 -0
  109. package/dist/agent/pages/docs/reference/operation-error-codes.md +90 -0
  110. package/dist/agent/pages/docs/reference/package-exports.md +106 -0
  111. package/dist/agent/pages/docs/reference/server-api.md +282 -0
  112. package/dist/agent/pages/docs.md +37 -0
  113. package/dist/index.d.mts +5 -0
  114. package/dist/index.d.ts +5 -0
  115. package/dist/index.mjs +4 -0
  116. package/dist/internal.d.mts +21 -0
  117. package/dist/internal.d.ts +21 -0
  118. package/dist/internal.mjs +4 -0
  119. package/dist/policy.d.mts +1 -0
  120. package/dist/policy.d.ts +1 -0
  121. package/dist/policy.mjs +1 -0
  122. package/dist/shared/better-convex-functions.BXyIEZ9W.mjs +1936 -0
  123. package/dist/shared/better-convex-functions.BagJR2Lk.d.mts +96 -0
  124. package/dist/shared/better-convex-functions.BagJR2Lk.d.ts +96 -0
  125. package/dist/shared/better-convex-functions.CkBcbT2F.mjs +96 -0
  126. package/dist/shared/better-convex-functions.CyTJjgz5.d.mts +34 -0
  127. package/dist/shared/better-convex-functions.CyTJjgz5.d.ts +34 -0
  128. package/dist/shared/better-convex-functions.DB87b11u.d.mts +1568 -0
  129. package/dist/shared/better-convex-functions.cKweSRF2.d.ts +1568 -0
  130. package/dist/test.d.mts +57 -0
  131. package/dist/test.d.ts +57 -0
  132. package/dist/test.mjs +148 -0
  133. package/package.json +51 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-present Lupinum OG and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,4 +1,155 @@
1
- # Temporary Holding Version
1
+ <p align="center"><img src="https://raw.githubusercontent.com/lupinum-dev/better-convex/main/docs/public/web-app-manifest-512x512.png" width="128" alt="Better Convex icon"></p>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
4
- If no other versions are published within 30 days, this package and version will be deleted.
3
+ <h1 align="center">@lupinum/better-convex-functions</h1>
4
+
5
+ <p align="center">Say once who may do what, to which rows, and let every Convex function check it.</p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@lupinum/better-convex-functions"><img src="https://img.shields.io/npm/v/@lupinum/better-convex-functions?label=npm" alt="npm version"></a>
9
+ <a href="https://github.com/lupinum-dev/better-convex/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/better-convex/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
10
+ <a href="https://github.com/lupinum-dev/better-convex/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
11
+ </p>
12
+
13
+ > [!WARNING]
14
+ > This package is experimental (`0.x`). Its API can change in any release until `1.0.0`.
15
+
16
+ ## Purpose
17
+
18
+ This package is an optional layer for the Convex functions of an application. You write one
19
+ policy (actions, roles, agent scopes) and one row rule per table. Every `query`, `mutation` and
20
+ internal operation that you build with `defineFunctions` then:
21
+
22
+ - finds the caller (a person, a signed-out visitor, an agent, or a system job);
23
+ - checks the action against the caller's role in the tenant that the input names;
24
+ - checks every row that the handler reads or writes through `ctx.db`, so a forgotten filter
25
+ fails instead of returning another tenant's rows;
26
+ - hands the same caller to internal operations that it calls or schedules.
27
+
28
+ A test helper finds every function that skips this layer. A plain Convex function stays
29
+ possible behind `trusted(reason, fn)`.
30
+
31
+ The package imports only `convex`. It works with any frontend.
32
+
33
+ ## Requirements
34
+
35
+ - Node.js `^22.19.0 || ^24.11.0`
36
+ - Convex `>=1.42.2 <2`
37
+ - A users table called `users`
38
+
39
+ ## Installation
40
+
41
+ ```bash
42
+ pnpm add @lupinum/better-convex-functions@next
43
+ ```
44
+
45
+ ## Quick start
46
+
47
+ Write the policy in its own file. It is plain data, and the browser can import it too, so take
48
+ `definePolicy` from the `/policy` entry, which has no server code.
49
+
50
+ ```ts [convex/policy.ts]
51
+ import { definePolicy } from '@lupinum/better-convex-functions/policy'
52
+
53
+ export const policy = definePolicy({
54
+ actions: ['projects.list', 'projects.archive'],
55
+ roles: {
56
+ owner: ['*'],
57
+ member: ['projects.list'],
58
+ },
59
+ // What a person grants an AI host on the consent page.
60
+ scopes: {
61
+ 'projects:read': { label: 'See your projects.', actions: ['projects.list'] },
62
+ 'projects:write': {
63
+ label: 'Archive projects after you approve it.',
64
+ actions: ['projects.archive'],
65
+ },
66
+ },
67
+ // An agent may ask to archive, but a person decides.
68
+ agents: { 'projects.archive': 'approve' },
69
+ })
70
+ ```
71
+
72
+ Then give `defineFunctions` the policy, how to find the user and their role, and one row rule
73
+ per table:
74
+
75
+ ```ts [convex/functions.ts]
76
+ import { custom, defineFunctions, owner, tenant } from '@lupinum/better-convex-functions'
77
+
78
+ import type { Doc } from './_generated/dataModel'
79
+ import { auth } from './auth'
80
+ import { policy } from './policy'
81
+
82
+ export const fns = defineFunctions({
83
+ auth,
84
+ policy,
85
+ user: (ctx, authId) =>
86
+ ctx.db
87
+ .query('users')
88
+ .withIndex('by_auth_id', (q) => q.eq('authId', authId))
89
+ .unique(),
90
+ roleOf: async (ctx, user, tenant) => {
91
+ if (tenant.table !== 'organizations') return null
92
+ const membership = await ctx.db
93
+ .query('memberships')
94
+ .withIndex('by_org_user', (q) => q.eq('organizationId', tenant.id).eq('userId', user._id))
95
+ .unique()
96
+ return membership?.role ?? null
97
+ },
98
+ rules: {
99
+ users: owner('_id'),
100
+ organizations: tenant('_id'),
101
+ // Every membership of an organization where your role allows the action. Not owner('userId'):
102
+ // that would let a member change their own role or add themselves to another organization.
103
+ memberships: custom<Doc<'memberships'>>((ctx, membership) =>
104
+ ctx.allows({ table: 'organizations', id: membership.organizationId }),
105
+ ),
106
+ projects: tenant('organizationId'),
107
+ },
108
+ })
109
+
110
+ export const { query, mutation, internalQuery, internalMutation, internalAction, job } = fns
111
+ ```
112
+
113
+ Spread `libraryTables` into your schema. A table without a rule is a type error.
114
+
115
+ ## Entry points
116
+
117
+ | Import | Contents |
118
+ | --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
119
+ | `@lupinum/better-convex-functions` | `defineFunctions`, `definePolicy`, the row rules, `libraryTables`, `trusted`, `fail` and helpers |
120
+ | `@lupinum/better-convex-functions/policy` | `definePolicy`, `can`, `consentScopes` and the policy types, without server code, for the browser |
121
+ | `@lupinum/better-convex-functions/test` | `unguardedFunctions` and `countDocuments`, for tests |
122
+ | `@lupinum/better-convex-functions/agent-docs` | Markdown file for coding agents; not a JavaScript module |
123
+
124
+ `@lupinum/better-convex-functions/internal` exists only for `@lupinum/better-convex-agents` and
125
+ the in-app agent runtime. It is not public API, is not covered by semver, and can change in any
126
+ release.
127
+
128
+ ## Testing your application
129
+
130
+ `@lupinum/better-convex-functions/test` has helpers for `convex-test`:
131
+
132
+ - `await unguardedFunctions(modules)` lists every function that bypasses the layer. Pass the
133
+ `import.meta.glob` map you give `convexTest` and assert that the list is empty. It throws when
134
+ the map has no `defineFunctions` operation.
135
+ - `countDocuments(call)` counts the documents one call reads and writes, for budget tests.
136
+
137
+ Test sign-in and MCP grants with the real Better Auth component
138
+ (`signInAs` and `grantMcp` from `@lupinum/better-convex-nuxt/better-auth/test`). Call tools as a
139
+ host does with `callTool` from `@lupinum/better-convex-agents/test`.
140
+
141
+ ## Documentation
142
+
143
+ [Start here](https://better-convex.lupinum.com/docs/build/functions/start-here) builds one
144
+ operation, one rule and one tool. Then read
145
+ [policy and roles](https://better-convex.lupinum.com/docs/build/functions/policy-and-roles),
146
+ [row rules](https://better-convex.lupinum.com/docs/build/functions/row-rules),
147
+ [internal operations](https://better-convex.lupinum.com/docs/build/functions/internal-operations),
148
+ [test your app](https://better-convex.lupinum.com/docs/build/functions/testing),
149
+ the [threat model](https://better-convex.lupinum.com/docs/build/functions/threat-model) and the
150
+ [error codes](https://better-convex.lupinum.com/docs/reference/operation-error-codes).
151
+ The package exports the same pages for coding agents as `@lupinum/better-convex-functions/agent-docs`.
152
+
153
+ ## License
154
+
155
+ [MIT](https://github.com/lupinum-dev/better-convex/blob/main/LICENSE)
@@ -0,0 +1,156 @@
1
+ # @lupinum/better-convex-functions 0.1.0-rc.0 documentation
2
+
3
+ These pages describe the installed version 0.1.0-rc.0. Prefer them over the
4
+ website and over knowledge of earlier versions: the API changed during the 1.0 betas.
5
+
6
+ ## Start here
7
+
8
+ | Task | Read in this order |
9
+ | ---- | ------------------ |
10
+ | Check who may do what in every Convex function | [Start here](./pages/docs/build/functions/start-here.md) → [Policy and roles](./pages/docs/build/functions/policy-and-roles.md) → [Row rules](./pages/docs/build/functions/row-rules.md) |
11
+ | Run follow-up work, outside calls and crons | [Internal operations](./pages/docs/build/functions/internal-operations.md) |
12
+ | Prove that nothing leaks and calls stay cheap | [Test your app](./pages/docs/build/functions/testing.md) → [Cost](./pages/docs/build/functions/cost.md) |
13
+ | Know what is and is not protected | [Threat model](./pages/docs/build/functions/threat-model.md) |
14
+ | Handle an error code | [Operation error codes](./pages/docs/reference/operation-error-codes.md) |
15
+
16
+ ## Rules
17
+
18
+ - Build every Convex function with `query`, `mutation`, `internalQuery`, `internalMutation`, `internalAction` or `job` from `defineFunctions`, never from `./_generated/server`. Wrap a function that must skip the library in `trusted(reason, fn)`, and keep the `unguardedFunctions` test green.
19
+ - Add an action to `policy.actions` before an operation uses it. Give every table a row rule; do not check membership in the handler.
20
+ - Read rows by an index that starts with the field the table rule checks (the tenant or owner field, or the `publicRead` condition). A query that returns a row the caller may not read fails.
21
+ - An operation on an `anyOf` table names its tenant in its own arguments (`organizationId`).
22
+ - Fail with `fail(code, message)` and an `ErrorCode`. Any other error reaches callers as a generic message.
23
+ - Call follow-up work with `ctx.runQuery`, `ctx.runMutation` or `ctx.scheduler` from the handler, and build the target with `internalQuery`, `internalMutation` or `internalAction` from `defineFunctions`.
24
+ - Start a `job` only from a cron or another job. A call or schedule of a job from an operation or an internal action is a type error; write a row that the job reads at its next run instead.
25
+
26
+ ## All pages
27
+
28
+ ### Overview
29
+
30
+ - [Better Convex documentation](./pages/docs.md)
31
+ - [Better Convex Nuxt](./pages/docs/overview/introduction.md)
32
+ - [Who it is for](./pages/docs/overview/who-it-is-for.md)
33
+ - [Limitations and trade-offs](./pages/docs/overview/limitations.md)
34
+ - [Compare Nuxt integrations](./pages/docs/overview/comparison.md)
35
+
36
+ ### Get started
37
+
38
+ - [Choose your path](./pages/docs/get-started/choose-your-path.md)
39
+ - [Installation](./pages/docs/get-started/installation.md)
40
+ - [First real-time page](./pages/docs/get-started/first-realtime-page.md)
41
+ - [Add a mutation](./pages/docs/get-started/add-a-mutation.md)
42
+ - [Add authentication](./pages/docs/get-started/add-authentication.md)
43
+ - [Protect data](./pages/docs/get-started/protect-data.md)
44
+ - [Project structure](./pages/docs/get-started/project-structure.md)
45
+ - [Next steps](./pages/docs/get-started/next-steps.md)
46
+ - [Plain Vue and Vite](./pages/docs/get-started/plain-vue.md)
47
+
48
+ ### Build
49
+
50
+ - [Queries](./pages/docs/build/queries/queries.md)
51
+ - [Reactive arguments](./pages/docs/build/queries/reactive-arguments.md)
52
+ - [Loading and stale data](./pages/docs/build/queries/loading-and-stale-data.md)
53
+ - [Query execution options](./pages/docs/build/queries/ssr-options.md)
54
+ - [Pagination](./pages/docs/build/queries/pagination.md)
55
+ - [Mutations](./pages/docs/build/write-data/mutations.md)
56
+ - [Actions](./pages/docs/build/write-data/actions.md)
57
+ - [Optimistic updates](./pages/docs/build/write-data/optimistic-updates.md)
58
+ - [Concurrent operations](./pages/docs/build/write-data/concurrent-operations.md)
59
+ - [Form submissions](./pages/docs/build/write-data/forms.md)
60
+ - [Multi-step operations](./pages/docs/build/write-data/multi-step-operations.md)
61
+ - [Authentication](./pages/docs/build/authentication/overview.md)
62
+ - [Better Auth setup](./pages/docs/build/authentication/better-auth-setup.md)
63
+ - [Auth state and user data](./pages/docs/build/authentication/auth-state-and-user.md)
64
+ - [Sign in and sign out](./pages/docs/build/authentication/sign-in-and-sign-out.md)
65
+ - [Route protection](./pages/docs/build/authentication/route-protection.md)
66
+ - [Backend authorization](./pages/docs/build/authentication/backend-authorization.md)
67
+ - [Better Auth plugins](./pages/docs/build/authentication/better-auth-plugins.md)
68
+ - [Custom user fields](./pages/docs/build/authentication/custom-user-fields.md)
69
+ - [User synchronization](./pages/docs/build/authentication/user-synchronization.md)
70
+ - [Delegated OAuth and MCP](./pages/docs/build/authentication/delegated-oauth-and-mcp.md)
71
+ - [Transactional auth email](./pages/docs/build/authentication/transactional-email.md)
72
+ - [Social sign-in](./pages/docs/build/authentication/social-sign-in.md)
73
+ - [Better Auth plugin support](./pages/docs/build/authentication/better-auth-plugin-support.md)
74
+ - [Cacheable public pages](./pages/docs/build/authentication/cacheable-public-pages.md)
75
+ - [Several sites on one deployment](./pages/docs/build/authentication/multiple-site-origins.md)
76
+ - [Account deletion](./pages/docs/build/authentication/account-deletion.md)
77
+ - [serverConvex](./pages/docs/build/server/server-convex.md)
78
+ - [Server routes](./pages/docs/build/server/server-routes.md)
79
+ - [Webhooks and jobs](./pages/docs/build/server/webhooks-and-jobs.md)
80
+ - [Credentials and server security](./pages/docs/build/server/credentials-and-security.md)
81
+ - [Upload files](./pages/docs/build/files/upload-files.md)
82
+ - [Storage URLs](./pages/docs/build/files/storage-urls.md)
83
+ - [File validation and deletion](./pages/docs/build/files/validation-and-deletion.md)
84
+ - [Connection state](./pages/docs/build/application-behavior/connection-state.md)
85
+ - [Error handling](./pages/docs/build/application-behavior/error-handling.md)
86
+ - [Logging](./pages/docs/build/application-behavior/logging.md)
87
+ - [DevTools](./pages/docs/build/application-behavior/devtools.md)
88
+ - [Performance](./pages/docs/build/application-behavior/performance.md)
89
+ - [Start the client on demand](./pages/docs/build/application-behavior/on-demand-client.md)
90
+ - [Tools and approvals](./pages/docs/build/agents/tools-and-approvals.md)
91
+ - [The MCP door](./pages/docs/build/agents/mcp-door.md)
92
+ - [Limits](./pages/docs/build/agents/limits.md)
93
+ - [MCP on Convex](./pages/docs/build/agents/mcp.md)
94
+ - [Add MCP to your application](./pages/docs/build/agents/mcp-application.md)
95
+ - [Connect ChatGPT and Claude](./pages/docs/build/agents/connect-chatgpt-and-claude.md)
96
+ - [MCP Apps](./pages/docs/build/agents/mcp-apps.md)
97
+ - [Start here](./pages/docs/build/functions/start-here.md)
98
+ - [Policy and roles](./pages/docs/build/functions/policy-and-roles.md)
99
+ - [Row rules](./pages/docs/build/functions/row-rules.md)
100
+ - [Internal operations](./pages/docs/build/functions/internal-operations.md)
101
+ - [Test your app](./pages/docs/build/functions/testing.md)
102
+ - [Cost](./pages/docs/build/functions/cost.md)
103
+ - [Threat model](./pages/docs/build/functions/threat-model.md)
104
+ - [Rate limits and audit log](./pages/docs/build/functions/limits-and-audit.md)
105
+
106
+ ### Recipes
107
+
108
+ - [Protected dashboard](./pages/docs/recipes/protected-dashboard.md)
109
+ - [Real-time feed](./pages/docs/recipes/realtime-feed.md)
110
+ - [Optimistic todo list](./pages/docs/recipes/optimistic-todo-list.md)
111
+ - [Infinite scroll](./pages/docs/recipes/infinite-scroll.md)
112
+ - [File upload form](./pages/docs/recipes/file-upload-form.md)
113
+ - [Organization permissions](./pages/docs/recipes/organization-permissions.md)
114
+ - [Authenticated server route](./pages/docs/recipes/authenticated-server-route.md)
115
+ - [Public and private data](./pages/docs/recipes/public-and-private-data.md)
116
+ - [Test signed-in screens](./pages/docs/recipes/component-testing.md)
117
+ - [Time-based data](./pages/docs/recipes/time-based-data.md)
118
+ - [A list of queries](./pages/docs/recipes/dynamic-query-list.md)
119
+ - [Error messages](./pages/docs/recipes/error-messages.md)
120
+ - [Several file uploads](./pages/docs/recipes/multiple-file-uploads.md)
121
+ - [Guest users](./pages/docs/recipes/guest-users.md)
122
+
123
+ ### Concepts
124
+
125
+ - [Mental model](./pages/docs/concepts/mental-model.md)
126
+ - [Request lifecycle](./pages/docs/concepts/request-lifecycle.md)
127
+ - [SSR, hydration, and real-time](./pages/docs/concepts/ssr-hydration-realtime.md)
128
+ - [Query state and caching](./pages/docs/concepts/query-ownership-and-caching.md)
129
+ - [Authentication and identity](./pages/docs/concepts/authentication-and-identity.md)
130
+ - [Server and client boundaries](./pages/docs/concepts/server-and-client-boundaries.md)
131
+ - [Errors and failures](./pages/docs/concepts/errors-and-failures.md)
132
+ - [Design decisions](./pages/docs/concepts/design-decisions.md)
133
+ - [Glossary](./pages/docs/concepts/glossary.md)
134
+
135
+ ### Operations
136
+
137
+ - [Deployment](./pages/docs/operations/deployment.md)
138
+ - [Environment variables](./pages/docs/operations/environment-variables.md)
139
+ - [Deploy to Vercel](./pages/docs/operations/deploy-to-vercel.md)
140
+ - [Troubleshooting](./pages/docs/operations/troubleshooting.md)
141
+ - [Release compatibility](./pages/docs/operations/release-compatibility.md)
142
+ - [Security model](./pages/docs/operations/security-model.md)
143
+ - [Upgrade to 1.0](./pages/docs/operations/upgrade-to-1-0.md)
144
+ - [Before your app goes live](./pages/docs/operations/before-launch.md)
145
+
146
+ ### Reference
147
+
148
+ - [Composables](./pages/docs/reference/composables.md)
149
+ - [Server API](./pages/docs/reference/server-api.md)
150
+ - [Error types](./pages/docs/reference/error-types.md)
151
+ - [Module configuration](./pages/docs/reference/module-configuration.md)
152
+ - [Package exports](./pages/docs/reference/package-exports.md)
153
+ - [API reference](./pages/docs/reference/api-surface.md)
154
+ - [Experimental APIs](./pages/docs/reference/experimental.md)
155
+ - [Command line](./pages/docs/reference/cli.md)
156
+ - [Operation error codes](./pages/docs/reference/operation-error-codes.md)
@@ -0,0 +1,175 @@
1
+ ---
2
+ title: "Connect ChatGPT and Claude"
3
+ description: "Create an OAuth client for each host, enter the right settings, test with MCP Inspector, and fix common connection failures."
4
+ url: "https://better-convex.lupinum.com/docs/build/agents/connect-chatgpt-and-claude"
5
+ route: "/docs/build/agents/connect-chatgpt-and-claude"
6
+ locale: "en"
7
+ section: "Documentation"
8
+ collection: "docs"
9
+ source: "ginko-content"
10
+ ---
11
+
12
+ # Connect ChatGPT and Claude
13
+
14
+ > Create an OAuth client for each host, enter the right settings, test with MCP Inspector, and fix common connection failures.
15
+
16
+ This page connects ChatGPT and Claude to an MCP server built with
17
+ [Add MCP to your application](./mcp-application.md). Each host
18
+ gets its own OAuth client. A person connects, signs in to your application,
19
+ and allows access on your consent page. The host then calls your tools with a
20
+ ten-minute access token and renews it while the person's session lasts.
21
+
22
+ ## Before you connect
23
+
24
+ - Deploy the application and Convex with HTTPS origins. Hosts do not connect to
25
+ a loopback address.
26
+ - Set `SITE_URL` to the exact public Nuxt origin. The OAuth issuer is
27
+ `${SITE_URL}/api/auth`.
28
+ - Run `auth:ensureSigningKey` and check that its key ID appears at
29
+ `https://your-app.example/api/auth/jwks`.
30
+ - List each host in the profile: `oauth: { mcp: { scopes, hosts: ['chatgpt', 'claude'] } }`.
31
+ - Export an internal mutation that calls `auth.oauthOperator.createHostClient`,
32
+ as in the recipe's `convex/connections.ts`.
33
+ - Test the flow with [MCP Inspector](#test-with-mcp-inspector) first.
34
+
35
+ ## What each host needs
36
+
37
+ | Setting | ChatGPT | Claude |
38
+ | --- | --- | --- |
39
+ | MCP server URL | `https://<deployment>.convex.site/mcp` | the same URL |
40
+ | Authentication | OAuth | OAuth |
41
+ | Client registration | User-defined OAuth client | Your own OAuth client |
42
+ | Client ID | From `createHostClient` | From `createHostClient` |
43
+ | Client secret | Empty | Empty |
44
+ | Token endpoint auth | `none` | Not asked |
45
+ | Callback URL | Shown by ChatGPT; pass it to `createHostClient` | Fixed: `https://claude.ai/api/mcp/auth_callback` |
46
+ | Scopes | Select your scopes; add `offline_access` to base scopes for renewal | Requested by Claude from your metadata |
47
+
48
+ The clients are public clients with S256 PKCE. They have no secret. Dynamic
49
+ client registration is off, so the host cannot create a client itself.
50
+
51
+ ## Connect Claude
52
+
53
+ 1. Create the client:
54
+ ```bash
55
+ pnpm exec better-convex convex run connections:createHostClient '{"host":"claude"}'
56
+ ```
57
+ Record the returned `clientId`. The client accepts only Claude's fixed
58
+ callback and every scope in your profile.
59
+ 2. In Claude, add a custom connector. Enter the MCP server URL.
60
+ 3. Select **Use your own OAuth client** and paste the client ID. Leave the
61
+ secret empty.
62
+ 4. Connect. Claude opens your login page, then your consent page. Sign in and
63
+ select **Allow**.
64
+ 5. Start a new conversation and ask for something one of your tools can do.
65
+
66
+ Claude reads `scopes_supported` from your protected-resource metadata. It
67
+ can request read access and renewal first, and ask for write consent the first
68
+ time a write tool needs it.
69
+
70
+ ## Connect ChatGPT
71
+
72
+ ChatGPT shows its callback URL during setup, so create the client in the
73
+ middle of the setup.
74
+
75
+ 1. In ChatGPT, start a new connector in the developer connection settings.
76
+ Enter the MCP server URL and select OAuth.
77
+ 2. Copy the exact callback URL that ChatGPT displays. It is
78
+ `https://chatgpt.com/connector_platform_oauth_redirect` or
79
+ `https://chatgpt.com/connector/oauth/<callback-id>`. Do not guess the
80
+ callback ID.
81
+ 3. Create the client with that callback:
82
+ ```bash
83
+ pnpm exec better-convex convex run connections:createHostClient \
84
+ '{"host":"chatgpt","redirectUri":"https://chatgpt.com/connector_platform_oauth_redirect"}'
85
+ ```
86
+ 4. In **Advanced OAuth settings**, set **Registration method** to
87
+ **User-Defined OAuth Client** and **Token endpoint auth method** to
88
+ **none**. Paste the client ID and leave the client secret empty.
89
+ 5. Under **Default scopes**, select the scopes the connection needs. Enter
90
+ `offline_access` in **Base scopes** so that ChatGPT receives a refresh
91
+ token. Without it, ChatGPT asks the person to reconnect after ten minutes.
92
+ 6. Connect, sign in, and allow access. Refresh the connector's tools, then
93
+ start a new conversation.
94
+
95
+ ## Scopes and consent
96
+
97
+ Your consent page shows the verified client name, the exact resource, and each
98
+ requested scope with its description from `oauth.mcp.scopes`. Consent grants
99
+ exactly the requested scopes, never more.
100
+
101
+ - A tool with `scopes: ['notes:write']` is visible to every connection. A
102
+ connection without that scope receives an HTTP 403 `insufficient_scope`
103
+ challenge when it calls the tool. The host can then ask the person for
104
+ consent again.
105
+ - `offline_access` allows renewal. The refresh token ends with the Better Auth
106
+ session that granted consent, and after at most seven days. Signing out of
107
+ your application ends renewal.
108
+ - A broader permission always needs new consent. An earlier grant is never
109
+ widened silently.
110
+
111
+ Each connection is one row on the person's connections page
112
+ (`auth.oauthConnections.list`). **Disconnect** there revokes the consent and
113
+ the refresh tokens on the server. The host's next request fails.
114
+
115
+ Disconnecting inside the host does not always revoke the grant on your server.
116
+ Revoke it on your connections page. To stop a host for every user, disable its
117
+ client with `auth.oauthOperator.setClientDisabled`.
118
+
119
+ ## Test with MCP Inspector
120
+
121
+ Test the OAuth flow and your tools locally before you connect a real host.
122
+
123
+ 1. Create a client for Inspector's local callback. Run this internal mutation
124
+ only in development:
125
+ ```ts [convex/connections.ts]
126
+ export const createInspectorClient = internalMutation({
127
+ args: {},
128
+ handler: async (ctx) =>
129
+ await auth.oauthOperator.createPublicClient(ctx, {
130
+ name: 'MCP Inspector',
131
+ profile: 'mcp-inspector',
132
+ redirectUris: ['http://localhost:6274/oauth/callback'],
133
+ scopes: ['notes:read', 'offline_access'],
134
+ }),
135
+ })
136
+ ```
137
+ Without a `resource`, the client is bound to the MCP resource of
138
+ `oauth.mcp`, as a `createHostClient` client is. Inspector requests
139
+ `offline_access` by default; without it in `scopes`, authorization fails
140
+ with `invalid_scope`.
141
+ 2. Run `pnpm dlx @modelcontextprotocol/inspector`.
142
+ 3. Select the Streamable HTTP transport and enter your `CONVEX_SITE_URL`
143
+ followed by `/mcp`.
144
+ 4. In the OAuth settings, enter the client ID, leave the secret empty, and
145
+ request your scopes.
146
+ 5. Connect, sign in, and allow access. List the tools and call one.
147
+ 6. Disconnect on your connections page, then call the tool again. The call must
148
+ fail with HTTP 401.
149
+
150
+ For automated checks, snapshot the catalog with `listMcpCatalog` as shown in
151
+ [MCP on Convex](./mcp.md#test-the-catalog).
152
+
153
+ ## Update tools after a deploy
154
+
155
+ Hosts cache the tool list. After you change tools:
156
+
157
+ - In ChatGPT, refresh the connector's tools, then start a new conversation.
158
+ - In Claude, start a new conversation. Claude can keep an older catalog for a
159
+ while.
160
+ - Keep MCP Apps `ui://` URIs stable. See [MCP Apps](./mcp-apps.md).
161
+
162
+ ## Common failures
163
+
164
+ | Symptom | Cause and fix |
165
+ | --- | --- |
166
+ | `createHostClient` fails with `AUTH_OAUTH_CLIENT_HOST_NOT_ENABLED` | Add the host to `oauth.mcp.hosts`. |
167
+ | `createHostClient` fails with `AUTH_OAUTH_CLIENT_REDIRECT_URI_INVALID` | Pass the exact ChatGPT callback. For Claude, omit `redirectUri`. |
168
+ | The host shows a redirect or `invalid_client` error | The client's callback does not match the host's callback, or the client ID is wrong. Create a new client with the exact callback. |
169
+ | The login page says the request is invalid or expired | The signed authorization request is older than two minutes, or the page changed its query. Start the connection again from the host. |
170
+ | Every tool call returns HTTP 401 `invalid_token` | `SITE_URL` does not match the issuer in the token, the resource URL differs from `CONVEX_SITE_URL` + `/mcp`, no signing key exists, or the grant was revoked. |
171
+ | A tool call returns HTTP 403 `insufficient_scope` | The connection lacks the tool's scope. Allow the new scope when the host asks. Check that the client was created with that scope. |
172
+ | The host asks to reconnect every ten minutes | The connection has no `offline_access`. In ChatGPT, add it to base scopes. Check that `renewal` is not `false`. A session that ended also ends renewal. |
173
+ | A tool result says `MCP_ACCESS_DENIED` | The grant, session, or client changed after the token was issued. Reconnect. |
174
+ | HTTP 400 with JSON-RPC `-32022` or `-32020` | The client does not send the `MCP-Protocol-Version: 2026-07-28` header. Only the modern protocol is supported. |
175
+ | New tools do not appear | Refresh the host's tool list and start a new conversation. |
@@ -0,0 +1,63 @@
1
+ ---
2
+ title: "Limits"
3
+ description: "The fixed limits on agent calls, approval requests, input size and stored history, and the error each one returns."
4
+ url: "https://better-convex.lupinum.com/docs/build/agents/limits"
5
+ route: "/docs/build/agents/limits"
6
+ locale: "en"
7
+ section: "Documentation"
8
+ collection: "docs"
9
+ source: "ginko-content"
10
+ ---
11
+
12
+ # Limits
13
+
14
+ > The fixed limits on agent calls, approval requests, input size and stored history, and the error each one returns.
15
+
16
+ The limits are on by default and fixed. They keep one connection from
17
+ flooding the application and keep each call inside Convex's own limits. An
18
+ agent that reaches one gets a code and a message that says what to do.
19
+
20
+ <note>
21
+ In-app agent runs are experimental in 0.1: their API may change in a minor release. The MCP door, tools and approvals are stable.
22
+ </note>
23
+
24
+ | Limit | Value | When reached |
25
+ | --- | --- | --- |
26
+ | Writes per agent connection | 60 a minute | `RATE_LIMITED`; the message says how many seconds to wait |
27
+ | Open approval requests per agent | 20 | `RATE_LIMITED`; the agent waits until people decide |
28
+ | IDs in the input of one call | 1,000 | `TOO_LARGE`, before the handler runs |
29
+ | Rows one approval request covers | 500 | `TOO_LARGE`; ask for fewer at once |
30
+ | Size of one approval request | 256 KiB, with its plan and input | `TOO_LARGE`; make the plan smaller, or split the work |
31
+ | Time to decide an approval request | 30 minutes | `APPROVAL_EXPIRED`; the agent asks again |
32
+ | Items per page of a tool | 1 to 100, 50 by default | larger values are cut to 100 |
33
+ | Size of one MCP request | 64 KiB | HTTP `413`, before any tool runs |
34
+ | Rows in one activity list | 1 to 200, 50 by default | larger values are cut to 200 |
35
+ | Stored result of a write, for replay | 64 KiB | stored as `{ truncated: true, bytes }`; the write itself is kept |
36
+ | Activity rows | kept 1 year | deleted by `housekeeping` |
37
+ | Decided approval requests | kept 90 days | deleted by `housekeeping`; the activity row records the decision |
38
+ | Finished in-app agent runs | kept 30 days, with their messages | deleted by `housekeeping` |
39
+ | Length of a tool name | 1 to 64 letters, digits, `_` or `-` | error when the module loads |
40
+ | Text of an approval summary | one line, 300 characters | longer text is cut |
41
+
42
+ Read tools have no rate limit. Convex's own limits apply to them, and a page
43
+ reads at most 100 rows.
44
+
45
+ A refused call does not count against a limit: its transaction rolls back.
46
+ Agents use the same limiter as the policy's [`limits`](../functions/limits-and-audit.md): a bucket that refills continuously, not a fixed window.
47
+
48
+ ## Retries
49
+
50
+ A host may send a write twice, for example after a timeout. Give the call a
51
+ `request_id`. The same `request_id` with the same input returns the first
52
+ result; the write runs once. A `request_id` reused for a different call fails
53
+ with `REQUEST_ID_REUSED`.
54
+
55
+ The same call while its approval request is open returns the same request.
56
+ After the person declines, the same call gets `APPROVAL_DECLINED`, with or
57
+ without its `request_id`, until the declined request would have expired (30
58
+ minutes after it was made).
59
+
60
+ ## Known gaps
61
+
62
+ - A parent tenant does not see the open requests of the tenants below it.
63
+ List them for each child tenant.