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

package/src/resources/toolkits.ts

@@ -7,15 +7,20 @@ import { path } from '../internal/utils/path';
 
 export class Toolkits extends APIResource {
   /**
-   * Retrieve detailed information about a specific toolkit using its slug identifier
+   * Retrieves comprehensive information about a specific toolkit using its unique
+   * slug identifier. This endpoint provides detailed metadata, authentication
+   * configuration options, and feature counts for the requested toolkit.
    */
   retrieve(slug: string, options?: RequestOptions): APIPromise<ToolkitRetrieveResponse> {
     return this._client.get(path`/api/v3/toolkits/${slug}`, options);
   }
 
   /**
-   * Retrieve a list of available toolkits with optional filtering and sorting
-   * options
+   * Retrieves a comprehensive list of toolkits that are available to the
+   * authenticated project. Toolkits represent integration points with external
+   * services and applications, each containing a collection of tools and triggers.
+   * This endpoint supports filtering by category, management type, and local
+   * availability, as well as different sorting options.
    */
   list(
     query: ToolkitListParams | null | undefined = {},
@@ -25,74 +30,168 @@ export class Toolkits extends APIResource {
   }
 
   /**
-   * Retrieve a list of all available toolkit categories for filtering toolkits
+   * Retrieves a comprehensive list of all available toolkit categories. These
+   * categories can be used to filter toolkits by type or purpose when using the
+   * toolkit listing endpoint. Categories help organize toolkits into logical groups
+   * based on their functionality or industry focus.
    */
-  retrieveCategories(options?: RequestOptions): APIPromise<ToolkitRetrieveCategoriesResponse> {
-    return this._client.get('/api/v3/toolkits/categories', options);
+  retrieveCategories(
+    query: ToolkitRetrieveCategoriesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ToolkitRetrieveCategoriesResponse> {
+    return this._client.get('/api/v3/toolkits/categories', { query, ...options });
   }
 }
 
+/**
+ * Detailed information about a single toolkit
+ */
 export interface ToolkitRetrieveResponse {
+  /**
+   * Indicates if this toolkit is currently enabled and available for use
+   */
   enabled: boolean;
 
+  /**
+   * Indicates if this toolkit is specific to the current project or globally
+   * available
+   */
   is_local_toolkit: boolean;
 
+  /**
+   * Comprehensive metadata for the toolkit including dates, descriptions, and
+   * statistics
+   */
   meta: ToolkitRetrieveResponse.Meta;
 
+  /**
+   * Human-readable name of the toolkit
+   */
   name: string;
 
+  /**
+   * URL-friendly unique identifier for the toolkit
+   */
   slug: string;
 
+  /**
+   * Complete authentication configuration details for each supported auth method
+   */
   auth_config_details?: Array<ToolkitRetrieveResponse.AuthConfigDetail>;
 
+  /**
+   * List of authentication methods that Composio manages for this toolkit
+   */
   composio_managed_auth_schemes?: Array<string>;
 }
 
 export namespace ToolkitRetrieveResponse {
+  /**
+   * Comprehensive metadata for the toolkit including dates, descriptions, and
+   * statistics
+   */
   export interface Meta {
+    /**
+     * List of categories associated with this toolkit
+     */
     categories: Array<Meta.Category>;
 
+    /**
+     * Creation date and time of the toolkit
+     */
     created_at: string;
 
+    /**
+     * Human-readable description explaining the toolkit's purpose and functionality
+     */
     description: string;
 
+    /**
+     * Image URL for the toolkit's branding
+     */
     logo: string;
 
+    /**
+     * Count of available tools in this toolkit
+     */
     tools_count: number;
 
+    /**
+     * Count of available triggers in this toolkit
+     */
     triggers_count: number;
 
+    /**
+     * Last modification date and time of the toolkit
+     */
     updated_at: string;
 
+    /**
+     * Link to the toolkit's main application or service website
+     */
     app_url?: string | null;
   }
 
   export namespace Meta {
     export interface Category {
+      /**
+       * Human-readable category name
+       */
       name: string;
 
+      /**
+       * URL-friendly identifier for the category
+       */
       slug: string;
     }
   }
 
+  /**
+   * Detailed configuration for an authentication method
+   */
   export interface AuthConfigDetail {
+    /**
+     * Field groups required for different authentication stages
+     */
     fields: AuthConfigDetail.Fields;
 
+    /**
+     * The type of authentication mode (e.g., oauth2, basic_auth, api_key)
+     */
     mode: string;
 
+    /**
+     * Display name for this authentication method
+     */
     name: string;
 
+    /**
+     * Configuration for proxying authentication requests to external services
+     */
     proxy?: AuthConfigDetail.Proxy;
   }
 
   export namespace AuthConfigDetail {
+    /**
+     * Field groups required for different authentication stages
+     */
     export interface Fields {
+      /**
+       * Form fields needed when creating an authentication configuration
+       */
       auth_config_creation: Fields.AuthConfigCreation;
 
+      /**
+       * Form fields needed when connecting a user account with this authentication
+       * method
+       */
       connected_account_initiation: Fields.ConnectedAccountInitiation;
     }
 
     export namespace Fields {
+      /**
+       * Form fields needed when creating an authentication configuration
+       */
       export interface AuthConfigCreation {
         optional: Array<AuthConfigCreation.Optional>;
 
@@ -129,6 +228,10 @@ export namespace ToolkitRetrieveResponse {
         }
       }
 
+      /**
+       * Form fields needed when connecting a user account with this authentication
+       * method
+       */
       export interface ConnectedAccountInitiation {
         optional: Array<ConnectedAccountInitiation.Optional>;
 
@@ -166,7 +269,13 @@ export namespace ToolkitRetrieveResponse {
       }
     }
 
+    /**
+     * Configuration for proxying authentication requests to external services
+     */
     export interface Proxy {
+      /**
+       * URL to which authentication requests will be proxied
+       */
       base_url: string;
     }
   }
@@ -181,45 +290,103 @@ export interface ToolkitListResponse {
 }
 
 export namespace ToolkitListResponse {
+  /**
+   * Detailed information about a toolkit
+   */
   export interface Item {
+    /**
+     * Indicates if this toolkit is specific to the current project or globally
+     * available
+     */
     is_local_toolkit: boolean;
 
+    /**
+     * Additional metadata about the toolkit
+     */
     meta: Item.Meta;
 
+    /**
+     * Human-readable name of the toolkit
+     */
     name: string;
 
+    /**
+     * URL-friendly unique identifier for the toolkit
+     */
     slug: string;
 
+    /**
+     * List of authentication methods supported by this toolkit
+     */
     auth_schemes?: Array<string>;
 
+    /**
+     * List of authentication methods that Composio manages for this toolkit
+     */
     composio_managed_auth_schemes?: Array<string>;
 
+    /**
+     * When true, this toolkit can be used without authentication
+     */
     no_auth?: boolean;
   }
 
   export namespace Item {
+    /**
+     * Additional metadata about the toolkit
+     */
     export interface Meta {
+      /**
+       * List of categories associated with this toolkit
+       */
       categories: Array<Meta.Category>;
 
+      /**
+       * Creation date and time of the toolkit
+       */
       created_at: string;
 
+      /**
+       * Human-readable description explaining the toolkit's purpose and functionality
+       */
       description: string;
 
+      /**
+       * Image URL for the toolkit's branding
+       */
       logo: string;
 
+      /**
+       * Count of available tools in this toolkit
+       */
       tools_count: number;
 
+      /**
+       * Count of available triggers in this toolkit
+       */
       triggers_count: number;
 
+      /**
+       * Last modification date and time of the toolkit
+       */
       updated_at: string;
 
+      /**
+       * Link to the toolkit's main application or service website
+       */
       app_url?: string | null;
     }
 
     export namespace Meta {
       export interface Category {
+        /**
+         * Category identifier
+         */
         id: string;
 
+        /**
+         * Human-readable category name
+         */
         name: string;
       }
     }
@@ -235,31 +402,57 @@ export interface ToolkitRetrieveCategoriesResponse {
 }
 
 export namespace ToolkitRetrieveCategoriesResponse {
+  /**
+   * Information about a single toolkit category
+   */
   export interface Item {
+    /**
+     * URL-friendly unique identifier for the category, used for filtering toolkits
+     */
     id: string;
 
+    /**
+     * Display name of the toolkit category
+     */
     name: string;
   }
 }
 
 export interface ToolkitListParams {
+  /**
+   * Filter toolkits by category
+   */
   category?: string;
 
   /**
-   * Whether to include local toolkits
+   * Whether to include local toolkits in the results
    */
   is_local?: boolean | null;
 
+  /**
+   * Filter toolkits by who manages them
+   */
   managed_by?: 'composio' | 'all' | 'project';
 
+  /**
+   * Sort order for returned toolkits
+   */
   sort_by?: 'usage' | 'alphabetically';
 }
 
+export interface ToolkitRetrieveCategoriesParams {
+  /**
+   * Cache control parameter
+   */
+  cache?: string;
+}
+
 export declare namespace Toolkits {
   export {
     type ToolkitRetrieveResponse as ToolkitRetrieveResponse,
     type ToolkitListResponse as ToolkitListResponse,
     type ToolkitRetrieveCategoriesResponse as ToolkitRetrieveCategoriesResponse,
     type ToolkitListParams as ToolkitListParams,
+    type ToolkitRetrieveCategoriesParams as ToolkitRetrieveCategoriesParams,
   };
 }