@oneie/claude 0.4.0 → 0.6.0

package/skills/composio/rules/app-auth-popup-ui.md

@@ -0,0 +1,144 @@
+---
+title: Building Popup Connection UI
+impact: MEDIUM
+description: Build a popup-based Composio auth-link UI with dedicated callback page handling and parent-window polling
+tags: [connected-accounts, auth-link, popup, callback-page, ui]
+---
+
+# Building Popup Connection UI
+
+Use this pattern when you want to open Composio auth links in a popup window and handle completion in the parent window.
+
+> This is a **general Composio auth link handler**, not an OAuth-only pattern. It works for any Composio hosted auth link that redirects back with URL params.
+
+## Flow Overview
+
+1. Parent app requests a Composio auth link (`redirectUrl`)
+2. Parent opens popup with that `redirectUrl`
+3. Popup completes auth and lands on a dedicated callback page in your app
+4. Parent polls popup URL, detects success/error params, closes popup, resolves state
+
+## Why Use a Dedicated Callback Page
+
+Always route popup completion to a dedicated page like `/auth/composio/callback` to:
+- show clear success/failure states
+- provide a stable URL shape for parameter parsing
+- prevent exposing auth-link query params in unrelated pages
+- keep popup close/cleanup logic predictable
+
+## Parent Window Handler
+
+Use a helper that opens the popup, polls URL params, and closes automatically when done:
+
+```typescript
+export const initiateComposioAuthFlow = (
+  url: string,
+  successParam: string = 'status'
+): Promise<Record<string, string>> => {
+  const width = 600;
+  const height = 840;
+  const leftPosition = (window.innerWidth - width) / 2;
+  const topPosition = (window.innerHeight - height) / 2;
+
+  return new Promise((resolve, reject) => {
+    const popup = window.open(
+      url,
+      'composio-auth-popup',
+      `width=${width},height=${height},left=${leftPosition},top=${topPosition}`
+    );
+
+    if (!popup) {
+      reject(new Error('Popup blocked by browser'));
+      return;
+    }
+
+    popup.focus();
+
+    const popupChecker = setInterval(() => {
+      if (popup.closed) {
+        clearInterval(popupChecker);
+        reject(new Error('Popup closed before completion'));
+        return;
+      }
+
+      let popupUrl: URL | null = null;
+      try {
+        popupUrl = new URL(popup.location.href);
+      } catch {
+        // Cross-origin while Composio page is open; ignore until redirected back to your domain.
+      }
+
+      if (!popupUrl) {
+        return;
+      }
+
+      const successValue = popupUrl.searchParams.get(successParam);
+      const errorValue = popupUrl.searchParams.get('error');
+
+      if (errorValue) {
+        clearInterval(popupChecker);
+        popup.close();
+        reject(new Error(String(errorValue)));
+        return;
+      }
+
+      if (successValue !== null) {
+        const allParams: Record<string, string> = {};
+        popupUrl.searchParams.forEach((value, key) => {
+          allParams[key] = value;
+        });
+
+        clearInterval(popupChecker);
+        popup.close();
+        resolve(allParams);
+      }
+    }, 500);
+  });
+};
+```
+
+## Dedicated Callback Page
+
+Create a small callback page in your app to handle the end state:
+- show "Connection successful" or "Connection failed"
+- optionally show a "You can close this window" fallback
+- keep query params intact so parent polling can read them
+
+Example route path:
+- `https://your-app.com/auth/composio/callback`
+
+## Example Integration with `connectedAccounts.link()` or `session.authorize()`
+
+```typescript
+// in the backend
+const connectionRequest = await composio.connectedAccounts.link(
+  userId,
+  authConfigId,
+  { callbackUrl: 'https://your-app.com/auth/composio/callback' }
+);
+
+// in the frontend
+const params = await initiateComposioAuthFlow(
+  connectionRequest.redirectUrl,
+  'status'
+);
+```
+
+You can also destructure all returned query params directly:
+
+```typescript
+const { status, connected_account_id } = await initiateComposioAuthFlow(
+  authLink,
+  'status'
+);
+```
+
+## Best Practices
+
+- Use popup only on user gesture (`onClick`) to avoid popup blockers
+- Keep polling interval small (`300-700ms`) for responsive close
+- Capture both success and error query params
+- Always clear interval on every exit path
+- Reject immediately if popup cannot be opened
+- Use a stable callback URL path across environments
+

package/skills/composio/rules/app-connected-accounts.md

@@ -0,0 +1,240 @@
+---
+title: Connected Accounts Management
+impact: HIGH
+description: Comprehensive guide to CRUD operations on connected accounts with emphasis on secure authentication flows
+tags: [connected-accounts, authentication, oauth, crud, security]
+---
+
+# Connected Accounts Management
+
+> **Using Sessions/Tool Router?** If you're using Tool Router Sessions, you can use `session.toolkits()` to view the auth configs and connected accounts being used by the Tool Router. You only need to use the methods below if you're managing connected accounts outside of Tool Router.
+> When using sessions, only use authConfigs listed via session.toolkit(), or use session.authorize() for toolkits which does not have authConfigs
+
+Connected accounts store authentication tokens for external services. Use the `connectedAccounts` API for CRUD operations.
+
+## Create Connected Accounts
+
+### Recommended: link() - Composio-Hosted Authentication
+
+Use `link()` for most flows. Composio handles security, OAuth, and form rendering.
+
+```typescript
+const connectionRequest = await composio.connectedAccounts.link(
+  'user_123',
+  'auth_config_123',
+  { callbackUrl: 'https://your-app.com/callback' }
+);
+
+// Redirect user to authentication page
+window.location.href = connectionRequest.redirectUrl;
+
+// IMPORTANT: if building web applications, look for `status=success&connectedAccountId=*******` query params in the callback url. Setup a dedicated route to handle the callback if opening via popus, to show success and failure states.
+
+// Only use the below for simpler single user application/CLIs etc.
+const account = await connectionRequest.waitForConnection();
+```
+
+While building popup-based authentication flows using Composio links, follow [Building Popup Connection UI](./app-auth-popup-ui.md).
+
+
+**Why use link():**
+- Handles OAuth security and form UI
+- Works with 200+ services
+- Whitelabel with your app name/logo (Project Settings on dashboard)
+- No custom UI needed
+
+### Advanced: initiate() - Custom Authentication UI
+
+Only use when building custom auth interfaces:
+
+```typescript
+// API Key (custom form)
+const connection = await composio.connectedAccounts.initiate(
+  'user_123',
+  'auth_config_456',
+  {
+    config: AuthScheme.ApiKey({ api_key: apiKey }),
+  }
+);
+
+// OAuth with extra params (Zendesk, PostHog, etc.)
+const connection = await composio.connectedAccounts.initiate(
+  'user_123',
+  'zendesk_config',
+  {
+    config: AuthScheme.OAuth2({ subdomain: "your_subdomain" })
+  }
+);
+window.location.href = connection.redirectUrl;
+```
+
+**AuthScheme helpers:**
+- `AuthScheme.OAuth2({ subdomain: 'example' })`
+- `AuthScheme.ApiKey({ api_key: 'key123' })`
+- `AuthScheme.Basic({ username: 'user', password: 'pass' })`
+- `AuthScheme.BearerToken({ token: 'token123' })`
+
+**Use initiate() only when:**
+- Building custom authentication UI
+- Handling credentials directly in backend
+- OAuth requires extra parameters before redirect
+
+## Read Connected Accounts
+
+```typescript
+// List all
+const allAccounts = await composio.connectedAccounts.list();
+
+// Filter by user
+const userAccounts = await composio.connectedAccounts.list({
+  userIds: ['user_123'],
+});
+
+// Filter by toolkit
+const githubAccounts = await composio.connectedAccounts.list({
+  toolkitSlugs: ['github'],
+});
+
+// Filter by status
+const activeAccounts = await composio.connectedAccounts.list({
+  statuses: ['ACTIVE']
+});
+
+// Filter by auth config
+const configAccounts = await composio.connectedAccounts.list({
+  authConfigIds: ['auth_config_123']
+});
+
+// Combine filters
+const filtered = await composio.connectedAccounts.list({
+  userIds: ['user_123'],
+  toolkitSlugs: ['github', 'slack'],
+  statuses: ['ACTIVE']
+});
+
+// Get specific account
+const account = await composio.connectedAccounts.get('conn_abc123');
+```
+
+**Available filters:**
+- `userIds` - Filter by user IDs
+- `toolkitSlugs` - Filter by toolkit slugs
+- `statuses` - Filter by connection statuses (see below for values)
+- `authConfigIds` - Filter by auth config IDs
+- `limit` - Results per page
+- `cursor` - Pagination cursor
+- `orderBy` - 'created_at' or 'updated_at'
+
+## Update Connected Accounts
+
+```typescript
+// Enable/disable
+await composio.connectedAccounts.enable('conn_abc123');
+await composio.connectedAccounts.disable('conn_abc123');
+
+// Refresh credentials (expired OAuth tokens)
+await composio.connectedAccounts.refresh('conn_abc123');
+```
+
+## Delete Connected Accounts
+
+```typescript
+await composio.connectedAccounts.delete('conn_abc123');
+```
+
+**Warning:** Permanent deletion. User must re-authenticate.
+
+## Wait for Connection Completion
+
+For async OAuth flows:
+
+```typescript
+// Default timeout (60 seconds)
+const account = await composio.connectedAccounts.waitForConnection('conn_123');
+
+// Custom timeout (2 minutes)
+const account = await composio.connectedAccounts.waitForConnection('conn_123', 120000);
+```
+
+**Errors:**
+- `ComposioConnectedAccountNotFoundError` - Account doesn't exist
+- `ConnectionRequestFailedError` - Connection failed/expired
+- `ConnectionRequestTimeoutError` - Timeout exceeded
+
+## Common Patterns
+
+### OAuth Flow
+
+```typescript
+// Create connection
+async function connectUser(userId, authConfigId) {
+  const request = await composio.connectedAccounts.link(
+    userId,
+    authConfigId,
+    { callbackUrl: 'https://app.com/callback' }
+  );
+  return { redirectUrl: request.redirectUrl };
+}
+
+// Handle callback
+async function handleCallback(connectionId) {
+  try {
+    const account = await composio.connectedAccounts.waitForConnection(
+      connectionId,
+      180000
+    );
+    return { success: true, account };
+  } catch (error) {
+    if (error.name === 'ConnectionRequestTimeoutError') {
+      return { error: 'Timeout. Please try again.' };
+    }
+    throw error;
+  }
+}
+```
+
+### Check Active Connections
+
+```typescript
+// Filter by status using statuses parameter
+async function getUserActiveConnections(userId) {
+  const accounts = await composio.connectedAccounts.list({
+    userIds: [userId],
+    statuses: ['ACTIVE']
+  });
+  return accounts.items;
+}
+
+// Check multiple statuses
+async function getUserConnectionsByStatus(userId) {
+  const accounts = await composio.connectedAccounts.list({
+    userIds: [userId],
+    statuses: ['ACTIVE', 'EXPIRED', 'FAILED']
+  });
+  return accounts.items;
+}
+
+async function isToolkitConnected(userId, toolkit) {
+  const accounts = await composio.connectedAccounts.list({
+    userIds: [userId],
+    toolkitSlugs: [toolkit],
+    statuses: ['ACTIVE']
+  });
+  return accounts.items.length > 0;
+}
+```
+
+**Available statuses:**
+- `INITIALIZING` - Connection being set up
+- `INITIATED` - Connection initiated, awaiting completion
+- `ACTIVE` - Connection active and ready to use
+- `FAILED` - Connection failed
+- `EXPIRED` - Credentials expired
+- `INACTIVE` - Connection disabled
+
+## Key Points
+
+- **Prefer link()** - Security, UI, and whitelabeling handled
+- **Store account IDs** - Save in your database, associate with users
+- **Check status** - Verify ACTIVE before use, refresh on errors
+- **Handle lifecycle** - Disable instead of delete when possible

package/skills/composio/rules/app-custom-tools.md

@@ -0,0 +1,220 @@
+---
+title: Creating Custom Tools
+impact: MEDIUM
+description: Build standalone and toolkit-based custom tools with proper authentication and validation
+tags: [custom-tools, extensibility, authentication, zod, development]
+---
+
+# Creating Custom Tools
+
+Create your own tools that integrate with Composio:
+- **Standalone tools** - No external authentication required
+- **Toolkit-based tools** - Use toolkit credentials for API requests
+
+> **⚠️ IMPORTANT:** When creating toolkit-based tools, do NOT make up or guess toolkit slugs. Always verify:
+> - Use `composio manage toolkits list` to discover and `composio manage toolkits info "..."` to view toolkit details and auth schemes (CLI)
+> - Use `composio.toolkits.get()` to discover toolkits programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## Standalone Tools
+
+For tools that don't need external authentication:
+
+```typescript
+import { z } from 'zod';
+
+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) => {
+    return {
+      data: { result: input.number * input.number },
+      error: null,
+      successful: true,
+    };
+  },
+});
+```
+
+**Use for:** Math, string operations, data transformations, internal logic.
+
+## Toolkit-Based Tools
+
+For tools that call authenticated APIs.
+
+### Using executeToolRequest (Recommended)
+
+Automatically handles authentication and baseURL:
+
+```typescript
+const tool = await composio.tools.createCustomTool({
+  slug: 'GITHUB_STAR_REPOSITORY',
+  name: 'Star GitHub Repository',
+  toolkitSlug: 'github',
+  description: 'Star a repository under composiohq',
+  inputParams: z.object({
+    repository: z.string().describe('Repository name'),
+    page: z.number().optional().describe('Page number'),
+  }),
+  execute: async (input, connectionConfig, executeToolRequest) => {
+    return await executeToolRequest({
+      endpoint: `/user/starred/composiohq/${input.repository}`,
+      method: 'PUT',
+      parameters: [
+        {
+          name: 'page',
+          value: input.page?.toString() || '1',
+          in: 'query', // Adds ?page=1
+        },
+      ],
+    });
+  },
+});
+```
+
+### Using connectionConfig (Direct API Calls)
+
+For custom HTTP requests:
+
+```typescript
+const tool = await composio.tools.createCustomTool({
+  slug: 'GITHUB_DIRECT_API',
+  name: 'Direct GitHub API',
+  toolkitSlug: 'github',
+  inputParams: z.object({
+    repo: z.string().describe('Repository name'),
+  }),
+  execute: async (input, connectionConfig) => {
+    const response = await fetch(`https://api.github.com/repos/${input.repo}`, {
+      headers: {
+        Authorization: `Bearer ${connectionConfig.val?.access_token}`,
+      },
+    });
+
+    const data = await response.json();
+
+    return {
+      data: data,
+      error: response.ok ? null : 'API request failed',
+      successful: response.ok,
+    };
+  },
+});
+```
+
+## Input Validation with Zod
+
+Define and validate parameters using Zod:
+
+```typescript
+inputParams: z.object({
+  // Required string
+  name: z.string().describe('User name'),
+
+  // Optional with default
+  count: z.number().optional().default(10).describe('Number of items'),
+
+  // With validation
+  email: z.string().email().describe('Email address'),
+
+  // Enum
+  status: z.enum(['active', 'inactive']).describe('Status'),
+
+  // Array
+  tags: z.array(z.string()).describe('Tags'),
+
+  // Nested object
+  metadata: z.object({
+    key: z.string(),
+    value: z.string(),
+  }).optional().describe('Metadata'),
+})
+```
+
+**Always use `.describe()`** - helps AI understand parameter purpose.
+
+## Headers and Query Parameters
+
+Add headers and query params via `parameters` array:
+
+```typescript
+execute: async (input, connectionConfig, executeToolRequest) => {
+  return await executeToolRequest({
+    endpoint: '/search/repositories',
+    method: 'GET',
+    parameters: [
+      // Query parameters
+      {
+        name: 'q',
+        value: input.query,
+        in: 'query', // ?q=value
+      },
+      // Headers
+      {
+        name: 'Accept',
+        value: 'application/vnd.github.v3+json',
+        in: 'header',
+      },
+    ],
+  });
+}
+```
+
+## Executing Custom Tools
+
+```typescript
+// Standalone tool
+await composio.tools.execute('CALCULATE_SQUARE', {
+  userId: 'default',
+  arguments: { number: 5 },
+});
+
+// Toolkit-based tool (uses userId to find account)
+await composio.tools.execute('GITHUB_STAR_REPOSITORY', {
+  userId: 'user_123',
+  arguments: { repository: 'composio' },
+});
+
+// With explicit connected account
+await composio.tools.execute('GITHUB_STAR_REPOSITORY', {
+  userId: 'user_123',
+  connectedAccountId: 'conn_abc123',
+  arguments: { repository: 'composio' },
+});
+```
+
+## Error Handling
+
+Always return structured responses:
+
+```typescript
+execute: async (input) => {
+  try {
+    const result = performOperation(input);
+    return {
+      data: result,
+      error: null,
+      successful: true,
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: error.message,
+      successful: false,
+    };
+  }
+}
+```
+
+## Key Points
+
+- **Naming:** Use `TOOLKIT_ACTION_DESCRIPTION` format for slugs
+- **Prefer executeToolRequest:** Handles auth and baseURL automatically
+- **Describe parameters:** AI agents need clear descriptions
+- **Not persisted:** Custom tools exist in memory only, recreate on restart
+- **Single toolkit scope:** executeToolRequest only works within same toolkit