@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 103 lines 3.34 KB
Rendered Raw
1 # Trigger System Implementation
2
3 This document explains the internal implementation of the trigger system in the Composio SDK.
4
5 ## Architecture Overview
6
7 The trigger system is built on top of Pusher for real-time communication. The implementation consists of two main components:
8
9 1. The Triggers class (`packages/core/src/models/Triggers.ts`)
10 2. The PusherService class (`packages/core/src/services/pusher/Pusher.ts`)
11
12 ## Real-time Communication
13
14 ### Pusher Integration
15
16 The SDK uses Pusher as the underlying real-time communication infrastructure. When a client subscribes to triggers, the following process occurs:
17
18 1. The SDK initializes a PusherService instance
19 2. The service connects to Pusher using client credentials
20 3. A channel subscription is established for the client's triggers
21 4. Incoming messages are processed and filtered based on user-defined criteria
22
23 ### Message Flow
24
25 ```mermaid
26 sequenceDiagram
27 participant Client
28 participant SDK
29 participant Pusher
30 participant ComposioAPI
31
32 Client->>SDK: subscribe(callback, filters)
33 SDK->>ComposioAPI: Authenticate Pusher connection
34 ComposioAPI-->>SDK: Connection credentials
35 SDK->>Pusher: Connect & Subscribe to channel
36 Pusher-->>SDK: Connection established
37 loop Real-time Events
38 Pusher->>SDK: Trigger event
39 SDK->>SDK: Apply filters
40 SDK->>Client: Filtered event callback
41 end
42 ```
43
44 ## API Endpoints
45
46 The SDK interacts with the following Composio API endpoints for trigger management:
47
48 ### Trigger Instance Management
49
50 - `GET /api/v3/trigger_instances/active` - List active triggers
51 - `POST /api/v3/trigger_instances/{slug}` - Create/update trigger instance
52 - Includes `toolkit_versions` parameter to specify the toolkit version for the trigger instance (defaults to global configuration)
53 - `PATCH /api/v3/trigger_instances/manage/{id}` - Update trigger instance
54 - `DELETE /api/v3/trigger_instances/manage/{id}` - Delete trigger instance
55
56 ### Trigger Types
57
58 - `GET /api/v3/triggers/types` - List trigger types
59 - `GET /api/v3/triggers/types/{slug}` - Get trigger type details
60 - `GET /api/v3/triggers/types/enum` - Get trigger type enums
61
62 ### Pusher Authentication
63
64 - `POST /api/v3/internal/sdk/realtime/auth` - Authenticate Pusher connection
65 - `GET /api/v3/internal/sdk/realtime/credentials` - Necessary credentials to create pusher client
66
67 ## Data Processing
68
69 When a trigger event is received through Pusher, the SDK:
70
71 1. Parses the raw event data
72 2. Validates it against the `IncomingTriggerPayloadSchema`
73 3. Applies user-defined filters
74 4. Delivers the processed event to the user's callback
75
76 ### Filter Processing
77
78 The SDK supports filtering triggers based on:
79
80 - Toolkit names
81 - Trigger IDs
82 - Connected Account IDs
83 - Trigger slugs
84 - Trigger data
85 - User IDs
86
87 Filters are applied in a compound manner - all specified filters must match for an event to be delivered.
88
89 ## Error Handling
90
91 The SDK implements robust error handling:
92
93 - Schema validation for all incoming and outgoing data
94 - Connection error recovery
95 - Callback error isolation (errors in user callbacks don't affect the subscription)
96 - Automatic reconnection on connection loss
97
98 ## Security Considerations
99
100 - All Pusher communications are authenticated
101 - API credentials are never exposed to the client
102 - Each client only receives events they are authorized to see
103 - Connection credentials are short-lived and rotated regularly