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

package/src/resources/tools.ts

@@ -7,15 +7,28 @@ import { path } from '../internal/utils/path';
 
 export class Tools extends APIResource {
   /**
-   * Retrieve detailed information about a specific tool using its slug identifier
+   * 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 list of available tools with optional filtering and search
-   * capabilities
+   * 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 = {},
@@ -25,7 +38,15 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Execute a specific tool operation with provided arguments and authentication
+   * 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,
@@ -35,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,
@@ -43,13 +77,32 @@ 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
+   * 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);
@@ -57,26 +110,53 @@ export class Tools extends APIResource {
 }
 
 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;
 }
 
@@ -94,10 +174,19 @@ export namespace ToolRetrieveResponse {
   }
 
   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;
   }
 }
@@ -115,37 +204,37 @@ export namespace ToolListResponse {
     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;
 
     /**
-     * Whether the tool requires authentication
+     * Indicates if the tool can be used without authentication
      */
     no_auth: boolean;
 
     /**
-     * The output parameters of the tool
+     * 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>;
 
@@ -155,7 +244,7 @@ export namespace ToolListResponse {
   export namespace Item {
     export interface Deprecated {
       /**
-       * The available versions of the tool
+       * List of all available versions for this tool
        */
       available_versions: Array<string>;
 
@@ -165,14 +254,14 @@ export namespace ToolListResponse {
       displayName: string;
 
       /**
-       * Whether the tool is deprecated
+       * Indicates if this tool is deprecated and may be removed in the future
        */
       is_deprecated: boolean;
 
       toolkit: Deprecated.Toolkit;
 
       /**
-       * The version of the tool
+       * Current version identifier of the tool
        */
       version: string;
     }
@@ -180,7 +269,7 @@ export namespace ToolListResponse {
     export namespace Deprecated {
       export interface Toolkit {
         /**
-         * The logo of the toolkit
+         * URL to the toolkit logo image
          */
         logo: string;
       }
@@ -188,12 +277,12 @@ export namespace ToolListResponse {
 
     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;
     }
@@ -201,69 +290,98 @@ 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;
 
   /**
-   * The tags to filter the tools by
+   * Filter tools by one or more tags (can be specified multiple times)
    */
-  tags?: Array<string> | null;
+  tags?: Array<string>;
 
   /**
-   * The slugs of the tools to filter by
+   * Comma-separated list of specific tool slugs to retrieve (overrides other
+   * filters)
    */
-  tool_slugs?: Array<string> | null;
+  tool_slugs?: string;
 
   /**
    * The slug of the toolkit to filter by
@@ -272,29 +390,49 @@ 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;
 
   /**
-   * An optional field for people who want to use their own auth to execute the
-   * action.
+   * 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 {
   /**
-   * An optional field for people who want to use their own auth to execute the
-   * action.
+   * Custom authentication parameters for tools that support parameterized
+   * authentication
    */
   export interface CustomAuthParams {
     parameters: Array<CustomAuthParams.Parameter>;
@@ -308,7 +446,7 @@ export namespace ToolExecuteParams {
 
     /**
      * The body to be sent to the endpoint for authentication. This is a JSON object.
-     * Note: This is very rarely neeed and is only required by very few apps.
+     * Note: This is very rarely needed and is only required by very few apps.
      */
     body?: Record<string, unknown>;
   }
@@ -335,44 +473,73 @@ export namespace ToolExecuteParams {
 
 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/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';

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

@@ -23,22 +23,9 @@ export class TriggerInstances extends APIResource {
     return this._client.get('/api/v3/trigger_instances/active', { query, ...options });
   }
 
-  removeUpsert(slug: string, options?: RequestOptions): APIPromise<TriggerInstanceRemoveUpsertResponse> {
-    return this._client.delete(path`/api/v3/trigger_instances/${slug}/upsert`, options);
-  }
-
-  updateStatus(
-    status: 'enable' | 'disable',
-    params: TriggerInstanceUpdateStatusParams,
-    options?: RequestOptions,
-  ): APIPromise<TriggerInstanceUpdateStatusResponse> {
-    const { slug } = params;
-    return this._client.patch(path`/api/v3/trigger_instances/${slug}/status/${status}`, options);
-  }
-
   upsert(
     slug: string,
-    body: TriggerInstanceUpsertParams,
+    body: TriggerInstanceUpsertParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<TriggerInstanceUpsertResponse> {
     return this._client.post(path`/api/v3/trigger_instances/${slug}/upsert`, { body, ...options });
@@ -119,25 +106,22 @@ export namespace TriggerInstanceListActiveResponse {
   }
 }
 
-export interface TriggerInstanceRemoveUpsertResponse {
+export interface TriggerInstanceUpsertResponse {
+  deprecated: TriggerInstanceUpsertResponse.Deprecated;
+
   /**
    * ID of the updated trigger
    */
   triggerId: string;
 }
 
-export interface TriggerInstanceUpdateStatusResponse {
-  /**
-   * Status of the operation
-   */
-  status: 'success';
-}
-
-export interface TriggerInstanceUpsertResponse {
-  /**
-   * ID of the updated trigger
-   */
-  triggerId: string;
+export namespace TriggerInstanceUpsertResponse {
+  export interface Deprecated {
+    /**
+     * ID of the updated trigger
+     */
+    uuid: string;
+  }
 }
 
 export interface TriggerInstanceListActiveParams {
@@ -187,23 +171,26 @@ export interface TriggerInstanceListActiveParams {
   triggerNames?: Array<string> | null;
 }
 
-export interface TriggerInstanceUpdateStatusParams {
+export interface TriggerInstanceUpsertParams {
   /**
-   * The slug of the trigger instance
+   * Connected account nanoid
    */
-  slug: string;
-}
+  connected_account_id?: string;
 
-export interface TriggerInstanceUpsertParams {
   /**
-   * Connection ID
+   * Connected account ID (deprecated)
    */
-  connectedAuthId: string;
+  connectedAuthId?: string;
 
   /**
    * Trigger configuration
    */
-  triggerConfig: Record<string, unknown>;
+  trigger_config?: Record<string, unknown>;
+
+  /**
+   * Trigger configuration (deprecated)
+   */
+  triggerConfig?: Record<string, unknown>;
 }
 
 TriggerInstances.Handle = Handle;
@@ -211,11 +198,8 @@ TriggerInstances.Handle = Handle;
 export declare namespace TriggerInstances {
   export {
     type TriggerInstanceListActiveResponse as TriggerInstanceListActiveResponse,
-    type TriggerInstanceRemoveUpsertResponse as TriggerInstanceRemoveUpsertResponse,
-    type TriggerInstanceUpdateStatusResponse as TriggerInstanceUpdateStatusResponse,
     type TriggerInstanceUpsertResponse as TriggerInstanceUpsertResponse,
     type TriggerInstanceListActiveParams as TriggerInstanceListActiveParams,
-    type TriggerInstanceUpdateStatusParams as TriggerInstanceUpdateStatusParams,
     type TriggerInstanceUpsertParams as TriggerInstanceUpsertParams,
   };