whatsapp_notifier 0.8.1 → 0.9.1

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

@@ -54,6 +54,13 @@ export const INBOUND_QUEUE_CAP = 1000;
 
 const inboundQueues = new Map<string, InboundMsg[]>();
 const outboundTargets = new Map<string, Set<string>>();
+// userId → (@lid privacy id → resolved phone @c.us). Learned whenever an @lid
+// is resolved to a phone (inbound contact lookup, fromMe live lookup, history
+// replay) and consulted by the fromMe leg, where msg.getContact() is no help
+// (it resolves the SENDER — the operator). Persisted per user next to
+// outbound_targets.json so a restart doesn't resume dropping operator
+// messages until the customer happens to write again.
+const lidAliases = new Map<string, Map<string, string>>();
 
 // How to resolve a user's on-disk session dir. index.ts wires this to
 // sessionDirForUser; tests point it at a tmp dir.
@@ -66,6 +73,34 @@ function targetsFilePath(userId: string) {
     return join(baseDirResolver(userId), 'outbound_targets.json');
 }
 
+function aliasesFilePath(userId: string) {
+    return join(baseDirResolver(userId), 'lid_aliases.json');
+}
+
+export function loadLidAliases(userId: string): Map<string, string> {
+    const cached = lidAliases.get(userId);
+    if (cached) return cached;
+
+    const map = new Map<string, string>();
+    try {
+        const p = aliasesFilePath(userId);
+        if (existsSync(p)) {
+            const obj = JSON.parse(readFileSync(p, 'utf8'));
+            if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+                for (const [lid, phone] of Object.entries(obj)) {
+                    if (typeof phone === 'string') map.set(lid, phone);
+                }
+            }
+        }
+    } catch (_) { /* corrupt/missing file → start empty */ }
+    lidAliases.set(userId, map);
+    return map;
+}
+
+export function resolveLidAlias(userId: string, lid: string): string | undefined {
+    return loadLidAliases(userId).get(lid);
+}
+
 export function loadTargets(userId: string): Set<string> {
     const cached = outboundTargets.get(userId);
     if (cached) return cached;
@@ -82,15 +117,31 @@ export function loadTargets(userId: string): Set<string> {
     return set;
 }
 
-// After an @lid sender is resolved to a phone @c.us: if the resolved phone is
-// one of our outbound targets, remember the @lid alias too. rememberTarget at
-// send time only ever stores @c.us ids, but for privacy-number accounts the
-// *chat* is keyed by the @lid — so a reconnect backfill that replays targets
-// via chat-id lookup could never re-open that chat, permanently losing any
-// disconnect-window replies. Duplicate captures across the @c.us/@lid pair are
-// fine: the contract is at-least-once and the host dedupes on messageId.
+// After an @lid is resolved to a phone @c.us, two things are remembered:
+//
+// 1. The @lid → phone mapping itself (persisted, see lidAliases): the fromMe
+//    leg has no contact handle of its own, so without this map every operator
+//    message in an @lid-keyed chat would depend on a live lookup succeeding.
+// 2. If the resolved phone is one of our outbound targets, the @lid joins the
+//    allowlist too. rememberTarget at send time only ever stores @c.us ids,
+//    but for privacy-number accounts the *chat* is keyed by the @lid — so a
+//    reconnect backfill that replays targets via chat-id lookup could never
+//    re-open that chat, permanently losing any disconnect-window replies.
+//    Duplicate captures across the @c.us/@lid pair are fine: the contract is
+//    at-least-once and the host dedupes on messageId.
 export function rememberLidAlias(userId: string, rawFrom: string, resolvedFrom: string) {
     if (!rawFrom.endsWith('@lid')) return;
+    const aliases = loadLidAliases(userId);
+    if (aliases.get(rawFrom) !== resolvedFrom) {
+        aliases.set(rawFrom, resolvedFrom);
+        try {
+            const dir = baseDirResolver(userId);
+            if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+            writeFileSync(aliasesFilePath(userId), JSON.stringify(Object.fromEntries(aliases)));
+        } catch (e) {
+            console.error(`Failed to persist @lid alias for ${userId}`, e);
+        }
+    }
     if (loadTargets(userId).has(resolvedFrom)) rememberTarget(userId, rawFrom);
 }
 
@@ -300,15 +351,23 @@ async function processOwnMessage(userId: string, msg: any, deps: CaptureDeps) {
     const messageId = msg.id && msg.id._serialized;
     if (messageId && isSelfSend(userId, messageId)) return;
 
-    const to: string = msg.to || '';
+    const rawTo: string = msg.to || '';
+    let to = rawTo;
     // 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;
+    // and msg.getContact() is no help here (it resolves the SENDER — the
+    // operator). Newer WhatsApp keys some 1:1 chats by the @lid, so EVERY
+    // operator-phone message in such a chat used to hit an unconditional
+    // drop while the customer's side flowed — half the conversation lost.
+    // Resolve it instead, BEFORE any media download (a dropped message must
+    // not have cost one): the alias map the inbound leg learns first, then
+    // one guarded live lookup. Only when both fail is the message dropped —
+    // now the rare case, not every @lid-keyed chat.
+    if (rawTo.endsWith('@lid')) {
+        to = resolveLidAlias(userId, rawTo) || await resolveOwnLidCounterparty(userId, rawTo, msg) || '';
+        if (!to) {
+            console.log(`Dropping fromMe message to unresolved @lid chat for ${userId}`);
+            return;
+        }
     }
 
     // Same kept-message-earns-the-download rule as inbound: every resolver
@@ -319,17 +378,52 @@ async function processOwnMessage(userId: string, msg: any, deps: CaptureDeps) {
     }
 
     const inbound = normalizeInbound(msg, media);
+    // Thread on the resolved phone: the host matches `to` against its own
+    // recipient records, and a raw @lid would never match. The @lid is still
+    // fine as normalizeInbound's fallback-id key — any stable counterparty
+    // string dedupes correctly.
+    inbound.to = to;
 
     // 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.
+    // this conversation after a disconnect window too. For an @lid-keyed
+    // chat the alias call ALSO allowlists the @lid id itself — the id the
+    // chat is actually reachable by (see rememberLidAlias).
     rememberTarget(userId, to);
+    if (rawTo.endsWith('@lid')) rememberLidAlias(userId, rawTo, to);
 
     enqueueInbound(userId, inbound);
     if (deps.push) deps.push(userId, inbound);
 }
 
+// Live fallback for a fromMe @lid counterparty with no learned alias yet
+// (e.g. right after a restart, before the customer writes again). Every wwebjs
+// Message carries its Client, and client.getContactById(<@lid>) is the exact
+// call the inbound leg's msg.getContact() makes for @lid senders — the one
+// path proven to yield the real phone in production. One roundtrip, guarded;
+// a hit is fed into rememberLidAlias so the next fromMe message resolves from
+// the map. contact.id.user is trusted only when the contact id itself is
+// phone-keyed — an @lid contact id would otherwise mint a bogus "phone" out
+// of the privacy id's own digits.
+async function resolveOwnLidCounterparty(userId: string, rawTo: string, msg: any): Promise<string | null> {
+    try {
+        const client = msg.client;
+        if (!client || typeof client.getContactById !== 'function') return null;
+        const contact = await client.getContactById(rawTo);
+        const num = contact && (contact.number ||
+            (contact.id && String(contact.id._serialized || '').endsWith('@c.us') && contact.id.user));
+        const digits = num ? String(num).replace(/\D/g, '') : '';
+        if (!digits) return null;
+        const resolved = `${digits}@c.us`;
+        rememberLidAlias(userId, rawTo, resolved);
+        return resolved;
+    } catch (e) {
+        console.error(`fromMe @lid contact lookup failed for ${userId}`, e);
+        return null;
+    }
+}
+
 // Minimal slice of whatsapp-web.js Client that backfill needs — a seam so the
 // replay loop can be tested without booting a real client.
 export interface ChatLike {
@@ -385,6 +479,10 @@ export async function backfillTargets(
 export function clearInbound(userId: string) {
     inboundQueues.delete(userId);
     outboundTargets.delete(userId);
+    // Same resurrection hazard as the allowlist: the on-disk lid_aliases.json
+    // was just wiped with the session dir, and a re-pair (possibly a DIFFERENT
+    // WhatsApp number) must not inherit the old pairing's @lid mappings.
+    lidAliases.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);
@@ -394,5 +492,6 @@ export function clearInbound(userId: string) {
 export function resetInboundState() {
     inboundQueues.clear();
     outboundTargets.clear();
+    lidAliases.clear();
     selfSendIds.clear();
 }

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

@@ -8,6 +8,7 @@ import { InitGate } from './init_gate';
 import {
     hasPairedSession,
     InitRetryLimiter,
+    isReadyWedged,
     reapLimitMs,
     touchClient,
     shouldWipeSessionOnReap
@@ -43,6 +44,13 @@ const BROWSER_EXECUTABLE_PATH = process.env.PUPPETEER_EXECUTABLE_PATH;
 // 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);
+// Recycle a client that authenticates from the on-disk session but never fires
+// 'ready' (the store never hydrates — RAM pressure, a mid-write SIGKILL, a
+// slow web.whatsapp.com). Without this the client serves qr=null +
+// authenticated=false until the 30-min idle reaper — the "No QR available
+// forever after a deploy" outage. 3 minutes is comfortably above a slow but
+// healthy hydration (~30s observed) and well under the reaper.
+const READY_TIMEOUT_MS = Number(process.env.WHATSAPP_READY_TIMEOUT_MS || 180000);
 // 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.
@@ -63,6 +71,7 @@ interface ClientData {
     // pairing visit whose LocalAuth dir holds no credentials at all.
     everAuthenticated?: boolean;
     initTimer?: ReturnType<typeof setTimeout>;
+    readyTimer?: ReturnType<typeof setTimeout>;
     releaseInitSlot?: () => void;
 }
 
@@ -101,6 +110,27 @@ async function pushWebhook(userId: string, msg: InboundMsg) {
     }
 }
 
+// Session lifecycle push (0.9.1): tell the host the moment a session becomes
+// sendable, so work it parked on "session down" resumes in realtime instead
+// of on its next polling tick. Same URL + token as the message webhook; the
+// payload carries `event` instead of `message`, which pre-0.9.1 hosts reject
+// with a 400 — harmless, and the host's poll-based resume still covers them.
+async function pushSessionEvent(userId: string, event: 'session_ready') {
+    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, event })
+        });
+    } catch (e) {
+        console.error(`Session event push failed for ${userId}`, e);
+    }
+}
+
 // 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.
@@ -140,6 +170,13 @@ const initGate = new InitGate(Number(process.env.WHATSAPP_MAX_CONCURRENT_INITS |
 const BROWSER_LAUNCH_TIMEOUT_MS = Number(process.env.WHATSAPP_BROWSER_TIMEOUT_MS || 60000);
 const PROTOCOL_TIMEOUT_MS = Number(process.env.WHATSAPP_PROTOCOL_TIMEOUT_MS || 120000);
 
+function clearReadyTimer(clientData: ClientData) {
+    if (clientData.readyTimer) {
+        clearTimeout(clientData.readyTimer);
+        clientData.readyTimer = undefined;
+    }
+}
+
 function clearInitTimer(clientData: ClientData) {
     if (clientData.initTimer) {
         clearTimeout(clientData.initTimer);
@@ -290,6 +327,7 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
     client.on('qr', async (qr) => {
         clientData.state = 'QR_REQUIRED';
         clearInitTimer(clientData); // progress made — QR is showable
+        clearReadyTimer(clientData); // WhatsApp wants a re-scan — a QR IS showing, not a wedge
         try {
             clientData.qr = await toDataURL(qr);
             console.log(`QR RECEIVED and converted for User ${userId}`);
@@ -303,8 +341,12 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         clientData.qr = null;
         clientData.ready = true;
         clearInitTimer(clientData);
+        clearReadyTimer(clientData);
         initRetries.reset(userId);
         console.log(`Client is READY for User ${userId}`);
+        // Wake the host NOW — a campaign parked on "session down" should not
+        // wait out a polling interval when the session just came back.
+        pushSessionEvent(userId, 'session_ready').catch(console.error);
         // Replay anything that arrived while we were disconnected.
         backfillInbound(userId, client).catch((e) => console.error(`Backfill failed for ${userId}`, e));
     });
@@ -324,12 +366,28 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         clientData.everAuthenticated = true;
         clearInitTimer(clientData);
         console.log(`AUTHENTICATED for User ${userId}`);
+
+        // Ready watchdog: 'authenticated' just cleared the INITIALIZING
+        // watchdog, so from here nothing guards the authenticated→ready hop.
+        // If the store never hydrates, recycle — the session dir survives
+        // (everAuthenticated), so the next /status poll relaunches Chromium
+        // and reconnects without a new QR. Re-armed on every 'authenticated',
+        // so a client that re-auths after a hiccup gets a fresh window.
+        clearReadyTimer(clientData);
+        clientData.readyTimer = setTimeout(() => {
+            if (isReadyWedged(clientData)) {
+                counters.ready_timeouts_total += 1;
+                console.error(`User ${userId} AUTHENTICATED but not ready > ${READY_TIMEOUT_MS}ms — recycling (session kept)`);
+                destroyClient(userId).catch(console.error);
+            }
+        }, READY_TIMEOUT_MS);
     });
 
     client.on('auth_failure', (msg) => {
         clientData.state = 'DISCONNECTED';
         clientData.ready = false;
         clearInitTimer(clientData);
+        clearReadyTimer(clientData);
         counters.auth_failures_total += 1;
         console.error(`AUTHENTICATION FAILURE for User ${userId}`, msg);
     });
@@ -409,6 +467,7 @@ async function destroyClient(userId: string, clearSession: boolean = false) {
     if (data && !data.isDestroying) {
         data.isDestroying = true;
         clearInitTimer(data);
+        clearReadyTimer(data);
         console.log(`Destroying WhatsApp client for User: ${userId} (clearSession: ${clearSession})`);
         try {
             // Unregister listeners to prevent loops or double-destroys

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

@@ -14,6 +14,7 @@ describe('newCounters', () => {
             init_failures_total: 0,
             ws_endpoint_timeouts_total: 0,
             init_timeouts_total: 0,
+            ready_timeouts_total: 0,
             auth_failures_total: 0,
             disconnects_total: 0,
         });
@@ -57,6 +58,7 @@ describe('renderMetrics', () => {
             init_failures_total: 4,
             ws_endpoint_timeouts_total: 2,
             init_timeouts_total: 1,
+            ready_timeouts_total: 6,
             auth_failures_total: 3,
             disconnects_total: 5,
         };
@@ -81,6 +83,7 @@ describe('renderMetrics', () => {
         expect(out).toContain('whatsapp_init_failures_total 4');
         expect(out).toContain('whatsapp_ws_endpoint_timeouts_total 2');
         expect(out).toContain('whatsapp_init_timeouts_total 1');
+        expect(out).toContain('whatsapp_ready_timeouts_total 6');
         expect(out).toContain('whatsapp_auth_failures_total 3');
         expect(out).toContain('whatsapp_disconnects_total 5');
         expect(out).toContain('whatsapp_service_uptime_seconds 86400');

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

@@ -19,6 +19,7 @@ export interface Counters {
     init_failures_total: number;        // client.initialize() rejected
     ws_endpoint_timeouts_total: number; // Chromium never produced a WS endpoint (crash-loop signature)
     init_timeouts_total: number;        // watchdog recycled a stuck-INITIALIZING client
+    ready_timeouts_total: number;       // watchdog recycled an AUTHENTICATED-but-never-ready wedge
     auth_failures_total: number;        // auth_failure event
     disconnects_total: number;          // disconnected event
 }
@@ -28,6 +29,7 @@ export function newCounters(): Counters {
         init_failures_total: 0,
         ws_endpoint_timeouts_total: 0,
         init_timeouts_total: 0,
+        ready_timeouts_total: 0,
         auth_failures_total: 0,
         disconnects_total: 0,
     };
@@ -103,6 +105,7 @@ export function renderMetrics(
         ...counter('whatsapp_init_failures_total', 'client.initialize() rejections.', counters.init_failures_total),
         ...counter('whatsapp_ws_endpoint_timeouts_total', 'Chromium launches that never produced a WS endpoint (crash-loop signature).', counters.ws_endpoint_timeouts_total),
         ...counter('whatsapp_init_timeouts_total', 'Clients recycled by the INITIALIZING watchdog.', counters.init_timeouts_total),
+        ...counter('whatsapp_ready_timeouts_total', 'Clients recycled by the ready watchdog (AUTHENTICATED but never ready).', counters.ready_timeouts_total),
         ...counter('whatsapp_auth_failures_total', 'auth_failure events.', counters.auth_failures_total),
         ...counter('whatsapp_disconnects_total', 'disconnected events.', counters.disconnects_total),
         ...gauge('whatsapp_service_uptime_seconds', 'Seconds since the service process started.', uptimeSeconds),

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

@@ -5,6 +5,7 @@ import { join } from 'path';
 import {
     hasPairedSession,
     InitRetryLimiter,
+    isReadyWedged,
     reapLimitMs,
     touchClient,
     shouldWipeSessionOnReap
@@ -127,3 +128,24 @@ describe('InitRetryLimiter', () => {
         expect(limiter.shouldRetry('b')).toBe(false);
     });
 });
+
+describe('isReadyWedged', () => {
+    test('AUTHENTICATED but never ready is the wedge', () => {
+        expect(isReadyWedged({ state: 'AUTHENTICATED', ready: false })).toBe(true);
+        expect(isReadyWedged({ state: 'AUTHENTICATED' })).toBe(true); // ready never set
+    });
+
+    test('a ready client is the normal path, not a wedge', () => {
+        expect(isReadyWedged({ state: 'AUTHENTICATED', ready: true })).toBe(false);
+    });
+
+    test('a client already being destroyed must not be recycled again', () => {
+        expect(isReadyWedged({ state: 'AUTHENTICATED', ready: false, isDestroying: true })).toBe(false);
+    });
+
+    test('other states are owned by their own paths', () => {
+        expect(isReadyWedged({ state: 'QR_REQUIRED', ready: false })).toBe(false);   // QR is showing
+        expect(isReadyWedged({ state: 'DISCONNECTED', ready: false })).toBe(false);  // disconnect path
+        expect(isReadyWedged({ state: 'INITIALIZING', ready: false })).toBe(false);  // init watchdog owns it
+    });
+});

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

@@ -89,3 +89,22 @@ export class InitRetryLimiter {
         this.counts.delete(userId);
     }
 }
+
+// The AUTHENTICATED-but-never-ready wedge (incident 2026-06-05, again
+// 2026-07-31): after a service restart a session re-authenticates from disk,
+// but Chromium never finishes loading the WhatsApp Web store, so `ready`
+// never fires. The client then serves qr=null + authenticated=false forever —
+// the broadcast modal shows "No QR available" and sends 503. The INITIALIZING
+// watchdog can't see it (state already moved on), and the idle reaper takes
+// 30+ minutes. This predicate names the wedge for the ready watchdog that
+// index.ts arms when 'authenticated' fires.
+//
+// NOT wedged: already ready (the normal path), already being destroyed
+// (recycling twice double-frees nothing but spams logs), or moved to another
+// state — QR_REQUIRED means WhatsApp wants a re-scan and IS showing a QR, and
+// DISCONNECTED clients are on the disconnect path already.
+export function isReadyWedged(
+    client: { state: string; ready?: boolean; isDestroying?: boolean }
+): boolean {
+    return client.state === 'AUTHENTICATED' && !client.ready && !client.isDestroying;
+}

data/lib/whatsapp_notifier/version.rb

@@ -1,4 +1,4 @@
 module WhatsAppNotifier
-  VERSION = "0.8.1"
+  VERSION = "0.9.1"
 
 end

data/lib/whatsapp_notifier/web_adapter.rb

@@ -67,6 +67,10 @@ module WhatsAppNotifier
         message_id: response["messageId"] || response["message_id"] ||
                     payload[:idempotency_key] || "local-#{Time.now.to_i}",
         session: session,
+        # A code the service supplied wins over anything the provider could
+        # infer from the message text. Absent on every service ≤ 0.8.x, which
+        # is why the provider still classifies as a fallback.
+        error_code: ErrorCode.normalize(response["errorCode"] || response["error_code"]),
         error_message: response["error"]
       }
     end
@@ -109,7 +113,7 @@ module WhatsAppNotifier
       user_id = user_id_from(metadata)
       res = binary_get("/media/#{user_id}/#{path_id(message_id)}")
       return nil if res.code.to_s == "404"
-      raise "service request failed (#{res.code}): #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+      raise ServiceError.new("service request failed (#{res.code}): #{res.body}", status: res.code) unless res.is_a?(Net::HTTPSuccess)
 
       body = res.body.to_s
       {
@@ -283,7 +287,7 @@ module WhatsAppNotifier
       # carries no "success" key, so they degrade rather than raise.
       return parsed if allow_404 && res.code.to_s == "404"
 
-      raise "service request failed (#{res.code}): #{parsed["error"] || res.body}"
+      raise ServiceError.new("service request failed (#{res.code}): #{parsed["error"] || res.body}", status: res.code)
     end
 
     def parse_body(raw)

data/lib/whatsapp_notifier.rb

@@ -1,5 +1,6 @@
 require_relative "whatsapp_notifier/version"
 require_relative "whatsapp_notifier/errors"
+require_relative "whatsapp_notifier/error_code"
 require_relative "whatsapp_notifier/result"
 require_relative "whatsapp_notifier/configuration"
 require_relative "whatsapp_notifier/web_adapter"
@@ -62,6 +63,16 @@ module WhatsAppNotifier
       client.connection_status(provider: provider, metadata: metadata)
     end
 
+    # One call for "can this operator send right now?" — an authenticated
+    # session answers true, everything else (including an unreachable status
+    # endpoint) answers false. `user_id:` is sugar for the metadata key every
+    # multi-user host passes; both forms work.
+    def session_ready?(user_id: nil, provider: nil, metadata: {})
+      meta = metadata.to_h
+      meta = meta.merge(user_id: user_id) unless user_id.nil?
+      client.session_ready?(provider: provider, metadata: meta)
+    end
+
     def fetch_inbound(provider: nil, metadata: {})
       client.fetch_inbound(provider: provider, metadata: metadata)
     end

data/spec/error_code_spec.rb

@@ -0,0 +1,107 @@
+require "spec_helper"
+require "net/http"
+
+RSpec.describe WhatsAppNotifier::ErrorCode do
+  describe ".from_exception" do
+    it "classifies a service error by its HTTP status, not its body text" do
+      # A 401 body that happens to mention a number must still read as auth.
+      error = WhatsAppNotifier::ServiceError.new(
+        "service request failed (401): No saved WhatsApp session for this user — pair via QR first",
+        status: "401"
+      )
+
+      expect(described_class.from_exception(error)).to eq(:auth_required)
+    end
+
+    it "classifies a 403 as auth and a 429 as rate limiting" do
+      forbidden = WhatsAppNotifier::ServiceError.new("nope", status: 403)
+      throttled = WhatsAppNotifier::ServiceError.new("slow down", status: "429")
+
+      expect(described_class.from_exception(forbidden)).to eq(:auth_required)
+      expect(described_class.from_exception(throttled)).to eq(:rate_limited)
+    end
+
+    # The service 422s a malformed REQUEST (a host bug), never a bad number,
+    # so it must NOT be classified as :invalid_phone.
+    it "leaves a 422 unclassified" do
+      error = WhatsAppNotifier::ServiceError.new("service request failed (422): `to` is required", status: 422)
+
+      expect(described_class.from_exception(error)).to eq(:delivery_exception)
+    end
+
+    it "classifies socket failures as service_unreachable" do
+      expect(described_class.from_exception(Errno::ECONNREFUSED.new)).to eq(:service_unreachable)
+      expect(described_class.from_exception(SocketError.new("getaddrinfo"))).to eq(:service_unreachable)
+      expect(described_class.from_exception(Net::OpenTimeout.new)).to eq(:service_unreachable)
+    end
+
+    # A read timeout is NOT the same as a connect timeout: the request went
+    # out, so the send may well have landed.
+    it "classifies a read timeout as :timeout, separate from :service_unreachable" do
+      expect(described_class.from_exception(Net::ReadTimeout.new)).to eq(:timeout)
+    end
+
+    it "falls back to the message when the class and status say nothing" do
+      expect(described_class.from_exception(RuntimeError.new("No LID for 919999000001"))).to eq(:recipient_unresolved)
+    end
+
+    it "falls back to the message for a 500 carrying a library error" do
+      error = WhatsAppNotifier::ServiceError.new("service request failed (500): No LID for 919999000001", status: 500)
+
+      expect(described_class.from_exception(error)).to eq(:recipient_unresolved)
+    end
+
+    it "leaves an opaque exception unclassified" do
+      expect(described_class.from_exception(RuntimeError.new("Evaluation failed: e"))).to eq(:delivery_exception)
+    end
+  end
+
+  describe ".from_message" do
+    {
+      "No LID for 919999000001" => :recipient_unresolved,
+      "Phone number is not registered" => :not_on_whatsapp,
+      "wid error: invalid wid" => :invalid_phone,
+      "User not authenticated" => :auth_required,
+      "Connection refused - connect(2) for 127.0.0.1:3001" => :service_unreachable,
+      "execution expired" => :timeout,
+      "Too Many Requests" => :rate_limited
+    }.each do |text, code|
+      it "reads #{text.inspect} as #{code}" do
+        expect(described_class.from_message(text)).to eq(code)
+      end
+    end
+
+    it "returns the catch-all for text it cannot place" do
+      expect(described_class.from_message("something new")).to eq(:delivery_exception)
+      expect(described_class.from_message(nil)).to eq(:delivery_exception)
+    end
+  end
+
+  describe ".normalize" do
+    it "folds the service's synonyms into one code" do
+      expect(described_class.normalize("unauthenticated")).to eq(:auth_required)
+      expect(described_class.normalize("NUMBER_NOT_REGISTERED")).to eq(:not_on_whatsapp)
+      expect(described_class.normalize(:throttled)).to eq(:rate_limited)
+    end
+
+    it "returns nil for a blank code so callers fall back to their own guess" do
+      expect(described_class.normalize(nil)).to be_nil
+      expect(described_class.normalize("  ")).to be_nil
+    end
+
+    # A newer service may introduce a code before the gem knows it — pass it
+    # through rather than flattening it, but only if it looks like an
+    # identifier.
+    it "passes an unknown identifier-shaped code through" do
+      expect(described_class.normalize("queue_full")).to eq(:queue_full)
+    end
+
+    it "flattens code-shaped garbage to the catch-all" do
+      expect(described_class.normalize("<html>502 Bad Gateway</html>")).to eq(:delivery_exception)
+    end
+  end
+
+  it "lists every code it can return" do
+    expect(described_class::ALL).to include(described_class::UNCLASSIFIED)
+  end
+end

data/spec/providers/web_automation_spec.rb

@@ -69,6 +69,68 @@ RSpec.describe WhatsAppNotifier::Providers::WebAutomation do
     end
   end
 
+  # Error codes are what hosts branch on to decide whether a retry could
+  # double-message someone, so a raised exception must survive as a code and
+  # not only as text.
+  it "classifies the raised exception into an error code" do
+    Dir.mktmpdir do |dir|
+      adapter = double
+      allow(adapter).to receive(:send_message)
+        .and_raise(WhatsAppNotifier::ServiceError.new("service request failed (401): User not authenticated", status: 401))
+      allow(adapter).to receive(:fetch_qr_code).and_return("qr")
+      allow(adapter).to receive(:connection_status).and_return({})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      result = provider.deliver(to: "+1", body: "h")
+
+      expect(result.error_code).to eq(:auth_required)
+      # The message field is untouched — hosts still fingerprinting it work.
+      expect(result.error_message).to eq("service request failed (401): User not authenticated")
+    end
+  end
+
+  it "classifies a failure the adapter reported without raising" do
+    Dir.mktmpdir do |dir|
+      adapter = double
+      allow(adapter).to receive(:send_message)
+        .and_return(success: false, session: {}, error_message: "No LID for 919999000001")
+      allow(adapter).to receive(:fetch_qr_code).and_return("qr")
+      allow(adapter).to receive(:connection_status).and_return({})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.deliver(to: "+1", body: "h").error_code).to eq(:recipient_unresolved)
+    end
+  end
+
+  it "keeps a code the adapter supplied instead of re-guessing from the text" do
+    Dir.mktmpdir do |dir|
+      adapter = double
+      allow(adapter).to receive(:send_message)
+        .and_return(success: false, session: {}, error_code: :not_on_whatsapp, error_message: "No LID for 919999000001")
+      allow(adapter).to receive(:fetch_qr_code).and_return("qr")
+      allow(adapter).to receive(:connection_status).and_return({})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.deliver(to: "+1", body: "h").error_code).to eq(:not_on_whatsapp)
+    end
+  end
+
+  it "leaves a successful send without an error code" do
+    Dir.mktmpdir do |dir|
+      adapter = double
+      allow(adapter).to receive(:send_message).and_return(success: true, message_id: "w1", session: {})
+      allow(adapter).to receive(:fetch_qr_code).and_return("qr")
+      allow(adapter).to receive(:connection_status).and_return({})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.deliver(to: "+1", body: "h").error_code).to be_nil
+    end
+  end
+
   it "raises for missing adapter methods in scan" do
     Dir.mktmpdir do |dir|
       adapter = Object.new