@devries-cameron20 / composio Mirror · read-only / commits / 4537cfba5
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 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 }