SDK 0.6.0 Major Update: Cloudflare Workers Support and Breaking Changes
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand all provider packages - Version:
0.6.0+
Python
- Package:
composioand all provider packages - Version:
0.11.0+
This major release focuses on Cloudflare Workers compatibility, platform-specific optimizations, and critical bug fixes. It includes breaking changes in both TypeScript and Python SDKs.
Breaking Changes
1. Webhook Verification Breaking Changes
TypeScript PR: #2436 | Python PR: #2361 The webhook verification API has breaking changes in both SDKs to support multiple webhook versions (v1, v2, v3) and edge runtime compatibility.TypeScript: Now Async + Signature Changed
TheverifyWebhook() method has two breaking changes: it’s now async AND requires additional parameters.
Before:
- ⚠️ Now async - Must use
await - ⚠️ New required parameter:
id(fromwebhook-idheader) - ⚠️ New required parameter:
timestamp(fromwebhook-timestampheader) - ⚠️ Header name changed:
x-composio-signature→webhook-signature - ⚠️ Return type changed:
TriggerEvent→VerifyWebhookResult
- Cloudflare Workers compatibility - uses Web Crypto API instead of
node:crypto - Supports v1, v2, and v3 webhook formats with improved signature verification
Python: Signature Changed (v1/v2/v3 Support)
The method signature changed to support new webhook versions and requires additional headers. Before:- ✅ Still synchronous (no
awaitneeded) - ⚠️ New required parameter:
id(webhook-id header) - ⚠️ New required parameter:
timestamp(webhook-timestamp header) - ⚠️ Header name changed:
x-composio-signature→webhook-signature - ⚠️ Return type changed:
TriggerEvent→VerifyWebhookResult - ⚠️ All parameters now keyword-only (must use
param=value)
2. Mastra v1 Provider Update
PR: #2433 The@composio/mastra provider has been updated to support Mastra v1, which has breaking API changes from v0.x.
Before (Mastra v0.x)
After (Mastra v1)
Changes Required
- Update Mastra dependency:
npm install @mastra/core@latest - Update provider initialization: Pass Mastra instance to provider
- Update tool handling: Mastra v1 uses different tool schema format
- Check Zod version: Mastra v1 supports both Zod v3 and v4
- Check Node.js version: Mastra v1 requires Node.js v22.13.0 or higher
We’ve added comprehensive E2E tests for both Zod v3 and v4 compatibility with Mastra v1 and Tool Router integration.
Major Features
3. Platform-Specific File Tool Modifier
PR: #2437 Separate implementations for Node.js and Cloudflare Workers to optimize file handling for each runtime. Key Improvements:- Node.js: Uses native file system APIs for better performance
- Cloudflare Workers: Uses platform-specific APIs, avoids Node.js-only code
- Automatic selection: SDK automatically picks the right implementation
- No code changes needed: Works transparently
Related Change: This platform-agnostic approach is why
composio.triggers.verifyWebhook() became async in Breaking Change #1. Node.js node:crypto is mostly synchronous, but the standard globalThis.crypto (Web Crypto API) available in Cloudflare Workers is async. To support both platforms with a single API, the method had to become async.4. Platform-Specific Config Defaults
PR: #2437 Different default configurations for different runtimes to optimize behavior. Changed theautoUploadDownloadFiles default configuration for the Cloudflare Workers runtime, to avoid triggering runtime errors on unsupported features.
Cloudflare Workers defaults:
- Zero config for common use cases
- Optimized for each platform’s strengths
- Override defaults when needed
5. Node Buffer → Uint8Array Refactoring
PR: #2438 Allnode:buffer usage replaced with standard Uint8Array for universal compatibility.
Impact:
- Works in Node.js and Cloudflare Workers
- ESLint rules enforce this pattern going forward
- Better type safety with standard types
- Fully backward compatible - no code changes needed
Why This Matters: Removing Node.js-specific APIs like
node:buffer and node:crypto enables Cloudflare Workers support. Cloudflare Workers don’t have access to Node.js built-in modules, so we use Web Standard APIs (Uint8Array, globalThis.crypto) that work in both Node.js and Cloudflare Workers.Bug Fixes
6. Tool Fetching with Specific Version
PR: #2518 Fixed issues when executing tools with version constraints.Before (Bug)
After (Fixed)
7. Python JSON Schema Default Values
PR: #2506 Fixed type coercion for stringified default values in JSON schemas.Before (Bug)
After (Fixed)
8. Salesforce Type Error Fix
PR: #2426 FixedSALESFORCE_CREATE_LEAD type error with custom_fields parameter.
Before (Bug)
After (Fixed)
anyOf and allOf JSON Schema constructs in Python SDK.
Migration Guide
Step 1: Update Dependencies
- npm
- pnpm
- yarn
- pip
- uv
Step 2: Update Webhook Verification (Required)
- TypeScript
- Python
Update signature with new parameters and add Express.js Example:Cloudflare Workers Example:
await:Step 3: Update Mastra Integration (If Using)
Only required if you use@composio/mastra provider
- npm
- pnpm
- yarn
Zod Compatibility: Mastra v1 works with both Zod v3 and v4. We test both versions in CI to ensure compatibility.
Step 4: Test Your Integration
- Run your test suite to catch any issues
- Test webhook verification if you use triggers
- Test file uploads/downloads - behavior improved but API unchanged
- Test in your target runtime (Node.js, Cloudflare Workers, etc.)
Backward Compatibility
Fully Compatible (No Changes Needed)
The following features work without any code changes:- ✅ All tool execution APIs
- ✅ Connected accounts management
- ✅ Authentication flows
- ✅ Custom tools
- ✅ Tool Router sessions
- ✅ File upload/download (API unchanged, implementation improved)
- ✅ All provider packages (except Mastra)
- ✅ Python SDK usage (except webhook verification)
Requires Changes
The following features require code updates:- ⚠️ Webhook verification (TypeScript) - Must add
awaitAND addid+timestampparameters, update header names - ⚠️ Webhook verification (Python) - Must add
id+timestampparameters, update header names (still synchronous) - ⚠️ Mastra integration (TypeScript only) - Must update to v1 API
Impact Summary
Cloudflare Workers Support
This release adds support for Cloudflare Workers:- ✅ Tool execution
- ✅ Connected accounts
- ✅ Webhook verification
- ✅ File upload/download
- ✅ Custom tools
Testing
This release includes extensive E2E testing:- ✅ Node.js: Both CJS and ESM compatibility tests
- ✅ Cloudflare Workers: Multiple test suites including Tool Router
- ✅ Mastra v1: Tests for both Zod v3 and v4
- ✅ File handling: Comprehensive tests for all platforms
- ✅ Webhook verification: Tests for all supported runtimes
Getting Help
If you encounter issues during migration:- Check the docs: docs.composio.dev
- Join our Discord: discord.composio.dev
- Open an issue: github.com/ComposioHQ/composio/issues
- Email support: support@composio.dev
What’s Next
Future releases will focus on:- 🚀 Performance optimizations
- 🔧 More platform-specific improvements
- 📚 Enhanced TypeScript types
- 🛠️ New tool integrations
- 🔐 Advanced authentication flows