agent-messenger 1.14.0 → 2.0.0

package/docs/content/docs/sdk/instagram.mdx

@@ -0,0 +1,367 @@
+---
+title: Instagram
+description: TypeScript SDK reference for Instagram — client, real-time events, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  InstagramClient,
+  InstagramListener,
+  InstagramError,
+  InstagramCredentialManager,
+} from 'agent-messenger/instagram'
+```
+
+## InstagramClient
+
+The main client for interacting with Instagram DMs via the private mobile API. Authenticates as a mobile device using username and password — no Graph API or OAuth required.
+
+```typescript
+import { InstagramClient } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login({ username: 'alice', password: 's3cret' })
+```
+
+Or use stored credentials from a previous login:
+
+```typescript
+import { InstagramClient } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+```
+
+### Authentication
+
+```typescript
+// Username/password login
+const result = await client.authenticate('alice', 's3cret')
+// → { userId: string, requiresTwoFactor?: boolean, twoFactorInfo?: object, challengeRequired?: boolean, challengePath?: string }
+
+// Two-factor authentication
+const tfResult = await client.twoFactorLogin('alice', '123456', twoFactorIdentifier)
+// → { userId: string }
+
+// Challenge flow (Instagram security verification)
+const sendResult = await client.challengeSendCode(challengePath, 'email')
+// → { contactPoint: string, stepName: string }
+
+const verifyResult = await client.challengeSubmitCode(challengePath, '123456')
+// → { userId: string }
+```
+
+### Chats
+
+```typescript
+// List DM threads (sorted by most recent activity)
+const chats = await client.listChats()
+const chats = await client.listChats(50) // custom limit
+// → InstagramChatSummary[]
+
+// Search threads by name
+const results = await client.searchChats('project')
+const results = await client.searchChats('project', 10) // custom limit
+// → InstagramChatSummary[]
+```
+
+### Messages
+
+```typescript
+// Get messages from a thread (returns chronological order)
+const messages = await client.getMessages('340282366841710300...')
+const messages = await client.getMessages('340282366841710300...', 50) // custom limit
+// → InstagramMessageSummary[]
+
+// Send a text message to a thread
+const msg = await client.sendMessage('340282366841710300...', 'Hello!')
+// → InstagramMessageSummary
+
+// Send a text message to a user by their pk (user ID)
+const msg = await client.sendMessageToUser('12345678', 'Hey there!')
+// → InstagramMessageSummary
+
+// Search messages by text content
+const results = await client.searchMessages('meeting notes')
+const results = await client.searchMessages('hello', { threadId: '340282366841710300...', limit: 10 })
+// → InstagramMessageSummary[]
+```
+
+### Users
+
+```typescript
+// Search Instagram users by username
+const users = await client.searchUsers('alice')
+// → Array<{ pk: string, username: string, fullName: string }>
+```
+
+### Session
+
+```typescript
+// Get the logged-in user's ID
+const userId = client.getUserId()
+// → string | null
+
+// Get pending challenge path (if any)
+const path = client.getChallengePath()
+// → string | undefined
+
+// Load a session from a specific file
+await client.loadSession('/path/to/session.json')
+
+// Set a custom session path
+client.setSessionPath('/path/to/session.json')
+
+// Enable debug logging
+client.setDebugLog((msg) => console.error(`[debug] ${msg}`))
+```
+
+## Real-Time Events
+
+`InstagramListener` polls the Instagram inbox for new messages at a configurable interval.
+
+```typescript
+import { InstagramClient, InstagramListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramListener(client, { pollInterval: 5000 })
+
+listener.on('message', (msg) => {
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('connected', (info) => {
+  console.log(`Listening as ${info.userId}`)
+})
+
+listener.on('error', (err) => console.error(err))
+listener.on('disconnected', () => console.log('Stopped'))
+
+await listener.start()
+// listener.stop() to disconnect
+```
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message` | `InstagramMessageSummary` | New message received |
+| `connected` | `{ userId: string }` | Initial poll completed, listener active |
+| `disconnected` | — | Listener stopped |
+| `error` | `Error` | Network or API error |
+
+The listener seeds its seen-message set on startup, so it only emits `message` events for messages that arrive after `start()`.
+
+## InstagramCredentialManager
+
+Manages Instagram credentials stored at `~/.config/agent-messenger/instagram-credentials.json`. Session files are stored per-account under `~/.config/agent-messenger/instagram/<account-id>/`. Files are written with `0o600` permissions.
+
+```typescript
+import { InstagramCredentialManager } from 'agent-messenger/instagram'
+
+const manager = new InstagramCredentialManager()
+```
+
+```typescript
+// Load full config from disk (returns defaults if file doesn't exist)
+const config = await manager.loadConfig()
+// → InstagramConfig { current, accounts }
+
+// Save full config to disk
+await manager.saveConfig(config)
+
+// Get the current account
+const account = await manager.getAccount()
+// → InstagramAccount | null
+
+// Get a specific account by ID
+const specific = await manager.getAccount('alice')
+// → InstagramAccount | null
+
+// Store account credentials
+await manager.setAccount(account)
+
+// List all accounts (includes is_current flag)
+const accounts = await manager.listAccounts()
+// → Array<InstagramAccount & { is_current: boolean }>
+
+// Switch the current account
+await manager.setCurrent('alice')
+// → boolean (true if found)
+
+// Remove an account and its session data
+await manager.removeAccount('alice')
+// → boolean (true if found)
+
+// Clear all credentials and session data
+await manager.clearCredentials()
+
+// Get paths for an account
+const paths = manager.getAccountPaths('alice')
+// → { account_dir: string, session_path: string }
+
+// Ensure account directories exist
+const paths = await manager.ensureAccountPaths('alice')
+// → { account_dir: string, session_path: string }
+```
+
+## Types
+
+```typescript
+import type {
+  InstagramAccount,
+  InstagramAccountPaths,
+  InstagramChatSummary,
+  InstagramConfig,
+  InstagramMessageSummary,
+  InstagramSessionState,
+  InstagramListenerEventMap,
+} from 'agent-messenger/instagram'
+```
+
+### Key Types
+
+```typescript
+interface InstagramChatSummary {
+  id: string             // Thread ID
+  name: string           // Thread title or participant names
+  type: 'private' | 'group'
+  is_group: boolean
+  participant_count: number
+  unread_count: number
+  last_message?: InstagramMessageSummary
+}
+
+interface InstagramMessageSummary {
+  id: string             // Message item ID
+  thread_id: string
+  from: string           // User pk (numeric ID)
+  from_name?: string
+  timestamp: string      // ISO 8601
+  is_outgoing: boolean
+  type: string           // 'text', 'media', 'reel_share', 'link', 'like', etc.
+  text?: string
+  media_url?: string
+}
+```
+
+### Utility Functions
+
+```typescript
+import {
+  createAccountId,      // Normalize a username to an account ID
+  getMessageType,       // Extract message type from API item
+  extractMessageText,   // Extract text from any message type
+  extractMediaUrl,      // Extract media URL from any message type
+} from 'agent-messenger/instagram'
+```
+
+## Examples
+
+### DM Inbox Summary
+
+List all DM threads and show unread counts.
+
+```typescript
+import { InstagramClient } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+
+const chats = await client.listChats(50)
+const unread = chats.filter(c => c.unread_count > 0)
+
+console.log(`${unread.length} threads with unread messages:`)
+for (const chat of unread) {
+  console.log(`  ${chat.name} (${chat.type}) — ${chat.unread_count} unread`)
+  if (chat.last_message?.text) {
+    console.log(`    Last: ${chat.last_message.text.slice(0, 80)}`)
+  }
+}
+```
+
+### Send a DM by Username
+
+Look up a user and send them a direct message.
+
+```typescript
+import { InstagramClient } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+
+// Find the user
+const users = await client.searchUsers('alice_smith')
+const alice = users.find(u => u.username === 'alice_smith')
+
+if (alice) {
+  const msg = await client.sendMessageToUser(alice.pk, 'Hey! Wanted to follow up on our chat.')
+  console.log(`Sent to thread ${msg.thread_id}`)
+}
+```
+
+### Message Monitor
+
+Watch for new DMs using the real-time listener.
+
+```typescript
+import { InstagramClient, InstagramListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramListener(client, { pollInterval: 10_000 })
+
+listener.on('message', (msg) => {
+  if (msg.is_outgoing) return
+  console.log(`New DM from ${msg.from}: ${msg.text ?? `[${msg.type}]`}`)
+})
+
+listener.on('error', (err) => {
+  console.error('Listener error:', err.message)
+})
+
+await listener.start()
+// Process keeps running until listener.stop() is called
+```
+
+### Search Across Threads
+
+Find messages mentioning a keyword across all conversations.
+
+```typescript
+import { InstagramClient } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+
+const results = await client.searchMessages('meeting tomorrow', { limit: 10 })
+
+for (const msg of results) {
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+  console.log(`  ${msg.timestamp}`)
+}
+```
+
+### Multi-Account
+
+Manage multiple Instagram accounts and switch between them.
+
+```typescript
+import { InstagramClient, InstagramCredentialManager } from 'agent-messenger/instagram'
+
+const manager = new InstagramCredentialManager()
+
+// List all linked accounts
+const accounts = await manager.listAccounts()
+for (const acc of accounts) {
+  console.log(`${acc.username} ${acc.is_current ? '(active)' : ''}`)
+}
+
+// Switch to a specific account
+await manager.setCurrent('work-account')
+
+// Use the new active account
+const client = await new InstagramClient(manager).login()
+const chats = await client.listChats()
+console.log(`${chats.length} threads in work account`)
+```

package/docs/content/docs/sdk/kakaotalk.mdx

@@ -0,0 +1,290 @@
+---
+title: KakaoTalk
+description: TypeScript SDK reference for KakaoTalk — client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  KakaoTalkClient,
+  KakaoCredentialManager,
+} from 'agent-messenger/kakaotalk'
+```
+
+## KakaoTalkClient
+
+The main client for interacting with KakaoTalk via the LOCO protocol. Unlike Discord/Slack which use stateless HTTP, KakaoTalk maintains a persistent TCP connection. Call `close()` when done.
+
+```typescript
+import { KakaoTalkClient } from 'agent-messenger/kakaotalk'
+
+const client = await new KakaoTalkClient().login({ oauthToken, userId, deviceUuid })
+// deviceUuid is optional — defaults to `agent-messenger-${userId}`
+```
+
+Or use automatic credential extraction — credentials are read from stored login state:
+
+```typescript
+import { KakaoTalkClient } from 'agent-messenger/kakaotalk'
+
+const client = await new KakaoTalkClient().login()
+```
+
+### Chat Rooms
+
+```typescript
+// List recent chat rooms (from login snapshot)
+const chats = await client.getChats()
+// → KakaoChat[]
+
+// List ALL chats (paginate beyond login snapshot)
+const allChats = await client.getChats({ all: true })
+
+// Search chats by display name
+const results = await client.getChats({ search: 'Alice' })
+```
+
+### Messages
+
+```typescript
+// Get recent messages from a chat (default: 20)
+const messages = await client.getMessages('9876543210')
+// → KakaoMessage[]
+
+// Get more messages
+const more = await client.getMessages('9876543210', { count: 100 })
+
+// Get messages after a known log ID
+const newer = await client.getMessages('9876543210', { from: '123456789' })
+```
+
+### Sending
+
+```typescript
+// Send a text message
+const result = await client.sendMessage('9876543210', 'Hello from SDK!')
+// → KakaoSendResult { success, status_code, chat_id, log_id, sent_at }
+```
+
+### Cleanup
+
+```typescript
+// Close the LOCO connection (MUST call when done)
+client.close()
+```
+
+Once closed, any subsequent method call throws a `KakaoTalkError` with code `client_closed`. Create a new client if you need to reconnect.
+
+## KakaoTalkListener
+
+Real-time event listener that receives push events from KakaoTalk via the LOCO protocol. Manages its own LOCO session with automatic reconnection.
+
+```typescript
+import { KakaoTalkClient, KakaoTalkListener } from 'agent-messenger/kakaotalk'
+
+const client = await new KakaoTalkClient().login()
+const listener = new KakaoTalkListener(client)
+
+listener.on('connected', (info) => {
+  console.log(`Connected as ${info.userId}`)
+})
+
+listener.on('message', (event) => {
+  console.log(`[${event.chat_id}] ${event.author_id}: ${event.message}`)
+})
+
+listener.on('member_joined', (event) => {
+  console.log(`User ${event.member.user_id} joined ${event.chat_id}`)
+})
+
+listener.on('member_left', (event) => {
+  console.log(`User ${event.member.user_id} left ${event.chat_id}`)
+})
+
+listener.on('read', (event) => {
+  console.log(`User ${event.user_id} read ${event.chat_id} up to ${event.watermark}`)
+})
+
+listener.on('disconnected', () => console.log('Reconnecting...'))
+listener.on('error', (err) => console.error(err))
+
+await listener.start()
+// listener.stop() to disconnect
+```
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message` | `KakaoTalkPushMessageEvent` | New message received |
+| `member_joined` | `KakaoTalkPushMemberEvent` | Member joined a chat |
+| `member_left` | `KakaoTalkPushMemberEvent` | Member left a chat |
+| `read` | `KakaoTalkPushReadEvent` | Read receipt (unread count decreased) |
+| `kakaotalk_event` | `KakaoTalkPushGenericEvent` | Catch-all for all push events |
+| `connected` | `{ userId: string }` | Connected to LOCO server |
+| `disconnected` | — | Disconnected (will auto-reconnect) |
+| `error` | `Error` | Connection or protocol error |
+
+### Reconnection
+
+The listener automatically reconnects with exponential backoff (1s → 2s → 4s → ... → 30s max) when the connection drops. Server-requested migrations (`CHANGESVR`) trigger immediate reconnection. If the session is kicked by another device (`KICKOUT`), the listener stops and emits an error.
+
+## KakaoCredentialManager
+
+Manages KakaoTalk credentials stored at `~/.config/agent-messenger/kakaotalk-credentials.json`. Files are written with `0o600` permissions.
+
+```typescript
+import { KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+
+const manager = new KakaoCredentialManager()
+```
+
+```typescript
+// Load full config from disk (returns defaults if file doesn't exist)
+const config = await manager.load()
+// → KakaoConfig { current_account, accounts }
+
+// Save full config to disk
+await manager.save(config)
+
+// Get the current account's credentials
+const account = await manager.getAccount()
+// → KakaoAccountCredentials | null
+
+// Get a specific account by ID
+const specific = await manager.getAccount('1234567890')
+// → KakaoAccountCredentials | null
+
+// Store account credentials
+await manager.setAccount(credentials)
+
+// Remove an account
+await manager.removeAccount('1234567890')
+
+// Switch the current account
+await manager.setCurrentAccount('1234567890')
+```
+
+## Types
+
+```typescript
+import type {
+  KakaoChat,
+  KakaoMessage,
+  KakaoSendResult,
+  KakaoAccountCredentials,
+  KakaoConfig,
+  KakaoDeviceType,
+  PendingLoginState,
+} from 'agent-messenger/kakaotalk'
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported for parsing API responses:
+
+```typescript
+import {
+  KakaoChatSchema,
+  KakaoMessageSchema,
+  KakaoSendResultSchema,
+  KakaoAccountCredentialsSchema,
+  KakaoConfigSchema,
+} from 'agent-messenger/kakaotalk'
+```
+
+## Examples
+
+### Chat Summary
+
+List all chats, count unread, and print a summary.
+
+```typescript
+import { KakaoTalkClient, KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+
+const manager = new KakaoCredentialManager()
+const account = await manager.getAccount()
+if (!account) throw new Error('Not authenticated')
+
+const client = await new KakaoTalkClient().login({ oauthToken: account.oauth_token, userId: account.user_id, deviceUuid: account.device_uuid })
+
+try {
+  const chats = await client.getChats({ all: true })
+  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.display_name} — ${chat.unread_count} unread`)
+  }
+} finally {
+  client.close()
+}
+```
+
+### Send Notification
+
+Send a message to a specific chat.
+
+```typescript
+import { KakaoTalkClient, KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+
+const manager = new KakaoCredentialManager()
+const account = await manager.getAccount()
+if (!account) throw new Error('Not authenticated')
+
+const client = await new KakaoTalkClient().login({ oauthToken: account.oauth_token, userId: account.user_id, deviceUuid: account.device_uuid })
+
+try {
+  const chats = await client.getChats({ search: 'Team' })
+  const teamChat = chats[0]
+
+  if (teamChat) {
+    const result = await client.sendMessage(teamChat.chat_id, '🚀 Deployment complete!')
+    console.log(`Sent (log_id: ${result.log_id})`)
+  }
+} finally {
+  client.close()
+}
+```
+
+### Message Monitor
+
+Poll for new messages in a chat room.
+
+```typescript
+import { KakaoTalkClient, KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+
+const manager = new KakaoCredentialManager()
+const account = await manager.getAccount()
+if (!account) throw new Error('Not authenticated')
+
+const client = await new KakaoTalkClient().login({ oauthToken: account.oauth_token, userId: account.user_id, deviceUuid: account.device_uuid })
+const chatId = '9876543210'
+
+let lastLogId: string | undefined
+
+const poll = async () => {
+  try {
+    const messages = lastLogId
+      ? await client.getMessages(chatId, { from: lastLogId })
+      : await client.getMessages(chatId, { count: 1 })
+
+    for (const msg of messages) {
+      if (msg.log_id !== lastLogId) {
+        console.log(`[${msg.author_id}] ${msg.message}`)
+        lastLogId = msg.log_id
+      }
+    }
+  } catch (error) {
+    console.error('Poll failed:', error)
+  }
+}
+
+const timer = setInterval(poll, 10_000)
+
+// To stop: clearInterval(timer); client.close()
+```