@cosmoops/connect-sdk 0.15.0 → 0.16.0

package/dist/esm/store-schema.js

@@ -0,0 +1,62 @@
+import { storeIndexFor, storeIndexSignature } from "./store.js";
+/**
+ * The signature of an index scanned backwards.
+ *
+ * Firestore serves a query from an index in either direction as long as *every*
+ * ordered field is flipped, so `[a asc, b desc]` also answers `[a desc, b asc]`.
+ * Mirrored by Connect's own `indexCovers`; kept in step with it deliberately,
+ * because a check here that is stricter than the server's would refuse queries
+ * that actually work, and a looser one would promise queries that do not.
+ */
+function reversedIndexSignature(fields) {
+    return storeIndexSignature(fields.map((entry) => entry.direction === "array-contains"
+        ? entry
+        : { field: entry.field, direction: entry.direction === "asc" ? "desc" : "asc" }));
+}
+/** Whether one of `declared` can serve a query needing exactly `required`. */
+export function storeIndexCovers(declared, required) {
+    const wanted = storeIndexSignature(required);
+    const mirrored = reversedIndexSignature(required);
+    return declared.some((index) => {
+        const signature = storeIndexSignature(index.fields);
+        return signature === wanted || signature === mirrored;
+    });
+}
+/**
+ * Why a collection cannot serve a query, in words a caller can act on - or
+ * `null` when it can.
+ *
+ * Runs the same two rules Connect runs, in the same order: every field must be
+ * declared queryable, and the shape must be inside an automatic single-field
+ * index or covered by a declared composite one. Checking here rather than
+ * letting the call fail is not about saving a round trip - it is so the refusal
+ * can name the index to declare while the caller still has the query in hand.
+ */
+export function describeQueryRejection(collection, query) {
+    const filters = query.filters ?? [];
+    const orderBy = query.orderBy ?? null;
+    const queryable = new Set(collection.queryableFields);
+    const undeclared = [
+        ...new Set([...filters.map((filter) => filter.field), ...(orderBy ? [orderBy.field] : [])]),
+    ].filter((field) => !queryable.has(field));
+    if (undeclared.length > 0) {
+        return `"${collection.name}" cannot be filtered or ordered on ${undeclared.join(", ")}. Queryable fields are: ${collection.queryableFields.join(", ")}.`;
+    }
+    let required;
+    try {
+        required = storeIndexFor({ filters, orderBy });
+    }
+    catch (error) {
+        // Firestore cannot serve the shape at all - two `array-contains`, ranges
+        // over two fields, a range ordered by another field. No index would help,
+        // so the thrown message is the whole answer.
+        return error instanceof Error ? error.message : String(error);
+    }
+    if (!required)
+        return null;
+    if (storeIndexCovers(collection.indexes, required))
+        return null;
+    return `"${collection.name}" has no index for this query. It would need one over ${required
+        .map((entry) => `${entry.field} (${entry.direction})`)
+        .join(", ")}.`;
+}

package/dist/types/client/components/ai-screens.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectScreen } from "../../types.js";
+/**
+ * The declared screen a live path is on, or `null` if none matches.
+ *
+ * `null` is a normal outcome, not an error: an application need only describe
+ * the screens it wants the assistant to know about, and an undescribed one
+ * simply costs the assistant its orientation rather than costing the user an
+ * answer.
+ */
+export declare function matchConnectScreen(screens: readonly ConnectScreen[], path: string): ConnectScreen | null;
+/**
+ * Whether an href the model produced may be rendered as a link.
+ *
+ * Same reasoning as Connect's own `showActions` check, and the same conclusion:
+ * an assistant that can emit an arbitrary URL is a redirect the model can be
+ * talked into, and retrieved content shares a context window with its
+ * tool-calling authority. So a link is drawn only when it resolves to a screen
+ * *your application declared* - which makes an external destination structurally
+ * impossible, since no route pattern has a scheme or a host.
+ *
+ * The protocol-relative form is refused separately: `//evil.example.com` has no
+ * scheme for a path matcher to trip over, and would otherwise reach an anchor
+ * as an absolute destination.
+ */
+export declare function isLinkableConnectScreen(screens: readonly ConnectScreen[], href: string): boolean;

package/dist/types/client/components/ai-widgets.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { AiChartInput, AiDetailsInput, AiMetricsInput, AiSourcesInput, AiStepsInput, AiTableInput, AiTimelineInput } from "../../types.js";
+import type { AiChartInput, AiDetailsInput, AiMetricsInput, AiSourcesInput, AiStepsInput, AiActionsInput, AiTableInput, AiTimelineInput, ConnectScreen } from "../../types.js";
 /**
  * `showTable`. Sorting and CSV are what a table is *for* - once an answer is
  * tabular the next thing anyone wants is to reorder it or take it elsewhere,
@@ -40,3 +40,36 @@ export declare function AiSteps({ title, steps, renderDetail, }: Readonly<AiStep
  * without is still a named row - never a marker with nothing behind it.
  */
 export declare function AiSources({ sources }: Readonly<AiSourcesInput>): import("react").JSX.Element;
+/**
+ * Where to go next, as links into *your* application.
+ *
+ * ## Why links and not navigation
+ *
+ * The obvious version of "the assistant can act" moves the user. It is also the
+ * version that breaks the property the whole design rests on: nothing happens
+ * without a click. Retrieved content shares a context window with the model's
+ * tool-calling authority, so an auto-navigate is a redirect primitive that
+ * content can reach. A link cannot be, and loses nothing - the user was going
+ * to click something anyway.
+ *
+ * ## Why every href is checked against your declared screens
+ *
+ * The model can emit any string. Only your application knows which strings are
+ * real routes, which is why `screens` is a prop rather than something Connect
+ * could supply. A link that does not resolve is *dropped* rather than rendered
+ * broken - the prose around it still stands, so a missing link reads as terse
+ * rather than wrong.
+ *
+ * `renderLink` is how this stays router-agnostic. Given one, a link is your
+ * framework's - a Next `<Link>`, a TanStack `<Link>` - and navigation is a
+ * client transition. Without one it falls back to an anchor, which works
+ * everywhere and costs a document load.
+ */
+export declare function AiActions({ title, actions, screens, renderLink, }: Readonly<AiActionsInput & {
+    screens: readonly ConnectScreen[];
+    renderLink?: (props: {
+        href: string;
+        className: string;
+        children: ReactNode;
+    }) => ReactNode;
+}>): import("react").JSX.Element | null;

package/dist/types/client/components/ask-ai.d.ts

@@ -1,5 +1,51 @@
+import { type ReactNode } from "react";
 import { type StreamdownProps } from "streamdown";
+import type { ConnectScreen } from "../../types.js";
 export interface ConnectAskAiProps {
+    /**
+     * The screens in your application, described for the assistant.
+     *
+     * Without these it answers from general knowledge about software, because
+     * Connect has no idea what your product is - see `ConnectScreen`. With them,
+     * "what can I do here?" answers in your own words, the empty panel offers
+     * your own opening questions, and `showActions` can link into your routes.
+     *
+     * Prose and links only: Connect never uses them to decide what anyone may do,
+     * and never executes anything on your behalf.
+     */
+    screens?: readonly ConnectScreen[];
+    /**
+     * The route the user is currently on.
+     *
+     * **Usually omit this.** Left unset, the panel resolves the live path itself
+     * through `useActivePath`, which reads `location.pathname` from a
+     * `useSyncExternalStore` whose server snapshot is empty - so it works inside
+     * a shared App Shell, where `usePathname()` is refused outright
+     * (`CLIENT_HOOK_DYNAMIC`) because URL data cannot live in an artifact shared
+     * across URLs. That is the same reason `ConnectAppShell` recommends leaving
+     * its own `activePath` unset in a Next app.
+     *
+     * Pass it only where your router's path is not `location.pathname` - a
+     * hash router, or a panel embedded under a basePath your routes do not
+     * include.
+     */
+    activePath?: string;
+    /**
+     * Renders an action link with your router, so following one is a client
+     * transition rather than a document load. Omit it and links are plain
+     * anchors, which work everywhere.
+     *
+     * ```tsx
+     * renderLink={({ href, className, children }) => (
+     *   <Link href={href} className={className}>{children}</Link>
+     * )}
+     * ```
+     */
+    renderLink?: (props: {
+        href: string;
+        className: string;
+        children: ReactNode;
+    }) => ReactNode;
     /** Panel heading. Defaults to `"Ask AI"`. */
     title?: string;
     /** Byline over each assistant turn. Defaults to `"Assistant"`. */
@@ -70,4 +116,4 @@ export interface ConnectAskAiProps {
  * Neither is something the browser can discover, so both surface as a message
  * in the panel rather than as a hidden button.
  */
-export declare function ConnectAskAi({ title, assistantName, placeholder, hint, defaultOpen, markdownPlugins, }: ConnectAskAiProps): import("react").JSX.Element | null;
+export declare function ConnectAskAi({ title, assistantName, placeholder, hint, defaultOpen, markdownPlugins, screens, activePath, renderLink, }: ConnectAskAiProps): import("react").JSX.Element | null;

package/dist/types/client/index.d.ts

@@ -41,6 +41,8 @@ export type { ConnectSidebarNavProps, ConnectSideNavProps } from "./components/s
 export { useActivePath } from "./use-active-path.js";
 export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, filterNavForAudience, } from "./components/nav.js";
 export type { ConnectNav, ConnectNavItem, ConnectNavSection, ConnectNavLinkProps, ConnectLinkRenderer, } from "./components/nav.js";
+export type { ConnectScreen } from "../types.js";
+export { matchConnectScreen, isLinkableConnectScreen, } from "./components/ai-screens.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 export type { ConnectAppsGridProps } from "./components/apps-grid.js";
 export { ConnectAskAi } from "./components/ask-ai.js";

package/dist/types/index.d.ts

@@ -10,10 +10,14 @@
  *   Holds the API key. Never import this from browser code.
  * - `@cosmoops/connect-sdk/client` - React components and hooks. Talks to your
  *   own origin only.
+ * - `@cosmoops/connect-sdk/mcp` - your store's declaration, derived into MCP
+ *   tools. Holds the API key; never import this from browser code.
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
 export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";
 export type { StoreIndexDirection, StoreIndexField } from "./store.js";
+export { describeQueryRejection, storeIndexCovers } from "./store-schema.js";
+export type { StoreCollectionDeclaration } from "./store-schema.js";
 export type { WirePlanFeature } from "./helpers.js";
 export type * from "./types.js";

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

@@ -0,0 +1,74 @@
+/**
+ * `@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.
+ */
+export { deriveStoreTools } from "./tools.js";
+export type { JsonSchema, StoreDataPort, StoreTool, StoreToolWrites, StoreToolsetOptions, } from "./tools.js";
+import { type StoreTool, type StoreToolsetOptions } from "./tools.js";
+/** One entry of an MCP `tools/list` response. */
+export interface McpToolDescriptor {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+}
+/** An MCP `tools/call` result. */
+export interface McpToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export interface StoreToolset {
+    /** The derived tools, if you would rather register them yourself. */
+    readonly tools: readonly StoreTool[];
+    listTools(): {
+        tools: McpToolDescriptor[];
+    };
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+}
+export declare function createStoreToolset(options: StoreToolsetOptions): StoreToolset;

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

@@ -0,0 +1,107 @@
+import type { StoreAggregation, StoreDocument, StoreOrderBy, StoreQueryFilter } from "../types.js";
+import { type StoreCollectionDeclaration } from "../store-schema.js";
+/** A JSON Schema object, as the MCP `tools/list` response carries it. */
+export type JsonSchema = Record<string, unknown>;
+/**
+ * One derived tool: the wire definition, and the call behind it.
+ *
+ * Shaped so `listTools`/`callTool` can be answered without this module knowing
+ * what transport is in front of it - see the note on `createStoreToolset`.
+ */
+export interface StoreTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    execute(args: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * The subset of `ConnectClient["data"]` a toolset uses.
+ *
+ * Structural rather than the concrete class so this module pulls in neither the
+ * transport nor the key-holding client, and so a test can pass a recording
+ * double without a network seam of its own.
+ */
+export interface StoreDataPort {
+    get(input: {
+        workspaceId?: string;
+        collection: string;
+        id: string;
+        asUser?: string;
+    }): Promise<StoreDocument>;
+    query(input: {
+        workspaceId?: string;
+        collection: string;
+        filters?: StoreQueryFilter[];
+        orderBy?: StoreOrderBy;
+        limit?: number;
+        cursor?: string | null;
+        asUser?: string;
+    }): Promise<{
+        items: StoreDocument[];
+        nextCursor: string | null;
+    }>;
+    aggregate(input: {
+        workspaceId?: string;
+        collection: string;
+        aggregations: StoreAggregation[];
+        filters?: StoreQueryFilter[];
+        asUser?: string;
+    }): Promise<{
+        values: Record<string, number | null>;
+    }>;
+    create(input: {
+        workspaceId?: string;
+        collection: string;
+        data: Record<string, unknown>;
+        id?: string;
+        asUser?: string;
+    }): Promise<StoreDocument>;
+    update(input: {
+        workspaceId?: string;
+        collection: string;
+        id: string;
+        data: Record<string, unknown>;
+        asUser?: string;
+    }): Promise<StoreDocument>;
+    delete(input: {
+        workspaceId?: string;
+        collection: string;
+        id: string;
+        asUser?: string;
+    }): Promise<void>;
+}
+/**
+ * How much of the write surface to derive.
+ *
+ * Defaults to `"none"`. A toolset is usually handed to a model driving somebody
+ * else's conversation, and the blast radius of a derived `delete` on every
+ * collection is not something to acquire by default - opting in is one word,
+ * and discovering it by accident is not recoverable.
+ */
+export type StoreToolWrites = "none" | "create" | "all";
+export interface StoreToolsetOptions {
+    /** The application's own declaration - the same array seeded to `Application.storeSchema`. */
+    collections: readonly StoreCollectionDeclaration[];
+    data: StoreDataPort;
+    /**
+     * The end user's Connect session token. Every call is made on their behalf.
+     *
+     * A function is resolved per call, for a toolset outliving one session.
+     */
+    asUser: string | (() => string | Promise<string>);
+    /** Omit for an application-scoped collection; required for a workspace-scoped one. */
+    workspaceId?: string;
+    writes?: StoreToolWrites;
+    /** Prepended to every tool name, for a server mounting more than one source. */
+    prefix?: string;
+    /** Collections to derive from. Defaults to every declared `data` collection. */
+    include?: readonly string[];
+}
+/** Every tool one declaration yields, in a stable order. */
+export declare function deriveStoreTools(options: StoreToolsetOptions): StoreTool[];

package/dist/types/server/client.d.ts

@@ -109,4 +109,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.14.0";
+export declare const SDK_VERSION = "0.16.0";

package/dist/types/server/resources/ai.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ChatMessage } from "../../types.js";
+import type { ChatMessage, ConnectScreen } from "../../types.js";
 /**
  * RAG chat and structured extraction against a workspace's data.
  *
@@ -21,6 +21,16 @@ export declare class AiResource {
         workspaceId: string;
         messages: ChatMessage[];
         asUser?: string;
+        /**
+         * Your application's screens, so the assistant answers in your product's
+         * words and can link into it - see `ConnectScreen`. Prose and links only:
+         * Connect never uses these to decide what anyone may do.
+         */
+        screens?: readonly ConnectScreen[] | unknown;
+        /** Where the user is, as `{ pathname }`. Matched against `screens`. */
+        screenContext?: {
+            pathname?: string;
+        } | unknown;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<Response>;

package/dist/types/store-schema.d.ts

@@ -0,0 +1,52 @@
+import type { StoreQueryFilter, StoreOrderBy } from "./types.js";
+import { type StoreIndexField } from "./store.js";
+/**
+ * One collection as an application declares it, and the helpers that read a
+ * declaration back.
+ *
+ * The declaration is the same shape Connect stores on `Application.storeSchema`
+ * and the same one `scripts/seed-*-application.ts` writes there, so an app that
+ * builds its schema from its own query matrix can hand the result straight to
+ * anything here without a second type of its own. Connect remains the
+ * authority - this is a local copy of what was declared, useful for deriving
+ * things *from* the declaration, never for deciding access.
+ *
+ * Isomorphic and dependency-free, like the rest of the root entry.
+ */
+export interface StoreCollectionDeclaration {
+    name: string;
+    kind: "data" | "kv";
+    scope: "workspace" | "application";
+    /** Prose. Connect shows it in the Console; `deriveStoreTools` gives it to a model. */
+    description: string;
+    /** The per-user permission Connect checks when a call carries `asUser`. `null` means any member. */
+    readPermission: string | null;
+    writePermission: string | null;
+    /** Whether `data.scan` may read this collection across every workspace. */
+    crossWorkspace: boolean;
+    /** Create-only. Connect refuses a replace, a merge or a delete for every caller. */
+    appendOnly: boolean;
+    /** Nothing may be filtered, ordered or aggregated on a field not listed. */
+    queryableFields: string[];
+    indexes: {
+        fields: StoreIndexField[];
+    }[];
+}
+/** Whether one of `declared` can serve a query needing exactly `required`. */
+export declare function storeIndexCovers(declared: readonly {
+    fields: StoreIndexField[];
+}[], required: readonly StoreIndexField[]): boolean;
+/**
+ * Why a collection cannot serve a query, in words a caller can act on - or
+ * `null` when it can.
+ *
+ * Runs the same two rules Connect runs, in the same order: every field must be
+ * declared queryable, and the shape must be inside an automatic single-field
+ * index or covered by a declared composite one. Checking here rather than
+ * letting the call fail is not about saving a round trip - it is so the refusal
+ * can name the index to declare while the caller still has the query in hand.
+ */
+export declare function describeQueryRejection(collection: StoreCollectionDeclaration, query: {
+    filters?: readonly StoreQueryFilter[];
+    orderBy?: StoreOrderBy | null;
+}): string | null;

package/dist/types/types.d.ts

@@ -898,8 +898,57 @@ export interface AiSourcesInput {
         snippet?: string;
     }[];
 }
+export interface AiActionsInput {
+    title?: string;
+    actions: {
+        label: string;
+        href: string;
+        detail?: string;
+    }[];
+}
 /** The tools this client knows how to draw. Anything else in the stream is ignored. */
-export type AiToolName = "showTable" | "showChart" | "showMetrics" | "showTimeline" | "showDetails" | "showSteps" | "showSources";
+export type AiToolName = "showTable" | "showChart" | "showMetrics" | "showTimeline" | "showDetails" | "showSteps" | "showSources" | "showActions";
+/**
+ * One screen in your application, described for the assistant.
+ *
+ * ## Why you declare these rather than Connect discovering them
+ *
+ * Connect has no idea what your app is. It cannot know that `/deals` is a
+ * pipeline, that a "lead" becomes a "contact", or that the thing your users
+ * call a quote lives under Settings. Without that, an assistant sitting inside
+ * your product answers from general knowledge about software - which is exactly
+ * how it reads.
+ *
+ * Declaring a screen is the cheapest possible fix: one line of prose per route,
+ * and questions like "what can I do here?" start answering in your product's
+ * own words.
+ *
+ * ## What Connect does and does not do with them
+ *
+ * They are **prose and links, and nothing else**. Connect puts your
+ * descriptions into the model's context so it can answer and so `showActions`
+ * can link to your screens. It never uses them to decide what anyone may do -
+ * your app's own authorization is untouched and unconsulted here - and it never
+ * executes anything on your behalf.
+ *
+ * They also arrive from a browser, so Connect treats them as untrusted text:
+ * bounded in count and length, and flattened to single lines before they reach
+ * a prompt.
+ */
+export interface ConnectScreen {
+    /**
+     * The route, as your router writes it. Dynamic segments in brackets -
+     * `/deals/[dealId]` - so a live path with a real id still matches.
+     */
+    path: string;
+    /** One line: what a person does here, in your product's words. */
+    purpose: string;
+    /**
+     * Opening questions offered as chips on an empty conversation, phrased as
+     * your users would type them. Two or three; a fourth is a menu.
+     */
+    suggestions?: string[];
+}
 /**
  * One document from the `data` store.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -31,6 +31,15 @@
       "import": "./dist/esm/next/index.js",
       "require": "./dist/cjs/next/index.js"
     },
+    "./mcp": {
+      "types": "./dist/types/mcp/index.d.ts",
+      "browser": {
+        "import": "./dist/esm/this-entry-is-server-only.js",
+        "require": "./dist/cjs/this-entry-is-server-only.js"
+      },
+      "import": "./dist/esm/mcp/index.js",
+      "require": "./dist/cjs/mcp/index.js"
+    },
     "./client": {
       "types": "./dist/types/client/index.d.ts",
       "import": "./dist/esm/client/index.js",