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

package/src/resources/auth-configs.ts

@@ -8,20 +8,44 @@ import { path } from '../internal/utils/path';
 export class AuthConfigs extends APIResource {
   /**
    * Create new authentication configuration
+   *
+   * @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 });
   }
 
   /**
-   * Get single authentication configuration by ID
+   * 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 an authentication configuration
+   * 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',
+   *   { credentials: { foo: 'bar' }, type: 'custom' },
+   * );
+   * ```
    */
   update(nanoid: string, body: AuthConfigUpdateParams, options?: RequestOptions): APIPromise<unknown> {
     return this._client.patch(path`/api/v3/auth_configs/${nanoid}`, { body, ...options });
@@ -29,6 +53,11 @@ export class AuthConfigs extends APIResource {
 
   /**
    * List authentication configurations with optional filters
+   *
+   * @example
+   * ```ts
+   * const authConfigs = await client.authConfigs.list();
+   * ```
    */
   list(
     query: AuthConfigListParams | null | undefined = {},
@@ -38,14 +67,31 @@ export class AuthConfigs extends APIResource {
   }
 
   /**
-   * Delete an authentication configuration
+   * 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);
   }
 
   /**
-   * Enable or disable an authentication configuration
+   * 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',
@@ -66,12 +112,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;
 
@@ -81,7 +127,7 @@ export namespace AuthConfigCreateResponse {
     is_composio_managed: boolean;
 
     /**
-     * The actions that the user can perform on the auth config
+     * The tools that the user can use with the auth config
      */
     restrict_to_following_tools?: Array<string>;
   }
@@ -96,36 +142,48 @@ export namespace AuthConfigCreateResponse {
 
 export interface AuthConfigRetrieveResponse {
   /**
-   * The unique id of the auth config
+   * The unique ID of the authentication configuration
    */
   id: string;
 
+  /**
+   * Deprecated parameters maintained for backward compatibility
+   */
   deprecated_params: AuthConfigRetrieveResponse.DeprecatedParams;
 
   /**
-   * 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';
 
+  /**
+   * Information about the associated integration
+   */
   toolkit: AuthConfigRetrieveResponse.Toolkit;
 
   /**
-   * The type of the auth config
+   * The type of the authentication configuration (custom or default)
    */
   type: 'default' | 'custom';
 
   /**
-   * The unique id of the auth config
+   * 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'
@@ -142,48 +200,79 @@ export interface AuthConfigRetrieveResponse {
     | 'SNOWFLAKE';
 
   /**
-   * 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;
 
+  /**
+   * The authentication credentials (tokens, keys, etc.) - may be partially hidden
+   * for security
+   */
   credentials?: Record<string, unknown>;
 
+  /**
+   * 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
+   * ISO 8601 date-time when the auth config was last updated
    */
   last_updated_at?: string;
 
+  /**
+   * List of tool IDs this auth config is restricted to use with
+   */
   restrict_to_following_tools?: Array<string>;
 }
 
 export namespace AuthConfigRetrieveResponse {
+  /**
+   * Deprecated parameters maintained for backward compatibility
+   */
   export interface DeprecatedParams {
+    /**
+     * Deprecated: Default connector ID
+     */
     default_connector_id: string | null;
 
+    /**
+     * Deprecated: Fields expected during connection initialization
+     */
     expected_input_fields?: Array<Record<string, unknown>>;
 
+    /**
+     * Deprecated: Member UUID
+     */
     member_uuid?: string;
 
+    /**
+     * Deprecated: Toolkit ID
+     */
     toolkit_id?: 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;
   }
@@ -202,36 +291,48 @@ export interface AuthConfigListResponse {
 export namespace AuthConfigListResponse {
   export interface Item {
     /**
-     * The unique id of the auth config
+     * The unique ID of the authentication configuration
      */
     id: string;
 
+    /**
+     * Deprecated parameters maintained for backward compatibility
+     */
     deprecated_params: Item.DeprecatedParams;
 
     /**
-     * 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';
 
+    /**
+     * Information about the associated integration
+     */
     toolkit: Item.Toolkit;
 
     /**
-     * The type of the auth config
+     * The type of the authentication configuration (custom or default)
      */
     type: 'default' | 'custom';
 
     /**
-     * The unique id of the auth config
+     * 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'
@@ -248,48 +349,79 @@ export namespace AuthConfigListResponse {
       | 'SNOWFLAKE';
 
     /**
-     * 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;
 
+    /**
+     * The authentication credentials (tokens, keys, etc.) - may be partially hidden
+     * for security
+     */
     credentials?: Record<string, unknown>;
 
+    /**
+     * 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
+     * ISO 8601 date-time when the auth config was last updated
      */
     last_updated_at?: string;
 
+    /**
+     * List of tool IDs this auth config is restricted to use with
+     */
     restrict_to_following_tools?: Array<string>;
   }
 
   export namespace Item {
+    /**
+     * Deprecated parameters maintained for backward compatibility
+     */
     export interface DeprecatedParams {
+      /**
+       * Deprecated: Default connector ID
+       */
       default_connector_id: string | null;
 
+      /**
+       * Deprecated: Fields expected during connection initialization
+       */
       expected_input_fields?: Array<Record<string, unknown>>;
 
+      /**
+       * Deprecated: Member UUID
+       */
       member_uuid?: string;
 
+      /**
+       * Deprecated: Toolkit ID
+       */
       toolkit_id?: 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;
     }
@@ -309,7 +441,7 @@ export interface AuthConfigCreateParams {
 export namespace AuthConfigCreateParams {
   export interface Toolkit {
     /**
-     * List of app unique keys to filter by
+     * List of toolkits unique keys to filter by
      */
     slug: string;
   }
@@ -403,7 +535,12 @@ export interface AuthConfigListParams {
   /**
    * The number of auth configs to return
    */
-  limit?: string;
+  limit?: number | null;
+
+  /**
+   * Show disabled auth configs
+   */
+  show_disabled?: boolean;
 
   /**
    * The slug of the toolkit to filter by
@@ -412,6 +549,9 @@ export interface AuthConfigListParams {
 }
 
 export interface AuthConfigUpdateStatusParams {
+  /**
+   * The unique identifier of the authentication configuration to update
+   */
   nanoid: string;
 }
 

package/src/resources/connected-accounts.ts

@@ -8,6 +8,15 @@ import { path } from '../internal/utils/path';
 export class ConnectedAccounts extends APIResource {
   /**
    * Create a new connected account
+   *
+   * @example
+   * ```ts
+   * const connectedAccount =
+   *   await client.connectedAccounts.create({
+   *     auth_config: { id: 'id' },
+   *     connection: {},
+   *   });
+   * ```
    */
   create(
     body: ConnectedAccountCreateParams,
@@ -17,7 +26,16 @@ export class ConnectedAccounts extends APIResource {
   }
 
   /**
-   * Get connected account details by ID
+   * Retrieves comprehensive details of a connected account, including authentication
+   * configuration, connection status, and all parameters needed for API requests.
+   *
+   * @example
+   * ```ts
+   * const connectedAccount =
+   *   await client.connectedAccounts.retrieve(
+   *     'con_1a2b3c4d5e6f',
+   *   );
+   * ```
    */
   retrieve(nanoid: string, options?: RequestOptions): APIPromise<ConnectedAccountRetrieveResponse> {
     return this._client.get(path`/api/v3/connected_accounts/${nanoid}`, options);
@@ -25,6 +43,12 @@ export class ConnectedAccounts extends APIResource {
 
   /**
    * List connected accounts with optional filters
+   *
+   * @example
+   * ```ts
+   * const connectedAccounts =
+   *   await client.connectedAccounts.list();
+   * ```
    */
   list(
     query: ConnectedAccountListParams | null | undefined = {},
@@ -34,21 +58,49 @@ export class ConnectedAccounts extends APIResource {
   }
 
   /**
-   * Delete a connected account
+   * Soft-deletes a connected account by marking it as deleted in the database. This
+   * prevents the account from being used for API calls but preserves the record for
+   * audit purposes.
+   *
+   * @example
+   * ```ts
+   * const connectedAccount =
+   *   await client.connectedAccounts.delete('con_1a2b3c4d5e6f');
+   * ```
    */
   delete(nanoid: string, options?: RequestOptions): APIPromise<ConnectedAccountDeleteResponse> {
     return this._client.delete(path`/api/v3/connected_accounts/${nanoid}`, options);
   }
 
   /**
-   * Refresh authentication for a connected account
+   * Initiates a new authentication flow for a connected account when credentials
+   * have expired or become invalid. This may generate a new authentication URL for
+   * OAuth flows or refresh tokens for other auth schemes.
+   *
+   * @example
+   * ```ts
+   * const response = await client.connectedAccounts.refresh(
+   *   'con_1a2b3c4d5e6f',
+   * );
+   * ```
    */
   refresh(nanoid: string, options?: RequestOptions): APIPromise<ConnectedAccountRefreshResponse> {
     return this._client.post(path`/api/v3/connected_accounts/${nanoid}/refresh`, options);
   }
 
   /**
-   * Enable or disable a connected account
+   * Updates the status of a connected account to either enabled (active) or disabled
+   * (inactive). Disabled accounts cannot be used for API calls but remain in the
+   * database.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.connectedAccounts.updateStatus(
+   *     'con_1a2b3c4d5e6f',
+   *     { enabled: true },
+   *   );
+   * ```
    */
   updateStatus(
     nanoID: string,
@@ -81,7 +133,7 @@ export interface ConnectedAccountCreateResponse {
   /**
    * The status of the connected account
    */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+  status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
 }
 
 export namespace ConnectedAccountCreateResponse {
@@ -117,22 +169,23 @@ export interface ConnectedAccountRetrieveResponse {
   data: Record<string, unknown>;
 
   /**
-   * Whether the connected account is disabled
+   * Whether the connected account is disabled. When true, the account cannot be used
+   * for API calls
    */
   is_disabled: boolean;
 
   /**
-   * The init data of the connection
+   * The initialization data of the connection, including configuration parameters
    */
   params: Record<string, unknown>;
 
   /**
    * The status of the connection
    */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+  status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
 
   /**
-   * The reason the connected account is disabled
+   * The reason why the connected account is disabled, if applicable
    */
   status_reason: string | null;
 
@@ -258,7 +311,7 @@ export namespace ConnectedAccountListResponse {
     /**
      * The status of the connection
      */
-    status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+    status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
 
     /**
      * The reason the connection is disabled
@@ -353,33 +406,40 @@ export namespace ConnectedAccountListResponse {
   }
 }
 
+/**
+ * Response returned after successfully deleting a connected account
+ */
 export interface ConnectedAccountDeleteResponse {
   /**
-   * The success of the update
+   * Indicates whether the connected account was successfully deleted
    */
   success: boolean;
 }
 
 export interface ConnectedAccountRefreshResponse {
   /**
-   * The id of the connected account
+   * The unique identifier of the connected account
    */
   id: string;
 
   /**
-   * The redirect URL of the app (previously named redirect_uri)
+   * The URL to which the user should be redirected to complete the authentication
+   * process (null for auth schemes that do not require redirection)
    */
   redirect_url: string | null;
 
   /**
-   * The status of the connected account
+   * The current status of the connected account (e.g., active, pending, failed)
    */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+  status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
 }
 
+/**
+ * Response returned after successfully updating a connected account status
+ */
 export interface ConnectedAccountUpdateStatusResponse {
   /**
-   * The success of the update
+   * Indicates whether the connected account status was successfully updated
    */
   success: boolean;
 }
@@ -456,7 +516,7 @@ export interface ConnectedAccountListParams {
   /**
    * The status of the connected account
    */
-  statuses?: Array<'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED'> | null;
+  statuses?: Array<'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED'> | null;
 
   /**
    * The toolkit slugs of the connected accounts
@@ -470,6 +530,9 @@ export interface ConnectedAccountListParams {
 }
 
 export interface ConnectedAccountUpdateStatusParams {
+  /**
+   * Set to true to enable the account or false to disable it
+   */
   enabled: boolean;
 }