Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

33.1 KB
Raw Blame
/**
 * @fileoverview Connected accounts class for Composio SDK, used to manage connected accounts of a user.
 *
 * @author Musthaq Ahamad <[email protected]>
 * @date 2025-05-05
 * @module ConnectedAccounts
 */
import ComposioClient, { BadRequestError, ConflictError } from '@composio/client';
import {
  ConnectedAccountCreateResponse,
  ConnectedAccountDeleteResponse,
  ConnectedAccountRefreshParams,
  ConnectedAccountRefreshResponse,
  ConnectedAccountUpdateStatusParams,
  ConnectedAccountUpdateStatusResponse,
  ConnectedAccountPatchResponse,
  ConnectedAccountListParams as ConnectedAccountListParamsRaw,
  ConnectedAccountCreateParams as ConnectedAccountCreateParamsRaw,
} from '@composio/client/resources/connected-accounts';
import { LinkCreateParams } from '@composio/client/resources/link';
import {
  CreateConnectedAccountOptions,
  ConnectedAccountRetrieveResponse,
  ConnectedAccountListParams,
  ConnectedAccountListParamsSchema,
  ConnectedAccountListResponse,
  CreateConnectedAccountLinkOptions,
  CreateConnectedAccountLinkOptionsSchema,
  ConnectedAccountStatuses,
  ConnectedAccountRefreshOptions,
  ConnectedAccountRefreshOptionsSchema,
  ConnectedAccountRevokeResponse,
  ConnectedAccountCompleteAuthParams,
  ConnectedAccountCompleteAuthParamsSchema,
  ConnectedAccountCompleteAuthResponse,
  UpdateConnectedAccountAclParams,
  UpdateConnectedAccountParams,
  UpdateConnectedAccountParamsSchema,
} from '../types/connectedAccounts.types';
import { ConnectionRequest } from '../types/connectionRequest.types';
import { createConnectionRequest } from './ConnectionRequest';
import {
  ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT,
  serializeExperimentalForWire,
  updateConnectedAccountAcl,
} from './Experimental';
import { ValidationError } from '../errors/ValidationErrors';
import { telemetry } from '../telemetry/Telemetry';
import {
  transformConnectedAccountListResponse,
  transformConnectedAccountResponse,
  transformConnectedAccountRevokeResponse,
  transformConnectedAccountCompleteAuthResponse,
} from '../utils/transformers/connectedAccounts';
import {
  ComposioAclOnlyForSharedError,
  ComposioConnectedAccountNotRevokableError,
  ComposioConnectedAccountRevocationNotSupportedError,
  ComposioFailedToCreateConnectedAccountLink,
  ComposioLegacyConnectedAccountsEndpointRetiredError,
  ComposioMultipleConnectedAccountsError,
} from '../errors';
import logger from '../utils/logger';
import { ConnectionData } from '../types/connectedAccountAuthStates.types';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
import { ComposioRequestCancelledError } from '../errors/SDKErrors';

// One-time-per-process guard so long-running services don't spam the deprecation
// warning on every initiate() call.
let _legacyInitiateWarningEmitted = false;

/**
 * ConnectedAccounts class
 *
 * This class is used to manage connected accounts in the Composio SDK.
 * Connected accounts are used to authenticate with third-party services.
 */
export class ConnectedAccounts {
  private client: ComposioClient;

  constructor(client: ComposioClient) {
    this.client = client;
    telemetry.instrument(this, 'ConnectedAccounts');
  }

  /**
   * Lists all connected accounts based on provided filter criteria.
   *
   * This method retrieves connected accounts from the Composio API with optional filtering.
   *
   * @param {ConnectedAccountListParams} [query] - Optional query parameters for filtering connected accounts
   * @returns {Promise<ConnectedAccountListResponse>} A paginated list of connected accounts
   * @throws {ValidationError} If the query fails validation against the expected schema
   * @example
   * ```typescript
   * // List all connected accounts
   * const allAccounts = await composio.connectedAccounts.list();
   *
   * // List accounts for a specific user
   * const userAccounts = await composio.connectedAccounts.list({
   *   userIds: ['user123']
   * });
   *
   * // List accounts for a specific toolkit
   * const githubAccounts = await composio.connectedAccounts.list({
   *   toolkitSlugs: ['github']
   * });
   * ```
   */
  async list(
    query?: ConnectedAccountListParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountListResponse> {
    let rawQuery: ConnectedAccountListParamsRaw | undefined = undefined;

    if (query) {
      const parsedQuery = ConnectedAccountListParamsSchema.safeParse(query);
      if (!parsedQuery.success) {
        throw new ValidationError('Failed to parse connected account list query', {
          cause: parsedQuery.error,
        });
      }
      rawQuery = {
        auth_config_ids: parsedQuery.data.authConfigIds,
        cursor: parsedQuery.data.cursor?.toString(),
        limit: parsedQuery.data.limit,
        order_by: parsedQuery.data.orderBy,
        // Cast widens to match the Stainless-generated client params, which
        // lag behind the live API enum. Apollo accepts the union value at
        // runtime (`z.nativeEnum(ConnectionStatusEnum)` on the query param);
        // remove the cast once `@composio/client` is regenerated.
        statuses: parsedQuery.data.statuses as ConnectedAccountListParamsRaw['statuses'],
        toolkit_slugs: parsedQuery.data.toolkitSlugs,
        user_ids: parsedQuery.data.userIds,
        ...(parsedQuery.data.accountType !== undefined && {
          account_type: parsedQuery.data.accountType,
        }),
      };
    }

    const result = await withCancellation(
      () => this.client.connectedAccounts.list(rawQuery, requestOptions),
      requestOptions?.signal
    );
    return transformConnectedAccountListResponse(result);
  }

  /**
   * Compound function to create a new connected account.
   * This function creates a new connected account and returns a connection request.
   * Users can then wait for the connection to be established using the `waitForConnection` method.
   *
   * **Deprecated for Composio-managed OAuth (OAuth1, OAuth2, DCR_OAUTH).**
   * The legacy `POST /api/v3/connected_accounts` endpoint that this method
   * wraps is being retired for Composio-managed auth configs on redirectable
   * schemes. The cutover is **2026-05-08** for new organizations and
   * **2026-07-03** for all remaining organizations. After your org's cutover,
   * this method will throw {@link ComposioLegacyConnectedAccountsEndpointRetiredError}
   * for that specific combination.
   *
   * Use {@link ConnectedAccounts.link} for Composio-managed OAuth — it works for
   * every redirectable scheme regardless of whether the auth config is
   * Composio-managed or custom, and the return shape is the same.
   *
   * Custom auth configs (your own OAuth app) and non-OAuth schemes (API key,
   * bearer token, basic auth) are unaffected and continue to work on
   * `initiate()`. See https://docs.composio.dev/docs/changelog/2026/04/24
   *
   * @param {string} userId - User ID of the connected account
   * @param {string} authConfigId - Auth config ID of the connected account
   * @param {CreateConnectedAccountOptions} options - Options for creating a new connected account
   * @returns {Promise<ConnectionRequest>} Connection request object
   *
   * @example
   * ```typescript
   * // For OAuth2 authentication
   * const connectionRequest = await composio.connectedAccounts.initiate(
   *   'user_123',
   *   'auth_config_123',
   *   {
   *     callbackUrl: 'https://your-app.com/callback',
   *     config: AuthScheme.OAuth2({
   *       access_token: 'your_access_token',
   *       token_type: 'Bearer'
   *     })
   *   }
   * );
   *
   * // For API Key authentication
   * const connectionRequest = await composio.connectedAccounts.initiate(
   *   'user_123',
   *   'auth_config_123',
   *   {
   *     config: AuthScheme.ApiKey({
   *       api_key: 'your_api_key'
   *     })
   *   }
   * );
   *
   * // For Basic authentication
   * const connectionRequest = await composio.connectedAccounts.initiate(
   *   'user_123',
   *   'auth_config_123',
   *   {
   *     config: AuthScheme.Basic({
   *       username: 'your_username',
   *       password: 'your_password'
   *     })
   *   }
   * );
   * ```
   *
   * @link https://docs.composio.dev/reference/connected-accounts/create-connected-account
   */
  async initiate(
    userId: string,
    authConfigId: string,
    options?: CreateConnectedAccountOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectionRequest> {
    // Check if there are multiple connected accounts for the authConfig of the user
    const connectedAccount = await this.list(
      {
        userIds: [userId],
        authConfigIds: [authConfigId],
        statuses: [ConnectedAccountStatuses.ACTIVE],
      },
      requestOptions
    );
    if (connectedAccount.items.length > 0 && !options?.allowMultiple) {
      throw new ComposioMultipleConnectedAccountsError(
        `Multiple connected accounts found for user ${userId} in auth config ${authConfigId}. Please use the allowMultiple option to allow multiple connected accounts.`
      );
    } else if (connectedAccount.items.length > 0) {
      logger.warn(
        `[Warn:AllowMultiple] Multiple connected accounts found for user ${userId} in auth config ${authConfigId}`
      );
    }

    const state: ConnectionData | undefined = options?.config ?? undefined;
    // @TODO: Commenting this out. This is a temporary fix to allow api_key to be optional, in future ideally we should fix this from API side

    // if (options?.config) {
    //   const connectionDataParsed = ConnectionDataSchema.safeParse(options.config);
    //   if (!connectionDataParsed.success) {
    //     throw new ValidationError('Failed to parse connection data', {
    //       cause: connectionDataParsed.error,
    //     });
    //   }
    //   state = connectionDataParsed.data;
    // }

    const createParams: ConnectedAccountCreateParamsRaw = {
      auth_config: { id: authConfigId },
      connection: {
        callback_url: options?.callbackUrl,
        user_id: userId,
        state: state as ConnectedAccountCreateParamsRaw.Connection['state'],
        ...(options?.alias != null && { alias: options.alias }),
      },
    };

    let response: ConnectedAccountCreateResponse;
    let httpResponse: Response | undefined;
    try {
      // Chain `.withResponse()` so we can read the SEC-339 `Deprecation`
      // header (RFC 9745) the apollo retiring branch sets — that header is
      // emitted only when the auth config is Composio-managed AND on a
      // redirectable OAuth scheme, so it's the canonical signal that this
      // caller needs to migrate. Custom auth configs and non-OAuth schemes
      // never see the header, eliminating the false-positive warning that
      // an `auth_scheme`-only check produced for `link()`-unaffected callers.
      const apiCall = this.client.connectedAccounts.create(createParams, requestOptions);
      if (typeof (apiCall as { withResponse?: unknown }).withResponse === 'function') {
        const resolved = await withCancellation(
          () =>
            (
              apiCall as unknown as {
                withResponse: () => Promise<{
                  data: ConnectedAccountCreateResponse;
                  response: Response;
                }>;
              }
            ).withResponse(),
          requestOptions?.signal
        );
        response = resolved.data;
        httpResponse = resolved.response;
      } else {
        // Test mocks may return a plain Promise without `withResponse`.
        // Fall back to a naked await; the deprecation gate below stays
        // off in that case (no header to read).
        response = await withCancellation(() => apiCall, requestOptions?.signal);
      }
    } catch (error) {
      // Caller-initiated cancellation must surface as the typed error,
      // not get remapped to the legacy-endpoint error below.
      if (error instanceof ComposioRequestCancelledError) {
        throw error;
      }
      // When the server has flipped this org to the retired path, the legacy
      // endpoint returns 400 with a stable migration message. Surface it as
      // a typed error so callers get an actionable hint instead of a generic
      // BadRequestError.
      if (
        error instanceof BadRequestError &&
        typeof error.message === 'string' &&
        error.message.includes('no longer supported') &&
        error.message.includes('/api/v3/connected_accounts/link')
      ) {
        throw new ComposioLegacyConnectedAccountsEndpointRetiredError(error.message, {
          cause: error,
        });
      }
      throw error;
    }

    // Warn once per process when apollo flags this response as on the
    // retiring path. Header presence is a 1:1 signal — custom auth configs
    // and non-OAuth schemes get a clean response and stay silent, fixing
    // the false-positive that auth_scheme-based detection produced.
    if (!_legacyInitiateWarningEmitted && httpResponse?.headers.get('Deprecation')) {
      _legacyInitiateWarningEmitted = true;
      logger.warn(
        '[Deprecation] composio.connectedAccounts.initiate() will stop ' +
          'working for this auth config on or before 2026-07-03 (see Sunset ' +
          'header on the response). Switch to composio.connectedAccounts.link() — ' +
          'same return shape, same allowMultiple semantics. ' +
          'https://docs.composio.dev/docs/changelog/2026/04/24'
      );
    }

    const redirectUrl =
      typeof response.connectionData?.val?.redirectUrl === 'string'
        ? response.connectionData.val.redirectUrl
        : null;

    return createConnectionRequest(
      this.client,
      response.id,
      response.connectionData.val.status,
      redirectUrl
    );
  }

  /**
   * @description Create a Composio Connect Link for a user to connect their account to a given auth config. This method will return an external link which you can use the user to connect their account.
   *
   * @docs https://docs.composio.dev/reference/connected-accounts/create-connected-account#create-a-composio-connect-link
   *
   * @param userId {string} - The external user ID to create the connected account for.
   * @param authConfigId {string} - The auth config ID to create the connected account for.
   * @param options {CreateConnectedAccountLinkOptions} - Options for creating a new connected account link.
   * @param options.callbackUrl {string} - The url to redirect the user to post connecting their account.
   * @returns {ConnectionRequest} Connection request object
   *
   * @example
   * ```typescript
   * // create a connection request and redirect the user to the redirect url
   * const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123');
   * const redirectUrl = connectionRequest.redirectUrl;
   * console.log(`Visit: ${redirectUrl} to authenticate your account`);
   *
   * // Wait for the connection to be established
   * const connectedAccount = await connectionRequest.waitForConnection()
   * ```
   *
   * @example
   * ```typescript
   * // create a connection request and redirect the user to the redirect url
   * const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123', {
   *   callbackUrl: 'https://your-app.com/callback'
   * });
   * const redirectUrl = connectionRequest.redirectUrl;
   * console.log(`Visit: ${redirectUrl} to authenticate your account`);
   *
   * // Wait for the connection to be established
   * const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);
   * ```
   */
  async link(
    userId: string,
    authConfigId: string,
    options?: CreateConnectedAccountLinkOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectionRequest> {
    const parsedLinkOptions = CreateConnectedAccountLinkOptionsSchema.safeParse(options || {});
    if (!parsedLinkOptions.success) {
      throw new ValidationError('Failed to parse create connected account link options', {
        cause: parsedLinkOptions.error,
      });
    }

    const opts = parsedLinkOptions.data;

    // Mirror initiate(): guard against silently creating extra connections on
    // the same auth config unless the caller explicitly opts in. The preflight
    // list call honors the caller's signal too — the whole composite is
    // cancellable as a single unit.
    const existing = await this.list(
      {
        userIds: [userId],
        authConfigIds: [authConfigId],
        statuses: [ConnectedAccountStatuses.ACTIVE],
      },
      requestOptions
    );
    if (existing.items.length > 0 && !opts.allowMultiple) {
      throw new ComposioMultipleConnectedAccountsError(
        `Multiple connected accounts found for user ${userId} in auth config ${authConfigId}. Please use the allowMultiple option to allow multiple connected accounts.`
      );
    } else if (existing.items.length > 0) {
      logger.warn(
        `[Warn:AllowMultiple] Multiple connected accounts found for user ${userId} in auth config ${authConfigId}`
      );
    }

    const experimentalWire = serializeExperimentalForWire(opts.experimental);
    const body: LinkCreateParams = {
      auth_config_id: authConfigId,
      user_id: userId,
      ...(opts.callbackUrl !== undefined && { callback_url: opts.callbackUrl }),
      ...(opts.alias !== undefined && { alias: opts.alias }),
      ...(experimentalWire !== undefined && { experimental: experimentalWire }),
    };

    try {
      const response = await withCancellation(
        () => this.client.link.create(body, requestOptions),
        requestOptions?.signal
      );

      const connectionRequest = createConnectionRequest(
        this.client,
        response.connected_account_id,
        ConnectedAccountStatuses.INITIATED,
        response.redirect_url
      );
      return connectionRequest;
    } catch (error) {
      // Caller-initiated cancellation must surface as the typed error,
      // not get remapped to ComposioFailedToCreateConnectedAccountLink below.
      if (error instanceof ComposioRequestCancelledError) {
        throw error;
      }
      // The server rejects ACL on PRIVATE connections — surface that as a
      // typed error so callers can `instanceof` instead of grepping messages.
      if (
        error instanceof BadRequestError &&
        typeof error.message === 'string' &&
        error.message.includes(ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT)
      ) {
        throw new ComposioAclOnlyForSharedError(error.message, { cause: error });
      }
      throw new ComposioFailedToCreateConnectedAccountLink(
        'Failed to create connected account link',
        {
          cause: error,
        }
      );
    }
  }

  /**
   * Waits for a connection request to complete and become active.
   *
   * This method continuously polls the Composio API to check the status of a connection
   * until it either becomes active, enters a terminal error state, or times out.
   *
   * @param {string} connectedAccountId - The ID of the connected account to wait for
   * @param {number} [timeout=60000] - Maximum time to wait in milliseconds (default: 60 seconds)
   * @returns {Promise<ConnectedAccountRetrieveResponse>} The finalized connected account data
   * @throws {ComposioConnectedAccountNotFoundError} If the connected account cannot be found
   * @throws {ConnectionRequestFailedError} If the connection enters a failed, expired, or deleted state
   * @throws {ConnectionRequestTimeoutError} If the connection does not complete within the timeout period
   *
   * @example
   * ```typescript
   * // Wait for a connection to complete with default timeout
   * const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc');
   *
   * // Wait with a custom timeout of 2 minutes
   * const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc', 120000);
   * ```
   */
  async waitForConnection(
    connectedAccountId: string,
    timeout: number = 60000
  ): Promise<ConnectedAccountRetrieveResponse> {
    const connectionRequest = createConnectionRequest(this.client, connectedAccountId);
    return connectionRequest.waitForConnection(timeout);
  }

  /**
   * Retrieves a specific connected account by its ID.
   *
   * This method fetches detailed information about a single connected account
   * and transforms the response to the SDK's standardized format.
   *
   * @param {string} nanoid - The unique identifier of the connected account
   * @returns {Promise<ConnectedAccountRetrieveResponse>} The connected account details
   * @throws {Error} If the connected account cannot be found or an API error occurs
   *
   * @example
   * ```typescript
   * // Get a connected account by ID
   * const account = await composio.connectedAccounts.get('conn_abc123');
   * console.log(account.status); // e.g., 'ACTIVE'
   * console.log(account.toolkit.slug); // e.g., 'github'
   * ```
   */
  async get(
    nanoid: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountRetrieveResponse> {
    const response = await withCancellation(
      () => this.client.connectedAccounts.retrieve(nanoid, requestOptions),
      requestOptions?.signal
    );
    return transformConnectedAccountResponse(response);
  }

  /**
   * Deletes a connected account.
   *
   * This method permanently removes a connected account from the Composio platform.
   * This action cannot be undone and will revoke any access tokens associated with the account.
   *
   * @param {string} nanoid - The unique identifier of the connected account to delete
   * @returns {Promise<ConnectedAccountDeleteResponse>} The deletion response
   * @throws {Error} If the account doesn't exist or cannot be deleted
   *
   * @example
   * ```typescript
   * // Delete a connected account
   * await composio.connectedAccounts.delete('conn_abc123');
   * ```
   */
  async delete(
    nanoid: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountDeleteResponse> {
    return withCancellation(
      () => this.client.connectedAccounts.delete(nanoid, undefined, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Refreshes a connected account's authentication credentials.
   *
   * This method attempts to refresh OAuth tokens or other credentials associated with
   * the connected account. This is useful when a token has expired or is about to expire.
   *
   * @param {string} nanoid - The unique identifier of the connected account to refresh
   * @returns {Promise<ConnectedAccountRefreshResponse>} The response containing the refreshed account details
   * @throws {Error} If the account doesn't exist or credentials cannot be refreshed
   *
   * @example
   * ```typescript
   * // Refresh a connected account's credentials
   * const refreshedAccount = await composio.connectedAccounts.refresh('conn_abc123');
   * ```
   *
   * @deprecated The `POST /connected_accounts/{id}/refresh` endpoint is deprecated by the
   *   Composio API. Re-initiate authentication instead: `composio.connectedAccounts.link(userId, authConfigId)`
   *   for a fresh connection, or `session.authorize(toolkit)` from a session. Behaviour is unchanged
   *   while the endpoint remains available; do not generate new code against `refresh`.
   */
  async refresh(
    nanoid: string,
    options?: ConnectedAccountRefreshOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountRefreshResponse> {
    let params: ConnectedAccountRefreshParams | undefined = undefined;

    if (options) {
      const parsedOptions = ConnectedAccountRefreshOptionsSchema.safeParse(options);
      if (!parsedOptions.success) {
        throw new ValidationError('Failed to parse connected account refresh options', {
          cause: parsedOptions.error,
        });
      }

      if (parsedOptions.data.validateCredentials !== undefined) {
        logger.warn(
          'connectedAccounts.refresh(): the Composio API no longer accepts `validateCredentials`; the option is ignored.'
        );
      }

      params = {
        query_redirect_url: parsedOptions.data.redirectUrl,
      };
    }

    return withCancellation(
      () => this.client.connectedAccounts.refresh(nanoid, params, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Revoke a connected account at the upstream provider.
   *
   * Best-effort upstream revocation of the stored tokens/credentials; on
   * success the connection status becomes `REVOKED`. Revoking an already
   * revoked connection returns an empty `revokedTokens` list without an
   * upstream call.
   *
   * @param {string} nanoid - The unique identifier of the connected account to revoke
   * @returns {Promise<ConnectedAccountRevokeResponse>} Which tokens were revoked and the resulting status
   * @throws {ComposioConnectedAccountRevocationNotSupportedError} If the toolkit does not support programmatic revocation (400)
   * @throws {ComposioConnectedAccountNotRevokableError} If the connection is not in a revokable state (409)
   *
   * @example
   * ```typescript
   * const result = await composio.connectedAccounts.revoke('conn_abc123');
   * console.log(result.connectedAccount.status); // 'REVOKED'
   * console.log(result.revokedTokens); // e.g. ['access_token', 'refresh_token']
   * ```
   */
  async revoke(
    nanoid: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountRevokeResponse> {
    try {
      const result = await withCancellation(
        () => this.client.connectedAccounts.revoke(nanoid, requestOptions),
        requestOptions?.signal
      );
      return transformConnectedAccountRevokeResponse(result);
    } catch (error) {
      if (error instanceof BadRequestError) {
        throw new ComposioConnectedAccountRevocationNotSupportedError(
          `Connected account ${nanoid} cannot be revoked programmatically: ${error.message}`,
          { cause: error, meta: { nanoid } }
        );
      }
      if (error instanceof ConflictError) {
        throw new ComposioConnectedAccountNotRevokableError(
          `Connected account ${nanoid} is not in a revokable state: ${error.message}`,
          { cause: error, meta: { nanoid } }
        );
      }
      throw error;
    }
  }

  /**
   * Complete a deferred OAuth connection once you have verified the user's
   * identity.
   *
   * When your project has an OAuth callback verifier configured, Composio
   * does not activate a new OAuth connection by itself: it redirects to your
   * verifier with a single-use session URI. After confirming who the user is,
   * redeem that session URI here; Composio checks that your project owns the
   * pending connection and that `userId` is its owner, completes the token
   * exchange, and the connection becomes `ACTIVE`.
   *
   * The session URI is single-use: redeeming it twice, or after it expires,
   * fails with a 404 from the API.
   *
   * @param {ConnectedAccountCompleteAuthParams} params - `userId` the connection was initiated for and the verifier's `sessionUri`
   * @returns {Promise<ConnectedAccountCompleteAuthResponse>} The completed connection's ID and toolkit
   * @throws {ValidationError} If the params fail validation
   *
   * @example
   * ```typescript
   * // In your verifier route, after authenticating the user:
   * const { connectedAccountId, toolkitSlug } = await composio.connectedAccounts.completeAuth({
   *   userId: 'user_123',
   *   sessionUri, // the session URI from the verifier redirect
   * });
   * ```
   */
  async completeAuth(
    params: ConnectedAccountCompleteAuthParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountCompleteAuthResponse> {
    const parsedParams = ConnectedAccountCompleteAuthParamsSchema.safeParse(params);
    if (!parsedParams.success) {
      throw new ValidationError('Failed to parse connected account completeAuth params', {
        cause: parsedParams.error,
      });
    }
    const result = await withCancellation(
      () =>
        this.client.connectedAccounts.completeAuth(
          {
            user_id: parsedParams.data.userId,
            session_uri: parsedParams.data.sessionUri,
          },
          requestOptions
        ),
      requestOptions?.signal
    );
    return transformConnectedAccountCompleteAuthResponse(result);
  }

  /**
   * Update the status of a connected account
   * @param {string} nanoid - Unique identifier of the connected account
   * @param {ConnectedAccountUpdateStatusParams} params - Parameters for updating the status
   * @returns {Promise<ConnectedAccountUpdateStatusResponse>} Updated connected account details
   *
   * @example
   * ```typescript
   * // Enable a connected account
   * const updatedAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
   *   enabled: true
   * });
   *
   * // Disable a connected account with a reason
   * const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
   *   enabled: false,
   *   reason: 'Token expired'
   * });
   * ```
   */
  async updateStatus(
    nanoid: string,
    params: ConnectedAccountUpdateStatusParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountUpdateStatusResponse> {
    return withCancellation(
      () => this.client.connectedAccounts.updateStatus(nanoid, params, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Enable a connected account
   * @param {string} nanoid - Unique identifier of the connected account
   * @returns {Promise<ConnectedAccountUpdateStatusResponse>} Updated connected account details
   *
   * @example
   * ```typescript
   * // Enable a previously disabled connected account
   * const enabledAccount = await composio.connectedAccounts.enable('conn_abc123');
   * console.log(enabledAccount.isDisabled); // false
   * ```
   */
  async enable(
    nanoid: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountUpdateStatusResponse> {
    return withCancellation(
      () => this.client.connectedAccounts.updateStatus(nanoid, { enabled: true }, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Disable a connected account
   * @param {string} nanoid - Unique identifier of the connected account
   * @returns {Promise<ConnectedAccountUpdateStatusResponse>} Updated connected account details
   *
   * @example
   * ```typescript
   * // Disable a connected account
   * const disabledAccount = await composio.connectedAccounts.disable('conn_abc123');
   * console.log(disabledAccount.isDisabled); // true
   *
   * // You can also use updateStatus with a reason
   * // const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
   * //   enabled: false,
   * //   reason: 'No longer needed'
   * // });
   * ```
   */
  async disable(
    nanoid: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountUpdateStatusResponse> {
    return withCancellation(
      () => this.client.connectedAccounts.updateStatus(nanoid, { enabled: false }, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Update the per-user ACL on a SHARED connected account.
   * **Experimental — shape may change in future releases.**
   *
   * Only meaningful for SHARED connections — calling this on a PRIVATE
   * connection raises `ComposioAclOnlyForSharedError` (400). ACL writes
   * require the connection's creator or an API key.
   *
   * PATCH semantics: omit a field to leave it unchanged; pass an empty
   * array to clear an allow/deny list. At least one field must be
   * provided.
   *
   * @param {string} nanoid - The unique identifier of the connected account
   * @param {UpdateConnectedAccountAclParams} params - The ACL fields to patch
   * @returns {Promise<ConnectedAccountPatchResponse>} The PATCH response
   *
   * @example
   * ```typescript
   * // Allow every userId to use this SHARED connection
   * await composio.connectedAccounts.updateAcl('ca_abc123', { allowAllUsers: true });
   *
   * // Targeted allow list
   * await composio.connectedAccounts.updateAcl('ca_abc123', {
   *   allowedUserIds: ['user_alice', 'user_bob'],
   * });
   *
   * // Clear the allow list (back to deny-by-default unless allowAllUsers is true)
   * await composio.connectedAccounts.updateAcl('ca_abc123', { allowedUserIds: [] });
   * ```
   */
  async updateAcl(
    nanoid: string,
    params: UpdateConnectedAccountAclParams
  ): Promise<ConnectedAccountPatchResponse> {
    return updateConnectedAccountAcl(this.client, nanoid, params);
  }

  /**
   * Enable or disable a connected account. Accepts `{ enabled: boolean }`.
   *
   * Use `updateAcl()` for ACL writes on SHARED connections.
   *
   * @param {string} nanoid - The unique identifier of the connected account
   * @param {UpdateConnectedAccountParams} params - The update parameters
   * @returns {Promise<ConnectedAccountUpdateStatusResponse>} The update response
   *
   * @example
   * ```typescript
   * // Disable an account
   * await composio.connectedAccounts.update('ca_abc123', { enabled: false });
   * ```
   */
  async update(
    nanoid: string,
    params: UpdateConnectedAccountParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectedAccountUpdateStatusResponse> {
    const parsedParams = UpdateConnectedAccountParamsSchema.safeParse(params);
    if (!parsedParams.success) {
      throw new ValidationError('Failed to parse connected account update params', {
        cause: parsedParams.error,
      });
    }

    return withCancellation(
      () => this.client.connectedAccounts.updateStatus(nanoid, parsedParams.data, requestOptions),
      requestOptions?.signal
    );
  }
}