agent-messenger 1.15.0 → 2.1.0

package/docs/content/docs/sdk/whatsapp.mdx

@@ -0,0 +1,293 @@
+---
+title: WhatsApp
+description: TypeScript SDK reference for WhatsApp — client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  WhatsAppClient,
+  WhatsAppCredentialManager,
+} from 'agent-messenger/whatsapp'
+```
+
+## WhatsAppClient
+
+The main client for interacting with WhatsApp via the Baileys library. WhatsApp uses a linked-device model: your application pairs with an existing WhatsApp account and maintains a persistent WebSocket connection. Call `close()` when done.
+
+The connection lifecycle has two steps: `login()` sets up credentials, then `connect()` opens the WebSocket. Both are required before calling any chat or message methods.
+
+### Authentication
+
+```typescript
+import { WhatsAppClient } from 'agent-messenger/whatsapp'
+
+// Explicit credentials — point to a Baileys auth directory
+const client = await new WhatsAppClient().login({ authDir: '/path/to/auth' })
+```
+
+Or use automatic credential extraction, which reads from stored login state managed by `WhatsAppCredentialManager`:
+
+```typescript
+import { WhatsAppClient } from 'agent-messenger/whatsapp'
+
+const client = await new WhatsAppClient().login()
+```
+
+### Connection
+
+After `login()`, call `connect()` to open the WebSocket and sync chat history. This must complete before calling any API methods.
+
+```typescript
+await client.connect()
+// Connection is now open — you can call listChats, sendMessage, etc.
+```
+
+For first-time device pairing, use `connectForPairing()` instead. It returns a pairing code to enter on your phone, plus a promise that resolves when authentication finishes.
+
+```typescript
+const { code, waitForAuth } = await client.connectForPairing('+1234567890')
+console.log(`Enter this code on your phone: ${code}`)
+await waitForAuth()
+// Device is now linked
+```
+
+### Chat Rooms
+
+WhatsApp identifies chats by JID (Jabber ID). Individuals use `phone@s.whatsapp.net`, groups use `id@g.us`.
+
+```typescript
+// List recent chats (sorted by last activity)
+const chats = await client.listChats()
+// → WhatsAppChatSummary[]
+
+// Limit results
+const recent = await client.listChats(10)
+
+// Search chats by name or JID
+const results = await client.searchChats('Team', 5)
+// → WhatsAppChatSummary[]
+```
+
+### Messages
+
+```typescript
+// Get recent messages from a chat (default: 25)
+const messages = await client.getMessages('5511999999999@s.whatsapp.net')
+// → WhatsAppMessageSummary[]
+
+// Get more messages
+const more = await client.getMessages('5511999999999@s.whatsapp.net', 100)
+
+// Phone numbers without @s.whatsapp.net are resolved automatically
+const msgs = await client.getMessages('5511999999999')
+```
+
+### Sending
+
+```typescript
+// Send a text message
+const sent = await client.sendMessage('5511999999999@s.whatsapp.net', 'Hello from SDK!')
+// → WhatsAppMessageSummary { id, chat_id, from, timestamp, is_outgoing, type, text }
+```
+
+### Reactions
+
+```typescript
+// React to a message
+await client.sendReaction('5511999999999@s.whatsapp.net', 'ABCDEF1234', '👍')
+
+// React to your own message
+await client.sendReaction('5511999999999@s.whatsapp.net', 'ABCDEF1234', '✅', true)
+
+// Remove a reaction (empty string)
+await client.sendReaction('5511999999999@s.whatsapp.net', 'ABCDEF1234', '')
+```
+
+### Socket Access
+
+For advanced Baileys operations not covered by the client API, access the raw socket directly.
+
+```typescript
+const sock = client.getSocket()
+// → WASocket | null
+```
+
+### Cleanup
+
+```typescript
+// Close the connection and persist store (MUST call when done)
+await client.close()
+```
+
+Once closed, any subsequent method call throws a `WhatsAppError` with code `not_connected`. Create a new client if you need to reconnect.
+
+## WhatsAppCredentialManager
+
+Manages WhatsApp credentials stored at `~/.config/agent-messenger/whatsapp-credentials.json`. Baileys auth state is stored per-account under `~/.config/agent-messenger/whatsapp/<account-id>/auth/`. Files are written with `0o600` permissions.
+
+```typescript
+import { WhatsAppCredentialManager } from 'agent-messenger/whatsapp'
+
+const manager = new WhatsAppCredentialManager()
+```
+
+```typescript
+// Load full config from disk (returns defaults if file doesn't exist)
+const config = await manager.loadConfig()
+// → WhatsAppConfig { current, accounts }
+
+// Save full config to disk
+await manager.saveConfig(config)
+
+// Get the current account
+const account = await manager.getAccount()
+// → WhatsAppAccount | null
+
+// Get a specific account by ID
+const specific = await manager.getAccount('plus-1234567890')
+// → WhatsAppAccount | null
+
+// List all accounts
+const accounts = await manager.listAccounts()
+// → Array<WhatsAppAccount & { is_current: boolean }>
+
+// Store an account
+await manager.setAccount(account)
+
+// Switch the current account
+const switched = await manager.setCurrent('plus-1234567890')
+// → boolean (false if account not found)
+
+// Remove an account (also deletes auth state on disk)
+const removed = await manager.removeAccount('plus-1234567890')
+// → boolean (false if account not found)
+
+// Delete all credentials and auth state
+await manager.clearCredentials()
+
+// Get filesystem paths for an account
+const paths = manager.getAccountPaths('plus-1234567890')
+// → WhatsAppAccountPaths { account_dir, auth_dir }
+
+// Get paths, creating directories if they don't exist
+const ensured = await manager.ensureAccountPaths('plus-1234567890')
+// → WhatsAppAccountPaths { account_dir, auth_dir }
+```
+
+## Types
+
+```typescript
+import type {
+  WhatsAppAccount,
+  WhatsAppAccountPaths,
+  WhatsAppChatSummary,
+  WhatsAppConfig,
+  WhatsAppMessageSummary,
+} from 'agent-messenger/whatsapp'
+```
+
+## Exported Utilities
+
+```typescript
+import {
+  createAccountId,
+  extractMessageText,
+  getMessageType,
+  jidToType,
+  WhatsAppError,
+} from 'agent-messenger/whatsapp'
+```
+
+| Export | Description |
+|--------|-------------|
+| `createAccountId(input)` | Normalizes a phone number or string into a safe account ID |
+| `extractMessageText(message)` | Pulls the text content from a Baileys `proto.IMessage` |
+| `getMessageType(message)` | Returns the message type (`text`, `image`, `video`, etc.) from a Baileys `proto.IMessage` |
+| `jidToType(jid)` | Maps a JID to its chat type: `individual`, `group`, `broadcast`, or `status` |
+| `WhatsAppError` | Error class with a `code` property for programmatic error handling |
+
+## Examples
+
+### Chat Summary
+
+List all chats, count unread, and print a summary.
+
+```typescript
+import { WhatsAppClient } from 'agent-messenger/whatsapp'
+
+const client = await new WhatsAppClient().login()
+await client.connect()
+
+try {
+  const chats = await client.listChats()
+  const unread = chats.filter(c => c.unread_count > 0)
+  console.log(`${unread.length} chats with unread messages:`)
+  for (const chat of unread) {
+    console.log(`  ${chat.name} (${chat.type}) — ${chat.unread_count} unread`)
+  }
+} finally {
+  await client.close()
+}
+```
+
+### Send Notification
+
+Find a chat by name and send a message.
+
+```typescript
+import { WhatsAppClient } from 'agent-messenger/whatsapp'
+
+const client = await new WhatsAppClient().login()
+await client.connect()
+
+try {
+  const chats = await client.searchChats('Team')
+  const teamChat = chats[0]
+
+  if (teamChat) {
+    const result = await client.sendMessage(teamChat.id, '🚀 Deployment complete!')
+    console.log(`Sent (id: ${result.id}, timestamp: ${result.timestamp})`)
+  }
+} finally {
+  await client.close()
+}
+```
+
+### Message Monitor
+
+Poll for new messages in a chat.
+
+```typescript
+import { WhatsAppClient } from 'agent-messenger/whatsapp'
+
+const client = await new WhatsAppClient().login()
+await client.connect()
+
+const chatJid = '5511999999999@s.whatsapp.net'
+let knownIds = new Set<string>()
+
+const poll = async () => {
+  try {
+    const messages = await client.getMessages(chatJid, 10)
+    for (const msg of messages) {
+      if (!knownIds.has(msg.id)) {
+        knownIds.add(msg.id)
+        const sender = msg.from_name ?? msg.from
+        console.log(`[${sender}] ${msg.text ?? `(${msg.type})`}`)
+      }
+    }
+  } catch (error) {
+    console.error('Poll failed:', error)
+  }
+}
+
+const timer = setInterval(poll, 10_000)
+
+// To stop: clearInterval(timer); await client.close()
+```

package/docs/content/docs/sdk/whatsappbot.mdx

@@ -0,0 +1,266 @@
+---
+title: WhatsApp Bot
+description: TypeScript SDK reference for WhatsApp Bot — Cloud API client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  WhatsAppBotClient,
+  WhatsAppBotCredentialManager,
+  WhatsAppBotError,
+} from 'agent-messenger/whatsappbot'
+```
+
+## WhatsAppBotClient
+
+The main client for interacting with the WhatsApp Business Cloud API (Meta Graph API v23.0) programmatically. All requests are stateless HTTP calls. The client handles rate-limiting automatically, reading the `x-business-use-case-usage` header and waiting on `429` responses. Network errors and `5xx` responses are retried with exponential backoff for `GET` requests.
+
+```typescript
+import { WhatsAppBotClient } from 'agent-messenger/whatsappbot'
+
+const client = await new WhatsAppBotClient().login({ phoneNumberId, accessToken })
+```
+
+Or use automatic credential extraction, where credentials are read from stored config:
+
+```typescript
+import { WhatsAppBotClient } from 'agent-messenger/whatsappbot'
+
+const client = await new WhatsAppBotClient().login()
+```
+
+### Verification
+
+```typescript
+// Verify the phone number's registered name
+const info = await client.verifyToken()
+// → { verified_name: string }
+```
+
+### Messages
+
+Phone numbers should be in E.164 format without the `+` prefix (e.g., `12025551234`).
+
+```typescript
+// Send a text message
+const msg = await client.sendTextMessage('12025551234', 'Hello from the bot!')
+const withPreview = await client.sendTextMessage('12025551234', 'Check https://example.com', true)
+// → WhatsAppBotMessageResponse
+
+// Send a template message
+const tmpl = await client.sendTemplateMessage('12025551234', 'hello_world', 'en_US')
+const withComponents = await client.sendTemplateMessage('12025551234', 'order_update', 'en_US', [
+  { type: 'body', parameters: [{ type: 'text', text: 'ORD-1234' }] },
+])
+// → WhatsAppBotMessageResponse
+
+// React to a message
+const reaction = await client.sendReaction('12025551234', 'wamid.abc123', '\u{1F44D}')
+// → WhatsAppBotMessageResponse
+
+// Send an image message
+const image = await client.sendImageMessage('12025551234', 'https://example.com/photo.jpg')
+const captioned = await client.sendImageMessage(
+  '12025551234',
+  'https://example.com/photo.jpg',
+  'Product screenshot',
+)
+// → WhatsAppBotMessageResponse
+
+// Send a document message
+const doc = await client.sendDocumentMessage(
+  '12025551234',
+  'https://example.com/invoice.pdf',
+  'invoice-2024.pdf',
+  'Your invoice is attached',
+)
+// → WhatsAppBotMessageResponse
+```
+
+### Templates
+
+```typescript
+// List message templates (optional limit)
+const templates = await client.listTemplates()
+const limited = await client.listTemplates({ limit: 10 })
+// → WhatsAppBotTemplate[]
+
+// Get a specific template by name
+const template = await client.getTemplate('hello_world')
+// → WhatsAppBotTemplate { name, status, category, language, components }
+```
+
+## WhatsAppBotCredentialManager
+
+Manages WhatsApp Bot credentials stored at `~/.config/agent-messenger/whatsappbot-credentials.json`. Files are written with `0o600` permissions. The environment variables `E2E_WHATSAPPBOT_ACCESS_TOKEN` and `E2E_WHATSAPPBOT_PHONE_NUMBER_ID` take precedence when calling `getCredentials()` without an `accountId`.
+
+```typescript
+import { WhatsAppBotCredentialManager } from 'agent-messenger/whatsappbot'
+
+const manager = new WhatsAppBotCredentialManager()
+// Custom path: new WhatsAppBotCredentialManager('/custom/config/dir')
+```
+
+```typescript
+// Load full config from disk (returns defaults if file doesn't exist)
+const config = await manager.load()
+// → WhatsAppBotConfig
+
+// Save full config to disk
+await manager.save(config)
+
+// Get credentials for an account (env vars take precedence)
+const creds = await manager.getCredentials()
+const specific = await manager.getCredentials(accountId)
+// → WhatsAppBotCredentials | null
+
+// Store credentials for an account
+await manager.setCredentials({
+  phone_number_id: '100200300400',
+  account_name: 'My Business',
+  access_token: 'EAAx...',
+})
+
+// Remove an account's credentials
+const removed = await manager.removeAccount('100200300400')
+// → boolean
+
+// Set the current default account
+const ok = await manager.setCurrent('100200300400')
+// → boolean
+
+// List all saved accounts with current marker
+const all = await manager.listAll()
+// → Array<WhatsAppBotAccountEntry & { is_current: boolean }>
+
+// Clear all stored credentials
+await manager.clearCredentials()
+```
+
+## Types
+
+```typescript
+import type {
+  WhatsAppBotAccountEntry,
+  WhatsAppBotConfig,
+  WhatsAppBotCredentials,
+  WhatsAppBotMessageResponse,
+  WhatsAppBotTemplate,
+  WhatsAppBotTemplateComponent,
+} from 'agent-messenger/whatsappbot'
+```
+
+## WhatsAppBotError
+
+Thrown on authentication failures, network errors, rate limits, and API errors. Includes a `code` string for programmatic handling.
+
+```typescript
+import { WhatsAppBotError } from 'agent-messenger/whatsappbot'
+
+try {
+  await client.sendTextMessage('12025551234', 'Hello')
+} catch (error) {
+  if (error instanceof WhatsAppBotError) {
+    console.error(`${error.code}: ${error.message}`)
+    // e.g. "rate_limited: Rate limited"
+    // e.g. "not_authenticated: Not authenticated. Call .login() first."
+  }
+}
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported for parsing API responses:
+
+```typescript
+import {
+  WhatsAppBotAccountEntrySchema,
+  WhatsAppBotConfigSchema,
+  WhatsAppBotCredentialsSchema,
+} from 'agent-messenger/whatsappbot'
+```
+
+## Examples
+
+### Send Text Message
+
+Send a simple text message to a phone number.
+
+```typescript
+import { WhatsAppBotClient } from 'agent-messenger/whatsappbot'
+
+const client = await new WhatsAppBotClient().login({ phoneNumberId, accessToken })
+
+const response = await client.sendTextMessage('12025551234', 'Your order has shipped!')
+console.log(`Message ID: ${response.messages[0].id}`)
+console.log(`WhatsApp ID: ${response.contacts[0].wa_id}`)
+```
+
+### Template Broadcast
+
+Send a template message with dynamic components to multiple recipients.
+
+```typescript
+import { WhatsAppBotClient } from 'agent-messenger/whatsappbot'
+
+const client = await new WhatsAppBotClient().login({ phoneNumberId, accessToken })
+
+const recipients = ['12025551234', '447700900123', '5511999887766']
+
+for (const phone of recipients) {
+  const response = await client.sendTemplateMessage(phone, 'order_update', 'en_US', [
+    {
+      type: 'body',
+      parameters: [
+        { type: 'text', text: 'ORD-5678' },
+        { type: 'text', text: 'March 30, 2026' },
+      ],
+    },
+  ])
+  console.log(`Sent to ${phone}: ${response.messages[0].id}`)
+}
+```
+
+### Multi-Account Management
+
+Set up and switch between multiple WhatsApp Business accounts.
+
+```typescript
+import { WhatsAppBotCredentialManager, WhatsAppBotClient } from 'agent-messenger/whatsappbot'
+
+const manager = new WhatsAppBotCredentialManager()
+
+// Store credentials for two accounts
+await manager.setCredentials({
+  phone_number_id: '100200300400',
+  account_name: 'Support Line',
+  access_token: 'EAAx...',
+})
+
+await manager.setCredentials({
+  phone_number_id: '500600700800',
+  account_name: 'Marketing Line',
+  access_token: 'EAAy...',
+})
+
+// List all accounts
+const accounts = await manager.listAll()
+for (const acct of accounts) {
+  const marker = acct.is_current ? '(current)' : ''
+  console.log(`${acct.account_name} [${acct.phone_number_id}] ${marker}`)
+}
+
+// Switch to the support account
+await manager.setCurrent('100200300400')
+
+// Login picks up the current account automatically
+const client = await new WhatsAppBotClient().login()
+const info = await client.verifyToken()
+console.log(`Logged in as: ${info.verified_name}`)
+```

package/docs/content/docs/tui.mdx

@@ -0,0 +1,138 @@
+---
+title: TUI (Terminal UI)
+description: A unified terminal interface for all your messaging platforms in one screen.
+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 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, Webex, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk — all from your terminal.
+
+![Agent Messenger TUI](/tui.png)
+
+## Launch
+
+```bash
+agent-messenger tui
+```
+
+On startup, the TUI attempts to log in to all platforms simultaneously using your stored credentials. Platforms that authenticate successfully appear as available; the rest show as "(offline)" and can be authenticated interactively.
+
+If only one platform succeeds, it auto-selects and jumps straight to the channel list.
+
+## Navigation
+
+The TUI has three navigation levels and three input modes.
+
+### Navigation Levels
+
+| Level | What it shows | How to enter |
+| --- | --- | --- |
+| **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 |
+
+### Input Modes
+
+| Mode | Focus | What you can do |
+| --- | --- | --- |
+| **Selection** | Sidebar | Navigate platforms, workspaces, and channels |
+| **Read** | Message log | Scroll through messages, switch to write mode |
+| **Write** | Input box | Type and send messages |
+
+## Keybindings
+
+| Key | Context | Action |
+| --- | --- | --- |
+| `↑` `↓` | Sidebar | Navigate items |
+| `Enter` / `→` | Sidebar | Drill into selected item |
+| `←` / `Esc` | Sidebar | Go back one level |
+| `Enter` | Read mode | Switch to write mode |
+| `Esc` | Read mode | Switch to selection mode |
+| `Enter` | Write mode | Send message |
+| `Esc` / `Tab` | Write mode | Switch to read mode |
+| `Tab` / `Shift+Tab` | Read/Write | Toggle between read and write |
+| `Ctrl+K` | Any (non-auth) | Fuzzy channel picker |
+| `Ctrl+W` | Read/Write | Fuzzy workspace picker |
+| `Ctrl+C` | Any | Quit |
+
+## Features
+
+### Multi-Platform Login
+
+All platforms authenticate in parallel on startup. The TUI reuses credentials already stored by each platform's CLI (e.g., `agent-slack auth extract`). Platforms that haven't been set up appear as "(offline)" — select them to trigger an interactive auth flow right in the TUI.
+
+### Real-Time Messages
+
+For platforms with listener support (Slack and Discord), new messages appear in real time. The listener starts automatically when you open a channel.
+
+### Fuzzy Pickers
+
+Press `Ctrl+K` to open the channel picker or `Ctrl+W` for the workspace picker. Both support fuzzy matching — just start typing to filter.
+
+### Interactive Auth
+
+If a platform isn't authenticated, selecting it in the sidebar starts an interactive auth flow. The TUI prompts for any required input (phone numbers, pairing codes, etc.) directly in the message pane.
+
+## Architecture
+
+The TUI demonstrates the adapter pattern at the core of Agent Messenger:
+
+```
+┌─────────────┐
+│   TUI App   │  blessed screen, views, key bindings
+├─────────────┤
+│  Adapters   │  PlatformAdapter interface (one per platform)
+├─────────────┤
+│  SDK Layer  │  SlackClient, DiscordClient, TeamsClient, ...
+└─────────────┘
+```
+
+Each platform implements the `PlatformAdapter` interface:
+
+```typescript
+interface PlatformAdapter {
+  readonly name: string
+  login(): Promise<void>
+  getChannels(): Promise<UnifiedChannel[]>
+  getMessages(channelId: string, limit?: number): Promise<UnifiedMessage[]>
+  sendMessage(channelId: string, text: string): Promise<void>
+  startListening?(onMessage: (msg: UnifiedMessage) => void): Promise<void>
+  stopListening?(): void
+  getWorkspaces?(): Promise<Workspace[]>
+  switchWorkspace?(workspaceId: string): Promise<void>
+  getCurrentWorkspace?(): Workspace | null
+  getAuthHint(): AuthHint
+  authenticate(io: AuthIO): Promise<void>
+}
+```
+
+This means adding a new platform to the TUI is just implementing one adapter — the same SDK clients that power each CLI also power the TUI.
+
+## Source
+
+The TUI source lives in [`src/tui/`](https://github.com/devxoul/agent-messenger/tree/main/src/tui):
+
+```
+src/tui/
+├── app.ts                          # Main app (screen, layout, modes)
+├── cli.ts                          # CLI entry point
+├── utils.ts                        # Timestamp formatting, fuzzy match, etc.
+├── adapters/
+│   ├── types.ts                    # PlatformAdapter interface
+│   ├── slack-adapter.ts
+│   ├── discord-adapter.ts
+│   ├── teams-adapter.ts
+│   ├── webex-adapter.ts
+│   ├── telegram-adapter.ts
+│   ├── whatsapp-adapter.ts
+│   ├── line-adapter.ts
+│   ├── instagram-adapter.ts
+│   ├── kakaotalk-adapter.ts
+│   └── channeltalk-adapter.ts
+└── views/
+    ├── channel-picker.ts           # Ctrl+K fuzzy channel search
+    └── workspace-picker.ts         # Ctrl+W fuzzy workspace search
+```