# Composio

Elixir client for the [Composio API](https://composio.dev) — tool and action integrations for AI agents.

## Installation

```elixir
def deps do
  [
    {:composio, "~> 0.1.0"}
  ]
end
```

## Quick Start

```elixir
# Create a client
client = Composio.client(api_key: "your-api-key")

# List available toolkits
{:ok, %{"items" => toolkits}} = Composio.Toolkits.list(client)

# List tools for a specific search
{:ok, %{"items" => tools}} = Composio.Tools.list(client, search: "github star")

# Execute a tool for a specific user
{:ok, result} = Composio.Tools.execute(client, "GITHUB_STAR_REPO",
  %{"owner" => "composiohq", "repo" => "composio"},
  user_id: "user-123"
)
```

## Multi-User Support

The client is designed for multi-tenant applications. Create one client per API key and pass `user_id` to individual operations:

```elixir
client = Composio.client(api_key: "your-key")

# Each user has their own connected accounts
{:ok, accounts} = Composio.ConnectedAccounts.list(client, user_id: "user-123")

# Execute tools on behalf of specific users
{:ok, result} = Composio.Tools.execute(client, "GMAIL_SEND_EMAIL",
  %{"to" => "bob@example.com", "subject" => "Hello"},
  user_id: "user-456"
)
```

## Connection Pooling

The library starts an HTTP/2 connection pool to `backend.composio.dev` automatically. HTTP/2 multiplexing allows many concurrent requests over a single connection.

Configure the pool in your application config:

```elixir
config :composio, :pool,
  count: 1,               # HTTP/2 connections (each handles ~256 concurrent requests)
  connect_timeout: 5_000   # TCP connect timeout in ms
```

## Modules

| Module | Description |
|--------|-------------|
| `Composio.Client` | Client struct and constructor |
| `Composio.Toolkits` | List and inspect available service integrations |
| `Composio.Tools` | List tool schemas, execute tools, proxy requests |
| `Composio.AuthConfigs` | Manage authentication configurations |
| `Composio.ConnectedAccounts` | Manage per-user authenticated connections |
| `Composio.TriggerTypes` | Browse available event trigger types |
| `Composio.TriggerInstances` | Manage active trigger subscriptions |
| `Composio.WebhookSubscriptions` | Manage webhook endpoints |
| `Composio.WebhookPlug` | Plug for webhook signature verification |

## License

MIT