@cmdop/bot 2026.2.26

package/examples/README.md

@@ -0,0 +1,142 @@
+# @cmdop/bot — Examples
+
+Runnable examples for each supported platform. All examples use `tsx` to run TypeScript directly.
+
+## Prerequisites
+
+```bash
+pnpm add @cmdop/bot
+# Install only the platform you need:
+pnpm add grammy @grammyjs/transformer-throttler          # Telegram
+pnpm add discord.js @discordjs/rest @discordjs/builders  # Discord
+pnpm add @slack/bolt @slack/web-api                      # Slack
+```
+
+---
+
+## telegram.ts — Telegram bot
+
+```bash
+CMDOP_API_KEY=cmdop_live_xxx \
+TELEGRAM_TOKEN=123456:ABC-DEF \
+pnpm tsx examples/telegram.ts
+```
+
+**Required env vars:**
+- `TELEGRAM_TOKEN` — get from [@BotFather](https://t.me/BotFather)
+
+**Optional:**
+- `CMDOP_API_KEY` — omit to use local IPC connection
+- `CMDOP_MACHINE` — pre-select a machine hostname
+- `BOT_ALLOWED_USERS` — comma-separated Telegram user IDs that receive `ADMIN`
+
+---
+
+## discord.ts — Discord bot (slash commands)
+
+```bash
+CMDOP_API_KEY=cmdop_live_xxx \
+DISCORD_TOKEN=your-bot-token \
+DISCORD_CLIENT_ID=your-app-id \
+DISCORD_GUILD_ID=your-guild-id \
+pnpm tsx examples/discord.ts
+```
+
+**Required env vars:**
+- `DISCORD_TOKEN` — bot token from [Discord Developer Portal](https://discord.com/developers)
+- `DISCORD_CLIENT_ID` — application ID from the same portal
+
+**Optional:**
+- `DISCORD_GUILD_ID` — register commands to a single guild (instant); omit for global (up to 1 hour)
+- `BOT_ALLOWED_USERS` — comma-separated Discord user IDs that receive `ADMIN`
+
+**Bot permissions required:** `applications.commands`, `bot` scope with `Send Messages`.
+
+---
+
+## slack.ts — Slack bot (Socket Mode)
+
+```bash
+CMDOP_API_KEY=cmdop_live_xxx \
+SLACK_BOT_TOKEN=xoxb-xxx \
+SLACK_APP_TOKEN=xapp-xxx \
+pnpm tsx examples/slack.ts
+```
+
+**Required env vars:**
+- `SLACK_BOT_TOKEN` — bot OAuth token (starts with `xoxb-`)
+- `SLACK_APP_TOKEN` — app-level token for Socket Mode (starts with `xapp-`)
+
+**Slack app setup:**
+1. Enable **Socket Mode** in your app settings
+2. Add `connections:write` scope to the App-level token
+3. Subscribe to bot events: `message.im`, `message.channels`, `app_mention`
+4. Enable **Messages Tab** in App Home settings
+
+**Optional:**
+- `BOT_ALLOWED_USERS` — comma-separated Slack user IDs that receive `ADMIN`
+
+---
+
+## multi-channel.ts — All platforms at once
+
+```bash
+CMDOP_API_KEY=cmdop_live_xxx \
+TELEGRAM_TOKEN=xxx \
+DISCORD_TOKEN=xxx \
+DISCORD_CLIENT_ID=xxx \
+SLACK_BOT_TOKEN=xoxb-xxx \
+SLACK_APP_TOKEN=xapp-xxx \
+pnpm tsx examples/multi-channel.ts
+```
+
+All channels share the same permission store. A user granted `EXECUTE` on Telegram has it on Discord and Slack too (if their identities are linked via `hub.linkIdentities()`).
+
+---
+
+## custom-channel.ts — Build your own platform integration
+
+Shows how to implement `ChannelProtocol` for any messaging platform not built into `@cmdop/bot`.
+
+```bash
+pnpm tsx examples/custom-channel.ts
+```
+
+No external dependencies — uses an in-process event emitter to simulate a platform.
+
+---
+
+## Running with a local CMDOP agent
+
+Omit `CMDOP_API_KEY` to connect via local IPC (requires the CMDOP agent running on your machine):
+
+```bash
+TELEGRAM_TOKEN=xxx pnpm tsx examples/telegram.ts
+```
+
+---
+
+## Common patterns
+
+### Grant permission to a specific user
+
+```ts
+// After hub is created, before hub.start():
+await hub.permissions.setLevel('telegram:123456789', 'EXECUTE');
+```
+
+### Pre-select a machine for all commands
+
+```ts
+const hub = await IntegrationHub.create({
+  defaultMachine: 'my-server.local',
+});
+```
+
+### Check which channels started successfully
+
+```ts
+await hub.start();
+console.log('Running:', hub.runningChannelIds);
+console.log('Failed: ', hub.failedChannelIds);
+```

package/examples/custom-channel.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env tsx
+/**
+ * Custom Channel Example
+ *
+ * Shows how to implement ChannelProtocol for any messaging platform
+ * not built into @cmdop/bot.
+ *
+ * This example uses an in-process EventEmitter to simulate a chat platform
+ * so it runs without any external dependencies.
+ *
+ * Run:
+ *   pnpm tsx examples/custom-channel.ts
+ *
+ * The bot will respond to a few simulated messages, then exit.
+ */
+
+import { EventEmitter } from 'node:events';
+import {
+  IntegrationHub,
+  BaseChannel,
+  createLogger,
+  type OutgoingMessage,
+  type IncomingMessage,
+  type PermissionManager,
+  type MessageDispatcher,
+  type LoggerProtocol,
+} from '../src/index.js';
+
+// ─── Simulated platform types ─────────────────────────────────────────────────
+
+interface PlatformMessage {
+  id: string;
+  authorId: string;
+  text: string;
+}
+
+interface PlatformSendEvent {
+  toUserId: string;
+  text: string;
+}
+
+// ─── Custom channel implementation ───────────────────────────────────────────
+
+/**
+ * EchoPlatformChannel — a minimal ChannelProtocol implementation.
+ *
+ * Key points when implementing your own channel:
+ *  1. Call `this.processMessage(msg)` from your platform event handler.
+ *     BaseChannel takes care of parsing, permission checks, dispatch, and send().
+ *  2. Implement `send()` to format and deliver OutgoingMessage to the platform.
+ *  3. `onMessage()` is called by the hub to register its own handler —
+ *     forward all incoming messages to it too (or just rely on processMessage).
+ *  4. `start()` / `stop()` manage the platform connection lifecycle.
+ */
+class EchoPlatformChannel extends BaseChannel {
+  private readonly platform: EventEmitter;
+  private readonly hubHandlers: Array<(msg: IncomingMessage) => Promise<void>> = [];
+
+  constructor(
+    platform: EventEmitter,
+    permissions: PermissionManager,
+    dispatcher: MessageDispatcher,
+    logger: LoggerProtocol,
+  ) {
+    // Pass a unique channel id, display name, and the shared hub dependencies
+    super('echo', 'Echo Platform', permissions, dispatcher, logger);
+    this.platform = platform;
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+  async start(): Promise<void> {
+    this.platform.on('message', this.handlePlatformMessage.bind(this));
+    this.logEvent('connected');
+  }
+
+  async stop(): Promise<void> {
+    this.platform.removeAllListeners('message');
+    this.logEvent('disconnected');
+  }
+
+  // ── Sending ───────────────────────────────────────────────────────────────
+
+  async send(_userId: string, message: OutgoingMessage): Promise<void> {
+    const text = this.formatMessage(message);
+    const event: PlatformSendEvent = { toUserId: _userId, text };
+    this.platform.emit('outgoing', event);
+    // In a real channel you'd call the platform SDK here, e.g.:
+    //   await platformApi.sendMessage(userId, text);
+  }
+
+  // ── Hub handler registration ───────────────────────────────────────────────
+
+  onMessage(handler: (msg: IncomingMessage) => Promise<void>): void {
+    // The hub registers its own handler here (for cross-channel routing).
+    // We store it and call it in handlePlatformMessage alongside processMessage.
+    this.hubHandlers.push(handler);
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  private async handlePlatformMessage(raw: PlatformMessage): Promise<void> {
+    const msg: IncomingMessage = {
+      id: raw.id,
+      userId: raw.authorId,
+      channelId: this.id,
+      text: raw.text,
+      timestamp: new Date(),
+      attachments: [],
+    };
+
+    // 1. Notify hub handlers (cross-channel features, logging, etc.)
+    for (const handler of this.hubHandlers) {
+      await handler(msg);
+    }
+
+    // 2. Parse command → check permission → dispatch → send result
+    await this.processMessage(msg);
+  }
+
+  private formatMessage(msg: OutgoingMessage): string {
+    switch (msg.type) {
+      case 'text':
+        return msg.text;
+      case 'code':
+        return `\`\`\`${msg.language ?? ''}\n${msg.code}\n\`\`\``;
+      case 'error':
+        return `ERROR: ${msg.message}${msg.hint ? ` (${msg.hint})` : ''}`;
+    }
+  }
+}
+
+// ─── Demo run ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const logger = createLogger('info');
+  const platform = new EventEmitter();
+
+  // Collect outgoing messages for display
+  platform.on('outgoing', (e: PlatformSendEvent) => {
+    console.log(`\n→ [to ${e.toUserId}] ${e.text}`);
+  });
+
+  // Create hub with local CMDOP connection (or mock)
+  // In a real app: IntegrationHub.create({ apiKey: process.env.CMDOP_API_KEY })
+  const hub = await IntegrationHub.create({ logger }).catch(() => {
+    console.warn('Could not connect to CMDOP — running in demo mode without a real client.');
+    process.exit(0);
+  });
+
+  // Grant admin to our test user
+  await hub.permissions.setLevel('echo:alice', 'ADMIN');
+
+  // Register the custom channel
+  const channel = new EchoPlatformChannel(
+    platform,
+    hub.permissions,
+    // Access the dispatcher via the hub's internal structure isn't exposed directly —
+    // for custom channels registered via hub.registerChannel(), the hub wires
+    // onMessage() to its internal dispatcher after registerChannel().
+    // Here we construct the channel and register it:
+    (hub as unknown as { _dispatcher: MessageDispatcher })._dispatcher,
+    logger,
+  );
+
+  hub.registerChannel(channel);
+  await hub.start();
+
+  console.log('Custom channel started. Simulating messages...\n');
+
+  // ── Simulate incoming platform messages ────────────────────────────────────
+
+  const send = (authorId: string, text: string) => {
+    console.log(`← [from ${authorId}] ${text}`);
+    platform.emit('message', {
+      id: `msg-${Date.now()}`,
+      authorId,
+      text,
+    } satisfies PlatformMessage);
+  };
+
+  // Small delay between messages so async handlers resolve cleanly
+  const delay = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+  await delay(50);
+  send('alice', '/help');
+
+  await delay(200);
+  send('alice', '/exec echo "hello from custom channel"');
+
+  await delay(200);
+  send('bob', '/exec ls'); // bob has no permission → PERMISSION_DENIED
+
+  await delay(200);
+  send('alice', 'just chatting — not a command, silently ignored');
+
+  await delay(200);
+
+  await hub.stop();
+  console.log('\nDone.');
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/examples/discord.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env tsx
+/**
+ * Discord Bot Example
+ *
+ * Run:
+ *   CMDOP_API_KEY=cmdop_live_xxx DISCORD_TOKEN=xxx DISCORD_CLIENT_ID=xxx pnpm tsx examples/discord.ts
+ *
+ * Required env vars:
+ *   CMDOP_API_KEY       — CMDOP cloud API key (omit to use local IPC)
+ *   DISCORD_TOKEN       — Bot token from Discord Developer Portal
+ *   DISCORD_CLIENT_ID   — Application ID from Discord Developer Portal
+ *
+ * Optional env vars:
+ *   DISCORD_GUILD_ID    — Register commands to a specific guild (instant); omit for global (up to 1h)
+ *   CMDOP_MACHINE       — Default machine hostname for all commands
+ *   BOT_ALLOWED_USERS   — Comma-separated Discord user IDs that get ADMIN
+ *   BOT_LOG_LEVEL       — debug | info | warn | error  (default: info)
+ */
+
+import { IntegrationHub } from '../src/index.js';
+
+async function main() {
+  const token = process.env['DISCORD_TOKEN'];
+  if (!token) {
+    console.error('DISCORD_TOKEN is required');
+    process.exit(1);
+  }
+
+  const clientId = process.env['DISCORD_CLIENT_ID'];
+  if (!clientId) {
+    console.error('DISCORD_CLIENT_ID is required');
+    process.exit(1);
+  }
+
+  const hub = await IntegrationHub.create({
+    apiKey: process.env['CMDOP_API_KEY'],
+    defaultMachine: process.env['CMDOP_MACHINE'],
+    adminUsers: (process.env['BOT_ALLOWED_USERS'] ?? '').split(',').filter(Boolean),
+  });
+
+  // addDiscord() wires permissions + dispatcher automatically
+  await hub.addDiscord({
+    token,
+    clientId,
+    guildId: process.env['DISCORD_GUILD_ID'],
+  });
+
+  await hub.start();
+  console.log('✅ Discord bot running. Press Ctrl+C to stop.');
+  console.log('Slash commands: /exec  /agent  /files  /help\n');
+
+  async function shutdown(signal: string) {
+    console.log(`\n${signal} received, shutting down...`);
+    await hub.stop();
+    process.exit(0);
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/examples/multi-channel.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env tsx
+/**
+ * Multi-Channel Bot Example
+ *
+ * Runs Telegram + Discord + Slack concurrently from a single hub.
+ * All three channels share the same permission store and CMDOP client,
+ * so a user granted EXECUTE on Telegram automatically has it on Discord/Slack.
+ *
+ * Run:
+ *   TELEGRAM_TOKEN=xxx \
+ *   DISCORD_TOKEN=xxx \
+ *   DISCORD_CLIENT_ID=xxx \
+ *   SLACK_BOT_TOKEN=xoxb-xxx \
+ *   SLACK_APP_TOKEN=xapp-xxx \
+ *   CMDOP_API_KEY=cmdop_live_xxx \
+ *   pnpm tsx examples/multi-channel.ts
+ *
+ * Required env vars:
+ *   CMDOP_API_KEY         — CMDOP cloud API key (omit for local IPC)
+ *   TELEGRAM_TOKEN        — Telegram bot token from @BotFather
+ *   DISCORD_TOKEN         — Bot token from Discord Developer Portal
+ *   DISCORD_CLIENT_ID     — Application ID from Discord Developer Portal
+ *   SLACK_BOT_TOKEN       — Bot OAuth token (xoxb-...)
+ *   SLACK_APP_TOKEN       — App-level token for Socket Mode (xapp-...)
+ *
+ * Optional env vars:
+ *   DISCORD_GUILD_ID      — Instant slash command registration for a guild
+ *   CMDOP_MACHINE         — Default machine hostname
+ *   BOT_ALLOWED_USERS     — Comma-separated user IDs that get ADMIN (any platform)
+ *   BOT_LOG_LEVEL         — debug | info | warn | error  (default: info)
+ */
+
+import { IntegrationHub, IdentityMap } from '../src/index.js';
+
+async function main() {
+  // ─── Validate required env vars ────────────────────────────────────────────
+  const telegramToken = process.env['TELEGRAM_TOKEN'];
+  const discordToken = process.env['DISCORD_TOKEN'];
+  const discordClientId = process.env['DISCORD_CLIENT_ID'];
+  const slackBotToken = process.env['SLACK_BOT_TOKEN'];
+  const slackAppToken = process.env['SLACK_APP_TOKEN'];
+
+  const missing: string[] = [];
+  if (!telegramToken) missing.push('TELEGRAM_TOKEN');
+  if (!discordToken) missing.push('DISCORD_TOKEN');
+  if (!discordClientId) missing.push('DISCORD_CLIENT_ID');
+  if (!slackBotToken) missing.push('SLACK_BOT_TOKEN');
+  if (!slackAppToken) missing.push('SLACK_APP_TOKEN');
+
+  if (missing.length > 0) {
+    console.error(`Missing required env vars: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  // ─── Create hub — shared CMDOP client, permissions, dispatcher ─────────────
+  const hub = await IntegrationHub.create({
+    apiKey: process.env['CMDOP_API_KEY'],
+    defaultMachine: process.env['CMDOP_MACHINE'],
+    adminUsers: (process.env['BOT_ALLOWED_USERS'] ?? '').split(',').filter(Boolean),
+    // 'isolated' (default): a failing channel doesn't block the others
+    channelStartMode: 'isolated',
+  });
+
+  // ─── Register channels ─────────────────────────────────────────────────────
+  await hub.addTelegram({ token: telegramToken! });
+  await hub.addDiscord({ token: discordToken!, clientId: discordClientId!, guildId: process.env['DISCORD_GUILD_ID'] });
+  await hub.addSlack({ token: slackBotToken!, appToken: slackAppToken! });
+
+  // ─── Cross-channel identity example ───────────────────────────────────────
+  // If you know a Telegram user and their Discord account are the same person,
+  // link them so permissions granted on one platform apply to the other.
+  // In a real app, you'd build a /link command to let users do this themselves.
+  //
+  // hub.linkIdentities('telegram', '12345678', 'discord', '987654321098765432');
+  //
+  // After linking: granting EXECUTE to the Telegram user also applies on Discord.
+  // await hub.permissions.setLevel('telegram:12345678', 'EXECUTE');
+
+  // ─── Start all channels concurrently ──────────────────────────────────────
+  await hub.start();
+
+  const running = hub.runningChannelIds;
+  const failed = hub.failedChannelIds;
+
+  console.log(`✅ IntegrationHub started (${running.length}/${hub.channelCount} channels running)`);
+  if (running.length > 0) console.log(`   Running: ${running.join(', ')}`);
+  if (failed.length > 0) console.warn(`   ⚠️  Failed: ${failed.join(', ')}`);
+  console.log('Commands: /exec  /agent  /files  /help\n');
+
+  // ─── Graceful shutdown ────────────────────────────────────────────────────
+  async function shutdown(signal: string) {
+    console.log(`\n${signal} received, shutting down...`);
+    await hub.stop();
+    console.log('Clean shutdown.');
+    process.exit(0);
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/examples/slack.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env tsx
+/**
+ * Slack Bot Example (Socket Mode)
+ *
+ * Run:
+ *   CMDOP_API_KEY=cmdop_live_xxx SLACK_BOT_TOKEN=xoxb-xxx SLACK_APP_TOKEN=xapp-xxx pnpm tsx examples/slack.ts
+ *
+ * Required env vars:
+ *   CMDOP_API_KEY       — CMDOP cloud API key (omit to use local IPC)
+ *   SLACK_BOT_TOKEN     — Bot OAuth token (xoxb-...)
+ *   SLACK_APP_TOKEN     — App-level token for Socket Mode (xapp-...)
+ *
+ * Optional env vars:
+ *   CMDOP_MACHINE       — Default machine hostname for all commands
+ *   BOT_ALLOWED_USERS   — Comma-separated Slack user IDs that get ADMIN
+ *   BOT_LOG_LEVEL       — debug | info | warn | error  (default: info)
+ *
+ * Slack app setup:
+ *   1. Enable Socket Mode in your Slack app settings
+ *   2. Enable the "connections:write" scope for the App-level token
+ *   3. Subscribe to bot events: message.im, message.channels, app_mention
+ *   4. Enable "Messages Tab" in App Home settings
+ */
+
+import { IntegrationHub } from '../src/index.js';
+
+async function main() {
+  const token = process.env['SLACK_BOT_TOKEN'];
+  if (!token) {
+    console.error('SLACK_BOT_TOKEN is required');
+    process.exit(1);
+  }
+
+  const appToken = process.env['SLACK_APP_TOKEN'];
+  if (!appToken) {
+    console.error('SLACK_APP_TOKEN is required');
+    process.exit(1);
+  }
+
+  const hub = await IntegrationHub.create({
+    apiKey: process.env['CMDOP_API_KEY'],
+    defaultMachine: process.env['CMDOP_MACHINE'],
+    adminUsers: (process.env['BOT_ALLOWED_USERS'] ?? '').split(',').filter(Boolean),
+  });
+
+  // addSlack() wires permissions + dispatcher automatically
+  await hub.addSlack({ token, appToken });
+
+  await hub.start();
+  console.log('✅ Slack bot running (Socket Mode). Press Ctrl+C to stop.');
+  console.log('Commands: /exec  /agent  /files  /help\n');
+
+  async function shutdown(signal: string) {
+    console.log(`\n${signal} received, shutting down...`);
+    await hub.stop();
+    process.exit(0);
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/examples/telegram.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+/**
+ * Telegram Bot Example
+ *
+ * Run:
+ *   CMDOP_API_KEY=cmdop_live_xxx TELEGRAM_TOKEN=xxx pnpm tsx examples/telegram.ts
+ *
+ * Required env vars:
+ *   CMDOP_API_KEY       — CMDOP cloud API key (omit to use local IPC)
+ *   TELEGRAM_TOKEN      — Telegram bot token from @BotFather
+ *
+ * Optional env vars:
+ *   CMDOP_MACHINE       — Default machine hostname for all commands
+ *   BOT_ALLOWED_USERS   — Comma-separated Telegram user IDs that get ADMIN
+ *   BOT_LOG_LEVEL       — debug | info | warn | error  (default: info)
+ */
+
+import { IntegrationHub } from '../src/index.js';
+
+async function main() {
+  const token = process.env['TELEGRAM_TOKEN'];
+  if (!token) {
+    console.error('TELEGRAM_TOKEN is required');
+    process.exit(1);
+  }
+
+  const hub = await IntegrationHub.create({
+    apiKey: process.env['CMDOP_API_KEY'],
+    defaultMachine: process.env['CMDOP_MACHINE'],
+    adminUsers: (process.env['BOT_ALLOWED_USERS'] ?? '').split(',').filter(Boolean),
+  });
+
+  // addTelegram() wires permissions + dispatcher automatically
+  await hub.addTelegram({ token });
+
+  await hub.start();
+  console.log('✅ Telegram bot running. Press Ctrl+C to stop.');
+  console.log('Available commands: /exec  /agent  /files  /help\n');
+
+  async function shutdown(signal: string) {
+    console.log(`\n${signal} received, shutting down...`);
+    await hub.stop();
+    process.exit(0);
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'));
+  process.once('SIGTERM', () => void shutdown('SIGTERM'));
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});