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 22, 22:00 UTC
refactor: update welcome page, enhance custom tools examples, and add type-safe trigger handling in TypeScript
- Removed outdated tip from the welcome page. - Updated custom tools section with a clearer example of creating a custom tool. - Added type-safe trigger handling examples in TypeScript, including payload definitions and webhook processing logic.
balyan.sid@gmail.com committed
Jul 29, 2025 at 12:37 UTC
4537cfba586d3fa9579971978db790895d170fc7
5 files changed
+186
-82
fern/pages/src/get-started/welcome.mdx
-4
@@ -9,10 +9,6 @@ hide-nav-links: false
9
<Frame>
10
<img src="../../../assets/images/hero.png" alt="Composio introduction image" />
11
</Frame>
12
-<Tip>
13
- Give your AI IDE access to Composio's documentation using our llms.txt files: ([short
14
- .txt](/llms.txt), [long .txt](/llms-full.txt))
15
-</Tip>
12
13
Composio is the fastest way to enable your AI agents to take real-world actions—without dealing with individual API integrations, authentication flows, or complex tool formatting.
14
fern/pages/src/tool-calling/custom-tools.mdx
+51
-52
@@ -18,24 +18,6 @@ Custom tools allow you to create your own tools that can be used with Composio.
18
A standalone tool is the simplest form of custom tool. It only requires input parameters and an execute function:
19
20
<CodeGroup>
21
-```typescript TypeScript maxLines=60 wordWrap
22
-const tool = await composio.tools.createCustomTool({
23
- slug: 'CALCULATE_SQUARE',
24
- name: 'Calculate Square',
25
- description: 'Calculates the square of a number',
26
- inputParams: z.object({
27
- number: z.number().describe('The number to calculate the square of'),
28
- }),
29
- execute: async input => {
30
- const { number } = input;
31
- return {
32
- data: { result: number * number },
33
- error: null,
34
- successful: true,
35
- };
36
- },
37
-});
38
-```
21
```python Python maxLines=60 wordWrap
22
from pydantic import BaseModel, Field
23
@@ -61,6 +43,24 @@ def add_two_numbers(request: AddTwoNumbersInput) -> int:
43
"""Add two numbers."""
44
return request.a + request.b
45
```
46
+```typescript TypeScript maxLines=60 wordWrap
47
+const tool = await composio.tools.createCustomTool({
48
+ slug: 'CALCULATE_SQUARE',
49
+ name: 'Calculate Square',
50
+ description: 'Calculates the square of a number',
51
+ inputParams: z.object({
52
+ number: z.number().describe('The number to calculate the square of'),
53
+ }),
54
+ execute: async input => {
55
+ const { number } = input;
56
+ return {
57
+ data: { result: number * number },
58
+ error: null,
59
+ successful: true,
60
+ };
61
+ },
62
+});
63
+```
64
</CodeGroup>
65
66
### Toolkit-based Tool
@@ -70,6 +70,39 @@ A toolkit-based tool has access to two ways of making authenticated requests:
70
1. Using `executeToolRequest` - The recommended way to make authenticated requests to the toolkit's API endpoints. Composio automatically handles credential injection and baseURL resolution:
71
72
<CodeGroup>
73
+```python Python maxLines=60 wordWrap
74
+class GetIssueInfoInput(BaseModel):
75
+ issue_number: int = Field(
76
+ ...,
77
+ description="The number of the issue to get information about",
78
+ )
79
+
80
+# function name will be used as slug
81
+@composio.tools.custom_tool(toolkit="github")
82
+def get_issue_info(
83
+ request: GetIssueInfoInput,
84
+ execute_request: ExecuteRequestFn,
85
+ auth_credentials: dict,
86
+) -> dict:
87
+ """Get information about a GitHub issue."""
88
+ response = execute_request(
89
+ endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
90
+ method="GET",
91
+ parameters=[
92
+ {
93
+ "name": "Accept",
94
+ "value": "application/vnd.github.v3+json",
95
+ "type": "header",
96
+ },
97
+ {
98
+ "name": "Authorization",
99
+ "value": f"Bearer {auth_credentials['access_token']}",
100
+ "type": "header",
101
+ },
102
+ ],
103
+ )
104
+ return {"data": response.data}
105
+```
106
```typescript TypeScript maxLines=60 wordWrap
107
const tool = await composio.tools.createCustomTool({
108
slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
@@ -110,40 +143,6 @@ const tool = await composio.tools.createCustomTool({
143
});
144
```
145
113
-```python Python maxLines=60 wordWrap
114
-class GetIssueInfoInput(BaseModel):
115
- issue_number: int = Field(
116
- ...,
117
- description="The number of the issue to get information about",
118
- )
119
-
120
-# function name will be used as slug
121
-@composio.tools.custom_tool(toolkit="github")
122
-def get_issue_info(
123
- request: GetIssueInfoInput,
124
- execute_request: ExecuteRequestFn,
125
- auth_credentials: dict,
126
-) -> dict:
127
- """Get information about a GitHub issue."""
128
- response = execute_request(
129
- endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
130
- method="GET",
131
- parameters=[
132
- {
133
- "name": "Accept",
134
- "value": "application/vnd.github.v3+json",
135
- "type": "header",
136
- },
137
- {
138
- "name": "Authorization",
139
- "value": f"Bearer {auth_credentials['access_token']}",
140
- "type": "header",
141
- },
142
- ],
143
- )
144
- return {"data": response.data}
145
-```
146
-
146
</CodeGroup>
147
148
2. Using `connectionConfig` - For making direct API calls when needed:
fern/pages/src/triggers/using-triggers.mdx
+26
@@ -148,6 +148,32 @@ console.log(triggerType.payload);
148
149
</CodeGroup>
150
151
+### Type-safe trigger handling (TypeScript)
152
+
153
+For better type safety and developer experience in TypeScript, you can define specific payload types and use the `TriggerEvent<T>` interface:
154
+
155
+<CodeGroup>
156
+<SnippetCode
157
+ src="fern/snippets/triggers/typescript/trigger-types.ts"
158
+ title="Type-safe trigger subscription"
159
+ startLine={3}
160
+ endLine={26}
161
+/>
162
+
163
+<SnippetCode
164
+ src="fern/snippets/triggers/typescript/trigger-webhook.ts"
165
+ title="Type-safe webhook handling"
166
+ startLine={3}
167
+ endLine={18}
168
+/>
169
+</CodeGroup>
170
+
171
+This approach provides:
172
+- **IntelliSense support** for trigger payload fields
173
+- **Compile-time error checking** for typos and invalid field access
174
+- **Better documentation** through TypeScript types
175
+- **Improved maintainability** of trigger handling code
176
+
177
178
## Prototyping triggers during development
179
During development, you may not have a proper webhook setup -- so you can subscribe to triggers directly through the SDK.
fern/snippets/triggers/typescript/trigger-types.ts
new
+58
@@ -0,0 +1,58 @@
1
+import { Composio, TriggerEvent } from '@composio/core';
2
+
3
+// Define type-safe payload for GitHub Star Added event
4
+export type GitHubStarAddedEventPayload = {
5
+ action: "created";
6
+ repository_id: number;
7
+ repository_name: string;
8
+ repository_url: string;
9
+ starred_at: string;
10
+ starred_by: string;
11
+};
12
+
13
+const composio = new Composio();
14
+const userId = 'user@acme.com';
15
+
16
+// Create the trigger
17
+const createResponse = await composio.triggers.create(userId, 'GITHUB_STAR_ADDED_EVENT', {
18
+ triggerConfig: {
19
+ owner: 'composiohq',
20
+ repo: 'composio',
21
+ },
22
+});
23
+
24
+// Fetch trigger type details
25
+const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");
26
+console.log(triggerType.config);
27
+
28
+// Type-safe trigger event handler
29
+function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
30
+ console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
31
+}
32
+
33
+// Subscribe to triggers with type-safe handling
34
+await composio.triggers.subscribe(
35
+ (triggerData) => {
36
+ if (triggerData.triggerSlug === 'GITHUB_STAR_ADDED_EVENT') {
37
+ const starEvent: TriggerEvent<GitHubStarAddedEventPayload> = {
38
+ type: triggerData.triggerSlug,
39
+ timestamp: new Date().toISOString(),
40
+ data: {
41
+ ...triggerData.payload as GitHubStarAddedEventPayload,
42
+ connection_nano_id: triggerData.metadata.connectedAccount.id,
43
+ trigger_nano_id: triggerData.id,
44
+ user_id: triggerData.userId,
45
+ }
46
+ };
47
+ handleGitHubStarEvent(starEvent);
48
+ }
49
+ },
50
+ {
51
+ authConfigId: 'ac_1234567890',
52
+ triggerSlug: ['GITHUB_STAR_ADDED_EVENT'],
53
+ }
54
+);
55
+
56
+await composio.triggers.enable('ti_9q19nLNykmVZ');
57
+await composio.triggers.disable('ti_9q19nLNykmVZ');
58
+
fern/snippets/triggers/typescript/trigger-webhook.ts
+51
-26
@@ -1,32 +1,57 @@
1
import type { NextApiRequest, NextApiResponse } from 'next';
2
+import { TriggerEvent } from '@composio/core';
3
+
4
+// Define type-safe payload for GitHub Star Added event
5
+export type GitHubStarAddedEventPayload = {
6
+ action: "created";
7
+ repository_id: number;
8
+ repository_name: string;
9
+ repository_url: string;
10
+ starred_at: string;
11
+ starred_by: string;
12
+};
13
+
14
+// Type-safe handler function
15
+function handleGitHubStarAddedEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
16
+ console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
17
+}
18
19
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
4
- // Only allow POST requests
5
- if (req.method !== 'POST') {
6
- return res.status(405).json({
7
- status: 'error',
8
- message: 'Method not allowed. Only POST requests are accepted.'
9
- });
10
- }
20
+ if (req.method !== 'POST') {
21
+ return res.status(405).json({
22
+ status: 'error',
23
+ message: 'Method not allowed. Only POST requests are accepted.'
24
+ });
25
+ }
26
12
- try {
13
- const payload = req.body;
14
-
15
- console.log('Received webhook payload:');
16
- console.log(JSON.stringify(payload, null, 2));
17
-
18
- // Process your webhook payload here
19
- // Add your webhook handling logic
20
-
21
- res.status(200).json({
22
- status: 'success',
23
- message: 'Webhook received and processed successfully'
24
- });
25
- } catch (error) {
26
- console.error('Error processing webhook:', error);
27
- res.status(500).json({
28
- status: 'error',
29
- message: 'Internal server error while processing webhook'
30
- });
27
+ try {
28
+ const payload = req.body;
29
+
30
+ // Type-safe webhook payload processing
31
+ if (payload.triggerSlug === 'GITHUB_STAR_ADDED_EVENT') {
32
+ const starEvent: TriggerEvent<GitHubStarAddedEventPayload> = {
33
+ type: payload.triggerSlug,
34
+ timestamp: new Date().toISOString(),
35
+ data: {
36
+ ...payload.payload as GitHubStarAddedEventPayload,
37
+ connection_nano_id: payload.metadata?.connectedAccount?.id || '',
38
+ trigger_nano_id: payload.id || '',
39
+ user_id: payload.userId || '',
40
+ }
41
+ };
42
+
43
+ handleGitHubStarAddedEvent(starEvent);
44
}
45
+
46
+ res.status(200).json({
47
+ status: 'success',
48
+ message: 'Webhook received and processed successfully'
49
+ });
50
+ } catch (error) {
51
+ console.error('Error processing webhook:', error);
52
+ res.status(500).json({
53
+ status: 'error',
54
+ message: 'Internal server error while processing webhook'
55
+ });
56
+ }
57
}