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 [email protected]

Installation

npm install @pompeii-labs/aqueducts

Usage

Initialize Client

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

await aqueduct.test();

List Integrations

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

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.

// 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: '[email protected]'
    }
});

// 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.

// 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: '[email protected]'
    }
});

// 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.

// 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: '[email protected]'
    }
});

// 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.

// 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.

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

await connection.updateMetadata({
    ...connection.metadata,
    email: '[email protected]'
});

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 [email protected]