@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/types/client/components/user-menu.d.ts

@@ -14,35 +14,81 @@ export interface ConnectUserMenuProps {
     theme?: ThemeMode;
     onThemeChange?: (theme: ThemeMode) => void;
 }
+export interface ConnectProfileModalProps {
+    /** Controlled open state. */
+    isOpen: boolean;
+    onOpenChange: (isOpen: boolean) => void;
+    /** Called after sign-out completes, e.g. to route home. */
+    onSignOut?: () => void;
+    /** See `ConnectUserButtonProps.theme`. */
+    theme?: ThemeMode;
+    onThemeChange?: (theme: ThemeMode) => void;
+}
 /**
- * Avatar and name in the trigger; an identity card, the three Connect
- * destinations (Profile, Billing, Connect), an optional appearance control,
- * this account's active sessions, and sign-out in the modal it opens.
+ * The account modal with **no trigger of its own**, driven by the host.
+ *
+ * For an application that already has an account control it wants to keep -
+ * an avatar in its own chrome, a "Manage account" row in its own settings
+ * page - and wants Connect's modal behind it rather than rebuilding identity,
+ * sessions and sign-out. `ConnectUserButton` is the same modal with the
+ * trigger supplied; reach for this one only when that trigger is in the way.
  *
- * Profile/Billing/Connect open in a **new tab**, each marked with an
- * external-link icon. They are a different application at a different
- * origin, and navigating the host app away to reach them would lose
- * whatever the user was doing here. Sign out is the only action that acts
- * in place, which is why it sits alone in the footer rather than as a fourth
- * item in the same list as three navigations.
+ * Renders nothing when signed out, open or not - there is no account to show.
+ */
+export declare function ConnectProfileModal({ isOpen, onOpenChange, onSignOut, theme, onThemeChange, }: ConnectProfileModalProps): import("react").JSX.Element | null;
+export interface ConnectUserButtonProps {
+    /**
+     * How the trigger is drawn.
+     *
+     * - `"row"` - a full-width sidebar row: avatar, name over email, and a
+     *   trailing glyph. The default, because the account control now lives in
+     *   the rail's footer rather than in a top bar.
+     * - `"compact"` - the avatar alone, for a dense strip.
+     * - `"inline"` - avatar and name side by side, for a bar with room.
+     */
+    variant?: "row" | "compact" | "inline";
+    /** Called after sign-out completes, e.g. to route home. */
+    onSignOut?: () => void;
+    className?: string;
+    /**
+     * Current theme, and where to send a change - the SDK has no theme provider
+     * of its own (no `next-themes` dependency), so this is entirely
+     * host-controlled. The Appearance section only renders when both are
+     * supplied; omit either to leave theme control out of the modal.
+     */
+    theme?: ThemeMode;
+    onThemeChange?: (theme: ThemeMode) => void;
+}
+/**
+ * The signed-in account, as a control that opens the account modal.
  *
- * The session list is account-wide, not scoped to this application - see
- * `ConnectUserSession`'s doc comment in `types.ts`. Appearance only renders
- * when both `theme` and `onThemeChange` are supplied.
+ * In `"row"` form this is the last thing in the sidebar, which is where an
+ * account control belongs: it is the one item in the rail that is about *you*
+ * rather than about the product, and the foot of a column is where every
+ * application a customer already uses puts that. It collapses with the rail -
+ * the avatar holds its position and the name fades - because the avatar alone
+ * is still a complete account control, which is exactly what an icon rail
+ * needs.
  *
- * Renders nothing when signed out - pair it with `<ConnectLoginButton>`, which
- * renders nothing when signed *in*, and the two swap cleanly with no branch in
- * your own layout.
+ * Renders nothing when signed out. Pair it with `<ConnectLoginButton>`, which
+ * renders nothing when signed *in*, and the two swap with no branch in your
+ * own layout.
  *
  * On the HeroUI shape: the trigger is a plain `<Button>` as a **direct child**
- * of `<Modal>`, not wrapped in `<Modal.Trigger>`. `Dropdown.Trigger` (and by
- * the same construction, `Modal.Trigger`) is itself a React Aria `Button`, so
- * wrapping one produces a button inside a button - invalid markup, and press
- * handling stops working. Kept uncontrolled (no `isOpen`/`onOpenChange`),
- * matching `<ConnectAppsGrid>`'s own `<Modal>` - nothing here needs to close
- * the modal programmatically; sign-out uses `slot="close"` instead.
+ * of `<Modal>`, not wrapped in `<Modal.Trigger>`. `Dropdown.Trigger` - and by
+ * the same construction `Modal.Trigger` - is itself a React Aria `Button`, so
+ * wrapping one produces a button inside a button: invalid markup, and press
+ * handling stops working.
+ */
+export declare function ConnectUserButton({ variant, onSignOut, className, theme, onThemeChange, }: ConnectUserButtonProps): import("react").JSX.Element | null;
+/**
+ * @deprecated Renamed to `ConnectUserButton` in 0.12 - it is one button that
+ * opens a modal, and calling it a "menu" had people looking for a dropdown
+ * that never existed. `compact` maps to `variant="compact"`, and the old
+ * default (avatar plus name) to `variant="inline"`. This alias will be removed
+ * in a later minor.
  */
-export declare function ConnectUserMenu({ compact, onSignOut, className, theme, onThemeChange, }: ConnectUserMenuProps): import("react").JSX.Element | null;
+export declare function ConnectUserMenu({ compact, ...rest }: ConnectUserMenuProps): import("react").JSX.Element;
 /**
  * The "Manage subscription" action on its own, for layouts that want it
  * visible rather than buried in the account menu - a billing banner, an empty

package/dist/types/client/components/workspace-switcher.d.ts

@@ -0,0 +1,49 @@
+import type { UserWorkspace } from "../../types.js";
+export interface ConnectWorkspaceSwitcherProps {
+    /**
+     * Called after a successful switch. Defaults to a full reload, which is
+     * almost always right: every server-rendered page in the host application
+     * was built for the *previous* workspace, and a client-side refresh would
+     * leave stale data on screen next to the new workspace's name.
+     */
+    onSwitched?: (workspace: UserWorkspace) => void;
+    /**
+     * Draw the trigger as a sidebar row rather than a plain button. On by
+     * default inside `AppShell`, where this sits directly under the
+     * brand; pass `false` for a standalone placement in your own chrome.
+     */
+    row?: boolean;
+    className?: string;
+}
+/**
+ * Switches which workspace this application is looking at.
+ *
+ * **Rendered in the `AppShell` sidebar header by default**, directly
+ * under the brand - which workspace you are in scopes everything below it, so
+ * it reads as a heading for the nav rather than as one more destination.
+ *
+ * It decides for itself whether to appear: an account with one workspace is
+ * shown nothing, because a switcher offering one option teaches the user
+ * nothing and costs a row of chrome on every screen. That is the opposite of
+ * Connect's own switcher, which always renders - Connect is where a workspace
+ * is *created*, so hiding it at one workspace would guarantee nobody ever
+ * reached two. A partner application creates nothing, so it has no such duty.
+ *
+ * **Authorization is the data, not a prop.** The list comes from the caller's
+ * own session (`GET /workspaces` takes no user id), so a workspace the user
+ * may not reach is simply not in it. There is deliberately no `roles` prop to
+ * pass or forget - the only way to render a row is for Connect to have
+ * returned it.
+ *
+ * Rows the user *belongs to* but cannot use here - a workspace outside the
+ * application's audience, or one with no subscription - are shown **disabled
+ * with the reason** rather than hidden. Hiding them reads as data loss to the
+ * person who owns the workspace; `switch` refuses the same two cases, so the
+ * label and the outcome always agree.
+ *
+ * A switch rotates the session token. The bridge persists the new one in the
+ * host application's own session store and the token never reaches this
+ * component - so the only thing to do afterwards is reload, which is what
+ * `onSwitched` defaults to.
+ */
+export declare function ConnectWorkspaceSwitcher({ onSwitched, row, className, }: Readonly<ConnectWorkspaceSwitcherProps>): import("react").JSX.Element | null;

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

@@ -10,28 +10,39 @@
  * whatever theme the host application platform already configured, and one theme
  * change lands identically in all of them.
  */
-export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
 export type { ConnectProviderProps, ConnectContextValue, ConnectSession } from "./provider.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
 export { ConnectError, isConnectError } from "../errors.js";
 export type * from "../types.js";
+export { ConnectGrievanceNotice } from "./components/grievance-notice.js";
+export type { ConnectGrievanceNoticeProps } from "./components/grievance-notice.js";
 export { ConnectMark } from "./mark.js";
 export { ConnectLogo } from "./components/logo.js";
 export type { ConnectLogoProps } from "./components/logo.js";
 export { ConnectLoginButton, ConnectRegisterButton } from "./components/auth-buttons.js";
 export type { ConnectAuthButtonProps } from "./components/auth-buttons.js";
-export { ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, ConnectProfileButton, ConnectHomeButton, ConnectSignOutButton, } from "./components/user-menu.js";
+export { ConnectUserButton, ConnectProfileModal, 
+/** @deprecated Renamed to `ConnectUserButton`. */
+ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, ConnectProfileButton, ConnectHomeButton, ConnectSignOutButton, } from "./components/user-menu.js";
+export type { ConnectUserButtonProps, ConnectProfileModalProps } from "./components/user-menu.js";
 export { ConnectAccountSessions } from "./components/account-sessions.js";
 export type { ConnectAccountSessionsProps } from "./components/account-sessions.js";
 export type { ConnectUserMenuProps } from "./components/user-menu.js";
 export { AppShell } from "./components/app-shell.js";
 export type { AppShellProps } from "./components/app-shell.js";
-export { ConnectSideNav } from "./components/side-nav.js";
-export type { ConnectSideNavProps } from "./components/side-nav.js";
+export { ConnectSidebar, ConnectSidebarHeader, ConnectSidebarBody, ConnectSidebarFooter, ConnectSidebarRow, } from "./components/sidebar.js";
+export type { ConnectSidebarProps, ConnectSidebarHeaderProps, ConnectSidebarRowProps, } from "./components/sidebar.js";
+export { ConnectShellProvider, useConnectShell, sidebarRowClass, RAIL_COLLAPSED, RAIL_EXPANDED, } from "./components/shell-context.js";
+export type { ConnectShellContextValue } from "./components/shell-context.js";
+export { ConnectSidebarNav, ConnectSideNav } from "./components/side-nav.js";
+export type { ConnectSidebarNavProps, ConnectSideNavProps } from "./components/side-nav.js";
 export { useActivePath } from "./use-active-path.js";
-export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, } from "./components/nav.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";
@@ -55,11 +66,24 @@ export { ConnectFeatureGate, useConnectFeature } from "./components/feature-gate
 export type { ConnectFeatureGateProps } from "./components/feature-gate.js";
 export { ConnectWorkspaceTypeGate } from "./components/workspace-type-gate.js";
 export type { ConnectWorkspaceTypeGateProps } from "./components/workspace-type-gate.js";
+export { ConnectPlatformGate } from "./components/platform-gate.js";
+export type { ConnectPlatformGateProps } from "./components/platform-gate.js";
 export { ConnectUsageMeter } from "./components/usage-meter.js";
 export type { ConnectUsageMeterProps } from "./components/usage-meter.js";
 export { ConnectPlansPage } from "./components/plans-page.js";
 export type { ConnectPlansPageProps } from "./components/plans-page.js";
+export { ConnectLinkButton } from "./components/link-button.js";
+export type { ConnectLinkButtonProps } from "./components/link-button.js";
+export { ConnectConfirmDialog } from "./components/confirm-dialog.js";
+export type { ConnectConfirmDialogProps } from "./components/confirm-dialog.js";
+export { ConnectCursorPagination } from "./components/cursor-pagination.js";
+export type { ConnectCursorPaginationProps } from "./components/cursor-pagination.js";
+export { ConnectFilterTabs } from "./components/filter-tabs.js";
+export type { ConnectFilterTabsProps, ConnectFilterTabsOption } from "./components/filter-tabs.js";
 export { useConnectCheckout, buildCheckoutUrl } from "./use-checkout.js";
 export type { ConnectCheckoutStatus, ConnectCheckoutState, ConnectEntitlements, StartCheckoutOptions, CheckoutUrlOptions, } from "./use-checkout.js";
 export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACTION_LABEL, groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";
 export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pricing.js";
+export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
+export type { ConnectWorkspaceSwitcherProps } from "./components/workspace-switcher.js";
+export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js";

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

@@ -1,14 +1,23 @@
 import type { ReactNode } from "react";
-import type { AddonUsageResponse, ConnectUser, IntegrationsListResponse, WorkspaceApp, PlansResponse, ReadinessResponse, ApplicationRole, SessionsListResponse, SessionSubscription, SessionAudience, SubscriptionResponse, WorkspaceType } from "../types.js";
+import type { AddonUsageResponse, CompanyProfileResponse, ConnectUser, IntegrationsListResponse, WorkspaceApp, UserWorkspace, ConnectWorkspaceMember, PlansResponse, ReadinessResponse, SessionsListResponse, SessionSubscription, SessionAudience, SubscriptionResponse, WorkspaceType } from "../types.js";
 export declare const CONNECT_APP_URL = "https://connect.cosmoops.com";
 export interface ConnectSession {
     user: ConnectUser | null;
     subscription: SessionSubscription | null;
-    applicationRole: ApplicationRole | null;
     /**
-     * `null` when signed out, for the same reason the three above are: there is
-     * no workspace to compare an audience against yet. Never `null` on a
-     * signed-in session.
+     * The signed-in account's role on this application, or `null` - see
+     * `SessionAccess.role`. `null` when signed out too, which is why `user`
+     * rather than this is the signed-in test.
+     */
+    role: string | null;
+    /** What to gate on - see `SessionAccess.permissions`. `[]` when signed out. */
+    permissions: string[];
+    /** Whether this is one of Connect's own operators - see `SessionAccess.staff`. `false` when signed out. */
+    staff: boolean;
+    /**
+     * `null` when signed out, for the same reason `user` and `subscription`
+     * are: there is no workspace to compare an audience against yet. Never
+     * `null` on a signed-in session.
      */
     audience: SessionAudience | null;
 }
@@ -83,7 +92,7 @@ export interface ConnectContextValue {
 }
 export interface ConnectProviderProps {
     /**
-     * This application's public `client_id`, from its Integration tab in Connect.
+     * This application's public `client_id`, from its Connect client section in Connect.
      *
      * Not needed for the default sign-in flow: `signIn()` with no `redirectUri`
      * bounces the browser to your own `/signin` route, which already knows
@@ -171,6 +180,35 @@ export declare function useConnectWorkspaceType(): WorkspaceType | null;
  * sign-up CTA you would rather not show to an account that cannot complete it.
  */
 export declare function useConnectAudience(): SessionAudience | null;
+/**
+ * Whether this session is one of Connect's own operators - see
+ * `SessionAccess.staff`.
+ *
+ * `isStaff` is the branch you want; `roles` narrows further when your operator
+ * console has tiers of its own (a `developer` seeing a read-only view of what
+ * a `platform_admin` can edit, say).
+ *
+ * **A rendering decision, not an access decision.** The browser can call this
+ * whatever it likes. Everything an operator console exposes must be re-checked
+ * server-side against `staff` from
+ * `client.identity.getUser(sessionToken)` - see `<ConnectPlatformGate>`, which
+ * says the same thing at more length.
+ */
+export declare function useConnectPlatformAccess(): {
+    isStaff: boolean;
+    /**
+     * The staff role, as a one-element array.
+     *
+     * Still an array because `<ConnectPlatformGate accept={[...]}>` matches
+     * against a set, and because a session reports one role since
+     * `role`/`permissions`/`staff` replaced the old `platformAccess.roles`
+     * list - Connect's platform roles nest, so the highest one is the whole
+     * answer. Empty for a member session.
+     */
+    roles: string[];
+    /** `true` while the session read is in flight - neither staff nor not-staff yet. */
+    isLoading: boolean;
+};
 /** Readiness gates and the live subscription, fetched on first use. */
 export declare function useConnectEntitlements(): {
     data: {
@@ -222,6 +260,29 @@ export declare function useConnectPlans(): {
      */
     refetch(): void;
 };
+/**
+ * The platform's legal identity and DPDP grievance channel.
+ *
+ * The one read here that does not depend on a session, so it resolves the
+ * same for a signed-out visitor - which is deliberate, because the moment a
+ * grievance channel most needs to be readable is on a public privacy page.
+ *
+ * Read it rather than copying it into your own configuration; see
+ * `CompanyProfile`. `<ConnectGrievanceNotice>` renders it for you.
+ */
+export declare function useConnectCompanyProfile(): {
+    data: CompanyProfileResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
 /** The apps this workspace can open. */
 export declare function useConnectApps(): {
     data: {
@@ -238,6 +299,48 @@ export declare function useConnectApps(): {
      */
     refetch(): void;
 };
+/**
+ * The workspaces this user belongs to - what `<ConnectWorkspaceSwitcher>`
+ * renders.
+ *
+ * Empty or single-entry results are normal, not errors: most accounts have one
+ * workspace, and the switcher decides for itself whether that is worth
+ * drawing.
+ */
+export declare function useConnectWorkspaces(): {
+    data: {
+        workspaces: UserWorkspace[];
+    } | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/**
+ * The team of the workspace this session is on, with each member's permissions
+ * already resolved for this application.
+ */
+export declare function useConnectWorkspaceMembers(): {
+    data: {
+        members: ConnectWorkspaceMember[];
+    } | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
 /** Enabled Composio-hosted toolkits and this workspace's connection status for each. */
 export declare function useConnectIntegrations(): {
     data: IntegrationsListResponse | null;

package/dist/types/client/use-checkout.d.ts

@@ -85,9 +85,13 @@ export declare function buildCancelUrl({ appUrl, subscriptionId }: {
  * The Connect URL that completes a subscribe or a plan change.
  *
  * Both land on a modal Connect renders over the relevant page (an intercepted
- * parallel route - `app/@modal/(.)applications/...` and
- * `app/@modal/(.)billing/...`), so the customer arrives already looking at the
- * confirmation for the plan they picked here, not at a catalogue they have to
- * find it in again.
+ * parallel route - `app/@modal/(.)apps/...` and `app/@modal/(.)billing/...`),
+ * so the customer arrives already looking at the confirmation for the plan
+ * they picked here, not at a catalogue they have to find it in again.
+ *
+ * The subscribe path is `/apps/...`, not `/applications/...`: the portal
+ * route customers see is `/apps`, and `/applications` is a Console-only
+ * prefix that has never served this page. Building the other one is what
+ * sent every first-time subscriber from a partner's pricing page to a 404.
  */
 export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;

package/dist/types/errors.d.ts

@@ -52,7 +52,7 @@ export declare class ConnectError extends Error {
      * guessing keys. These two are the exception: reaching them required
      * presenting a key whose hash matched, so you already hold it, and what you
      * need to know is that no retry and no scope change will fix this - the key
-     * has to be reissued from the application's Integration tab.
+     * has to be reissued from the application's Connect client section.
      *
      * Worth alerting on. It is the one failure that will not resolve itself and
      * takes down every call your integration makes.

package/dist/types/index.d.ts

@@ -10,8 +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/next/index.d.ts

@@ -125,7 +125,7 @@ export declare function getConnectSession(request?: 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