@vllnt/convex-helpers 0.1.0-canary.1e0f54a

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bntvllnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+<!-- Badges -->
+[![npm version](https://img.shields.io/npm/v/@vllnt/convex-helpers.svg)](https://www.npmjs.com/package/@vllnt/convex-helpers)
+[![CI](https://github.com/vllnt/convex-helpers/actions/workflows/ci.yml/badge.svg)](https://github.com/vllnt/convex-helpers/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/@vllnt/convex-helpers.svg)](./LICENSE)
+
+# @vllnt/convex-helpers
+
+Typed host-side helpers for Convex backends — builders, errors, validators, relationships,
+pagination, HTTP, env, and observability.
+
+```ts
+import { asyncMap, pruneNull, nullThrows } from "@vllnt/convex-helpers";
+
+const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+```
+
+A helpers library (not a sandboxed Convex component): pure functions and host-`ctx` glue that run with
+the host's `ctx` — no own tables, no `app.use()` mounting. Stateful concerns (rate limiting,
+idempotency, flags) belong in `@convex-dev/*` or `@vllnt/convex-*` components.
+
+See [ROADMAP.md](./ROADMAP.md) for the planned module surface.
+
+## Features
+
+- `asyncMap` — parallel async map that preserves order
+- `pruneNull` — filter null/undefined from arrays
+- `nullThrows` — non-null assertion with typed `NullDocumentError`
+- `./mcp` — expose Convex functions as MCP tools (`createMCPServer` + `query`/`mutation`/`action`/`resource`), default-deny auth, optional cursor pagination
+- [planned] `./builders` — `customQuery`/`customMutation`/`customAction`/`customCtx`
+- [planned] `./errors` — typed `AppError` + HTTP-status map
+- [planned] `./auth` — provider-agnostic `requireIdentity`/`getCurrentSubject`
+- [planned] `./env` — `defineEnv(zodSchema)` cold-start validation
+- [planned] `./tracing` — span emit + `traceparent` propagation via `@vllnt/logger`
+- [planned] `./testing` — fixture factories + `withIdentity`
+- [planned] `./relationships`, `./validators`, `./pagination`, `./rls`, `./triggers`, `./http`
+- [planned] `./react` — optional tree-shakeable front-end hooks layer
+
+## Installation
+
+```bash
+pnpm add @vllnt/convex-helpers
+```
+
+`convex` is a peer dependency:
+
+```bash
+pnpm add convex
+```
+
+## Usage
+
+```ts
+import { asyncMap, pruneNull, nullThrows } from "@vllnt/convex-helpers";
+
+// Parallel fetch with null filtering
+const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+
+// Non-null assertion
+const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+```
+
+### MCP tools — `./mcp`
+
+Expose Convex functions to LLM agents over the Model Context Protocol. The `./mcp` entry is
+tree-shakeable — backend-only consumers pull zero MCP code. It needs two optional peer deps:
+
+```bash
+pnpm add @modelcontextprotocol/sdk zod
+```
+
+```ts
+import { createMCPServer, query, mutation } from "@vllnt/convex-helpers/mcp";
+import { api } from "./_generated/api";
+import { v } from "convex/values";
+
+export const mcp = createMCPServer({
+  auth: { validate: async (key) => key === process.env.MCP_API_KEY },
+  tools: {
+    list_projects: query(api.projects.list, { args: v.object({}), description: "List all projects" }),
+    create_project: mutation(api.projects.create, {
+      args: v.object({ name: v.string() }),
+      description: "Create a project",
+    }),
+  },
+});
+
+// Mount the route handler (e.g. Next.js App Router)
+export const { GET, POST } = mcp.handler();
+```
+
+Migrating from `@vllnt/convex-mcp`? Change the import to `@vllnt/convex-helpers/mcp` — the API is
+identical. See [docs/API.md](./docs/API.md#mcp-tools-mcp) for the full `./mcp` reference.
+
+## API Reference
+
+See [docs/API.md](./docs/API.md) for full API reference with signatures and examples.
+
+## Testing
+
+```bash
+pnpm test
+pnpm test:coverage   # must reach 100%
+```
+
+Tests use [vitest](https://vitest.dev) with the node environment. 100% coverage is enforced via
+`vitest.config.mts` thresholds.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+## Author
+
+Built by [bntvllnt](https://github.com/bntvllnt) · [bntvllnt.com](https://bntvllnt.com) · [X
+@bntvllnt](https://x.com/bntvllnt)
+
+Part of the [@vllnt](https://github.com/vllnt) Convex component fleet —
+[vllnt.com](https://vllnt.com)
+
+If this is useful, [sponsor the work](https://github.com/sponsors/bntvllnt).
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export declare function asyncMap<T, TResult>(list: T[], fn: (item: T, index: number) => Promise<TResult>): Promise<TResult[]>;
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export declare function pruneNull<T>(list: (null | T | undefined)[]): T[];
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export declare class NullDocumentError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export declare function nullThrows<T>(value: null | T | undefined, message?: string): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EACvC,IAAI,EAAE,CAAC,EAAE,EACT,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,EAAE,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEhE;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAiC;CAIrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,GAAG,CAAC,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAKH"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export async function asyncMap(list, fn) {
+    return Promise.all(list.map(fn));
+}
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export function pruneNull(list) {
+    return list.filter((item) => item !== null && item !== undefined);
+}
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export class NullDocumentError extends Error {
+    constructor(message = "Expected a non-null document") {
+        super(message);
+        this.name = "NullDocumentError";
+    }
+}
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export function nullThrows(value, message) {
+    if (value === null || value === undefined) {
+        throw new NullDocumentError(message);
+    }
+    return value;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAS,EACT,EAAgD;IAEhD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAI,IAA8B;IACzD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAa,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;AAC/E,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,GAAG,8BAA8B;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,KAA2B,EAC3B,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/mcp/auth.d.ts

@@ -0,0 +1,11 @@
+import type { AuthConfig } from "./types.js";
+export declare function extractApiKey(request: Request): string | undefined;
+export declare function validateRequest(request: Request, auth: AuthConfig): Promise<{
+    apiKey: string;
+    convexToken?: string;
+    valid: true;
+} | {
+    response: Response;
+    valid: false;
+}>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/mcp/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASlE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CACN;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CACvC,CAiCA"}

package/dist/mcp/auth.js

@@ -0,0 +1,36 @@
+export function extractApiKey(request) {
+    const authHeader = request.headers.get("authorization");
+    if (!authHeader)
+        return undefined;
+    if (authHeader.startsWith("Bearer ")) {
+        return authHeader.slice(7);
+    }
+    return undefined;
+}
+export async function validateRequest(request, auth) {
+    const apiKey = extractApiKey(request);
+    if (!apiKey) {
+        return {
+            response: new Response(JSON.stringify({
+                error: "Missing or malformed API key. Use Authorization: Bearer <key>.",
+            }), { headers: { "Content-Type": "application/json" }, status: 401 }),
+            valid: false,
+        };
+    }
+    const isValid = await auth.validate(apiKey);
+    if (!isValid) {
+        return {
+            response: new Response(JSON.stringify({ error: "Invalid API key." }), {
+                headers: { "Content-Type": "application/json" },
+                status: 401,
+            }),
+            valid: false,
+        };
+    }
+    let convexToken;
+    if (auth.convexToken) {
+        convexToken = await auth.convexToken(apiKey);
+    }
+    return { apiKey, convexToken, valid: true };
+}
+//# sourceMappingURL=auth.js.map

package/dist/mcp/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAElC,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAgB,EAChB,IAAgB;IAKhB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EACH,gEAAgE;aACnE,CAAC,EACF,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CACjE;YACD,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;gBACpE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,MAAM,EAAE,GAAG;aACZ,CAAC;YACF,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,IAAI,WAA+B,CAAC;IACpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,7 @@
+export type { ToolPage, ToolSummary } from "./pagination/types.js";
+export { resource } from "./resources/helpers.js";
+export { createMCPServer } from "./server.js";
+export { action, mutation, query } from "./tools/helpers.js";
+export type { AuthConfig, CallContext, ConvexClient, ConvexMCPServer, ConvexValidator, FunctionType, LifecycleHooks, OnCallResult, PaginationConfig, ResourceDef, ServerConfig, ToolDef, } from "./types.js";
+export { convertValidator, convexArgsToZod, UnsupportedValidatorError, } from "./validators.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,5 @@
+export { resource } from "./resources/helpers.js";
+export { createMCPServer } from "./server.js";
+export { action, mutation, query } from "./tools/helpers.js";
+export { convertValidator, convexArgsToZod, UnsupportedValidatorError, } from "./validators.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAe7D,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/mcp/pagination/context.d.ts

@@ -0,0 +1,9 @@
+import type { PaginationConfig } from "./types.js";
+/** Create pagination context from config. Validates pageSize >= 1. */
+export declare function createPaginationContext(config: PaginationConfig | undefined): {
+    enabled: boolean;
+    pageSize: number;
+    secret: string;
+    twoPhaseDiscovery: boolean;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/mcp/pagination/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAkBA"}

package/dist/mcp/pagination/context.js

@@ -0,0 +1,21 @@
+/** Create pagination context from config. Validates pageSize >= 1. */
+export function createPaginationContext(config) {
+    if (!config) {
+        return {
+            enabled: false,
+            pageSize: 0,
+            secret: "",
+            twoPhaseDiscovery: false,
+        };
+    }
+    if (!Number.isInteger(config.pageSize) || config.pageSize < 1) {
+        throw new Error("pagination.pageSize must be a positive integer >= 1");
+    }
+    return {
+        enabled: true,
+        pageSize: config.pageSize,
+        secret: crypto.randomUUID(),
+        twoPhaseDiscovery: config.twoPhaseDiscovery ?? false,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/mcp/pagination/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/mcp/pagination/context.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,UAAU,uBAAuB,CAAC,MAAoC;IAM1E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,EAAE;YACV,iBAAiB,EAAE,KAAK;SACzB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE;QAC3B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,KAAK;KACrD,CAAC;AACJ,CAAC"}

package/dist/mcp/pagination/cursor.d.ts

@@ -0,0 +1,7 @@
+export declare function encodeCursor(method: string, offset: number, secret: string): Promise<string>;
+export declare function decodeCursor(cursor: string, expectedMethod: string, secret: string): Promise<{
+    error: string;
+} | {
+    offset: number;
+}>;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/mcp/pagination/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/cursor.ts"],"names":[],"mappings":"AAgEA,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBjD"}

package/dist/mcp/pagination/cursor.js

@@ -0,0 +1,60 @@
+const SEPARATOR = ".";
+function isCursorPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const object = value;
+    return (typeof object.v === "number" &&
+        typeof object.m === "string" &&
+        typeof object.o === "number");
+}
+async function importKey(secret, usages) {
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { hash: "SHA-256", name: "HMAC" }, false, usages);
+}
+async function hmacSign(payload, secret) {
+    const key = await importKey(secret, ["sign"]);
+    return crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
+}
+async function hmacVerify(payload, signature, secret) {
+    let sigBytes;
+    try {
+        sigBytes = new Uint8Array(Array.from(atob(signature), (c) => c.charCodeAt(0)));
+    }
+    catch {
+        return false;
+    }
+    const key = await importKey(secret, ["verify"]);
+    return crypto.subtle.verify("HMAC", key, sigBytes, new TextEncoder().encode(payload));
+}
+function arrayBufferToBase64(buf) {
+    return btoa(Array.from(new Uint8Array(buf), (b) => String.fromCharCode(b)).join(""));
+}
+export async function encodeCursor(method, offset, secret) {
+    const payload = { m: method, o: offset, v: 1 };
+    const json = JSON.stringify(payload);
+    const b64 = btoa(json);
+    const sig = await hmacSign(b64, secret);
+    return `${b64}${SEPARATOR}${arrayBufferToBase64(sig)}`;
+}
+export async function decodeCursor(cursor, expectedMethod, secret) {
+    const separatorIndex = cursor.lastIndexOf(SEPARATOR);
+    if (separatorIndex === -1)
+        return { error: "invalid or expired cursor" };
+    const b64 = cursor.slice(0, separatorIndex);
+    const sig = cursor.slice(separatorIndex + 1);
+    const valid = await hmacVerify(b64, sig, secret);
+    if (!valid)
+        return { error: "invalid or expired cursor" };
+    // Safe to parse without try-catch: HMAC verification above guarantees b64 is
+    // a payload we signed, so atob + JSON.parse will not throw.
+    const raw = JSON.parse(atob(b64));
+    if (!isCursorPayload(raw))
+        return { error: "invalid or expired cursor" };
+    if (raw.v !== 1)
+        return { error: "invalid or expired cursor" };
+    if (raw.m !== expectedMethod)
+        return { error: "invalid or expired cursor" };
+    if (raw.o < 0)
+        return { error: "invalid or expired cursor" };
+    return { offset: raw.o };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/mcp/pagination/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/mcp/pagination/cursor.ts"],"names":[],"mappings":"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"}

package/dist/mcp/pagination/handlers.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type McpTool = {
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    name: string;
+};
+type ToolListFn = () => Promise<McpTool[]>;
+export declare function getOriginalToolsList(mcpServer: McpServer): ToolListFn;
+export declare function registerPaginationHandlers(mcpServer: McpServer, getAllTools: ToolListFn, pageSize: number, secret: string): void;
+export declare function registerTwoPhaseHandlers(mcpServer: McpServer, getAllTools: ToolListFn, pageSize: number, secret: string): void;
+export {};
+//# sourceMappingURL=handlers.d.ts.map

package/dist/mcp/pagination/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWzE,KAAK,OAAO,GAAG;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AAgB3C,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAcrE;AA+BD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,IAAI,CAwBN;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,IAAI,CAyDN"}

package/dist/mcp/pagination/handlers.js

@@ -0,0 +1,91 @@
+import { ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { decodeCursor, encodeCursor } from "./cursor.js";
+/* v8 ignore start -- canary: only triggers if SDK removes tools/list handler */
+function assertHandler(handler) {
+    if (!handler)
+        throw new Error("[convex-mcp] tools/list handler not found — SDK API may have changed.");
+    return handler;
+}
+/* v8 ignore stop */
+export function getOriginalToolsList(mcpServer) {
+    const handlers = mcpServer.server._requestHandlers;
+    const origHandler = assertHandler(handlers.get("tools/list"));
+    return async () => {
+        const result = await origHandler({ method: "tools/list", params: {} }, { signal: new AbortController().signal });
+        return result.tools;
+    };
+}
+async function paginateTools(tools, method, pageSize, cursor, secret) {
+    let offset = 0;
+    if (cursor !== "") {
+        const decoded = await decodeCursor(cursor, method, secret);
+        if ("error" in decoded)
+            return { error: decoded.error };
+        offset = decoded.offset;
+    }
+    /* v8 ignore start -- unreachable from public API: HMAC prevents crafting out-of-bounds cursors */
+    if (offset >= tools.length && tools.length > 0)
+        return { error: "invalid or expired cursor" };
+    /* v8 ignore stop */
+    const page = tools.slice(offset, offset + pageSize);
+    const hasMore = offset + pageSize < tools.length;
+    const nextCursor = hasMore
+        ? await encodeCursor(method, offset + pageSize, secret)
+        : undefined;
+    return { nextCursor, tools: page };
+}
+export function registerPaginationHandlers(mcpServer, getAllTools, pageSize, secret) {
+    mcpServer.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+        const cursor = request.params?.cursor;
+        const allTools = await getAllTools();
+        if (cursor === undefined) {
+            return { tools: allTools };
+        }
+        const result = await paginateTools(allTools, "tools/list", pageSize, cursor, secret);
+        if ("error" in result) {
+            throw new McpError(ErrorCode.InvalidParams, result.error);
+        }
+        return { nextCursor: result.nextCursor, tools: result.tools };
+    });
+}
+export function registerTwoPhaseHandlers(mcpServer, getAllTools, pageSize, secret) {
+    const listSummarySchema = z.object({
+        method: z.literal("tools/list_summary"),
+        params: z.object({ cursor: z.string().optional() }).optional(),
+    });
+    mcpServer.server.setRequestHandler(listSummarySchema, async (request) => {
+        const allTools = await getAllTools();
+        const summaries = allTools.map((t) => ({
+            /* v8 ignore next -- both branches tested; v8 misreports ternary in .map() */
+            description: t.description === undefined ? "" : t.description,
+            name: t.name,
+        }));
+        const cursor = request.params?.cursor;
+        if (cursor === undefined) {
+            return { tools: summaries };
+        }
+        const result = await paginateTools(summaries, "tools/list_summary", pageSize, cursor, secret);
+        if ("error" in result) {
+            throw new McpError(ErrorCode.InvalidParams, result.error);
+        }
+        return { nextCursor: result.nextCursor, tools: result.tools };
+    });
+    const describeSchema = z.object({
+        method: z.literal("tools/describe"),
+        params: z.object({ name: z.string().optional() }).optional(),
+    });
+    mcpServer.server.setRequestHandler(describeSchema, async (request) => {
+        const name = request.params?.name;
+        if (!name) {
+            throw new McpError(ErrorCode.InvalidParams, "Invalid params: 'name' is required");
+        }
+        const allTools = await getAllTools();
+        const tool = allTools.find((t) => t.name === name);
+        if (!tool) {
+            throw new McpError(ErrorCode.InvalidParams, `Invalid params: tool '${name}' not found`);
+        }
+        return { tool };
+    });
+}
+//# sourceMappingURL=handlers.js.map

package/dist/mcp/pagination/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/mcp/pagination/handlers.ts"],"names":[],"mappings":"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"}

package/dist/mcp/pagination/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Opt-in pagination for `tools/list` and two-phase tool discovery.
+ *
+ * `pageSize` is required for all pagination features including `twoPhaseDiscovery`.
+ * Must be >= 1. When enabled, `tools/list` without a cursor still returns ALL tools
+ * (backwards-compatible). Cursor pagination activates only when the client sends a cursor.
+ *
+ * `twoPhaseDiscovery` enables non-standard custom MCP methods (`tools/list_summary`,
+ * `tools/describe`). These are NOT part of the MCP spec — only custom agents that
+ * explicitly call these methods will benefit.
+ */
+export type PaginationConfig = {
+    /** Number of tools per page when client sends a cursor. Must be >= 1. */
+    pageSize: number;
+    /** Enable `tools/list_summary` + `tools/describe` custom methods. Default: false. */
+    twoPhaseDiscovery?: boolean;
+};
+export type ToolSummary = {
+    description: string;
+    name: string;
+};
+export type ToolPage<T extends object> = {
+    nextCursor?: string;
+    tools: T[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/pagination/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ,CAAC"}

package/dist/mcp/pagination/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/pagination/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/mcp/pagination/types.ts"],"names":[],"mappings":""}

package/dist/mcp/resources/helpers.d.ts

@@ -0,0 +1,9 @@
+import type { ConvexValidator } from "../types.js";
+import type { ResourceDef } from "./types.js";
+type ResourceOptions = {
+    args?: ConvexValidator;
+    description?: string;
+};
+export declare function resource(ref: unknown, options?: ResourceOptions): ResourceDef;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/mcp/resources/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,QAAQ,CACtB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,GAC5B,WAAW,CAMb"}

package/dist/mcp/resources/helpers.js

@@ -0,0 +1,8 @@
+export function resource(ref, options = {}) {
+    return {
+        args: options.args,
+        description: options.description,
+        ref,
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/mcp/resources/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/mcp/resources/helpers.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,QAAQ,CACtB,GAAY,EACZ,UAA2B,EAAE;IAE7B,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG;KACJ,CAAC;AACJ,CAAC"}