1
# Contributing to Composio SDK
2
3
-Thank you for your interest in contributing to Composio SDK! This document provides guidelines and instructions for contributing to the project.
3
+Thank you for your interest in contributing to Composio. This guide covers the root SDK repository. The monorepo contains the TypeScript SDK, Python SDK, docs site, examples, and release tooling.
4
5
## Table of Contents
6
7
- [Development Setup](#development-setup)
8
- [Project Structure](#project-structure)
9
+- [Development Commands](#development-commands)
10
- [Coding Standards](#coding-standards)
11
- [Documentation Requirements](#documentation-requirements)
12
- [Pull Request Process](#pull-request-process)
13
- [Creating New Providers](#creating-new-providers)
14
- [Testing Guidelines](#testing-guidelines)
15
- [Release Process](#release-process)
16
+- [Questions and Support](#questions-and-support)
17
18
## Development Setup
19
20
### Prerequisites
21
20
-- Node.js (Latest LTS version recommended)
21
-- [pnpm](https://pnpm.io/) (v10.8.0 or later)
22
-- [bun](https://bun.sh) for productivity (optional)
22
+Tool versions are pinned in [`mise.toml`](mise.toml), which is the source of truth for local development and CI:
23
+
24
+- Node.js 24.17.0
25
+- pnpm 11.8.0
26
+- Bun 1.3.10
27
+- Deno 2.6.7
28
+- Python 3.12
29
+- uv 0.8.19
30
+
31
+Use [mise](https://mise.jdx.dev) to install the toolchain:
32
+
33
+```bash
34
+mise install
35
+```
36
+
37
+pnpm is installed through mise's npm backend. Do not rely on Corepack for this repository.
38
39
### Getting Started
40
45
cd composio
46
```
47
33
-2. Install dependencies:
48
+2. Install the pinned toolchain:
49
+
50
+ ```bash
51
+ mise install
52
+ ```
53
+
54
+3. Install dependencies:
55
56
```bash
57
pnpm install
58
```
59
39
-3. Build the project:
60
+4. Build the project:
61
62
```bash
63
pnpm build
64
```
65
45
-4. Run tests:
66
+5. Run tests:
67
+
68
```bash
69
pnpm test
70
```
71
50
-### Development Commands
72
+## Project Structure
73
+
74
+```text
75
+composio/
76
+├── ts/ # TypeScript SDK workspace
77
+│ ├── packages/
78
+│ │ ├── core/ # Core SDK package (@composio/core)
79
+│ │ ├── cli/ # CLI binary and command implementations
80
+│ │ ├── cli-keyring/ # Keyring helper for the CLI
81
+│ │ ├── cli-local-tools/ # Local tools support for the CLI
82
+│ │ ├── providers/ # AI framework provider adapters
83
+│ │ ├── json-schema-to-zod/ # Schema conversion utility
84
+│ │ └── ts-builders/ # TypeScript build helpers
85
+│ ├── e2e-tests/ # Runtime and CLI end-to-end tests
86
+│ ├── examples/ # TypeScript examples
87
+│ └── scripts/ # TypeScript build and maintenance scripts
88
+├── python/ # Python SDK
89
+│ ├── composio/ # Main Python package
90
+│ ├── providers/ # Python provider adapters
91
+│ ├── tests/ # pytest test suite
92
+│ ├── scripts/ # Python development and release scripts
93
+│ └── docs/ # Python release notes and process docs
94
+├── docs/ # Documentation site
95
+├── test/ # Root-level release/install script tests
96
+└── .github/ # GitHub Actions and shared CI actions
97
+```
98
+
99
+## Development Commands
100
101
```bash
53
-# Lint code
102
+# Build all packages
103
+pnpm build
104
+
105
+# Build TypeScript packages only
106
+pnpm build:packages
107
+
108
+# Lint TypeScript packages
109
pnpm lint
110
56
-# Fix linting issues
111
+# Fix lint issues where possible
112
pnpm lint:fix
113
59
-# Format code
114
+# Format supported files
115
pnpm format
116
62
-# Create a new provider
117
+# Create a new TypeScript provider
118
pnpm create:provider <provider-name> [--agentic]
119
65
-# Create a new example
120
+# Create a new TypeScript example
121
pnpm create:example <example-name>
122
123
# Check peer dependencies
127
pnpm update:peer-deps
128
```
129
75
-## Project Structure
130
+## Coding Standards
131
77
-```
78
-composio/
79
-├── packages/ # Main packages directory
80
-│ ├── core/ # Core SDK package
81
-│ └── providers/ # Provider implementations
82
-├── examples/ # Example implementations
83
-├── docs/ # Documentation
84
-├── scripts/ # Development and build scripts
85
-└── .github/ # GitHub configuration
86
-```
132
+### TypeScript
133
88
-## Coding Standards
134
+1. Follow the style of the package you are editing.
135
+2. Use TypeScript for new TypeScript SDK code.
136
+3. Use named exports for public APIs unless the local package pattern says otherwise.
137
+4. Keep public API changes typed and documented with TSDoc.
138
+5. Add focused tests for new behavior and bug fixes.
139
+6. Use ESLint and Prettier through the repo scripts.
140
+7. Keep generated or vendored code out of manual edits unless the package explicitly owns that output.
141
90
-### File Headers
91
-
92
-Every source file must include a header comment with:
93
-
94
-```typescript
95
-/**
96
- * @file Description of what this file does/contains
97
- * @module path/to/module
98
- * @description Detailed description of the file's purpose
99
- *
100
- * @author Original Author <email@example.com>
101
- * @contributors
102
- * - Contributor Name <email@example.com>
103
- *
104
- * @copyright Composio 2024
105
- * @license ISC
106
- *
107
- * @see {@link https://related.documentation.link}
108
- * @see {@link https://another.related.link}
109
- */
110
-```
142
+### Python
143
112
-### Function Documentation
113
-
114
-Every user-facing function must include:
115
-
116
-1. TSDoc documentation
117
-2. Example usage
118
-3. Parameter and return type descriptions
119
-4. Error cases
120
-
121
-Example:
122
-
123
-````typescript
124
-/**
125
- * Executes a tool with the given parameters.
126
- *
127
- * @description
128
- * This function executes a tool with the provided parameters and returns the result.
129
- * It handles authentication, parameter validation, and error cases automatically.
130
- *
131
- * @example
132
- * ```typescript
133
- * const result = await executeTool('GMAIL_SEND_EMAIL', {
134
- * userId: 'user123',
135
- * arguments: {
136
- * to: 'recipient@example.com',
137
- * subject: 'Hello',
138
- * body: 'Message content'
139
- * }
140
- * });
141
- * ```
142
- *
143
- * @param {string} toolId - The unique identifier of the tool to execute
144
- * @param {ExecuteToolOptions} options - Tool execution options
145
- * @returns {Promise<ExecuteToolResult>} The result of the tool execution
146
- *
147
- * @throws {ToolNotFoundError} When the specified tool doesn't exist
148
- * @throws {ValidationError} When required parameters are missing
149
- * @throws {AuthenticationError} When authentication fails
150
- *
151
- * @see {@link https://docs.composio.dev/api/tools#execute}
152
- */
153
-export async function executeTool(
154
- toolId: string,
155
- options: ExecuteToolOptions
156
-): Promise<ExecuteToolResult> {
157
- // Implementation
158
-}
159
-````
160
-
161
-### Code Style
162
-
163
-1. Use TypeScript for all new code
164
-2. Follow the existing code style in the repository
165
-3. Use ESLint and Prettier for code formatting
166
-4. Use meaningful variable and function names
167
-5. Keep functions small and focused
168
-6. Write unit tests for all new code
169
-7. Use async/await instead of Promises
170
-8. Use named exports instead of default exports
171
-9. Use const assertions for constants
172
-10. Use type assertions sparingly
144
+1. Follow the existing Python SDK layout under `python/`.
145
+2. Use Ruff formatting and linting through the Python make targets.
146
+3. Keep provider-specific changes inside the relevant `python/providers/*` package.
147
+4. Add pytest coverage for behavior changes.
148
149
### Error Handling
150
176
-1. Use custom error classes
177
-2. Include meaningful error messages
178
-3. Document error cases in TSDoc
179
-4. Include error codes for API errors
180
-5. Log errors appropriately
181
-
182
-Example:
183
-
184
-```typescript
185
-/**
186
- * Custom error for tool execution failures.
187
- */
188
-export class ToolExecutionError extends ComposioError {
189
- constructor(
190
- message: string,
191
- public readonly toolId: string,
192
- public readonly cause?: Error
193
- ) {
194
- super(message, 'TOOL_EXECUTION_ERROR');
195
- this.name = 'ToolExecutionError';
196
- }
197
-}
198
-```
151
+1. Use the existing error classes and result shapes in the package you are editing.
152
+2. Include enough context in error messages to identify the failing operation.
153
+3. Avoid swallowing errors unless the caller has an explicit fallback path.
154
155
## Documentation Requirements
156
202
-### Package Documentation
203
-
204
-Each package must include:
205
-
206
-1. README.md with:
157
+Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage.
158
208
- - Package description
209
- - Installation instructions
210
- - Usage examples
211
- - API reference
212
- - Environment variables
213
- - Contributing guidelines
159
+For documentation-site work, read [`docs/CLAUDE.md`](docs/CLAUDE.md) first. It documents the docs app, MDX conventions, link checking, generated data, and docs branch workflow.
160
215
-2. API documentation:
161
+Package documentation should generally include:
162
217
- - TSDoc for all public APIs
218
- - Example code snippets
219
- - Error handling documentation
220
- - Type definitions
221
-
222
-3. Example implementations:
223
- - Basic usage example
224
- - Advanced usage examples
225
- - Integration examples
226
-
227
-### Provider Documentation
228
-
229
-Provider packages must additionally include:
230
-
231
-1. Provider-specific setup instructions
232
-2. Authentication requirements
233
-3. Supported features
234
-4. Limitations and constraints
235
-5. Integration examples
236
-6. Streaming support details
237
-7. Error handling examples
163
+1. A short package description.
164
+2. Installation instructions.
165
+3. Usage examples.
166
+4. Public API notes.
167
+5. Environment variables or authentication requirements when relevant.
168
+6. Provider limitations or streaming details when relevant.
169
170
## Pull Request Process
171
241
-1. Create a new branch for your changes:
172
+1. Create a branch from the target base branch. Most active SDK and docs work targets `next`.
173
174
```bash
175
+ git checkout next
176
+ git pull origin next
177
git checkout -b feature/your-feature-name
178
```
179
247
-2. Make your changes following the coding standards
180
+2. Make focused changes that match the issue or feature scope.
181
249
-3. Add tests for new functionality
182
+3. Add or update tests for behavior changes.
183
251
-4. Update documentation as needed
184
+4. Update documentation when user-facing behavior changes.
185
253
-5. Create a changeset:
186
+5. Add a changeset for changes that affect published TypeScript packages:
187
188
```bash
189
pnpm changeset
190
```
191
259
-6. Push your changes and create a pull request
192
+ Root-level documentation-only changes, such as edits to this file, do not need a changeset.
193
+
194
+6. Run the smallest meaningful verification command locally before opening the PR.
195
261
-7. Wait for review and address any feedback
196
+7. Push your branch and open a PR against the correct base branch.
197
198
## Creating New Providers
199
265
-1. Use the provider creation script:
200
+### TypeScript Providers
201
267
- ```bash
268
- pnpm create:provider my-provider [--agentic]
269
- ```
202
+Use the TypeScript provider creation script:
203
+
204
+```bash
205
+pnpm create:provider my-provider [--agentic]
206
+```
207
271
-2. Implement required methods:
208
+Then:
209
273
- - For non-agentic providers: `wrapTool` and `wrapTools`, and helper functions
274
- - For agentic providers: `wrapTool`, `wrapTools`, and execution handlers
210
+1. Implement the required provider methods.
211
+2. Add tests under the provider package.
212
+3. Add examples or docs when the provider has user-facing setup details.
213
+4. Run the package tests and relevant build checks.
214
+
215
+### Python Providers
216
+
217
+Use the Python provider creation target from the `python/` directory:
218
+
219
+```bash
220
+cd python
221
+make create-provider name=my-provider
222
+```
223
276
-3. Add comprehensive tests
224
+For agentic providers:
225
278
-4. Add provider documentation
226
+```bash
227
+cd python
228
+make create-provider name=my-provider agentic=true
229
+```
230
280
-5. Create example implementations
231
+Then add provider tests and run the relevant Python checks.
232
233
## Testing Guidelines
234
284
-1. Write unit tests for all new code
285
-2. Include integration tests for providers
286
-3. Test error cases
287
-4. Test edge cases
288
-5. Use mocks appropriately
289
-6. Test streaming functionality
290
-7. Test with different Node.js versions
291
-
292
-Example test:
293
-
294
-```typescript
295
-describe('ToolExecution', () => {
296
- it('should execute a tool successfully', async () => {
297
- const result = await executeTool('TEST_TOOL', {
298
- userId: 'user123',
299
- arguments: { test: true },
300
- });
301
- expect(result.successful).toBe(true);
302
- });
303
-
304
- it('should handle errors appropriately', async () => {
305
- await expect(
306
- executeTool('INVALID_TOOL', {
307
- userId: 'user123',
308
- arguments: {},
309
- })
310
- ).rejects.toThrow(ToolNotFoundError);
311
- });
312
-});
235
+### TypeScript SDK
236
+
237
+Run the root TypeScript test suite:
238
+
239
+```bash
240
+pnpm test
241
```
242
315
-## Release Process
243
+Run all TypeScript end-to-end tests:
244
317
-1. Create a release branch:
245
+```bash
246
+pnpm test:e2e
247
+```
248
319
- ```bash
320
- git checkout -b release/v1.2.3
321
- ```
249
+Run runtime-specific end-to-end tests:
250
323
-2. Update version numbers:
251
+```bash
252
+pnpm test:e2e:node
253
+pnpm test:e2e:deno
254
+pnpm test:e2e:cli
255
+pnpm test:e2e:cloudflare
256
+```
257
325
- ```bash
326
- pnpm changeset version
327
- ```
258
+Open the Vitest UI:
259
329
-3. Update CHANGELOG.md
260
+```bash
261
+pnpm test:ui
262
+```
263
331
-4. Create a release commit:
264
+### Python SDK
265
333
- ```bash
334
- git commit -am "Release v1.2.3"
335
- ```
266
+Set up the Python development environment:
267
337
-5. Create a pull request for the release
268
+```bash
269
+cd python
270
+make env
271
+source .venv/bin/activate
272
+```
273
339
-6. After approval, merge and tag:
274
+Run Python checks:
275
341
- ```bash
342
- git tag v1.2.3
343
- git push origin v1.2.3
344
- ```
276
+```bash
277
+make fmt
278
+make chk
279
+make tst
280
+make snt
281
+```
282
346
-7. Publish to npm:
347
- ```bash
348
- pnpm changeset publish
349
- ```
283
+You can also run a focused pytest command through uv:
284
+
285
+```bash
286
+uv run pytest tests/test_sdk.py -v
287
+```
288
+
289
+### Docs Site
290
+
291
+For docs changes:
292
+
293
+```bash
294
+cd docs
295
+bun install
296
+bun run build
297
+bun run lint:links
298
+```
299
+
300
+See [`docs/CLAUDE.md`](docs/CLAUDE.md) for the full docs workflow.
301
+
302
+## Release Process
303
+
304
+Only maintainers publish releases.
305
+
306
+For TypeScript package and CLI release details, use [`ts/docs/internal/release.md`](ts/docs/internal/release.md). The root scripts are:
307
+
308
+```bash
309
+pnpm changeset
310
+pnpm changeset:version
311
+pnpm changeset:release
312
+```
313
+
314
+For Python package release details, use [`python/docs/release.md`](python/docs/release.md). Python package versioning and release preparation are handled from the `python/` workspace.
315
316
## Questions and Support
317