composio_sdk/lib.rs
1//! # Composio Rust SDK
2//!
3//! A minimal, type-safe Rust SDK for the Composio Tool Router REST API.
4//!
5//! This SDK enables ZeroClaw and other Rust applications to interact with external services
6//! through Composio's Tool Router API, providing session management, tool execution,
7//! and authentication handling with a minimal memory footprint (~2 MB).
8//!
9//! ## Features
10//!
11//! - **Session Management**: Create and manage Tool Router sessions for users
12//! - **Tool Execution**: Execute tools and meta tools with automatic retry logic
13//! - **Type Safety**: Comprehensive type definitions for all API requests and responses
14//! - **Error Handling**: Detailed error types with actionable error messages
15//! - **Async/Await**: Built on tokio for efficient async operations
16//! - **Memory Efficient**: Minimal memory footprint suitable for resource-constrained environments
17//!
18//! ## Quick Start
19//!
20//! ```no_run
21//! use composio_sdk::{ComposioClient, MetaToolSlug};
22//! use serde_json::json;
23//!
24//! #[tokio::main]
25//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
26//! // Initialize client with API key
27//! let client = ComposioClient::builder()
28//! .api_key(std::env::var("COMPOSIO_API_KEY")?)
29//! .build()?;
30//!
31//! // Create a session for a user
32//! let session = client
33//! .create_session("user_123")
34//! .toolkits(vec!["github", "gmail"])
35//! .manage_connections(true)
36//! .send()
37//! .await?;
38//!
39//! println!("Session ID: {}", session.session_id());
40//! println!("MCP URL: {}", session.mcp_url());
41//!
42//! // Execute a tool
43//! let result = session
44//! .execute_tool(
45//! "GITHUB_CREATE_ISSUE",
46//! json!({
47//! "owner": "composio",
48//! "repo": "composio",
49//! "title": "Test issue",
50//! "body": "Created via Rust SDK"
51//! })
52//! )
53//! .await?;
54//!
55//! println!("Result: {:?}", result.data);
56//!
57//! // Execute a meta tool
58//! let search_result = session
59//! .execute_meta_tool(
60//! MetaToolSlug::ComposioSearchTools,
61//! json!({
62//! "query": "create a GitHub issue"
63//! })
64//! )
65//! .await?;
66//!
67//! println!("Search result: {:?}", search_result.data);
68//!
69//! Ok(())
70//! }
71//! ```
72//!
73//! ## Session Configuration
74//!
75//! Sessions can be configured with various options:
76//!
77//! ```no_run
78//! # use composio_sdk::ComposioClient;
79//! # async fn example(client: ComposioClient) -> Result<(), Box<dyn std::error::Error>> {
80//! let session = client
81//! .create_session("user_123")
82//! .toolkits(vec!["github", "gmail"]) // Enable specific toolkits
83//! .disable_toolkits(vec!["exa", "firecrawl"]) // Or disable specific toolkits
84//! .auth_config("github", "ac_custom_config") // Use custom auth config
85//! .connected_account("gmail", "ca_work_email") // Select specific account
86//! .manage_connections(true) // Enable in-chat auth
87//! .send()
88//! .await?;
89//! # Ok(())
90//! # }
91//! ```
92//!
93//! ## Error Handling
94//!
95//! The SDK provides comprehensive error handling:
96//!
97//! ```no_run
98//! # use composio_sdk::{ComposioClient, ComposioError};
99//! # use serde_json::json;
100//! # async fn example(client: ComposioClient) -> Result<(), Box<dyn std::error::Error>> {
101//! # let session = client.create_session("user_123").send().await?;
102//! match session.execute_tool("INVALID_TOOL", json!({})).await {
103//! Ok(result) => println!("Success: {:?}", result),
104//! Err(ComposioError::ApiError { status, message, suggested_fix, .. }) => {
105//! eprintln!("API error ({}): {}", status, message);
106//! if let Some(fix) = suggested_fix {
107//! eprintln!("Suggested fix: {}", fix);
108//! }
109//! }
110//! Err(ComposioError::NetworkError(e)) => {
111//! eprintln!("Network error: {}", e);
112//! }
113//! Err(e) => {
114//! eprintln!("Other error: {}", e);
115//! }
116//! }
117//! # Ok(())
118//! # }
119//! ```
120//!
121//! ## Configuration
122//!
123//! Customize SDK behavior with [`ComposioConfig`]:
124//!
125//! ```no_run
126//! use composio_sdk::ComposioClient;
127//! use std::time::Duration;
128//!
129//! let client = ComposioClient::builder()
130//! .api_key("your-api-key")
131//! .base_url("https://backend.composio.dev/api/v3")
132//! .timeout(Duration::from_secs(60))
133//! .max_retries(5)
134//! .build()?;
135//! # Ok::<(), composio_sdk::ComposioError>(())
136//! ```
137
138// ============================================================================
139// Module Declarations
140// ============================================================================
141
142pub mod client;
143pub mod config;
144pub mod error;
145pub mod models;
146pub mod retry;
147pub mod session;
148pub mod wizard;
149
150// ============================================================================
151// Core Client and Configuration
152// ============================================================================
153
154/// Main client for interacting with the Composio API
155pub use client::ComposioClient;
156
157/// Builder for constructing a [`ComposioClient`] with custom configuration
158pub use client::ComposioClientBuilder;
159
160/// Configuration for the Composio SDK
161pub use config::ComposioConfig;
162
163// ============================================================================
164// Session Management
165// ============================================================================
166
167/// A Tool Router session for a specific user
168pub use session::Session;
169
170/// Builder for constructing a session with custom configuration
171pub use session::SessionBuilder;
172
173// ============================================================================
174// Error Types
175// ============================================================================
176
177/// Main error type for the SDK
178pub use error::ComposioError;
179
180/// Detailed error information from API error responses
181pub use error::ErrorDetail;
182
183// ============================================================================
184// Request Models
185// ============================================================================
186
187/// Configuration for creating a Tool Router session
188pub use models::SessionConfig;
189
190/// Toolkit filter for enabling or disabling specific toolkits
191pub use models::ToolkitFilter;
192
193/// Configuration for per-toolkit tool filtering
194pub use models::ToolsConfig;
195
196/// Tool filter for a specific toolkit
197pub use models::ToolFilter;
198
199/// Configuration for tag-based tool filtering
200pub use models::TagsConfig;
201
202/// Configuration for workbench execution
203pub use models::WorkbenchConfig;
204
205/// Request to execute a tool
206pub use models::ToolExecutionRequest;
207
208/// Request to execute a meta tool
209pub use models::MetaToolExecutionRequest;
210
211/// Request to create an authentication link
212pub use models::LinkRequest;
213
214// ============================================================================
215// Response Models
216// ============================================================================
217
218/// Response from session creation
219pub use models::SessionResponse;
220
221/// MCP server information
222pub use models::McpInfo;
223
224/// Tool schema information
225pub use models::ToolSchema;
226
227/// Response from tool execution
228pub use models::ToolExecutionResponse;
229
230/// Response from meta tool execution
231pub use models::MetaToolExecutionResponse;
232
233/// Response from listing toolkits
234pub use models::ToolkitListResponse;
235
236/// Information about a toolkit
237pub use models::ToolkitInfo;
238
239/// Metadata about a toolkit
240pub use models::ToolkitMeta;
241
242/// Information about a connected account
243pub use models::ConnectedAccountInfo;
244
245/// Response from creating an auth link
246pub use models::LinkResponse;
247
248/// Error response from API
249pub use models::ErrorResponse;
250
251// ============================================================================
252// Enums
253// ============================================================================
254
255/// Meta tool slugs for the 5 core Composio meta tools
256pub use models::MetaToolSlug;
257
258/// Tag types for filtering tools by behavior hints
259pub use models::TagType;
260
261/// Authentication schemes supported by toolkits
262pub use models::AuthScheme;
263
264// ============================================================================
265// Wizard Module (Skills Integration)
266// ============================================================================
267
268/// Wizard instruction generation utilities
269///
270/// This module provides tools for extracting Composio Skills content and
271/// generating wizard instructions for AI agents based on official best practices.
272///
273/// See the [`wizard`] module documentation for detailed usage examples.
274pub use wizard::{
275 Impact, InstructionValidator, Rule, SkillsExtractor, ValidationResult,
276 WizardInstructionGenerator,
277};