@anuma/sdk 1.0.0-next.20260224164627

package/dist/tools/index.d.ts

@@ -0,0 +1,427 @@
+/**
+ * Google Calendar tool definition for the chat system.
+ * This tool allows the LLM to list events from the user's Google Calendar.
+ */
+/**
+ * Tool configuration type that extends the SDK's tool type with executor support.
+ * The SDK runtime supports these properties even though the base types don't include them.
+ *
+ * Note: Client tools use "arguments" internally. The SDK converts this to "parameters"
+ * when sending to the API (see serverTools.ts mergeTools function).
+ */
+interface ToolConfig {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        arguments: Record<string, unknown>;
+    };
+    executor?: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+    autoExecute?: boolean;
+    skipContinuation?: boolean;
+}
+interface ListEventsArgs {
+    timeMin?: string;
+    timeMax?: string;
+    maxResults?: number;
+}
+interface CreateEventArgs {
+    summary: string;
+    start: string;
+    end: string;
+    description?: string;
+    location?: string;
+    attendees?: string[];
+}
+interface UpdateEventArgs {
+    eventId: string;
+    summary?: string;
+    start?: string;
+    end?: string;
+    description?: string;
+    location?: string;
+    attendees?: string[];
+}
+interface CalendarEvent {
+    id: string;
+    summary: string;
+    start: string;
+    end: string;
+    description?: string;
+    location?: string;
+}
+/**
+ * Creates the Google Calendar list events tool with access to the token getter.
+ * The token getter is captured in a closure so the executor can access it.
+ */
+declare function createGoogleCalendarTool(getAccessToken: () => string | null, requestCalendarAccess: () => Promise<string>): ToolConfig;
+/**
+ * Creates the Google Calendar create event tool with access to the token getter.
+ * The token getter is captured in a closure so the executor can access it.
+ */
+declare function createGoogleCalendarCreateEventTool(getAccessToken: () => string | null, requestCalendarAccess: () => Promise<string>): ToolConfig;
+/**
+ * Creates the Google Calendar update event tool with access to the token getter.
+ * The token getter is captured in a closure so the executor can access it.
+ */
+declare function createGoogleCalendarUpdateEventTool(getAccessToken: () => string | null, requestCalendarAccess: () => Promise<string>): ToolConfig;
+/**
+ * Creates all chat tools with the provided token context.
+ * This factory function allows tools to access authentication tokens via closures.
+ */
+declare function createChatTools(getAccessToken: () => string | null, requestCalendarAccess: () => Promise<string>): ToolConfig[];
+
+/**
+ * Generic factories for creating client-side UI interaction tools.
+ *
+ * These factories handle the boilerplate of wiring tool executors to the
+ * UIInteractionProvider lifecycle (ID generation, context injection,
+ * promise resolution). Apps provide the tool schema and any custom logic.
+ */
+
+/**
+ * Minimal context interface required by tool factories.
+ * Matches the methods provided by UIInteractionProvider.
+ */
+type UIInteractionContext = {
+    createInteraction: (id: string, type: string, data: any) => Promise<any>;
+    createDisplayInteraction: (id: string, displayType: string, data: any, result: any, toolVersion?: number) => void;
+};
+/**
+ * Options for context injection, following the same getter pattern
+ * as createGoogleCalendarTool and createDriveTools.
+ */
+type CreateUIToolsOptions = {
+    /** Returns the current UIInteractionContext (or null if unavailable) */
+    getContext: () => UIInteractionContext | null;
+    /** Returns the ID of the last message in the conversation (used for anchoring) */
+    getLastMessageId?: () => string | undefined;
+};
+/**
+ * Configuration for an interactive tool that waits for user input.
+ */
+type InteractiveToolConfig = {
+    /** Tool name as called by the LLM (e.g. "prompt_user_choice") */
+    name: string;
+    /** Tool description shown to the LLM */
+    description: string;
+    /** JSON Schema for tool parameters */
+    parameters: Record<string, unknown>;
+    /** Interaction type string used by the provider (e.g. "choice", "form") */
+    interactionType: string;
+    /** Optional validation of LLM-provided args. Return false to cancel. */
+    validate?: (args: any) => boolean;
+    /** Transform args before storing as interaction data */
+    mapArgs?: (args: any) => any;
+    /** Transform the user's result before returning to the LLM */
+    mapResult?: (result: any, args: any) => any;
+};
+/**
+ * Migration map for a display tool.
+ * Keys are "fromVersion->toVersion" strings (e.g. "1->2").
+ * Each function receives the stored result at fromVersion and returns the
+ * result upgraded to toVersion.
+ *
+ * @example
+ * ```typescript
+ * migrations: {
+ *   "1->2": (old) => ({ ...old, newField: old.legacyField ?? defaultValue }),
+ * }
+ * ```
+ */
+type DisplayToolMigrations = {
+    [key: `${number}->${number}`]: (data: any) => any;
+};
+/**
+ * Configuration for a display-only tool that renders data without blocking.
+ */
+type DisplayToolConfig<TArgs = any, TResult = any> = {
+    /** Tool name as called by the LLM (e.g. "display_weather") */
+    name: string;
+    /** Tool description shown to the LLM */
+    description: string;
+    /** JSON Schema for tool parameters */
+    parameters: Record<string, unknown>;
+    /** Display type string used to dispatch rendering (e.g. "weather") */
+    displayType: string;
+    /** Execute function that fetches/computes the display data */
+    execute: (args: TArgs) => Promise<TResult>;
+    /**
+     * Schema version for the result format. Increment when the result shape
+     * changes in a backward-incompatible way. Default: 1.
+     */
+    version?: number;
+    /**
+     * Migration functions keyed by "fromVersion->toVersion".
+     * Used to upgrade stored results to the current version on restore.
+     */
+    migrations?: DisplayToolMigrations;
+};
+/**
+ * Migrate a stored display result from an older version to the current version.
+ *
+ * Runs the migration chain step-by-step: fromVersion → fromVersion+1 → … → toVersion.
+ * Steps with no registered migration function are skipped (result passes through unchanged).
+ * Returns the original result unchanged if fromVersion >= toVersion.
+ *
+ * @example
+ * ```typescript
+ * const migrated = migrateDisplayResult(storedResult, 1, 3, {
+ *   "1->2": (v1) => ({ ...v1, added: v1.old ?? 0 }),
+ *   "2->3": (v2) => ({ ...v2, renamed: v2.added }),
+ * });
+ * ```
+ */
+declare function migrateDisplayResult(result: any, fromVersion: number, toVersion: number, migrations: DisplayToolMigrations): any;
+/**
+ * Create an interactive tool that waits for user input.
+ *
+ * When the LLM calls this tool, it creates a pending interaction in
+ * the UIInteractionProvider and returns a Promise that resolves when
+ * the user responds via the UI.
+ *
+ * @example
+ * ```typescript
+ * const choiceTool = createInteractiveTool(
+ *   { getContext: () => uiInteraction, getLastMessageId: () => lastMsgId },
+ *   {
+ *     name: "prompt_user_choice",
+ *     description: "Present choices to the user",
+ *     parameters: { type: "object", properties: { ... } },
+ *     interactionType: "choice",
+ *     validate: (args) => args.title && args.options?.length >= 2,
+ *   }
+ * );
+ * ```
+ */
+declare function createInteractiveTool(options: CreateUIToolsOptions, config: InteractiveToolConfig): ToolConfig;
+/**
+ * Create a display-only tool that renders data without blocking.
+ *
+ * When the LLM calls this tool, it executes the provided function,
+ * stores the result as a resolved display interaction for rendering,
+ * and immediately returns the data to the LLM.
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = createDisplayTool(
+ *   { getContext: () => uiInteraction, getLastMessageId: () => lastMsgId },
+ *   {
+ *     name: "display_weather",
+ *     description: "Show weather for a location",
+ *     parameters: { type: "object", properties: { location: { type: "string" } } },
+ *     displayType: "weather",
+ *     execute: async (args) => fetchWeatherData(args.location),
+ *   }
+ * );
+ * ```
+ */
+declare function createDisplayTool<TArgs = any, TResult = any>(options: CreateUIToolsOptions, config: DisplayToolConfig<TArgs, TResult>): ToolConfig;
+
+/**
+ * Chart display tool factory.
+ *
+ * Creates a client-side tool that renders bar, line, area, and pie charts
+ * inline in the chat. The tool validates the LLM-provided data and passes
+ * it through for rendering by the ChartCard component.
+ */
+
+type ChartDataPoint = Record<string, string | number>;
+type DisplayChartResult = {
+    chartType: "bar" | "line" | "area" | "pie";
+    title?: string;
+    data: ChartDataPoint[];
+    dataKeys: string[];
+    xAxisKey?: string;
+    colors?: Record<string, string>;
+} | {
+    error: string;
+};
+/**
+ * Create a display_chart tool that renders charts inline in the chat.
+ *
+ * @example
+ * ```typescript
+ * import { createChartTool } from "@anuma/sdk/tools";
+ *
+ * const chartTool = createChartTool({
+ *   getContext: () => uiInteraction,
+ *   getLastMessageId: () => lastMsgId,
+ * });
+ * ```
+ */
+declare function createChartTool(options: CreateUIToolsOptions): ToolConfig;
+
+/**
+ * Google Drive tool definition for the chat system.
+ * This tool allows the LLM to search files in the user's Google Drive.
+ */
+
+interface SearchFilesArgs {
+    query: string;
+    maxResults?: number;
+    mimeType?: string;
+}
+interface DriveFile {
+    id: string;
+    name: string;
+    mimeType: string;
+    webViewLink?: string;
+    modifiedTime?: string;
+    size?: string;
+    owners?: {
+        displayName: string;
+        emailAddress: string;
+    }[];
+}
+/**
+ * Creates the Google Drive search tool with access to the token getter.
+ * The token getter is captured in a closure so the executor can access it.
+ */
+declare function createGoogleDriveSearchTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
+interface ListRecentFilesArgs {
+    maxResults?: number;
+    mimeType?: string;
+}
+/**
+ * Creates the Google Drive list recent files tool with access to the token getter.
+ */
+declare function createGoogleDriveListRecentTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
+interface GetFileContentArgs {
+    fileId?: string;
+    fileName?: string;
+}
+/**
+ * Creates the Google Drive get file content tool
+ */
+declare function createGoogleDriveGetContentTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
+/**
+ * Creates all Google Drive tools with the provided token context.
+ */
+declare function createDriveTools(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig[];
+
+/**
+ * Notion MCP tool definitions for the chat system.
+ *
+ * These tools communicate with Notion's hosted MCP server using the
+ * Model Context Protocol (JSON-RPC 2.0). The MCP server handles all
+ * Notion API interactions - we just forward tool calls to it.
+ *
+ * MCP Server: https://mcp.notion.com/mcp (Streamable HTTP)
+ * Fallback: https://mcp.notion.com/sse (Server-Sent Events)
+ *
+ * @see https://developers.notion.com/guides/mcp/build-mcp-client
+ * @see https://modelcontextprotocol.io
+ */
+
+interface NotionSearchArgs {
+    query: string;
+    query_type?: "internal" | "user";
+    filters?: Record<string, unknown>;
+}
+interface NotionFetchArgs {
+    id: string;
+    include_transcript?: boolean;
+    include_discussions?: boolean;
+}
+interface NotionCreatePagesArgs {
+    pages: Array<{
+        properties: Record<string, unknown>;
+        content: string;
+    }>;
+    parent?: Record<string, unknown>;
+}
+interface NotionUpdatePageArgs {
+    data: {
+        page_id: string;
+        command: string;
+        properties?: Record<string, unknown>;
+        new_str?: string;
+        selection_with_ellipsis?: string;
+        allow_deleting_content?: boolean;
+    };
+}
+interface NotionMovePagesArgs {
+    page_or_database_ids: string[];
+    new_parent: Record<string, unknown>;
+}
+/**
+ * MCP Tool: notion-search
+ * Semantic search over Notion workspace and connected sources, or user search
+ */
+declare function createNotionSearchTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-fetch
+ * Retrieves details about a Notion entity (page or database) by URL or ID
+ */
+declare function createNotionFetchTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-pages
+ * Creates one or more Notion pages with properties and content
+ */
+declare function createNotionCreatePagesTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-update-page
+ * Update a page's properties or content using command-based operations
+ */
+declare function createNotionUpdatePageTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-move-pages
+ * Move one or more pages/databases to a new parent
+ */
+declare function createNotionMovePagesTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-duplicate-page
+ * Duplicate a Notion page (completes asynchronously)
+ */
+declare function createNotionDuplicatePageTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-database
+ * Create a new Notion database with a properties schema
+ */
+declare function createNotionCreateDatabaseTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-update-data-source
+ * Update a data source's properties, name, or other attributes
+ */
+declare function createNotionUpdateDataSourceTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-comment
+ * Add a comment to a page, specific content, or reply to a discussion
+ */
+declare function createNotionCreateCommentTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-comments
+ * Get comments and discussions from a Notion page
+ */
+declare function createNotionGetCommentsTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-users
+ * List users in the workspace, get a specific user, or get self
+ */
+declare function createNotionGetUsersTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-teams
+ * Retrieve teams (teamspaces) in the workspace
+ */
+declare function createNotionGetTeamsTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * Create all Notion MCP tools
+ *
+ * Returns tools that communicate with Notion's hosted MCP server.
+ * The MCP server handles all Notion API interactions.
+ */
+declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
+/**
+ * Get the MCP endpoints for direct access
+ */
+declare function getMCPEndpoints(): {
+    http: string;
+    sse: string;
+};
+/**
+ * Call any MCP tool directly (for advanced use cases)
+ */
+declare function callNotionMCPTool<T>(accessToken: string, toolName: string, args: Record<string, unknown>): Promise<T>;
+
+export { type CalendarEvent, type ChartDataPoint, type CreateEventArgs, type CreateUIToolsOptions, type DisplayChartResult, type DisplayToolConfig, type DisplayToolMigrations, type DriveFile, type GetFileContentArgs, type InteractiveToolConfig, type ListEventsArgs, type ListRecentFilesArgs, type NotionCreatePagesArgs, type NotionFetchArgs, type NotionMovePagesArgs, type NotionSearchArgs, type NotionUpdatePageArgs, type SearchFilesArgs, type ToolConfig, type UIInteractionContext, type UpdateEventArgs, callNotionMCPTool, createChartTool, createChatTools, createDisplayTool, createDriveTools, createGoogleCalendarCreateEventTool, createGoogleCalendarTool, createGoogleCalendarUpdateEventTool, createGoogleDriveGetContentTool, createGoogleDriveListRecentTool, createGoogleDriveSearchTool, createInteractiveTool, createNotionCreateCommentTool, createNotionCreateDatabaseTool, createNotionCreatePagesTool, createNotionDuplicatePageTool, createNotionFetchTool, createNotionGetCommentsTool, createNotionGetTeamsTool, createNotionGetUsersTool, createNotionMovePagesTool, createNotionSearchTool, createNotionTools, createNotionUpdateDataSourceTool, createNotionUpdatePageTool, getMCPEndpoints, migrateDisplayResult };