whatsapp_notifier 0.3.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58d5e7ea12d1eb8560b911c6c84595f4ee1590cb64d5351ecc4d3d5e5af8245d
-  data.tar.gz: c743fca10de3d4cd9b21789822dc8b6dff4dbfe9ffc9a5a6b119d257386c08a7
+  metadata.gz: fc24f1c67db14b3be6dfc49310e7a86987c520c6ddc595895d6e00b483aafab4
+  data.tar.gz: e600799c44eeefddfa3476c65894bc1aa430d7c488685e7172c9dcaf5e9c27df
 SHA512:
-  metadata.gz: 07b15329406ab0f4f64013f60108b66d40906277acb5ae9c980688e9dfb11317fb2988a2e7ca73c9945c0853bdf46071f94af8f1ba0e5cdb81bb7595dd6750e7
-  data.tar.gz: 932f108caf6a2ee6af828a4e23d41b1bacdedc308f1d59d41ac6cdd03f9cfde1e3892f6065eaf888c80af238a73a641bc42549b5a5a4df4972511b1582063c76
+  metadata.gz: f85d85f6e467055c93c8c5ba30c325a8d68f1113b5d257d3b26f8397976706fb771cff63cedadba721f50c87d24f5159a79fac570ce6e1b2a2cffe84be877b30
+  data.tar.gz: 747e11eeee1780b222f7e46c044dad8bd8235462dadc5b3f8f0afb2d4d2f04a84c7e71ece2bfbcbab4571a061cda6cfd2671e0e736dbe7a932d4b81d86101df4

data/README.md

@@ -54,6 +54,20 @@ status = WhatsAppNotifier.connection_status(metadata: { user_id: current_user.id
 # => { state: "...", authenticated: true/false, has_qr: true/false }
 ```
 
+## Log out (disconnect + clear session)
+
+Explicitly disconnects the user and wipes their saved WhatsApp session from the
+service, so the next connect starts fresh with a new QR. Call this from a
+user-initiated "Log out WhatsApp" action — NOT from your app's sign-out, which
+should leave the WhatsApp session intact for the next login.
+
+```ruby
+WhatsAppNotifier.logout(metadata: { user_id: current_user.id })
+# => { success: true }
+```
+
+The mounted engine also exposes `DELETE /whatsapp/logout` for the same effect.
+
 ## Send a message
 
 ```ruby
@@ -120,6 +134,13 @@ This copies the service to `whatsapp_service/` and updates `.gitignore`.
 
 - This gem uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.
 - Keep Chromium available in your runtime (or set `PUPPETEER_EXECUTABLE_PATH`).
+- Session profiles persist under `WHATSAPP_SESSION_DIR` (default `/whatsapp_data`).
+  Mount it on durable storage so logins survive restarts; the service clears stale
+  Chromium `SingletonLock` files on each launch so an unclean exit can't wedge it.
+- Resilience knobs: `WHATSAPP_INIT_TIMEOUT_MS` (default 90000) recycles a client
+  that never reaches QR/READY; set `WWEBJS_WEB_VERSION` (e.g. `2.3000.1023204887`,
+  optionally `WWEBJS_WEB_VERSION_CACHE_URL`) to pin the WhatsApp Web build so a
+  live web.whatsapp.com change can't silently break the client.
 
 ## License
 

data/app/controllers/whatsapp_notifier/messages_controller.rb

@@ -30,5 +30,18 @@ module WhatsAppNotifier
       render json: { success: false, error: e.message },
              status: :internal_server_error
     end
+
+    # GET /inbound — drain pending inbound messages for the current user.
+    # Optional convenience for host apps that prefer pulling through Rails
+    # instead of calling WhatsAppNotifier.fetch_inbound directly.
+    def inbound
+      messages = WhatsAppNotifier.fetch_inbound(
+        metadata: { user_id: whatsapp_notifier_user_id }
+      )
+      render json: { messages: messages }
+    rescue StandardError => e
+      render json: { success: false, error: e.message },
+             status: :internal_server_error
+    end
   end
 end

data/app/controllers/whatsapp_notifier/sessions_controller.rb

@@ -22,6 +22,16 @@ module WhatsAppNotifier
              status: :internal_server_error
     end
 
+    # DELETE /logout — disconnect WhatsApp and clear the saved session for the
+    # current user. Explicit, user-initiated; app sign-out must NOT call this.
+    def destroy
+      WhatsAppNotifier.logout(metadata: metadata)
+      render json: { success: true }
+    rescue StandardError => e
+      render json: { error: "Failed to log out: #{e.message}" },
+             status: :internal_server_error
+    end
+
     private
 
     def metadata

data/config/routes.rb

@@ -1,5 +1,7 @@
 WhatsAppNotifier::Engine.routes.draw do
-  get  "status", to: "sessions#show", as: :status
-  get  "qr",     to: "sessions#qr",   as: :qr
-  post "send",   to: "messages#create", as: :send_message
+  get    "status",  to: "sessions#show",     as: :status
+  get    "qr",      to: "sessions#qr",       as: :qr
+  delete "logout",  to: "sessions#destroy",  as: :logout
+  post   "send",    to: "messages#create",   as: :send_message
+  get    "inbound", to: "messages#inbound",  as: :inbound
 end

data/lib/whatsapp_notifier/client.rb

@@ -27,6 +27,14 @@ module WhatsAppNotifier
       provider_for(provider || @configuration.provider).connection_status(metadata: metadata)
     end
 
+    def fetch_inbound(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).fetch_inbound(metadata: metadata)
+    end
+
+    def logout(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).logout(metadata: metadata)
+    end
+
     private
 
     def provider_for(key)

data/lib/whatsapp_notifier/configuration.rb

@@ -7,7 +7,7 @@ module WhatsAppNotifier
                   :bulk_max_attempts, :bulk_retryable_error_codes, :logger,
                   :web_automation_enabled, :warn_on_risky_provider,
                   :authenticate_with, :current_user_id_resolver,
-                  :parent_controller
+                  :parent_controller, :on_inbound_message_handler
 
     def initialize
       @provider = :web_automation
@@ -24,6 +24,9 @@ module WhatsAppNotifier
       @authenticate_with = nil
       @current_user_id_resolver = -> { respond_to?(:current_user) && current_user ? current_user.id : nil }
       @parent_controller = "::ApplicationController"
+      # Optional host hook: a callable invoked with each inbound message hash.
+      # Lets a push-based integration react without polling. Nil = no handler.
+      @on_inbound_message_handler = nil
     end
 
     def validate!

data/lib/whatsapp_notifier/jobs/send_message_job.rb

@@ -1,6 +1,10 @@
 module WhatsAppNotifier
   module Jobs
     if defined?(::ActiveJob::Base)
+      # Real async path, only live in a host app that has ActiveJob loaded (any
+      # Rails app). Not exercisable in the gem's unit suite — the class is chosen
+      # at load time and ActiveJob isn't a gem dependency.
+      # :nocov:
       class SendMessageJob < ::ActiveJob::Base
         queue_as :default
 
@@ -9,6 +13,7 @@ module WhatsAppNotifier
           klass.with(params).deliver_now
         end
       end
+      # :nocov:
     else
       class SendMessageJob
         def self.perform_later(notification_class_name, params)

data/lib/whatsapp_notifier/providers/web_automation.rb

@@ -48,6 +48,28 @@ module WhatsAppNotifier
         adapter.connection_status(metadata: metadata)
       end
 
+      # Pull pending inbound messages for the user. fetch_inbound is an
+      # optional adapter capability (added in v0.4.0) — older adapters that
+      # predate inbound support raise a clear ConfigurationError rather than
+      # NoMethodError, and Configuration#validate! does not require it.
+      def fetch_inbound(metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter does not support inbound capture (upgrade to a fetch_inbound-capable adapter)" unless adapter.respond_to?(:fetch_inbound)
+
+        adapter.fetch_inbound(metadata: metadata)
+      end
+
+      def logout(metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter must be configured for web_automation provider" unless adapter.respond_to?(:logout)
+
+        adapter.logout(metadata: metadata)
+      end
+
 
       private
 

data/lib/whatsapp_notifier/services/web_automation/inbound.test.ts

@@ -0,0 +1,106 @@
+import { test, expect, beforeEach, afterAll } from 'bun:test';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+    INBOUND_QUEUE_CAP,
+    configureInbound,
+    loadTargets,
+    rememberTarget,
+    enqueueInbound,
+    drainInbound,
+    shouldCapture,
+    normalizeInbound,
+    resetInboundState
+} from './inbound';
+
+const root = mkdtempSync(join(tmpdir(), 'wa-inbound-'));
+const dirFor = (userId: string) => join(root, `session-user-${userId}`);
+
+beforeEach(() => {
+    resetInboundState();
+    configureInbound(dirFor);
+});
+
+afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+const CUST = '919999000001@c.us';
+
+function msg(overrides: any = {}) {
+    return {
+        from: CUST,
+        body: 'hello',
+        fromMe: false,
+        isStatus: false,
+        id: { _serialized: 'true_919999000001@c.us_ABC' },
+        timestamp: 1717000000,
+        type: 'chat',
+        ...overrides
+    };
+}
+
+// G10 — sanity filter (captures any real inbound 1:1; host matches relevance)
+test('shouldCapture: any inbound 1:1 chat, no allowlist gate', () => {
+    expect(shouldCapture('1', msg())).toBe(true);                         // @c.us 1:1
+    expect(shouldCapture('1', msg({ from: '125417440686124@lid' }))).toBe(true); // @lid 1:1
+
+    expect(shouldCapture('1', msg({ type: 'image' }))).toBe(true);        // media is real content
+
+    expect(shouldCapture('1', msg({ fromMe: true }))).toBe(false);       // own message
+    expect(shouldCapture('1', msg({ from: '12@g.us' }))).toBe(false);     // group
+    expect(shouldCapture('1', msg({ isStatus: true }))).toBe(false);      // status
+    expect(shouldCapture('1', msg({ from: 'status@broadcast' }))).toBe(false);
+    expect(shouldCapture('1', msg({ type: 'e2e_notification' }))).toBe(false); // system event
+    expect(shouldCapture('1', msg({ type: 'call_log' }))).toBe(false);        // system event
+    expect(shouldCapture('1', null)).toBe(false);                         // junk
+});
+
+// allowlist persists to disk + reloads
+test('rememberTarget persists and loadTargets reloads from disk', () => {
+    rememberTarget('1', CUST);
+    const file = join(dirFor('1'), 'outbound_targets.json');
+    expect(existsSync(file)).toBe(true);
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual([CUST]);
+
+    resetInboundState(); // drop in-memory cache → must reload from file
+    expect(loadTargets('1').has(CUST)).toBe(true);
+});
+
+// G11 — enqueue + drain
+test('enqueue then drain returns once, then empties', () => {
+    enqueueInbound('1', normalizeInbound(msg()));
+    enqueueInbound('1', normalizeInbound(msg({ id: { _serialized: 'm2' } })));
+
+    const first = drainInbound('1');
+    expect(first.length).toBe(2);
+
+    const second = drainInbound('1');
+    expect(second.length).toBe(0);
+});
+
+// G12 — queue cap (drop oldest)
+test('queue is bounded to INBOUND_QUEUE_CAP (drops oldest)', () => {
+    for (let i = 0; i < INBOUND_QUEUE_CAP + 5; i++) {
+        enqueueInbound('1', normalizeInbound(msg({ id: { _serialized: `m${i}` }, body: String(i) })));
+    }
+    const drained = drainInbound('1');
+    expect(drained.length).toBe(INBOUND_QUEUE_CAP);
+    expect(drained[0].body).toBe('5');                       // 0-4 dropped
+    expect(drained[drained.length - 1].body).toBe(String(INBOUND_QUEUE_CAP + 4));
+});
+
+// normalize shape + messageId fallback
+test('normalizeInbound maps fields and falls back on missing id', () => {
+    const a = normalizeInbound(msg());
+    expect(a).toEqual({
+        from: CUST, body: 'hello', messageId: 'true_919999000001@c.us_ABC',
+        timestamp: 1717000000, type: 'chat'
+    });
+
+    const b = normalizeInbound({ from: CUST, timestamp: 42 });
+    expect(b.messageId).toBe(`${CUST}-42`);                  // fallback id
+    expect(b.body).toBe('');
+    expect(b.type).toBe('chat');
+});

data/lib/whatsapp_notifier/services/web_automation/inbound.ts

@@ -0,0 +1,119 @@
+// Inbound capture core (v0.4.0)
+//
+// Pure, testable logic for the two-way layer. Kept separate from index.ts so
+// it can be unit-tested without booting a whatsapp-web.js Client.
+//
+// Policy: surface real inbound 1:1 messages (phone @c.us or privacy-id @lid)
+// — dropping our own messages, groups (@g.us), status broadcasts, and non-text
+// system events (e2e_notification, call_log, revoked, …) that carry no real
+// reply. Captured messages buffer in an in-memory queue drained by GET
+// /inbound/:userId (at-least-once; the host dedupes on messageId and decides
+// relevance by matching the resolved phone to its own recipient records).
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+export interface InboundMsg {
+    from: string;
+    body: string;
+    messageId: string;
+    timestamp: number;
+    type: string;
+}
+
+export const INBOUND_QUEUE_CAP = 1000;
+
+const inboundQueues = new Map<string, InboundMsg[]>();
+const outboundTargets = new Map<string, Set<string>>();
+
+// How to resolve a user's on-disk session dir. index.ts wires this to
+// sessionDirForUser; tests point it at a tmp dir.
+let baseDirResolver: (userId: string) => string = () => '.';
+export function configureInbound(resolver: (userId: string) => string) {
+    baseDirResolver = resolver;
+}
+
+function targetsFilePath(userId: string) {
+    return join(baseDirResolver(userId), 'outbound_targets.json');
+}
+
+export function loadTargets(userId: string): Set<string> {
+    const cached = outboundTargets.get(userId);
+    if (cached) return cached;
+
+    let set = new Set<string>();
+    try {
+        const p = targetsFilePath(userId);
+        if (existsSync(p)) {
+            const arr = JSON.parse(readFileSync(p, 'utf8'));
+            if (Array.isArray(arr)) set = new Set(arr);
+        }
+    } catch (_) { /* corrupt/missing file → start empty */ }
+    outboundTargets.set(userId, set);
+    return set;
+}
+
+export function rememberTarget(userId: string, chatId: string) {
+    const set = loadTargets(userId);
+    if (set.has(chatId)) return;
+    set.add(chatId);
+    try {
+        const dir = baseDirResolver(userId);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        writeFileSync(targetsFilePath(userId), JSON.stringify([...set]));
+    } catch (e) {
+        console.error(`Failed to persist outbound target for ${userId}`, e);
+    }
+}
+
+export function enqueueInbound(userId: string, msg: InboundMsg) {
+    let q = inboundQueues.get(userId);
+    if (!q) { q = []; inboundQueues.set(userId, q); }
+    q.push(msg);
+    // Bound memory: drop oldest beyond the cap.
+    if (q.length > INBOUND_QUEUE_CAP) q.splice(0, q.length - INBOUND_QUEUE_CAP);
+}
+
+export function drainInbound(userId: string): InboundMsg[] {
+    const q = inboundQueues.get(userId) || [];
+    inboundQueues.set(userId, []);
+    return q;
+}
+
+// Sanity filter for a real inbound 1:1 reply. Accepts both phone-number chats
+// (@c.us) and privacy-id chats (@lid — newer WhatsApp delivers replies from an
+// @lid). Drops own messages, groups (@g.us) and status (@broadcast). The host
+// app decides relevance by matching the resolved phone to its own records, so
+// we no longer gate on the per-send allowlist (which was unreliable).
+// Real human/content message types. Anything else (e2e_notification,
+// notification_template, call_log, revoked, protocol, gp2, …) is a system event
+// with no body and must NOT be surfaced as a reply.
+const TEXTUAL_TYPES = new Set([
+    'chat', 'image', 'video', 'audio', 'ptt', 'document', 'sticker', 'location', 'vcard'
+]);
+
+export function shouldCapture(userId: string, msg: any): boolean {
+    if (!msg || msg.fromMe) return false;
+    const from: string = msg.from || '';
+    if (!from.endsWith('@c.us') && !from.endsWith('@lid')) return false;
+    if (msg.isStatus) return false;
+    if (msg.type && !TEXTUAL_TYPES.has(msg.type)) return false; // drop system events
+    return true;
+}
+
+export function normalizeInbound(msg: any): InboundMsg {
+    const from: string = msg.from || '';
+    return {
+        from,
+        body: msg.body || '',
+        messageId: (msg.id && msg.id._serialized) || `${from}-${msg.timestamp}`,
+        timestamp: msg.timestamp || Math.floor(Date.now() / 1000),
+        type: msg.type || 'chat'
+    };
+}
+
+// Test helper: wipe in-memory state between examples.
+export function resetInboundState() {
+    inboundQueues.clear();
+    outboundTargets.clear();
+}

data/lib/whatsapp_notifier/services/web_automation/index.ts

@@ -3,12 +3,33 @@ import { Hono } from 'hono';
 import { rmSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { toDataURL } from 'qrcode';
+import {
+    InboundMsg,
+    configureInbound,
+    loadTargets,
+    rememberTarget,
+    enqueueInbound,
+    drainInbound,
+    shouldCapture,
+    normalizeInbound
+} from './inbound';
 
 const app = new Hono();
 const port = Number(process.env.PORT || 3001);
 const SESSION_BASE_DIR = process.env.WHATSAPP_SESSION_DIR || '/whatsapp_data';
 const BROWSER_EXECUTABLE_PATH = process.env.PUPPETEER_EXECUTABLE_PATH;
 
+// Recycle a client that boots Chromium but never reaches QR/READY (e.g. after a
+// WhatsApp Web update breaks the injected store), instead of wedging in
+// INITIALIZING forever with no QR.
+const INIT_TIMEOUT_MS = Number(process.env.WHATSAPP_INIT_TIMEOUT_MS || 90000);
+// Optionally pin the WhatsApp Web build so a live web.whatsapp.com change can't
+// silently break the client. Set WWEBJS_WEB_VERSION to a known-good version
+// (e.g. "2.3000.1023204887"); leave unset to use the library default.
+const WEB_VERSION = process.env.WWEBJS_WEB_VERSION || null;
+const WEB_VERSION_CACHE_URL = process.env.WWEBJS_WEB_VERSION_CACHE_URL ||
+    'https://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/{version}.html';
+
 // Multi-user client management
 interface ClientData {
     client: Client;
@@ -17,11 +38,85 @@ interface ClientData {
     lastUsed: number;
     isDestroying?: boolean;
     ready?: boolean;
+    initTimer?: ReturnType<typeof setTimeout>;
 }
 
 const clients = new Map<string, ClientData>();
 const initializingClients = new Set<string>();
 
+// ── Inbound capture (v0.4.0) — core logic lives in ./inbound.ts ──
+const WEBHOOK_URL = process.env.WHATSAPP_WEBHOOK_URL;
+const WEBHOOK_TOKEN = process.env.WHATSAPP_WEBHOOK_TOKEN;
+
+// Tell the inbound core how to resolve each user's on-disk session dir.
+configureInbound(sessionDirForUser);
+
+async function pushWebhook(userId: string, msg: InboundMsg) {
+    if (!WEBHOOK_URL) return;
+    try {
+        await fetch(WEBHOOK_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(WEBHOOK_TOKEN ? { 'X-WA-Token': WEBHOOK_TOKEN } : {})
+            },
+            body: JSON.stringify({ userId, message: msg })
+        });
+    } catch (e) {
+        console.error(`Webhook push failed for ${userId}`, e);
+    }
+}
+
+// Wrapper: sanity filter → normalize → resolve @lid → enqueue → optional webhook.
+async function captureInbound(userId: string, msg: any) {
+    try {
+        if (!shouldCapture(userId, msg)) return;
+        const inbound = normalizeInbound(msg);
+        // Newer WhatsApp delivers the reply's `from` as an @lid privacy id with
+        // no phone number, which the host can't match. Resolve it to the real
+        // phone via the contact so callers always get a phone-number @c.us.
+        if (inbound.from.endsWith('@lid')) {
+            try {
+                const contact = await msg.getContact();
+                const num = contact && (contact.number || (contact.id && contact.id.user));
+                if (num) inbound.from = `${String(num).replace(/\D/g, '')}@c.us`;
+            } catch (e) {
+                console.error(`lid->phone resolve failed for ${userId}`, e);
+            }
+            // Still an @lid => no phone to match or scope by. Drop it rather than
+            // forward an unmatchable, unpurgeable plaintext body.
+            if (inbound.from.endsWith('@lid')) return;
+        }
+        enqueueInbound(userId, inbound);
+        pushWebhook(userId, inbound);
+    } catch (e) {
+        console.error(`captureInbound error for ${userId}`, e);
+    }
+}
+
+async function backfillInbound(userId: string, client: Client) {
+    // On reconnect, replay recent messages ONLY from chats we actually messaged
+    // (the per-send allowlist) so a disconnect window doesn't drop a reply —
+    // without scraping every personal conversation on the linked number. Live
+    // replies are covered by the message_create handler; this is just recovery.
+    const targets = loadTargets(userId);
+    if (targets.size === 0) return;
+    for (const chatId of targets) {
+        try {
+            const chat = await client.getChatById(chatId);
+            const msgs = await chat.fetchMessages({ limit: 20 });
+            for (const m of msgs) captureInbound(userId, m);
+        } catch (_) { /* chat not materialized yet → skip */ }
+    }
+}
+
+function clearInitTimer(clientData: ClientData) {
+    if (clientData.initTimer) {
+        clearTimeout(clientData.initTimer);
+        clientData.initTimer = undefined;
+    }
+}
+
 function sessionDirForUser(userId: string) {
     return join(SESSION_BASE_DIR, `session-user-${userId}`);
 }
@@ -135,7 +230,11 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
                 '--disable-gpu'
             ],
             ...(BROWSER_EXECUTABLE_PATH ? { executablePath: BROWSER_EXECUTABLE_PATH } : {})
-        }
+        },
+        ...(WEB_VERSION ? {
+            webVersion: WEB_VERSION,
+            webVersionCache: { type: 'remote' as const, remotePath: WEB_VERSION_CACHE_URL }
+        } : {})
     });
 
     const clientData: ClientData = {
@@ -148,8 +247,18 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
 
     clients.set(userId, clientData);
 
+    // Watchdog: if the client never reaches QR/READY, recycle it so the next
+    // poll spins a fresh attempt instead of wedging in INITIALIZING forever.
+    clientData.initTimer = setTimeout(() => {
+        if (clientData.state === 'INITIALIZING' && !clientData.qr && !clientData.ready) {
+            console.error(`User ${userId} stuck INITIALIZING > ${INIT_TIMEOUT_MS}ms — recycling`);
+            destroyClient(userId).catch(console.error);
+        }
+    }, INIT_TIMEOUT_MS);
+
     client.on('qr', async (qr) => {
         clientData.state = 'QR_REQUIRED';
+        clearInitTimer(clientData); // progress made — QR is showable
         try {
             clientData.qr = await toDataURL(qr);
             console.log(`QR RECEIVED and converted for User ${userId}`);
@@ -162,18 +271,34 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         clientData.state = 'AUTHENTICATED';
         clientData.qr = null;
         clientData.ready = true;
+        clearInitTimer(clientData);
         console.log(`Client is READY for User ${userId}`);
+        // Replay anything that arrived while we were disconnected.
+        backfillInbound(userId, client).catch((e) => console.error(`Backfill failed for ${userId}`, e));
     });
 
+    // Capture inbound replies. 'message' fires for incoming only, but in some
+    // linked/multi-device sessions it silently never fires — 'message_create'
+    // is the reliable event (fires for all messages). shouldCapture drops our
+    // own sends (fromMe) + groups/status, and the queue dedupes on message_id,
+    // so listening on both is safe.
+    // Only 'message_create' — it fires reliably for every message across linked/
+    // multi-device sessions (plain 'message' silently never fires on some), and
+    // listening on both would double-enqueue every reply. shouldCapture drops
+    // our own sends (fromMe).
+    client.on('message_create', (msg) => captureInbound(userId, msg));
+
     client.on('authenticated', () => {
         clientData.state = 'AUTHENTICATED';
         clientData.ready = false;
+        clearInitTimer(clientData);
         console.log(`AUTHENTICATED for User ${userId}`);
     });
 
     client.on('auth_failure', (msg) => {
         clientData.state = 'DISCONNECTED';
         clientData.ready = false;
+        clearInitTimer(clientData);
         console.error(`AUTHENTICATION FAILURE for User ${userId}`, msg);
     });
 
@@ -186,6 +311,7 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
 
     client.initialize().catch(async (err) => {
         console.error(`Initialization failed for user ${userId}:`, err.message || err);
+        clearInitTimer(clientData);
         // Clean up the failed client
         try { client.removeAllListeners(); } catch (_) {}
         try { await client.destroy(); } catch (_) {}
@@ -203,11 +329,12 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
     return clientData;
 }
 
-async function destroyClient(userId: string) {
+async function destroyClient(userId: string, clearSession: boolean = false) {
     const data = clients.get(userId);
     if (data && !data.isDestroying) {
         data.isDestroying = true;
-        console.log(`Destroying WhatsApp client for User: ${userId}`);
+        clearInitTimer(data);
+        console.log(`Destroying WhatsApp client for User: ${userId} (clearSession: ${clearSession})`);
         try {
             // Unregister listeners to prevent loops or double-destroys
             data.client.removeAllListeners();
@@ -216,7 +343,18 @@ async function destroyClient(userId: string) {
             console.error(`Error destroying client for ${userId}`, e);
         }
         clients.delete(userId);
-        // Session data is preserved on disk for auto-reconnect
+        // Session data is preserved on disk for auto-reconnect (unless clearing below).
+    }
+    // On explicit logout, wipe the persisted Chromium profile / WhatsApp session
+    // from disk — even if there was no live client in memory.
+    if (clearSession) {
+        const dir = sessionDirForUser(userId);
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            console.log(`Cleared session dir for User: ${userId}`);
+        } catch (e) {
+            console.error(`Failed to clear session dir for ${userId}`, e);
+        }
     }
 }
 
@@ -250,6 +388,17 @@ app.get('/qr/:userId', async (c) => {
     return c.json({ qr: data.qr });
 });
 
+// Explicit per-user logout: disconnect the client and wipe the saved WhatsApp
+// session from disk so the next connect starts fresh with a new QR. Triggered by
+// the user-settings "Log out WhatsApp" button — NOT by app sign-out.
+app.post('/logout/:userId', async (c) => {
+    const userId = c.req.param('userId');
+    console.log(`Logout requested for User: ${userId}`);
+    await destroyClient(userId, true);
+    initializingClients.delete(userId);
+    return c.json({ success: true });
+});
+
 app.post('/send/:userId', async (c) => {
     const userId = c.req.param('userId');
     const { to, message, mediaUrl } = await c.req.json();
@@ -266,6 +415,9 @@ app.post('/send/:userId', async (c) => {
         const chatId = to.includes('@c.us') ? to : `${to}@c.us`;
         await sendMessageWithRetry(data.client, data, chatId, message, mediaUrl);
 
+        // Record the recipient so their replies pass the inbound allowlist.
+        rememberTarget(userId, chatId);
+
         data.lastUsed = Date.now();
         return c.json({ success: true });
     } catch (error: any) {
@@ -274,6 +426,15 @@ app.post('/send/:userId', async (c) => {
     }
 });
 
+// GET /inbound/:userId — drain the user's pending inbound queue.
+// Returns { messages: [...] } and clears the buffer (at-least-once;
+// the Rails side dedupes on messageId).
+app.get('/inbound/:userId', async (c) => {
+    const userId = c.req.param('userId');
+    await getOrCreateClient(userId);
+    return c.json({ messages: drainInbound(userId) });
+});
+
 
 console.log(`Starting Multi-User WhatsApp service (Bun Native) on port ${port}...`);
 

data/lib/whatsapp_notifier/services/web_automation/package.json

@@ -2,6 +2,9 @@
   "name": "whatsapp-service",
   "version": "1.0.0",
   "main": "index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
   "dependencies": {
     "hono": "^4.12.9",
     "whatsapp-web.js": "1.34.6",

data/lib/whatsapp_notifier/session/qr_service.rb

@@ -9,39 +9,15 @@ module WhatsAppNotifier
       end
 
       def qr_code(metadata: {})
-        generated = adapter.fetch_qr_code(metadata: metadata)
-        # We don't cache the QR code because it expires every ~20 seconds
-        # The underlying adapter/service is responsible for providing the latest one
-        generated
+        # We don't cache the QR code because it expires every ~20 seconds.
+        # The underlying adapter/service provides the latest one each call.
+        adapter.fetch_qr_code(metadata: metadata)
       end
 
-
       def activate!(token)
         session = store.load
         store.save(session.merge(active: true, token: token, qr_code: nil))
       end
-
-      private
-
-      def cached_qr(session, user_id)
-        return session[:qr_code] unless user_id
-
-        session.fetch(:users, {}).fetch(user_key(user_id), {})[:qr_code]
-      end
-
-      def with_cached_qr(session, user_id, qr_code)
-        return session.merge(qr_code: qr_code) unless user_id
-
-        users = session.fetch(:users, {})
-        key = user_key(user_id)
-        user_session = users.fetch(key, {})
-        users[key] = user_session.merge(qr_code: qr_code)
-        session.merge(users: users)
-      end
-
-      def user_key(user_id)
-        user_id.to_s.to_sym
-      end
     end
   end
 end

data/lib/whatsapp_notifier/version.rb

@@ -1,4 +1,4 @@
 module WhatsAppNotifier
-  VERSION = "0.3.1"
+  VERSION = "0.5.1"
 
 end

data/lib/whatsapp_notifier/web_adapter.rb

@@ -52,6 +52,32 @@ module WhatsAppNotifier
       }
     end
 
+    # Drains the service's pending inbound queue for this user. The service
+    # returns the messages once, then clears them (at-least-once handoff —
+    # callers must dedupe on message_id). Accepts either a bare array or a
+    # { "messages" => [...] } envelope so the wire format can evolve.
+    def fetch_inbound(metadata: {})
+      user_id = user_id_from(metadata)
+      response = request(:get, "/inbound/#{user_id}")
+      raw = response.is_a?(Hash) ? response["messages"] : response
+      Array(raw).map do |m|
+        {
+          from: m["from"],
+          body: m["body"],
+          message_id: m["messageId"] || m["message_id"],
+          timestamp: m["timestamp"],
+          type: m["type"]
+        }
+      end
+    end
+
+    # Logs the user out of WhatsApp and clears their saved session on the service.
+    def logout(metadata: {})
+      user_id = user_id_from(metadata)
+      response = request(:post, "/logout/#{user_id}")
+      { success: response.fetch("success", false) }
+    end
+
     private
 
     def user_id_from(metadata)

data/lib/whatsapp_notifier.rb

@@ -62,6 +62,14 @@ module WhatsAppNotifier
       client.connection_status(provider: provider, metadata: metadata)
     end
 
+    def fetch_inbound(provider: nil, metadata: {})
+      client.fetch_inbound(provider: provider, metadata: metadata)
+    end
+
+    def logout(provider: nil, metadata: {})
+      client.logout(provider: provider, metadata: metadata)
+    end
+
   end
 end
 

data/spec/client_spec.rb

@@ -49,4 +49,38 @@ RSpec.describe WhatsAppNotifier::Client do
       expect(status).to include(state: "QR_REQUIRED")
     end
   end
+
+  it "delegates fetch_inbound to the provider" do
+    Dir.mktmpdir do |dir|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_session_path = File.join(dir, "session.json")
+      config.web_adapter = double(
+        send_message: { success: true, session: {} },
+        fetch_qr_code: "qr",
+        connection_status: { state: "AUTHENTICATED", authenticated: true },
+        fetch_inbound: [{ from: "a@c.us", body: "hi" }]
+      )
+      client = described_class.new(configuration: config)
+
+      expect(client.fetch_inbound(provider: :web_automation)).to eq([{ from: "a@c.us", body: "hi" }])
+    end
+  end
+
+  it "delegates logout to the provider" do
+    Dir.mktmpdir do |dir|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_session_path = File.join(dir, "session.json")
+      config.web_adapter = double(
+        send_message: { success: true, session: {} },
+        fetch_qr_code: "qr",
+        connection_status: { state: "AUTHENTICATED", authenticated: true },
+        logout: { success: true }
+      )
+      client = described_class.new(configuration: config)
+
+      expect(client.logout(provider: :web_automation, metadata: { user_id: 1 })).to eq(success: true)
+    end
+  end
 end

data/spec/configuration_spec.rb

@@ -44,4 +44,20 @@ RSpec.describe WhatsAppNotifier::Configuration do
 
     expect { config.validate! }.to raise_error(WhatsAppNotifier::ConfigurationError, /web_adapter must be configured/)
   end
+
+  it "exposes an inbound message handler accessor that defaults to nil" do
+    config = described_class.new
+    expect(config.on_inbound_message_handler).to be_nil
+
+    handler = ->(msg) { msg }
+    config.on_inbound_message_handler = handler
+    expect(config.on_inbound_message_handler).to eq(handler)
+  end
+
+  it "validates without requiring fetch_inbound on the adapter (inbound is optional)" do
+    config = described_class.new
+    config.web_adapter = double(send_message: {}, fetch_qr_code: "qr", connection_status: {})
+
+    expect { config.validate! }.not_to raise_error
+  end
 end

data/spec/jobs/send_message_job_spec.rb

@@ -24,13 +24,14 @@ RSpec.describe WhatsAppNotifier::Jobs::SendMessageJob do
     expect(result).to be_success
   end
 
-  it "raises when perform_later has no active job base" do
-    hide_const("ActiveJob")
-    expect { described_class.perform_later("JobNotification", to: "+1") }.to raise_error(LoadError)
+  it "falls back to synchronous delivery when ActiveJob is unavailable" do
+    # ActiveJob is not a gem dependency, so the sync-fallback class is the one
+    # that loads; perform_later runs perform_now rather than raising.
+    result = described_class.perform_later("JobNotification", to: "+1")
+    expect(result).to be_success
   end
 
-  it "allows perform_later when active job base is present" do
-    stub_const("ActiveJob::Base", Class.new)
+  it "allows perform_later without raising" do
     expect { described_class.perform_later("JobNotification", to: "+1") }.not_to raise_error
   end
 end

data/spec/notification_spec.rb

@@ -30,14 +30,19 @@ RSpec.describe WhatsAppNotifier::Notification do
     expect(result).to be_success
   end
 
-  it "supports deliver_later when active job exists" do
-    stub_const("ActiveJob::Base", Class.new)
+  it "supports deliver_later" do
     expect { TestNotification.deliver_later(params: { name: "Neha" }) }.not_to raise_error
   end
 
-  it "raises for deliver_later without active job" do
-    hide_const("ActiveJob")
-    expect { TestNotification.deliver_later(params: { name: "Neha" }) }.to raise_error(LoadError)
+  it "falls back to synchronous delivery for deliver_later without active job" do
+    # No ActiveJob dependency → deliver_later runs the job synchronously.
+    result = TestNotification.deliver_later(params: { name: "Neha" })
+    expect(result).to be_success
+  end
+
+  it "supports instance-level deliver_later" do
+    result = TestNotification.with(params: { name: "Neha" }).deliver_later
+    expect(result).to be_success
   end
 
   it "raises when recipient is missing" do

data/spec/providers/web_automation_spec.rb

@@ -106,4 +106,64 @@ RSpec.describe WhatsAppNotifier::Providers::WebAutomation do
       expect(adapter).to have_received(:send_message).with(payload: hash_including(metadata: { user_id: "user-b" }), session: {}).once
     end
   end
+
+  it "fetches inbound via the adapter when enabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, fetch_inbound: [{ from: "x@c.us", body: "hi" }])
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.fetch_inbound(metadata: { user_id: 1 })).to eq([{ from: "x@c.us", body: "hi" }])
+    end
+  end
+
+  it "raises on fetch_inbound when the provider is disabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, fetch_inbound: [])
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter, enabled: false)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.fetch_inbound }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+    end
+  end
+
+  it "raises on fetch_inbound when the adapter lacks inbound support" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.fetch_inbound }.to raise_error(WhatsAppNotifier::ConfigurationError, /inbound capture/)
+    end
+  end
+
+  it "logs out via adapter when enabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, logout: { success: true })
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.logout(metadata: { user_id: 1 })).to eq(success: true)
+    end
+  end
+
+  it "raises on logout when provider disabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, logout: { success: true })
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter, enabled: false)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.logout }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+    end
+  end
+
+  it "raises for missing adapter logout method" do
+    Dir.mktmpdir do |dir|
+      adapter = Object.new
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.logout }.to raise_error(WhatsAppNotifier::ConfigurationError, /web_adapter/)
+    end
+  end
 end

data/spec/session/qr_service_spec.rb

@@ -12,7 +12,7 @@ RSpec.describe WhatsAppNotifier::Session::QrService do
     end
   end
 
-  it "caches qr code per user_id when metadata is provided" do
+  it "fetches a fresh qr on every call (codes expire, so no caching) and passes metadata" do
     Dir.mktmpdir do |dir|
       store = WhatsAppNotifier::Session::Store.new(path: File.join(dir, "s.json"))
       adapter = double
@@ -20,10 +20,9 @@ RSpec.describe WhatsAppNotifier::Session::QrService do
       service = described_class.new(store: store, adapter: adapter)
 
       expect(service.qr_code(metadata: { user_id: 1 })).to eq("qr-user-1")
-      expect(service.qr_code(metadata: { user_id: 1 })).to eq("qr-user-1")
-      expect(service.qr_code(metadata: { user_id: 2 })).to eq("qr-user-2")
+      expect(service.qr_code(metadata: { user_id: 1 })).to eq("qr-user-2")
 
-      expect(adapter).to have_received(:fetch_qr_code).twice
+      expect(adapter).to have_received(:fetch_qr_code).with(metadata: { user_id: 1 }).twice
     end
   end
 

data/spec/web_adapter_spec.rb

@@ -24,6 +24,20 @@ RSpec.describe WhatsAppNotifier::WebAdapter do
     expect(result).to include(success: true, message_id: "k1")
   end
 
+  it "yields the http connection to run the request" do
+    response = http_success(body: { "success" => true })
+    http = instance_double(Net::HTTP, request: response)
+    allow(Net::HTTP).to receive(:start).and_yield(http).and_return(response)
+
+    result = adapter.send_message(
+      payload: { to: "+1", body: "hi", metadata: {}, idempotency_key: "k1" },
+      session: {}
+    )
+
+    expect(result).to include(success: true)
+    expect(http).to have_received(:request)
+  end
+
   it "fetches qr and status data" do
     qr_response = http_success(body: { "qr" => "data:image/png;base64,qr" })
     status_response = http_success(body: { "state" => "AUTHENTICATED", "authenticated" => true, "hasQR" => false })
@@ -52,4 +66,59 @@ RSpec.describe WhatsAppNotifier::WebAdapter do
     expect(adapter.fetch_qr_code(metadata: {})).to be_nil
     expect { adapter.connection_status(metadata: {}) }.to raise_error(/raw-error/)
   end
+
+  it "fetches inbound messages from a bare array body" do
+    body = [
+      { "from" => "919@c.us", "body" => "hi", "messageId" => "m1", "timestamp" => 123, "type" => "chat" }
+    ]
+    allow(Net::HTTP).to receive(:start).and_return(http_success(body: body))
+
+    messages = adapter.fetch_inbound(metadata: { user_id: "u-1" })
+
+    expect(messages).to eq([{ from: "919@c.us", body: "hi", message_id: "m1", timestamp: 123, type: "chat" }])
+  end
+
+  it "fetches inbound from a {messages:} envelope and accepts the message_id alias" do
+    body = { "messages" => [{ "from" => "918@c.us", "body" => "yo", "message_id" => "m2", "timestamp" => 9 }] }
+    allow(Net::HTTP).to receive(:start).and_return(http_success(body: body))
+
+    messages = adapter.fetch_inbound(metadata: { user_id: "u-1" })
+
+    expect(messages.first).to include(from: "918@c.us", message_id: "m2", type: nil)
+  end
+
+  it "returns an empty array when the inbound body is empty" do
+    empty = instance_double(Net::HTTPOK, body: "", code: "200", is_a?: true)
+    allow(Net::HTTP).to receive(:start).and_return(empty)
+
+    expect(adapter.fetch_inbound(metadata: {})).to eq([])
+  end
+
+  it "raises when the inbound fetch fails" do
+    allow(Net::HTTP).to receive(:start).and_return(http_failure(code: "500", body: JSON.generate({ error: "down" })))
+
+    expect { adapter.fetch_inbound(metadata: {}) }.to raise_error(/service request failed/)
+  end
+
+  it "logs out via the service" do
+    allow(Net::HTTP).to receive(:start).and_return(http_success(body: { "success" => true }))
+
+    expect(adapter.logout(metadata: { user_id: "u-1" })).to eq(success: true)
+  end
+
+  it "defaults logout success to false when the service omits it" do
+    allow(Net::HTTP).to receive(:start).and_return(http_success(body: {}))
+
+    expect(adapter.logout(metadata: {})).to eq(success: false)
+  end
+
+  it "executes the request inside the Net::HTTP block" do
+    fake_http = instance_double(Net::HTTP)
+    allow(fake_http).to receive(:request).and_return(http_success(body: { "qr" => "data:image/png;base64,x" }))
+    # Invoke the block so the real request path runs (other specs stub it away).
+    allow(Net::HTTP).to receive(:start) { |*_args, &blk| blk.call(fake_http) }
+
+    expect(adapter.fetch_qr_code(metadata: { user_id: 1 })).to eq("data:image/png;base64,x")
+    expect(fake_http).to have_received(:request)
+  end
 end

data/spec/whatsapp_notifier_spec.rb

@@ -93,11 +93,30 @@ RSpec.describe WhatsAppNotifier do
     allow(fake_client).to receive(:deliver_bulk).and_return(total: 0, success: 0, failed: 0, results: [])
     allow(fake_client).to receive(:scan_qr).and_return("qr-code")
     allow(fake_client).to receive(:connection_status).and_return(state: "QR_REQUIRED")
+    allow(fake_client).to receive(:fetch_inbound).and_return([{ from: "q@c.us" }])
+    allow(fake_client).to receive(:logout).and_return(success: true)
     described_class.instance_variable_set(:@client, fake_client)
 
     expect(described_class.deliver_bulk([], provider: :web_automation)[:total]).to eq(0)
     expect(described_class.scan_qr(provider: :web_automation, metadata: { user_id: 1 })).to eq("qr-code")
     expect(described_class.connection_status(provider: :web_automation, metadata: { user_id: 1 })).to include(state: "QR_REQUIRED")
+    expect(described_class.fetch_inbound(provider: :web_automation, metadata: { user_id: 1 })).to eq([{ from: "q@c.us" }])
+    expect(described_class.logout(provider: :web_automation, metadata: { user_id: 1 })).to eq(success: true)
   end
 
+  it "fetches inbound through the module API end to end" do
+    adapter = double(
+      send_message: { success: true, session: {} },
+      fetch_qr_code: "qr",
+      connection_status: { state: "AUTHENTICATED", authenticated: true },
+      fetch_inbound: [{ from: "z@c.us", body: "ping" }]
+    )
+    described_class.configure do |config|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_adapter = adapter
+    end
+
+    expect(described_class.fetch_inbound(metadata: { user_id: 1 })).to eq([{ from: "z@c.us", body: "ping" }])
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whatsapp_notifier
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Kshitiz Sinha
@@ -79,6 +79,8 @@ files:
 - lib/whatsapp_notifier/railtie.rb
 - lib/whatsapp_notifier/result.rb
 - lib/whatsapp_notifier/services/web_automation/bun.lock
+- lib/whatsapp_notifier/services/web_automation/inbound.test.ts
+- lib/whatsapp_notifier/services/web_automation/inbound.ts
 - lib/whatsapp_notifier/services/web_automation/index.ts
 - lib/whatsapp_notifier/services/web_automation/node_modules/@babel/code-frame/LICENSE
 - lib/whatsapp_notifier/services/web_automation/node_modules/@babel/code-frame/README.md