@composio/client 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/resources/toolkits.ts

@@ -5,82 +5,251 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * Toolkit and tool management
+ */
 export class Toolkits extends APIResource {
-  retrieve(slug: string, options?: RequestOptions): APIPromise<ToolkitRetrieveResponse> {
-    return this._client.get(path`/api/v3/toolkits/${slug}`, options);
+  /**
+   * 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,
+    query: ToolkitRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ToolkitRetrieveResponse> {
+    return this._client.get(path`/api/v3.1/toolkits/${slug}`, { query, ...options });
   }
 
+  /**
+   * Retrieves a comprehensive list of toolkits of their latest versions 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 and management type,
+   * as well as different sorting options.
+   */
   list(
     query: ToolkitListParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<ToolkitListResponse> {
-    return this._client.get('/api/v3/toolkits', { query, ...options });
+    return this._client.get('/api/v3.1/toolkits', { query, ...options });
   }
 
+  /**
+   * Retrieves a comprehensive list of all available toolkit categories from their
+   * latest versions. 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);
+    return this._client.get('/api/v3.1/toolkits/categories', options);
   }
 }
 
+/**
+ * Detailed information about a single toolkit
+ */
 export interface ToolkitRetrieveResponse {
+  deprecated: ToolkitRetrieveResponse.Deprecated;
+
+  /**
+   * Indicates if this toolkit is currently enabled and available for use
+   */
   enabled: boolean;
 
+  /**
+   * @deprecated DEPRECATED: This field is no longer meaningful and will always
+   * return false. It was previously used to indicate if a toolkit is specific to the
+   * current project.
+   */
   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>;
 
+  /**
+   * URL to a guide page with authentication setup instructions for this toolkit
+   */
+  auth_guide_url?: string | null;
+
+  /**
+   * If evaluation of base URL needs some connection info (like shopify), please
+   * create the connection and get the base URL from there
+   */
+  base_url?: string;
+
+  /**
+   * List of authentication methods that Composio manages for this toolkit
+   */
   composio_managed_auth_schemes?: Array<string>;
+
+  /**
+   * Endpoint to get the current user
+   */
+  get_current_user_endpoint?: string;
+
+  /**
+   * HTTP method to use when calling the get current user endpoint (e.g., GET, POST)
+   */
+  get_current_user_endpoint_method?: string;
 }
 
 export namespace ToolkitRetrieveResponse {
+  export interface Deprecated {
+    rawProxyInfoByAuthSchemes: Array<{ [key: string]: unknown }>;
+
+    toolkitId: string;
+
+    getCurrentUserEndpoint?: string;
+  }
+
+  /**
+   * Comprehensive metadata for the toolkit including dates, descriptions, and
+   * statistics
+   */
   export interface Meta {
+    /**
+     * Available versions of the toolkit
+     */
+    available_versions: Array<string>;
+
+    /**
+     * 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;
+
+    /**
+     * Version of the toolkit
+     */
+    version: 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;
 
+    /**
+     * URL to a page where users can obtain or configure credentials for this
+     * authentication method
+     */
+    auth_hint_url?: string | null;
+
+    /**
+     * @deprecated Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't
+     * recommend using this field for authentication and might break post Aug 31 2025.
+     */
+    deprecated_auth_provider_details?: AuthConfigDetail.DeprecatedAuthProviderDetails;
+
+    /**
+     * 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>;
 
@@ -89,26 +258,42 @@ export namespace ToolkitRetrieveResponse {
 
       export namespace AuthConfigCreation {
         export interface Optional {
+          description: string;
+
           displayName: string;
 
           name: string;
 
+          required: boolean;
+
           type: string;
 
           default?: string | null;
+
+          legacy_template_name?: string;
         }
 
         export interface Required {
+          description: string;
+
           displayName: string;
 
           name: string;
 
+          required: boolean;
+
           type: string;
 
           default?: string | null;
+
+          legacy_template_name?: string;
         }
       }
 
+      /**
+       * Form fields needed when connecting a user account with this authentication
+       * method
+       */
       export interface ConnectedAccountInitiation {
         optional: Array<ConnectedAccountInitiation.Optional>;
 
@@ -117,79 +302,194 @@ export namespace ToolkitRetrieveResponse {
 
       export namespace ConnectedAccountInitiation {
         export interface Optional {
+          description: string;
+
           displayName: string;
 
           name: string;
 
+          required: boolean;
+
           type: string;
 
           default?: string | null;
+
+          legacy_template_name?: string;
         }
 
         export interface Required {
+          description: string;
+
           displayName: string;
 
           name: string;
 
+          required: boolean;
+
           type: string;
 
           default?: string | null;
+
+          legacy_template_name?: string;
         }
       }
     }
 
+    /**
+     * @deprecated Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't
+     * recommend using this field for authentication and might break post Aug 31 2025.
+     */
+    export interface DeprecatedAuthProviderDetails {
+      authorization_url?: string;
+
+      token_url?: string;
+    }
+
+    /**
+     * Configuration for proxying authentication requests to external services
+     */
     export interface Proxy {
+      /**
+       * URL to which authentication requests will be proxied
+       */
       base_url: string;
     }
   }
 }
 
 export interface ToolkitListResponse {
+  current_page: number;
+
   items: Array<ToolkitListResponse.Item>;
 
-  next_cursor: string | null;
+  total_items: number;
 
   total_pages: number;
+
+  next_cursor?: string | null;
 }
 
 export namespace ToolkitListResponse {
+  /**
+   * Detailed information about a toolkit
+   */
   export interface Item {
+    /**
+     * @deprecated Deprecated toolkit ID
+     */
+    deprecated: Item.Deprecated;
+
+    /**
+     * @deprecated DEPRECATED: This field is no longer meaningful and will always
+     * return false. It was previously used to indicate if a toolkit is specific to the
+     * current project.
+     */
     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;
 
+    /**
+     * URL to a guide page with authentication setup instructions for this toolkit
+     */
+    auth_guide_url?: string | null;
+
+    /**
+     * 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 {
+    /**
+     * @deprecated Deprecated toolkit ID
+     */
+    export interface Deprecated {
+      toolkitId: string;
+    }
+
+    /**
+     * 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;
+
+      /**
+       * Version of the toolkit
+       */
+      version: 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;
       }
     }
@@ -197,28 +497,78 @@ export namespace ToolkitListResponse {
 }
 
 export interface ToolkitRetrieveCategoriesResponse {
+  current_page: number;
+
   items: Array<ToolkitRetrieveCategoriesResponse.Item>;
 
-  next_cursor: string | null;
+  total_items: number;
 
   total_pages: number;
+
+  next_cursor?: string | null;
 }
 
 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 ToolkitRetrieveParams {
+  /**
+   * Version of the toolkit
+   */
+  version?: string;
+}
+
 export interface ToolkitListParams {
+  /**
+   * Filter toolkits by category
+   */
   category?: string;
 
-  is_local?: boolean;
-
-  managed_by?: 'all' | 'composio_managed' | 'project_managed';
-
+  /**
+   * 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;
+
+  /**
+   * Include deprecated toolkits in the response
+   */
+  include_deprecated?: boolean | null;
+
+  /**
+   * Number of items per page, max allowed is 1000
+   */
+  limit?: number | null;
+
+  /**
+   * Filter toolkits by who manages them
+   */
+  managed_by?: 'composio' | 'all' | 'project';
+
+  /**
+   * Search query to filter toolkits by name, slug, or description
+   */
+  search?: string;
+
+  /**
+   * Sort order for returned toolkits
+   */
   sort_by?: 'usage' | 'alphabetically';
 }
 
@@ -227,6 +577,7 @@ export declare namespace Toolkits {
     type ToolkitRetrieveResponse as ToolkitRetrieveResponse,
     type ToolkitListResponse as ToolkitListResponse,
     type ToolkitRetrieveCategoriesResponse as ToolkitRetrieveCategoriesResponse,
+    type ToolkitRetrieveParams as ToolkitRetrieveParams,
     type ToolkitListParams as ToolkitListParams,
   };
 }