@composio/client 0.1.0-alpha.6 → 0.1.0-alpha.60

package/src/resources/auth-configs.ts

@@ -6,22 +6,65 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class AuthConfigs extends APIResource {
+  /**
+   * Creates a new auth config for a toolkit, allowing you to use your own OAuth
+   * credentials or API keys instead of Composio-managed authentication. This is
+   * required when you want to use custom OAuth apps (bring your own client
+   * ID/secret) or configure specific authentication parameters for a toolkit.
+   *
+   * @example
+   * ```ts
+   * const authConfig = await client.authConfigs.create({
+   *   toolkit: { slug: 'slug' },
+   * });
+   * ```
+   */
   create(body: AuthConfigCreateParams, options?: RequestOptions): APIPromise<AuthConfigCreateResponse> {
     return this._client.post('/api/v3/auth_configs', { body, ...options });
   }
 
+  /**
+   * Retrieves detailed information about a specific authentication configuration
+   * using its unique identifier.
+   *
+   * @example
+   * ```ts
+   * const authConfig = await client.authConfigs.retrieve(
+   *   'nanoid',
+   * );
+   * ```
+   */
   retrieve(nanoid: string, options?: RequestOptions): APIPromise<AuthConfigRetrieveResponse> {
     return this._client.get(path`/api/v3/auth_configs/${nanoid}`, options);
   }
 
-  update(
-    nanoid: string,
-    body: AuthConfigUpdateParams,
-    options?: RequestOptions,
-  ): APIPromise<AuthConfigUpdateResponse> {
+  /**
+   * Modifies an existing authentication configuration with new credentials or other
+   * settings. Only specified fields will be updated.
+   *
+   * @example
+   * ```ts
+   * const authConfig = await client.authConfigs.update(
+   *   'nanoid',
+   *   { type: 'custom' },
+   * );
+   * ```
+   */
+  update(nanoid: string, body: AuthConfigUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.patch(path`/api/v3/auth_configs/${nanoid}`, { body, ...options });
   }
 
+  /**
+   * Retrieves all auth configs for your project. Auth configs define how users
+   * authenticate with external services (OAuth, API keys, etc.). Use filters to find
+   * configs for specific toolkits or to distinguish between Composio-managed and
+   * custom configurations.
+   *
+   * @example
+   * ```ts
+   * const authConfigs = await client.authConfigs.list();
+   * ```
+   */
   list(
     query: AuthConfigListParams | null | undefined = {},
     options?: RequestOptions,
@@ -29,15 +72,38 @@ export class AuthConfigs extends APIResource {
     return this._client.get('/api/v3/auth_configs', { query, ...options });
   }
 
-  delete(nanoid: string, options?: RequestOptions): APIPromise<AuthConfigDeleteResponse> {
+  /**
+   * Soft-deletes an authentication configuration by marking it as deleted in the
+   * database. This operation cannot be undone.
+   *
+   * @example
+   * ```ts
+   * const authConfig = await client.authConfigs.delete(
+   *   'nanoid',
+   * );
+   * ```
+   */
+  delete(nanoid: string, options?: RequestOptions): APIPromise<unknown> {
     return this._client.delete(path`/api/v3/auth_configs/${nanoid}`, options);
   }
 
+  /**
+   * Updates the status of an authentication configuration to either enabled or
+   * disabled. Disabled configurations cannot be used for new connections.
+   *
+   * @example
+   * ```ts
+   * const response = await client.authConfigs.updateStatus(
+   *   'ENABLED',
+   *   { nanoid: 'nanoid' },
+   * );
+   * ```
+   */
   updateStatus(
     status: 'ENABLED' | 'DISABLED',
     params: AuthConfigUpdateStatusParams,
     options?: RequestOptions,
-  ): APIPromise<AuthConfigUpdateStatusResponse> {
+  ): APIPromise<unknown> {
     const { nanoid } = params;
     return this._client.patch(path`/api/v3/auth_configs/${nanoid}/${status}`, options);
   }
@@ -52,12 +118,12 @@ export interface AuthConfigCreateResponse {
 export namespace AuthConfigCreateResponse {
   export interface AuthConfig {
     /**
-     * The auth config id of the app (must be a valid auth config id)
+     * The auth config id of the toolkit (must be a valid auth config id)
      */
     id: string;
 
     /**
-     * The authentication mode of the app
+     * The authentication mode of the toolkit
      */
     auth_scheme: string;
 
@@ -65,6 +131,11 @@ export namespace AuthConfigCreateResponse {
      * Whether the auth config is managed by Composio
      */
     is_composio_managed: boolean;
+
+    /**
+     * The tools that the user can use with the auth config
+     */
+    restrict_to_following_tools?: Array<string>;
   }
 
   export interface Toolkit {
@@ -77,33 +148,48 @@ export namespace AuthConfigCreateResponse {
 
 export interface AuthConfigRetrieveResponse {
   /**
-   * The unique id of the auth config
+   * The unique ID of the authentication configuration
    */
   id: string;
 
   /**
-   * The name of the auth config
+   * The display name of the authentication configuration
    */
   name: string;
 
   /**
-   * The number of connections for the auth config
+   * The number of active connections using this auth config
    */
   no_of_connections: number;
 
+  /**
+   * Current status of the authentication configuration
+   */
   status: 'ENABLED' | 'DISABLED';
 
+  tool_access_config: AuthConfigRetrieveResponse.ToolAccessConfig;
+
+  /**
+   * Information about the associated integration
+   */
   toolkit: AuthConfigRetrieveResponse.Toolkit;
 
   /**
-   * The unique id of the auth config
+   * The type of the authentication configuration (custom or default)
+   */
+  type: 'default' | 'custom';
+
+  /**
+   * The UUID of the authentication configuration (for backward compatibility)
    */
   uuid: string;
 
+  /**
+   * The authentication scheme used (e.g., OAuth2, API Key, etc.)
+   */
   auth_scheme?:
     | 'OAUTH2'
     | 'OAUTH1'
-    | 'OAUTH1A'
     | 'API_KEY'
     | 'BASIC'
     | 'BILLCOM_AUTH'
@@ -111,90 +197,195 @@ export interface AuthConfigRetrieveResponse {
     | 'GOOGLE_SERVICE_ACCOUNT'
     | 'NO_AUTH'
     | 'BASIC_WITH_JWT'
-    | 'COMPOSIO_LINK'
     | 'CALCOM_AUTH'
-    | 'SNOWFLAKE';
+    | 'SERVICE_ACCOUNT'
+    | 'SAML'
+    | 'DCR_OAUTH'
+    | 'S2S_OAUTH2';
 
   /**
-   * The date and time the auth config was created
+   * ISO 8601 date-time when the auth config was created
    */
   created_at?: string;
 
   /**
-   * The user who created the auth config
+   * The identifier of the user who created the auth config
    */
   created_by?: string;
 
-  credentials?: Record<string, unknown>;
+  /**
+   * The authentication credentials (tokens, keys, etc.) - may be partially hidden
+   * for security
+   */
+  credentials?: { [key: string]: unknown };
+
+  /**
+   * @deprecated DEPRECATED: This parameter will be removed in a future version.
+   */
+  deprecated_params?: AuthConfigRetrieveResponse.DeprecatedParams;
 
+  /**
+   * Fields expected during connection initialization
+   */
   expected_input_fields?: Array<unknown>;
 
+  /**
+   * Whether this authentication configuration is managed by Composio or the user
+   */
   is_composio_managed?: boolean;
 
   /**
-   * The date and time the auth config was last updated
+   * Whether this auth config is enabled for tool router
+   */
+  is_enabled_for_tool_router?: boolean;
+
+  /**
+   * ISO 8601 date-time when the auth config was last updated
    */
   last_updated_at?: string;
+
+  proxy_config?: AuthConfigRetrieveResponse.ProxyConfig | null;
+
+  /**
+   * @deprecated Use tool_access_config instead. This field will be deprecated in the
+   * future.
+   */
+  restrict_to_following_tools?: Array<string>;
+
+  /**
+   * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
+   * accounts using this auth config
+   */
+  shared_credentials?: { [key: string]: unknown };
 }
 
 export namespace AuthConfigRetrieveResponse {
+  export interface ToolAccessConfig {
+    /**
+     * The actions that the user can perform on the auth config. If passed, this will
+     * update the actions that the user can perform on the auth config.
+     */
+    tools_available_for_execution?: Array<string>;
+
+    /**
+     * Tools used to generate the minimum required scopes for the auth config (only
+     * valid for OAuth). If passed, this will update the scopes.
+     */
+    tools_for_connected_account_creation?: Array<string>;
+  }
+
+  /**
+   * Information about the associated integration
+   */
   export interface Toolkit {
     /**
-     * The logo of the app
+     * The URL to the integration app's logo image
      */
     logo: string;
 
     /**
-     * The unique key of the app
+     * The unique identifier of the integration app
      */
     slug: string;
   }
-}
 
-export interface AuthConfigUpdateResponse {
-  message: string;
+  /**
+   * @deprecated DEPRECATED: This parameter will be removed in a future version.
+   */
+  export interface DeprecatedParams {
+    /**
+     * Deprecated: Default connector ID
+     */
+    default_connector_id: string | null;
+
+    /**
+     * Deprecated: Fields expected during connection initialization
+     */
+    expected_input_fields?: Array<{ [key: string]: unknown }>;
+
+    /**
+     * Deprecated: Member UUID
+     */
+    member_uuid?: string;
+
+    /**
+     * Deprecated: Toolkit ID
+     */
+    toolkit_id?: string;
+  }
 
-  success: boolean;
+  export interface ProxyConfig {
+    /**
+     * The url of the auth proxy
+     */
+    proxy_url: string;
+
+    /**
+     * The auth key for the auth proxy
+     */
+    proxy_auth_key?: string;
+  }
 }
 
+export type AuthConfigUpdateResponse = unknown;
+
 export interface AuthConfigListResponse {
+  current_page: number;
+
   items: Array<AuthConfigListResponse.Item>;
 
-  next_cursor: string | null;
+  total_items: number;
 
   total_pages: number;
+
+  next_cursor?: string | null;
 }
 
 export namespace AuthConfigListResponse {
   export interface Item {
     /**
-     * The unique id of the auth config
+     * The unique ID of the authentication configuration
      */
     id: string;
 
     /**
-     * The name of the auth config
+     * The display name of the authentication configuration
      */
     name: string;
 
     /**
-     * The number of connections for the auth config
+     * The number of active connections using this auth config
      */
     no_of_connections: number;
 
+    /**
+     * Current status of the authentication configuration
+     */
     status: 'ENABLED' | 'DISABLED';
 
+    tool_access_config: Item.ToolAccessConfig;
+
+    /**
+     * Information about the associated integration
+     */
     toolkit: Item.Toolkit;
 
     /**
-     * The unique id of the auth config
+     * The type of the authentication configuration (custom or default)
+     */
+    type: 'default' | 'custom';
+
+    /**
+     * The UUID of the authentication configuration (for backward compatibility)
      */
     uuid: string;
 
+    /**
+     * The authentication scheme used (e.g., OAuth2, API Key, etc.)
+     */
     auth_scheme?:
       | 'OAUTH2'
       | 'OAUTH1'
-      | 'OAUTH1A'
       | 'API_KEY'
       | 'BASIC'
       | 'BILLCOM_AUTH'
@@ -202,59 +393,141 @@ export namespace AuthConfigListResponse {
       | 'GOOGLE_SERVICE_ACCOUNT'
       | 'NO_AUTH'
       | 'BASIC_WITH_JWT'
-      | 'COMPOSIO_LINK'
       | 'CALCOM_AUTH'
-      | 'SNOWFLAKE';
+      | 'SERVICE_ACCOUNT'
+      | 'SAML'
+      | 'DCR_OAUTH'
+      | 'S2S_OAUTH2';
 
     /**
-     * The date and time the auth config was created
+     * ISO 8601 date-time when the auth config was created
      */
     created_at?: string;
 
     /**
-     * The user who created the auth config
+     * The identifier of the user who created the auth config
      */
     created_by?: string;
 
-    credentials?: Record<string, unknown>;
+    /**
+     * The authentication credentials (tokens, keys, etc.) - may be partially hidden
+     * for security
+     */
+    credentials?: { [key: string]: unknown };
+
+    /**
+     * @deprecated DEPRECATED: This parameter will be removed in a future version.
+     */
+    deprecated_params?: Item.DeprecatedParams;
 
+    /**
+     * Fields expected during connection initialization
+     */
     expected_input_fields?: Array<unknown>;
 
+    /**
+     * Whether this authentication configuration is managed by Composio or the user
+     */
     is_composio_managed?: boolean;
 
     /**
-     * The date and time the auth config was last updated
+     * Whether this auth config is enabled for tool router
+     */
+    is_enabled_for_tool_router?: boolean;
+
+    /**
+     * ISO 8601 date-time when the auth config was last updated
      */
     last_updated_at?: string;
+
+    proxy_config?: Item.ProxyConfig | null;
+
+    /**
+     * @deprecated Use tool_access_config instead. This field will be deprecated in the
+     * future.
+     */
+    restrict_to_following_tools?: Array<string>;
+
+    /**
+     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
+     * accounts using this auth config
+     */
+    shared_credentials?: { [key: string]: unknown };
   }
 
   export namespace Item {
+    export interface ToolAccessConfig {
+      /**
+       * The actions that the user can perform on the auth config. If passed, this will
+       * update the actions that the user can perform on the auth config.
+       */
+      tools_available_for_execution?: Array<string>;
+
+      /**
+       * Tools used to generate the minimum required scopes for the auth config (only
+       * valid for OAuth). If passed, this will update the scopes.
+       */
+      tools_for_connected_account_creation?: Array<string>;
+    }
+
+    /**
+     * Information about the associated integration
+     */
     export interface Toolkit {
       /**
-       * The logo of the app
+       * The URL to the integration app's logo image
        */
       logo: string;
 
       /**
-       * The unique key of the app
+       * The unique identifier of the integration app
        */
       slug: string;
     }
-  }
-}
 
-export interface AuthConfigDeleteResponse {
-  message: string;
+    /**
+     * @deprecated DEPRECATED: This parameter will be removed in a future version.
+     */
+    export interface DeprecatedParams {
+      /**
+       * Deprecated: Default connector ID
+       */
+      default_connector_id: string | null;
 
-  success: boolean;
-}
+      /**
+       * Deprecated: Fields expected during connection initialization
+       */
+      expected_input_fields?: Array<{ [key: string]: unknown }>;
 
-export interface AuthConfigUpdateStatusResponse {
-  message: string;
+      /**
+       * Deprecated: Member UUID
+       */
+      member_uuid?: string;
 
-  success: boolean;
+      /**
+       * Deprecated: Toolkit ID
+       */
+      toolkit_id?: string;
+    }
+
+    export interface ProxyConfig {
+      /**
+       * The url of the auth proxy
+       */
+      proxy_url: string;
+
+      /**
+       * The auth key for the auth proxy
+       */
+      proxy_auth_key?: string;
+    }
+  }
 }
 
+export type AuthConfigDeleteResponse = unknown;
+
+export type AuthConfigUpdateStatusResponse = unknown;
+
 export interface AuthConfigCreateParams {
   toolkit: AuthConfigCreateParams.Toolkit;
 
@@ -264,7 +537,7 @@ export interface AuthConfigCreateParams {
 export namespace AuthConfigCreateParams {
   export interface Toolkit {
     /**
-     * List of app unique keys to filter by
+     * Toolkit slug to create auth config for
      */
     slug: string;
   }
@@ -272,19 +545,53 @@ export namespace AuthConfigCreateParams {
   export interface UnionMember0 {
     type: 'use_composio_managed_auth';
 
-    credentials?: Record<string, string | boolean | number>;
+    credentials?: UnionMember0.Credentials;
+
+    /**
+     * Whether this auth config is enabled for tool router
+     */
+    is_enabled_for_tool_router?: boolean;
 
     /**
      * The name of the integration
      */
     name?: string;
+
+    /**
+     * @deprecated Use tool_access_config instead. This field will be deprecated in the
+     * future.
+     */
+    restrict_to_following_tools?: Array<string>;
+
+    /**
+     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
+     * accounts using this auth config
+     */
+    shared_credentials?: { [key: string]: unknown };
+
+    tool_access_config?: UnionMember0.ToolAccessConfig;
+  }
+
+  export namespace UnionMember0 {
+    export interface Credentials {
+      scopes?: string | Array<string>;
+
+      user_scopes?: string | Array<string>;
+    }
+
+    export interface ToolAccessConfig {
+      /**
+       * Tools used to generate the minimum required scopes for the auth config (only
+       * valid for OAuth). If passed, this will update the scopes.
+       */
+      tools_for_connected_account_creation?: Array<string>;
+    }
   }
 
   export interface UnionMember1 {
     authScheme:
       | 'OAUTH2'
       | 'OAUTH1'
-      | 'OAUTH1A'
       | 'API_KEY'
       | 'BASIC'
       | 'BILLCOM_AUTH'
@@ -292,57 +599,239 @@ export namespace AuthConfigCreateParams {
       | 'GOOGLE_SERVICE_ACCOUNT'
       | 'NO_AUTH'
       | 'BASIC_WITH_JWT'
-      | 'COMPOSIO_LINK'
       | 'CALCOM_AUTH'
-      | 'SNOWFLAKE';
-
-    credentials: Record<string, string | boolean | number>;
+      | 'SERVICE_ACCOUNT'
+      | 'SAML'
+      | 'DCR_OAUTH'
+      | 'S2S_OAUTH2';
 
     type: 'use_custom_auth';
 
+    credentials?: UnionMember1.Credentials;
+
+    /**
+     * Whether this auth config is enabled for tool router
+     */
+    is_enabled_for_tool_router?: boolean;
+
     /**
      * The name of the integration
      */
     name?: string;
+
+    proxy_config?: UnionMember1.ProxyConfig | null;
+
+    /**
+     * @deprecated Use tool_access_config instead. This field will be deprecated in the
+     * future.
+     */
+    restrict_to_following_tools?: Array<string>;
+
+    /**
+     * [EXPERIMENTAL] Shared credentials that will be inherited by all connected
+     * accounts using this auth config
+     */
+    shared_credentials?: { [key: string]: unknown };
+
+    tool_access_config?: UnionMember1.ToolAccessConfig;
   }
-}
 
-export interface AuthConfigUpdateParams {
-  auth_config: AuthConfigUpdateParams.AuthConfig;
+  export namespace UnionMember1 {
+    export interface Credentials {
+      scopes?: string | Array<string>;
+
+      user_scopes?: string | Array<string>;
+    }
+
+    export interface ProxyConfig {
+      /**
+       * The url of the auth proxy
+       */
+      proxy_url: string;
+
+      /**
+       * The auth key for the auth proxy
+       */
+      proxy_auth_key?: string;
+    }
+
+    export interface ToolAccessConfig {
+      /**
+       * Tools used to generate the minimum required scopes for the auth config (only
+       * valid for OAuth). If passed, this will update the scopes.
+       */
+      tools_for_connected_account_creation?: Array<string>;
+    }
+  }
 }
 
-export namespace AuthConfigUpdateParams {
-  export interface AuthConfig {
+export type AuthConfigUpdateParams = AuthConfigUpdateParams.Variant0 | AuthConfigUpdateParams.Variant1;
+
+export declare namespace AuthConfigUpdateParams {
+  export interface Variant0 {
+    type: 'custom';
+
+    credentials?: Variant0.Credentials;
+
+    /**
+     * Whether this auth config is enabled for tool router
+     */
+    is_enabled_for_tool_router?: boolean;
+
     /**
-     * Authentication configuration
+     * The display name of the authentication configuration
      */
-    credentials?: Record<string, unknown>;
+    name?: string;
+
+    proxy_config?: Variant0.ProxyConfig | null;
+
+    /**
+     * @deprecated Use tool_access_config instead. This field will be deprecated in the
+     * future.
+     */
+    restrict_to_following_tools?: Array<string>;
+
+    /**
+     * Shared credentials that will be inherited by connected accounts. For eg: this
+     * can be used to share the API key for a tool with all connected accounts using
+     * this auth config.
+     */
+    shared_credentials?: { [key: string]: unknown };
+
+    tool_access_config?: Variant0.ToolAccessConfig;
+  }
+
+  export namespace Variant0 {
+    export interface Credentials {
+      scopes?: string | Array<string>;
+
+      user_scopes?: string | Array<string>;
+    }
+
+    export interface ProxyConfig {
+      /**
+       * The url of the auth proxy
+       */
+      proxy_url: string;
+
+      /**
+       * The auth key for the auth proxy
+       */
+      proxy_auth_key?: string;
+    }
+
+    export interface ToolAccessConfig {
+      /**
+       * The actions that the user can perform on the auth config. If passed, this will
+       * update the actions that the user can perform on the auth config.
+       */
+      tools_available_for_execution?: Array<string>;
+
+      /**
+       * Tools used to generate the minimum required scopes for the auth config (only
+       * valid for OAuth). If passed, this will update the scopes.
+       */
+      tools_for_connected_account_creation?: Array<string>;
+    }
+  }
+
+  export interface Variant1 {
+    type: 'default';
+
+    /**
+     * Whether this auth config is enabled for tool router
+     */
+    is_enabled_for_tool_router?: boolean;
+
+    /**
+     * The display name of the authentication configuration
+     */
+    name?: string;
+
+    /**
+     * @deprecated Use tool_access_config instead. This field will be deprecated in the
+     * future.
+     */
+    restrict_to_following_tools?: Array<string>;
+
+    scopes?: string | Array<string>;
+
+    /**
+     * Shared credentials that will be inherited by connected accounts. For eg: this
+     * can be used to share the API key for a tool with all connected accounts using
+     * this auth config.
+     */
+    shared_credentials?: { [key: string]: unknown };
+
+    tool_access_config?: Variant1.ToolAccessConfig;
+  }
+
+  export namespace Variant1 {
+    export interface ToolAccessConfig {
+      /**
+       * The actions that the user can perform on the auth config. If passed, this will
+       * update the actions that the user can perform on the auth config.
+       */
+      tools_available_for_execution?: Array<string>;
+
+      /**
+       * Tools used to generate the minimum required scopes for the auth config (only
+       * valid for OAuth). If passed, this will update the scopes.
+       */
+      tools_for_connected_account_creation?: Array<string>;
+    }
   }
 }
 
 export interface AuthConfigListParams {
   /**
-   * The cursor to paginate through the auth configs
+   * 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;
 
+  /**
+   * @deprecated The app id to filter by
+   */
+  deprecated_app_id?: string;
+
+  /**
+   * @deprecated DEPRECATED: This parameter will be removed in a future version.
+   */
+  deprecated_status?: string;
+
   /**
    * Whether to filter by composio managed auth configs
    */
   is_composio_managed?: string | boolean;
 
   /**
-   * The number of auth configs to return
+   * Number of items per page, max allowed is 1000
    */
-  limit?: string;
+  limit?: number | null;
 
   /**
-   * The slug of the toolkit to filter by
+   * Search auth configs by name
+   */
+  search?: string;
+
+  /**
+   * Show disabled auth configs
+   */
+  show_disabled?: boolean | null;
+
+  /**
+   * Comma-separated list of toolkit slugs to filter auth configs by
    */
   toolkit_slug?: string;
 }
 
 export interface AuthConfigUpdateStatusParams {
+  /**
+   * The unique identifier of the authentication configuration to update
+   */
   nanoid: string;
 }