zilmate 1.7.8 → 1.8.1

package/.agents/skills/composio/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: composio
+description: Use 1000+ external apps via Composio - either directly through the CLI or by building AI agents and apps with the SDK
+tags: [composio, tool-router, agents, mcp, tools, api, automation, cli]
+---
+
+## When to Apply
+
+- User wants to access or interact with external apps (Gmail, Slack, GitHub, Notion, etc.)
+- User wants to automate a task using an external service (send email, create issue, post message)
+- Building an AI agent or app that integrates with external tools
+- Multi-user apps that need per-user connections to external services
+
+## Setup
+
+Check if the CLI is installed; if not, install it:
+```bash
+curl -fsSL https://composio.dev/install | bash
+```
+
+After installation, restart your terminal or source your shell config, then authenticate:
+```bash
+composio login       # OAuth; interactive org/project picker (use -y to skip)
+composio whoami      # verify org_id, project_id, user_id
+```
+For agents without direct browser access: `composio login --no-wait | jq` to get URL/key, share URL with user, then `composio login --key <cli_key> --no-wait` once they complete login.
+
+---
+
+### 1. Use Apps via Composio CLI
+
+**Use this when:** The user wants to take action on an external app directly — no code writing needed. The agent uses the CLI to search, connect, and execute tools on behalf of the user.
+
+Key commands (new top-level aliases):
+- `composio search "<query>"` — find tools by use case
+- `composio execute "<TOOL_SLUG>" -d '{...<input params>}'` — execute a tool
+- `composio link [toolkit]` — connect a user account to an app (agents: always use `--no-wait` for non-interactive mode)
+- `composio listen` — listen for real-time trigger events
+
+Typical workflow: **search → link (if needed) → execute**
+
+> Full reference: [Composio CLI Guide](rules/composio-cli.md)
+
+---
+
+### 2. Building Apps and Agents with Composio
+
+**Use this when:** Writing code — an AI agent, app, or backend service that integrates with external tools via the Composio SDK.
+
+Run this first inside the project directory to set up the API key:
+```bash
+composio init
+```
+
+> Full reference: [Building with Composio](rules/building-with-composio.md)

package/.agents/skills/composio/rules/_template.md

@@ -0,0 +1,38 @@
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+description: One sentence describing what this rule prevents or improves
+tags: [tag1, tag2, tag3]
+---
+
+# Rule Title
+
+Brief explanation of why this pattern is important (1-2 sentences).
+
+## ❌ Incorrect
+
+```typescript
+// Explain why this is wrong
+const bad = 'example';
+```
+
+```python
+# Explain why this is wrong
+bad = "example"
+```
+
+## ✅ Correct
+
+```typescript
+// Explain why this is correct
+const good = 'example';
+```
+
+```python
+# Explain why this is correct
+good = "example"
+```
+
+## Reference
+
+- [Relevant documentation](https://docs.composio.dev)

package/.agents/skills/composio/rules/app-auth-configs.md

@@ -0,0 +1,224 @@
+---
+title: Auth Config Management
+impact: MEDIUM
+description: Advanced programmatic management of authentication configurations for multi-tenant applications
+tags: [auth-config, authentication, oauth, api-key, advanced]
+---
+
+# Auth Config Management
+
+> **Note:** This is an **advanced use case**. Most users should create and manage auth configs through the Composio dashboard at [platform.composio.dev](https://platform.composio.dev). Use the SDK methods below only when you need programmatic auth config management.
+
+> **Using Tool Router?** If you're using Tool Router, 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 creating custom auth configs to be used with Tool Router.
+
+Auth configs define how authentication works for a toolkit. They specify the authentication scheme (OAuth2, API Key, etc.) and control which tools can be accessed.
+
+## When to Use the SDK
+
+Use these methods when you need to:
+- Programmatically create auth configs for multi-tenant applications
+- Dynamically manage auth configs based on user actions
+- Automate auth config creation in CI/CD pipelines
+
+For most cases, **use the dashboard** instead.
+
+## Read Auth Configs
+
+### List auth configs
+
+```typescript
+// List all auth configs
+const configs = await composio.authConfigs.list();
+
+// List for a specific toolkit
+const githubConfigs = await composio.authConfigs.list({
+  toolkit: 'github',
+});
+
+// Filter by Composio-managed
+const managedConfigs = await composio.authConfigs.list({
+  isComposioManaged: true,
+});
+```
+
+### Get a specific auth config
+
+```typescript
+const authConfig = await composio.authConfigs.get('auth_config_123');
+console.log(authConfig.name);
+console.log(authConfig.authScheme); // 'OAUTH2', 'API_KEY', etc.
+console.log(authConfig.toolkit.slug);
+```
+
+## Create Auth Configs
+
+### Composio-Managed Authentication (Recommended)
+
+Use Composio's OAuth credentials (simplest option):
+
+```typescript
+const authConfig = await composio.authConfigs.create('github', {
+  type: 'use_composio_managed_auth',
+  name: 'GitHub Auth Config',
+});
+```
+
+### Custom OAuth Credentials
+
+Use your own OAuth app credentials:
+
+```typescript
+const authConfig = await composio.authConfigs.create('slack', {
+  type: 'use_custom_auth',
+  name: 'My Slack Auth',
+  authScheme: 'OAUTH2',
+  credentials: {
+    client_id: 'your_client_id',
+    client_secret: 'your_client_secret',
+  }
+});
+```
+
+### Custom API Key Authentication
+
+For services using API keys:
+
+```typescript
+const authConfig = await composio.authConfigs.create('openai', {
+  type: 'use_custom_auth',
+  name: 'OpenAI API Key Auth',
+  authScheme: 'API_KEY',
+  credentials: {
+    api_key: 'your_api_key',
+  }
+});
+```
+
+## Update Auth Configs
+
+### Update custom auth credentials
+
+```typescript
+const updated = await composio.authConfigs.update('auth_config_123', {
+  type: 'custom',
+  credentials: {
+    client_id: 'new_client_id',
+    client_secret: 'new_client_secret',
+  }
+});
+```
+
+### Update OAuth scopes
+
+```typescript
+const updated = await composio.authConfigs.update('auth_config_456', {
+  type: 'default',
+  scopes: 'read:user,repo'
+});
+```
+
+### Restrict tools (for security)
+
+```typescript
+const restricted = await composio.authConfigs.update('auth_config_789', {
+  type: 'custom',
+  credentials: { /* ... */ },
+  toolAccessConfig: {
+    toolsAvailableForExecution: ['SLACK_SEND_MESSAGE', 'SLACK_GET_CHANNEL']
+  }
+});
+```
+
+## Enable/Disable Auth Configs
+
+```typescript
+// Enable an auth config
+await composio.authConfigs.enable('auth_config_123');
+
+// Disable an auth config
+await composio.authConfigs.disable('auth_config_123');
+```
+
+## Delete Auth Configs
+
+```typescript
+await composio.authConfigs.delete('auth_config_123');
+```
+
+**Warning:** Deleting an auth config will affect all connected accounts using it.
+
+## Available Parameters
+
+### List Parameters
+
+- `toolkit` (string) - Filter by toolkit slug
+- `isComposioManaged` (boolean) - Filter Composio-managed vs custom
+- `limit` (number) - Results per page
+- `cursor` (string) - Pagination cursor
+
+### Create Parameters
+
+**For `use_composio_managed_auth`:**
+- `type`: `'use_composio_managed_auth'`
+- `name` (optional): Display name
+- `credentials` (optional): Object with `scopes` field
+- `toolAccessConfig` (optional): Tool restrictions
+- `isEnabledForToolRouter` (optional): Enable for Tool Router
+
+**For `use_custom_auth`:**
+- `type`: `'use_custom_auth'`
+- `authScheme`: `'OAUTH2'`, `'API_KEY'`, `'BASIC_AUTH'`, etc.
+- `name` (optional): Display name
+- `credentials`: Object with auth-specific fields (client_id, client_secret, api_key, etc.)
+- `toolAccessConfig` (optional): Tool restrictions
+- `isEnabledForToolRouter` (optional): Enable for Tool Router
+
+### Update Parameters
+
+**For custom type:**
+```typescript
+{
+  type: 'custom',
+  credentials: { /* auth fields */ },
+  toolAccessConfig: {
+    toolsAvailableForExecution: ['TOOL_SLUG_1', 'TOOL_SLUG_2']
+  }
+}
+```
+
+**For default type:**
+```typescript
+{
+  type: 'default',
+  scopes: 'scope1,scope2',
+  toolAccessConfig: {
+    toolsAvailableForExecution: ['TOOL_SLUG_1', 'TOOL_SLUG_2']
+  }
+}
+```
+
+## Best Practices
+
+1. **Use the dashboard for manual setup**
+   - Easier to configure
+   - Visual interface for OAuth setup
+   - Less error-prone
+
+2. **Use SDK for automation only**
+   - Multi-tenant app provisioning
+   - CI/CD integration
+   - Dynamic configuration
+
+3. **Prefer Composio-managed auth**
+   - No OAuth app setup required
+   - Maintained by Composio
+   - Works out of the box
+
+4. **Restrict tools for security**
+   - Limit `toolsAvailableForExecution`
+   - Implements least privilege
+   - Reduces risk
+
+5. **Name configs clearly**
+   - Include environment: "Production GitHub", "Staging Slack"
+   - Makes debugging easier

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

@@ -0,0 +1,143 @@
+---
+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/.agents/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