agent-messenger 1.14.0 → 2.0.0

package/docs/content/docs/cli/instagram.mdx

@@ -0,0 +1,211 @@
+---
+title: Instagram
+description: Complete reference for the agent-instagram CLI.
+---
+
+> **Tip**: After `npm install -g agent-messenger`, `agent-instagram` is available directly. For one-off execution without a global install you can use `npm exec --package agent-messenger agent-instagram ...`, `pnpm dlx --package agent-messenger agent-instagram ...`, `yarn dlx agent-messenger agent-instagram ...`, or `bunx --package agent-messenger agent-instagram ...`.
+
+## Requirements
+
+Instagram integration uses a private mobile API (not the official Graph API). No new npm dependencies are required:
+
+- Authenticates with **username and password**, with support for 2FA and login challenges.
+- Each command makes HTTP requests on demand. No persistent connection or background process.
+- Multiple Instagram accounts can be linked simultaneously.
+
+## Quick Start
+
+```bash
+# Log in with your Instagram credentials
+agent-instagram auth login
+
+# List DM threads
+agent-instagram chat list
+
+# Send a message
+agent-instagram message send 12345678901 "Hello from agent-instagram"
+```
+
+## Authentication
+
+### Username/Password Login
+
+The CLI authenticates as a mobile client using your Instagram username and password. Your existing app sessions are never affected.
+
+**Interactive mode** (TTY): prompts for credentials automatically.
+
+```bash
+agent-instagram auth login
+```
+
+**Non-interactive mode** (CI / agents): pass credentials as flags.
+
+```bash
+agent-instagram auth login --username your_username --password your_password
+```
+
+### Two-Factor Authentication
+
+If 2FA is enabled, the CLI handles it automatically in interactive mode. In non-interactive mode, use a separate verify step:
+
+```bash
+agent-instagram auth verify --username your_username --code 123456 --identifier <two_factor_identifier>
+```
+
+The `--identifier` value comes from the login response's `two_factor_identifier` field.
+
+### Challenge Required
+
+Instagram may require a challenge for logins from new devices or locations. The CLI resolves challenges interactively when possible. In non-interactive mode:
+
+```bash
+agent-instagram auth challenge --username your_username --method email
+agent-instagram auth challenge --username your_username --code 123456
+```
+
+### Debug Mode
+
+Use `--debug` on login to see raw API responses when troubleshooting:
+
+```bash
+agent-instagram auth login --username your_username --password your_password --debug
+```
+
+### Account Management
+
+```bash
+# Check current auth state
+agent-instagram auth status
+agent-instagram auth status --account <id>
+
+# List linked accounts
+agent-instagram auth list
+
+# Switch active account
+agent-instagram auth use <id>
+
+# Remove stored session
+agent-instagram auth logout
+agent-instagram auth logout --account <id>
+```
+
+## Commands
+
+### Chat Commands
+
+```bash
+# List DM threads (sorted by most recent activity)
+agent-instagram chat list
+agent-instagram chat list --limit 50
+agent-instagram chat list --account <id>
+
+# Search threads by name
+agent-instagram chat search "project"
+agent-instagram chat search "project" --limit 10
+agent-instagram chat search "project" --account <id>
+```
+
+### Message Commands
+
+```bash
+# List messages in a thread
+agent-instagram message list <thread> --limit 20
+agent-instagram message list 12345678901 --limit 50
+
+# Send a text message by thread ID
+agent-instagram message send <thread> <text>
+agent-instagram message send 12345678901 "Hello!"
+
+# Send a text message by username (resolves the user first)
+agent-instagram message send-to <username> <text>
+agent-instagram message send-to alice "Hello!"
+
+# Search messages by text content
+agent-instagram message search <query>
+agent-instagram message search "meeting notes" --thread 12345678901
+agent-instagram message search "hello" --limit 10
+
+# Search for users by name or username
+agent-instagram message search-users <query>
+agent-instagram message search-users "alice"
+```
+
+Thread IDs are numeric strings returned by `chat list` (e.g. `340282366841710300949128138443434234567`).
+
+## 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/instagram-credentials.json`
+- Session data stored in `~/.config/agent-messenger/instagram/<account-id>/`
+
+## Limitations
+
+- **HTTP on demand**: Each command makes HTTP requests and returns. No persistent daemon or WebSocket connection.
+- **Ban risk**: Instagram monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
+- **No file uploads or downloads**
+- **No voice or video calls**
+- **No Stories, Reels, or Feed access**
+- **Private API**: This uses Instagram's private mobile API, not the official Graph API. Behavior may change without notice.
+
+## Troubleshooting
+
+### `agent-instagram: command not found`
+
+**`agent-instagram` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+```bash
+# If installed globally
+agent-instagram chat list --pretty
+
+# If not installed, use --package
+npx -y --package agent-messenger agent-instagram chat list --pretty
+```
+
+**NEVER run `npx agent-instagram`** without `--package agent-messenger`. It will fail or install a wrong package.
+
+### Login fails with "challenge_required"
+
+Instagram flagged the login as suspicious. Complete the challenge:
+
+```bash
+# Check what challenge is pending
+agent-instagram auth challenge --status
+
+# Submit the code sent to your email or phone
+agent-instagram auth challenge --code 123456
+```
+
+If challenges keep appearing, try logging in from the Instagram app first to "warm up" the account, then retry the CLI.
+
+### Login fails with "two_factor_required"
+
+Your account has 2FA enabled. Complete the verification:
+
+```bash
+agent-instagram auth verify --code 123456
+```
+
+### Session expired
+
+Instagram may invalidate sessions after extended inactivity or password changes. If commands start failing:
+
+```bash
+# Check if still authenticated
+agent-instagram auth status
+
+# Re-login if needed
+agent-instagram auth login
+```
+
+## AI Agent Integration
+
+See [`skills/agent-instagram/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-instagram) for:
+
+- Complete skill documentation
+- Common patterns for AI agent workflows

package/docs/content/docs/cli/kakaotalk.mdx

@@ -0,0 +1,286 @@
+---
+title: KakaoTalk
+description: Complete reference for the agent-kakaotalk CLI.
+---
+
+> **Tip**: After `npm install -g agent-messenger`, `agent-kakaotalk` is available directly. For one-off execution without a global install you can use `npm exec --package agent-messenger agent-kakaotalk ...`, `pnpm dlx --package agent-messenger agent-kakaotalk ...`, `yarn dlx agent-messenger agent-kakaotalk ...`, or `bunx --package agent-messenger agent-kakaotalk ...`.
+
+## Key Concepts
+
+Before diving in, a few things about KakaoTalk's architecture:
+
+| Term                       | Description                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| **LOCO protocol**          | KakaoTalk's binary messaging protocol. The CLI handles this internally — you never touch it.        |
+| **Chat room**              | A conversation (1:1, group, or open chat). Referenced by a numeric chat ID.                         |
+| **Device slots**           | KakaoTalk allows one phone + one PC + one tablet session simultaneously.                            |
+| **Sub-device**             | A secondary device (PC or tablet). The CLI logs in as a sub-device so your phone session is never affected. |
+| **Passcode verification**  | When registering a new device, KakaoTalk displays a code that you confirm on your phone.            |
+| **Log ID**                 | A unique numeric identifier for each message, used for pagination.                                  |
+
+## Quick Start
+
+```bash
+# 1. Login (registers as sub-device — desktop app stays running)
+agent-kakaotalk auth login
+
+# 2. List chat rooms
+agent-kakaotalk chat list
+
+# 3. Send a message
+agent-kakaotalk message send <chat-id> "Hello from agent-kakaotalk!"
+
+# 4. List messages in a chat
+agent-kakaotalk message list <chat-id>
+```
+
+## Authentication
+
+KakaoTalk offers two authentication methods. **Login** is recommended because it registers the CLI as a sub-device and keeps your desktop app running.
+
+### Method 1: Login (Recommended)
+
+Registers the CLI as a sub-device using the **tablet** slot by default. Your desktop app keeps running.
+
+```bash
+# Interactive — prompts for email and password
+agent-kakaotalk auth login
+
+# Non-interactive (for AI agents)
+agent-kakaotalk auth login --email user@example.com --password mypass
+```
+
+On first login, KakaoTalk requires device verification:
+
+1. The CLI requests a passcode from KakaoTalk's server
+2. A numeric code is displayed in the terminal
+3. Enter the code on your phone when prompted
+4. The CLI polls until you confirm — login completes automatically
+
+### Method 2: Extract from Desktop App
+
+Extracts OAuth tokens directly from the KakaoTalk desktop app's cache. This **kicks the desktop session** because it reuses the desktop's credentials.
+
+```bash
+agent-kakaotalk auth extract
+agent-kakaotalk auth extract --debug
+```
+
+### Device Slots
+
+KakaoTalk allows these simultaneous sessions:
+
+- **Phone** — always active, never affected by the CLI
+- **PC** — will kick KakaoTalk desktop if the CLI uses this slot
+- **Tablet** (default) — safe if you don't use a tablet for KakaoTalk
+
+```bash
+# Default: tablet slot (safe for most users)
+agent-kakaotalk auth login
+
+# Use PC slot instead (kicks desktop app)
+agent-kakaotalk auth login --device-type pc
+
+# Force login even if slot is occupied
+agent-kakaotalk auth login --device-type tablet --force
+```
+
+### Auth Management
+
+```bash
+# Check auth status
+agent-kakaotalk auth status
+agent-kakaotalk auth status --account <account-id>
+
+# List all stored accounts
+agent-kakaotalk auth list
+
+# Switch the current account
+agent-kakaotalk auth use <account-id>
+
+# Remove stored credentials
+agent-kakaotalk auth logout
+agent-kakaotalk auth logout --account <account-id>
+```
+
+## Multi-Account
+
+KakaoTalk supports multiple accounts. Each login or extraction stores credentials separately, keyed by user ID.
+
+```bash
+# List all stored accounts
+agent-kakaotalk auth list
+
+# Switch the current account
+agent-kakaotalk auth use <account-id>
+
+# Use a specific account for any command
+agent-kakaotalk chat list --account <account-id>
+agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
+```
+
+Without `--account`, commands use the current (default) account.
+
+## Commands
+
+### Chat Commands
+
+```bash
+# List all chat rooms (sorted by most recent activity)
+agent-kakaotalk chat list
+agent-kakaotalk chat list --pretty
+agent-kakaotalk chat list --account <account-id>
+
+# Fetch all chats (paginate beyond login snapshot)
+agent-kakaotalk chat list --all
+
+# Search for a chat by display name
+agent-kakaotalk chat list --search "Alice"
+agent-kakaotalk chat list --all --search "project"
+```
+
+Output includes:
+
+- `chat_id` — numeric chat room ID
+- `type` — chat type (1:1, group, open chat)
+- `display_name` — comma-separated member names
+- `active_members` — number of active members
+- `unread_count` — unread message count
+- `last_message` — most recent message preview
+
+### Message Commands
+
+```bash
+# List messages in a chat room
+agent-kakaotalk message list <chat-id>
+agent-kakaotalk message list <chat-id> -n 50
+agent-kakaotalk message list <chat-id> --from <log-id>
+agent-kakaotalk message list <chat-id> --pretty
+
+# Send a text message
+agent-kakaotalk message send <chat-id> "Hello world"
+agent-kakaotalk message send <chat-id> "Hello world" --pretty
+
+# Use a specific account
+agent-kakaotalk message list <chat-id> --account <account-id>
+agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
+```
+
+Each message includes:
+
+- `log_id` — unique message identifier
+- `type` — message type (1 = text, 2 = photo, etc.)
+- `author_id` — sender's user ID
+- `message` — message text content
+- `sent_at` — Unix timestamp (milliseconds)
+
+#### Fetching More Messages
+
+The CLI handles internal pagination automatically. Just increase `-n` to get more messages. Pagination is capped at ~4,000 raw messages (50 pages × 80 per page). If the cap is hit, a warning is printed to stderr and results may be incomplete.
+
+```bash
+# Get latest 20 messages (default)
+agent-kakaotalk message list 9876543210
+
+# Get 50 messages
+agent-kakaotalk message list 9876543210 -n 50
+
+# Get 200 messages
+agent-kakaotalk message list 9876543210 -n 200
+
+# Get messages newer than a known log ID (forward only)
+agent-kakaotalk message list 9876543210 --from 123456789
+```
+
+## Global Options
+
+| Option      | Description                                                 |
+| ----------- | ----------------------------------------------------------- |
+| `--account` | Use a specific KakaoTalk account (default: current account) |
+| `--pretty`  | Human-readable output instead of JSON                       |
+
+## Storage
+
+- Credentials stored in `~/.config/agent-messenger/kakaotalk-credentials.json` (0600 permissions)
+- macOS extraction reads from `~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db`
+- Windows extraction reads from the registry and `%LocalAppData%\Kakao\login_list.dat`
+
+## Limitations
+
+- `auth extract` requires macOS or Windows (reads from the KakaoTalk desktop app)
+- `auth login` works on any platform (email + password, no desktop app needed)
+- No file upload or download
+- No channel/chat room creation or management
+- No friend list management
+- No reactions or emoji
+- No message editing or deletion
+- No open chat browsing or joining
+- No search across chats
+
+- Plain text messages only (no photos, videos, or rich content)
+- Chat IDs are numeric and not human-readable — use `chat list` to discover them
+
+## Troubleshooting
+
+### `agent-kakaotalk: command not found`
+
+**`agent-kakaotalk` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+```bash
+# If installed globally
+agent-kakaotalk chat list --pretty
+
+# If not installed, use --package
+npx -y --package agent-messenger agent-kakaotalk chat list --pretty
+```
+
+**NEVER run `npx agent-kakaotalk`** without `--package agent-messenger`. It will fail or install a wrong package.
+
+### No credentials found
+
+If `auth extract` fails:
+
+1. Make sure the KakaoTalk desktop app is installed and you're logged in
+2. Run `agent-kakaotalk auth extract --debug` for detailed diagnostics
+3. If extraction still fails, use `agent-kakaotalk auth login` instead (recommended)
+
+### Device slot occupied
+
+If login fails because the tablet slot is occupied:
+
+```bash
+# Option 1: Use the PC slot instead
+agent-kakaotalk auth login --device-type pc --force
+
+# Option 2: Force the tablet slot (kicks existing tablet session)
+agent-kakaotalk auth login --device-type tablet --force
+```
+
+### Passcode verification timeout
+
+If the passcode expires before you confirm on your phone:
+
+1. Run `agent-kakaotalk auth login` again — a new passcode will be generated
+2. Confirm the code on your phone within the time limit
+3. The CLI automatically completes login after confirmation
+
+### Cache.db not found (macOS)
+
+The CLI looks for KakaoTalk's cache at:
+
+```
+~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db
+```
+
+If this file doesn't exist:
+
+1. Install KakaoTalk from the Mac App Store
+2. Log in and send at least one message (to populate the cache)
+3. Run `agent-kakaotalk auth extract` again
+
+## AI Agent Integration
+
+See [`skills/agent-kakaotalk/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-kakaotalk) for:
+
+- Complete skill documentation
+- Common patterns for AI agent workflows