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.

Add documentation related to connectedAccounts.waitforconnection

haxzie1765dd60f463
diff --git a/README.md b/README.md
index 7e66aa868..b1173891e 100644
--- a/README.md
+++ b/README.md
@@ -296,6 +296,30 @@ const connectionRequest = await composio.createConnectedAccount(
const connectedAccount = await connectionRequest.waitForConnection();
```
+### Waiting for Connection to be Established
+
+The SDK provides a convenient way to wait for a connection to be established using the `waitForConnection` method:
+
+```typescript
+// From a ConnectionRequest instance (after creating a connected account)
+// With default timeout (60 seconds)
+const connectedAccount = await connectionRequest.waitForConnection();
+
+// With custom timeout (2 minutes)
+const connectedAccount = await connectionRequest.waitForConnection(120000);
+
+// Directly from the ConnectedAccounts class (with an existing connected account ID)
+const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_abc123', 60000);
+```
+
+The method polls the Composio API until:
+
+- The connection becomes `ACTIVE` (returns the connected account)
+- The connection enters a terminal state (`FAILED`, `EXPIRED`, `DELETED`) and throws an error
+- The timeout is exceeded (throws a timeout error)
+
+This is particularly useful for OAuth flows where the user needs to authorize the connection in a browser.
+
### Managing Connected Accounts
```typescript
diff --git a/examples/connected-accounts/README.md b/examples/connected-accounts/README.md
new file mode 100644
index 000000000..4fdad69a5
--- /dev/null
+++ b/examples/connected-accounts/README.md
@@ -0,0 +1,97 @@
+# Connected Accounts Example
+
+This example demonstrates how to work with connected accounts in the Composio SDK, including authorization flows and waiting for connections to become active.
+
+## Overview
+
+Connected accounts in Composio enable your application to interact with third-party services on behalf of your users. This example showcases:
+
+1. Creating connection requests
+2. Directing users to authorization pages
+3. Waiting for connections to become active
+4. Using connected accounts with tools
+
+## Example Files
+
+- **toolkit-authorize.ts**: Demonstrates authorizing a toolkit and waiting for the connection
+- **magic-flow-demo.ts**: Shows how to use the magic flow for a streamlined connection experience
+- **index.ts**: Basic entry point that imports the examples
+
+## Using the waitForConnection Method
+
+The `waitForConnection` method is a crucial part of the connection flow. It allows your application to:
+
+- Poll the Composio API until a connection becomes active
+- Handle connection failures gracefully
+- Set appropriate timeouts for your use case
+
+### Syntax
+
+```typescript
+// From a ConnectionRequest object
+await connectionRequest.waitForConnection(timeout?: number): Promise<ConnectedAccountRetrieveResponse>
+
+// From the ConnectedAccounts class
+await composio.connectedAccounts.waitForConnection(
+ connectedAccountId: string,
+ timeout?: number
+): Promise<ConnectedAccountRetrieveResponse>
+```
+
+### Example Usage
+
+```typescript
+// Create a connection request
+const connectionRequest = await composio.toolkits.authorize('default', 'github');
+
+// If there's a redirect URL, show it to the user
+if (connectionRequest.redirectUrl) {
+ console.log(`Please visit: ${connectionRequest.redirectUrl}`);
+}
+
+// Wait for the connection to be established (with default 60s timeout)
+try {
+ const connectedAccount = await connectionRequest.waitForConnection();
+ console.log(`Connection successful! ID: ${connectedAccount.id}`);
+} catch (error) {
+ if (error instanceof ConnectionRequestTimeoutError) {
+ console.error('Connection timed out. Please try again.');
+ } else if (error instanceof ConnectionRequestFailedError) {
+ console.error(`Connection failed: ${error.message}`);
+ }
+}
+```
+
+### With Custom Timeout
+
+```typescript
+// Wait for up to 3 minutes
+const connectedAccount = await connectionRequest.waitForConnection(180000);
+```
+
+### Handling Connection States
+
+The `waitForConnection` method handles different connection states:
+
+- `ACTIVE`: Returns the connected account
+- `FAILED`, `EXPIRED`, `DELETED`: Throws a `ConnectionRequestFailedError`
+- Timeout exceeded: Throws a `ConnectionRequestTimeoutError`
+
+## Running This Example
+
+1. Install dependencies:
+
+ ```bash
+ pnpm install
+ ```
+
+2. Set your API key:
+
+ ```bash
+ export COMPOSIO_API_KEY=your_api_key
+ ```
+
+3. Run the example:
+ ```bash
+ pnpm start
+ ```
diff --git a/packages/core/README.md b/packages/core/README.md
index 6344eb106..ca2cec2d1 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -145,6 +145,26 @@ const connectionRequest = await composio.createConnectedAccount(
const connectedAccount = await connectionRequest.waitForConnection();
```
+### Waiting for Connection Establishment
+
+The `waitForConnection` method is available on both the `ConnectionRequest` and `ConnectedAccounts` classes. It allows you to poll for a connection to become active:
+
+```typescript
+// From a ConnectionRequest instance (returned by createConnectedAccount)
+const connectedAccount = await connectionRequest.waitForConnection(120000); // 2 minute timeout
+
+// From the ConnectedAccounts class (using a connected account ID)
+const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_abc123', 60000); // 1 minute timeout
+```
+
+The method continuously polls the Composio API until the connection:
+
+- Becomes `ACTIVE` (returns the connected account)
+- Enters a terminal state like `FAILED`, `EXPIRED`, or `DELETED` (throws an error)
+- Exceeds the specified timeout (throws a timeout error)
+
+If the connection does not complete within the provided timeout (default: 60 seconds), a `ConnectionRequestTimeoutError` is thrown.
+
### Managing Connected Accounts
```typescript