whatsapp-pi 1.0.22 → 1.0.24

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:
@@ -71,7 +79,7 @@ pi -e whatsapp-pi.ts --verbose
 - `/whatsapp` - Open the WhatsApp management menu
 
 ### Main Menu Options
-- **Connect WhatsApp** - Start WhatsApp connection (shows QR code for first-time setup)
+- **Connect / Reconnect WhatsApp** - Start WhatsApp connection using saved credentials when available; QR code appears only if pairing is required
 - **Disconnect WhatsApp** - Stop WhatsApp connection
 - **Logoff (Delete Session)** - Remove all credentials and session data
 - **Allowed Numbers** - Manage contacts that can interact with Pi
@@ -79,8 +87,7 @@ pi -e whatsapp-pi.ts --verbose
 
 ### Allowed Numbers Management
 - **Add Number** - Add a new contact to the allow list (format: +5511999999999)
-- **Remove [Number]** - Remove a specific contact from the allow list
-- **Clear All** - Remove all allowed numbers
+- **Select a contact** - Open a submenu with **Send Message**, **Remove Number**, and **Back**
 - **Back** - Return to main menu
 
 ### Blocked Numbers Management
@@ -108,6 +115,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 +128,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.22",
+  "version": "1.0.24",
   "type": "module",
   "description": "WhatsApp integration extension for Pi",
   "main": "whatsapp-pi.ts",

package/src/models/whatsapp.types.ts

@@ -44,3 +44,37 @@ 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;
+}
+
+export type MessageDirection = 'incoming' | 'outgoing';
+
+export interface RecentConversationMessage {
+    messageId: string;
+    senderNumber: string;
+    text: string;
+    direction: MessageDirection;
+    timestamp: number;
+}
+
+export interface RecentConversationSummary {
+    senderNumber: string;
+    senderName?: string;
+    lastMessagePreview: string;
+    lastMessageTime: number;
+    lastMessageDirection: MessageDirection;
+    messageCount: number;
+    isAllowed: boolean;
+}
+
+export interface RecentsStore {
+    conversations: RecentConversationSummary[];
+    messagesBySender: Record<string, RecentConversationMessage[]>;
+    updatedAt: 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/recents.service.ts

@@ -0,0 +1,203 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import type {
+    MessageDirection,
+    RecentConversationMessage,
+    RecentConversationSummary,
+    RecentsStore
+} from '../models/whatsapp.types.js';
+import { SessionManager } from './session.manager.js';
+
+export interface RecentsMessageInput {
+    messageId: string;
+    senderNumber: string;
+    senderName?: string;
+    text: string;
+    direction: MessageDirection;
+    timestamp: number;
+}
+
+export class RecentsService {
+    private readonly baseDir = join(homedir(), '.pi', 'whatsapp-pi');
+    private readonly dataDir = join(this.baseDir, 'recents');
+    private readonly storePath = join(this.dataDir, 'recents.json');
+    private store: RecentsStore = {
+        conversations: [],
+        messagesBySender: {},
+        updatedAt: Date.now()
+    };
+
+    constructor(private readonly sessionManager: SessionManager) {}
+
+    async ensureInitialized() {
+        await mkdir(this.dataDir, { recursive: true });
+        await this.loadStore();
+    }
+
+    private async loadStore() {
+        try {
+            const content = await readFile(this.storePath, 'utf-8');
+            const parsed = JSON.parse(content) as Partial<RecentsStore>;
+
+            this.store = {
+                conversations: Array.isArray(parsed.conversations) ? parsed.conversations.slice(0, 20) : [],
+                messagesBySender: parsed.messagesBySender && typeof parsed.messagesBySender === 'object'
+                    ? this.normalizeMessagesMap(parsed.messagesBySender)
+                    : {},
+                updatedAt: typeof parsed.updatedAt === 'number' ? parsed.updatedAt : Date.now()
+            };
+
+            this.rebuildConversationState();
+        } catch {
+            this.store = {
+                conversations: [],
+                messagesBySender: {},
+                updatedAt: Date.now()
+            };
+        }
+    }
+
+    private normalizeMessagesMap(messagesBySender: RecentsStore['messagesBySender']): RecentsStore['messagesBySender'] {
+        const normalized: RecentsStore['messagesBySender'] = {};
+
+        for (const [senderNumber, messages] of Object.entries(messagesBySender)) {
+            if (!Array.isArray(messages)) continue;
+            normalized[senderNumber] = messages
+                .filter((message): message is RecentConversationMessage => this.isValidMessage(message))
+                .map(message => ({ ...message, timestamp: this.normalizeTimestamp(message.timestamp) }))
+                .sort((left, right) => left.timestamp - right.timestamp)
+                .slice(-20);
+        }
+
+        return normalized;
+    }
+
+    private isValidMessage(message: unknown): message is RecentConversationMessage {
+        return Boolean(
+            message &&
+            typeof message === 'object' &&
+            typeof (message as RecentConversationMessage).messageId === 'string' &&
+            typeof (message as RecentConversationMessage).senderNumber === 'string' &&
+            typeof (message as RecentConversationMessage).text === 'string' &&
+            (message as RecentConversationMessage).text.trim().length > 0 &&
+            ((message as RecentConversationMessage).direction === 'incoming' || (message as RecentConversationMessage).direction === 'outgoing') &&
+            typeof (message as RecentConversationMessage).timestamp === 'number'
+        );
+    }
+
+    private rebuildConversationState() {
+        const previousNames = new Map(
+            this.store.conversations.map(conversation => [conversation.senderNumber, conversation.senderName] as const)
+        );
+        const summaries = new Map<string, RecentConversationSummary>();
+
+        for (const [senderNumber, messages] of Object.entries(this.store.messagesBySender)) {
+            if (messages.length === 0) continue;
+            const lastMessage = messages[messages.length - 1];
+            summaries.set(senderNumber, {
+                senderNumber,
+                senderName: previousNames.get(senderNumber),
+                lastMessagePreview: this.buildPreview(lastMessage.text),
+                lastMessageTime: lastMessage.timestamp,
+                lastMessageDirection: lastMessage.direction,
+                messageCount: messages.length,
+                isAllowed: this.sessionManager.isAllowed(senderNumber)
+            });
+        }
+
+        this.store.conversations = Array.from(summaries.values())
+            .sort((left, right) => right.lastMessageTime - left.lastMessageTime)
+            .slice(0, 20);
+    }
+
+    private buildPreview(text: string): string {
+        const normalized = text.trim().replace(/\s+/g, ' ');
+        if (normalized.length <= 80) return normalized;
+        return `${normalized.slice(0, 77)}...`;
+    }
+
+    private async persistStore() {
+        this.store.updatedAt = Date.now();
+        await writeFile(this.storePath, JSON.stringify(this.store, null, 2));
+    }
+
+    private normalizeNumber(input: string): string {
+        const cleaned = input.replace(/@s\.whatsapp\.net$/, '');
+        if (cleaned.startsWith('+')) {
+            return cleaned;
+        }
+        if (/^\d+$/.test(cleaned)) {
+            return `+${cleaned}`;
+        }
+        return cleaned;
+    }
+
+    private normalizeTimestamp(timestamp: number): number {
+        return timestamp < 1_000_000_000_000 ? timestamp * 1000 : timestamp;
+    }
+
+    async recordMessage(input: RecentsMessageInput) {
+        const senderNumber = this.normalizeNumber(input.senderNumber);
+        if (!senderNumber) return;
+
+        const normalizedTimestamp = this.normalizeTimestamp(input.timestamp);
+        const normalizedText = input.text.trim().replace(/\s+/g, ' ');
+        if (!normalizedText) return;
+
+        const existing = this.store.messagesBySender[senderNumber] ?? [];
+        const nextMessage: RecentConversationMessage = {
+            messageId: input.messageId,
+            senderNumber,
+            text: normalizedText,
+            direction: input.direction,
+            timestamp: normalizedTimestamp
+        };
+
+        const filtered = existing.filter(message => message.messageId !== nextMessage.messageId);
+        filtered.push(nextMessage);
+
+        this.store.messagesBySender[senderNumber] = filtered
+            .sort((left, right) => left.timestamp - right.timestamp)
+            .slice(-20);
+
+        const existingConversation = this.store.conversations.find(conversation => conversation.senderNumber === senderNumber);
+        const summary: RecentConversationSummary = {
+            senderNumber,
+            senderName: input.senderName ?? existingConversation?.senderName,
+            lastMessagePreview: this.buildPreview(input.text),
+            lastMessageTime: normalizedTimestamp,
+            lastMessageDirection: input.direction,
+            messageCount: this.store.messagesBySender[senderNumber].length,
+            isAllowed: this.sessionManager.isAllowed(senderNumber)
+        };
+
+        this.store.conversations = [
+            summary,
+            ...this.store.conversations.filter(item => item.senderNumber !== senderNumber)
+        ]
+            .sort((left, right) => right.lastMessageTime - left.lastMessageTime)
+            .slice(0, 20);
+
+        await this.persistStore();
+    }
+
+    async getRecentConversations(): Promise<RecentConversationSummary[]> {
+        this.rebuildConversationState();
+        return [...this.store.conversations];
+    }
+
+    async getConversationHistory(senderNumber: string): Promise<RecentConversationMessage[]> {
+        const normalizedNumber = this.normalizeNumber(senderNumber);
+        const messages = this.store.messagesBySender[normalizedNumber] ?? [];
+        return [...messages]
+            .map(message => ({ ...message, timestamp: this.normalizeTimestamp(message.timestamp) }))
+            .sort((left, right) => left.timestamp - right.timestamp)
+            .slice(-20);
+    }
+
+    async hasRecentConversations(): Promise<boolean> {
+        const conversations = await this.getRecentConversations();
+        return conversations.length > 0;
+    }
+}

package/src/services/session.manager.ts

@@ -1,6 +1,6 @@
 import { useMultiFileAuthState } from '@whiskeysockets/baileys';
 import { join } from 'path';
-import { readFile, writeFile, mkdir, rm } from 'fs/promises';
+import { readFile, writeFile, mkdir, rm, readdir } from 'fs/promises';
 import { homedir } from 'os';
 import { SessionStatus } from '../models/whatsapp.types.js';
 
@@ -12,21 +12,27 @@ export interface Contact {
 export class SessionManager {
     // 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 authStateDir = join(this.baseDir, 'auth');
     private readonly configPath = join(this.baseDir, 'config.json');
 
     private status: SessionStatus = 'logged-out';
     private allowList: Contact[] = [];
     private blockList: Contact[] = [];
     private ignoredNumbers: Contact[] = [];
+    private hasAuthState = false;
     private openaiKey: string = '';
     private visionModel: string = 'gpt-4o';
 
+    private async ensureStorageDirectories() {
+        await mkdir(this.baseDir, { recursive: true });
+        await mkdir(this.authStateDir, { recursive: true });
+    }
+
     public async ensureInitialized() {
         try {
-            await mkdir(this.baseDir, { recursive: true });
-            await mkdir(this.authDir, { recursive: true });
+            await this.ensureStorageDirectories();
             await this.loadConfig();
+            await this.syncAuthStateFromDisk();
         } catch (error) {}
     }
 
@@ -54,6 +60,7 @@ export class SessionManager {
             this.blockList = (config.blockList || []).map(cleanContact).filter(Boolean) as Contact[];
             this.ignoredNumbers = (config.ignoredNumbers || []).map(cleanContact).filter(Boolean) as Contact[];
             this.status = config.status || 'logged-out';
+            this.hasAuthState = Boolean(config.hasAuthState);
             this.openaiKey = config.openaiKey || '';
             this.visionModel = config.visionModel || 'gpt-4o';
         } catch (error) {
@@ -68,6 +75,7 @@ export class SessionManager {
                 blockList: this.blockList,
                 ignoredNumbers: this.ignoredNumbers,
                 status: this.status,
+                hasAuthState: this.hasAuthState,
                 openaiKey: this.openaiKey,
                 visionModel: this.visionModel
             };
@@ -81,6 +89,10 @@ export class SessionManager {
         return this.allowList;
     }
 
+    getAllowedContact(number: string): Contact | undefined {
+        return this.allowList.find(c => c.number === number);
+    }
+
     getBlockList(): Contact[] {
         return this.blockList;
     }
@@ -106,12 +118,19 @@ export class SessionManager {
             return;
         }
 
-        if (!this.allowList.find(c => c.number === cleanNumber)) {
+        const existing = this.allowList.find(c => c.number === cleanNumber);
+        if (!existing) {
             this.allowList.push({ number: cleanNumber, name });
             // Remove from blockList and ignoredNumbers if it was there
             this.blockList = this.blockList.filter(c => c.number !== cleanNumber);
             this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== cleanNumber);
             await this.saveConfig();
+            return;
+        }
+
+        if (name && !existing.name) {
+            existing.name = name;
+            await this.saveConfig();
         }
     }
 
@@ -120,8 +139,28 @@ export class SessionManager {
         await this.saveConfig();
     }
 
-    async clearAllowList() {
-        this.allowList = [];
+    async setAllowedContactAlias(number: string, alias: string) {
+        const trimmedAlias = alias.trim();
+        if (!trimmedAlias) {
+            return;
+        }
+
+        const contact = this.getAllowedContact(number);
+        if (!contact) {
+            return;
+        }
+
+        contact.name = trimmedAlias;
+        await this.saveConfig();
+    }
+
+    async removeAllowedContactAlias(number: string) {
+        const contact = this.getAllowedContact(number);
+        if (!contact || !contact.name) {
+            return;
+        }
+
+        delete contact.name;
         await this.saveConfig();
     }
 
@@ -168,25 +207,51 @@ export class SessionManager {
 
     public async isRegistered(): Promise<boolean> {
         try {
-            const credsPah = join(this.authDir, 'creds.json');
+            const credsPah = join(this.authStateDir, 'creds.json');
             await readFile(credsPah);
+            this.hasAuthState = true;
             return true;
         } catch {
-            return false;
+            await this.syncAuthStateFromDisk();
+            return this.hasAuthState;
+        }
+    }
+
+    async markAuthStateAvailable() {
+        if (!this.hasAuthState) {
+            this.hasAuthState = true;
+            await this.saveConfig();
         }
     }
 
     async getAuthState() {
-        return await useMultiFileAuthState(this.authDir);
+        await this.ensureStorageDirectories();
+        return await useMultiFileAuthState(this.authStateDir);
+    }
+
+    private async syncAuthStateFromDisk() {
+        try {
+            const entries = await readdir(this.authStateDir);
+            if (entries.length > 0) {
+                if (!this.hasAuthState) {
+                    this.hasAuthState = true;
+                    await this.saveConfig();
+                }
+            }
+        } catch {
+            // Ignore missing directory / empty auth state
+        }
     }
 
-    async clearSession() {
+    async deleteAuthState() {
         try {
-            await rm(this.authDir, { recursive: true, force: true });
+            await rm(this.authStateDir, { recursive: true, force: true });
+            await mkdir(this.authStateDir, { recursive: true });
             this.status = 'logged-out';
+            this.hasAuthState = false;
             await this.saveConfig();
         } catch (error) {
-            console.error('Failed to clear session:', error);
+            console.error('Failed to delete auth state:', error);
         }
     }
 
@@ -217,7 +282,7 @@ export class SessionManager {
         await this.saveConfig();
     }
 
-    getAuthDir(): string {
-        return this.authDir;
+    getAuthStateDir(): string {
+        return this.authStateDir;
     }
 }