agent-messenger 2.20.4 → 2.21.0

package/docs/content/docs/cli/webexbot.mdx

@@ -0,0 +1,290 @@
+---
+title: Webex Bot
+description: Complete reference for the agent-webexbot CLI.
+---
+
+> **Tip**: `agent-webexbot` is a shortcut for `agent-messenger webexbot`.
+
+## Overview
+
+`agent-webexbot` wraps the Webex REST API using **bot tokens** issued at [developer.webex.com](https://developer.webex.com). It's designed for server-side and CI/CD integrations where you want a persistent bot identity rather than a user session.
+
+For acting as a real user account (browser token extraction or OAuth Device Grant), use [`agent-webex`](./webex) instead.
+
+## Requirements
+
+- A bot token from [developer.webex.com](https://developer.webex.com/my-apps/new/bot)
+- Node.js 18+ or Bun runtime
+
+## Quick Start
+
+```bash
+# 1. Set your bot token (validates against Webex)
+agent-webexbot auth set YOUR_BOT_TOKEN
+
+# 2. Verify auth
+agent-webexbot whoami
+
+# 3. Send a message
+agent-webexbot message send <space-id> "Hello from the bot!"
+
+# 4. Stream real-time events
+agent-webexbot listen
+```
+
+## Authentication
+
+### Bot Token Setup
+
+Create a bot at [developer.webex.com → My Webex Apps → Create a Bot](https://developer.webex.com/my-apps/new/bot). The token is shown once at creation time — save it immediately. Bot tokens never expire.
+
+```bash
+# Set bot token (validates against Webex API before saving)
+agent-webexbot auth set YOUR_BOT_TOKEN
+
+# Set with a custom bot identifier for multi-bot setups
+agent-webexbot auth set YOUR_BOT_TOKEN --bot deploy
+
+# Check auth status
+agent-webexbot auth status
+
+# Clear all stored credentials
+agent-webexbot auth clear
+```
+
+Credentials are stored in `~/.config/agent-messenger/webexbot-credentials.json` (0600 permissions).
+
+### Multi-Bot Support
+
+```bash
+# List all configured bots
+agent-webexbot auth list
+
+# Switch active bot
+agent-webexbot auth use <bot-id>
+
+# Remove a stored bot
+agent-webexbot auth remove <bot-id>
+
+# Use a specific bot for a single command
+agent-webexbot --bot deploy message send <space-id> "Deploy succeeded"
+```
+
+## Commands
+
+### Whoami Command
+
+```bash
+# Show current authenticated bot
+agent-webexbot whoami
+agent-webexbot whoami --pretty
+```
+
+Output includes the bot's identity information from the Webex API.
+
+### Space Commands
+
+```bash
+# List spaces the bot is a member of
+agent-webexbot space list
+agent-webexbot space list --type group
+agent-webexbot space list --type direct
+agent-webexbot space list --max 20
+
+# Get space details
+agent-webexbot space info <space-id>
+```
+
+### Message Commands
+
+```bash
+# Send a message to a space
+agent-webexbot message send <space-id> "Hello world"
+
+# Send a markdown message
+agent-webexbot message send <space-id> "**Bold** and _italic_" --markdown
+
+# Send a direct message by email
+agent-webexbot message dm alice@example.com "Hey, quick question"
+agent-webexbot message dm alice@example.com "**Build failed**" --markdown
+
+# List messages in a space
+agent-webexbot message list <space-id>
+agent-webexbot message list <space-id> --max 50
+
+# Get a specific message
+agent-webexbot message get <message-id>
+
+# Edit a message (bot's own messages only)
+agent-webexbot message edit <message-id> <space-id> "Updated text"
+agent-webexbot message edit <message-id> <space-id> "**Updated**" --markdown
+
+# Delete a message
+agent-webexbot message delete <message-id>
+```
+
+### Member Commands
+
+```bash
+# List members of a space
+agent-webexbot member list <space-id>
+agent-webexbot member list <space-id> --max 100
+```
+
+### Listen Command
+
+Stream real-time Webex events over the Mercury WebSocket. No public URL required — works behind firewalls and in CI/CD environments.
+
+```bash
+# Listen for all default events (NDJSON output)
+agent-webexbot listen
+
+# Filter to specific events
+agent-webexbot listen --events message_created,membership_created
+
+# Pretty-print each event
+agent-webexbot listen --pretty
+
+# Use a specific bot
+agent-webexbot listen --bot deploy
+```
+
+Supported events:
+
+| Event                | Description                                 |
+| -------------------- | ------------------------------------------- |
+| `message_created`    | New message posted in a space the bot is in |
+| `message_updated`    | Existing message edited                     |
+| `message_deleted`    | Message deleted                             |
+| `membership_created` | Bot added to a new space                    |
+| `attachment_action`  | Adaptive card button clicked                |
+| `room_created`       | New space created                           |
+| `room_updated`       | Space details changed                       |
+| `webex_event`        | Catch-all — every content event             |
+| `connected`          | WebSocket connection established            |
+| `reconnecting`       | Reconnect attempt in progress               |
+| `disconnected`       | Connection dropped (will auto-reconnect)    |
+| `error`              | Connection error (auto-reconnect continues) |
+
+Default events (when `--events` is omitted): `message_created`, `message_updated`, `message_deleted`, `membership_created`, `attachment_action`, `connected`, `reconnecting`, `disconnected`, `error`.
+
+Output is NDJSON — one JSON object per line:
+
+```json
+{"type":"connected","payload":{"connected":true,"status":{"status":"connected","webSocketOpen":true,"kmsInitialized":true,"deviceRegistered":true,"reconnectAttempt":0}}}
+{"type":"message_created","payload":{"id":"Y2lz...","text":"Hello bot!","personEmail":"alice@example.com"}}
+```
+
+The listener filters the bot's own messages by default (`ignoreSelfMessages` defaults to `true`), preventing echo loops.
+
+## Global Options
+
+All commands support these options:
+
+```bash
+--pretty        # Pretty-print JSON output (default is compact JSON)
+--bot <id>      # Use a specific bot for this command
+```
+
+## Key Differences: Webex Bot vs Webex User
+
+| Feature            | agent-webex (user)                 | agent-webexbot (bot)            |
+| ------------------ | ---------------------------------- | ------------------------------- |
+| Token type         | Browser session / OAuth / PAT      | Bot token (developer.webex.com) |
+| Auth method        | Browser extraction or Device Grant | `auth set <token>` (manual)     |
+| Token lifetime     | Session-based or 14-day OAuth      | Never expires                   |
+| Messages appear as | You (your name)                    | Bot identity                    |
+| Real-time events   | No                                 | Yes (Mercury WebSocket)         |
+| CI/CD friendly     | Possible (bot token via `--token`) | Yes (designed for it)           |
+| Initiate DMs       | Yes                                | Yes (by email)                  |
+
+## Troubleshooting
+
+### "No credentials configured"
+
+No bot token stored. Set one first:
+
+```bash
+agent-webexbot auth set YOUR_BOT_TOKEN
+```
+
+### "Token is not a bot token"
+
+The token you provided belongs to a user account, not a bot. Use `agent-webex` for user tokens, or create a bot at [developer.webex.com](https://developer.webex.com/my-apps/new/bot) to get a proper bot token.
+
+### "401 Unauthorized"
+
+Bot tokens don't expire, so a 401 usually means the token was copied incorrectly or the bot was deleted. Double-check the full token, then re-run:
+
+```bash
+agent-webexbot auth set YOUR_BOT_TOKEN
+```
+
+### Bot can't see a space
+
+The bot must be added to each space it needs to interact with. Invite the bot from the Webex app, then retry.
+
+### Rate Limiting (429 Too Many Requests)
+
+Webex allows roughly 600 API calls per minute. Add delays between bulk operations:
+
+```bash
+sleep 1
+```
+
+### Space or Message Not Found
+
+Webex uses opaque Base64-encoded IDs. Always get IDs from `space list` first:
+
+```bash
+agent-webexbot space list --pretty
+```
+
+### `agent-webexbot: command not found`
+
+The npm package is `agent-messenger`, not `agent-webexbot`:
+
+```bash
+npm install -g agent-messenger
+```
+
+## AI Agent Integration
+
+See [`skills/agent-webexbot/`](https://github.com/agent-messenger/agent-messenger/tree/main/skills/agent-webexbot) for:
+
+- Complete skill documentation
+- Common patterns and runnable templates
+
+### Example: CI/CD Notifier
+
+```bash
+#!/bin/bash
+# Post build status to a Webex space
+
+SPACE_ID="Y2lzY29zcGFyazovL..."
+
+# Send initial status
+RESULT=$(agent-webexbot message send "$SPACE_ID" "Deploying v2.1.0...")
+MSG_ID=$(echo "$RESULT" | jq -r '.id')
+
+# ... do work ...
+
+# Update with final status
+agent-webexbot message edit "$MSG_ID" "$SPACE_ID" "Deployed v2.1.0 successfully!"
+```
+
+### Example: Real-Time Event Handler
+
+```bash
+#!/bin/bash
+# Stream events and react to messages
+
+agent-webexbot listen --events message_created | while read -r line; do
+  TEXT=$(echo "$line" | jq -r '.payload.text // ""')
+  SPACE=$(echo "$line" | jq -r '.payload.roomId // ""')
+
+  if echo "$TEXT" | grep -qi "status"; then
+    agent-webexbot message send "$SPACE" "All systems operational."
+  fi
+done
+```

package/docs/content/docs/sdk/meta.json

@@ -7,6 +7,7 @@
     "discordbot",
     "teams",
     "webex",
+    "webexbot",
     "telegrambot",
     "whatsapp",
     "whatsappbot",

package/docs/content/docs/sdk/webexbot.mdx

@@ -0,0 +1,340 @@
+---
+title: Webex Bot
+description: TypeScript SDK reference for Webex Bot — client, real-time Mercury WebSocket listener, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import { WebexBotClient, WebexBotCredentialManager, WebexBotListener } from 'agent-messenger/webexbot'
+```
+
+## WebexBotClient
+
+The main client for interacting with the Webex REST API using a bot token. Delegates to the same underlying HTTP layer as `WebexClient`, with automatic rate-limit handling and exponential backoff on server errors.
+
+Bot tokens never expire, so no refresh logic is needed.
+
+```typescript
+const client = await new WebexBotClient().login({ token: 'YOUR_BOT_TOKEN' })
+```
+
+Or use stored credentials — read from `~/.config/agent-messenger/webexbot-credentials.json` (managed by `agent-webexbot auth set`):
+
+```typescript
+const client = await new WebexBotClient().login()
+```
+
+### Authentication
+
+```typescript
+// Verify credentials and get bot identity
+const me = await client.testAuth()
+// → WebexPerson { id, displayName, emails, orgId, type }
+```
+
+### Spaces
+
+```typescript
+// List spaces the bot is a member of (default limit: 50)
+const spaces = await client.listSpaces()
+const grouped = await client.listSpaces({ type: 'group', max: 20 })
+// → WebexSpace[]
+
+// Get a specific space by ID
+const space = await client.getSpace(spaceId)
+// → WebexSpace { id, title, type, isLocked, lastActivity, created, creatorId }
+```
+
+### Messages
+
+```typescript
+// Send a message to a space
+const msg = await client.sendMessage(roomId, 'Hello world')
+// → WebexMessage { id, roomId, roomType, text, personId, personEmail, created }
+
+// Send a markdown message
+await client.sendMessage(roomId, '**Bold** and _italic_', { markdown: true })
+
+// Send a direct message by email
+const dm = await client.sendDirectMessage('alice@example.com', 'Hey!')
+await client.sendDirectMessage('alice@example.com', '**Important**', { markdown: true })
+
+// List messages in a space (default limit: 50)
+const messages = await client.listMessages(roomId)
+const limited = await client.listMessages(roomId, { max: 25 })
+// → WebexMessage[]
+
+// Get a single message by ID
+const message = await client.getMessage(messageId)
+// → WebexMessage
+
+// Edit a message (bot's own messages only)
+const updated = await client.editMessage(messageId, roomId, 'Updated text')
+await client.editMessage(messageId, roomId, '**Updated**', { markdown: true })
+// → WebexMessage
+
+// Delete a message
+await client.deleteMessage(messageId)
+```
+
+### Memberships
+
+```typescript
+// List members of a space
+const members = await client.listMemberships(roomId)
+const limited = await client.listMemberships(roomId, { max: 100 })
+// → WebexMembership[]
+
+// List all spaces the bot belongs to
+const mySpaces = await client.listMyMemberships()
+// → WebexMembership[]
+```
+
+### People
+
+```typescript
+// Search people by email or display name
+const people = await client.listPeople({ email: 'alice@example.com' })
+const byName = await client.listPeople({ displayName: 'Alice', max: 10 })
+// → WebexPerson[]
+```
+
+## WebexBotListener
+
+A real-time event listener using the Mercury WebSocket protocol. No public URL required — works behind firewalls and in CI/CD environments. Analogous to Slack Socket Mode or Discord Gateway.
+
+Under the hood, the listener uses `webex-message-handler` which handles WDM device registration, Mercury WebSocket connection, KMS key decryption, and auto-reconnect with exponential backoff. The bot's Webex cluster is auto-discovered from the U2C catalog at startup, so the listener works regardless of the org's home region.
+
+The bot's own messages are filtered by default (`ignoreSelfMessages` defaults to `true`), preventing echo loops.
+
+```typescript
+import { WebexBotClient, WebexBotListener } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login({ token: 'YOUR_BOT_TOKEN' })
+const listener = new WebexBotListener(client)
+
+listener.on('connected', ({ connected, status }) => {
+  console.log(`Connected (${connected}, state: ${status.status})`)
+})
+
+listener.on('message_created', (event) => {
+  console.log(`New message in ${event.roomId}: ${event.text}`)
+})
+
+listener.on('membership_created', (event) => {
+  console.log(`Bot added to space: ${event.roomId}`)
+})
+
+listener.on('disconnected', (reason) => {
+  console.log(`Disconnected: ${reason} — will reconnect`)
+})
+
+listener.on('error', (error) => {
+  console.error('Fatal error:', error)
+})
+
+await listener.start()
+```
+
+### Constructor Options
+
+```typescript
+const listener = new WebexBotListener(client, {
+  ignoreSelfMessages: true, // Filter bot's own messages (default: true)
+  pingInterval: 15000, // WebSocket ping interval in ms
+  pongTimeout: 5000, // Pong response timeout in ms
+  reconnectBackoffMax: 30000, // Max reconnect delay in ms
+  maxReconnectAttempts: 10, // Max reconnect attempts before giving up
+})
+```
+
+### Lifecycle
+
+- `start()` — Registers a WDM device, opens the Mercury WebSocket, and begins streaming events.
+- `stop()` — Closes the WebSocket and cleans up listeners. Safe to call multiple times.
+
+### Events
+
+| Event                | Payload                  | Notes                                                  |
+| -------------------- | ------------------------ | ------------------------------------------------------ |
+| `message_created`    | `DecryptedMessage`       | New message in a space the bot is in                   |
+| `message_updated`    | `DecryptedMessage`       | Existing message edited                                |
+| `message_deleted`    | `DeletedMessage`         | Message deleted                                        |
+| `membership_created` | `MembershipActivity`     | Bot added to a new space                               |
+| `attachment_action`  | `AttachmentAction`       | Adaptive card button clicked                           |
+| `room_created`       | `RoomActivity`           | New space created                                      |
+| `room_updated`       | `RoomActivity`           | Space details changed                                  |
+| `webex_event`        | (any of the above)       | Catch-all — every content event                        |
+| `connected`          | `{ connected, status }`  | Once after `start()` succeeds                          |
+| `reconnecting`       | `number` (attempt count) | Reconnect attempt in progress                          |
+| `disconnected`       | `string` (reason)        | Connection dropped; listener will auto-reconnect       |
+| `error`              | `Error`                  | Fatal error (max reconnects exceeded). Listener stops. |
+
+### Reconnection
+
+On transient failures (network drops, 5xx), the listener emits `disconnected` and retries with exponential backoff up to `reconnectBackoffMax`. After `maxReconnectAttempts` consecutive failures, it emits `error` and stops.
+
+## WebexBotCredentialManager
+
+```typescript
+const manager = new WebexBotCredentialManager()
+
+// Store credentials (sets this bot as current)
+await manager.setCredentials({ token, bot_id: 'deploy', bot_name: 'Deploy Bot' })
+
+// Retrieve current bot credentials
+const creds = await manager.getCredentials()
+// → { token, bot_id, bot_name } | null
+
+// Retrieve a specific bot
+const creds = await manager.getCredentials('deploy')
+
+// Multi-bot support
+const all = await manager.listAll()
+// → Array<{ bot_id, bot_name, is_current }>
+
+await manager.setCurrent('deploy')
+await manager.removeBot('alert')
+await manager.clearCredentials()
+```
+
+Credentials are stored under `~/.config/agent-messenger/webexbot-credentials.json` with `0600` file permissions. Override the directory with the `AGENT_MESSENGER_CONFIG_DIR` environment variable, or pass `new WebexBotCredentialManager(customDir)`.
+
+## Types
+
+```typescript
+import type {
+  WebexSpace,
+  WebexMessage,
+  WebexPerson,
+  WebexMembership,
+  WebexBotConfig,
+  WebexBotCredentials,
+  WebexBotListenerOptions,
+  WebexBotListenerEventMap,
+} from 'agent-messenger/webexbot'
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported:
+
+```typescript
+import {
+  WebexSpaceSchema,
+  WebexMessageSchema,
+  WebexPersonSchema,
+  WebexMembershipSchema,
+  WebexBotConfigSchema,
+  WebexBotCredentialsSchema,
+} from 'agent-messenger/webexbot'
+```
+
+## Real-time Events (Webex Bot)
+
+Stream messages and membership events over the Mercury WebSocket — no public HTTP endpoint required.
+
+```typescript
+import { WebexBotClient, WebexBotListener } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login({ token: 'YOUR_BOT_TOKEN' })
+const listener = new WebexBotListener(client)
+
+listener.on('message_created', (event) => {
+  console.log(`New message in ${event.roomId}: ${event.text}`)
+})
+
+listener.on('membership_created', (event) => {
+  console.log(`Bot added to space: ${event.roomId}`)
+})
+
+await listener.start()
+```
+
+## Examples
+
+### Deploy Notifier
+
+Post a deployment message, then update it when done.
+
+```typescript
+import { WebexBotClient } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login()
+
+// Post initial status
+const msg = await client.sendMessage(spaceId, 'Deploying v2.1.0 to production...')
+
+// Stream progress
+await client.sendMessage(spaceId, 'Building application...')
+await client.sendMessage(spaceId, 'Running tests (142 passed)...')
+await client.sendMessage(spaceId, 'Rolling out to 3 regions...')
+
+// Update original message with final status
+await client.editMessage(msg.id, spaceId, 'Deployed v2.1.0 to production')
+```
+
+### Reactive Bot
+
+Listen for messages and respond to keywords.
+
+```typescript
+import { WebexBotClient, WebexBotListener } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login({ token: 'YOUR_BOT_TOKEN' })
+const listener = new WebexBotListener(client)
+
+listener.on('message_created', async (event) => {
+  const text = event.text?.toLowerCase() ?? ''
+
+  if (text.includes('status')) {
+    await client.sendMessage(event.roomId, 'All systems operational.')
+  }
+
+  if (text.includes('help')) {
+    await client.sendMessage(event.roomId, 'Available commands: `status`, `help`')
+  }
+})
+
+await listener.start()
+```
+
+### Multi-Space Broadcast
+
+Send a message to every space the bot is in.
+
+```typescript
+import { WebexBotClient } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login()
+
+const spaces = await client.listSpaces({ type: 'group' })
+
+for (const space of spaces) {
+  await client.sendMessage(space.id, 'Maintenance window starts in 30 minutes.')
+  // Respect rate limits
+  await new Promise((r) => setTimeout(r, 200))
+}
+```
+
+### Direct Message Pipeline
+
+Send a DM to multiple people by email.
+
+```typescript
+import { WebexBotClient } from 'agent-messenger/webexbot'
+
+const client = await new WebexBotClient().login()
+
+const recipients = ['alice@example.com', 'bob@example.com', 'carol@example.com']
+
+for (const email of recipients) {
+  await client.sendDirectMessage(email, 'Reminder: standup in 5 minutes')
+  await new Promise((r) => setTimeout(r, 200))
+}
+```