composiohq__composio/ts

Composio SDK v3

The Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. It helps you connect to various services (toolkits), execute tools, and manage user connections seamlessly.

Features

• Execute tools from various services (GitHub, Gmail, Slack, etc.)
• Manage user connections to external services
• Create session-scoped custom tools with your own logic
• Integrate with AI providers like OpenAI
• Powerful middleware and modifier support
• Extensive error handling

Documentation

The SDK is thoroughly documented in the docs directory:

• Overview - Introduction and key concepts
• Getting Started - Quick start guide
• Core Concepts - Fundamental SDK concepts
• Configuration - Environment variables and SDK configuration

API Reference

• Composio Class - Main SDK class
• Tools - Listing, fetching, and executing tools
• Tool Router - Sessions, search, and custom tools
• Toolkits - Working with tool collections
• Connected Accounts - User authentication
• Auth Configs - Authentication configuration
• Providers - AI integration options

Provider Documentation

• OpenAI Provider - Using OpenAI with Composio
• Google Provider - Using Google GenAI with Composio
• Custom Providers - Creating new providers

Advanced Topics

• Error Handling - Managing errors
• Middleware and Modifiers - Customizing tools
• Telemetry - SDK usage tracking
• Custom Providers - Detailed provider guide

Internal Documentation

For SDK maintainers and contributors:

• Configuration and Environment Variables - Detailed guide on SDK configuration
• Triggers Implementation - Internal workings of the trigger system

Installation

# Using npm
npm install @composio/core

# Using yarn
yarn add @composio/core

# Using pnpm
pnpm add @composio/core

Quick Start

import { Composio } from '@composio/core';

// Initialize the SDK
const composio = new Composio({
  apiKey: 'your-api-key',
});

// Get tools from a specific toolkit
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
});

// Get a specific tool
const specificTool = await composio.tools.get('default', 'GITHUB_GET_REPOS');

// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
  userId: 'default',
  arguments: {
    owner: 'composio',
    repo: 'sdk',
  },
});

console.log(result.data);

OpenAI Integration

import { Composio } from '@composio/core';
import OpenAI from 'openai';

// Initialize Composio and OpenAI
const composio = new Composio({
  apiKey: 'your-composio-api-key',
});

const openai = new OpenAI({
  apiKey: 'your-openai-api-key',
});

// Get GitHub tools
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
});


// Create a chat completion with the tools
const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: 'You are a helpful assistant with access to GitHub tools.' },
    { role: 'user', content: 'Find information about the Composio SDK repository' },
  ],
  tools, // Pass the tools to OpenAI
});

// If the model wants to use a tool
if (completion.choices[0].message.tool_calls) {
  const toolCall = completion.choices[0].message.tool_calls[0];
  const args = JSON.parse(toolCall.function.arguments);

  // Execute the tool
  const result = await composio.tools.execute(toolCall.function.name, {
    userId: 'default',
    arguments: args,
  });

  console.log(result.data);
}

Creating Custom Tools

import { Composio, experimental_createTool } from '@composio/core';
import { z } from 'zod';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

const weatherForecast = experimental_createTool('WEATHER_FORECAST', {
  name: 'Weather Forecast',
  description: 'Get the weather forecast for a location',
  inputParams: z.object({
    location: z.string().describe('The location to get the forecast for'),
    days: z.number().optional().default(3).describe('Number of days for the forecast'),
  }),
  execute: async (input) => {
    const { location, days = 3 } = input;
    const forecast = await getWeatherForecast(location, days);
    return { forecast };
  },
});

const session = await composio.create('default', {
  experimental: { customTools: [weatherForecast] },
});

const result = await session.execute('WEATHER_FORECAST', {
  location: 'San Francisco, CA',
});

Project Structure

composio/
├── packages/                  # Main packages directory
│   ├── core/                  # Core SDK package
│   └── providers/             # Provider implementations
├── examples/                  # Example implementations
│   ├── connected-accounts/    # Connected accounts examples
│   ├── langchain/            # LangChain integration examples
│   ├── openai/               # OpenAI integration examples
│   ├── modifiers/            # Modifiers examples
│   ├── toolkits/             # Toolkits examples
│   └── vercel/               # Vercel AI examples
├── docs/                      # Documentation
├── scripts/                   # Development and build scripts
└── .github/                   # GitHub configuration

Development Setup

1. Prerequisites

   • Node.js (Latest LTS version recommended)
   • pnpm (v10.8.0 or later)
   • bun for productivity (optional)

2. Clone and Install

   git clone https://github.com/ComposioHQ/sdk-v3-ts.git
   cd composio
   pnpm install
   

3. Build

   pnpm build
   

4. Development Commands

   # Lint code
   pnpm lint
   
   # Fix linting issues
   pnpm lint:fix
   
   # Format code
   pnpm format
   
   # Create a new provider
   pnpm create:provider <provider-name> [--agentic]
   
   # Create a new example
   pnpm create:example <example-name>
   
   # Check peer dependencies
   pnpm check:peer-deps
   
   # Update peer dependencies
   pnpm update:peer-deps
   

Creating a New Example

1. Use the create:example script:

   pnpm create:example my-example
   

2. The script will create a new example in examples/my-example with:

   • package.json with minimal dependencies (@composio/core and dotenv)
   • tsconfig.json for TypeScript configuration
   • .env.example and .env files for environment variables
   • src/index.ts with basic Composio SDK setup
   • README.md with setup and usage instructions
   • Dependencies automatically installed

3. Next steps after creation:

   • Edit .env and add your COMPOSIO_API_KEY
   • Customize src/index.ts with your example logic
   • Add any additional dependencies as needed
   • Run with pnpm start or pnpm dev (with file watching)

Creating a New Provider

1. Use the create:provider script:

   pnpm create:provider my-provider [--agentic]
   

2. The script will create a new provider in packages/providers/my-provider with:

   • Basic provider implementation
   • TypeScript configuration
   • Package configuration
   • README template

3. Implement the required methods in src/index.ts:

   • For non-agentic providers: wrapTool and wrapTools
   • For agentic providers: wrapTool, wrapTools, and execution handlers

Release Process

For detailed information about both automated and manual release processes, please refer to our Release Process Documentation.

Environment Variables

• COMPOSIO_API_KEY: Your Composio API key
• COMPOSIO_BASE_URL: Custom API base URL (optional)
• COMPOSIO_LOG_LEVEL: Logging level (silent, error, warn, info, debug)
• COMPOSIO_DISABLE_TELEMETRY: Disable telemetry when set to "true"
• COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>: Specific version for a toolkit (e.g., COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00)
• DEVELOPMENT: Development mode flag
• CI: CI environment flag

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

License

ISC License

Support

For support, please visit our Documentation or join our Discord Community.