@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/cjs/mcp/index.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveStoreTools = void 0;
+exports.createStoreToolset = createStoreToolset;
+/**
+ * `@cosmoops/connect-sdk/mcp` - your application's store, as an MCP server.
+ *
+ * Server-only: every call goes out through `ConnectClient`, which holds the API
+ * key. The `browser` export condition resolves this entry to a stub, so an
+ * import from client code fails the build rather than shipping the key.
+ *
+ * ## Zero dependencies, on purpose
+ *
+ * This entry does not import `@modelcontextprotocol/sdk`, and the package takes
+ * no dependency on it. `listTools()` and `callTool()` answer in the shapes the
+ * MCP protocol defines, so wiring them to the official server is four lines and
+ * a transport you choose:
+ *
+ * ```ts
+ * const toolset = createStoreToolset({
+ *   collections: STORE_SCHEMA,
+ *   data: connect.data,
+ *   workspaceId: session.workspaceId,
+ *   asUser: session.sessionToken,
+ * })
+ *
+ * server.setRequestHandler(ListToolsRequestSchema, () => toolset.listTools())
+ * server.setRequestHandler(CallToolRequestSchema, (request) =>
+ *   toolset.callTool(request.params.name, request.params.arguments ?? {}),
+ * )
+ * ```
+ *
+ * The alternative - depending on the MCP SDK so this file could return an
+ * `McpServer` - would put a version of it in every install of this package,
+ * including the ones that never touch MCP, and pin partners to whichever
+ * version shipped here. The protocol shapes are stable and small; the coupling
+ * would not be.
+ *
+ * ## One toolset per session
+ *
+ * `asUser` is an end user's Connect session token, and Connect checks each
+ * collection's declared permission against that member's live roles. A toolset
+ * is therefore scoped to one signed-in user - build it per request from
+ * `getConnectSession()`, or pass a function for `asUser` if the surrounding
+ * server outlives a session.
+ */
+var tools_js_1 = require("./tools.js");
+Object.defineProperty(exports, "deriveStoreTools", { enumerable: true, get: function () { return tools_js_1.deriveStoreTools; } });
+const tools_js_2 = require("./tools.js");
+/**
+ * A refusal is a result, not a thrown error.
+ *
+ * MCP draws that distinction deliberately: a protocol error is a fault the
+ * model cannot act on, while `isError: true` is a tool result the model reads
+ * and can respond to. An unservable query and a permission Connect refused are
+ * both things a model should see and adapt to - naming a field it may not
+ * filter on, or telling the user it cannot reach that data - so they come back
+ * as content rather than as a transport failure.
+ */
+function asResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function createStoreToolset(options) {
+    const tools = (0, tools_js_2.deriveStoreTools)(options);
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    return {
+        tools,
+        listTools: () => ({
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
+            })),
+        }),
+        async callTool(name, args) {
+            const tool = byName.get(name);
+            if (!tool) {
+                return asResult(`No such tool: "${name}". Available: ${[...byName.keys()].join(", ")}.`, true);
+            }
+            try {
+                return asResult(JSON.stringify(await tool.execute(args), null, 2));
+            }
+            catch (error) {
+                return asResult(error instanceof Error ? error.message : String(error), true);
+            }
+        },
+    };
+}

package/dist/cjs/mcp/tools.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveStoreTools = deriveStoreTools;
+const store_js_1 = require("../store.js");
+const store_schema_js_1 = require("../store-schema.js");
+/**
+ * The store, as tools a model can call.
+ *
+ * ## Why a declaration is enough
+ *
+ * `Application.storeSchema` already answers every question a tool definition
+ * asks. It names the collection and says what it holds (`description`), which
+ * fields may be filtered or ordered on (`queryableFields`), which query shapes
+ * the database can actually serve (`indexes`), and whether the collection
+ * refuses everything but a create (`appendOnly`). Writing those tools by hand
+ * means maintaining a second copy of all of it, and the copy is wrong the first
+ * time a filter is added to a screen.
+ *
+ * So they are derived. Adding a queryable field to the declaration and
+ * re-seeding widens the tools on the next boot, with no tool code to touch.
+ *
+ * ## What this is not
+ *
+ * **It is not an authorization boundary.** Connect is. Every call here goes out
+ * with the end user's session token (`asUser`), and Connect resolves it to a
+ * member and checks the collection's declared `readPermission`/`writePermission`
+ * against that member's live roles - so a tool can never reach further than the
+ * person on whose behalf it runs, and a permission revoked in the console is
+ * gone from the next call. The shaping done here - omitting write tools for an
+ * `appendOnly` collection, refusing an unservable query - is there so a model
+ * fails fast and legibly, not because it protects anything. Connect refuses the
+ * same things independently.
+ *
+ * **There is no `scan` tool, deliberately.** `data.scan` reads a collection
+ * across every workspace and, for exactly that reason, takes no `asUser` - a
+ * workspace admin is an admin of their own workspace and not of a partner's
+ * other customers. A toolset that runs on behalf of a signed-in user therefore
+ * has nothing to derive from `crossWorkspace`, and generating a scan tool would
+ * mean running that one call under the application's own key while every tool
+ * beside it ran under the user's. Cross-tenant reads belong in a back-office
+ * surface with its own gate.
+ *
+ * **`kv` collections are skipped.** The key/value store is addressed by
+ * namespace and key rather than queried, so it derives nothing from
+ * `queryableFields` or `indexes` and the tools it wants are a different shape.
+ *
+ * ## Deriving over every collection is usually wrong
+ *
+ * Measured on the two reference applications: club's fifteen collections yield
+ * 45 read tools and 88 with writes on; CRM's seven yield 21 and 40. Those are
+ * whole-catalogue numbers, and a model offered them chooses worse than one
+ * offered a handful - the ceiling is tool-choice accuracy, which degrades well
+ * before a context window fills. Connect's own assistant bounds each turn to
+ * the capabilities the current screen promotes for exactly this reason.
+ *
+ * So `include` is the normal way to call this, not a refinement: name the
+ * collections the surface at hand is about. Nothing here enforces a cap,
+ * because the right number depends on the surface and a silent truncation
+ * would be worse than a large list.
+ */
+/** Connect's own ceilings, mirrored so a tool can describe them before the call. */
+const MAX_QUERY_LIMIT = 200;
+const DEFAULT_QUERY_LIMIT = 50;
+const QUERY_OPERATORS = [
+    "==",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "in",
+    "not-in",
+    "array-contains",
+];
+/**
+ * MCP tool names are `[a-z0-9_-]`; collection names additionally allow capitals.
+ * Lowercasing and folding `-` to `_` is what makes `dues-demands` addressable,
+ * and is also how two collections can collide - which is caught, not resolved,
+ * because silently renaming one would make the tool a model calls depend on
+ * declaration order.
+ */
+function toolBaseName(collection) {
+    return collection.toLowerCase().replace(/-/g, "_");
+}
+/**
+ * How many index shapes are worth spelling out before the listing costs more
+ * than it teaches.
+ *
+ * A real declaration is not a handful. club's ledger declares around forty
+ * shapes, and writing all of them into both the list and aggregate tools was
+ * most of a 79 KB `tools/list` on its own - paid on every turn, for a listing a
+ * model reads poorly anyway. Past this many, the description states the rule
+ * and leaves the specifics to the refusal, which names the exact index a
+ * rejected query needed and costs no round trip to get.
+ */
+const MAX_DESCRIBED_INDEXES = 12;
+/** The servable query shapes, spelled out for the model rather than left to be discovered. */
+function describeIndexes(collection) {
+    if (collection.indexes.length === 0) {
+        return "No composite indexes are declared, so a query may use at most one filter, ordered only by that same field.";
+    }
+    const preamble = "A query using more than one filter, or ordering by a field it does not filter on, must match a declared composite index";
+    if (collection.indexes.length > MAX_DESCRIBED_INDEXES) {
+        return `${preamble}. ${collection.indexes.length} are declared - too many to list here. Issue the query you want: if no index covers it you get back the exact index it would need, before anything is read.`;
+    }
+    const shapes = collection.indexes.map((index) => `  - ${(0, store_js_1.storeIndexSignature)(index.fields)}`).join("\n");
+    return `${preamble}:\n${shapes}`;
+}
+function readDescription(collection, verb) {
+    const head = `${verb} ${collection.name}. ${collection.description}`;
+    // Nothing declared queryable means the collection can only be read whole -
+    // which is the right shape for the one-document-per-key collections (a
+    // settings block, a counter), and saying so beats offering a filter argument
+    // that has no legal value.
+    if (collection.queryableFields.length === 0) {
+        return `${head}\n\nThis collection declares no queryable fields, so it cannot be filtered or ordered - it is read whole.`;
+    }
+    return [head, "", `Queryable fields: ${collection.queryableFields.join(", ")}.`, describeIndexes(collection)].join("\n");
+}
+const filtersSchema = (collection) => ({
+    type: "array",
+    description: "Filters, ANDed together.",
+    items: {
+        type: "object",
+        properties: {
+            field: { type: "string", enum: [...collection.queryableFields] },
+            op: { type: "string", enum: QUERY_OPERATORS },
+            value: {
+                description: "The value to compare against. Dates are ISO-8601 strings; a calendar day is YYYY-MM-DD.",
+            },
+        },
+        required: ["field", "op", "value"],
+        additionalProperties: false,
+    },
+});
+/**
+ * Documents come back with Connect's `_`-prefixed bookkeeping on them, and
+ * every write refuses those fields. Saying so on the write tools is what stops
+ * a model reading a document, editing one field and posting the whole thing
+ * back - which fails, correctly, but wastes a turn learning it.
+ */
+const WRITE_DATA_NOTE = "Fields beginning with `_` are written by Connect and are refused here - strip `_createdAt`, `_updatedAt`, `_createdBy`, `_updatedBy` and `_updateTime` from a document you read before writing it back.";
+function buildReadTools(collection, base, call, data, workspaceId) {
+    return [
+        {
+            name: `${base}_get`,
+            title: `Get one ${collection.name} document`,
+            description: `Read one document from ${collection.name} by id. ${collection.description}`,
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string", description: "The document id." } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: (args) => call((asUser) => data.get({ workspaceId, collection: collection.name, id: String(args.id), asUser })),
+        },
+        {
+            name: `${base}_list`,
+            title: `List ${collection.name}`,
+            description: readDescription(collection, "List documents in"),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ...(collection.queryableFields.length > 0
+                        ? {
+                            filters: filtersSchema(collection),
+                            orderBy: {
+                                type: "object",
+                                properties: {
+                                    field: { type: "string", enum: [...collection.queryableFields] },
+                                    direction: { type: "string", enum: ["asc", "desc"] },
+                                },
+                                required: ["field", "direction"],
+                                additionalProperties: false,
+                            },
+                        }
+                        : {}),
+                    limit: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: MAX_QUERY_LIMIT,
+                        description: `Page size. Defaults to ${DEFAULT_QUERY_LIMIT}, caps at ${MAX_QUERY_LIMIT}.`,
+                    },
+                    cursor: {
+                        type: "string",
+                        description: "The previous page's nextCursor. A null nextCursor is the end of the collection.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: async (args) => {
+                const filters = args.filters ?? [];
+                const orderBy = args.orderBy ?? null;
+                const rejection = (0, store_schema_js_1.describeQueryRejection)(collection, { filters, orderBy });
+                if (rejection)
+                    throw new Error(rejection);
+                return call((asUser) => data.query({
+                    workspaceId,
+                    collection: collection.name,
+                    filters,
+                    orderBy: orderBy ?? undefined,
+                    limit: args.limit,
+                    cursor: args.cursor ?? null,
+                    asUser,
+                }));
+            },
+        },
+        {
+            name: `${base}_aggregate`,
+            title: `Count, sum or average ${collection.name}`,
+            description: [
+                readDescription(collection, "Aggregate"),
+                "",
+                "Counts, sums and averages are computed in the database rather than by reading rows back, so prefer this over listing a collection to add it up. A sum or average over nothing answers null, not 0.",
+            ].join("\n"),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    aggregations: {
+                        type: "array",
+                        minItems: 1,
+                        items: {
+                            type: "object",
+                            properties: {
+                                op: {
+                                    type: "string",
+                                    // `sum` and `avg` need a field, and every field they could
+                                    // name must be queryable - so a collection declaring none can
+                                    // only be counted.
+                                    enum: collection.queryableFields.length > 0 ? ["count", "sum", "avg"] : ["count"],
+                                },
+                                ...(collection.queryableFields.length > 0
+                                    ? {
+                                        field: {
+                                            type: "string",
+                                            enum: [...collection.queryableFields],
+                                            description: "Required for sum and avg; omitted for count, which counts documents.",
+                                        },
+                                    }
+                                    : {}),
+                                alias: { type: "string", description: "What the result is keyed by." },
+                            },
+                            required: ["op", "alias"],
+                            additionalProperties: false,
+                        },
+                    },
+                    ...(collection.queryableFields.length > 0 ? { filters: filtersSchema(collection) } : {}),
+                },
+                required: ["aggregations"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+            execute: async (args) => {
+                const filters = args.filters ?? [];
+                // An aggregation has no ordering, so the index it needs is the one its
+                // filters need - the same check `list` makes, minus the sort.
+                const rejection = (0, store_schema_js_1.describeQueryRejection)(collection, { filters, orderBy: null });
+                if (rejection)
+                    throw new Error(rejection);
+                return call((asUser) => data.aggregate({
+                    workspaceId,
+                    collection: collection.name,
+                    aggregations: args.aggregations,
+                    filters,
+                    asUser,
+                }));
+            },
+        },
+    ];
+}
+function buildWriteTools(collection, base, call, data, workspaceId, writes) {
+    if (writes === "none")
+        return [];
+    const tools = [
+        {
+            name: `${base}_create`,
+            title: `Create a ${collection.name} document`,
+            description: `Create a document in ${collection.name}. ${collection.description}\n\n${WRITE_DATA_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    data: { type: "object", description: "The document's fields." },
+                    id: { type: "string", description: "Choose the id, or omit for an allocated one. An existing id is a conflict." },
+                },
+                required: ["data"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+            execute: (args) => call((asUser) => data.create({
+                workspaceId,
+                collection: collection.name,
+                data: args.data,
+                id: args.id,
+                asUser,
+            })),
+        },
+    ];
+    // An append-only collection refuses a merge and a delete for every caller,
+    // this application's own key included, so deriving those tools would offer a
+    // model two calls that can only ever fail.
+    if (writes === "all" && !collection.appendOnly) {
+        tools.push({
+            name: `${base}_update`,
+            title: `Update a ${collection.name} document`,
+            description: `Merge top-level fields into an existing ${collection.name} document. Fields not named are left alone.\n\n${WRITE_DATA_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    data: { type: "object", description: "The fields to merge." },
+                },
+                required: ["id", "data"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+            execute: (args) => call((asUser) => data.update({
+                workspaceId,
+                collection: collection.name,
+                id: String(args.id),
+                data: args.data,
+                asUser,
+            })),
+        }, {
+            name: `${base}_delete`,
+            title: `Delete a ${collection.name} document`,
+            description: `Delete one document from ${collection.name}. Idempotent - deleting a document that is not there succeeds.`,
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" } },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+            execute: (args) => call((asUser) => data
+                .delete({ workspaceId, collection: collection.name, id: String(args.id), asUser })
+                .then(() => ({ deleted: String(args.id) }))),
+        });
+    }
+    return tools;
+}
+/** Every tool one declaration yields, in a stable order. */
+function deriveStoreTools(options) {
+    const { collections, data, workspaceId, writes = "none", prefix = "", include } = options;
+    const resolveUser = typeof options.asUser === "function" ? options.asUser : () => options.asUser;
+    const call = async (run) => run(await resolveUser());
+    const wanted = include ? new Set(include) : null;
+    const selected = collections.filter((collection) => collection.kind === "data" && (!wanted || wanted.has(collection.name)));
+    if (wanted) {
+        const declared = new Set(collections.map((collection) => collection.name));
+        const missing = [...wanted].filter((name) => !declared.has(name));
+        if (missing.length > 0) {
+            throw new Error(`No declaration for ${missing.join(", ")}. Declared collections: ${[...declared].join(", ")}.`);
+        }
+    }
+    const byBaseName = new Map();
+    const tools = [];
+    for (const collection of selected) {
+        const base = `${prefix}${toolBaseName(collection.name)}`;
+        const clash = byBaseName.get(base);
+        if (clash) {
+            throw new Error(`"${collection.name}" and "${clash}" both derive the tool prefix "${base}". Rename one, or give one its own toolset with a prefix.`);
+        }
+        byBaseName.set(base, collection.name);
+        tools.push(...buildReadTools(collection, base, call, data, workspaceId), ...buildWriteTools(collection, base, call, data, workspaceId, writes));
+    }
+    return tools;
+}

package/dist/cjs/next/index.js

@@ -82,7 +82,7 @@ const handler_js_1 = require("../server/handler.js");
  * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
- * application's Integration tab. That is the only step this cannot do for you.
+ * application's Connect client section. That is the only step this cannot do for you.
  *
  * No `next.config.ts` changes needed either, including `transpilePackages`:
  * `dist/` is already ES2022 with `"use client"` hoisted to the top of every
@@ -317,7 +317,7 @@ async function getConnectSession(request, options = {}) {
  * A thin wrapper, not a framework of its own - reach for `getConnectSession`
  * plus your own check when "not signed in" isn't "redirect to sign-in"
  * (an API route returning 401, say). Role and entitlement checks stay
- * outside this function on purpose: `session.applicationRole.granted` and
+ * outside this function on purpose: `session.permissions` and
  * `connect.entitlements.*` are one line each on top of the session this
  * already gives you, and where that line redirects (a plans page, a
  * "forbidden" screen) is a decision only your app can make - see

package/dist/cjs/server/client.js

@@ -4,6 +4,9 @@ exports.SDK_VERSION = exports.ConnectClient = exports.DEFAULT_BASE_URL = void 0;
 const access_js_1 = require("./resources/access.js");
 const apps_js_1 = require("./resources/apps.js");
 const ai_js_1 = require("./resources/ai.js");
+const data_js_1 = require("./resources/data.js");
+const workspaces_js_1 = require("./resources/workspaces.js");
+const kv_js_1 = require("./resources/kv.js");
 const billing_js_1 = require("./resources/billing.js");
 const drive_js_1 = require("./resources/drive.js");
 const entitlements_js_1 = require("./resources/entitlements.js");
@@ -13,6 +16,7 @@ const logs_js_1 = require("./resources/logs.js");
 const analytics_js_1 = require("./resources/analytics.js");
 const otp_js_1 = require("./resources/otp.js");
 const sessions_js_1 = require("./resources/sessions.js");
+const platform_js_1 = require("./resources/platform.js");
 exports.DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -77,6 +81,10 @@ class ConnectClient {
     drive;
     /** RAG chat and structured extraction. */
     ai;
+    /** Your application's own document store - see `DataResource`. */
+    data;
+    /** Your application's key/value store - see `KvResource`. */
+    kv;
     /** WhatsApp/SMS phone verification. */
     otp;
     /** Feature events into the Console's audit log, filterable to your application. */
@@ -87,10 +95,20 @@ class ConnectClient {
     sessions;
     /** Composio-hosted third-party connections (Google Calendar, Slack, ...) a workspace has connected. */
     integrations;
+    /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
+    workspaces;
+    /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
+    platform;
+    /**
+     * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
+     * store route and nothing else. See `storePassthrough`.
+     * @internal
+     */
+    storeRelay;
     constructor(options) {
         assertNotBrowser();
         if (!options.apiKey) {
-            throw new TypeError("ConnectClient requires `apiKey` - the plaintext shown once in the Integration tab.");
+            throw new TypeError("ConnectClient requires `apiKey` - the plaintext shown once in the Connect client section.");
         }
         const appBaseUrl = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
         const transport = {
@@ -110,13 +128,18 @@ class ConnectClient {
         this.billing = new billing_js_1.BillingResource(transport);
         this.drive = new drive_js_1.DriveResource(transport);
         this.ai = new ai_js_1.AiResource(transport);
+        this.data = new data_js_1.DataResource(transport);
+        this.kv = new kv_js_1.KvResource(transport);
         this.otp = new otp_js_1.OtpResource(transport);
         this.logs = new logs_js_1.LogsResource(transport);
         this.analytics = new analytics_js_1.AnalyticsResource(transport);
         this.sessions = new sessions_js_1.SessionsResource(transport, options.clientId ?? null);
         this.integrations = new integrations_js_1.IntegrationsResource(transport);
+        this.workspaces = new workspaces_js_1.WorkspacesResource(transport);
+        this.platform = new platform_js_1.PlatformResource(transport);
+        this.storeRelay = (spec) => (0, data_js_1.storePassthrough)(transport, spec);
     }
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.9.0";
+exports.SDK_VERSION = "0.16.0";