Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
/**
* @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
);
}
}