agent-messenger 1.14.0 → 2.0.0

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,137 @@
+---
+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 9 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.
+
+![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 9 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
+│   ├── 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
+```