whatsapp_notifier 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0202159fbe717a98a4bb69187abf75876258ce5f1d0bb1840deb46ed83096002'
-  data.tar.gz: df8857673fc57f8be6ba9681eb959d9aa842a051a522ceed530a19e57868d1b3
+  metadata.gz: fc24f1c67db14b3be6dfc49310e7a86987c520c6ddc595895d6e00b483aafab4
+  data.tar.gz: e600799c44eeefddfa3476c65894bc1aa430d7c488685e7172c9dcaf5e9c27df
 SHA512:
-  metadata.gz: a9618573ca58faba4ba1b98c69626caf7627288a1b490ea102b39053166d15552d83a30e7a2583db5702111a312cd33b6bdb7dc02c011d2f355161259532cc9a
-  data.tar.gz: 973ff970420fc87db0280f82758f2ba51cf6cc54189d0b1ea0a2ba84f43aaa993ec4938b6a606ebae0cb14bc38e314c832b6c56fb1622712433a64fb0eaa7c33
+  metadata.gz: f85d85f6e467055c93c8c5ba30c325a8d68f1113b5d257d3b26f8397976706fb771cff63cedadba721f50c87d24f5159a79fac570ce6e1b2a2cffe84be877b30
+  data.tar.gz: 747e11eeee1780b222f7e46c044dad8bd8235462dadc5b3f8f0afb2d4d2f04a84c7e71ece2bfbcbab4571a061cda6cfd2671e0e736dbe7a932d4b81d86101df4

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/config/routes.rb

@@ -1,6 +1,7 @@
 WhatsAppNotifier::Engine.routes.draw do
-  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    "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,10 @@ 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

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/providers/web_automation.rb

@@ -48,6 +48,19 @@ 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
 

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,6 +3,16 @@ 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);
@@ -34,6 +44,72 @@ interface ClientData {
 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);
@@ -197,8 +273,21 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         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;
@@ -326,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) {
@@ -334,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,13 +9,11 @@ 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))

data/lib/whatsapp_notifier/version.rb

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

data/lib/whatsapp_notifier/web_adapter.rb

@@ -52,6 +52,25 @@ 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)

data/lib/whatsapp_notifier.rb

@@ -62,6 +62,10 @@ 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

data/spec/client_spec.rb

@@ -50,6 +50,23 @@ RSpec.describe WhatsAppNotifier::Client do
     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

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/providers/web_automation_spec.rb

@@ -107,6 +107,36 @@ RSpec.describe WhatsAppNotifier::Providers::WebAutomation do
     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 })

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 })
@@ -53,6 +67,39 @@ RSpec.describe WhatsAppNotifier::WebAdapter do
     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 }))
 

data/spec/whatsapp_notifier_spec.rb

@@ -93,13 +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.4.0
+  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