agent-messenger 2.3.0 → 2.5.0

package/docs/content/docs/cli/wechatbot.mdx

@@ -0,0 +1,188 @@
+---
+title: WeChat Bot
+description: Complete reference for the agent-wechatbot CLI.
+---
+
+> **Tip**: `agent-wechatbot` is a shortcut for `agent-messenger wechatbot`.
+
+## Quick Start
+
+```bash
+# 1. Set your API credentials
+agent-wechatbot auth set your-app-id your-app-secret
+
+# 2. Verify authentication
+agent-wechatbot auth status
+
+# 3. List available templates
+agent-wechatbot template list --pretty
+
+# 4. Send a text message (recipient must have interacted within 48h)
+agent-wechatbot message send oXXXXXXXXXXXXXXX "Hello from the CLI!"
+```
+
+## Key Concepts
+
+WeChat Official Account API works differently from typical messaging APIs:
+
+| Concept                  | Description                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| **Send-only**            | Cannot list or read received messages. Inbound messages require webhooks.         |
+| **Customer service messages** | Free-form text, image, and news messages within 48h of user's last interaction. |
+| **Template messages**    | Pre-approved templates can be sent at any time. Created in the WeChat admin panel. |
+| **App ID + App Secret**  | Credentials from WeChat Official Account admin panel under Development settings.  |
+| **OpenID**               | Each follower has a unique OpenID scoped to your Official Account.                |
+| **IP Whitelist**         | Your server IP must be added to the account's whitelist or API calls fail (40164). |
+
+## Authentication
+
+### API Credential Setup
+
+agent-wechatbot uses App ID + App Secret pairs from the WeChat Official Account admin panel:
+
+```bash
+# Set credentials (validates against WeChat API before saving)
+agent-wechatbot auth set <app-id> <app-secret>
+
+# Check auth status
+agent-wechatbot auth status
+agent-wechatbot auth status --account <account-id>
+
+# Clear stored credentials
+agent-wechatbot auth clear
+```
+
+### How to Get API Credentials
+
+1. Log in to the [WeChat Official Account admin panel](https://mp.weixin.qq.com/)
+2. Navigate to **Development > Basic Configuration**
+3. Copy your **App ID** and **App Secret** (you may need to reset the secret if you don't have it saved)
+4. Add your server's IP to the **IP Whitelist**
+5. Run `agent-wechatbot auth set <app-id> <app-secret>`
+
+### Multi-Account Management
+
+```bash
+# List stored accounts
+agent-wechatbot auth list
+
+# Switch active account
+agent-wechatbot auth use <account-id>
+
+# Remove a stored account
+agent-wechatbot auth remove <account-id>
+```
+
+## Commands
+
+### Whoami Command
+
+```bash
+# Show current authenticated bot
+agent-wechatbot whoami
+agent-wechatbot whoami --pretty
+agent-wechatbot whoami --account <account-id>
+```
+
+### Message Commands
+
+```bash
+# Send a text message (customer service, within 48h window)
+agent-wechatbot message send <open-id> <text>
+agent-wechatbot message send oABCD1234 "Your order has shipped!"
+
+# Send an image message (customer service, within 48h window)
+agent-wechatbot message send-image <open-id> <media-id>
+agent-wechatbot message send-image oABCD1234 MEDIA_ID_HERE
+
+# Send a news/article message (customer service, within 48h window)
+agent-wechatbot message send-news <open-id> \
+  --title "Title" --description "Desc" --url "https://..." --picurl "https://..."
+```
+
+### Template Commands
+
+```bash
+# List all private templates
+agent-wechatbot template list
+
+# Send a template message
+agent-wechatbot template send <open-id> <template-id>
+agent-wechatbot template send oABCD1234 TM00001 \
+  --data '{"order_id":{"value":"ORD-9876"},"customer_name":{"value":"Alice"}}' \
+  --url "https://example.com/order/9876"
+
+# Delete a template
+agent-wechatbot template delete <template-id>
+```
+
+### User Commands
+
+```bash
+# List followers (paginated)
+agent-wechatbot user list
+agent-wechatbot user list --next-openid oLAST_OPENID
+
+# Get user info by OpenID
+agent-wechatbot user get <open-id>
+agent-wechatbot user get oABCD1234 --lang en
+```
+
+## Global Options
+
+| Option           | Description                            |
+| ---------------- | -------------------------------------- |
+| `--pretty`       | Human-readable output instead of JSON  |
+| `--account <id>` | Use a specific account for this command |
+
+## Storage
+
+Credentials stored in `~/.config/agent-messenger/wechatbot-credentials.json` (0600 permissions).
+
+## Limitations
+
+- **Cannot list or read received messages** -- WeChat Official Account API delivers inbound messages via webhooks only. This CLI is send-only.
+- **Customer service messages require 48h window** -- Free-form text, image, and news messages only work within 48 hours of the user's last interaction.
+- **Template messages require pre-approval** -- Templates must be created and approved in the WeChat admin panel before use.
+- **IP whitelist required** -- Your server's IP must be added to the Official Account's whitelist (error 40164).
+- **Media IDs required for images** -- Images must be uploaded to WeChat's media platform first. The CLI accepts media IDs, not URLs.
+- **No group chat support** -- Official Account API communicates with individual followers only.
+- **No real-time events / WebSocket connection** -- Inbound messages require a separate webhook server.
+- **No message editing or deletion**
+- **No voice or video calls**
+- **Access tokens expire** -- Tokens are valid for 7200 seconds. The CLI handles automatic refresh.
+
+## Troubleshooting
+
+### `agent-wechatbot: command not found`
+
+**`agent-wechatbot` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+```bash
+# If installed globally
+agent-wechatbot message send oABCD1234 "Hello"
+
+# If not installed, use npx
+npx -y agent-messenger wechatbot message send oABCD1234 "Hello"
+```
+
+### IP whitelist errors (40164)
+
+If you get error `40164`, your server's IP is not in the Official Account's whitelist. Add it in the admin panel under **Development > Basic Configuration > IP Whitelist**.
+
+### Token errors (40001, 42001)
+
+These indicate an expired or invalid access token. The CLI handles automatic token refresh, but if you see persistent errors:
+- Verify your App Secret hasn't been reset in the admin panel
+- Re-run `agent-wechatbot auth set <app-id> <app-secret>` with the current credentials
+
+### Rate limiting (45009)
+
+WeChat enforces API call frequency limits. If you hit error `45009`, wait before retrying. For bulk operations, add delays between requests.
+
+## AI Agent Integration
+
+See [`skills/agent-wechatbot/`](https://github.com/agent-messenger/agent-messenger/tree/main/skills/agent-wechatbot) for:
+
+- Complete skill documentation
+- Common patterns for AI agent workflows

package/docs/content/docs/cli/whatsapp.mdx

@@ -9,14 +9,17 @@ description: Complete reference for the agent-whatsapp CLI.
 
 WhatsApp integration uses [Baileys](https://github.com/WhiskeySockets/Baileys), a reverse-engineered WhatsApp Web API:
 
-- Links as a **companion device** via pairing code, so your phone stays connected.
+- Links as a **companion device** via QR code or pairing code, so your phone stays connected.
 - Each command opens a WebSocket connection on demand and disconnects when done. No persistent background process.
 - Multiple WhatsApp accounts can be linked simultaneously.
 
 ## Quick Start
 
 ```bash
-# Link as companion device (enter the pairing code on your phone)
+# Link as companion device via QR code (scan with your phone)
+agent-whatsapp auth login --qr
+
+# Or link via pairing code (enter the code on your phone)
 agent-whatsapp auth login --phone +1234567890
 
 # List chats
@@ -28,16 +31,23 @@ agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"
 
 ## Authentication
 
-### Pairing Code Login
+The CLI supports two authentication methods. Both register as a companion (linked) device, so your phone session is never affected.
 
-The CLI registers as a companion (linked) device using a numeric pairing code. Your phone session is never affected.
+### QR Code Login
+
+```bash
+agent-whatsapp auth login --qr
+```
+
+A QR code is displayed in the terminal and opened in the browser. Scan it with WhatsApp on your phone: Settings > Linked Devices > Link a Device.
+
+### Pairing Code Login
 
 ```bash
-# Start login (displays a pairing code)
 agent-whatsapp auth login --phone +1234567890
 ```
 
-The CLI outputs a pairing code. Enter it on your phone: WhatsApp > Settings > Linked Devices > Link a Device.
+A numeric pairing code is displayed. Enter it on your phone: WhatsApp > Settings > Linked Devices > Link with phone number.
 
 ### Account Management
 
@@ -59,6 +69,17 @@ agent-whatsapp auth logout --account <id>
 
 ## Commands
 
+### Whoami Command
+
+```bash
+# Show current authenticated user
+agent-whatsapp whoami
+agent-whatsapp whoami --pretty
+agent-whatsapp whoami --account <account-id>
+```
+
+Output includes the authenticated user's identity information.
+
 ### Chat Commands
 
 ```bash
@@ -135,6 +156,14 @@ npx -y --package agent-messenger agent-whatsapp chat list --pretty
 
 **NEVER run `npx agent-whatsapp`** without `--package agent-messenger`. It will fail or install a wrong package.
 
+### QR code not scanning
+
+1. Make sure WhatsApp is open on your phone
+2. Go to Settings > Linked Devices > Link a Device
+3. Point your phone camera at the QR code in the terminal or browser
+4. If the QR code expires, run `auth login --qr` again for a fresh code
+5. If QR scanning fails, try pairing code: `auth login --phone <number>`
+
 ### Pairing code not working
 
 1. Make sure WhatsApp is open on your phone
@@ -152,12 +181,12 @@ WhatsApp may disconnect linked devices that are inactive for extended periods. I
 agent-whatsapp auth status
 
 # Re-link if needed
-agent-whatsapp auth login --phone +1234567890
+agent-whatsapp auth login --qr
 ```
 
 ## AI Agent Integration
 
-See [`skills/agent-whatsapp/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-whatsapp) for:
+See [`skills/agent-whatsapp/`](https://github.com/agent-messenger/agent-messenger/tree/main/skills/agent-whatsapp) for:
 
 - Complete skill documentation
 - Common patterns for AI agent workflows

package/docs/content/docs/cli/whatsappbot.mdx

@@ -74,6 +74,15 @@ agent-whatsappbot auth remove <account-id>
 
 ## Commands
 
+### Whoami Command
+
+```bash
+# Show current authenticated bot
+agent-whatsappbot whoami
+agent-whatsappbot whoami --pretty
+agent-whatsappbot whoami --account <account-id>
+```
+
 ### Message Commands
 
 ```bash
@@ -163,7 +172,7 @@ WhatsApp enforces rate limits based on your business tier. The CLI automatically
 
 ## AI Agent Integration
 
-See [`skills/agent-whatsappbot/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-whatsappbot) for:
+See [`skills/agent-whatsappbot/`](https://github.com/agent-messenger/agent-messenger/tree/main/skills/agent-whatsappbot) for:
 
 - Complete skill documentation
 - Common patterns for AI agent workflows

package/docs/content/docs/sdk/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "TypeScript SDK",
-  "pages": ["slack", "discord", "teams", "webex", "whatsapp", "whatsappbot", "line", "instagram", "kakaotalk", "channeltalk", "channeltalkbot"]
+  "pages": ["slack", "discord", "teams", "webex", "whatsapp", "whatsappbot", "line", "wechatbot", "instagram", "kakaotalk", "channeltalk", "channeltalkbot"]
 }

package/docs/content/docs/sdk/wechatbot.mdx

@@ -0,0 +1,282 @@
+---
+title: WeChat Bot
+description: TypeScript SDK reference for WeChat Bot — Official Account API client, credential management, and types.
+---
+
+## Installation
+
+```bash
+npm install agent-messenger
+```
+
+```typescript
+import {
+  WeChatBotClient,
+  WeChatBotCredentialManager,
+  WeChatBotError,
+} from 'agent-messenger/wechatbot'
+```
+
+## WeChatBotClient
+
+The main client for interacting with the WeChat Official Account API programmatically. Handles access token lifecycle (caching, auto-refresh on expiry), errcode-aware response parsing, and automatic retries on transient errors. All API calls use query-parameter token injection per WeChat convention.
+
+```typescript
+import { WeChatBotClient } from 'agent-messenger/wechatbot'
+
+const client = await new WeChatBotClient().login({ appId, appSecret })
+```
+
+Or use automatic credential extraction, where credentials are read from stored config:
+
+```typescript
+import { WeChatBotClient } from 'agent-messenger/wechatbot'
+
+const client = await new WeChatBotClient().login()
+```
+
+### Verification
+
+```typescript
+// Verify credentials by attempting to obtain an access token
+const valid = await client.verifyCredentials()
+// → boolean
+```
+
+### Customer Service Messages
+
+Customer service messages can be sent to users who have interacted with your Official Account within the last 48 hours.
+
+```typescript
+// Send a text message
+await client.sendTextMessage('oABCD1234', 'Hello from the bot!')
+
+// Send an image message (requires a media ID from WeChat's media upload API)
+await client.sendImageMessage('oABCD1234', 'MEDIA_ID_HERE')
+
+// Send a news/article message
+await client.sendNewsMessage('oABCD1234', [
+  {
+    title: 'Your Order Update',
+    description: 'Your order #12345 has been shipped',
+    url: 'https://example.com/orders/12345',
+    picurl: 'https://example.com/images/shipping.jpg',
+  },
+])
+```
+
+### Template Messages
+
+Template messages can be sent at any time, regardless of the 48-hour interaction window.
+
+```typescript
+// Send a template message
+const result = await client.sendTemplateMessage(
+  'oABCD1234',
+  'TM00001',
+  { order_id: { value: 'ORD-9876' }, customer_name: { value: 'Alice' } },
+  'https://example.com/order/9876', // optional click URL
+)
+console.log(`Message ID: ${result.msgid}`)
+// → { msgid: number }
+
+// List all private templates
+const templates = await client.listTemplates()
+// → WeChatBotTemplate[]
+
+// Delete a template
+await client.deleteTemplate('TM00001')
+```
+
+### Users
+
+```typescript
+// List followers (paginated)
+const followers = await client.getFollowers()
+console.log(`Total: ${followers.total}, This page: ${followers.count}`)
+// → { total: number, count: number, openids: string[], next_openid: string }
+
+// Get next page
+const nextPage = await client.getFollowers(followers.next_openid)
+
+// Get user info
+const user = await client.getUserInfo('oABCD1234', 'en')
+// → WeChatBotUserInfo
+```
+
+## WeChatBotCredentialManager
+
+Manages WeChat Bot credentials stored at `~/.config/agent-messenger/wechatbot-credentials.json`. Files are written with `0o600` permissions. The environment variables `E2E_WECHATBOT_APP_ID` and `E2E_WECHATBOT_APP_SECRET` take precedence when calling `getCredentials()` without an `accountId`.
+
+```typescript
+import { WeChatBotCredentialManager } from 'agent-messenger/wechatbot'
+
+const manager = new WeChatBotCredentialManager()
+// Custom path: new WeChatBotCredentialManager('/custom/config/dir')
+```
+
+```typescript
+// Load full config from disk (returns defaults if file doesn't exist)
+const config = await manager.load()
+// → WeChatBotConfig
+
+// 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)
+// → WeChatBotCredentials | null
+
+// Store credentials for an account
+await manager.setCredentials({
+  app_id: 'wx1234567890',
+  app_secret: '...',
+  account_name: 'wx1234567890',
+})
+
+// Remove an account's credentials
+const removed = await manager.removeAccount('wx1234567890')
+// → boolean
+
+// Set the current default account
+const ok = await manager.setCurrent('wx1234567890')
+// → boolean
+
+// List all saved accounts with current marker
+const all = await manager.listAll()
+// → Array<WeChatBotAccountEntry & { is_current: boolean }>
+
+// Clear all stored credentials
+await manager.clearCredentials()
+```
+
+## Types
+
+```typescript
+import type {
+  WeChatBotAccountEntry,
+  WeChatBotConfig,
+  WeChatBotCredentials,
+  WeChatBotNewsArticle,
+  WeChatBotTemplate,
+  WeChatBotUserInfo,
+} from 'agent-messenger/wechatbot'
+```
+
+## WeChatBotError
+
+Thrown on authentication failures, network errors, rate limits, and API errors. Includes a `code` string for programmatic handling.
+
+```typescript
+import { WeChatBotError } from 'agent-messenger/wechatbot'
+
+try {
+  await client.sendTextMessage('oABCD1234', 'Hello')
+} catch (error) {
+  if (error instanceof WeChatBotError) {
+    console.error(`${error.code}: ${error.message}`)
+    // e.g. "40001: Invalid credential"
+    // e.g. "45009: Reach max API daily quota limit"
+    // e.g. "40164: Invalid ip, not in whitelist"
+  }
+}
+```
+
+### Zod Schemas
+
+Runtime-validated schemas are also exported for parsing API responses:
+
+```typescript
+import {
+  WeChatBotAccountEntrySchema,
+  WeChatBotConfigSchema,
+  WeChatBotCredentialsSchema,
+  WeChatBotNewsArticleSchema,
+  WeChatBotTemplateSchema,
+  WeChatBotUserInfoSchema,
+} from 'agent-messenger/wechatbot'
+```
+
+## Examples
+
+### Send Template Notification
+
+Send a template message with dynamic data to a follower.
+
+```typescript
+import { WeChatBotClient } from 'agent-messenger/wechatbot'
+
+const client = await new WeChatBotClient().login({ appId, appSecret })
+
+const result = await client.sendTemplateMessage(
+  'oABCD1234',
+  'order_confirmation',
+  {
+    order_id: { value: 'ORD-5678' },
+    status: { value: 'Shipped' },
+    date: { value: 'March 30, 2026' },
+  },
+  'https://example.com/orders/5678',
+)
+console.log(`Sent template, msgid: ${result.msgid}`)
+```
+
+### Broadcast to All Followers
+
+Iterate through paginated follower list and send template messages.
+
+```typescript
+import { WeChatBotClient } from 'agent-messenger/wechatbot'
+
+const client = await new WeChatBotClient().login({ appId, appSecret })
+
+let nextOpenId: string | undefined
+do {
+  const page = await client.getFollowers(nextOpenId)
+  for (const openId of page.openids) {
+    await client.sendTemplateMessage(openId, 'weekly_update', {
+      content: { value: 'New features released this week!' },
+    })
+  }
+  nextOpenId = page.next_openid || undefined
+} while (nextOpenId)
+```
+
+### Multi-Account Management
+
+Set up and switch between multiple Official Account credentials.
+
+```typescript
+import { WeChatBotCredentialManager, WeChatBotClient } from 'agent-messenger/wechatbot'
+
+const manager = new WeChatBotCredentialManager()
+
+// Store credentials for two accounts
+await manager.setCredentials({
+  app_id: 'wx1111111111',
+  app_secret: 'secret1...',
+  account_name: 'wx1111111111',
+})
+
+await manager.setCredentials({
+  app_id: 'wx2222222222',
+  app_secret: 'secret2...',
+  account_name: 'wx2222222222',
+})
+
+// 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.app_id}] ${marker}`)
+}
+
+// Switch to a specific account
+await manager.setCurrent('wx1111111111')
+
+// Login picks up the current account automatically
+const client = await new WeChatBotClient().login()
+const valid = await client.verifyCredentials()
+console.log(`Credentials valid: ${valid}`)
+```

package/docs/content/docs/tui.mdx

@@ -113,7 +113,7 @@ This means adding a new platform to the TUI is just implementing one adapter —
 
 ## Source
 
-The TUI source lives in [`src/tui/`](https://github.com/devxoul/agent-messenger/tree/main/src/tui):
+The TUI source lives in [`src/tui/`](https://github.com/agent-messenger/agent-messenger/tree/main/src/tui):
 
 ```
 src/tui/

package/docs/src/app/page.tsx

@@ -543,7 +543,7 @@ const HOW_IT_WORKS = [
   {
     step: 3,
     title: 'Teach Your Agent',
-    code: 'npx skills add devxoul/agent-messenger',
+    code: 'npx skills add agent-messenger/agent-messenger',
     description: 'Install Agent Skills via Skills CLI, Claude Code, OpenCode, or SkillPad — your agent learns every command and starts messaging on its own.',
   },
 ]
@@ -617,7 +617,7 @@ export default function Home() {
             docs
           </Link>
           <a
-            href="https://github.com/devxoul/agent-messenger"
+            href="https://github.com/agent-messenger/agent-messenger"
             target="_blank"
             rel="noopener noreferrer"
             className="rounded-lg px-3 py-2 font-mono text-xs text-zinc-500 transition-colors hover:text-zinc-900 dark:text-zinc-400 dark:hover:text-zinc-100"
@@ -661,7 +661,7 @@ export default function Home() {
               Get Started
             </Link>
             <a
-              href="https://github.com/devxoul/agent-messenger"
+              href="https://github.com/agent-messenger/agent-messenger"
               target="_blank"
               rel="noopener noreferrer"
               className="inline-flex items-center justify-center rounded-xl border border-zinc-300 px-6 py-3 text-sm font-medium text-zinc-700 transition-all duration-300 hover:bg-zinc-50 dark:border-white/[0.06] dark:text-zinc-300 dark:hover:border-white/15 dark:hover:bg-white/[0.05]"
@@ -1002,7 +1002,7 @@ export default function Home() {
                 Read the Docs
               </Link>
               <a
-                href="https://github.com/devxoul/agent-messenger"
+                href="https://github.com/agent-messenger/agent-messenger"
                 target="_blank"
                 rel="noopener noreferrer"
                 className="inline-flex items-center justify-center rounded-xl border border-zinc-300 px-6 py-3 text-sm font-medium text-zinc-700 transition-all duration-300 hover:bg-white dark:border-white/[0.06] dark:text-zinc-300 dark:hover:border-white/15 dark:hover:bg-white/[0.05]"
@@ -1024,7 +1024,7 @@ export default function Home() {
               docs
             </Link>
             <a
-              href="https://github.com/devxoul/agent-messenger"
+              href="https://github.com/agent-messenger/agent-messenger"
               target="_blank"
               rel="noopener noreferrer"
               className="transition-colors duration-300 hover:text-zinc-700 dark:hover:text-zinc-300"