@composio/client 0.1.0-alpha.39 → 0.1.0-alpha.41

package/resources/tool-router/session.d.ts

@@ -0,0 +1,708 @@
+import { APIResource } from "../../core/resource.js";
+import { APIPromise } from "../../core/api-promise.js";
+import { RequestOptions } from "../../internal/request-options.js";
+export declare class Session extends APIResource {
+    /**
+     * Creates a new session for the tool router feature. This endpoint initializes a
+     * new session with specified toolkits and their authentication configurations. The
+     * session provides an isolated environment for testing and managing tool routing
+     * logic with scoped MCP server access.
+     *
+     * @example
+     * ```ts
+     * const session = await client.toolRouter.session.create({
+     *   user_id: 'user_123456789',
+     * });
+     * ```
+     */
+    create(body: SessionCreateParams, options?: RequestOptions): APIPromise<SessionCreateResponse>;
+    /**
+     * Retrieves an existing tool router session by its ID. Returns the session
+     * configuration, MCP server URL, and available tools.
+     *
+     * @example
+     * ```ts
+     * const session = await client.toolRouter.session.retrieve(
+     *   'trs_123456789',
+     * );
+     * ```
+     */
+    retrieve(sessionID: string, options?: RequestOptions): APIPromise<SessionRetrieveResponse>;
+    /**
+     * Executes a specific tool within a tool router session. The toolkit is
+     * automatically inferred from the tool slug. The tool must belong to an allowed
+     * toolkit and must not be disabled in the session configuration. This endpoint
+     * validates permissions, resolves connected accounts, and executes the tool with
+     * the session context.
+     *
+     * @example
+     * ```ts
+     * const response = await client.toolRouter.session.execute(
+     *   'trs_LX9uJKBinWWr',
+     *   { tool_slug: 'GITHUB_CREATE_ISSUE' },
+     * );
+     * ```
+     */
+    execute(sessionID: string, params: SessionExecuteParams, options?: RequestOptions): APIPromise<SessionExecuteResponse>;
+    /**
+     * Initiates an authentication link session for a specific toolkit within a tool
+     * router session. Returns a link token and redirect URL that users can use to
+     * complete the OAuth flow.
+     *
+     * @example
+     * ```ts
+     * const response = await client.toolRouter.session.link(
+     *   'trs_LX9uJKBinWWr',
+     *   { toolkit: 'github' },
+     * );
+     * ```
+     */
+    link(sessionID: string, body: SessionLinkParams, options?: RequestOptions): APIPromise<SessionLinkResponse>;
+    /**
+     * Retrieves a cursor-paginated list of toolkits available in the tool router
+     * session. Includes toolkit metadata, composio-managed auth schemes, and connected
+     * accounts if available. Optionally filter by specific toolkit slugs.
+     *
+     * @example
+     * ```ts
+     * const response = await client.toolRouter.session.toolkits(
+     *   'trs_123456789',
+     * );
+     * ```
+     */
+    toolkits(sessionID: string, query?: SessionToolkitsParams | null | undefined, options?: RequestOptions): APIPromise<SessionToolkitsResponse>;
+}
+export interface SessionCreateResponse {
+    /**
+     * The session configuration including user, toolkits, and overrides
+     */
+    config: SessionCreateResponse.Config;
+    mcp: SessionCreateResponse.Mcp;
+    /**
+     * The identifier of the session
+     */
+    session_id: string;
+    /**
+     * List of available tools in this session
+     */
+    tool_router_tools: Array<'COMPOSIO_SEARCH_TOOLS' | 'COMPOSIO_MULTI_EXECUTE_TOOL' | 'COMPOSIO_MANAGE_CONNECTIONS' | 'COMPOSIO_REMOTE_WORKBENCH' | 'COMPOSIO_REMOTE_BASH_TOOL'>;
+}
+export declare namespace SessionCreateResponse {
+    /**
+     * The session configuration including user, toolkits, and overrides
+     */
+    interface Config {
+        /**
+         * User identifier for this session
+         */
+        user_id: string;
+        /**
+         * Connections configuration
+         */
+        connections?: Config.Connections;
+        /**
+         * Execution configuration
+         */
+        execution?: Config.Execution;
+        /**
+         * Toolkit configuration - either enabled list or disabled list
+         */
+        toolkits?: Config.Enabled | Config.Disabled;
+        /**
+         * Tools configuration
+         */
+        tools?: Config.Tools;
+    }
+    namespace Config {
+        /**
+         * Connections configuration
+         */
+        interface Connections {
+            /**
+             * Auth config overrides per toolkit
+             */
+            auth_config_overrides?: {
+                [key: string]: string;
+            };
+            /**
+             * Whether to enable the connection manager for automatic connection handling
+             */
+            auto_manage_connections?: boolean;
+            /**
+             * Custom callback URI for connected account auth flows
+             */
+            callback_uri?: string;
+            /**
+             * Connected account overrides per toolkit
+             */
+            connected_account_overrides?: {
+                [key: string]: string;
+            };
+            /**
+             * Whether to auto-infer auth scopes from tools
+             */
+            infer_scopes_from_tools?: boolean;
+        }
+        /**
+         * Execution configuration
+         */
+        interface Execution {
+            /**
+             * Whether to allow proxy execute calls in the workbench
+             */
+            proxy_execution_enabled?: boolean;
+            /**
+             * Maximum execution time for workbench operations in seconds
+             */
+            timeout_seconds?: number;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        /**
+         * Tools configuration
+         */
+        interface Tools {
+            /**
+             * Tool filtering configuration
+             */
+            filters?: Tools.Filters;
+            /**
+             * Tool-level overrides per toolkit
+             */
+            overrides?: {
+                [key: string]: Tools.Enabled | Tools.Disabled;
+            };
+        }
+        namespace Tools {
+            /**
+             * Tool filtering configuration
+             */
+            interface Filters {
+                /**
+                 * Filter tools by specific tags
+                 */
+                tags?: Filters.Tags;
+            }
+            namespace Filters {
+                /**
+                 * Filter tools by specific tags
+                 */
+                interface Tags {
+                    /**
+                     * Exclude tools that have these tags
+                     */
+                    exclude?: Array<string>;
+                    /**
+                     * Only include tools that have these tags
+                     */
+                    include?: Array<string>;
+                }
+            }
+            interface Enabled {
+                enabled: Array<string>;
+            }
+            interface Disabled {
+                disabled: Array<string>;
+            }
+        }
+    }
+    interface Mcp {
+        /**
+         * The type of the MCP server. Can be http
+         */
+        type: 'HTTP';
+        /**
+         * The URL of the MCP server
+         */
+        url: string;
+    }
+}
+export interface SessionRetrieveResponse {
+    /**
+     * The session configuration including user, toolkits, and overrides
+     */
+    config: SessionRetrieveResponse.Config;
+    mcp: SessionRetrieveResponse.Mcp;
+    /**
+     * The identifier of the session
+     */
+    session_id: string;
+    /**
+     * List of available tools in this session
+     */
+    tool_router_tools: Array<'COMPOSIO_SEARCH_TOOLS' | 'COMPOSIO_MULTI_EXECUTE_TOOL' | 'COMPOSIO_MANAGE_CONNECTIONS' | 'COMPOSIO_REMOTE_WORKBENCH' | 'COMPOSIO_REMOTE_BASH_TOOL'>;
+}
+export declare namespace SessionRetrieveResponse {
+    /**
+     * The session configuration including user, toolkits, and overrides
+     */
+    interface Config {
+        /**
+         * User identifier for this session
+         */
+        user_id: string;
+        /**
+         * Connections configuration
+         */
+        connections?: Config.Connections;
+        /**
+         * Execution configuration
+         */
+        execution?: Config.Execution;
+        /**
+         * Toolkit configuration - either enabled list or disabled list
+         */
+        toolkits?: Config.Enabled | Config.Disabled;
+        /**
+         * Tools configuration
+         */
+        tools?: Config.Tools;
+    }
+    namespace Config {
+        /**
+         * Connections configuration
+         */
+        interface Connections {
+            /**
+             * Auth config overrides per toolkit
+             */
+            auth_config_overrides?: {
+                [key: string]: string;
+            };
+            /**
+             * Whether to enable the connection manager for automatic connection handling
+             */
+            auto_manage_connections?: boolean;
+            /**
+             * Custom callback URI for connected account auth flows
+             */
+            callback_uri?: string;
+            /**
+             * Connected account overrides per toolkit
+             */
+            connected_account_overrides?: {
+                [key: string]: string;
+            };
+            /**
+             * Whether to auto-infer auth scopes from tools
+             */
+            infer_scopes_from_tools?: boolean;
+        }
+        /**
+         * Execution configuration
+         */
+        interface Execution {
+            /**
+             * Whether to allow proxy execute calls in the workbench
+             */
+            proxy_execution_enabled?: boolean;
+            /**
+             * Maximum execution time for workbench operations in seconds
+             */
+            timeout_seconds?: number;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        /**
+         * Tools configuration
+         */
+        interface Tools {
+            /**
+             * Tool filtering configuration
+             */
+            filters?: Tools.Filters;
+            /**
+             * Tool-level overrides per toolkit
+             */
+            overrides?: {
+                [key: string]: Tools.Enabled | Tools.Disabled;
+            };
+        }
+        namespace Tools {
+            /**
+             * Tool filtering configuration
+             */
+            interface Filters {
+                /**
+                 * Filter tools by specific tags
+                 */
+                tags?: Filters.Tags;
+            }
+            namespace Filters {
+                /**
+                 * Filter tools by specific tags
+                 */
+                interface Tags {
+                    /**
+                     * Exclude tools that have these tags
+                     */
+                    exclude?: Array<string>;
+                    /**
+                     * Only include tools that have these tags
+                     */
+                    include?: Array<string>;
+                }
+            }
+            interface Enabled {
+                enabled: Array<string>;
+            }
+            interface Disabled {
+                disabled: Array<string>;
+            }
+        }
+    }
+    interface Mcp {
+        /**
+         * The type of the MCP server. Can be http
+         */
+        type: 'HTTP';
+        /**
+         * The URL of the MCP server
+         */
+        url: string;
+    }
+}
+export interface SessionExecuteResponse {
+    /**
+     * The data returned by the tool execution
+     */
+    data: {
+        [key: string]: unknown;
+    };
+    /**
+     * Error message if the execution failed, null otherwise
+     */
+    error: string | null;
+    /**
+     * Unique identifier for the execution log
+     */
+    log_id: string;
+}
+export interface SessionLinkResponse {
+    /**
+     * The unique identifier for the connected account
+     */
+    connected_account_id: string;
+    /**
+     * Token used to complete the authentication flow
+     */
+    link_token: string;
+    /**
+     * The URL where users should be redirected to complete OAuth
+     */
+    redirect_url: string;
+}
+export interface SessionToolkitsResponse {
+    current_page: number;
+    items: Array<SessionToolkitsResponse.Item>;
+    total_items: number;
+    total_pages: number;
+    next_cursor?: string | null;
+}
+export declare namespace SessionToolkitsResponse {
+    interface Item {
+        /**
+         * Available Composio-managed auth schemes
+         */
+        composio_managed_auth_schemes: Array<string>;
+        /**
+         * Connected account if available
+         */
+        connected_account: Item.ConnectedAccount | null;
+        /**
+         * Whether the toolkit is enabled
+         */
+        enabled: boolean;
+        /**
+         * Toolkit metadata
+         */
+        meta: Item.Meta;
+        /**
+         * Display name of the toolkit
+         */
+        name: string;
+        /**
+         * Unique slug identifier
+         */
+        slug: string;
+    }
+    namespace Item {
+        /**
+         * Connected account if available
+         */
+        interface ConnectedAccount {
+            /**
+             * Connected account identifier
+             */
+            id: string;
+            /**
+             * Auth config details
+             */
+            auth_config: ConnectedAccount.AuthConfig;
+            /**
+             * Creation timestamp
+             */
+            created_at: string;
+            /**
+             * Connection status
+             */
+            status: string;
+            /**
+             * Last update timestamp
+             */
+            updated_at: string;
+            /**
+             * User identifier
+             */
+            user_id: string;
+        }
+        namespace ConnectedAccount {
+            /**
+             * Auth config details
+             */
+            interface AuthConfig {
+                /**
+                 * Auth config identifier
+                 */
+                id: string;
+                /**
+                 * Authentication scheme type
+                 */
+                auth_scheme: string;
+                /**
+                 * Whether this is a Composio-managed auth config
+                 */
+                is_composio_managed: boolean;
+            }
+        }
+        /**
+         * Toolkit metadata
+         */
+        interface Meta {
+            /**
+             * Description of the toolkit
+             */
+            description: string;
+            /**
+             * URL to the toolkit logo
+             */
+            logo: string;
+        }
+    }
+}
+export interface SessionCreateParams {
+    /**
+     * The identifier of the user who is initiating the session, ideally a unique
+     * identifier from your database like a user ID or email address
+     */
+    user_id: string;
+    /**
+     * Configuration for authentication and connected account management
+     */
+    connections?: SessionCreateParams.Connections;
+    /**
+     * Configuration for workbench behavior including security restrictions and
+     * execution limits
+     */
+    execution?: SessionCreateParams.Execution;
+    /**
+     * Toolkit configuration - specify either enabled toolkits (allowlist) or disabled
+     * toolkits (denylist). Mutually exclusive.
+     */
+    toolkits?: SessionCreateParams.Enabled | SessionCreateParams.Disabled;
+    /**
+     * Configuration for tool overrides and filtering
+     */
+    tools?: SessionCreateParams.Tools;
+}
+export declare namespace SessionCreateParams {
+    /**
+     * Configuration for authentication and connected account management
+     */
+    interface Connections {
+        /**
+         * The auth configs to use for the session. This will override the default behavior
+         * and use the given auth config when specific toolkits are being executed
+         */
+        auth_config_overrides?: {
+            [key: string]: string;
+        };
+        /**
+         * Whether to enable the connection manager for automatic connection handling. If
+         * true, we will provide a tool your agent can use to initiate connections to
+         * toolkits if it doesnt exist. If set to false, then you have to manage
+         * connections manually.
+         */
+        auto_manage_connections?: boolean | null;
+        /**
+         * The URI to redirect to after a user completes authentication for a connected
+         * account. This allows you to handle the auth callback in your own application.
+         */
+        callback_uri?: string;
+        /**
+         * The connected accounts to use for the session. This will override the default
+         * behaviour and use the given connected account when specific toolkits are being
+         * executed
+         */
+        connected_account_overrides?: {
+            [key: string]: string;
+        };
+        /**
+         * If enabled, authentication scopes will be automatically inferred from the
+         * specific tools being used in the session. This ensures minimal permissions are
+         * requested.
+         */
+        infer_scopes_from_tools?: boolean | null;
+    }
+    /**
+     * Configuration for workbench behavior including security restrictions and
+     * execution limits
+     */
+    interface Execution {
+        /**
+         * Whether to allow proxy execute calls in the workbench. If false, prevents
+         * arbitrary HTTP requests and destructive actions.
+         */
+        proxy_execution_enabled?: boolean | null;
+        /**
+         * Maximum allowed execution time for workbench operations in seconds. If not
+         * specified, uses the default timeout.
+         */
+        timeout_seconds?: number;
+    }
+    /**
+     * Enable only specific toolkits (allowlist)
+     */
+    interface Enabled {
+        /**
+         * Only these specific toolkits will be enabled
+         */
+        enabled: Array<string>;
+    }
+    /**
+     * Disable specific toolkits (denylist)
+     */
+    interface Disabled {
+        /**
+         * These specific toolkits will be disabled
+         */
+        disabled: Array<string>;
+    }
+    /**
+     * Configuration for tool overrides and filtering
+     */
+    interface Tools {
+        /**
+         * Configuration for filtering available tools based on tags and characteristics
+         */
+        filters?: Tools.Filters;
+        /**
+         * Tool-level overrides per toolkit - either specify enabled tools (whitelist) or
+         * disabled tools (blacklist) for each toolkit
+         */
+        overrides?: {
+            [key: string]: Tools.Enabled | Tools.Disabled;
+        };
+    }
+    namespace Tools {
+        /**
+         * Configuration for filtering available tools based on tags and characteristics
+         */
+        interface Filters {
+            /**
+             * Filter tools by tags such as read_only_hint, non_destructive_hint,
+             * open_world_hint, idempotent_hint. Use include to only show tools with specific
+             * tags, or exclude to hide tools with specific tags.
+             */
+            tags?: Filters.Tags;
+        }
+        namespace Filters {
+            /**
+             * Filter tools by tags such as read_only_hint, non_destructive_hint,
+             * open_world_hint, idempotent_hint. Use include to only show tools with specific
+             * tags, or exclude to hide tools with specific tags.
+             */
+            interface Tags {
+                /**
+                 * Exclude tools that have any of these tags. Tools with any of these tags will be
+                 * filtered out.
+                 */
+                exclude?: Array<string>;
+                /**
+                 * Only include tools that have these tags. Tools must have at least one of these
+                 * tags to be included.
+                 */
+                include?: Array<string>;
+            }
+        }
+        interface Enabled {
+            /**
+             * Only these specific tools will be available for this toolkit
+             */
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            /**
+             * These specific tools will be disabled for this toolkit
+             */
+            disabled: Array<string>;
+        }
+    }
+}
+export interface SessionExecuteParams {
+    /**
+     * Body param: The unique slug identifier of the tool to execute
+     */
+    tool_slug: string;
+    /**
+     * Body param: The arguments required by the tool
+     */
+    arguments?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Header param: Session access key for sandbox/workbench authentication.
+     * Alternative to x-api-key for internal tool router endpoints.
+     */
+    'x-session-access-key'?: string;
+}
+export interface SessionLinkParams {
+    /**
+     * The unique slug identifier of the toolkit to connect
+     */
+    toolkit: string;
+    /**
+     * URL where users will be redirected after completing auth
+     */
+    callback_url?: string;
+}
+export interface SessionToolkitsParams {
+    /**
+     * Cursor for pagination. The cursor is a base64 encoded string of the page and
+     * limit. The page is the page number and the limit is the number of items per
+     * page. The cursor is used to paginate through the items. The cursor is not
+     * required for the first page.
+     */
+    cursor?: string;
+    /**
+     * Number of items per page, max allowed is 1000
+     */
+    limit?: number | null;
+    /**
+     * Optional comma-separated list of toolkit slugs to filter by. If provided, only
+     * these toolkits will be returned, overriding the session configuration.
+     */
+    toolkits?: Array<string> | null;
+}
+export declare namespace Session {
+    export { type SessionCreateResponse as SessionCreateResponse, type SessionRetrieveResponse as SessionRetrieveResponse, type SessionExecuteResponse as SessionExecuteResponse, type SessionLinkResponse as SessionLinkResponse, type SessionToolkitsResponse as SessionToolkitsResponse, type SessionCreateParams as SessionCreateParams, type SessionExecuteParams as SessionExecuteParams, type SessionLinkParams as SessionLinkParams, type SessionToolkitsParams as SessionToolkitsParams, };
+}
+//# sourceMappingURL=session.d.ts.map