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.

5.3 KB
Raw Blame
/**
 * @fileoverview Connection request function for Composio SDK, used to manage an initiated connection request.
 *
 * @author Musthaq Ahamad <[email protected]>
 * @date 2025-05-05
 * @module ConnectionRequest
 */
import ComposioClient from '@composio/client';
import {
  ConnectedAccountStatus,
  ConnectedAccountStatuses,
  ConnectedAccountRetrieveResponse,
} from '../types/connectedAccounts.types';
import {
  ConnectionRequestFailedError,
  ConnectionRequestTimeoutError,
} from '../errors/ConnectionRequestErrors';
import { ComposioConnectedAccountNotFoundError } from '../errors/ConnectedAccountsErrors';
import { telemetry } from '../telemetry/Telemetry';
import { transformConnectedAccountResponse } from '../utils/transformers/connectedAccounts';
import { ConnectionRequest, ConnectionRequestState } from '../types/connectionRequest.types';

/**
 * Creates a connection request object with methods to manage the connection lifecycle.
 *
 * @param {ComposioClient} client - The Composio client instance
 * @param {string} connectedAccountId - The ID of the connected account
 * @param {ConnectedAccountStatus} [status] - Initial status of the connection
 * @param {string | null} [redirectUrl] - OAuth redirect URL if applicable
 * @returns {ConnectionRequestState & { waitForConnection: (timeout?: number) => Promise<ConnectedAccountRetrieveResponse> }}
 * Connection request object with state and methods
 */
export function createConnectionRequest(
  client: ComposioClient,
  connectedAccountId: string,
  status?: ConnectedAccountStatus,
  redirectUrl?: string | null
): ConnectionRequest {
  const state: ConnectionRequestState = {
    id: connectedAccountId,
    status: status || ConnectedAccountStatuses.INITIATED,
    redirectUrl,
  };

  telemetry.instrument(state, 'ConnectionRequest');

  /**
   * Waits for the connection request to complete and become active.
   *
   * This method continuously polls the Composio API to check the status of the connection request
   * until it either becomes active, enters a terminal error state, or times out.
   *
   * @param {number} [timeout=60000] - Maximum time to wait in milliseconds before timing out (default: 60 seconds)
   * @returns {Promise<ConnectedAccountRetrieveResponse>} The final connected account response when successful
   * @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 request does not complete within the timeout period
   *
   * @example
   * ```typescript
   * // Wait for connection with default timeout (60 seconds)
   * try {
   *   const connection = await connectionRequest.waitForConnection();
   *   console.log('Connection established:', connection.id);
   * } catch (error) {
   *   console.error('Connection failed:', error.message);
   * }
   *
   * // Wait for connection with custom timeout (2 minutes)
   * const connection = await connectionRequest.waitForConnection(120000);
   * ```
   */
  async function waitForConnection(
    timeout: number = 60000
  ): Promise<ConnectedAccountRetrieveResponse> {
    const terminalErrorStates: ConnectedAccountStatus[] = [
      ConnectedAccountStatuses.FAILED,
      ConnectedAccountStatuses.EXPIRED,
      ConnectedAccountStatuses.REVOKED,
    ];
    const failIfTerminal = (response: {
      status: ConnectedAccountStatus;
      status_reason?: string | null;
    }) => {
      if (terminalErrorStates.includes(response.status)) {
        throw new ConnectionRequestFailedError(
          `Connection request failed with status: ${response.status}${response.status_reason ? `, reason: ${response.status_reason}` : ''}`,
          {
            meta: {
              connectedAccountId: state.id,
              status: response.status,
              statusReason: response.status_reason,
            },
          }
        );
      }
    };

    try {
      const response = await client.connectedAccounts.retrieve(state.id);
      if (response.status === ConnectedAccountStatuses.ACTIVE) {
        state.status = ConnectedAccountStatuses.ACTIVE;
        return transformConnectedAccountResponse(response);
      }
      failIfTerminal(response);
    } catch (error) {
      if (error instanceof ComposioClient.NotFoundError) {
        throw new ComposioConnectedAccountNotFoundError(
          `Connected account with id ${state.id} not found`,
          {
            meta: {
              connectedAccountId: state.id,
            },
          }
        );
      } else {
        throw error;
      }
    }

    const start = Date.now();
    const pollInterval = 1000;

    while (Date.now() - start < timeout) {
      try {
        const response = await client.connectedAccounts.retrieve(state.id);

        state.status = response.status;
        if (response.status === ConnectedAccountStatuses.ACTIVE) {
          return transformConnectedAccountResponse(response);
        }

        failIfTerminal(response);

        await new Promise(resolve => setTimeout(resolve, pollInterval));
      } catch (error) {
        throw error;
      }
    }

    throw new ConnectionRequestTimeoutError(`Connection request timed out for ${state.id}`);
  }

  return {
    ...state,
    waitForConnection,
    toJSON: () => ({ ...state }),
    toString: () => JSON.stringify(state, null, 2),
  };
}