@composio/client 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/resources/tools.ts

@@ -6,10 +6,30 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class Tools extends APIResource {
+  /**
+   * Retrieve detailed information about a specific tool using its slug identifier.
+   * This endpoint returns full metadata about a tool including input/output
+   * parameters, versions, and toolkit information.
+   *
+   * @example
+   * ```ts
+   * const tool = await client.tools.retrieve('tool_slug');
+   * ```
+   */
   retrieve(toolSlug: string, options?: RequestOptions): APIPromise<ToolRetrieveResponse> {
     return this._client.get(path`/api/v3/tools/${toolSlug}`, options);
   }
 
+  /**
+   * Retrieve a paginated list of available tools with comprehensive filtering,
+   * sorting and search capabilities. Use query parameters to narrow down results by
+   * toolkit, tags, or search terms.
+   *
+   * @example
+   * ```ts
+   * const tools = await client.tools.list();
+   * ```
+   */
   list(
     query: ToolListParams | null | undefined = {},
     options?: RequestOptions,
@@ -17,6 +37,17 @@ export class Tools extends APIResource {
     return this._client.get('/api/v3/tools', { query, ...options });
   }
 
+  /**
+   * Execute a specific tool operation with provided arguments and authentication.
+   * This is the primary endpoint for integrating with third-party services and
+   * executing tools. You can provide structured arguments or use natural language
+   * processing by providing a text description of what you want to accomplish.
+   *
+   * @example
+   * ```ts
+   * const response = await client.tools.execute('action');
+   * ```
+   */
   execute(
     action: string,
     body: ToolExecuteParams | null | undefined = {},
@@ -25,6 +56,19 @@ export class Tools extends APIResource {
     return this._client.post(path`/api/v3/tools/execute/${action}`, { body, ...options });
   }
 
+  /**
+   * Uses AI to translate a natural language description into structured arguments
+   * for a specific tool. This endpoint is useful when you want to let users describe
+   * what they want to do in plain language instead of providing structured
+   * parameters.
+   *
+   * @example
+   * ```ts
+   * const response = await client.tools.getInput('actionName', {
+   *   text: 'I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production',
+   * });
+   * ```
+   */
   getInput(
     actionName: string,
     body: ToolGetInputParams,
@@ -33,41 +77,116 @@ export class Tools extends APIResource {
     return this._client.post(path`/api/v3/tools/execute/${actionName}/input`, { body, ...options });
   }
 
+  /**
+   * Proxy an HTTP request to a third-party API using connected account credentials.
+   * This endpoint allows making authenticated API calls to external services while
+   * abstracting away authentication details.
+   *
+   * @example
+   * ```ts
+   * const response = await client.tools.proxy({
+   *   endpoint: '/api/v1/resources',
+   *   method: 'GET',
+   * });
+   * ```
+   */
   proxy(body: ToolProxyParams, options?: RequestOptions): APIPromise<ToolProxyResponse> {
     return this._client.post('/api/v3/tools/execute/proxy', { body, ...options });
   }
 
+  /**
+   * Retrieve a list of all available tool enumeration values (tool slugs) for the
+   * project. This endpoint returns a comma-separated string of tool slugs that can
+   * be used in other API calls.
+   *
+   * @example
+   * ```ts
+   * const response = await client.tools.retrieveEnum();
+   * ```
+   */
   retrieveEnum(options?: RequestOptions): APIPromise<string> {
     return this._client.get('/api/v3/tools/enum', options);
   }
 }
 
 export interface ToolRetrieveResponse {
+  /**
+   * List of all available versions for this tool
+   */
   available_versions: Array<string>;
 
+  deprecated: ToolRetrieveResponse.Deprecated;
+
+  /**
+   * Detailed description of what the tool does
+   */
   description: string;
 
+  /**
+   * Schema definition of required input parameters for the tool
+   */
   input_parameters: Record<string, unknown>;
 
+  /**
+   * Human-readable name of the tool
+   */
   name: string;
 
+  /**
+   * Indicates if the tool can be used without authentication
+   */
+  no_auth: boolean;
+
+  /**
+   * Schema definition of return values from the tool
+   */
   output_parameters: Record<string, unknown>;
 
+  /**
+   * Unique identifier for the tool
+   */
   slug: string;
 
+  /**
+   * List of tags associated with the tool for categorization
+   */
   tags: Array<string>;
 
   toolkit: ToolRetrieveResponse.Toolkit;
 
+  /**
+   * Current version of the tool
+   */
   version: string;
 }
 
 export namespace ToolRetrieveResponse {
+  export interface Deprecated {
+    /**
+     * The display name of the tool
+     */
+    displayName: string;
+
+    /**
+     * Whether the action is deprecated
+     */
+    is_deprecated: boolean;
+  }
+
   export interface Toolkit {
+    /**
+     * URL to the toolkit logo image
+     */
     logo: string;
 
+    /**
+     * Human-readable name of the parent toolkit
+     */
     name: string;
 
+    /**
+     * Unique identifier of the parent toolkit
+     */
     slug: string;
   }
 }
@@ -82,33 +201,40 @@ export interface ToolListResponse {
 
 export namespace ToolListResponse {
   export interface Item {
+    deprecated: Item.Deprecated;
+
     /**
-     * The description of the tool
+     * Detailed explanation of the tool's functionality and purpose
      */
     description: string;
 
     /**
-     * The input parameters of the tool
+     * Schema definition of required input parameters for the tool
      */
     input_parameters: Record<string, unknown>;
 
     /**
-     * The name of the tool
+     * Human-readable display name of the tool
      */
     name: string;
 
     /**
-     * The output parameters of the tool
+     * Indicates if the tool can be used without authentication
+     */
+    no_auth: boolean;
+
+    /**
+     * Schema definition of return values from the tool
      */
     output_parameters: Record<string, unknown>;
 
     /**
-     * The slug of the tool
+     * Unique identifier for the tool
      */
     slug: string;
 
     /**
-     * The tags of the tool
+     * List of tags associated with the tool for categorization and filtering
      */
     tags: Array<string>;
 
@@ -116,14 +242,47 @@ export namespace ToolListResponse {
   }
 
   export namespace Item {
+    export interface Deprecated {
+      /**
+       * List of all available versions for this tool
+       */
+      available_versions: Array<string>;
+
+      /**
+       * The display name of the tool
+       */
+      displayName: string;
+
+      /**
+       * Indicates if this tool is deprecated and may be removed in the future
+       */
+      is_deprecated: boolean;
+
+      toolkit: Deprecated.Toolkit;
+
+      /**
+       * Current version identifier of the tool
+       */
+      version: string;
+    }
+
+    export namespace Deprecated {
+      export interface Toolkit {
+        /**
+         * URL to the toolkit logo image
+         */
+        logo: string;
+      }
+    }
+
     export interface Toolkit {
       /**
-       * The name of the toolkit
+       * Human-readable name of the parent toolkit
        */
       name: string;
 
       /**
-       * The slug of the toolkit
+       * Unique identifier of the parent toolkit
        */
       slug: string;
     }
@@ -131,60 +290,99 @@ export namespace ToolListResponse {
 }
 
 export interface ToolExecuteResponse {
+  /**
+   * Tool execution output data that varies based on the specific tool
+   */
   data: Record<string, unknown>;
 
+  /**
+   * Error message if the tool execution was not successful (null if successful)
+   */
   error: string | null;
 
+  /**
+   * Indicates if the tool execution was successful
+   */
   successful: boolean;
 
+  /**
+   * Unique identifier for the execution log (useful for debugging and support)
+   */
   log_id?: string;
 
+  /**
+   * Optional session information for tools that return session context
+   */
   session_info?: unknown;
 }
 
 export interface ToolGetInputResponse {
   /**
-   * The arguments for the action needed to execute the given task.
+   * Key-value pairs of arguments required by the tool to accomplish the described
+   * task
    */
   arguments?: Record<string, unknown>;
 
   /**
-   * The error message if the arguments were not generated successfully.
+   * Error message if the arguments could not be generated (null if successful)
    */
   error?: string;
 }
 
 export interface ToolProxyResponse {
+  /**
+   * The HTTP status code returned from the proxied API
+   */
   status: number;
 
+  /**
+   * The response data returned from the proxied API
+   */
   data?: unknown;
 
+  /**
+   * The HTTP headers returned from the proxied API
+   */
   headers?: Record<string, string>;
 }
 
+/**
+ * Comma-separated list of tool slugs available to the project
+ */
 export type ToolRetrieveEnumResponse = string;
 
 export interface ToolListParams {
   /**
-   * The cursor to paginate through the results
+   * Pagination cursor for fetching next page of results (base64 encoded)
    */
   cursor?: string;
 
   /**
-   * Whether to filter by important tools
+   * Filter to only show important/featured tools (set to "true" to enable)
    */
-  important?: string;
+  important?: 'true' | 'false';
 
   /**
-   * The number of results to return
+   * Maximum number of tools to return per page (defaults to 20, max 100)
    */
   limit?: string;
 
   /**
-   * The search query to filter by
+   * Free-text search query to find tools by name, description, or functionality
    */
   search?: string;
 
+  /**
+   * Filter tools by one or more tags (can be specified multiple times)
+   */
+  tags?: Array<string>;
+
+  /**
+   * Comma-separated list of specific tool slugs to retrieve (overrides other
+   * filters)
+   */
+  tool_slugs?: string;
+
   /**
    * The slug of the toolkit to filter by
    */
@@ -192,59 +390,156 @@ export interface ToolListParams {
 }
 
 export interface ToolExecuteParams {
+  /**
+   * Enable debug tracing for tool execution (useful for debugging)
+   */
   allow_tracing?: boolean;
 
+  /**
+   * Key-value pairs of arguments required by the tool (mutually exclusive with text)
+   */
   arguments?: Record<string, unknown>;
 
+  /**
+   * Unique identifier for the connected account to use for authentication
+   */
   connected_account_id?: string;
 
+  /**
+   * Custom authentication parameters for tools that support parameterized
+   * authentication
+   */
+  custom_auth_params?: ToolExecuteParams.CustomAuthParams;
+
+  /**
+   * Entity identifier for multi-entity connected accounts (e.g. multiple
+   * repositories, organizations)
+   */
   entity_id?: string;
 
+  /**
+   * Natural language description of the task to perform (mutually exclusive with
+   * arguments)
+   */
   text?: string;
 
+  /**
+   * Tool version to execute (defaults to "latest" if not specified)
+   */
   version?: string;
 }
 
+export namespace ToolExecuteParams {
+  /**
+   * Custom authentication parameters for tools that support parameterized
+   * authentication
+   */
+  export interface CustomAuthParams {
+    parameters: Array<CustomAuthParams.Parameter>;
+
+    /**
+     * The base URL (root address) what you should use while making http requests to
+     * the connected account. For example, for gmail, it would be
+     * 'https://gmail.googleapis.com'
+     */
+    base_url?: string;
+
+    /**
+     * The body to be sent to the endpoint for authentication. This is a JSON object.
+     * Note: This is very rarely needed and is only required by very few apps.
+     */
+    body?: Record<string, unknown>;
+  }
+
+  export namespace CustomAuthParams {
+    export interface Parameter {
+      /**
+       * The location of the parameter. Can be 'query' or 'header'.
+       */
+      in: 'query' | 'header';
+
+      /**
+       * The name of the parameter. For example, 'x-api-key', 'Content-Type', etc.
+       */
+      name: string;
+
+      /**
+       * The value of the parameter. For example, '1234567890', 'application/json', etc.
+       */
+      value: string | number;
+    }
+  }
+}
+
 export interface ToolGetInputParams {
   /**
-   * The use-case description for the action, this will give context to LLM to
-   * generate the correct inputs for the action.
+   * Natural language description of what you want to accomplish with this tool
    */
   text: string;
 
   /**
-   * The custom description for the action, use this to provide customised context
-   * about the action to the LLM to suit your use-case.
+   * Custom description of the tool to help guide the LLM in generating more accurate
+   * inputs
    */
   customDescription?: string;
 
   /**
-   * The system prompt to be used by LLM, use this to control and guide the behaviour
-   * of the LLM.
+   * System prompt to control and guide the behavior of the LLM when generating
+   * inputs
    */
   systemPrompt?: string;
 
+  /**
+   * Tool version to use when generating inputs (defaults to "latest" if not
+   * specified)
+   */
   version?: string;
 }
 
 export interface ToolProxyParams {
+  /**
+   * The API endpoint to call (absolute URL or path relative to base URL of the
+   * connected account)
+   */
   endpoint: string;
 
+  /**
+   * The HTTP method to use for the request
+   */
   method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
+  /**
+   * The request body (for POST, PUT, and PATCH requests)
+   */
   body?: unknown;
 
+  /**
+   * The ID of the connected account to use for authentication (if not provided, will
+   * use the default account for the project)
+   */
   connected_account_id?: string;
 
+  /**
+   * Additional HTTP headers or query parameters to include in the request
+   */
   parameters?: Array<ToolProxyParams.Parameter>;
 }
 
 export namespace ToolProxyParams {
   export interface Parameter {
+    /**
+     * Parameter name
+     */
     name: string;
 
+    /**
+     * Parameter type (header or query)
+     */
     type: 'header' | 'query';
 
+    /**
+     * Parameter value
+     */
     value: string;
   }
 }

package/src/resources/trigger-instances/handle.ts

@@ -6,12 +6,20 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 export class Handle extends APIResource {
-  retrieve(projectID: string, params: HandleRetrieveParams, options?: RequestOptions): APIPromise<string> {
+  retrieve(
+    projectID: (string & {}) | 'default',
+    params: HandleRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<string> {
     const { slug } = params;
     return this._client.get(path`/api/v3/trigger_instances/${slug}/${projectID}/handle`, options);
   }
 
-  execute(projectID: string, params: HandleExecuteParams, options?: RequestOptions): APIPromise<string> {
+  execute(
+    projectID: (string & {}) | 'default',
+    params: HandleExecuteParams,
+    options?: RequestOptions,
+  ): APIPromise<string> {
     const { slug } = params;
     return this._client.post(path`/api/v3/trigger_instances/${slug}/${projectID}/handle`, options);
   }

package/src/resources/trigger-instances/index.ts

@@ -10,10 +10,7 @@ export {
 export {
   TriggerInstances,
   type TriggerInstanceListActiveResponse,
-  type TriggerInstanceRemoveUpsertResponse,
-  type TriggerInstanceUpdateStatusResponse,
   type TriggerInstanceUpsertResponse,
   type TriggerInstanceListActiveParams,
-  type TriggerInstanceUpdateStatusParams,
   type TriggerInstanceUpsertParams,
 } from './trigger-instances';