zilmate 1.7.8 → 1.8.0

package/.agents/skills/composio/rules/triggers-manage.md

@@ -0,0 +1,275 @@
+---
+title: Manage Trigger Lifecycle (Enable, Disable, Update)
+impact: HIGH
+description: Control trigger states, update configurations, and manage trigger instances
+tags: [triggers, lifecycle, enable, disable, update, management]
+---
+
+# Manage Trigger Lifecycle
+
+Control trigger states and configurations without recreating triggers.
+
+## Enable/Disable Triggers
+
+```typescript
+// Disable trigger (stop receiving events)
+await composio.triggers.disable('trigger_id_123');
+
+// Enable trigger (resume receiving events)
+await composio.triggers.enable('trigger_id_123');
+```
+
+**Use cases:**
+- **Disable:** Pause events temporarily, user disconnects account, billing issues
+- **Enable:** Resume after resolving issues, user reconnects account
+
+## Update Trigger Configuration
+
+```typescript
+// Update trigger config
+await composio.triggers.update('trigger_id_123', {
+  triggerConfig: {
+    labelIds: 'SENT', // Changed from 'INBOX'
+    interval: 120     // Changed from 60
+  }
+});
+```
+
+**Updateable fields:**
+- `triggerConfig` - Trigger-specific configuration
+- Cannot change trigger slug or connected account
+
+## Delete Triggers
+
+```typescript
+await composio.triggers.delete('trigger_id_123');
+```
+
+**Warning:** Permanent deletion. Creates new trigger if needed later.
+
+## List Active Triggers
+
+```typescript
+// All active triggers
+const triggers = await composio.triggers.getActiveTriggers();
+
+// By trigger slug
+const gmailTriggers = await composio.triggers.getActiveTriggers({
+  triggerSlugs: ['GMAIL_NEW_GMAIL_MESSAGE']
+});
+
+// By user
+const userTriggers = await composio.triggers.getActiveTriggers({
+  userIds: ['user_123']
+});
+
+// By connected account
+const accountTriggers = await composio.triggers.getActiveTriggers({
+  connectedAccountIds: ['conn_abc123']
+});
+
+// By status
+const enabled = await composio.triggers.getActiveTriggers({
+  status: 'enabled'
+});
+const disabled = await composio.triggers.getActiveTriggers({
+  status: 'disabled'
+});
+
+// Combine filters
+const filtered = await composio.triggers.getActiveTriggers({
+  triggerSlugs: ['SLACK_NEW_MESSAGE'],
+  userIds: ['user_123'],
+  status: 'enabled'
+});
+```
+
+**Response includes:**
+- `triggerId` - Unique ID
+- `triggerSlug` - Trigger type
+- `userId` - User ID
+- `connectedAccountId` - Account ID
+- `status` - 'enabled' or 'disabled'
+- `config` - Current configuration
+- `createdAt`, `updatedAt` - Timestamps
+
+## Get Trigger Details
+
+```typescript
+// Get specific trigger
+const trigger = await composio.triggers.getTriggerById('trigger_id_123');
+
+console.log(trigger.status);                // 'enabled'
+console.log(trigger.triggerSlug);           // 'GMAIL_NEW_GMAIL_MESSAGE'
+console.log(trigger.config.triggerConfig);  // { labelIds: 'INBOX', ... }
+```
+
+## Common Patterns
+
+### Pause User's Triggers
+
+```typescript
+async function pauseUserTriggers(userId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId],
+    status: 'enabled'
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.disable(trigger.triggerId);
+  }
+}
+```
+
+### Resume User's Triggers
+
+```typescript
+async function resumeUserTriggers(userId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId],
+    status: 'disabled'
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.enable(trigger.triggerId);
+  }
+}
+```
+
+### Clean Up Disconnected Account Triggers
+
+```typescript
+async function cleanupTriggers(connectedAccountId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    connectedAccountIds: [connectedAccountId]
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.delete(trigger.triggerId);
+  }
+}
+```
+
+### Update All User Gmail Triggers
+
+```typescript
+async function updateGmailInterval(userId: string, newInterval: number) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId],
+    triggerSlugs: ['GMAIL_NEW_GMAIL_MESSAGE']
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.update(trigger.triggerId, {
+      triggerConfig: {
+        ...trigger.config.triggerConfig,
+        interval: newInterval
+      }
+    });
+  }
+}
+```
+
+### Check Trigger Status
+
+```typescript
+async function isTriggerActive(triggerId: string): Promise<boolean> {
+  try {
+    const trigger = await composio.triggers.getTriggerById(triggerId);
+    return trigger.status === 'enabled';
+  } catch (error) {
+    return false; // Trigger doesn't exist
+  }
+}
+```
+
+### Get Trigger Count by User
+
+```typescript
+async function getUserTriggerCount(userId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId]
+  });
+
+  return {
+    total: triggers.items.length,
+    enabled: triggers.items.filter(t => t.status === 'enabled').length,
+    disabled: triggers.items.filter(t => t.status === 'disabled').length
+  };
+}
+```
+
+## Lifecycle Management
+
+### Account Disconnection
+
+```typescript
+// When user disconnects an account
+async function handleAccountDisconnect(accountId: string) {
+  // Option 1: Disable triggers (can resume later)
+  const triggers = await composio.triggers.getActiveTriggers({
+    connectedAccountIds: [accountId]
+  });
+  for (const trigger of triggers.items) {
+    await composio.triggers.disable(trigger.triggerId);
+  }
+
+  // Option 2: Delete triggers (permanent)
+  for (const trigger of triggers.items) {
+    await composio.triggers.delete(trigger.triggerId);
+  }
+}
+```
+
+### Account Reconnection
+
+```typescript
+// When user reconnects
+async function handleAccountReconnect(accountId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    connectedAccountIds: [accountId],
+    status: 'disabled'
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.enable(trigger.triggerId);
+  }
+}
+```
+
+### Subscription Management
+
+```typescript
+// Downgrade: disable non-essential triggers
+async function handleDowngrade(userId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId],
+    triggerSlugs: ['NON_ESSENTIAL_TRIGGER']
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.disable(trigger.triggerId);
+  }
+}
+
+// Upgrade: enable all triggers
+async function handleUpgrade(userId: string) {
+  const triggers = await composio.triggers.getActiveTriggers({
+    userIds: [userId],
+    status: 'disabled'
+  });
+
+  for (const trigger of triggers.items) {
+    await composio.triggers.enable(trigger.triggerId);
+  }
+}
+```
+
+## Key Points
+
+- **Disable vs Delete** - Disable pauses events, delete is permanent
+- **Update config** - Change trigger settings without recreating
+- **Filter getActiveTriggers** - Use multiple filters to narrow results
+- **Batch operations** - Loop through triggers for bulk enable/disable
+- **Handle disconnects** - Disable or delete triggers when accounts disconnect
+- **Status check** - Always verify trigger status before operations

package/.agents/skills/composio/rules/triggers-subscribe.md

@@ -0,0 +1,173 @@
+---
+title: Subscribe to Trigger Events
+impact: MEDIUM
+description: Listen to real-time trigger events during development using subscribe()
+tags: [triggers, events, subscribe, development, real-time]
+---
+
+# Subscribe to Trigger Events
+
+Use `subscribe()` to listen to trigger events in **development only**. For production, use webhooks via `listenToTriggers()`.
+
+## Development vs Production
+
+**Development (subscribe):**
+- Real-time event listening in CLI/local development
+- Simple callback function
+- No webhook URLs needed
+- **Do NOT use in production**
+
+**Production (webhooks):**
+- Scalable webhook delivery
+- Reliable event processing
+- Use `listenToTriggers()` with Express/HTTP server
+- See triggers-webhook.md
+
+## Basic Subscribe
+
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+
+// Subscribe to trigger events
+const unsubscribe = await composio.triggers.subscribe((event) => {
+  console.log('Trigger received:', event.triggerSlug);
+  console.log('Payload:', event.payload);
+  console.log('User:', event.userId);
+  console.log('Account:', event.connectedAccountId);
+});
+
+// Keep process alive
+console.log('Listening for events... Press Ctrl+C to stop');
+```
+
+## Subscribe with Filters
+
+```typescript
+// Filter by trigger slug
+await composio.triggers.subscribe(
+  (event) => {
+    console.log('Gmail message:', event.payload);
+  },
+  { triggerSlugs: ['GMAIL_NEW_GMAIL_MESSAGE'] }
+);
+
+// Filter by user ID
+await composio.triggers.subscribe(
+  (event) => {
+    console.log('Event for user_123:', event.payload);
+  },
+  { userIds: ['user_123'] }
+);
+
+// Filter by connected account
+await composio.triggers.subscribe(
+  (event) => {
+    console.log('Event from specific account:', event.payload);
+  },
+  { connectedAccountIds: ['conn_abc123'] }
+);
+
+// Combine filters
+await composio.triggers.subscribe(
+  (event) => {
+    console.log('Filtered event:', event.payload);
+  },
+  {
+    triggerSlugs: ['SLACK_NEW_MESSAGE'],
+    userIds: ['user_123'],
+    connectedAccountIds: ['conn_def456']
+  }
+);
+```
+
+## Event Payload Structure
+
+```typescript
+interface TriggerEvent {
+  triggerSlug: string;           // 'GMAIL_NEW_GMAIL_MESSAGE'
+  userId: string;                // 'user_123'
+  connectedAccountId: string;    // 'conn_abc123'
+  payload: {
+    // Trigger-specific data
+    // Example for Gmail:
+    // { id: 'msg_123', subject: 'Hello', from: 'user@example.com' }
+  };
+  metadata: {
+    triggerId: string;
+    timestamp: string;
+  };
+}
+```
+
+## Unsubscribe
+
+```typescript
+const unsubscribe = await composio.triggers.subscribe((event) => {
+  console.log('Event:', event);
+});
+
+// Stop listening
+await unsubscribe();
+console.log('Unsubscribed from all triggers');
+```
+
+## Development Pattern
+
+```typescript
+async function devMode() {
+  console.log('Starting development mode...');
+
+  // Subscribe to events
+  const unsubscribe = await composio.triggers.subscribe((event) => {
+    console.log(`\n[${event.triggerSlug}]`);
+    console.log('User:', event.userId);
+    console.log('Payload:', JSON.stringify(event.payload, null, 2));
+  });
+
+  // Handle shutdown
+  process.on('SIGINT', async () => {
+    console.log('\nShutting down...');
+    await unsubscribe();
+    process.exit(0);
+  });
+
+  console.log('Listening for events. Press Ctrl+C to stop.');
+}
+
+devMode();
+```
+
+## Migration to Production
+
+Development (subscribe):
+```typescript
+// Development only
+await composio.triggers.subscribe((event) => {
+  console.log(event);
+});
+```
+
+Production (webhooks):
+```typescript
+// Production ready
+import express from 'express';
+
+const app = express();
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+
+await composio.triggers.listenToTriggers(app, (event) => {
+  console.log('Webhook received:', event);
+});
+
+app.listen(3000);
+```
+
+## Key Points
+
+- **Development only** - Never use subscribe() in production
+- **Use webhooks for production** - More reliable and scalable
+- **Filter events** - Reduce noise with triggerSlugs, userIds, connectedAccountIds
+- **Cleanup** - Always call unsubscribe() when done
+- **Long-running process** - Keep Node.js process alive to receive events

package/.agents/skills/composio/rules/triggers-webhook.md

@@ -0,0 +1,227 @@
+---
+title: Verify Webhooks for Production (Recommended)
+impact: CRITICAL
+description: Use webhook verification for reliable, scalable event delivery in production
+tags: [triggers, webhooks, production, security, verification, hmac]
+---
+
+# Webhook Verification for Production
+
+Webhooks are the **production-ready** way to receive trigger events. Provides reliable delivery, automatic retries, and works with serverless.
+
+## Setup with listenToTriggers()
+
+```typescript
+import express from 'express';
+import { Composio } from '@composio/core';
+
+const app = express();
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+
+// Automatic webhook verification and handling
+await composio.triggers.listenToTriggers(app, async (event) => {
+  console.log('Webhook:', event.triggerSlug);
+  console.log('User:', event.userId);
+  console.log('Payload:', event.payload);
+
+  await handleEvent(event);
+});
+
+app.listen(3000);
+```
+
+**What it does:**
+- Creates `/composio/triggers` endpoint
+- Verifies webhook signatures automatically
+- Parses and validates payloads
+- Calls callback with verified events
+
+## Manual Verification
+
+For custom endpoints:
+
+```typescript
+import { verifyWebhookSignature } from '@composio/core';
+
+app.post('/custom/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-composio-signature'];
+  const payload = req.body;
+
+  const isValid = verifyWebhookSignature(
+    payload,
+    signature,
+    process.env.COMPOSIO_WEBHOOK_SECRET
+  );
+
+  if (!isValid) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+
+  const event = JSON.parse(payload);
+  handleEvent(event);
+  res.json({ success: true });
+});
+```
+
+## Event Structure
+
+```typescript
+interface WebhookEvent {
+  triggerSlug: string;
+  userId: string;
+  connectedAccountId: string;
+  payload: object;
+  metadata: {
+    triggerId: string;
+    timestamp: string;
+    webhookId: string;
+  };
+}
+```
+
+## Processing Patterns
+
+### Route by Trigger Type
+
+```typescript
+async function handleEvent(event: WebhookEvent) {
+  switch (event.triggerSlug) {
+    case 'GMAIL_NEW_GMAIL_MESSAGE':
+      await handleGmail(event.userId, event.payload);
+      break;
+    case 'GITHUB_COMMIT_EVENT':
+      await handleGithub(event.userId, event.payload);
+      break;
+    case 'SLACK_NEW_MESSAGE':
+      await handleSlack(event.userId, event.payload);
+      break;
+  }
+}
+```
+
+### With Error Handling
+
+```typescript
+await composio.triggers.listenToTriggers(app, async (event) => {
+  try {
+    await processEvent(event);
+  } catch (error) {
+    console.error('Error:', error);
+    // Don't throw - acknowledge webhook received
+  }
+});
+```
+
+### With Idempotency
+
+```typescript
+await composio.triggers.listenToTriggers(app, async (event) => {
+  const webhookId = event.metadata.webhookId;
+
+  // Check if already processed
+  if (await isProcessed(webhookId)) {
+    console.log('Duplicate webhook, skipping');
+    return;
+  }
+
+  // Mark as processed
+  await markProcessed(webhookId);
+
+  // Process event
+  await handleEvent(event);
+});
+```
+
+## Configuration
+
+Set webhook URL in Composio dashboard:
+
+1. Go to [platform.composio.dev](https://platform.composio.dev)
+2. **Settings** > **Webhooks**
+3. Set URL: `https://your-app.com/composio/triggers`
+
+**Requirements:**
+- HTTPS URL (publicly accessible)
+- Respond with 200 OK within 30 seconds
+- Handle concurrent requests
+
+## Testing Locally
+
+Use ngrok:
+
+```bash
+ngrok http 3000
+# Use https://abc123.ngrok.io/composio/triggers in dashboard
+```
+
+## Security
+
+- **Always verify signatures** - Use `listenToTriggers()` or manual verification
+- **HTTPS only** - Never HTTP in production
+- **Keep secrets secure** - Environment variables only
+- **Validate payloads** - Check required fields
+- **Handle errors gracefully** - Log, don't throw
+- **Implement idempotency** - Use webhookId to deduplicate
+
+## Common Issues
+
+**401 Unauthorized:**
+- Invalid signature - check webhook secret
+- Wrong secret - verify environment variable
+
+**Timeout:**
+- Processing > 30 seconds - move to background queue
+- Return 200 OK immediately
+
+**Duplicates:**
+- Webhooks may deliver multiple times
+- Use webhookId for idempotency
+
+## Complete Example
+
+```typescript
+import express from 'express';
+import { Composio } from '@composio/core';
+
+const app = express();
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+
+await composio.triggers.listenToTriggers(app, async (event) => {
+  try {
+    // Idempotency check
+    if (await isProcessed(event.metadata.webhookId)) {
+      return;
+    }
+
+    // Process
+    switch (event.triggerSlug) {
+      case 'GMAIL_NEW_GMAIL_MESSAGE':
+        await sendNotification(event.userId, {
+          title: 'New Email',
+          body: event.payload.subject
+        });
+        break;
+    }
+
+    // Mark processed
+    await markProcessed(event.metadata.webhookId);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+});
+
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+
+app.listen(3000, () => {
+  console.log('Webhook server running on port 3000');
+});
+```
+
+## Key Points
+
+- **Production standard** - Use webhooks, not subscribe()
+- **listenToTriggers()** - Handles verification automatically
+- **HTTPS required** - Security requirement
+- **Quick response** - Return 200 OK within 30s
+- **Idempotency** - Handle duplicates with webhookId
+- **Error handling** - Log but don't throw