agent-messenger 1.15.0 → 2.1.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/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))
+}
+```