# @continual/integrations

This package provides integration modules for the Continual Agent Platform, allowing you to connect
your agents with various third-party services and APIs.

## Installation

### As a Dependency

```bash
npm install @continual/integrations
# or
yarn add @continual/integrations
# or
pnpm add @continual/integrations
```

### For CLI Access (Global Installation)

```bash
npm install -g @continual/integrations
# or
yarn global add @continual/integrations
# or
pnpm add -g @continual/integrations
```

After installing globally, you can use the `continual-apps` command anywhere in your terminal.

## Available Integrations

The package includes integrations with various services including:

- Coding
- Slack
- Linear
- GitHub
- Notion
- Google APIs
  - Google Drive
  - Gmail
  - Calendar
  - Meet transcripts
- Postgres
- SendGrid
- HubSpot
- And more...

## Usage

Import and use app builder functions from the integrations package:

```typescript
import {
  createLinearWorkspaceApp,
  createNotionMarkdownApp,
  createGithubWorkspaceApp,
  createGmailApp,
} from "@continual/integrations";

// Create a Linear app
const linearApp = createLinearWorkspaceApp();

// Create a Notion app
const notionApp = createNotionMarkdownApp();

// Create apps with configuration
const gmailApp = createGmailApp();
```

Each integration exports app builder functions and configuration schemas that can be used with the
Continual Agent SDK.

## CLI Commands

The `continual-apps` command line tool provides utilities for working with Continual integrations
and apps.

```bash
continual-apps [options] <command>
```

### Global Options

- `-c, --cwd <directory>`: Set the working directory

> **Note:** When using integrations that require OAuth (like Google, Linear, GitHub), you'll need to
> set up the appropriate OAuth credentials. You may see "No credentials provided" warnings if these
> are missing. See the [OAuth Credentials](#oauth-credentials) section below for details.

### Available Commands

- `serve`: Run an appserver with selected apps
- `list`: List all available apps that can be used with the serve command

### Serve Command

The `serve` command allows you to run a Continual appserver with selected integrations apps.

```bash
continual-apps serve [options]
```

#### Options

- `-p, --port <port>`: The port to run the server on (default: "3456")
- `-a, --apps <apps>`: Comma-separated list of apps to include (default: "computerUse")
- `-n, --networkproxy`: Enable a network proxy to expose your local server to the internet
- `-r, --register`: Enable self-registration of apps (requires CONTINUAL_API_KEY environment
  variable)

#### Examples

Run with default apps (computerUse):

```bash
continual-apps serve
```

Run with only the computerUse app:

```bash
continual-apps serve --apps computerUse
```

Run with a custom port:

```bash
continual-apps serve --port 4000
```

Run with network proxy (requires ngrok):

```bash
continual-apps serve --networkproxy
```

Run with auto-registration enabled:

```bash
export CONTINUAL_API_KEY=your_api_key
continual-apps serve --register
```

#### App Registration

When using the `--register` flag, the appserver will automatically register the running apps with
the Continual platform. This requires:

1. Setting the `CONTINUAL_API_KEY` environment variable with your Continual API key
2. The server must be accessible from the internet (consider using `--networkproxy` for local
   development)

If the `CONTINUAL_API_KEY` is not set when using `--register`, the command will exit with an error.

#### Using the Network Proxy

When you use the `--networkproxy` flag, the server uses ngrok to create a secure tunnel and expose
your local server to the internet. This is useful for:

- Testing webhooks that need to reach your local machine
- Sharing your development environment with remote collaborators
- Testing integrations that require a publicly accessible URL
- Enabling app registration in production workspace

To use this feature:

1. Make sure you have an ngrok account and authtoken
2. Set your ngrok authtoken as an environment variable:
   ```bash
   export NGROK_AUTHTOKEN=your_ngrok_authtoken
   ```
3. Start the server with the proxy enabled:
   ```bash
   continual-apps serve --networkproxy
   ```

The console will output the public URL that you can use to access your local server.

#### App Installation

When running the appserver without the `--register` flag:

- For built-in apps (like `computerUse`), the server will display an installation URL that you can
  use to install the app in your Continual workspace
- For custom apps, you'll need to manually register them through the Continual console or use the
  `--register` flag for automatic registration

The server will display clear instructions in the console for installing each app, including the
server URL and installation URL where applicable.

### List Command

The `list` command allows you to see all available apps that can be used with the serve command.

```bash
continual-apps list [options]
```

#### Options

- `-j, --json`: Output as JSON (useful for programmatic use)

#### Examples

List all available apps:

```bash
continual-apps list
```

Get apps in JSON format:

```bash
continual-apps list --json
```

## Documentation

For more detailed documentation on each integration, see the
[Continual documentation](https://docs.continual.ai).

### OAuth Credentials

When using the `continual-apps` CLI or any of the integration apps that require OAuth
authentication, you'll need to provide OAuth credentials for the respective services. The "No
credentials provided" messages you're seeing indicate that the necessary environment variables are
missing.

#### Required Environment Variables

Below are the environment variables needed for each OAuth-based integration:

##### Linear

```bash
# Option 1: Provide credentials as JSON data
LINEAR_OAUTH_CREDENTIALS_DATA={"clientId":"your-client-id","clientSecret":"your-client-secret"}

# Option 2: Provide path to a credentials file
LINEAR_OAUTH_CREDENTIALS_PATH=path/to/linear-credentials.json

# Required for webhook functionality
LINEAR_WEBHOOK_SECRET=your-webhook-secret
```

##### GitHub

```bash
# Option 1: Provide credentials as JSON data
GITHUB_OAUTH_CREDENTIALS_DATA={"clientId":"your-client-id","clientSecret":"your-client-secret"}

# Option 2: Provide path to a credentials file
GITHUB_OAUTH_CREDENTIALS_PATH=path/to/github-credentials.json

# Required for GitHub App installation
GITHUB_APP_ID=your-app-id
GITHUB_APP_PRIVATE_KEY=your-private-key
GITHUB_WEBHOOK_SECRET=your-webhook-secret
```

##### Google (Gmail, Calendar, Drive, etc.)

```bash
# Option 1: Provide credentials as JSON data
GOOGLE_OAUTH_CREDENTIALS_DATA={"web":{"client_id":"your-client-id","client_secret":"your-client-secret","redirect_uris":["your-redirect-uri"]}}

# Option 2: Provide path to a credentials file
GOOGLE_OAUTH_CREDENTIALS_PATH=path/to/google-credentials.json
```

##### Notion

```bash
# Option 1: Provide credentials as JSON data
NOTION_OAUTH_CREDENTIALS_DATA={"clientId":"your-client-id","clientSecret":"your-client-secret"}

# Option 2: Provide path to a credentials file
NOTION_OAUTH_CREDENTIALS_PATH=path/to/notion-credentials.json
```

##### HubSpot

```bash
# Option 1: Provide credentials as JSON data
HUBSPOT_OAUTH_CREDENTIALS_DATA={"clientId":"your-client-id","clientSecret":"your-client-secret"}

# Option 2: Provide path to a credentials file
HUBSPOT_OAUTH_CREDENTIALS_PATH=path/to/hubspot-credentials.json
```

#### How to Set Up

1. Create a `.env` file in your project root or the location where you're running the CLI
2. Add the relevant environment variables from the list above
3. Make sure to load the environment variables before running the CLI, for example:
   ```bash
   source .env && continual-apps list
   ```

#### For Development Testing

When testing locally without real credentials, you can:

1. Create stub/mock credentials for development
2. Use the `dotenv` package to load credentials from a `.env` file
3. Pass credentials directly via command line or configuration files

#### Getting OAuth Credentials

Each service has its own process for obtaining OAuth credentials:

- **Linear**: Create an OAuth app in your
  [Linear Developer Settings](https://linear.app/settings/api/applications)
- **GitHub**: Register an OAuth App in your
  [GitHub Developer Settings](https://github.com/settings/developers)
- **Google**: Create OAuth credentials in the
  [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
- **Notion**: Create an integration in the
  [Notion Integrations dashboard](https://www.notion.so/my-integrations)
- **HubSpot**: Create an app in the [HubSpot Developer Portal](https://developers.hubspot.com/)

## License

See license file in the root of the project.
