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

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

@@ -0,0 +1,858 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export 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> {
+    return this._client.post('/api/v3/tool_router/session', { body, ...options });
+  }
+
+  /**
+   * 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> {
+    return this._client.get(path`/api/v3/tool_router/session/${sessionID}`, options);
+  }
+
+  /**
+   * 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> {
+    const { 'x-session-access-key': xSessionAccessKey, ...body } = params;
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(xSessionAccessKey != null ? { 'x-session-access-key': xSessionAccessKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/link`, { body, ...options });
+  }
+
+  /**
+   * 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> {
+    return this._client.get(path`/api/v3/tool_router/session/${sessionID}/toolkits`, { query, ...options });
+  }
+}
+
+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 namespace SessionCreateResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  export 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;
+  }
+
+  export namespace Config {
+    /**
+     * Connections configuration
+     */
+    export 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
+     */
+    export 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;
+    }
+
+    export interface Enabled {
+      enabled: Array<string>;
+    }
+
+    export interface Disabled {
+      disabled: Array<string>;
+    }
+
+    /**
+     * Tools configuration
+     */
+    export interface Tools {
+      /**
+       * Tool filtering configuration
+       */
+      filters?: Tools.Filters;
+
+      /**
+       * Tool-level overrides per toolkit
+       */
+      overrides?: { [key: string]: Tools.Enabled | Tools.Disabled };
+    }
+
+    export namespace Tools {
+      /**
+       * Tool filtering configuration
+       */
+      export interface Filters {
+        /**
+         * Filter tools by specific tags
+         */
+        tags?: Filters.Tags;
+      }
+
+      export namespace Filters {
+        /**
+         * Filter tools by specific tags
+         */
+        export interface Tags {
+          /**
+           * Exclude tools that have these tags
+           */
+          exclude?: Array<string>;
+
+          /**
+           * Only include tools that have these tags
+           */
+          include?: Array<string>;
+        }
+      }
+
+      export interface Enabled {
+        enabled: Array<string>;
+      }
+
+      export interface Disabled {
+        disabled: Array<string>;
+      }
+    }
+  }
+
+  export 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 namespace SessionRetrieveResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  export 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;
+  }
+
+  export namespace Config {
+    /**
+     * Connections configuration
+     */
+    export 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
+     */
+    export 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;
+    }
+
+    export interface Enabled {
+      enabled: Array<string>;
+    }
+
+    export interface Disabled {
+      disabled: Array<string>;
+    }
+
+    /**
+     * Tools configuration
+     */
+    export interface Tools {
+      /**
+       * Tool filtering configuration
+       */
+      filters?: Tools.Filters;
+
+      /**
+       * Tool-level overrides per toolkit
+       */
+      overrides?: { [key: string]: Tools.Enabled | Tools.Disabled };
+    }
+
+    export namespace Tools {
+      /**
+       * Tool filtering configuration
+       */
+      export interface Filters {
+        /**
+         * Filter tools by specific tags
+         */
+        tags?: Filters.Tags;
+      }
+
+      export namespace Filters {
+        /**
+         * Filter tools by specific tags
+         */
+        export interface Tags {
+          /**
+           * Exclude tools that have these tags
+           */
+          exclude?: Array<string>;
+
+          /**
+           * Only include tools that have these tags
+           */
+          include?: Array<string>;
+        }
+      }
+
+      export interface Enabled {
+        enabled: Array<string>;
+      }
+
+      export interface Disabled {
+        disabled: Array<string>;
+      }
+    }
+  }
+
+  export 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 namespace SessionToolkitsResponse {
+  export 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;
+  }
+
+  export namespace Item {
+    /**
+     * Connected account if available
+     */
+    export 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;
+    }
+
+    export namespace ConnectedAccount {
+      /**
+       * Auth config details
+       */
+      export 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
+     */
+    export 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 namespace SessionCreateParams {
+  /**
+   * Configuration for authentication and connected account management
+   */
+  export 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
+   */
+  export 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)
+   */
+  export interface Enabled {
+    /**
+     * Only these specific toolkits will be enabled
+     */
+    enabled: Array<string>;
+  }
+
+  /**
+   * Disable specific toolkits (denylist)
+   */
+  export interface Disabled {
+    /**
+     * These specific toolkits will be disabled
+     */
+    disabled: Array<string>;
+  }
+
+  /**
+   * Configuration for tool overrides and filtering
+   */
+  export 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 };
+  }
+
+  export namespace Tools {
+    /**
+     * Configuration for filtering available tools based on tags and characteristics
+     */
+    export 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;
+    }
+
+    export 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.
+       */
+      export 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>;
+      }
+    }
+
+    export interface Enabled {
+      /**
+       * Only these specific tools will be available for this toolkit
+       */
+      enabled: Array<string>;
+    }
+
+    export 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,
+  };
+}