agent-messenger 1.14.0 → 2.0.0

package/docs/content/docs/sdk/teams.mdx

@@ -0,0 +1,350 @@
+---
+title: Teams
+description: TypeScript SDK reference for Microsoft Teams — client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  TeamsClient,
+  TeamsCredentialManager,
+  TeamsError,
+} from 'agent-messenger/teams'
+```
+
+## TeamsClient
+
+The main client for interacting with Microsoft Teams' API programmatically. All API methods include automatic rate-limit handling with per-bucket tracking and exponential backoff on server errors.
+
+Teams tokens expire in 60-90 minutes. The client checks expiry before each request and throws a `TeamsError` with code `token_expired` when the token is stale. Re-run `agent-teams auth extract` to refresh.
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login({ token })
+// With expiry tracking: await new TeamsClient().login({ token, tokenExpiresAt: '2025-03-23T12:00:00Z' })
+```
+
+Or use automatic credential extraction — credentials are extracted from the desktop app, no manual token needed:
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login()
+```
+
+### Authentication
+
+```typescript
+// Verify credentials and get identity
+const user = await client.testAuth()
+// → TeamsUser { id, displayName }
+```
+
+### Teams
+
+```typescript
+// List all teams the authenticated user belongs to
+const teams = await client.listTeams()
+// → TeamsTeam[]
+
+// Get a specific team by ID
+const team = await client.getTeam(teamId)
+// → TeamsTeam { id, name, description? }
+```
+
+### Channels
+
+```typescript
+// List all channels in a team
+const channels = await client.listChannels(teamId)
+// → TeamsChannel[]
+
+// Get a specific channel by ID
+const channel = await client.getChannel(teamId, channelId)
+// → TeamsChannel { id, team_id, name, type }
+```
+
+Channel IDs use a Teams thread ID format (`19:xxx@thread.tacv2`), not numeric snowflakes. Always pass the parent `teamId` alongside the `channelId`.
+
+### Messages
+
+```typescript
+// Send a message to a channel
+const msg = await client.sendMessage(teamId, channelId, 'Hello world')
+// → TeamsMessage { id, channel_id, author, content, timestamp }
+
+// Get recent messages from a channel (default limit: 50)
+const messages = await client.getMessages(teamId, channelId)
+const limited = await client.getMessages(teamId, channelId, 25)
+// → TeamsMessage[]
+
+// Get a single message by ID
+const message = await client.getMessage(teamId, channelId, messageId)
+// → TeamsMessage
+
+// Delete a message
+await client.deleteMessage(teamId, channelId, messageId)
+```
+
+### Reactions
+
+```typescript
+// Add a reaction to a message
+await client.addReaction(teamId, channelId, messageId, 'like')
+
+// Remove your reaction
+await client.removeReaction(teamId, channelId, messageId, 'like')
+```
+
+### Users
+
+```typescript
+// List all members in a team
+const users = await client.listUsers(teamId)
+// → TeamsUser[]
+
+// Get a specific user by ID
+const user = await client.getUser(userId)
+// → TeamsUser { id, displayName, email?, userPrincipalName? }
+```
+
+### Files
+
+```typescript
+// Upload a file to a channel (by file path)
+const file = await client.uploadFile(teamId, channelId, '/path/to/report.pdf')
+// → TeamsFile { id, name, size, url, contentType? }
+
+// List files in a channel
+const files = await client.listFiles(teamId, channelId)
+// → TeamsFile[]
+```
+
+## TeamsCredentialManager
+
+Manages Teams credentials stored at `~/.config/agent-messenger/teams-credentials.json`. Files are written with `0o600` permissions. Supports multiple accounts (work and personal) with automatic migration from the legacy single-account format.
+
+The static property `TeamsCredentialManager.accountOverride` lets you force a specific account type (`'work'` or `'personal'`) for all operations, overriding the stored `current_account` setting.
+
+```typescript
+import { TeamsCredentialManager } from 'agent-messenger/teams'
+
+const manager = new TeamsCredentialManager()
+// Custom path: new TeamsCredentialManager('/custom/config/dir')
+```
+
+```typescript
+// Load full config from disk (returns null if file doesn't exist)
+const config = await manager.loadConfig()
+// → TeamsConfig | null
+
+// Save full config to disk
+await manager.saveConfig(config)
+
+// Get stored token for the current account
+const token = await manager.getToken()
+// → string | null
+
+// Get token with expiry info
+const tokenInfo = await manager.getTokenWithExpiry()
+// → { token: string; tokenExpiresAt?: string } | null
+
+// Store a token for a specific account type
+await manager.setToken('my-teams-token', 'work', '2025-03-23T12:00:00Z')
+
+// Check if the current account's token has expired
+const expired = await manager.isTokenExpired()
+// → boolean
+
+// Check if a specific account's token has expired
+const workExpired = await manager.isAccountTokenExpired('work')
+// → boolean
+
+// Clear all stored credentials (deletes the file)
+await manager.clearCredentials()
+
+// Get current default team
+const team = await manager.getCurrentTeam()
+// → { team_id: string; team_name: string } | null
+
+// Set the current default team
+await manager.setCurrentTeam('team-uuid', 'Engineering')
+
+// Get the active account type
+const accountType = await manager.getCurrentAccountType()
+// → 'work' | 'personal' | null
+
+// Switch the active account
+await manager.setCurrentAccount('personal')
+
+// Get the full account object for the current account
+const account = await manager.getCurrentAccount()
+// → TeamsAccount | null
+
+// Get all saved accounts
+const accounts = await manager.getAccounts()
+// → Record<string, TeamsAccount>
+
+// Override account selection globally (static property)
+TeamsCredentialManager.accountOverride = 'personal'
+```
+
+## Types
+
+```typescript
+import type {
+  TeamsTeam,
+  TeamsChannel,
+  TeamsMessage,
+  TeamsUser,
+  TeamsReaction,
+  TeamsFile,
+  TeamsCredentials,
+  TeamsAccountType,
+  TeamsAccount,
+  TeamsConfig,
+  TeamsConfigLegacy,
+} from 'agent-messenger/teams'
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported for parsing API responses:
+
+```typescript
+import {
+  TeamsTeamSchema,
+  TeamsChannelSchema,
+  TeamsMessageSchema,
+  TeamsUserSchema,
+  TeamsReactionSchema,
+  TeamsFileSchema,
+  TeamsCredentialsSchema,
+  TeamsAccountTypeSchema,
+  TeamsAccountSchema,
+  TeamsConfigSchema,
+  TeamsConfigLegacySchema,
+} from 'agent-messenger/teams'
+```
+
+## Examples
+
+### Deploy Notifier
+
+Post a deployment message, stream progress, and mark it complete with a reaction.
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login({ token, tokenExpiresAt })
+
+// Post parent message to deploys channel
+const msg = await client.sendMessage(teamId, channelId, '🚀 Deploying v2.1.0 to production...')
+await client.addReaction(teamId, channelId, msg.id, 'like')
+
+// Stream progress with follow-up messages
+await client.sendMessage(teamId, channelId, '• Building application...')
+await client.sendMessage(teamId, channelId, '• Running tests (142 passed)...')
+await client.sendMessage(teamId, channelId, '• Rolling out to 3 regions...')
+
+// Finalize
+await client.removeReaction(teamId, channelId, msg.id, 'like')
+await client.addReaction(teamId, channelId, msg.id, 'heart')
+await client.deleteMessage(teamId, channelId, msg.id)
+await client.sendMessage(teamId, channelId, '✅ v2.1.0 deployed to production')
+```
+
+### Channel Monitor
+
+List channels in a team and pull recent messages from each one.
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login({ token, tokenExpiresAt })
+
+// List all channels in the team
+const channels = await client.listChannels(teamId)
+
+for (const channel of channels) {
+  const messages = await client.getMessages(teamId, channel.id, 5)
+  console.log(`#${channel.name} (${messages.length} recent messages)`)
+
+  for (const msg of messages) {
+    console.log(`  [${msg.author.displayName}] ${msg.content.slice(0, 80)}`)
+  }
+}
+```
+
+### Team Summary
+
+Build a snapshot-style overview of a team: members, channels, and latest activity.
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login({ token, tokenExpiresAt })
+
+// Gather team info
+const team = await client.getTeam(teamId)
+const channels = await client.listChannels(teamId)
+const members = await client.listUsers(teamId)
+
+console.log(`Team: ${team.name}`)
+console.log(`Members: ${members.length}`)
+console.log(`Channels: ${channels.length}`)
+console.log()
+
+// Show latest message per channel
+for (const channel of channels.slice(0, 5)) {
+  const messages = await client.getMessages(teamId, channel.id, 1)
+  const latest = messages[0]
+  if (latest) {
+    console.log(
+      `#${channel.name}: "${latest.content.slice(0, 60)}" — ${latest.author.displayName}`,
+    )
+  } else {
+    console.log(`#${channel.name}: (no messages)`)
+  }
+}
+```
+
+### File Pipeline
+
+Collect files from one channel and re-upload them to an archive channel with a summary.
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login({ token, tokenExpiresAt })
+
+// Get files from the source channel
+const files = await client.listFiles(teamId, sourceChannelId)
+
+for (const file of files.slice(0, 5)) {
+  // Fetch the file content
+  const response = await fetch(file.url)
+  const buffer = Buffer.from(await response.arrayBuffer())
+
+  // Write to a temp file and re-upload to archive channel
+  const tmpPath = `/tmp/${file.name}`
+  const fs = await import('node:fs/promises')
+  await fs.writeFile(tmpPath, buffer)
+  const uploaded = await client.uploadFile(teamId, archiveChannelId, tmpPath)
+
+  await client.sendMessage(
+    teamId,
+    archiveChannelId,
+    [
+      `📎 Archived **${file.name}**`,
+      `Size: ${(file.size / 1024).toFixed(0)} KB · Type: ${file.contentType ?? 'unknown'}`,
+    ].join('\n'),
+  )
+}
+```

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()
+```