Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add example usage of user_id in the docs
haxziecb46a71b1e54
diff --git a/README.md b/README.mdindex 579b60193..ab586d4c4 100644--- a/README.md+++ b/README.md@@ -248,6 +248,9 @@ composio/# Create a new providerpnpm create:provider <provider-name> [--agentic]+ # Create a new example+ pnpm create:example <example-name>+# Check peer dependenciespnpm check:peer-deps@@ -255,6 +258,29 @@ composio/pnpm update:peer-deps```+## Creating a New Example++1. Use the create:example script:++ ```bash+ 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 Provider1. Use the create:provider script:diff --git a/docs/core-concepts.md b/docs/core-concepts.mdindex fa3147ee7..32ae19206 100644--- a/docs/core-concepts.md+++ b/docs/core-concepts.md@@ -2,6 +2,128 @@Composio SDK is built around a set of key concepts that work together to provide a seamless integration experience for third-party services and tools.+## User IDs++User IDs are the **core foundation** of accessing and executing tools in Composio. Every tool execution, connection authorization, and account management operation requires a `userId` parameter that identifies which user's context the operation should be performed in.++### ⚠️ Critical Security Considerations++User IDs are crucial for security and data isolation. You must be extremely careful when handling user IDs to ensure:++- Users can only access their own connected accounts+- Tool executions are performed in the correct user context+- No unauthorized access to other users' data++### The `default` User ID++The `default` userId refers to the default account of your Composio project and should **only be used for**:++- **Testing and development** environments+- **Single-user applications** where external users don't connect their own accounts+- **Internal tools** where all operations are performed by your system++```typescript+// ❌ Don't use 'default' in production for multi-user apps+const tools = await composio.tools.get('default', {+ toolkits: ['github'],+});++// ❌ This could expose other users' data+const result = await composio.tools.execute('GITHUB_GET_REPO', {+ userId: 'default',+ arguments: { owner: 'example', repo: 'repo' },+});+```++### Production User IDs++In production applications with multiple users, always use unique identifiers for each user. The best practices are:++#### ✅ **Recommended: Database UUID**++```typescript+// Use your database's user ID (UUID, primary key, etc.)+const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"++const tools = await composio.tools.get(userId, {+ toolkits: ['github'],+});++const result = await composio.tools.execute('GITHUB_GET_REPO', {+ userId: userId,+ arguments: { owner: 'example', repo: 'repo' },+});+```++#### ✅ **Acceptable: Unique Username/Identifier**++```typescript+// Use a unique, stable identifier from your system+const userId = user.username; // e.g., "john_doe_123"+// or+const userId = user.externalId; // e.g., "auth0|507f1f77bcf86cd799439011"+```++#### ⚠️ **Not Recommended: Email Address**++```typescript+// While functional, emails can change and may cause issues+const userId = user.email; // e.g., "[email protected]"+```++### Example: Multi-User Application Flow++```typescript+import { Composio } from '@composio/core';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+});++// 1. User initiates GitHub connection+async function connectUserToGitHub(userId: string) {+ const connectionRequest = await composio.toolkits.authorize(userId, 'github');+ return connectionRequest.redirectUrl;+}++// 2. Get user's connected GitHub tools+async function getUserGitHubTools(userId: string) {+ return await composio.tools.get(userId, {+ toolkits: ['github'],+ });+}++// 3. Execute tool for specific user+async function getUserRepos(userId: string) {+ return await composio.tools.execute('GITHUB_LIST_REPOS', {+ userId: userId,+ arguments: {+ per_page: 10,+ },+ });+}++// Usage in your API endpoint+app.get('/api/github/repos', async (req, res) => {+ const userId = req.user.id; // Get from your auth system++ try {+ const repos = await getUserRepos(userId);+ res.json(repos.data);+ } catch (error) {+ res.status(500).json({ error: 'Failed to fetch repos' });+ }+});+```++### Best Practices++1. **Always validate user IDs** before passing them to Composio methods+2. **Use your authentication system** to ensure users can only access their own data+3. **Keep user IDs consistent** across your application and Composio+4. **Never expose user IDs** in client-side code or logs+5. **Use meaningful, stable identifiers** that won't change over time+## ToolsTools are the fundamental units of functionality in Composio. Each tool represents a specific action that can be performed, such as "Get GitHub Repository" or "Send Email". Tools have:@@ -94,19 +216,19 @@ const customTool = await composio.tools.createCustomTool({param1: {type: 'string',description: 'First parameter',- required: true- }+ required: true,+ },},outputParameters: {result: {type: 'string',- description: 'The result of the operation'- }+ description: 'The result of the operation',+ },},handler: async (params, context) => {// Custom logic herereturn { data: { result: 'Success!' } };- }+ },});```@@ -119,4 +241,4 @@ Triggers allow your application to respond to events from external services. Theconst triggers = await composio.triggers.get({toolkits: ['github'],});-```\ No newline at end of file+```diff --git a/examples/triggers/src/index.ts b/examples/triggers/src/index.tsindex b5fb7b96f..3fb5e031d 100644--- a/examples/triggers/src/index.ts+++ b/examples/triggers/src/index.ts@@ -29,7 +29,7 @@ async function main() {// Get available toolsconst tools = await composio.tools.get('default', {// Specify the apps you want to use- // apps: ['gmail', 'googlecalendar'],+ toolkits: ['gmail', 'googlecalendar'],limit: 10,});