whatsapp-pi 1.0.21 → 1.0.23

package/README.md

@@ -18,14 +18,22 @@ Pi is a powerful agentic AI coding assistant that operates in your terminal. Thi
   - View ignored numbers (not in allow list) and add them when needed
 - **Reliable Messaging**: Queue-based message sending with retry logic
 - **TUI Integration**: Menu-driven interface for managing connections and contacts
+- **Media Support**: 
+  - **Vision Analysis**: Automatically forwards WhatsApp images to Pi for analysis.
+  - **Document Handling**: Downloads and stores documents (PDF, text) for agent access.
 
 ## Prerequisites
 
-To enable audio features, you need to install OpenAI Whisper:
+To enable audio transcription features:
 ```bash
 python -m pip install -U openai-whisper
 ```
 
+To enable PDF reading capabilities (required for the agent to process documents):
+- **Linux**: `sudo apt-get install poppler-utils`
+- **macOS**: `brew install poppler`
+- **Windows**: Install `poppler` (e.g., via Scoop) and add to PATH.
+
 ## Quick Start
 
 1. Install the extension:
@@ -108,6 +116,11 @@ See `specs/` directory for detailed feature documentation:
 - `002-manual-whatsapp-connection/` - Connection management
 - `003-whatsapp-messaging-refactor/` - Reliable messaging
 - `004-blocked-numbers-management/` - Block list feature
+- `005-verbose-mode-support/` - Logging and tracing
+- `006-auto-connect-flag/` - Automatic connection support
+- `007-image-recognition/` - Vision analysis integration
+- `008-document-message-support/` - Document handling and storage
+- `009-localize-system-messages/` - US English localization
 
 ## Development
 
@@ -116,7 +129,17 @@ Run tests:
 npm test
 ```
 
-Lint:
-```bash
-npm run lint
-```
+## Implementation Notes
+
+### Recent Feature Updates (2026-04)
+
+- **Auto-Connect Support**: Use the `--whatsapp-pi-online` flag to automatically connect to WhatsApp on startup if you have a valid active session.
+- **Vision Analysis**: Images sent via WhatsApp are automatically downloaded and forwarded to the Pi agent as base64, enabling vision-based interactions.
+- **Document Message Support**: 
+  - WhatsApp documents (PDFs, text files, etc.) are downloaded and saved to `./.pi-data/whatsapp/documents/`.
+  - The Pi agent receives a notification with the file path and metadata.
+- **Full US-English Localization**: All user-facing menus, TUI notifications, console logs, and agent communication headers have been localized to `en-US` for a consistent experience.
+- **Intelligent Message Filtering**: 
+  - **Loop Prevention**: The bot automatically ignores any message ending with the `π` symbol, preventing infinite loops between instances.
+  - **Manual Interaction**: Users can now interact with the bot from their own WhatsApp account; the bot will process `fromMe` messages as long as they don't contain the bot's signature.
+- **Storage Management**: All persistent data (auth state, documents, config) is centralized in the `.pi-data/` directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-pi",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "type": "module",
   "description": "WhatsApp integration extension for Pi",
   "main": "whatsapp-pi.ts",

package/src/models/whatsapp.types.ts

@@ -44,3 +44,11 @@ export class WhatsAppError extends Error {
 export function validatePhoneNumber(number: string): boolean {
     return /^\+[1-9]\d{1,14}$/.test(number);
 }
+
+export interface DocumentMetadata {
+    filename: string;
+    mimetype: string;
+    size: number;
+    savedPath: string;
+    timestamp: number;
+}

package/src/services/audio.service.ts

@@ -45,10 +45,10 @@ export class AudioService {
                 return text.trim();
             }
 
-            return '[Transcrição vazia]';
+            return '[Empty transcription]';
         } catch (error) {
             console.error('[AudioService] Transcription error:', error);
-            return `[Erro na transcrição: ${error instanceof Error ? error.message : String(error)}]`;
+            return `[Transcription error: ${error instanceof Error ? error.message : String(error)}]`;
         }
     }
 }

package/src/services/session.manager.ts

@@ -1,19 +1,17 @@
 import { useMultiFileAuthState } from '@whiskeysockets/baileys';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { rm, readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { readFile, writeFile, mkdir, rm } from 'fs/promises';
+import { homedir } from 'os';
 import { SessionStatus } from '../models/whatsapp.types.js';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
 export interface Contact {
     number: string;
     name?: string;
 }
 
 export class SessionManager {
-    // Data is stored in a fixed folder inside the extension project
-    private readonly baseDir = join(__dirname, '..', '..', '.pi-data');
+    // Data is stored in the user's home directory to persist across updates
+    private readonly baseDir = join(homedir(), '.pi', 'whatsapp-pi');
     private readonly authDir = join(this.baseDir, 'auth');
     private readonly configPath = join(this.baseDir, 'config.json');
 

package/src/services/whatsapp.service.ts

@@ -41,7 +41,7 @@ export class WhatsAppService {
 
     async start() {
         if (this.isReconnecting) return;
-        this.onStatusUpdate?.('| WhatsApp: Connecting...');
+        this.onStatusUpdate?.('WhatsApp: Connecting...');
 
         const { state, saveCreds } = await this.sessionManager.getAuthState();
         const { version } = await fetchLatestBaileysVersion();
@@ -76,7 +76,7 @@ export class WhatsAppService {
             if (qr) {
                 this.sessionManager.setStatus('pairing');
                 this.onQRCode?.(qr);
-                this.onStatusUpdate?.('| WhatsApp: Pairing...');
+                this.onStatusUpdate?.('WhatsApp: Pairing...');
             }
 
             if (connection === 'close') {
@@ -96,26 +96,26 @@ export class WhatsAppService {
                     console.error(`Session invalid or logged out [${statusCode}] - clearing session and forcing re-auth`);
                     await this.sessionManager.clearSession();
                     this.sessionManager.setStatus('logged-out');
-                    this.onStatusUpdate?.('| WhatsApp: Logged out');
+                    this.onStatusUpdate?.('WhatsApp: Logged out');
                     return;
                 }
 
                 if (statusCode === DisconnectReason.connectionReplaced) {
                     console.error('Connection replaced - another instance connected');
-                    this.onStatusUpdate?.('| WhatsApp: Conflict (Another Instance)');
+                    this.onStatusUpdate?.('WhatsApp: Conflict (Another Instance)');
                     return;
                 }
                 
                 if (shouldReconnect && !this.isReconnecting) {
                     this.isReconnecting = true;
-                    this.onStatusUpdate?.('| WhatsApp: Reconnecting...');
+                    this.onStatusUpdate?.('WhatsApp: Reconnecting...');
                     setTimeout(() => {
                         this.isReconnecting = false;
                         this.start();
                     }, 3000);
                 } else if (!shouldReconnect) {
                     this.sessionManager.setStatus('logged-out');
-                    this.onStatusUpdate?.('| WhatsApp: Disconnected');
+                    this.onStatusUpdate?.('WhatsApp: Disconnected');
                 }
             } else if (connection === 'open') {
                 if (this.verboseMode) {
@@ -123,7 +123,7 @@ export class WhatsAppService {
                 }
                 this.isReconnecting = false;
                 this.sessionManager.setStatus('connected');
-                this.onStatusUpdate?.('| WhatsApp: Connected');
+                this.onStatusUpdate?.('WhatsApp: Connected');
             }
         });
 
@@ -245,6 +245,6 @@ export class WhatsAppService {
             this.isReconnecting = false;
         }
         await this.sessionManager.setStatus('disconnected');
-        this.onStatusUpdate?.('| WhatsApp: Disconnected');
+        this.onStatusUpdate?.('WhatsApp: Disconnected');
     }
 }

package/src/ui/menu.handler.ts

@@ -64,7 +64,7 @@ export class MenuHandler {
 
     private async manageAllowList(ctx: ExtensionCommandContext) {
         const list = this.sessionManager.getAllowList();
-        // Exibe o nome se existir, senão apenas o número
+        // Display the name if it exists, otherwise just the number
         let options = [...list.map(c => `Remove ${c.name ? c.name + ' (' + c.number + ')' : c.number}`), 'Add Number'];
         if (list.length > 0) {
             options.push('Clear All');
@@ -90,7 +90,7 @@ export class MenuHandler {
             }
             await this.manageAllowList(ctx);
         } else if (choice?.startsWith('Remove ')) {
-            // Extrai o número entre parênteses ou o que sobrar depois de "Remove "
+            // Extract the number between parentheses or what's left after "Remove "
             let num = choice.replace('Remove ', '');
             if (num.includes('(')) {
                 const match = num.match(/\((.*?)\)/);

package/whatsapp-pi.ts

@@ -3,6 +3,8 @@ import { SessionManager } from './src/services/session.manager.js';
 import { WhatsAppService } from './src/services/whatsapp.service.js';
 import { MenuHandler } from './src/ui/menu.handler.js';
 import { AudioService } from './src/services/audio.service.js';
+import { join } from 'node:path';
+import { writeFile, mkdir } from 'node:fs/promises';
 
 console.log("[WhatsApp-Pi] Extension file loaded by Pi...");
 export default function (pi: ExtensionAPI) {
@@ -39,7 +41,7 @@ export default function (pi: ExtensionAPI) {
         if (isVerbose) {
             console.log('[WhatsApp-Pi] Verbose mode enabled - Baileys trace logs will be shown');
         }
-        ctx.ui.setStatus('whatsapp', '|  WhatsApp: Disconnected');
+        ctx.ui.setStatus('whatsapp', 'WhatsApp: Disconnected');
         whatsappService.setStatusCallback((status) => {
             ctx.ui.setStatus('whatsapp', status);
         });
@@ -67,7 +69,7 @@ export default function (pi: ExtensionAPI) {
             const shouldConnect = isWhatsappPiOn;
 
             if (shouldConnect) {
-                ctx.ui.setStatus('whatsapp', '|  WhatsApp: Auto-connecting...');
+                ctx.ui.setStatus('whatsapp', 'WhatsApp: Auto-connecting...');
 
                 // Retry logic (max 3 attempts, 3s delay)
                 let attempts = 0;
@@ -83,7 +85,7 @@ export default function (pi: ExtensionAPI) {
                             setTimeout(tryConnect, 3000);
                         } else {
                             ctx.ui.notify('WhatsApp: Auto-connect failed after multiple attempts.', 'error');
-                            ctx.ui.setStatus('whatsapp', '|  WhatsApp: Connection Failed');
+                            ctx.ui.setStatus('whatsapp', 'WhatsApp: Connection Failed');
                         }
                     }
                 };
@@ -98,6 +100,17 @@ export default function (pi: ExtensionAPI) {
         }
 
         ctx.ui.notify('WhatsApp: Session reset via /new is now fully supported.', 'info');
+
+        // Verify pdftotext availability for document support
+        try {
+            const { code } = await pi.exec('pdftotext', ['-v']);
+            if (code !== 0 && code !== 99) { // 99 is a common exit code for -v in some versions
+                throw new Error(`pdftotext returned code ${code}`);
+            }
+        } catch (e) {
+            ctx.ui.notify('WhatsApp: pdftotext not found. PDF document support will be limited to storage only.', 'warning');
+            console.warn('[WhatsApp-Pi] Warning: pdftotext not found in system PATH.');
+        }
     });
 
 
@@ -126,7 +139,7 @@ export default function (pi: ExtensionAPI) {
         if (msg.message.audioMessage) {
             console.log(`[WhatsApp-Pi] Transcribing audio from ${pushName}...`);
             const transcription = await audioService.transcribe(msg.message.audioMessage);
-            text = `[Áudio Transcrito]: ${transcription}`;
+            text = `[Transcribed Audio]: ${transcription}`;
         } else if (msg.message.imageMessage) {
             console.log(`[WhatsApp-Pi] Downloading image from ${pushName}...`);
             try {
@@ -153,7 +166,53 @@ export default function (pi: ExtensionAPI) {
         } else if (!text) {
             if (msg.message.videoMessage) text = "[Video]";
             else if (msg.message.stickerMessage) text = "[Sticker]";
-            else if (msg.message.documentMessage) text = "[Document]";
+            else if (msg.message.documentMessage) 
+                {   
+                   const doc = msg.message.documentMessage;
+                   const fileName = doc.fileName || 'unnamed_document';
+                   const mimeType = doc.mimetype || 'application/octet-stream';
+                   const fileSize = doc.fileLength ? Number(doc.fileLength) : 0;
+                   
+                   console.log(`[WhatsApp-Pi] Downloading document from ${pushName}: ${fileName}...`);
+                   
+                   try {
+                       const { downloadContentFromMessage } = await import('@whiskeysockets/baileys');
+                       const stream = await downloadContentFromMessage(doc, 'document');
+                       let buffer = Buffer.from([]);
+                       for await (const chunk of stream) {
+                           buffer = Buffer.concat([buffer, chunk]);
+                       }
+                       
+                       // Sanitize filename
+                       const sanitized = fileName.replace(/[^a-z0-9\._-]/gi, '_');
+                       const savedFileName = `${Date.now()}_${sanitized}`;
+                       const relativePath = `./.pi-data/whatsapp/documents/${savedFileName}`;
+                       const absolutePath = join(process.cwd(), '.pi-data', 'whatsapp', 'documents', savedFileName);
+                       
+                       // Ensure directory exists (T001 handles it at startup, but let's be safe)
+                       await mkdir(join(process.cwd(), '.pi-data', 'whatsapp', 'documents'), { recursive: true });
+                       await writeFile(absolutePath, buffer);
+                       
+                       console.log(`[WhatsApp-Pi] Document saved to ${relativePath} (${buffer.length} bytes)`);
+                       
+                       const sizeFormatted = fileSize > 1024 * 1024 
+                           ? `${(fileSize / (1024 * 1024)).toFixed(1)} MB`
+                           : `${(fileSize / 1024).toFixed(1)} KB`;
+                       
+                       text = `[Document Received: ${fileName}]\n` +
+                              `MIME Type: ${mimeType}\n` +
+                              `Size: ${sizeFormatted}\n` +
+                              `Location: ${relativePath}`;
+                              
+                       if (doc.caption) {
+                           text += `\n\nDescription: ${doc.caption}`;
+                       }
+                   } catch (e) {
+                       console.error(`[WhatsApp-Pi] Failed to download document:`, e);
+                       text = `[Document: ${fileName} (download failed)]`;
+                   }
+                }
+
             else if (msg.message.contactMessage || msg.message.contactsArrayMessage) text = "[Contact]";
             else if (msg.message.locationMessage) text = "[Location]";
             else text = "[Unsupported Message Type]";
@@ -165,11 +224,11 @@ export default function (pi: ExtensionAPI) {
         // Use a standard delivery for ALL messages to ensure TUI consistency
         if (imageBuffer && imageMimeType) {
             pi.sendUserMessage([
-                { type: "text", text: `Mensagem de ${pushName} (+${sender}): ${text}` },
+                { type: "text", text: `Message from ${pushName} (+${sender}): ${text}` },
                 { type: "image", data: imageBuffer.toString('base64'), mimeType: imageMimeType }
             ], { deliverAs: "followUp" });
         } else {
-            pi.sendUserMessage(`Mensagem de ${pushName} (+${sender}): ${text}`, { deliverAs: "followUp" });
+            pi.sendUserMessage(`Message from ${pushName} (+${sender}): ${text}`, { deliverAs: "followUp" });
         }
 
         // Handle commands
@@ -178,7 +237,7 @@ export default function (pi: ExtensionAPI) {
 
             if (_ctx) {
                 _ctx.compact();
-                await whatsappService.sendMessage(remoteJid!, "Sessão compactada com sucesso! ✅");
+                await whatsappService.sendMessage(remoteJid!, "Session compacted successfully! ✅");
             }
             return;
         }
@@ -187,7 +246,7 @@ export default function (pi: ExtensionAPI) {
             console.log(`[WhatsApp-Pi] Abort requested by ${pushName}.`);
             if (_ctx) {
                 _ctx.abort();
-                await whatsappService.sendMessage(remoteJid!, "Abortado! ✅");
+                await whatsappService.sendMessage(remoteJid!, "Aborted! ✅");
             }
             return;
         }