agent-messenger 2.0.0 → 2.2.0

package/docs/content/docs/sdk/webex.mdx

@@ -0,0 +1,260 @@
+---
+title: Webex
+description: TypeScript SDK reference for Cisco Webex — client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  WebexClient,
+  WebexCredentialManager,
+  WebexError,
+} from 'agent-messenger/webex'
+```
+
+## WebexClient
+
+The main client for interacting with the Webex REST API programmatically. All API methods include automatic rate-limit handling with per-bucket tracking and exponential backoff on server errors.
+
+OAuth tokens auto-refresh via the stored refresh token. Bot tokens never expire. PATs expire in 12 hours.
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login({ token })
+```
+
+Or use automatic credential extraction — credentials are loaded from stored OAuth/bot tokens, no manual token needed:
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login()
+```
+
+### Authentication
+
+```typescript
+// Verify credentials and get identity
+const me = await client.testAuth()
+// → WebexPerson { id, displayName, emails, orgId, type }
+```
+
+### Spaces
+
+```typescript
+// List all spaces (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
+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)
+```
+
+### People
+
+```typescript
+// List people (search by email or display name)
+const people = await client.listPeople({ email: 'alice@example.com' })
+const byName = await client.listPeople({ displayName: 'Alice', max: 10 })
+// → WebexPerson[]
+```
+
+### Memberships
+
+```typescript
+// List members of a space
+const members = await client.listMemberships(roomId)
+const limited = await client.listMemberships(roomId, { max: 100 })
+// → WebexMembership[]
+```
+
+## WebexCredentialManager
+
+Manages Webex credentials stored at `~/.config/agent-messenger/webex-credentials.json`. Files are written with `0o600` permissions. Supports OAuth Device Grant flow, bot tokens, and PATs.
+
+```typescript
+import { WebexCredentialManager } from 'agent-messenger/webex'
+
+const manager = new WebexCredentialManager()
+// Custom path: new WebexCredentialManager('/custom/config/dir')
+```
+
+```typescript
+// Load config from disk (returns null if file doesn't exist)
+const config = await manager.loadConfig()
+// → WebexConfig | null
+
+// Save config to disk (atomic write)
+await manager.saveConfig(config)
+
+// Get stored access token (auto-refreshes OAuth tokens if expired)
+const token = await manager.getToken()
+// → string | null
+
+// Refresh an OAuth token manually
+const refreshed = await manager.refreshToken(refreshToken, clientId, clientSecret)
+// → WebexConfig | null
+
+// Start OAuth Device Grant flow (request device code)
+const device = await manager.requestDeviceCode(clientId)
+// → { deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval }
+
+// Poll for device token approval
+const tokenConfig = await manager.pollDeviceToken(deviceCode, interval, expiresIn, clientId, clientSecret)
+// → WebexConfig
+
+// Clear all stored credentials (deletes the file)
+await manager.clearCredentials()
+```
+
+## Types
+
+```typescript
+import type {
+  WebexSpace,
+  WebexMessage,
+  WebexPerson,
+  WebexMembership,
+  WebexConfig,
+} from 'agent-messenger/webex'
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported for parsing API responses:
+
+```typescript
+import {
+  WebexSpaceSchema,
+  WebexMessageSchema,
+  WebexPersonSchema,
+  WebexMembershipSchema,
+  WebexConfigSchema,
+} from 'agent-messenger/webex'
+```
+
+## Examples
+
+### Deploy Notifier
+
+Post a deployment message, then update it when done.
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().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')
+```
+
+### Space Monitor
+
+List spaces and pull recent messages from each one.
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login()
+
+const spaces = await client.listSpaces({ type: 'group', max: 10 })
+
+for (const space of spaces) {
+  const messages = await client.listMessages(space.id, { max: 5 })
+  console.log(`${space.title} (${messages.length} recent messages)`)
+
+  for (const msg of messages) {
+    console.log(`  [${msg.personEmail}] ${(msg.text ?? '').slice(0, 80)}`)
+  }
+}
+```
+
+### Workspace Summary
+
+Build a snapshot-style overview: spaces, members, and latest activity.
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login()
+
+const spaces = await client.listSpaces()
+console.log(`Total spaces: ${spaces.length}`)
+
+for (const space of spaces.slice(0, 5)) {
+  const members = await client.listMemberships(space.id)
+  const messages = await client.listMessages(space.id, { max: 1 })
+  const latest = messages[0]
+
+  console.log(`${space.title} (${members.length} members)`)
+  if (latest) {
+    console.log(`  Latest: "${(latest.text ?? '').slice(0, 60)}" — ${latest.personEmail}`)
+  }
+}
+```
+
+### Direct Message Pipeline
+
+Send a DM to multiple people by email.
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().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')
+  // Respect rate limits
+  await new Promise((r) => setTimeout(r, 200))
+}
+```

package/docs/content/docs/tui.mdx

@@ -4,11 +4,11 @@ description: A unified terminal interface for all your messaging platforms in on
 icon: Monitor
 ---
 
-> **Experimental** — The TUI is a showcase of what's possible with Agent Messenger's SDK. It's not intended for production use, but demonstrates the power of having a unified adapter layer across 9 messaging platforms.
+> **Experimental** — The TUI is a showcase of what's possible with Agent Messenger's SDK. It's not intended for production use, but demonstrates the power of having a unified adapter layer across 10 messaging platforms.
 
 ## What Is It?
 
-The TUI (Terminal User Interface) is a `blessed`-based interactive terminal app that unifies all your messaging platforms into a single screen. Navigate between Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk — all from your terminal.
+The TUI (Terminal User Interface) is a `blessed`-based interactive terminal app that unifies all your messaging platforms into a single screen. Navigate between Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk — all from your terminal.
 
 ![Agent Messenger TUI](/tui.png)
 
@@ -30,7 +30,7 @@ The TUI has three navigation levels and three input modes.
 
 | Level | What it shows | How to enter |
 | --- | --- | --- |
-| **Platform** | All 9 platforms with online/offline status | Launch or press `Esc` from workspace level |
+| **Platform** | All 10 platforms with online/offline status | Launch or press `Esc` from workspace level |
 | **Workspace** | Workspaces for the selected platform (skipped if only one) | Select a platform |
 | **Channel** | Channels in the current workspace | Select a workspace |
 
@@ -125,6 +125,7 @@ src/tui/
 │   ├── slack-adapter.ts
 │   ├── discord-adapter.ts
 │   ├── teams-adapter.ts
+│   ├── webex-adapter.ts
 │   ├── telegram-adapter.ts
 │   ├── whatsapp-adapter.ts
 │   ├── line-adapter.ts

package/docs/src/app/page.tsx

@@ -648,8 +648,8 @@ export default function Home() {
 
           {/* Subtitle */}
           <p className="mx-auto mt-6 max-w-2xl text-lg leading-relaxed text-zinc-600 dark:text-zinc-400">
-            One CLI for Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk.
-            Credentials extracted from desktop apps or authenticated in seconds — no API keys, no OAuth, no admin approval.
+            One CLI for Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk.
+            Credentials extracted from desktop apps or authenticated in seconds — no API keys, no admin approval.
           </p>
 
           {/* CTAs with glass treatment in dark mode */}

package/e2e/README.md

@@ -20,14 +20,24 @@ Before running E2E tests, you need:
 
 ## Test Infrastructure
 
-| File                   | Description                                        |
-| ---------------------- | -------------------------------------------------- |
-| `config.ts`            | Hardcoded test workspace/server IDs and validation |
-| `helpers.ts`           | CLI runner, JSON parser, message cleanup utilities |
-| `slack.e2e.test.ts`    | Slack command tests                                |
-| `slackbot.e2e.test.ts` | SlackBot command tests                             |
-| `discord.e2e.test.ts`  | Discord command tests                              |
-| `teams.e2e.test.ts`    | Teams command tests                                |
+| File                      | Description                                        |
+| ------------------------- | -------------------------------------------------- |
+| `config.ts`               | Hardcoded test workspace/server IDs and validation |
+| `helpers.ts`              | CLI runner, JSON parser, message cleanup utilities |
+| `slack.e2e.test.ts`       | Slack command tests                                |
+| `slackbot.e2e.test.ts`    | SlackBot command tests                             |
+| `discord.e2e.test.ts`     | Discord command tests                              |
+| `discordbot.e2e.test.ts`  | DiscordBot command tests                           |
+| `teams.e2e.test.ts`       | Teams command tests                                |
+| `webex.e2e.test.ts`       | Webex command tests                                |
+| `telegram.e2e.test.ts`    | Telegram command tests                             |
+| `whatsapp.e2e.test.ts`    | WhatsApp command tests                             |
+| `whatsappbot.e2e.test.ts` | WhatsApp Bot command tests                         |
+| `line.e2e.test.ts`        | LINE command tests                                 |
+| `instagram.e2e.test.ts`   | Instagram command tests                            |
+| `kakaotalk.e2e.test.ts`   | KakaoTalk command tests                            |
+| `channeltalk.e2e.test.ts` | Channel Talk command tests                         |
+| `channeltalkbot.e2e.test.ts` | Channel Talk Bot command tests                  |
 
 ## Running E2E Tests Locally
 
@@ -211,6 +221,120 @@ When triggering manually, you can select which platform to test:
 
 > ⚠️ Teams tests require `E2E_TEAMS_TEAM_ID` and `E2E_TEAMS_CHANNEL_ID` environment variables. Teams tokens expire in 60-90 minutes.
 
+### DiscordBot Tests
+
+| Command Group | Tests                                            |
+| ------------- | ------------------------------------------------ |
+| `auth`        | status                                           |
+| `message`     | send, list, get, update, delete, thread, replies |
+| `channel`     | list, info                                       |
+| `user`        | list, info                                       |
+| `reaction`    | add, remove                                      |
+| `server`      | list, current                                    |
+
+### Webex Tests
+
+| Command Group | Tests                                        |
+| ------------- | -------------------------------------------- |
+| `auth`        | status                                       |
+| `message`     | send, list, get, delete, edit                |
+| `space`       | list, info                                   |
+| `member`      | list                                         |
+| `snapshot`    | default, --spaces-only, --members-only       |
+
+> ⚠️ Webex tests require `E2E_WEBEX_SPACE_ID`. Optionally set `E2E_WEBEX_DM_EMAIL` for DM tests.
+
+### Telegram Tests
+
+| Command Group | Tests                |
+| ------------- | -------------------- |
+| `auth`        | status, list         |
+| `chat`        | list, search, get    |
+| `message`     | send, list           |
+
+> ⚠️ Telegram tests require `E2E_TELEGRAM_CHAT_ID`.
+
+### WhatsApp Tests
+
+| Command Group | Tests                |
+| ------------- | -------------------- |
+| `auth`        | status, list         |
+| `chat`        | list, search         |
+| `message`     | send, list, react    |
+
+> ⚠️ WhatsApp tests require `E2E_WHATSAPP_CHAT_ID`.
+
+### WhatsApp Bot Tests
+
+| Command Group | Tests                |
+| ------------- | -------------------- |
+| `auth`        | status, list         |
+| `message`     | send                 |
+| `template`    | list, get            |
+
+> ⚠️ WhatsApp Bot tests require `E2E_WHATSAPPBOT_PHONE_NUMBER`.
+
+### LINE Tests
+
+| Command Group | Tests                |
+| ------------- | -------------------- |
+| `auth`        | status, list         |
+| `chat`        | list                 |
+| `friend`      | list                 |
+| `message`     | send, list           |
+| `profile`     | (top-level command)  |
+
+> ⚠️ LINE tests require `E2E_LINE_CHAT_ID`.
+
+### Instagram Tests
+
+| Command Group | Tests                                   |
+| ------------- | --------------------------------------- |
+| `auth`        | status, list                            |
+| `chat`        | list, search                            |
+| `message`     | send, list, send-to\*, search, search-users |
+
+\* `message send-to` requires `E2E_INSTAGRAM_USERNAME` to be set.
+
+> ⚠️ Instagram tests require `E2E_INSTAGRAM_THREAD_ID`. Optionally set `E2E_INSTAGRAM_USERNAME` for send-to tests.
+
+### KakaoTalk Tests
+
+| Command Group | Tests                |
+| ------------- | -------------------- |
+| `auth`        | status, list         |
+| `chat`        | list, list --search  |
+| `message`     | send, list           |
+
+> ⚠️ KakaoTalk tests require `E2E_KAKAOTALK_CHAT_ID`.
+
+### Channel Talk Tests
+
+| Command Group | Tests                             |
+| ------------- | --------------------------------- |
+| `auth`        | status, list                      |
+| `group`       | list, get, messages               |
+| `message`     | send, list, get                   |
+| `chat`        | list                              |
+| `manager`     | list                              |
+| `bot`         | list                              |
+| `snapshot`    | default                           |
+
+> ⚠️ Channel Talk tests require `E2E_CHANNEL_WORKSPACE_ID`.
+
+### Channel Talk Bot Tests
+
+| Command Group | Tests                             |
+| ------------- | --------------------------------- |
+| `auth`        | status                            |
+| `group`       | list, get (by id), get (by @name), messages |
+| `message`     | send, list, get                   |
+| `manager`     | list, get                         |
+| `bot`         | list                              |
+| `snapshot`    | default                           |
+
+> ⚠️ Channel Talk Bot tests require `E2E_CHANNELBOT_WORKSPACE_ID`.
+
 ## Troubleshooting
 
 ### "Wrong workspace" / "Wrong server" Error

package/e2e/channeltalk.e2e.test.ts

@@ -11,14 +11,9 @@ let testGroupName = ''
 
 describe('Channel E2E Tests', () => {
   beforeAll(async () => {
-    if (!CHANNEL_TEST_WORKSPACE_ID) {
-      console.warn(
-        'Skipping Channel E2E: set E2E_CHANNEL_WORKSPACE_ID to run against a dedicated test workspace.',
-      )
-      return
-    }
-
     const group = await validateChannelEnvironment()
+    if (!group) return
+
     testGroupId = group.groupId
     testGroupName = group.groupName
 

package/e2e/channeltalkbot.e2e.test.ts

@@ -13,13 +13,9 @@ let testGroupName = ''
 
 describe('ChannelBot E2E Tests', () => {
   beforeAll(async () => {
-    if (!CHANNELBOT_TEST_WORKSPACE_ID) {
-      console.warn(
-        'Skipping ChannelBot E2E: set E2E_CHANNELBOT_WORKSPACE_ID to run against a dedicated test workspace.',
-      )
-      return
-    }
     const group = await validateChannelBotEnvironment()
+    if (!group) return
+
     testGroupId = group.groupId
     testGroupName = group.groupName
     channelbotAvailable = true