@pompeii-labs/aqueducts/README.md

The Aqueducts integration SDK from Pompeii Labs

# Aqueduct SDK

A TypeScript SDK for interacting with the Aqueducts API - the easiest way to use integrations for AI agents.

https://aqueducts.dev

**Note:** Before you write any code, create your project in the Aqueducts dashboard and get your project API key.

For any integrations you set up, you will need to register the Aqueducts' redirect URL - `https://api.aqueducts.dev/v1/oauth/callback`.

For questions or support, email [matty@pompeiilabs.com](mailto:matty@pompeiilabs.com)

## Installation

```bash
npm install @pompeii-labs/aqueducts
```

## Usage

### Initialize Client

```typescript
import { Aqueduct } from '@pompeii-labs/aqueducts';
import dotenv from 'dotenv';

dotenv.config();

// API key will be automatically pulled from AQUEDUCT_API_KEY env var
const aqueduct = new Aqueduct();

// Or provide API key directly
const aqueduct = new Aqueduct(process.env.AQUEDUCT_API_KEY);
```

### Test Connection

```typescript
await aqueduct.test();
```

### List Integrations

You can list all integrations that have been configured for your project.

```typescript
const integrations = await aqueduct.listIntegrations();
```

### Get Auth URL

Use `authUrl` to get a signed Oauth2 url for a specific integration. When you / your user clicks the link, they will be redirected to connect their account in the respective service.

```typescript
// Start the OAuth process for a provider
const authUrl = await aqueduct.authUrl({
    provider: 'github',
    userId: 'userId'
});

// Optionally pass metadata to the integration
const authUrl = await aqueduct.authUrl({
    provider: 'github',
    userId: 'mattyId',
    metadata: {
        email: 'matty@pompeiilabs.com'
    }
});

// Optionally pass a redirect URI to return your user to after they connect their account
const authUrl = await aqueduct.authUrl({
    provider: 'github',
    userId: 'userId',
    redirectUri: 'https://your-app.com/callback'
});
```

### Get Connection

You can find a connection on a specific provider by searching with connection ID, user ID, and/or metadata.

```typescript
// Get by connection ID
const connection = await aqueduct.getConnection({
    provider: 'github',
    connectionId: 'userId'
});

// Get by metadata
const connection = await aqueduct.getConnection({
    provider: 'github',
    metadata: {
        email: 'matty@pompeiilabs.com'
    }
});

// Force refresh the connection
const connection = await aqueduct.getConnection({
    provider: 'github',
    connectionId: 'userid',
    force_refresh: true
});
```

### List Connections

You can list all connections for a project, optionally filtered by provider, connection ID, user ID, or metadata.

```typescript
// List all connections
const connections = await aqueduct.listConnections({});

// List connections for a specific provider
const connections = await aqueduct.listConnections({
    provider: 'github'
});

// List connections with metadata filter
const connections = await aqueduct.listConnections({
    provider: 'github',
    metadata: {
        email: 'matty@pompeiilabs.com'
    }
});

// Force refresh all listed connections
const connections = await aqueduct.listConnections({
    provider: 'github',
    forceRefresh: true
});
```

### Delete Connection

You can delete a connection once you have retrieved it.

```typescript
// Get a connection
const connection = await aqueduct.getConnection({
    provider: 'github',
    userId: 'userId'
});

// Delete the connection
await connection.delete();
```

### Update Connection Metadata

You can update the metadata for a connection once you have retrieved it.

```typescript
const connection = await aqueduct.getConnection({
    provider: 'github',
    userId: 'userId'
});

await connection.updateMetadata({
    ...connection.metadata,
    email: 'matty@pompeiilabs.com'
});
```

## Environment Variables

- `AQUEDUCT_API_KEY`: Your Aqueduct API key (optional if provided in constructor)

## Types

The SDK is typed for the following integrations:

- github
- google
- gcal
- gmail
- drive
- slack_bot
- notion
- linear
- quickbooks
- quickbooks_dev

If you need support for another integration, please reach out to [hello@pompeiilabs.com](mailto:hello@pompeiilabs.com)