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

package/src/resources/connected-accounts.ts

@@ -6,6 +6,18 @@ import { RequestOptions } from '../internal/request-options';
 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,
     options?: RequestOptions,
@@ -13,10 +25,31 @@ export class ConnectedAccounts extends APIResource {
     return this._client.post('/api/v3/connected_accounts', { body, ...options });
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * List connected accounts with optional filters
+   *
+   * @example
+   * ```ts
+   * const connectedAccounts =
+   *   await client.connectedAccounts.list();
+   * ```
+   */
   list(
     query: ConnectedAccountListParams | null | undefined = {},
     options?: RequestOptions,
@@ -24,14 +57,51 @@ export class ConnectedAccounts extends APIResource {
     return this._client.get('/api/v3/connected_accounts', { query, ...options });
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * 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,
     body: ConnectedAccountUpdateStatusParams,
@@ -47,15 +117,37 @@ export interface ConnectedAccountCreateResponse {
    */
   id: string;
 
+  deprecated: ConnectedAccountCreateResponse.Deprecated;
+
   /**
-   * The redirect uri of the app
+   * @deprecated DEPRECATED: This field will be removed in a future version. Please
+   * use redirect_url instead.
    */
   redirect_uri: string | null;
 
+  /**
+   * The URL to redirect to after connection completion
+   */
+  redirect_url: string | null;
+
   /**
    * The status of the connected account
    */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+  status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
+}
+
+export namespace ConnectedAccountCreateResponse {
+  export interface Deprecated {
+    /**
+     * The uuid of the auth config
+     */
+    authConfigUuid: string;
+
+    /**
+     * The uuid of the connected account
+     */
+    uuid: string;
+  }
 }
 
 export interface ConnectedAccountRetrieveResponse {
@@ -77,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;
 
@@ -108,10 +201,7 @@ export interface ConnectedAccountRetrieveResponse {
    */
   user_id: string;
 
-  /**
-   * The uuid of the connection
-   */
-  uuid: string;
+  deprecated?: ConnectedAccountRetrieveResponse.Deprecated;
 
   /**
    * The endpoint to make test request for verification
@@ -153,6 +243,17 @@ export namespace ConnectedAccountRetrieveResponse {
      * Whether the auth config is disabled
      */
     is_disabled: boolean;
+
+    deprecated?: AuthConfig.Deprecated;
+  }
+
+  export namespace AuthConfig {
+    export interface Deprecated {
+      /**
+       * The uuid of the auth config
+       */
+      uuid: string;
+    }
   }
 
   export interface Toolkit {
@@ -161,6 +262,18 @@ export namespace ConnectedAccountRetrieveResponse {
      */
     slug: string;
   }
+
+  export interface Deprecated {
+    /**
+     * The labels of the connection
+     */
+    labels: Array<string>;
+
+    /**
+     * The uuid of the connection
+     */
+    uuid: string;
+  }
 }
 
 export interface ConnectedAccountListResponse {
@@ -198,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
@@ -217,15 +330,12 @@ export namespace ConnectedAccountListResponse {
      */
     user_id: string;
 
+    deprecated?: Item.Deprecated;
+
     /**
      * The endpoint to make test request for verification
      */
     test_request_endpoint?: string;
-
-    /**
-     * The uuid of the connected account
-     */
-    uuid?: string;
   }
 
   export namespace Item {
@@ -262,6 +372,17 @@ export namespace ConnectedAccountListResponse {
        * Whether the auth config is disabled
        */
       is_disabled: boolean;
+
+      deprecated?: AuthConfig.Deprecated;
+    }
+
+    export namespace AuthConfig {
+      export interface Deprecated {
+        /**
+         * The uuid of the auth config
+         */
+        uuid: string;
+      }
     }
 
     export interface Toolkit {
@@ -270,307 +391,57 @@ export namespace ConnectedAccountListResponse {
        */
       slug: string;
     }
+
+    export interface Deprecated {
+      /**
+       * The labels of the connection
+       */
+      labels: Array<string>;
+
+      /**
+       * The uuid of the connection
+       */
+      uuid: string;
+    }
   }
 }
 
+/**
+ * Response returned after successfully deleting a connected account
+ */
 export interface ConnectedAccountDeleteResponse {
   /**
-   * The id of the connection
-   */
-  id: string;
-
-  auth_config: ConnectedAccountDeleteResponse.AuthConfig;
-
-  /**
-   * The created at of the connection
-   */
-  created_at: string;
-
-  /**
-   * The data of the connection
-   */
-  data: Record<string, unknown>;
-
-  /**
-   * Whether the connection is disabled
+   * Indicates whether the connected account was successfully deleted
    */
-  is_disabled: boolean;
-
-  /**
-   * The status of the connection
-   */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
-
-  /**
-   * The reason the connection is disabled
-   */
-  status_reason: string | null;
-
-  toolkit: ConnectedAccountDeleteResponse.Toolkit;
-
-  /**
-   * The updated at of the connection
-   */
-  updated_at: string;
-
-  /**
-   * The user id of the connection
-   */
-  user_id: string;
-
-  /**
-   * The uuid of the connection
-   */
-  uuid: string;
-
-  /**
-   * The endpoint to make test request for verification
-   */
-  test_request_endpoint?: string;
-}
-
-export namespace ConnectedAccountDeleteResponse {
-  export interface AuthConfig {
-    /**
-     * The id of the auth config
-     */
-    id: string;
-
-    /**
-     * The auth scheme of the auth config
-     */
-    auth_scheme:
-      | 'OAUTH2'
-      | 'OAUTH1'
-      | 'OAUTH1A'
-      | 'API_KEY'
-      | 'BASIC'
-      | 'BILLCOM_AUTH'
-      | 'BEARER_TOKEN'
-      | 'GOOGLE_SERVICE_ACCOUNT'
-      | 'NO_AUTH'
-      | 'BASIC_WITH_JWT'
-      | 'COMPOSIO_LINK'
-      | 'CALCOM_AUTH'
-      | 'SNOWFLAKE';
-
-    /**
-     * Whether the auth config is managed by Composio
-     */
-    is_composio_managed: boolean;
-
-    /**
-     * Whether the auth config is disabled
-     */
-    is_disabled: boolean;
-  }
-
-  export interface Toolkit {
-    /**
-     * The slug of the toolkit
-     */
-    slug: string;
-  }
+  success: boolean;
 }
 
 export interface ConnectedAccountRefreshResponse {
   /**
-   * The id of the connection
+   * The unique identifier of the connected account
    */
   id: string;
 
-  auth_config: ConnectedAccountRefreshResponse.AuthConfig;
-
-  /**
-   * The created at of the connection
-   */
-  created_at: string;
-
-  /**
-   * The data of the connection
-   */
-  data: Record<string, unknown>;
-
-  /**
-   * Whether the connection is disabled
-   */
-  is_disabled: boolean;
-
-  /**
-   * The status of the connection
-   */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
-
   /**
-   * The reason the connection is disabled
+   * The URL to which the user should be redirected to complete the authentication
+   * process (null for auth schemes that do not require redirection)
    */
-  status_reason: string | null;
-
-  toolkit: ConnectedAccountRefreshResponse.Toolkit;
+  redirect_url: string | null;
 
   /**
-   * The updated at of the connection
+   * The current status of the connected account (e.g., active, pending, failed)
    */
-  updated_at: string;
-
-  /**
-   * The user id of the connection
-   */
-  user_id: string;
-
-  /**
-   * The uuid of the connection
-   */
-  uuid: string;
-
-  /**
-   * The endpoint to make test request for verification
-   */
-  test_request_endpoint?: string;
-}
-
-export namespace ConnectedAccountRefreshResponse {
-  export interface AuthConfig {
-    /**
-     * The id of the auth config
-     */
-    id: string;
-
-    /**
-     * The auth scheme of the auth config
-     */
-    auth_scheme:
-      | 'OAUTH2'
-      | 'OAUTH1'
-      | 'OAUTH1A'
-      | 'API_KEY'
-      | 'BASIC'
-      | 'BILLCOM_AUTH'
-      | 'BEARER_TOKEN'
-      | 'GOOGLE_SERVICE_ACCOUNT'
-      | 'NO_AUTH'
-      | 'BASIC_WITH_JWT'
-      | 'COMPOSIO_LINK'
-      | 'CALCOM_AUTH'
-      | 'SNOWFLAKE';
-
-    /**
-     * Whether the auth config is managed by Composio
-     */
-    is_composio_managed: boolean;
-
-    /**
-     * Whether the auth config is disabled
-     */
-    is_disabled: boolean;
-  }
-
-  export interface Toolkit {
-    /**
-     * The slug of the toolkit
-     */
-    slug: string;
-  }
+  status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED';
 }
 
+/**
+ * Response returned after successfully updating a connected account status
+ */
 export interface ConnectedAccountUpdateStatusResponse {
   /**
-   * The id of the connection
-   */
-  id: string;
-
-  auth_config: ConnectedAccountUpdateStatusResponse.AuthConfig;
-
-  /**
-   * The created at of the connection
-   */
-  created_at: string;
-
-  /**
-   * The data of the connection
-   */
-  data: Record<string, unknown>;
-
-  /**
-   * Whether the connection is disabled
+   * Indicates whether the connected account status was successfully updated
    */
-  is_disabled: boolean;
-
-  /**
-   * The status of the connection
-   */
-  status: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
-
-  /**
-   * The reason the connection is disabled
-   */
-  status_reason: string | null;
-
-  toolkit: ConnectedAccountUpdateStatusResponse.Toolkit;
-
-  /**
-   * The updated at of the connection
-   */
-  updated_at: string;
-
-  /**
-   * The user id of the connection
-   */
-  user_id: string;
-
-  /**
-   * The uuid of the connection
-   */
-  uuid: string;
-
-  /**
-   * The endpoint to make test request for verification
-   */
-  test_request_endpoint?: string;
-}
-
-export namespace ConnectedAccountUpdateStatusResponse {
-  export interface AuthConfig {
-    /**
-     * The id of the auth config
-     */
-    id: string;
-
-    /**
-     * The auth scheme of the auth config
-     */
-    auth_scheme:
-      | 'OAUTH2'
-      | 'OAUTH1'
-      | 'OAUTH1A'
-      | 'API_KEY'
-      | 'BASIC'
-      | 'BILLCOM_AUTH'
-      | 'BEARER_TOKEN'
-      | 'GOOGLE_SERVICE_ACCOUNT'
-      | 'NO_AUTH'
-      | 'BASIC_WITH_JWT'
-      | 'COMPOSIO_LINK'
-      | 'CALCOM_AUTH'
-      | 'SNOWFLAKE';
-
-    /**
-     * Whether the auth config is managed by Composio
-     */
-    is_composio_managed: boolean;
-
-    /**
-     * Whether the auth config is disabled
-     */
-    is_disabled: boolean;
-  }
-
-  export interface Toolkit {
-    /**
-     * The slug of the toolkit
-     */
-    slug: string;
-  }
+  success: boolean;
 }
 
 export interface ConnectedAccountCreateParams {
@@ -588,13 +459,24 @@ export namespace ConnectedAccountCreateParams {
   }
 
   export interface Connection {
+    /**
+     * The URL to redirect to after connection completion
+     */
+    callback_url?: string;
+
     /**
      * Initial data to pass to the connected account
      */
     data?: Record<string, unknown>;
 
     /**
-     * The URL to redirect to after connection completion
+     * Whether the connection is rerouted
+     */
+    deprecated_is_v1_rerouted?: boolean;
+
+    /**
+     * @deprecated DEPRECATED: This parameter will be removed in a future version.
+     * Please use callback_url instead.
      */
     redirect_uri?: string;
 
@@ -607,15 +489,20 @@ export namespace ConnectedAccountCreateParams {
 
 export interface ConnectedAccountListParams {
   /**
-   * The auth config id of the connected account
+   * The auth config ids of the connected accounts
    */
-  auth_config_id?: string;
+  auth_config_ids?: Array<string> | null;
 
   /**
    * The cursor to paginate through the connected accounts
    */
   cursor?: number | null;
 
+  /**
+   * The labels of the connected accounts
+   */
+  labels?: Array<string> | null;
+
   /**
    * The limit of the connected accounts to return
    */
@@ -629,20 +516,23 @@ export interface ConnectedAccountListParams {
   /**
    * The status of the connected account
    */
-  status?: 'ACTIVE' | 'INACTIVE' | 'DELETED' | 'INITIATED' | 'EXPIRED' | 'FAILED';
+  statuses?: Array<'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED'> | null;
 
   /**
-   * The toolkit slug of the connected account
+   * The toolkit slugs of the connected accounts
    */
-  toolkit_slug?: string;
+  toolkit_slugs?: Array<string> | null;
 
   /**
-   * The user id of the connected account
+   * The user ids of the connected accounts
    */
-  user_id?: string;
+  user_ids?: Array<string> | null;
 }
 
 export interface ConnectedAccountUpdateStatusParams {
+  /**
+   * Set to true to enable the account or false to disable it
+   */
   enabled: boolean;
 }