whatsapp_notifier 0.6.0 → 0.8.0

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

@@ -1,14 +1,17 @@
-// Inbound capture core (v0.4.0)
+// Inbound capture core (v0.4.0; two-way since v0.8.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).
+// Policy: surface real 1:1 messages in BOTH directions (phone @c.us or
+// privacy-id @lid) — customer replies AND messages the operator sends from
+// the WhatsApp app itself (fromMe), so host threads show whole conversations.
+// Groups (@g.us), status broadcasts, and non-text system events
+// (e2e_notification, call_log, revoked, …) that carry no real reply are
+// dropped. Captured messages buffer in an in-memory queue drained by GET
+// /inbound/:userId (at-least-once; the host dedupes on messageId — which also
+// eats the fromMe echo of its own /send calls — and decides relevance by
+// matching the resolved phone to its own recipient records).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
@@ -19,6 +22,32 @@ 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;
+    // 0.8.0 two-way capture. Present ONLY on operator-sent messages (fromMe),
+    // where `to` carries the counterparty (customer) chat id the host threads
+    // on. Inbound payloads keep the exact pre-0.8.0 shape.
+    fromMe?: boolean;
+    to?: 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;
@@ -92,11 +121,62 @@ export function drainInbound(userId: string): InboundMsg[] {
     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).
+// ── Self-send echo registry ──
+//
+// Every POST /send fires its own fromMe message_create echo. Letting that
+// echo run the capture pipeline is pure waste: a media send re-downloads the
+// attachment it just uploaded (up to the 30s download budget on the sending
+// Chromium) and stores bytes nobody will ever fetch against the per-user
+// media cap — at campaign scale those phantom copies churn the cap, evicting
+// REAL customer inbound media the operator still wants. The echo's payload is
+// redundant too: the /send response already handed the host this exact
+// messageId, and the host's id-dedupe would discard the echo anyway — so a
+// registry hit is suppressed ENTIRELY (no media resolution, no enqueue, no
+// webhook), which also closes the host-side echo-beats-response adopt race
+// for same-process sends. Messages NOT in the registry (typed on the phone,
+// or replayed by the reconnect backfill) flow through unchanged.
+//
+// Best-effort by design: the registry is in-memory, so an echo landing after
+// a service restart (or one that fires before /send finishes registering the
+// id) flows through — the host's id-dedupe catches it, harmless. Bounded per
+// user and TTL'd because echoes land within seconds of the send; the limits
+// only have to outlive the echo lag, not the conversation.
+export const SELF_SEND_MAX = 200;
+export const SELF_SEND_TTL_MS = 10 * 60 * 1000;
+
+// userId → (messageId → expiry epoch ms). Maps iterate in insertion order,
+// so the first key is always the oldest send — eviction is O(evicted).
+const selfSendIds = new Map<string, Map<string, number>>();
+
+export function rememberSelfSend(userId: string, messageId: string, nowMs = Date.now()) {
+    let ids = selfSendIds.get(userId);
+    if (!ids) { ids = new Map(); selfSendIds.set(userId, ids); }
+    ids.set(messageId, nowMs + SELF_SEND_TTL_MS);
+    while (ids.size > SELF_SEND_MAX) {
+        ids.delete(ids.keys().next().value as string);
+    }
+}
+
+export function isSelfSend(userId: string, messageId: string, nowMs = Date.now()): boolean {
+    const ids = selfSendIds.get(userId);
+    const expiry = ids && ids.get(messageId);
+    if (expiry === undefined) return false;
+    if (nowMs > expiry) {
+        ids!.delete(messageId); // expired — forget it so the map stays lean
+        return false;
+    }
+    return true;
+}
+
+// Sanity filter for a real 1:1 message in either direction. Accepts both
+// phone-number chats (@c.us) and privacy-id chats (@lid — newer WhatsApp
+// delivers replies from an @lid). The jid gate always validates the
+// COUNTERPARTY: the customer is at `from` on inbound but at `to` on
+// operator-sent (fromMe) messages — gating fromMe on `from` (the operator's
+// own jid, always @c.us) would let group/status posts through. Groups
+// (@g.us) and status (@broadcast) are dropped. 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.
@@ -105,23 +185,149 @@ const TEXTUAL_TYPES = new Set([
 ]);
 
 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) return false;
+    const counterparty: string = (msg.fromMe ? msg.to : msg.from) || '';
+    if (!counterparty.endsWith('@c.us') && !counterparty.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 {
+export function normalizeInbound(msg: any, media?: InboundMediaInfo): InboundMsg {
     const from: string = msg.from || '';
-    return {
+    const to: string = msg.to || '';
+    // The fallback id keys on the COUNTERPARTY (the customer): on fromMe the
+    // `from` is the operator's own jid, shared by every chat — id-less
+    // operator messages to different customers in the same second must not
+    // collide in the host's dedupe.
+    const counterparty = msg.fromMe ? to : from;
+    const inbound: InboundMsg = {
         from,
         body: msg.body || '',
-        messageId: (msg.id && msg.id._serialized) || `${from}-${msg.timestamp}`,
+        messageId: (msg.id && msg.id._serialized) || `${counterparty}-${msg.timestamp}`,
         timestamp: msg.timestamp || Math.floor(Date.now() / 1000),
         type: msg.type || 'chat'
     };
+    // fromMe/to are added ONLY for operator-sent messages — like the media
+    // keys below, inbound payloads keep the exact pre-0.8.0 shape so older
+    // hosts stay byte-compatible and newer ones key-gate on fromMe presence.
+    if (msg.fromMe) {
+        inbound.fromMe = true;
+        inbound.to = to;
+    }
+    // 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;
+
+    // Operator-sent messages take their own (shorter) path: no sender to
+    // resolve, and the chat is keyed by the counterparty at msg.to.
+    if (msg.fromMe) return processOwnMessage(userId, msg, deps);
+
+    // 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);
+}
+
+// Operator-sent (fromMe) leg of the pipeline. The senderName contact lookup
+// is skipped on purpose: the "sender" is the operator themself, so the name
+// adds nothing and the lookup costs a puppeteer roundtrip per message. Media
+// resolution, enqueue and webhook are the SAME as inbound — operator photos/
+// documents sync through the existing GET /media path under the same caps.
+async function processOwnMessage(userId: string, msg: any, deps: CaptureDeps) {
+    // The echo of our own /send: suppress entirely — no media resolution, no
+    // enqueue, no webhook (see the self-send registry above for why).
+    // rememberTarget is skipped too: /send already allowlisted this recipient.
+    const messageId = msg.id && msg.id._serialized;
+    if (messageId && isSelfSend(userId, messageId)) return;
+
+    const to: string = msg.to || '';
+    // An @lid counterparty carries no phone number the host can thread on,
+    // and unlike inbound there is no contact handle to resolve it through
+    // (msg.getContact() resolves the SENDER — here, the operator). Rare in
+    // practice: operator-initiated chats are keyed by the phone @c.us. Drop
+    // with a log rather than forward an unmatchable body.
+    if (to.endsWith('@lid')) {
+        console.log(`Dropping fromMe message to unresolved @lid chat for ${userId}`);
+        return;
+    }
+
+    // Same kept-message-earns-the-download rule as inbound: every resolver
+    // failure mode reports 'unavailable' instead of throwing.
+    let media: InboundMediaInfo | undefined;
+    if (msg.hasMedia) {
+        media = await deps.resolveMedia(userId, msg);
+    }
+
+    const inbound = normalizeInbound(msg, media);
+
+    // A fromMe message to a brand-new number means the operator opened the
+    // conversation in the WhatsApp app — allowlist the chat exactly like
+    // /send does for its recipients, so the reconnect backfill can replay
+    // this conversation after a disconnect window too.
+    rememberTarget(userId, to);
+
+    enqueueInbound(userId, inbound);
+    if (deps.push) deps.push(userId, inbound);
 }
 
 // Minimal slice of whatsapp-web.js Client that backfill needs — a seam so the
@@ -179,10 +385,14 @@ export async function backfillTargets(
 export function clearInbound(userId: string) {
     inboundQueues.delete(userId);
     outboundTargets.delete(userId);
+    // Self-send echo ids belong to the old pairing too — and suppression must
+    // never leak across a re-pair (however unlikely an id collision is).
+    selfSendIds.delete(userId);
 }
 
 // Test helper: wipe in-memory state between examples.
 export function resetInboundState() {
     inboundQueues.clear();
     outboundTargets.clear();
+    selfSendIds.clear();
 }

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

@@ -16,14 +16,23 @@ import {
     InboundMsg,
     configureInbound,
     rememberTarget,
-    rememberLidAlias,
+    rememberSelfSend,
     backfillTargets,
-    enqueueInbound,
+    resolveChat,
     drainInbound,
     clearInbound,
-    shouldCapture,
-    normalizeInbound
+    processInbound
 } from './inbound';
+import { chatsResponse, historyResponse, refetchResponse, HistoryDeps, RefetchDeps } from './history';
+import {
+    configureMedia,
+    resolveMediaForMessage,
+    sweepExpired,
+    clearUserMedia,
+    mediaGetResponse,
+    mediaDeleteResponse
+} from './media';
+import { sentMessageId } from './send';
 
 const app = new Hono();
 const port = Number(process.env.PORT || 3001);
@@ -71,8 +80,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 +101,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);
     }
@@ -124,8 +118,10 @@ async function captureInbound(userId: string, msg: any) {
 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.
+    // without scraping every personal conversation on the linked number.
+    // fetchMessages returns BOTH directions, so operator-app (fromMe) messages
+    // typed during the window recover too. Live traffic is covered by the
+    // message_create handler; this is just recovery.
     await backfillTargets(userId, client, captureInbound);
 }
 
@@ -205,6 +201,8 @@ async function waitForClientReady(clientData: ClientData, timeoutMs = 30000): Pr
     throw new Error('Client not ready: WhatsApp Web store did not initialize in time');
 }
 
+// Resolves to the sent whatsapp-web.js Message so /send can hand the real
+// message id back to the host (the echo-dedupe key for two-way capture).
 async function sendMessageWithRetry(client: Client, clientData: ClientData, chatId: string, message: string, mediaUrl?: string | null) {
     const maxAttempts = 5;
 
@@ -216,12 +214,10 @@ async function sendMessageWithRetry(client: Client, clientData: ClientData, chat
             if (mediaUrl) {
                 const { MessageMedia } = require('whatsapp-web.js');
                 const media = await MessageMedia.fromUrl(mediaUrl);
-                await client.sendMessage(chatId, media, { caption: message });
-            } else {
-                await client.sendMessage(chatId, message);
+                return await client.sendMessage(chatId, media, { caption: message });
             }
 
-            return;
+            return await client.sendMessage(chatId, message);
         } catch (error) {
             console.error(`Send attempt ${attempt}/${maxAttempts} failed for chat ${chatId}:`, error);
 
@@ -312,10 +308,13 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         backfillInbound(userId, client).catch((e) => console.error(`Backfill failed for ${userId}`, e));
     });
 
-    // Capture inbound replies. Only 'message_create' — it fires reliably for
-    // every message across linked/multi-device sessions (plain 'message'
-    // silently never fires on some). shouldCapture drops our own sends (fromMe)
-    // + groups/status; the queue dedupes on message_id on the Rails side.
+    // Capture BOTH directions of every 1:1 chat. Only 'message_create' — it
+    // fires reliably for every message across linked/multi-device sessions
+    // (plain 'message' silently never fires on some) and, unlike 'message',
+    // also fires for operator-sent (fromMe) messages, which the host threads
+    // as the other half of the conversation since 0.8.0. shouldCapture drops
+    // groups/status; the host dedupes on message_id — including the fromMe
+    // echo of its own /send calls.
     client.on('message_create', (msg) => captureInbound(userId, msg));
 
     client.on('authenticated', () => {
@@ -460,6 +459,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 +517,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 });
 });
@@ -534,13 +546,21 @@ app.post('/send/:userId', async (c) => {
 
     try {
         const chatId = to.includes('@c.us') ? to : `${to}@c.us`;
-        await sendMessageWithRetry(data.client, data, chatId, message, mediaUrl);
+        const sent = await sendMessageWithRetry(data.client, data, chatId, message, mediaUrl);
 
         // Record the recipient so their replies survive a reconnect backfill.
         rememberTarget(userId, chatId);
 
         data.lastUsed = Date.now();
-        return c.json({ success: true });
+        // messageId is the echo-dedupe key: this send fires its own fromMe
+        // message_create, which the host must match by id (see send.ts).
+        const messageId = sentMessageId(sent);
+        // Register the id so the echo is suppressed service-side (no media
+        // re-download, no queue slot, no webhook — see inbound.ts). Best
+        // effort: an echo that already fired before sendMessage resolved
+        // flows through, and the host's id-dedupe catches it.
+        if (messageId) rememberSelfSend(userId, messageId);
+        return c.json({ success: true, messageId });
     } catch (error: any) {
         console.error(`Send error for user ${userId}:`, error);
         return c.json({ success: false, error: error.message }, 500);
@@ -561,6 +581,68 @@ 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));
+
+// ── Chat history (history.ts) ──
+//
+// Shared deps for the two history routes: the SAME pairing fast-reject and
+// client accessor /send uses (never any other initialization path), plus
+// inbound.ts's chat resolver + reconnect allowlist.
+const historyDeps: HistoryDeps = {
+    hasPaired: (userId) => hasPairedSession(userId, clients, sessionDirForUser),
+    getClient: getOrCreateClient,
+    resolveChat,
+    rememberTarget
+};
+
+// GET /chats/:userId — list the paired number's 1:1 chats (discovery for the
+// host's old-conversation sync). Token-gated like /media; paired+ready gated
+// like /send; capped at the newest 500 (see history.ts).
+app.get('/chats/:userId', (c) =>
+    chatsResponse(c.req.param('userId'), c.req.header('X-WA-Token'), WEBHOOK_TOKEN, historyDeps));
+
+// POST /history/:userId { chatId, limit } — replay one chat's history through
+// the live-capture normalizer and return it DIRECTLY in the response (no
+// queue, no webhook — the host ingests synchronously). History media is
+// marked unavailable by design, never downloaded (see history.ts).
+app.post('/history/:userId', async (c) =>
+    historyResponse(
+        c.req.param('userId'),
+        await c.req.json().catch(() => ({})),
+        c.req.header('X-WA-Token'),
+        WEBHOOK_TOKEN,
+        historyDeps
+    ));
+
+// POST /media/:userId/refetch { messageId, chatId } — WhatsApp tap-to-download.
+// The host calls this when an operator opens an evicted/expired media bubble:
+// re-pull THAT message's bytes on demand, store them (cap re-enforced), and
+// report ready so the host can GET /media as usual. Token-gated + paired-ready
+// gated like /history; media no longer upstream → 404 'gone'. Reuses the live
+// resolveMediaForMessage pipeline (per-message size cap + 30s timeout).
+const refetchDeps: RefetchDeps = {
+    ...historyDeps,
+    getMessageById: (client, messageId) => client.getMessageById(messageId),
+    resolveMedia: (userId, msg) => resolveMediaForMessage(userId, msg)
+};
+
+app.post('/media/:userId/refetch', async (c) =>
+    refetchResponse(
+        c.req.param('userId'),
+        await c.req.json().catch(() => ({})),
+        c.req.header('X-WA-Token'),
+        WEBHOOK_TOKEN,
+        refetchDeps
+    ));
+
 
 console.log(`Starting Multi-User WhatsApp service (Bun Native) on port ${port}...`);