feat: skills as branches, channels as forks

Replace the custom skills engine with standard git operations.
Feature skills are now git branches (on upstream or channel forks)
applied via `git merge`. Channels are separate fork repos.

- Remove skills-engine/ (6,300+ lines), apply/uninstall/rebase scripts
- Remove old skill format (add/, modify/, manifest.yaml) from all skills
- Remove old CI (skill-drift.yml, skill-pr.yml)
- Add merge-forward CI for upstream skill branches
- Add fork notification (repository_dispatch to channel forks)
- Add marketplace config (.claude/settings.json)
- Add /update-skills operational skill
- Update /setup and /customize for marketplace plugin install
- Add docs/skills-as-branches.md architecture doc

Channel forks created: nanoclaw-whatsapp (with 5 skill branches),
nanoclaw-telegram, nanoclaw-discord, nanoclaw-slack, nanoclaw-gmail.

Upstream retains: skill/ollama-tool, skill/apple-container, skill/compact.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-03-10 00:18:25 +02:00
parent e7852a45a5
commit 5118239cea
182 changed files with 1065 additions and 36205 deletions

View File

@@ -1,361 +0,0 @@
---
name: add-whatsapp
description: Add WhatsApp as a channel. Can replace other channels entirely or run alongside them. Uses QR code or pairing code for authentication.
---
# Add WhatsApp Channel
This skill adds WhatsApp support to NanoClaw. It installs the WhatsApp channel code, dependencies, and guides through authentication, registration, and configuration.
## Phase 1: Pre-flight
### Check current state
Check if WhatsApp is already configured. If `store/auth/` exists with credential files, skip to Phase 4 (Registration) or Phase 5 (Verify).
```bash
ls store/auth/creds.json 2>/dev/null && echo "WhatsApp auth exists" || echo "No WhatsApp auth"
```
### Detect environment
Check whether the environment is headless (no display server):
```bash
[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"
```
### Ask the user
Use `AskUserQuestion` to collect configuration. **Adapt auth options based on environment:**
If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?
- **Pairing code** (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
- **QR code in browser** (Recommended) - Opens a browser window with a large, scannable QR code
- **Pairing code** - Enter a numeric code on your phone (no camera needed, requires phone number)
- **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)
If they chose pairing code:
AskUserQuestion: What is your phone number? (Include country code without +, e.g., 1234567890)
## Phase 2: Verify Code
Apply the skill to install the WhatsApp channel code and dependencies:
```bash
npx tsx scripts/apply-skill.ts .claude/skills/add-whatsapp
```
Verify the code was placed correctly:
```bash
test -f src/channels/whatsapp.ts && echo "WhatsApp channel code present" || echo "ERROR: WhatsApp channel code missing — re-run skill apply"
```
### Verify dependencies
```bash
node -e "require('@whiskeysockets/baileys')" 2>/dev/null && echo "Baileys installed" || echo "Installing Baileys..."
```
If not installed:
```bash
npm install @whiskeysockets/baileys qrcode qrcode-terminal
```
### Validate build
```bash
npm run build
```
Build must be clean before proceeding.
## Phase 3: Authentication
### Clean previous auth state (if re-authenticating)
```bash
rm -rf store/auth/
```
### Run WhatsApp authentication
For QR code in browser (recommended):
```bash
npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
```
(Bash timeout: 150000ms)
Tell the user:
> A browser window will open with a QR code.
>
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
> 2. Scan the QR code in the browser
> 3. The page will show "Authenticated!" when done
For QR code in terminal:
```bash
npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
```
Tell the user to run `npm run auth` in another terminal, then:
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
> 2. Scan the QR code displayed in the terminal
For pairing code:
Tell the user to have WhatsApp open on **Settings > Linked Devices > Link a Device**, ready to tap **"Link with phone number instead"** — the code expires in ~60 seconds and must be entered immediately.
Run the auth process in the background and poll `store/pairing-code.txt` for the code:
```bash
rm -f store/pairing-code.txt && npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &
```
Then immediately poll for the code (do NOT wait for the background command to finish):
```bash
for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done
```
Display the code to the user the moment it appears. Tell them:
> **Enter this code now** — it expires in ~60 seconds.
>
> 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
> 2. Tap **Link with phone number instead**
> 3. Enter the code immediately
After the user enters the code, poll for authentication to complete:
```bash
for i in $(seq 1 60); do grep -q 'AUTH_STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'AUTH_STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done
```
**If failed:** qr_timeout → re-run. logged_out → delete `store/auth/` and re-run. 515 → re-run. timeout → ask user, offer retry.
### Verify authentication succeeded
```bash
test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"
```
### Configure environment
Channels auto-enable when their credentials are present — WhatsApp activates when `store/auth/creds.json` exists.
Sync to container environment:
```bash
mkdir -p data/env && cp .env data/env/env
```
## Phase 4: Registration
### Configure trigger and channel type
Get the bot's WhatsApp number: `node -e "const c=require('./store/auth/creds.json');console.log(c.me.id.split(':')[0].split('@')[0])"`
AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number (separate device)?
- **Shared number** - Your personal WhatsApp number (recommended: use self-chat or a solo group)
- **Dedicated number** - A separate phone/SIM for the assistant
AskUserQuestion: What trigger word should activate the assistant?
- **@Andy** - Default trigger
- **@Claw** - Short and easy
- **@Claude** - Match the AI name
AskUserQuestion: What should the assistant call itself?
- **Andy** - Default name
- **Claw** - Short and easy
- **Claude** - Match the AI name
AskUserQuestion: Where do you want to chat with the assistant?
**Shared number options:**
- **Self-chat** (Recommended) - Chat in your own "Message Yourself" conversation
- **Solo group** - A group with just you and the linked device
- **Existing group** - An existing WhatsApp group
**Dedicated number options:**
- **DM with bot** (Recommended) - Direct message the bot's number
- **Solo group** - A group with just you and the bot
- **Existing group** - An existing WhatsApp group
### Get the JID
**Self-chat:** JID = your phone number with `@s.whatsapp.net`. Extract from auth credentials:
```bash
node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"
```
**DM with bot:** The JID is the **user's** phone number — the number they will message *from* (not the bot's own number). Ask:
AskUserQuestion: What is your personal phone number? (The number you'll use to message the bot — include country code without +, e.g. 1234567890)
JID = `<user-number>@s.whatsapp.net`
**Group (solo, existing):** Run group sync and list available groups:
```bash
npx tsx setup/index.ts --step groups
npx tsx setup/index.ts --step groups --list
```
The output shows `JID|GroupName` pairs. Present candidates as AskUserQuestion (names only, not JIDs).
### Register the chat
```bash
npx tsx setup/index.ts --step register \
--jid "<jid>" \
--name "<chat-name>" \
--trigger "@<trigger>" \
--folder "whatsapp_main" \
--channel whatsapp \
--assistant-name "<name>" \
--is-main \
--no-trigger-required # For self-chat and DM with bot (1:1 conversations don't need a trigger prefix)
```
For additional groups (trigger-required):
```bash
npx tsx setup/index.ts --step register \
--jid "<group-jid>" \
--name "<group-name>" \
--trigger "@<trigger>" \
--folder "whatsapp_<group-name>" \
--channel whatsapp
```
## Phase 5: Verify
### Build and restart
```bash
npm run build
```
Restart the service:
```bash
# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/com.nanoclaw
# Linux (systemd)
systemctl --user restart nanoclaw
# Linux (nohup fallback)
bash start-nanoclaw.sh
```
### Test the connection
Tell the user:
> Send a message to your registered WhatsApp chat:
> - For self-chat / main: Any message works
> - For groups: Use the trigger word (e.g., "@Andy hello")
>
> The assistant should respond within a few seconds.
### Check logs if needed
```bash
tail -f logs/nanoclaw.log
```
## Troubleshooting
### QR code expired
QR codes expire after ~60 seconds. Re-run the auth command:
```bash
rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts
```
### Pairing code not working
Codes expire in ~60 seconds. To retry:
```bash
rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts --pairing-code --phone <phone>
```
Enter the code **immediately** when it appears. Also ensure:
1. Phone number includes country code without `+` (e.g., `1234567890`)
2. Phone has internet access
3. WhatsApp is updated to the latest version
If pairing code keeps failing, switch to QR-browser auth instead:
```bash
rm -rf store/auth/ && npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
```
### "conflict" disconnection
This happens when two instances connect with the same credentials. Ensure only one NanoClaw process is running:
```bash
pkill -f "node dist/index.js"
# Then restart
```
### Bot not responding
Check:
1. Auth credentials exist: `ls store/auth/creds.json`
3. Chat is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%whatsapp%' OR jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"`
4. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)
5. Logs: `tail -50 logs/nanoclaw.log`
### Group names not showing
Run group metadata sync:
```bash
npx tsx setup/index.ts --step groups
```
This fetches all group names from WhatsApp. Runs automatically every 24 hours.
## After Setup
If running `npm run dev` while the service is active:
```bash
# macOS:
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
npm run dev
# When done testing:
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
# Linux:
# systemctl --user stop nanoclaw
# npm run dev
# systemctl --user start nanoclaw
```
## Removal
To remove WhatsApp integration:
1. Delete auth credentials: `rm -rf store/auth/`
2. Remove WhatsApp registrations: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"`
3. Sync env: `mkdir -p data/env && cp .env data/env/env`
4. Rebuild and restart: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)

View File

@@ -1,368 +0,0 @@
/**
* Step: whatsapp-auth — WhatsApp interactive auth (QR code / pairing code).
*/
import { execSync, spawn } from 'child_process';
import fs from 'fs';
import path from 'path';
import { logger } from '../src/logger.js';
import { openBrowser, isHeadless } from './platform.js';
import { emitStatus } from './status.js';
const QR_AUTH_TEMPLATE = `<!DOCTYPE html>
<html><head><title>NanoClaw - WhatsApp Auth</title>
<meta http-equiv="refresh" content="3">
<style>
body { font-family: -apple-system, sans-serif; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
.card { background: white; border-radius: 16px; padding: 40px; box-shadow: 0 4px 24px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
h2 { margin: 0 0 8px; }
.timer { font-size: 18px; color: #666; margin: 12px 0; }
.timer.urgent { color: #e74c3c; font-weight: bold; }
.instructions { color: #666; font-size: 14px; margin-top: 16px; }
svg { width: 280px; height: 280px; }
</style></head><body>
<div class="card">
<h2>Scan with WhatsApp</h2>
<div class="timer" id="timer">Expires in <span id="countdown">60</span>s</div>
<div id="qr">{{QR_SVG}}</div>
<div class="instructions">Settings \\u2192 Linked Devices \\u2192 Link a Device</div>
</div>
<script>
var startKey = 'nanoclaw_qr_start';
var start = localStorage.getItem(startKey);
if (!start) { start = Date.now().toString(); localStorage.setItem(startKey, start); }
var elapsed = Math.floor((Date.now() - parseInt(start)) / 1000);
var remaining = Math.max(0, 60 - elapsed);
var countdown = document.getElementById('countdown');
var timer = document.getElementById('timer');
countdown.textContent = remaining;
if (remaining <= 10) timer.classList.add('urgent');
if (remaining <= 0) {
timer.textContent = 'QR code expired \\u2014 a new one will appear shortly';
timer.classList.add('urgent');
localStorage.removeItem(startKey);
}
</script></body></html>`;
const SUCCESS_HTML = `<!DOCTYPE html>
<html><head><title>NanoClaw - Connected!</title>
<style>
body { font-family: -apple-system, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
.card { background: white; border-radius: 16px; padding: 40px; box-shadow: 0 4px 24px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
h2 { color: #27ae60; margin: 0 0 8px; }
p { color: #666; }
.check { font-size: 64px; margin-bottom: 16px; }
</style></head><body>
<div class="card">
<div class="check">&#10003;</div>
<h2>Connected to WhatsApp</h2>
<p>You can close this tab.</p>
</div>
<script>localStorage.removeItem('nanoclaw_qr_start');</script>
</body></html>`;
function parseArgs(args: string[]): { method: string; phone: string } {
let method = '';
let phone = '';
for (let i = 0; i < args.length; i++) {
if (args[i] === '--method' && args[i + 1]) {
method = args[i + 1];
i++;
}
if (args[i] === '--phone' && args[i + 1]) {
phone = args[i + 1];
i++;
}
}
return { method, phone };
}
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
function readFileSafe(filePath: string): string {
try {
return fs.readFileSync(filePath, 'utf-8');
} catch {
return '';
}
}
function getPhoneNumber(projectRoot: string): string {
try {
const creds = JSON.parse(
fs.readFileSync(
path.join(projectRoot, 'store', 'auth', 'creds.json'),
'utf-8',
),
);
if (creds.me?.id) {
return creds.me.id.split(':')[0].split('@')[0];
}
} catch {
// Not available yet
}
return '';
}
function emitAuthStatus(
method: string,
authStatus: string,
status: string,
extra: Record<string, string> = {},
): void {
const fields: Record<string, string> = {
AUTH_METHOD: method,
AUTH_STATUS: authStatus,
...extra,
STATUS: status,
LOG: 'logs/setup.log',
};
emitStatus('AUTH_WHATSAPP', fields);
}
export async function run(args: string[]): Promise<void> {
const projectRoot = process.cwd();
const { method, phone } = parseArgs(args);
const statusFile = path.join(projectRoot, 'store', 'auth-status.txt');
const qrFile = path.join(projectRoot, 'store', 'qr-data.txt');
if (!method) {
emitAuthStatus('unknown', 'failed', 'failed', {
ERROR: 'missing_method_flag',
});
process.exit(4);
}
// qr-terminal is a manual flow
if (method === 'qr-terminal') {
emitAuthStatus('qr-terminal', 'manual', 'manual', {
PROJECT_PATH: projectRoot,
});
return;
}
if (method === 'pairing-code' && !phone) {
emitAuthStatus('pairing-code', 'failed', 'failed', {
ERROR: 'missing_phone_number',
});
process.exit(4);
}
if (!['qr-browser', 'pairing-code'].includes(method)) {
emitAuthStatus(method, 'failed', 'failed', { ERROR: 'unknown_method' });
process.exit(4);
}
// Clean stale state
logger.info({ method }, 'Starting channel authentication');
try {
fs.rmSync(path.join(projectRoot, 'store', 'auth'), {
recursive: true,
force: true,
});
} catch {
/* ok */
}
try {
fs.unlinkSync(qrFile);
} catch {
/* ok */
}
try {
fs.unlinkSync(statusFile);
} catch {
/* ok */
}
// Start auth process in background
const authArgs =
method === 'pairing-code'
? ['src/whatsapp-auth.ts', '--pairing-code', '--phone', phone]
: ['src/whatsapp-auth.ts'];
const authProc = spawn('npx', ['tsx', ...authArgs], {
cwd: projectRoot,
stdio: ['ignore', 'pipe', 'pipe'],
detached: false,
});
const logFile = path.join(projectRoot, 'logs', 'setup.log');
const logStream = fs.createWriteStream(logFile, { flags: 'a' });
authProc.stdout?.pipe(logStream);
authProc.stderr?.pipe(logStream);
// Cleanup on exit
const cleanup = () => {
try {
authProc.kill();
} catch {
/* ok */
}
};
process.on('exit', cleanup);
try {
if (method === 'qr-browser') {
await handleQrBrowser(projectRoot, statusFile, qrFile);
} else {
await handlePairingCode(projectRoot, statusFile, phone);
}
} finally {
cleanup();
process.removeListener('exit', cleanup);
}
}
async function handleQrBrowser(
projectRoot: string,
statusFile: string,
qrFile: string,
): Promise<void> {
// Poll for QR data (15s)
let qrReady = false;
for (let i = 0; i < 15; i++) {
const statusContent = readFileSafe(statusFile);
if (statusContent === 'already_authenticated') {
emitAuthStatus('qr-browser', 'already_authenticated', 'success');
return;
}
if (fs.existsSync(qrFile)) {
qrReady = true;
break;
}
await sleep(1000);
}
if (!qrReady) {
emitAuthStatus('qr-browser', 'failed', 'failed', { ERROR: 'qr_timeout' });
process.exit(3);
}
// Generate QR SVG and HTML
const qrData = fs.readFileSync(qrFile, 'utf-8');
try {
const svg = execSync(
`node -e "const QR=require('qrcode');const data='${qrData}';QR.toString(data,{type:'svg'},(e,s)=>{if(e)process.exit(1);process.stdout.write(s)})"`,
{ cwd: projectRoot, encoding: 'utf-8' },
);
const html = QR_AUTH_TEMPLATE.replace('{{QR_SVG}}', svg);
const htmlPath = path.join(projectRoot, 'store', 'qr-auth.html');
fs.writeFileSync(htmlPath, html);
// Open in browser (cross-platform)
if (!isHeadless()) {
const opened = openBrowser(htmlPath);
if (!opened) {
logger.warn(
'Could not open browser — display QR in terminal as fallback',
);
}
} else {
logger.info(
'Headless environment — QR HTML saved but browser not opened',
);
}
} catch (err) {
logger.error({ err }, 'Failed to generate QR HTML');
}
// Poll for completion (120s)
await pollAuthCompletion('qr-browser', statusFile, projectRoot);
}
async function handlePairingCode(
projectRoot: string,
statusFile: string,
phone: string,
): Promise<void> {
// Poll for pairing code (15s)
let pairingCode = '';
for (let i = 0; i < 15; i++) {
const statusContent = readFileSafe(statusFile);
if (statusContent === 'already_authenticated') {
emitAuthStatus('pairing-code', 'already_authenticated', 'success');
return;
}
if (statusContent.startsWith('pairing_code:')) {
pairingCode = statusContent.replace('pairing_code:', '');
break;
}
if (statusContent.startsWith('failed:')) {
emitAuthStatus('pairing-code', 'failed', 'failed', {
ERROR: statusContent.replace('failed:', ''),
});
process.exit(1);
}
await sleep(1000);
}
if (!pairingCode) {
emitAuthStatus('pairing-code', 'failed', 'failed', {
ERROR: 'pairing_code_timeout',
});
process.exit(3);
}
// Write to file immediately so callers can read it without waiting for stdout
try {
fs.writeFileSync(
path.join(projectRoot, 'store', 'pairing-code.txt'),
pairingCode,
);
} catch {
/* non-fatal */
}
// Emit pairing code immediately so the caller can display it to the user
emitAuthStatus('pairing-code', 'pairing_code_ready', 'waiting', {
PAIRING_CODE: pairingCode,
});
// Poll for completion (120s)
await pollAuthCompletion(
'pairing-code',
statusFile,
projectRoot,
pairingCode,
);
}
async function pollAuthCompletion(
method: string,
statusFile: string,
projectRoot: string,
pairingCode?: string,
): Promise<void> {
const extra: Record<string, string> = {};
if (pairingCode) extra.PAIRING_CODE = pairingCode;
for (let i = 0; i < 60; i++) {
const content = readFileSafe(statusFile);
if (content === 'authenticated' || content === 'already_authenticated') {
// Write success page if qr-auth.html exists
const htmlPath = path.join(projectRoot, 'store', 'qr-auth.html');
if (fs.existsSync(htmlPath)) {
fs.writeFileSync(htmlPath, SUCCESS_HTML);
}
const phoneNumber = getPhoneNumber(projectRoot);
if (phoneNumber) extra.PHONE_NUMBER = phoneNumber;
emitAuthStatus(method, content, 'success', extra);
return;
}
if (content.startsWith('failed:')) {
const error = content.replace('failed:', '');
emitAuthStatus(method, 'failed', 'failed', { ERROR: error, ...extra });
process.exit(1);
}
await sleep(2000);
}
emitAuthStatus(method, 'failed', 'failed', { ERROR: 'timeout', ...extra });
process.exit(3);
}

View File

@@ -1,950 +0,0 @@
import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
import { EventEmitter } from 'events';
// --- Mocks ---
// Mock config
vi.mock('../config.js', () => ({
STORE_DIR: '/tmp/nanoclaw-test-store',
ASSISTANT_NAME: 'Andy',
ASSISTANT_HAS_OWN_NUMBER: false,
}));
// Mock logger
vi.mock('../logger.js', () => ({
logger: {
debug: vi.fn(),
info: vi.fn(),
warn: vi.fn(),
error: vi.fn(),
},
}));
// Mock db
vi.mock('../db.js', () => ({
getLastGroupSync: vi.fn(() => null),
setLastGroupSync: vi.fn(),
updateChatName: vi.fn(),
}));
// Mock fs
vi.mock('fs', async () => {
const actual = await vi.importActual<typeof import('fs')>('fs');
return {
...actual,
default: {
...actual,
existsSync: vi.fn(() => true),
mkdirSync: vi.fn(),
},
};
});
// Mock child_process (used for osascript notification)
vi.mock('child_process', () => ({
exec: vi.fn(),
}));
// Build a fake WASocket that's an EventEmitter with the methods we need
function createFakeSocket() {
const ev = new EventEmitter();
const sock = {
ev: {
on: (event: string, handler: (...args: unknown[]) => void) => {
ev.on(event, handler);
},
},
user: {
id: '1234567890:1@s.whatsapp.net',
lid: '9876543210:1@lid',
},
sendMessage: vi.fn().mockResolvedValue(undefined),
sendPresenceUpdate: vi.fn().mockResolvedValue(undefined),
groupFetchAllParticipating: vi.fn().mockResolvedValue({}),
end: vi.fn(),
// Expose the event emitter for triggering events in tests
_ev: ev,
};
return sock;
}
let fakeSocket: ReturnType<typeof createFakeSocket>;
// Mock Baileys
vi.mock('@whiskeysockets/baileys', () => {
return {
default: vi.fn(() => fakeSocket),
Browsers: { macOS: vi.fn(() => ['macOS', 'Chrome', '']) },
DisconnectReason: {
loggedOut: 401,
badSession: 500,
connectionClosed: 428,
connectionLost: 408,
connectionReplaced: 440,
timedOut: 408,
restartRequired: 515,
},
fetchLatestWaWebVersion: vi
.fn()
.mockResolvedValue({ version: [2, 3000, 0] }),
normalizeMessageContent: vi.fn((content: unknown) => content),
makeCacheableSignalKeyStore: vi.fn((keys: unknown) => keys),
useMultiFileAuthState: vi.fn().mockResolvedValue({
state: {
creds: {},
keys: {},
},
saveCreds: vi.fn(),
}),
};
});
import { WhatsAppChannel, WhatsAppChannelOpts } from './whatsapp.js';
import { getLastGroupSync, updateChatName, setLastGroupSync } from '../db.js';
// --- Test helpers ---
function createTestOpts(
overrides?: Partial<WhatsAppChannelOpts>,
): WhatsAppChannelOpts {
return {
onMessage: vi.fn(),
onChatMetadata: vi.fn(),
registeredGroups: vi.fn(() => ({
'registered@g.us': {
name: 'Test Group',
folder: 'test-group',
trigger: '@Andy',
added_at: '2024-01-01T00:00:00.000Z',
},
})),
...overrides,
};
}
function triggerConnection(state: string, extra?: Record<string, unknown>) {
fakeSocket._ev.emit('connection.update', { connection: state, ...extra });
}
function triggerDisconnect(statusCode: number) {
fakeSocket._ev.emit('connection.update', {
connection: 'close',
lastDisconnect: {
error: { output: { statusCode } },
},
});
}
async function triggerMessages(messages: unknown[]) {
fakeSocket._ev.emit('messages.upsert', { messages });
// Flush microtasks so the async messages.upsert handler completes
await new Promise((r) => setTimeout(r, 0));
}
// --- Tests ---
describe('WhatsAppChannel', () => {
beforeEach(() => {
fakeSocket = createFakeSocket();
vi.mocked(getLastGroupSync).mockReturnValue(null);
});
afterEach(() => {
vi.restoreAllMocks();
});
/**
* Helper: start connect, flush microtasks so event handlers are registered,
* then trigger the connection open event. Returns the resolved promise.
*/
async function connectChannel(channel: WhatsAppChannel): Promise<void> {
const p = channel.connect();
// Flush microtasks so connectInternal completes its await and registers handlers
await new Promise((r) => setTimeout(r, 0));
triggerConnection('open');
return p;
}
// --- Version fetch ---
describe('version fetch', () => {
it('connects with fetched version', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
const { fetchLatestWaWebVersion } =
await import('@whiskeysockets/baileys');
expect(fetchLatestWaWebVersion).toHaveBeenCalledWith({});
});
it('falls back gracefully when version fetch fails', async () => {
const { fetchLatestWaWebVersion } =
await import('@whiskeysockets/baileys');
vi.mocked(fetchLatestWaWebVersion).mockRejectedValueOnce(
new Error('network error'),
);
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Should still connect successfully despite fetch failure
expect(channel.isConnected()).toBe(true);
});
});
// --- Connection lifecycle ---
describe('connection lifecycle', () => {
it('resolves connect() when connection opens', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
expect(channel.isConnected()).toBe(true);
});
it('sets up LID to phone mapping on open', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// The channel should have mapped the LID from sock.user
// We can verify by sending a message from a LID JID
// and checking the translated JID in the callback
});
it('flushes outgoing queue on reconnect', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Disconnect
(channel as any).connected = false;
// Queue a message while disconnected
await channel.sendMessage('test@g.us', 'Queued message');
expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
// Reconnect
(channel as any).connected = true;
await (channel as any).flushOutgoingQueue();
// Group messages get prefixed when flushed
expect(fakeSocket.sendMessage).toHaveBeenCalledWith('test@g.us', {
text: 'Andy: Queued message',
});
});
it('disconnects cleanly', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.disconnect();
expect(channel.isConnected()).toBe(false);
expect(fakeSocket.end).toHaveBeenCalled();
});
});
// --- QR code and auth ---
describe('authentication', () => {
it('exits process when QR code is emitted (no auth state)', async () => {
vi.useFakeTimers();
const mockExit = vi
.spyOn(process, 'exit')
.mockImplementation(() => undefined as never);
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
// Start connect but don't await (it won't resolve - process exits)
channel.connect().catch(() => {});
// Flush microtasks so connectInternal registers handlers
await vi.advanceTimersByTimeAsync(0);
// Emit QR code event
fakeSocket._ev.emit('connection.update', { qr: 'some-qr-data' });
// Advance timer past the 1000ms setTimeout before exit
await vi.advanceTimersByTimeAsync(1500);
expect(mockExit).toHaveBeenCalledWith(1);
mockExit.mockRestore();
vi.useRealTimers();
});
});
// --- Reconnection behavior ---
describe('reconnection', () => {
it('reconnects on non-loggedOut disconnect', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
expect(channel.isConnected()).toBe(true);
// Disconnect with a non-loggedOut reason (e.g., connectionClosed = 428)
triggerDisconnect(428);
expect(channel.isConnected()).toBe(false);
// The channel should attempt to reconnect (calls connectInternal again)
});
it('exits on loggedOut disconnect', async () => {
const mockExit = vi
.spyOn(process, 'exit')
.mockImplementation(() => undefined as never);
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Disconnect with loggedOut reason (401)
triggerDisconnect(401);
expect(channel.isConnected()).toBe(false);
expect(mockExit).toHaveBeenCalledWith(0);
mockExit.mockRestore();
});
it('retries reconnection after 5s on failure', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Disconnect with stream error 515
triggerDisconnect(515);
// The channel sets a 5s retry — just verify it doesn't crash
await new Promise((r) => setTimeout(r, 100));
});
});
// --- Message handling ---
describe('message handling', () => {
it('delivers message for registered group', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-1',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: { conversation: 'Hello Andy' },
pushName: 'Alice',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onChatMetadata).toHaveBeenCalledWith(
'registered@g.us',
expect.any(String),
undefined,
'whatsapp',
true,
);
expect(opts.onMessage).toHaveBeenCalledWith(
'registered@g.us',
expect.objectContaining({
id: 'msg-1',
content: 'Hello Andy',
sender_name: 'Alice',
is_from_me: false,
}),
);
});
it('only emits metadata for unregistered groups', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-2',
remoteJid: 'unregistered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: { conversation: 'Hello' },
pushName: 'Bob',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onChatMetadata).toHaveBeenCalledWith(
'unregistered@g.us',
expect.any(String),
undefined,
'whatsapp',
true,
);
expect(opts.onMessage).not.toHaveBeenCalled();
});
it('ignores status@broadcast messages', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-3',
remoteJid: 'status@broadcast',
fromMe: false,
},
message: { conversation: 'Status update' },
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onChatMetadata).not.toHaveBeenCalled();
expect(opts.onMessage).not.toHaveBeenCalled();
});
it('ignores messages with no content', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-4',
remoteJid: 'registered@g.us',
fromMe: false,
},
message: null,
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onMessage).not.toHaveBeenCalled();
});
it('extracts text from extendedTextMessage', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-5',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: {
extendedTextMessage: { text: 'A reply message' },
},
pushName: 'Charlie',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onMessage).toHaveBeenCalledWith(
'registered@g.us',
expect.objectContaining({ content: 'A reply message' }),
);
});
it('extracts caption from imageMessage', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-6',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: {
imageMessage: {
caption: 'Check this photo',
mimetype: 'image/jpeg',
},
},
pushName: 'Diana',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onMessage).toHaveBeenCalledWith(
'registered@g.us',
expect.objectContaining({ content: 'Check this photo' }),
);
});
it('extracts caption from videoMessage', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-7',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: {
videoMessage: { caption: 'Watch this', mimetype: 'video/mp4' },
},
pushName: 'Eve',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onMessage).toHaveBeenCalledWith(
'registered@g.us',
expect.objectContaining({ content: 'Watch this' }),
);
});
it('handles message with no extractable text (e.g. voice note without caption)', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-8',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: {
audioMessage: { mimetype: 'audio/ogg; codecs=opus', ptt: true },
},
pushName: 'Frank',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
// Skipped — no text content to process
expect(opts.onMessage).not.toHaveBeenCalled();
});
it('uses sender JID when pushName is absent', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-9',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: { conversation: 'No push name' },
// pushName is undefined
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onMessage).toHaveBeenCalledWith(
'registered@g.us',
expect.objectContaining({ sender_name: '5551234' }),
);
});
});
// --- LID ↔ JID translation ---
describe('LID to JID translation', () => {
it('translates known LID to phone JID', async () => {
const opts = createTestOpts({
registeredGroups: vi.fn(() => ({
'1234567890@s.whatsapp.net': {
name: 'Self Chat',
folder: 'self-chat',
trigger: '@Andy',
added_at: '2024-01-01T00:00:00.000Z',
},
})),
});
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// The socket has lid '9876543210:1@lid' → phone '1234567890@s.whatsapp.net'
// Send a message from the LID
await triggerMessages([
{
key: {
id: 'msg-lid',
remoteJid: '9876543210@lid',
fromMe: false,
},
message: { conversation: 'From LID' },
pushName: 'Self',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
// Should be translated to phone JID
expect(opts.onChatMetadata).toHaveBeenCalledWith(
'1234567890@s.whatsapp.net',
expect.any(String),
undefined,
'whatsapp',
false,
);
});
it('passes through non-LID JIDs unchanged', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-normal',
remoteJid: 'registered@g.us',
participant: '5551234@s.whatsapp.net',
fromMe: false,
},
message: { conversation: 'Normal JID' },
pushName: 'Grace',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
expect(opts.onChatMetadata).toHaveBeenCalledWith(
'registered@g.us',
expect.any(String),
undefined,
'whatsapp',
true,
);
});
it('passes through unknown LID JIDs unchanged', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await triggerMessages([
{
key: {
id: 'msg-unknown-lid',
remoteJid: '0000000000@lid',
fromMe: false,
},
message: { conversation: 'Unknown LID' },
pushName: 'Unknown',
messageTimestamp: Math.floor(Date.now() / 1000),
},
]);
// Unknown LID passes through unchanged
expect(opts.onChatMetadata).toHaveBeenCalledWith(
'0000000000@lid',
expect.any(String),
undefined,
'whatsapp',
false,
);
});
});
// --- Outgoing message queue ---
describe('outgoing message queue', () => {
it('sends message directly when connected', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.sendMessage('test@g.us', 'Hello');
// Group messages get prefixed with assistant name
expect(fakeSocket.sendMessage).toHaveBeenCalledWith('test@g.us', {
text: 'Andy: Hello',
});
});
it('prefixes direct chat messages on shared number', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.sendMessage('123@s.whatsapp.net', 'Hello');
// Shared number: DMs also get prefixed (needed for self-chat distinction)
expect(fakeSocket.sendMessage).toHaveBeenCalledWith(
'123@s.whatsapp.net',
{ text: 'Andy: Hello' },
);
});
it('queues message when disconnected', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
// Don't connect — channel starts disconnected
await channel.sendMessage('test@g.us', 'Queued');
expect(fakeSocket.sendMessage).not.toHaveBeenCalled();
});
it('queues message on send failure', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Make sendMessage fail
fakeSocket.sendMessage.mockRejectedValueOnce(new Error('Network error'));
await channel.sendMessage('test@g.us', 'Will fail');
// Should not throw, message queued for retry
// The queue should have the message
});
it('flushes multiple queued messages in order', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
// Queue messages while disconnected
await channel.sendMessage('test@g.us', 'First');
await channel.sendMessage('test@g.us', 'Second');
await channel.sendMessage('test@g.us', 'Third');
// Connect — flush happens automatically on open
await connectChannel(channel);
// Give the async flush time to complete
await new Promise((r) => setTimeout(r, 50));
expect(fakeSocket.sendMessage).toHaveBeenCalledTimes(3);
// Group messages get prefixed
expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(1, 'test@g.us', {
text: 'Andy: First',
});
expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(2, 'test@g.us', {
text: 'Andy: Second',
});
expect(fakeSocket.sendMessage).toHaveBeenNthCalledWith(3, 'test@g.us', {
text: 'Andy: Third',
});
});
});
// --- Group metadata sync ---
describe('group metadata sync', () => {
it('syncs group metadata on first connection', async () => {
fakeSocket.groupFetchAllParticipating.mockResolvedValue({
'group1@g.us': { subject: 'Group One' },
'group2@g.us': { subject: 'Group Two' },
});
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Wait for async sync to complete
await new Promise((r) => setTimeout(r, 50));
expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Group One');
expect(updateChatName).toHaveBeenCalledWith('group2@g.us', 'Group Two');
expect(setLastGroupSync).toHaveBeenCalled();
});
it('skips sync when synced recently', async () => {
// Last sync was 1 hour ago (within 24h threshold)
vi.mocked(getLastGroupSync).mockReturnValue(
new Date(Date.now() - 60 * 60 * 1000).toISOString(),
);
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await new Promise((r) => setTimeout(r, 50));
expect(fakeSocket.groupFetchAllParticipating).not.toHaveBeenCalled();
});
it('forces sync regardless of cache', async () => {
vi.mocked(getLastGroupSync).mockReturnValue(
new Date(Date.now() - 60 * 60 * 1000).toISOString(),
);
fakeSocket.groupFetchAllParticipating.mockResolvedValue({
'group@g.us': { subject: 'Forced Group' },
});
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.syncGroupMetadata(true);
expect(fakeSocket.groupFetchAllParticipating).toHaveBeenCalled();
expect(updateChatName).toHaveBeenCalledWith('group@g.us', 'Forced Group');
});
it('handles group sync failure gracefully', async () => {
fakeSocket.groupFetchAllParticipating.mockRejectedValue(
new Error('Network timeout'),
);
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Should not throw
await expect(channel.syncGroupMetadata(true)).resolves.toBeUndefined();
});
it('skips groups with no subject', async () => {
fakeSocket.groupFetchAllParticipating.mockResolvedValue({
'group1@g.us': { subject: 'Has Subject' },
'group2@g.us': { subject: '' },
'group3@g.us': {},
});
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
// Clear any calls from the automatic sync on connect
vi.mocked(updateChatName).mockClear();
await channel.syncGroupMetadata(true);
expect(updateChatName).toHaveBeenCalledTimes(1);
expect(updateChatName).toHaveBeenCalledWith('group1@g.us', 'Has Subject');
});
});
// --- JID ownership ---
describe('ownsJid', () => {
it('owns @g.us JIDs (WhatsApp groups)', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect(channel.ownsJid('12345@g.us')).toBe(true);
});
it('owns @s.whatsapp.net JIDs (WhatsApp DMs)', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect(channel.ownsJid('12345@s.whatsapp.net')).toBe(true);
});
it('does not own Telegram JIDs', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect(channel.ownsJid('tg:12345')).toBe(false);
});
it('does not own unknown JID formats', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect(channel.ownsJid('random-string')).toBe(false);
});
});
// --- Typing indicator ---
describe('setTyping', () => {
it('sends composing presence when typing', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.setTyping('test@g.us', true);
expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith(
'composing',
'test@g.us',
);
});
it('sends paused presence when stopping', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
await channel.setTyping('test@g.us', false);
expect(fakeSocket.sendPresenceUpdate).toHaveBeenCalledWith(
'paused',
'test@g.us',
);
});
it('handles typing indicator failure gracefully', async () => {
const opts = createTestOpts();
const channel = new WhatsAppChannel(opts);
await connectChannel(channel);
fakeSocket.sendPresenceUpdate.mockRejectedValueOnce(new Error('Failed'));
// Should not throw
await expect(
channel.setTyping('test@g.us', true),
).resolves.toBeUndefined();
});
});
// --- Channel properties ---
describe('channel properties', () => {
it('has name "whatsapp"', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect(channel.name).toBe('whatsapp');
});
it('does not expose prefixAssistantName (prefix handled internally)', () => {
const channel = new WhatsAppChannel(createTestOpts());
expect('prefixAssistantName' in channel).toBe(false);
});
});
});

View File

@@ -1,398 +0,0 @@
import { exec } from 'child_process';
import fs from 'fs';
import path from 'path';
import makeWASocket, {
Browsers,
DisconnectReason,
WASocket,
fetchLatestWaWebVersion,
makeCacheableSignalKeyStore,
normalizeMessageContent,
useMultiFileAuthState,
} from '@whiskeysockets/baileys';
import {
ASSISTANT_HAS_OWN_NUMBER,
ASSISTANT_NAME,
STORE_DIR,
} from '../config.js';
import { getLastGroupSync, setLastGroupSync, updateChatName } from '../db.js';
import { logger } from '../logger.js';
import {
Channel,
OnInboundMessage,
OnChatMetadata,
RegisteredGroup,
} from '../types.js';
import { registerChannel, ChannelOpts } from './registry.js';
const GROUP_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
export interface WhatsAppChannelOpts {
onMessage: OnInboundMessage;
onChatMetadata: OnChatMetadata;
registeredGroups: () => Record<string, RegisteredGroup>;
}
export class WhatsAppChannel implements Channel {
name = 'whatsapp';
private sock!: WASocket;
private connected = false;
private lidToPhoneMap: Record<string, string> = {};
private outgoingQueue: Array<{ jid: string; text: string }> = [];
private flushing = false;
private groupSyncTimerStarted = false;
private opts: WhatsAppChannelOpts;
constructor(opts: WhatsAppChannelOpts) {
this.opts = opts;
}
async connect(): Promise<void> {
return new Promise<void>((resolve, reject) => {
this.connectInternal(resolve).catch(reject);
});
}
private async connectInternal(onFirstOpen?: () => void): Promise<void> {
const authDir = path.join(STORE_DIR, 'auth');
fs.mkdirSync(authDir, { recursive: true });
const { state, saveCreds } = await useMultiFileAuthState(authDir);
const { version } = await fetchLatestWaWebVersion({}).catch((err) => {
logger.warn(
{ err },
'Failed to fetch latest WA Web version, using default',
);
return { version: undefined };
});
this.sock = makeWASocket({
version,
auth: {
creds: state.creds,
keys: makeCacheableSignalKeyStore(state.keys, logger),
},
printQRInTerminal: false,
logger,
browser: Browsers.macOS('Chrome'),
});
this.sock.ev.on('connection.update', (update) => {
const { connection, lastDisconnect, qr } = update;
if (qr) {
const msg =
'WhatsApp authentication required. Run /setup in Claude Code.';
logger.error(msg);
exec(
`osascript -e 'display notification "${msg}" with title "NanoClaw" sound name "Basso"'`,
);
setTimeout(() => process.exit(1), 1000);
}
if (connection === 'close') {
this.connected = false;
const reason = (
lastDisconnect?.error as { output?: { statusCode?: number } }
)?.output?.statusCode;
const shouldReconnect = reason !== DisconnectReason.loggedOut;
logger.info(
{
reason,
shouldReconnect,
queuedMessages: this.outgoingQueue.length,
},
'Connection closed',
);
if (shouldReconnect) {
logger.info('Reconnecting...');
this.connectInternal().catch((err) => {
logger.error({ err }, 'Failed to reconnect, retrying in 5s');
setTimeout(() => {
this.connectInternal().catch((err2) => {
logger.error({ err: err2 }, 'Reconnection retry failed');
});
}, 5000);
});
} else {
logger.info('Logged out. Run /setup to re-authenticate.');
process.exit(0);
}
} else if (connection === 'open') {
this.connected = true;
logger.info('Connected to WhatsApp');
// Announce availability so WhatsApp relays subsequent presence updates (typing indicators)
this.sock.sendPresenceUpdate('available').catch((err) => {
logger.warn({ err }, 'Failed to send presence update');
});
// Build LID to phone mapping from auth state for self-chat translation
if (this.sock.user) {
const phoneUser = this.sock.user.id.split(':')[0];
const lidUser = this.sock.user.lid?.split(':')[0];
if (lidUser && phoneUser) {
this.lidToPhoneMap[lidUser] = `${phoneUser}@s.whatsapp.net`;
logger.debug({ lidUser, phoneUser }, 'LID to phone mapping set');
}
}
// Flush any messages queued while disconnected
this.flushOutgoingQueue().catch((err) =>
logger.error({ err }, 'Failed to flush outgoing queue'),
);
// Sync group metadata on startup (respects 24h cache)
this.syncGroupMetadata().catch((err) =>
logger.error({ err }, 'Initial group sync failed'),
);
// Set up daily sync timer (only once)
if (!this.groupSyncTimerStarted) {
this.groupSyncTimerStarted = true;
setInterval(() => {
this.syncGroupMetadata().catch((err) =>
logger.error({ err }, 'Periodic group sync failed'),
);
}, GROUP_SYNC_INTERVAL_MS);
}
// Signal first connection to caller
if (onFirstOpen) {
onFirstOpen();
onFirstOpen = undefined;
}
}
});
this.sock.ev.on('creds.update', saveCreds);
this.sock.ev.on('messages.upsert', async ({ messages }) => {
for (const msg of messages) {
try {
if (!msg.message) continue;
// Unwrap container types (viewOnceMessageV2, ephemeralMessage,
// editedMessage, etc.) so that conversation, extendedTextMessage,
// imageMessage, etc. are accessible at the top level.
const normalized = normalizeMessageContent(msg.message);
if (!normalized) continue;
const rawJid = msg.key.remoteJid;
if (!rawJid || rawJid === 'status@broadcast') continue;
// Translate LID JID to phone JID if applicable
const chatJid = await this.translateJid(rawJid);
const timestamp = new Date(
Number(msg.messageTimestamp) * 1000,
).toISOString();
// Always notify about chat metadata for group discovery
const isGroup = chatJid.endsWith('@g.us');
this.opts.onChatMetadata(
chatJid,
timestamp,
undefined,
'whatsapp',
isGroup,
);
// Only deliver full message for registered groups
const groups = this.opts.registeredGroups();
if (groups[chatJid]) {
const content =
normalized.conversation ||
normalized.extendedTextMessage?.text ||
normalized.imageMessage?.caption ||
normalized.videoMessage?.caption ||
'';
// Skip protocol messages with no text content (encryption keys, read receipts, etc.)
if (!content) continue;
const sender = msg.key.participant || msg.key.remoteJid || '';
const senderName = msg.pushName || sender.split('@')[0];
const fromMe = msg.key.fromMe || false;
// Detect bot messages: with own number, fromMe is reliable
// since only the bot sends from that number.
// With shared number, bot messages carry the assistant name prefix
// (even in DMs/self-chat) so we check for that.
const isBotMessage = ASSISTANT_HAS_OWN_NUMBER
? fromMe
: content.startsWith(`${ASSISTANT_NAME}:`);
this.opts.onMessage(chatJid, {
id: msg.key.id || '',
chat_jid: chatJid,
sender,
sender_name: senderName,
content,
timestamp,
is_from_me: fromMe,
is_bot_message: isBotMessage,
});
}
} catch (err) {
logger.error(
{ err, remoteJid: msg.key?.remoteJid },
'Error processing incoming message',
);
}
}
});
}
async sendMessage(jid: string, text: string): Promise<void> {
// Prefix bot messages with assistant name so users know who's speaking.
// On a shared number, prefix is also needed in DMs (including self-chat)
// to distinguish bot output from user messages.
// Skip only when the assistant has its own dedicated phone number.
const prefixed = ASSISTANT_HAS_OWN_NUMBER
? text
: `${ASSISTANT_NAME}: ${text}`;
if (!this.connected) {
this.outgoingQueue.push({ jid, text: prefixed });
logger.info(
{ jid, length: prefixed.length, queueSize: this.outgoingQueue.length },
'WA disconnected, message queued',
);
return;
}
try {
await this.sock.sendMessage(jid, { text: prefixed });
logger.info({ jid, length: prefixed.length }, 'Message sent');
} catch (err) {
// If send fails, queue it for retry on reconnect
this.outgoingQueue.push({ jid, text: prefixed });
logger.warn(
{ jid, err, queueSize: this.outgoingQueue.length },
'Failed to send, message queued',
);
}
}
isConnected(): boolean {
return this.connected;
}
ownsJid(jid: string): boolean {
return jid.endsWith('@g.us') || jid.endsWith('@s.whatsapp.net');
}
async disconnect(): Promise<void> {
this.connected = false;
this.sock?.end(undefined);
}
async setTyping(jid: string, isTyping: boolean): Promise<void> {
try {
const status = isTyping ? 'composing' : 'paused';
logger.debug({ jid, status }, 'Sending presence update');
await this.sock.sendPresenceUpdate(status, jid);
} catch (err) {
logger.debug({ jid, err }, 'Failed to update typing status');
}
}
async syncGroups(force: boolean): Promise<void> {
return this.syncGroupMetadata(force);
}
/**
* Sync group metadata from WhatsApp.
* Fetches all participating groups and stores their names in the database.
* Called on startup, daily, and on-demand via IPC.
*/
async syncGroupMetadata(force = false): Promise<void> {
if (!force) {
const lastSync = getLastGroupSync();
if (lastSync) {
const lastSyncTime = new Date(lastSync).getTime();
if (Date.now() - lastSyncTime < GROUP_SYNC_INTERVAL_MS) {
logger.debug({ lastSync }, 'Skipping group sync - synced recently');
return;
}
}
}
try {
logger.info('Syncing group metadata from WhatsApp...');
const groups = await this.sock.groupFetchAllParticipating();
let count = 0;
for (const [jid, metadata] of Object.entries(groups)) {
if (metadata.subject) {
updateChatName(jid, metadata.subject);
count++;
}
}
setLastGroupSync();
logger.info({ count }, 'Group metadata synced');
} catch (err) {
logger.error({ err }, 'Failed to sync group metadata');
}
}
private async translateJid(jid: string): Promise<string> {
if (!jid.endsWith('@lid')) return jid;
const lidUser = jid.split('@')[0].split(':')[0];
// Check local cache first
const cached = this.lidToPhoneMap[lidUser];
if (cached) {
logger.debug(
{ lidJid: jid, phoneJid: cached },
'Translated LID to phone JID (cached)',
);
return cached;
}
// Query Baileys' signal repository for the mapping
try {
const pn = await this.sock.signalRepository?.lidMapping?.getPNForLID(jid);
if (pn) {
const phoneJid = `${pn.split('@')[0].split(':')[0]}@s.whatsapp.net`;
this.lidToPhoneMap[lidUser] = phoneJid;
logger.info(
{ lidJid: jid, phoneJid },
'Translated LID to phone JID (signalRepository)',
);
return phoneJid;
}
} catch (err) {
logger.debug({ err, jid }, 'Failed to resolve LID via signalRepository');
}
return jid;
}
private async flushOutgoingQueue(): Promise<void> {
if (this.flushing || this.outgoingQueue.length === 0) return;
this.flushing = true;
try {
logger.info(
{ count: this.outgoingQueue.length },
'Flushing outgoing message queue',
);
while (this.outgoingQueue.length > 0) {
const item = this.outgoingQueue.shift()!;
// Send directly — queued items are already prefixed by sendMessage
await this.sock.sendMessage(item.jid, { text: item.text });
logger.info(
{ jid: item.jid, length: item.text.length },
'Queued message sent',
);
}
} finally {
this.flushing = false;
}
}
}
registerChannel('whatsapp', (opts: ChannelOpts) => new WhatsAppChannel(opts));

View File

@@ -1,180 +0,0 @@
/**
* WhatsApp Authentication Script
*
* Run this during setup to authenticate with WhatsApp.
* Displays QR code, waits for scan, saves credentials, then exits.
*
* Usage: npx tsx src/whatsapp-auth.ts
*/
import fs from 'fs';
import path from 'path';
import pino from 'pino';
import qrcode from 'qrcode-terminal';
import readline from 'readline';
import makeWASocket, {
Browsers,
DisconnectReason,
fetchLatestWaWebVersion,
makeCacheableSignalKeyStore,
useMultiFileAuthState,
} from '@whiskeysockets/baileys';
const AUTH_DIR = './store/auth';
const QR_FILE = './store/qr-data.txt';
const STATUS_FILE = './store/auth-status.txt';
const logger = pino({
level: 'warn', // Quiet logging - only show errors
});
// Check for --pairing-code flag and phone number
const usePairingCode = process.argv.includes('--pairing-code');
const phoneArg = process.argv.find((_, i, arr) => arr[i - 1] === '--phone');
function askQuestion(prompt: string): Promise<string> {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
return new Promise((resolve) => {
rl.question(prompt, (answer) => {
rl.close();
resolve(answer.trim());
});
});
}
async function connectSocket(
phoneNumber?: string,
isReconnect = false,
): Promise<void> {
const { state, saveCreds } = await useMultiFileAuthState(AUTH_DIR);
if (state.creds.registered && !isReconnect) {
fs.writeFileSync(STATUS_FILE, 'already_authenticated');
console.log('✓ Already authenticated with WhatsApp');
console.log(
' To re-authenticate, delete the store/auth folder and run again.',
);
process.exit(0);
}
const { version } = await fetchLatestWaWebVersion({}).catch((err) => {
logger.warn(
{ err },
'Failed to fetch latest WA Web version, using default',
);
return { version: undefined };
});
const sock = makeWASocket({
version,
auth: {
creds: state.creds,
keys: makeCacheableSignalKeyStore(state.keys, logger),
},
printQRInTerminal: false,
logger,
browser: Browsers.macOS('Chrome'),
});
if (usePairingCode && phoneNumber && !state.creds.me) {
// Request pairing code after a short delay for connection to initialize
// Only on first connect (not reconnect after 515)
setTimeout(async () => {
try {
const code = await sock.requestPairingCode(phoneNumber!);
console.log(`\n🔗 Your pairing code: ${code}\n`);
console.log(' 1. Open WhatsApp on your phone');
console.log(' 2. Tap Settings → Linked Devices → Link a Device');
console.log(' 3. Tap "Link with phone number instead"');
console.log(` 4. Enter this code: ${code}\n`);
fs.writeFileSync(STATUS_FILE, `pairing_code:${code}`);
} catch (err: any) {
console.error('Failed to request pairing code:', err.message);
process.exit(1);
}
}, 3000);
}
sock.ev.on('connection.update', (update) => {
const { connection, lastDisconnect, qr } = update;
if (qr) {
// Write raw QR data to file so the setup skill can render it
fs.writeFileSync(QR_FILE, qr);
console.log('Scan this QR code with WhatsApp:\n');
console.log(' 1. Open WhatsApp on your phone');
console.log(' 2. Tap Settings → Linked Devices → Link a Device');
console.log(' 3. Point your camera at the QR code below\n');
qrcode.generate(qr, { small: true });
}
if (connection === 'close') {
const reason = (lastDisconnect?.error as any)?.output?.statusCode;
if (reason === DisconnectReason.loggedOut) {
fs.writeFileSync(STATUS_FILE, 'failed:logged_out');
console.log('\n✗ Logged out. Delete store/auth and try again.');
process.exit(1);
} else if (reason === DisconnectReason.timedOut) {
fs.writeFileSync(STATUS_FILE, 'failed:qr_timeout');
console.log('\n✗ QR code timed out. Please try again.');
process.exit(1);
} else if (reason === 515) {
// 515 = stream error, often happens after pairing succeeds but before
// registration completes. Reconnect to finish the handshake.
console.log('\n⟳ Stream error (515) after pairing — reconnecting...');
connectSocket(phoneNumber, true);
} else {
fs.writeFileSync(STATUS_FILE, `failed:${reason || 'unknown'}`);
console.log('\n✗ Connection failed. Please try again.');
process.exit(1);
}
}
if (connection === 'open') {
fs.writeFileSync(STATUS_FILE, 'authenticated');
// Clean up QR file now that we're connected
try {
fs.unlinkSync(QR_FILE);
} catch {}
console.log('\n✓ Successfully authenticated with WhatsApp!');
console.log(' Credentials saved to store/auth/');
console.log(' You can now start the NanoClaw service.\n');
// Give it a moment to save credentials, then exit
setTimeout(() => process.exit(0), 1000);
}
});
sock.ev.on('creds.update', saveCreds);
}
async function authenticate(): Promise<void> {
fs.mkdirSync(AUTH_DIR, { recursive: true });
// Clean up any stale QR/status files from previous runs
try {
fs.unlinkSync(QR_FILE);
} catch {}
try {
fs.unlinkSync(STATUS_FILE);
} catch {}
let phoneNumber = phoneArg;
if (usePairingCode && !phoneNumber) {
phoneNumber = await askQuestion(
'Enter your phone number (with country code, no + or spaces, e.g. 14155551234): ',
);
}
console.log('Starting WhatsApp authentication...\n');
await connectSocket(phoneNumber);
}
authenticate().catch((err) => {
console.error('Authentication failed:', err.message);
process.exit(1);
});

View File

@@ -1,23 +0,0 @@
skill: whatsapp
version: 1.0.0
description: "WhatsApp channel via Baileys (Multi-Device Web API)"
core_version: 0.1.0
adds:
- src/channels/whatsapp.ts
- src/channels/whatsapp.test.ts
- src/whatsapp-auth.ts
- setup/whatsapp-auth.ts
modifies:
- src/channels/index.ts
- setup/index.ts
structured:
npm_dependencies:
"@whiskeysockets/baileys": "^7.0.0-rc.9"
"qrcode": "^1.5.4"
"qrcode-terminal": "^0.12.0"
"@types/qrcode-terminal": "^0.12.0"
env_additions:
- ASSISTANT_HAS_OWN_NUMBER
conflicts: []
depends: []
test: "npx vitest run src/channels/whatsapp.test.ts"

View File

@@ -1,60 +0,0 @@
/**
* Setup CLI entry point.
* Usage: npx tsx setup/index.ts --step <name> [args...]
*/
import { logger } from '../src/logger.js';
import { emitStatus } from './status.js';
const STEPS: Record<
string,
() => Promise<{ run: (args: string[]) => Promise<void> }>
> = {
environment: () => import('./environment.js'),
channels: () => import('./channels.js'),
container: () => import('./container.js'),
'whatsapp-auth': () => import('./whatsapp-auth.js'),
groups: () => import('./groups.js'),
register: () => import('./register.js'),
mounts: () => import('./mounts.js'),
service: () => import('./service.js'),
verify: () => import('./verify.js'),
};
async function main(): Promise<void> {
const args = process.argv.slice(2);
const stepIdx = args.indexOf('--step');
if (stepIdx === -1 || !args[stepIdx + 1]) {
console.error(
`Usage: npx tsx setup/index.ts --step <${Object.keys(STEPS).join('|')}> [args...]`,
);
process.exit(1);
}
const stepName = args[stepIdx + 1];
const stepArgs = args.filter(
(a, i) => i !== stepIdx && i !== stepIdx + 1 && a !== '--',
);
const loader = STEPS[stepName];
if (!loader) {
console.error(`Unknown step: ${stepName}`);
console.error(`Available steps: ${Object.keys(STEPS).join(', ')}`);
process.exit(1);
}
try {
const mod = await loader();
await mod.run(stepArgs);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
logger.error({ err, step: stepName }, 'Setup step failed');
emitStatus(stepName.toUpperCase(), {
STATUS: 'failed',
ERROR: message,
});
process.exit(1);
}
}
main();

View File

@@ -1 +0,0 @@
Add `'whatsapp-auth': () => import('./whatsapp-auth.js'),` to the setup STEPS map so the WhatsApp authentication step is available during setup.

View File

@@ -1,13 +0,0 @@
// Channel self-registration barrel file.
// Each import triggers the channel module's registerChannel() call.
// discord
// gmail
// slack
// telegram
// whatsapp
import './whatsapp.js';

View File

@@ -1,7 +0,0 @@
# Intent: Add WhatsApp channel import
Add `import './whatsapp.js';` to the channel barrel file so the WhatsApp
module self-registers with the channel registry on startup.
This is an append-only change — existing import lines for other channels
must be preserved.

View File

@@ -1,70 +0,0 @@
import { describe, expect, it } from 'vitest';
import fs from 'fs';
import path from 'path';
describe('whatsapp skill package', () => {
const skillDir = path.resolve(__dirname, '..');
it('has a valid manifest', () => {
const manifestPath = path.join(skillDir, 'manifest.yaml');
expect(fs.existsSync(manifestPath)).toBe(true);
const content = fs.readFileSync(manifestPath, 'utf-8');
expect(content).toContain('skill: whatsapp');
expect(content).toContain('version: 1.0.0');
expect(content).toContain('@whiskeysockets/baileys');
});
it('has all files declared in adds', () => {
const channelFile = path.join(skillDir, 'add', 'src', 'channels', 'whatsapp.ts');
expect(fs.existsSync(channelFile)).toBe(true);
const content = fs.readFileSync(channelFile, 'utf-8');
expect(content).toContain('class WhatsAppChannel');
expect(content).toContain('implements Channel');
expect(content).toContain("registerChannel('whatsapp'");
// Test file for the channel
const testFile = path.join(skillDir, 'add', 'src', 'channels', 'whatsapp.test.ts');
expect(fs.existsSync(testFile)).toBe(true);
const testContent = fs.readFileSync(testFile, 'utf-8');
expect(testContent).toContain("describe('WhatsAppChannel'");
// Auth script (runtime)
const authFile = path.join(skillDir, 'add', 'src', 'whatsapp-auth.ts');
expect(fs.existsSync(authFile)).toBe(true);
// Auth setup step
const setupAuthFile = path.join(skillDir, 'add', 'setup', 'whatsapp-auth.ts');
expect(fs.existsSync(setupAuthFile)).toBe(true);
const setupAuthContent = fs.readFileSync(setupAuthFile, 'utf-8');
expect(setupAuthContent).toContain('WhatsApp interactive auth');
});
it('has all files declared in modifies', () => {
// Channel barrel file
const indexFile = path.join(skillDir, 'modify', 'src', 'channels', 'index.ts');
expect(fs.existsSync(indexFile)).toBe(true);
const indexContent = fs.readFileSync(indexFile, 'utf-8');
expect(indexContent).toContain("import './whatsapp.js'");
// Setup index (adds whatsapp-auth step)
const setupIndexFile = path.join(skillDir, 'modify', 'setup', 'index.ts');
expect(fs.existsSync(setupIndexFile)).toBe(true);
const setupIndexContent = fs.readFileSync(setupIndexFile, 'utf-8');
expect(setupIndexContent).toContain("'whatsapp-auth'");
});
it('has intent files for modified files', () => {
expect(
fs.existsSync(path.join(skillDir, 'modify', 'src', 'channels', 'index.ts.intent.md')),
).toBe(true);
expect(
fs.existsSync(path.join(skillDir, 'modify', 'setup', 'index.ts.intent.md')),
).toBe(true);
});
});