@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/esm/mcp/tools.js

@@ -0,0 +1,366 @@
+import { storeIndexSignature } from "../store.js";
+import { describeQueryRejection } from "../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) => `  - ${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 = 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 = 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. */
+export 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/esm/next/index.js

@@ -38,7 +38,7 @@ import { createConnectHandler } from "../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
@@ -287,7 +287,7 @@ export 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/esm/server/client.js

@@ -1,6 +1,9 @@
 import { AccessResource } from "./resources/access.js";
 import { AppsResource } from "./resources/apps.js";
 import { AiResource } from "./resources/ai.js";
+import { DataResource, storePassthrough } from "./resources/data.js";
+import { WorkspacesResource } from "./resources/workspaces.js";
+import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
 import { EntitlementsResource } from "./resources/entitlements.js";
@@ -10,6 +13,7 @@ import { LogsResource } from "./resources/logs.js";
 import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
+import { PlatformResource } from "./resources/platform.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -74,6 +78,10 @@ export 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. */
@@ -84,10 +92,20 @@ export 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 ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         const transport = {
@@ -107,12 +125,17 @@ export class ConnectClient {
         this.billing = new BillingResource(transport);
         this.drive = new DriveResource(transport);
         this.ai = new AiResource(transport);
+        this.data = new DataResource(transport);
+        this.kv = new KvResource(transport);
         this.otp = new OtpResource(transport);
         this.logs = new LogsResource(transport);
         this.analytics = new AnalyticsResource(transport);
         this.sessions = new SessionsResource(transport, options.clientId ?? null);
         this.integrations = new IntegrationsResource(transport);
+        this.workspaces = new WorkspacesResource(transport);
+        this.platform = new PlatformResource(transport);
+        this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.9.0";
+export const SDK_VERSION = "0.16.0";