whatsapp_notifier 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a84b4298c91af2e175b2a8aa46fd2b9101e5b5729558f1387325a8c39894a31
-  data.tar.gz: e11b629a0b342288eb8199ed95eaf6aa72f9d7ce557984c76e71b58f2e37bb4c
+  metadata.gz: 554f8799b1a8ce9c71c59f4b801d3ea5f614a313f2ce22df8f93a6983ba06780
+  data.tar.gz: 0015b28a62c3471d63fbaa13060faec05084ede1acd6df72018d6e7fee38ca4a
 SHA512:
-  metadata.gz: ed49385c1ea444b94a1ee99ca5ec1c891145bb5474a63544e314a715f85dab8712b743908ce1765efd9c1981b476287c62ed24930061a5fb5a667f2ff781011a
-  data.tar.gz: 5b7eaec3a131a137edc5ce9dcba1e7cadcabe74bf210ef167975bb6952ac087b803a31d573f6c67b62f188be8d6c6593cd503a371cbdf57e91337a3ddf06f14e
+  metadata.gz: 5c8eed1d767807dfbd1de97daa5f3f017f5a853acc7c008a66f99523d135c12b3f420e8866b03e0523e53d45b2df4efdc29036b527dc359918b99b23b19e279e
+  data.tar.gz: 0a065dd16263cba9b7f4f8c27f5b4d5b0aae1ba2b0e0b55f8d1a767b61e08804fbdbd432998532298aa33ce2c5cefe2e9b6841c3a2e35c59dda0752e4a86a255

data/README.md

@@ -57,9 +57,11 @@ status = WhatsAppNotifier.connection_status(metadata: { user_id: current_user.id
 ## 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.
+service — including any downloaded inbound media and queued replies, which
+belong to the old pairing — 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 })
@@ -144,6 +146,21 @@ creates a WhatsApp client — so it is safe to poll every few seconds:
 those have a fully hydrated WhatsApp Web store. Prometheus metrics live at
 `GET /metrics`.
 
+## Upgrading to 0.7.0
+
+- **If your app monkey-patches `WhatsAppNotifier::WebAdapter#request`** (a
+  common trick to bolt TLS onto the service URL): the shared JSON path now
+  also carries `DELETE` (`delete_media`) and attaches `X-WA-Token` when
+  `WHATSAPP_WEBHOOK_TOKEN` is set. A patch that only routes `POST`/`GET` or
+  drops headers will break the new media calls. Prefer retiring the patch
+  entirely — the adapter now honors `https://` service URLs natively on both
+  the JSON control plane and the binary media path (`use_ssl` follows the URL
+  scheme), so TLS no longer needs a patch.
+- **Logout now wipes stored media**: `POST /logout` removes the user's
+  downloaded inbound media along with the session dir and queued replies.
+  Fetch (and ideally `delete_media`) anything you want to keep before logging
+  a user out.
+
 ## Notes
 
 - This gem uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.

data/lib/generators/whatsapp_notifier/install_service_generator.rb

@@ -14,6 +14,7 @@ module WhatsAppNotifier
         index.ts
         inbound.ts
         init_gate.ts
+        media.ts
         metrics.ts
         sessions.ts
         package.json

data/lib/whatsapp_notifier/client.rb

@@ -31,6 +31,14 @@ module WhatsAppNotifier
       provider_for(provider || @configuration.provider).fetch_inbound(metadata: metadata)
     end
 
+    def fetch_media(message_id:, metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).fetch_media(message_id: message_id, metadata: metadata)
+    end
+
+    def delete_media(message_id:, metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).delete_media(message_id: message_id, metadata: metadata)
+    end
+
     def logout(metadata: {}, provider: nil)
       provider_for(provider || @configuration.provider).logout(metadata: metadata)
     end

data/lib/whatsapp_notifier/providers/web_automation.rb

@@ -61,6 +61,27 @@ module WhatsAppNotifier
         adapter.fetch_inbound(metadata: metadata)
       end
 
+      # Media helpers are optional adapter capabilities (added in v0.7.0) —
+      # same guard idiom as fetch_inbound so older adapters fail with a clear
+      # ConfigurationError rather than NoMethodError.
+      def fetch_media(message_id:, metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter does not support media fetch (upgrade to a fetch_media-capable adapter)" unless adapter.respond_to?(:fetch_media)
+
+        adapter.fetch_media(message_id: message_id, metadata: metadata)
+      end
+
+      def delete_media(message_id:, metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter does not support media deletion (upgrade to a delete_media-capable adapter)" unless adapter.respond_to?(:delete_media)
+
+        adapter.delete_media(message_id: message_id, 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

@@ -15,9 +15,12 @@ import {
     clearInbound,
     shouldCapture,
     normalizeInbound,
+    processInbound,
     resetInboundState,
-    type ChatResolver
+    type ChatResolver,
+    type InboundMsg
 } from './inbound';
+import { configureMedia, resolveMediaForMessage, mediaDiskBytes, resetMediaState } from './media';
 
 const root = mkdtempSync(join(tmpdir(), 'wa-inbound-'));
 const dirFor = (userId: string) => join(root, `session-user-${userId}`);
@@ -215,3 +218,148 @@ test('normalizeInbound maps fields and falls back on missing id', () => {
     expect(b.body).toBe('');
     expect(b.type).toBe('chat');
 });
+
+// ── processInbound (capture pipeline ordering) ──
+
+const LID_FROM = '125417440686124@lid';
+
+function mediaMsg(overrides: any = {}) {
+    return msg({
+        hasMedia: true,
+        type: 'image',
+        _data: { size: 10, mimetype: 'image/jpeg' },
+        getContact: async () => ({ pushname: 'Asha' }),
+        downloadMedia: async () => ({
+            data: Buffer.from('jpeg-bytes').toString('base64'),
+            mimetype: 'image/jpeg',
+            filename: 'beach.jpg'
+        }),
+        ...overrides
+    });
+}
+
+// Wire the real media store at a per-test root so "nothing written" is a
+// statement about the disk, not about a stub.
+function useMediaRoot(name: string) {
+    const mediaRoot = join(root, name);
+    configureMedia(() => mediaRoot);
+    resetMediaState();
+    return mediaRoot;
+}
+
+test('processInbound drops an unresolvable @lid BEFORE any media download', async () => {
+    const mediaRoot = useMediaRoot('media-lid-drop');
+    let resolveCalls = 0;
+    let downloads = 0;
+    const m = mediaMsg({
+        from: LID_FROM,
+        getContact: async () => ({ pushname: 'Asha' }), // no phone → unresolvable
+        downloadMedia: async () => { downloads += 1; return null; }
+    });
+
+    await processInbound('pi1', m, {
+        resolveMedia: (u, message) => { resolveCalls += 1; return resolveMediaForMessage(u, message); }
+    });
+
+    expect(resolveCalls).toBe(0);               // dropped before the download path
+    expect(downloads).toBe(0);
+    expect(drainInbound('pi1')).toEqual([]);
+    expect(existsSync(mediaRoot)).toBe(false);  // nothing written to disk
+    expect(mediaDiskBytes()).toBe(0);
+});
+
+test('processInbound resolves an @lid sender, then downloads for the kept message', async () => {
+    useMediaRoot('media-lid-kept');
+    rememberTarget('pi2', CUST); // resolved phone is a known outbound target
+    const m = mediaMsg({
+        from: LID_FROM,
+        getContact: async () => ({ pushname: 'Asha', number: '919999000001' })
+    });
+
+    const pushed: InboundMsg[] = [];
+    await processInbound('pi2', m, {
+        resolveMedia: resolveMediaForMessage,
+        push: (_u, inbound) => pushed.push(inbound)
+    });
+
+    const drained = drainInbound('pi2');
+    expect(drained.length).toBe(1);
+    expect(drained[0].from).toBe(CUST);                     // resolved to the phone
+    expect(drained[0].senderName).toBe('Asha');
+    expect(drained[0].mediaStatus).toBe('available');
+    expect(drained[0].mediaSize).toBe(10);
+    expect(pushed).toEqual(drained);                        // webhook saw the same payload
+    expect(loadTargets('pi2').has(LID_FROM)).toBe(true);    // alias allowlisted for backfill
+});
+
+test('processInbound keeps an @c.us message when the contact lookup fails', async () => {
+    useMediaRoot('media-contact-fail');
+    const m = msg({ getContact: async () => { throw new Error('boom'); } });
+
+    await processInbound('pi3', m, { resolveMedia: resolveMediaForMessage });
+
+    const drained = drainInbound('pi3');
+    expect(drained.length).toBe(1);
+    expect(drained[0].from).toBe(CUST);
+    expect('senderName' in drained[0]).toBe(false);
+});
+
+test('processInbound enqueues type-only when the media resolver reports a failure', async () => {
+    const m = mediaMsg({});
+    await processInbound('pi4', m, {
+        resolveMedia: async () => ({ mediaStatus: 'unavailable', mediaError: 'download_failed' })
+    });
+
+    const drained = drainInbound('pi4');
+    expect(drained.length).toBe(1);
+    expect(drained[0].hasMedia).toBe(true);
+    expect(drained[0].mediaStatus).toBe('unavailable');
+    expect(drained[0].mediaError).toBe('download_failed');
+});
+
+test('processInbound rejects filtered messages without resolving anything', async () => {
+    let resolveCalls = 0;
+    const deps = { resolveMedia: async () => { resolveCalls += 1; return { mediaStatus: 'available' as const }; } };
+
+    await processInbound('pi5', mediaMsg({ fromMe: true }), deps);
+    await processInbound('pi5', mediaMsg({ from: '12@g.us' }), deps);
+
+    expect(resolveCalls).toBe(0);
+    expect(drainInbound('pi5')).toEqual([]);
+});
+
+// 0.6.0 wire back-compat: text payloads must keep the exact five-field shape —
+// no media keys, not even hasMedia:false (hosts key-gate on hasMedia presence).
+test('normalizeInbound keeps the 0.6.0 shape for non-media messages', () => {
+    const plain = normalizeInbound(msg({ hasMedia: false }));
+    expect(Object.keys(plain).sort()).toEqual(['body', 'from', 'messageId', 'timestamp', 'type']);
+});
+
+test('normalizeInbound flags hasMedia even when no verdict is supplied', () => {
+    const out = normalizeInbound(msg({ hasMedia: true, type: 'image' }));
+    expect(out.hasMedia).toBe(true);
+    expect(out.type).toBe('image');
+    expect('mediaStatus' in out).toBe(false);                // verdict is capture-level
+});
+
+test('normalizeInbound merges an available media verdict into the payload', () => {
+    const out = normalizeInbound(msg({ hasMedia: true, type: 'image' }), {
+        mediaStatus: 'available', mediaMime: 'image/jpeg', mediaFilename: 'beach.jpg', mediaSize: 1024
+    });
+    expect(out).toEqual({
+        from: CUST, body: 'hello', messageId: 'true_919999000001@c.us_ABC',
+        timestamp: 1717000000, type: 'image',
+        hasMedia: true, mediaStatus: 'available',
+        mediaMime: 'image/jpeg', mediaFilename: 'beach.jpg', mediaSize: 1024
+    });
+});
+
+test('normalizeInbound merges an unavailable verdict with its typed reason', () => {
+    const out = normalizeInbound(msg({ hasMedia: true, type: 'video' }), {
+        mediaStatus: 'unavailable', mediaError: 'unsupported_type'
+    });
+    expect(out.hasMedia).toBe(true);
+    expect(out.mediaStatus).toBe('unavailable');
+    expect(out.mediaError).toBe('unsupported_type');
+    expect('mediaMime' in out).toBe(false);
+});

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

@@ -19,6 +19,27 @@ export interface InboundMsg {
     messageId: string;
     timestamp: number;
     type: string;
+    // 0.7.0 media + sender enrichment. ALL optional and only present when the
+    // message actually carries them, so the wire format stays byte-compatible
+    // with 0.6.0 hosts (and 0.7.0 hosts can key-gate on hasMedia).
+    hasMedia?: boolean;
+    mediaStatus?: 'available' | 'unavailable';
+    mediaError?: string;
+    mediaMime?: string;
+    mediaFilename?: string;
+    mediaSize?: number;
+    senderName?: string;
+}
+
+// Media verdict merged into the payload by captureInbound — structurally
+// matches media.ts's MediaResolution without importing it (inbound stays the
+// dependency-free core).
+export interface InboundMediaInfo {
+    mediaStatus: 'available' | 'unavailable';
+    mediaError?: string;
+    mediaMime?: string;
+    mediaFilename?: string;
+    mediaSize?: number;
 }
 
 export const INBOUND_QUEUE_CAP = 1000;
@@ -113,15 +134,82 @@ export function shouldCapture(userId: string, msg: any): boolean {
     return true;
 }
 
-export function normalizeInbound(msg: any): InboundMsg {
+export function normalizeInbound(msg: any, media?: InboundMediaInfo): InboundMsg {
     const from: string = msg.from || '';
-    return {
+    const inbound: InboundMsg = {
         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'
     };
+    // Media keys are added ONLY for media messages so text payloads keep the
+    // exact 0.6.0 five-field shape (hosts key-gate on hasMedia presence).
+    if (msg.hasMedia) inbound.hasMedia = true;
+    if (media) Object.assign(inbound, media);
+    return inbound;
+}
+
+// ── Capture pipeline ──
+//
+// Extracted from index.ts so the ordering contract is unit-testable:
+// sanity filter → contact/@lid sender resolution (drop early) → media
+// download → normalize → enqueue → optional webhook push. The media resolver
+// is injected (media.ts's resolveMediaForMessage in production) so this file
+// stays the dependency-free core.
+export interface CaptureDeps {
+    resolveMedia: (userId: string, msg: any) => Promise<InboundMediaInfo>;
+    push?: (userId: string, msg: InboundMsg) => void;
+}
+
+export async function processInbound(userId: string, msg: any, deps: CaptureDeps) {
+    if (!shouldCapture(userId, msg)) return;
+
+    // One best-effort contact lookup feeds both the sender's display name
+    // and the @lid phone resolution. Failure must never drop the message —
+    // unless the sender is an unresolvable @lid (handled below).
+    let contact: any;
+    try {
+        contact = await msg.getContact();
+    } catch (e) {
+        console.error(`contact lookup failed for ${userId}`, e);
+    }
+
+    // Resolve the sender BEFORE downloading media. Newer WhatsApp delivers
+    // the reply's `from` as an @lid privacy id with no phone number, which
+    // the host can't match; if the contact can't supply the real phone the
+    // message is dropped — and a dropped message must not have cost a
+    // download that leaves up to 25MB of unreferenced bytes on disk.
+    const rawFrom: string = msg.from || '';
+    let from = rawFrom;
+    if (rawFrom.endsWith('@lid')) {
+        const num = contact && (contact.number || (contact.id && contact.id.user));
+        if (num) from = `${String(num).replace(/\D/g, '')}@c.us`;
+        // Still an @lid => no phone to match or scope by. Drop it rather than
+        // forward an unmatchable, unpurgeable plaintext body.
+        if (from.endsWith('@lid')) return;
+    }
+
+    // Only a kept message earns the download. Every resolver failure mode
+    // returns an 'unavailable' verdict instead of throwing, so the message
+    // still reaches the host type-only.
+    let media: InboundMediaInfo | undefined;
+    if (msg.hasMedia) {
+        media = await deps.resolveMedia(userId, msg);
+    }
+
+    const inbound = normalizeInbound(msg, media);
+    inbound.from = from;
+    const senderName = contact && (contact.pushname || contact.name || contact.shortName);
+    if (senderName) inbound.senderName = String(senderName);
+    if (rawFrom.endsWith('@lid')) {
+        // Known recipient replying from a privacy-number chat: allowlist the
+        // @lid chat id too, so the reconnect backfill can re-open this chat.
+        rememberLidAlias(userId, rawFrom, from);
+    }
+
+    enqueueInbound(userId, inbound);
+    if (deps.push) deps.push(userId, inbound);
 }
 
 // Minimal slice of whatsapp-web.js Client that backfill needs — a seam so the

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

@@ -16,14 +16,19 @@ import {
     InboundMsg,
     configureInbound,
     rememberTarget,
-    rememberLidAlias,
     backfillTargets,
-    enqueueInbound,
     drainInbound,
     clearInbound,
-    shouldCapture,
-    normalizeInbound
+    processInbound
 } from './inbound';
+import {
+    configureMedia,
+    resolveMediaForMessage,
+    sweepExpired,
+    clearUserMedia,
+    mediaGetResponse,
+    mediaDeleteResponse
+} from './media';
 
 const app = new Hono();
 const port = Number(process.env.PORT || 3001);
@@ -71,8 +76,10 @@ const initRetries = new InitRetryLimiter(MAX_INIT_RETRIES);
 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.
+// Tell the inbound core how to resolve each user's on-disk session dir, and
+// the media store where downloaded inbound media lives (survives restarts).
 configureInbound(sessionDirForUser);
+configureMedia(() => join(SESSION_BASE_DIR, 'media'));
 
 async function pushWebhook(userId: string, msg: InboundMsg) {
     if (!WEBHOOK_URL) return;
@@ -90,32 +97,15 @@ async function pushWebhook(userId: string, msg: InboundMsg) {
     }
 }
 
-// Wrapper: sanity filter → normalize → resolve @lid → enqueue → optional webhook.
+// Wrapper around the testable pipeline in inbound.ts (sanity filter → sender
+// resolution with early @lid drop → media download → normalize → enqueue →
+// webhook). The catch keeps a single bad message from killing the listener.
 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')) {
-            const rawFrom = inbound.from;
-            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;
-            // Known recipient replying from a privacy-number chat: allowlist the
-            // @lid chat id too, so the reconnect backfill can re-open this chat.
-            rememberLidAlias(userId, rawFrom, inbound.from);
-        }
-        enqueueInbound(userId, inbound);
-        pushWebhook(userId, inbound);
+        await processInbound(userId, msg, {
+            resolveMedia: resolveMediaForMessage,
+            push: pushWebhook
+        });
     } catch (e) {
         console.error(`captureInbound error for ${userId}`, e);
     }
@@ -460,6 +450,14 @@ setInterval(() => {
             destroyClient(userId, wipe).catch(console.error);
         }
     }
+
+    // Evict downloaded inbound media past its TTL (and refresh the disk-cap
+    // accounting) on the same cadence — a sweep failure must not stop reaping.
+    try {
+        sweepExpired();
+    } catch (e) {
+        console.error('Media sweep failed', e);
+    }
 }, SWEEP_INTERVAL_MS);
 
 // API Routes
@@ -510,6 +508,11 @@ app.post('/logout/:userId', async (c) => {
     // anything captured between the last poll and this logout would sit in
     // memory and replay into the WRONG pairing if this userId pairs again.
     clearInbound(userId);
+    // Logout privacy contract: downloaded media belongs to the old pairing.
+    // Without this wipe, customer photos/documents stayed on disk (and
+    // fetchable via GET /media) for up to the 48h TTL after the operator
+    // severed the pairing.
+    clearUserMedia(userId);
     initializingClients.delete(userId);
     return c.json({ success: true });
 });
@@ -561,6 +564,16 @@ app.get('/inbound/:userId', async (c) => {
     return c.json({ messages: drainInbound(userId) });
 });
 
+// GET/DELETE /media/:userId/:messageId — serve / evict downloaded inbound
+// media. Token-gated when WHATSAPP_WEBHOOK_TOKEN is set; ids are sanitized in
+// the store; NEVER calls getOrCreateClient (same fast-reject rule as /inbound:
+// fetching bytes for a never-paired user must not boot a Chromium).
+app.get('/media/:userId/:messageId', (c) =>
+    mediaGetResponse(c.req.param('userId'), c.req.param('messageId'), c.req.header('X-WA-Token'), WEBHOOK_TOKEN));
+
+app.delete('/media/:userId/:messageId', (c) =>
+    mediaDeleteResponse(c.req.param('userId'), c.req.param('messageId'), c.req.header('X-WA-Token'), WEBHOOK_TOKEN));
+
 
 console.log(`Starting Multi-User WhatsApp service (Bun Native) on port ${port}...`);