Skip to content

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

refactor: update welcome page, enhance custom tools examples, and add type-safe trigger handling in TypeScript

[email protected]4537cfba586d
diff --git a/fern/pages/src/get-started/welcome.mdx b/fern/pages/src/get-started/welcome.mdx
index ace9061be..c4d2e9843 100644
--- a/fern/pages/src/get-started/welcome.mdx
+++ b/fern/pages/src/get-started/welcome.mdx
@@ -9,10 +9,6 @@ hide-nav-links: false
<Frame>
<img src="../../../assets/images/hero.png" alt="Composio introduction image" />
</Frame>
-<Tip>
- Give your AI IDE access to Composio's documentation using our llms.txt files: ([short
- .txt](/llms.txt), [long .txt](/llms-full.txt))
-</Tip>
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.
diff --git a/fern/pages/src/tool-calling/custom-tools.mdx b/fern/pages/src/tool-calling/custom-tools.mdx
index 1a2036ffe..8b16a4eb2 100644
--- a/fern/pages/src/tool-calling/custom-tools.mdx
+++ b/fern/pages/src/tool-calling/custom-tools.mdx
@@ -18,24 +18,6 @@ Custom tools allow you to create your own tools that can be used with Composio.
A standalone tool is the simplest form of custom tool. It only requires input parameters and an execute function:
<CodeGroup>
-```typescript TypeScript maxLines=60 wordWrap
-const tool = await composio.tools.createCustomTool({
- slug: 'CALCULATE_SQUARE',
- name: 'Calculate Square',
- description: 'Calculates the square of a number',
- inputParams: z.object({
- number: z.number().describe('The number to calculate the square of'),
- }),
- execute: async input => {
- const { number } = input;
- return {
- data: { result: number * number },
- error: null,
- successful: true,
- };
- },
-});
-```
```python Python maxLines=60 wordWrap
from pydantic import BaseModel, Field
@@ -61,6 +43,24 @@ def add_two_numbers(request: AddTwoNumbersInput) -> int:
"""Add two numbers."""
return request.a + request.b
```
+```typescript TypeScript maxLines=60 wordWrap
+const tool = await composio.tools.createCustomTool({
+ slug: 'CALCULATE_SQUARE',
+ name: 'Calculate Square',
+ description: 'Calculates the square of a number',
+ inputParams: z.object({
+ number: z.number().describe('The number to calculate the square of'),
+ }),
+ execute: async input => {
+ const { number } = input;
+ return {
+ data: { result: number * number },
+ error: null,
+ successful: true,
+ };
+ },
+});
+```
</CodeGroup>
### Toolkit-based Tool
@@ -70,6 +70,39 @@ A toolkit-based tool has access to two ways of making authenticated requests:
1. Using `executeToolRequest` - The recommended way to make authenticated requests to the toolkit's API endpoints. Composio automatically handles credential injection and baseURL resolution:
<CodeGroup>
+```python Python maxLines=60 wordWrap
+class GetIssueInfoInput(BaseModel):
+ issue_number: int = Field(
+ ...,
+ description="The number of the issue to get information about",
+ )
+
+# function name will be used as slug
[email protected]_tool(toolkit="github")
+def get_issue_info(
+ request: GetIssueInfoInput,
+ execute_request: ExecuteRequestFn,
+ auth_credentials: dict,
+) -> dict:
+ """Get information about a GitHub issue."""
+ response = execute_request(
+ endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
+ method="GET",
+ parameters=[
+ {
+ "name": "Accept",
+ "value": "application/vnd.github.v3+json",
+ "type": "header",
+ },
+ {
+ "name": "Authorization",
+ "value": f"Bearer {auth_credentials['access_token']}",
+ "type": "header",
+ },
+ ],
+ )
+ return {"data": response.data}
+```
```typescript TypeScript maxLines=60 wordWrap
const tool = await composio.tools.createCustomTool({
slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
@@ -110,40 +143,6 @@ const tool = await composio.tools.createCustomTool({
});
```
-```python Python maxLines=60 wordWrap
-class GetIssueInfoInput(BaseModel):
- issue_number: int = Field(
- ...,
- description="The number of the issue to get information about",
- )
-
-# function name will be used as slug
[email protected]_tool(toolkit="github")
-def get_issue_info(
- request: GetIssueInfoInput,
- execute_request: ExecuteRequestFn,
- auth_credentials: dict,
-) -> dict:
- """Get information about a GitHub issue."""
- response = execute_request(
- endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
- method="GET",
- parameters=[
- {
- "name": "Accept",
- "value": "application/vnd.github.v3+json",
- "type": "header",
- },
- {
- "name": "Authorization",
- "value": f"Bearer {auth_credentials['access_token']}",
- "type": "header",
- },
- ],
- )
- return {"data": response.data}
-```
-
</CodeGroup>
2. Using `connectionConfig` - For making direct API calls when needed:
diff --git a/fern/pages/src/triggers/using-triggers.mdx b/fern/pages/src/triggers/using-triggers.mdx
index 4cc9cb996..b697ba438 100644
--- a/fern/pages/src/triggers/using-triggers.mdx
+++ b/fern/pages/src/triggers/using-triggers.mdx
@@ -148,6 +148,32 @@ console.log(triggerType.payload);
</CodeGroup>
+### Type-safe trigger handling (TypeScript)
+
+For better type safety and developer experience in TypeScript, you can define specific payload types and use the `TriggerEvent<T>` interface:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/triggers/typescript/trigger-types.ts"
+ title="Type-safe trigger subscription"
+ startLine={3}
+ endLine={26}
+/>
+
+<SnippetCode
+ src="fern/snippets/triggers/typescript/trigger-webhook.ts"
+ title="Type-safe webhook handling"
+ startLine={3}
+ endLine={18}
+/>
+</CodeGroup>
+
+This approach provides:
+- **IntelliSense support** for trigger payload fields
+- **Compile-time error checking** for typos and invalid field access
+- **Better documentation** through TypeScript types
+- **Improved maintainability** of trigger handling code
+
## Prototyping triggers during development
During development, you may not have a proper webhook setup -- so you can subscribe to triggers directly through the SDK.
diff --git a/fern/snippets/triggers/typescript/trigger-types.ts b/fern/snippets/triggers/typescript/trigger-types.ts
new file mode 100644
index 000000000..cf1a2e8ed
--- /dev/null
+++ b/fern/snippets/triggers/typescript/trigger-types.ts
@@ -0,0 +1,58 @@
+import { Composio, TriggerEvent } from '@composio/core';
+
+// Define type-safe payload for GitHub Star Added event
+export type GitHubStarAddedEventPayload = {
+ action: "created";
+ repository_id: number;
+ repository_name: string;
+ repository_url: string;
+ starred_at: string;
+ starred_by: string;
+};
+
+const composio = new Composio();
+const userId = '[email protected]';
+
+// Create the trigger
+const createResponse = await composio.triggers.create(userId, 'GITHUB_STAR_ADDED_EVENT', {
+ triggerConfig: {
+ owner: 'composiohq',
+ repo: 'composio',
+ },
+});
+
+// Fetch trigger type details
+const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");
+console.log(triggerType.config);
+
+// Type-safe trigger event handler
+function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
+ console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
+}
+
+// Subscribe to triggers with type-safe handling
+await composio.triggers.subscribe(
+ (triggerData) => {
+ if (triggerData.triggerSlug === 'GITHUB_STAR_ADDED_EVENT') {
+ const starEvent: TriggerEvent<GitHubStarAddedEventPayload> = {
+ type: triggerData.triggerSlug,
+ timestamp: new Date().toISOString(),
+ data: {
+ ...triggerData.payload as GitHubStarAddedEventPayload,
+ connection_nano_id: triggerData.metadata.connectedAccount.id,
+ trigger_nano_id: triggerData.id,
+ user_id: triggerData.userId,
+ }
+ };
+ handleGitHubStarEvent(starEvent);
+ }
+ },
+ {
+ authConfigId: 'ac_1234567890',
+ triggerSlug: ['GITHUB_STAR_ADDED_EVENT'],
+ }
+);
+
+await composio.triggers.enable('ti_9q19nLNykmVZ');
+await composio.triggers.disable('ti_9q19nLNykmVZ');
+
diff --git a/fern/snippets/triggers/typescript/trigger-webhook.ts b/fern/snippets/triggers/typescript/trigger-webhook.ts
index 7d509fbfb..2be02d230 100644
--- a/fern/snippets/triggers/typescript/trigger-webhook.ts
+++ b/fern/snippets/triggers/typescript/trigger-webhook.ts
@@ -1,32 +1,57 @@
import type { NextApiRequest, NextApiResponse } from 'next';
+import { TriggerEvent } from '@composio/core';
+
+// Define type-safe payload for GitHub Star Added event
+export type GitHubStarAddedEventPayload = {
+ action: "created";
+ repository_id: number;
+ repository_name: string;
+ repository_url: string;
+ starred_at: string;
+ starred_by: string;
+};
+
+// Type-safe handler function
+function handleGitHubStarAddedEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
+ console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
+}
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
- // Only allow POST requests
- if (req.method !== 'POST') {
- return res.status(405).json({
- status: 'error',
- message: 'Method not allowed. Only POST requests are accepted.'
- });
- }
+ if (req.method !== 'POST') {
+ return res.status(405).json({
+ status: 'error',
+ message: 'Method not allowed. Only POST requests are accepted.'
+ });
+ }
- try {
- const payload = req.body;
-
- console.log('Received webhook payload:');
- console.log(JSON.stringify(payload, null, 2));
-
- // Process your webhook payload here
- // Add your webhook handling logic
-
- res.status(200).json({
- status: 'success',
- message: 'Webhook received and processed successfully'
- });
- } catch (error) {
- console.error('Error processing webhook:', error);
- res.status(500).json({
- status: 'error',
- message: 'Internal server error while processing webhook'
- });
+ try {
+ const payload = req.body;
+
+ // Type-safe webhook payload processing
+ if (payload.triggerSlug === 'GITHUB_STAR_ADDED_EVENT') {
+ const starEvent: TriggerEvent<GitHubStarAddedEventPayload> = {
+ type: payload.triggerSlug,
+ timestamp: new Date().toISOString(),
+ data: {
+ ...payload.payload as GitHubStarAddedEventPayload,
+ connection_nano_id: payload.metadata?.connectedAccount?.id || '',
+ trigger_nano_id: payload.id || '',
+ user_id: payload.userId || '',
+ }
+ };
+
+ handleGitHubStarAddedEvent(starEvent);
}
+
+ res.status(200).json({
+ status: 'success',
+ message: 'Webhook received and processed successfully'
+ });
+ } catch (error) {
+ console.error('Error processing webhook:', error);
+ res.status(500).json({
+ status: 'error',
+ message: 'Internal server error while processing webhook'
+ });
+ }
}