whatsapp_notifier 0.8.2 → 0.9.1

data/docs/CONFIGURATION.md

@@ -0,0 +1,89 @@
+# Configuration reference
+
+Every configuration option and every environment variable, with its type and
+default read from the source. The gem is configured in Ruby; the bundled service
+is configured through environment variables.
+
+## Ruby configuration
+
+Set these in `config/initializers/whatsapp_notifier.rb`:
+
+```ruby
+WhatsAppNotifier.configure do |config|
+  config.bulk_max_recipients = 300
+  # ...
+end
+```
+
+`WhatsAppNotifier.configure` runs `validate!` after the block, so an invalid
+value raises `WhatsAppNotifier::ConfigurationError` at boot.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `provider` | Symbol | `:web_automation` | Messaging backend. Only `:web_automation` is supported; any other value fails `validate!`. |
+| `web_adapter` | object | `WhatsAppNotifier::WebAdapter.new` | HTTP client that talks to the service. Must respond to `send_message`, `fetch_qr_code`, and `connection_status`. |
+| `web_session_path` | String | `"tmp/whatsapp_notifier/session.json"` | File where the gem stores per-user session pointers. |
+| `bulk_base_delay_seconds` | Float | `1.0` | Base pause between consecutive bulk sends. |
+| `bulk_jitter_seconds` | Float | `0.3` | Upper bound of random jitter added to each bulk pause. |
+| `bulk_max_recipients` | Integer | `500` | Largest batch `deliver_bulk` accepts. Must be positive. |
+| `bulk_max_attempts` | Integer | `3` | Attempts per message during bulk retries. Must be positive. |
+| `bulk_retryable_error_codes` | Array\<Symbol\> | `%i[rate_limited network_error temporary_failure]` | Error codes that make a failed bulk send eligible for retry. |
+| `logger` | Logger | `Logger.new($stdout)` | Logger used for warnings and diagnostics. |
+| `web_automation_enabled` | Boolean | `true` | When false, the provider raises instead of sending. A kill switch. |
+| `warn_on_risky_provider` | Boolean | `true` | Logs a one-time warning that web automation is unofficial. |
+| `authenticate_with` | callable or nil | `nil` | Runs as a `before_action` inside the engine's controllers (for example `-> { authenticate_user! }`). |
+| `current_user_id_resolver` | callable | resolves `current_user.id` | How the engine identifies the current user when talking to the service. |
+| `parent_controller` | String | `"::ApplicationController"` | Class the engine's controllers inherit from, so they pick up your layout and filters. |
+| `on_inbound_message_handler` | callable or nil | `nil` | Optional host hook invoked with each inbound message hash, for push-based integrations that would rather not poll. |
+
+## Ruby-side environment variables
+
+Read by the gem (the adapter, doctor, and CLI):
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `WHATSAPP_NOTIFIER_SERVICE_URL` | `http://127.0.0.1:3001` | Base URL of the service. `https://` URLs are honored natively. |
+| `WHATSAPP_SERVICE_URL` | (unset) | Legacy alias used only when `WHATSAPP_NOTIFIER_SERVICE_URL` is unset. |
+| `WHATSAPP_WEBHOOK_TOKEN` | (unset) | When set, the adapter sends it as the `X-WA-Token` header on media, chats, and history requests, matching the service's gate. |
+| `PUPPETEER_EXECUTABLE_PATH` | (unset) | Path to the Chromium/Chrome binary. Checked by `doctor` and the `service` command. |
+| `WHATSAPP_SESSION_DIR` | `tmp/whatsapp_notifier/.wwebjs_auth` (via `doctor`/CLI) | Session directory the `doctor` check and the `service` launcher use. See the note below. |
+
+## Service environment variables
+
+Read by the bundled Bun service under
+`lib/whatsapp_notifier/services/web_automation`:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PORT` | `3001` | Port the service listens on. The `service` command's `--port` flag sets this. |
+| `WHATSAPP_SESSION_DIR` | `/whatsapp_data` | Base directory for per-user WhatsApp sessions. See the note below. |
+| `PUPPETEER_EXECUTABLE_PATH` | (Puppeteer default) | Chromium/Chrome binary to launch. |
+| `WHATSAPP_INIT_TIMEOUT_MS` | `90000` | Recycle a client that boots Chromium but never reaches QR or READY. |
+| `WWEBJS_WEB_VERSION` | (library default) | Pin the WhatsApp Web build (for example `2.3000.1023204887`) so a live change on web.whatsapp.com cannot break the client. |
+| `WWEBJS_WEB_VERSION_CACHE_URL` | wa-version template URL | Remote cache location for the pinned web version. |
+| `WHATSAPP_WEBHOOK_URL` | (unset) | If set, the service POSTs each inbound message here instead of relying only on polling. |
+| `WHATSAPP_WEBHOOK_TOKEN` | (unset) | Shared secret sent as `X-WA-Token` on webhook pushes. When set, it also gates `/media`, `/chats`, and `/history`. Set it in production. |
+| `WHATSAPP_MAX_CONCURRENT_INITS` | `3` | Cap on concurrent Chromium launches, so a herd of cold starts cannot exhaust memory. |
+| `WHATSAPP_UNREADY_REAP_MS` | `1800000` (30 min) | Destroy non-ready clients idle at least this long (abandoned pairing screens). Ready clients keep a 72h idle limit. |
+| `WHATSAPP_BROWSER_TIMEOUT_MS` | `60000` | Puppeteer browser launch timeout. |
+| `WHATSAPP_PROTOCOL_TIMEOUT_MS` | `120000` | Puppeteer protocol timeout. |
+| `WHATSAPP_MEDIA_TTL_MS` | `172800000` (48h) | Lifetime of downloaded inbound media before the sweep evicts it. |
+| `WHATSAPP_MEDIA_MAX_BYTES` | `26214400` (25MB) | Per-document download cap. Inline images and voice notes cap at WhatsApp's 16MB ceiling. |
+| `WHATSAPP_MEDIA_MAX_USER_BYTES` | `1073741824` (1GB) | Per-user rolling media cap with LRU eviction. The cap that shapes disk use. |
+| `WHATSAPP_MEDIA_MAX_DISK_BYTES` | `5368709120` (5GB) | Absolute global backstop for total media on disk. |
+
+Malformed numeric values (for example `"50GB"`) fall back to the default rather
+than parsing to `NaN` and disabling a limit.
+
+### Note on the session directory
+
+`WHATSAPP_SESSION_DIR` has two different defaults depending on how the service
+starts:
+
+- Run directly (`bun index.ts`), it defaults to `/whatsapp_data`.
+- Run through `bundle exec whatsapp_notifier service`, the CLI sets it, if unset,
+  to `tmp/whatsapp_notifier/.wwebjs_auth` relative to the current working
+  directory.
+
+In production, set `WHATSAPP_SESSION_DIR` explicitly to a durable mount so logins
+survive restarts and redeploys.

data/lib/whatsapp_notifier/client.rb

@@ -27,6 +27,10 @@ module WhatsAppNotifier
       provider_for(provider || @configuration.provider).connection_status(metadata: metadata)
     end
 
+    def session_ready?(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).session_ready?(metadata: metadata)
+    end
+
     def fetch_inbound(metadata: {}, provider: nil)
       provider_for(provider || @configuration.provider).fetch_inbound(metadata: metadata)
     end

data/lib/whatsapp_notifier/error_code.rb

@@ -0,0 +1,137 @@
+module WhatsAppNotifier
+  # Stable, machine-readable classification of a failed send.
+  #
+  # Before 0.9.0 every send failure surfaced as error_code :delivery_exception,
+  # so hosts had to fingerprint Result#error_message text to decide whether a
+  # retry was safe. These codes replace that. They are part of the public API
+  # and will not be renamed:
+  #
+  #   :auth_required        session logged out / service refused upfront —
+  #                         nothing was sent
+  #   :not_on_whatsapp      the number has no WhatsApp account
+  #   :invalid_phone        the number is malformed
+  #   :recipient_unresolved the service could not resolve the recipient id
+  #                         (wedged session) — nothing was sent
+  #   :service_unreachable  the TCP connection never opened — nothing was sent
+  #   :timeout              the request went out but the answer never came, so
+  #                         the outcome is UNKNOWN — a retry may double-send
+  #   :rate_limited         the service throttled the send
+  #   :delivery_exception   unclassified; the pre-0.9.0 catch-all, kept as the
+  #                         fallback so hosts keying on it keep working
+  #
+  # The first four plus :service_unreachable are "definitely not sent"; only
+  # :timeout and :delivery_exception leave the outcome ambiguous.
+  module ErrorCode
+    UNCLASSIFIED = :delivery_exception
+
+    ALL = %i[
+      auth_required
+      not_on_whatsapp
+      invalid_phone
+      recipient_unresolved
+      service_unreachable
+      timeout
+      rate_limited
+      delivery_exception
+    ].freeze
+
+    # HTTP status → code, for a non-2xx answer from the service. Checked
+    # first: a status is exact where the body text is a guess. 422 is
+    # deliberately absent — the service 422s a malformed REQUEST (a host bug),
+    # not a bad number, so it falls through to the unclassified catch-all.
+    STATUS_CODES = {
+      401 => :auth_required,
+      403 => :auth_required,
+      429 => :rate_limited
+    }.freeze
+
+    # Exception class name → code. Matched on the name rather than the
+    # constant so this file never has to require net/http or resolve Errno.
+    EXCEPTION_CODES = {
+      "Errno::ECONNREFUSED" => :service_unreachable,
+      "Errno::ECONNRESET" => :service_unreachable,
+      "Errno::EHOSTUNREACH" => :service_unreachable,
+      "Errno::ENETUNREACH" => :service_unreachable,
+      "SocketError" => :service_unreachable,
+      "Net::OpenTimeout" => :service_unreachable,
+      "Net::ReadTimeout" => :timeout,
+      "Net::WriteTimeout" => :timeout,
+      "Timeout::Error" => :timeout
+    }.freeze
+
+    # Codes a service (or a third-party adapter) may hand us directly, folded
+    # into the vocabulary above. Several spellings map to one code because the
+    # Bun service has renamed its own codes across versions.
+    SERVICE_CODES = {
+      "auth_required" => :auth_required,
+      "unauthenticated" => :auth_required,
+      "unauthorized" => :auth_required,
+      "session_expired" => :auth_required,
+      "not_on_whatsapp" => :not_on_whatsapp,
+      "number_not_on_whatsapp" => :not_on_whatsapp,
+      "number_not_registered" => :not_on_whatsapp,
+      "invalid_phone" => :invalid_phone,
+      "invalid_number" => :invalid_phone,
+      "recipient_unresolved" => :recipient_unresolved,
+      "service_unreachable" => :service_unreachable,
+      "timeout" => :timeout,
+      "rate_limited" => :rate_limited,
+      "throttled" => :rate_limited
+    }.freeze
+
+    # Free-text fingerprints, the last resort: whatsapp-web.js failures reach
+    # us as an opaque 500 whose body is the library's own message, so text is
+    # all there is. Order matters — the first match wins.
+    MESSAGE_CODES = [
+      [/\bno lid\b/i, :recipient_unresolved],
+      [/not registered|not on whatsapp|not a valid whatsapp/i, :not_on_whatsapp],
+      [/invalid wid|wid error|invalid (phone|number)/i, :invalid_phone],
+      [/not authenticated|pair via qr|logged out|session expired|unauthorized/i, :auth_required],
+      [/connection refused|failed to open tcp|network is unreachable|no route to host/i, :service_unreachable],
+      [/execution expired|timed out|timeout/i, :timeout],
+      [/rate limit|too many requests/i, :rate_limited]
+    ].freeze
+
+    # Bound on what a service-supplied code may look like before we pass it
+    # through unrecognized: an identifier, not arbitrary text.
+    CODE_SHAPE = /\A[a-z0-9_]{1,64}\z/
+
+    class << self
+      # Classify the exception a transport raised. ServiceError carries the
+      # HTTP status, which beats guessing from the message.
+      def from_exception(exception)
+        status_code = status_code_for(exception)
+        return status_code if status_code
+
+        EXCEPTION_CODES[exception.class.name] || from_message(exception.message)
+      end
+
+      # Classify a failure the transport reported without raising (a 200 body
+      # with success: false).
+      def from_message(text)
+        haystack = text.to_s
+        MESSAGE_CODES.each { |pattern, code| return code if pattern.match?(haystack) }
+        UNCLASSIFIED
+      end
+
+      # Fold a code the service supplied into the vocabulary. Returns nil for
+      # a blank code so callers can fall back to their own classification;
+      # an unrecognized but identifier-shaped code passes through so a newer
+      # service can introduce one without a gem release.
+      def normalize(value)
+        text = value.to_s.strip.downcase
+        return nil if text.empty?
+
+        SERVICE_CODES[text] || (CODE_SHAPE.match?(text) ? text.to_sym : UNCLASSIFIED)
+      end
+
+      private
+
+      def status_code_for(exception)
+        return nil unless exception.respond_to?(:status)
+
+        STATUS_CODES[exception.status.to_i]
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/errors.rb

@@ -2,4 +2,25 @@ module WhatsAppNotifier
   class Error < StandardError; end
   class ConfigurationError < Error; end
   class DeliveryError < Error; end
+
+  # Raised when the service answers a non-2xx. Carries the HTTP status so
+  # callers classify on the status instead of re-parsing the message text.
+  #
+  # Subclasses RuntimeError, NOT WhatsAppNotifier::Error: before 0.9.0 this
+  # was a bare `raise "service request failed (...)"`, so hosts wrote
+  # `rescue RuntimeError` around media fetches and status polls. Hanging it
+  # off Error instead would silently stop those rescues from firing and turn
+  # a handled 5xx into an unhandled one.
+  #
+  # The message keeps its pre-0.9.0 wording ("service request failed (401):
+  # ...") for the same reason — hosts that fingerprinted that string keep
+  # matching while they migrate to Result#error_code.
+  class ServiceError < RuntimeError
+    attr_reader :status
+
+    def initialize(message, status: nil)
+      super(message)
+      @status = status
+    end
+  end
 end

data/lib/whatsapp_notifier/providers/base.rb

@@ -19,6 +19,24 @@ module WhatsAppNotifier
         raise NotImplementedError, "#{self.class.name} does not support status checking"
       end
 
+      # True when the paired session can actually send right now. Wraps
+      # #connection_status so hosts stop reimplementing the same
+      # "authenticated == true, rescue transport errors to false" check — a
+      # status endpoint the host cannot reach means sends can't succeed
+      # either, so an unreachable service reads as not-ready.
+      #
+      # ConfigurationError is deliberately NOT swallowed: that is a boot-time
+      # mistake in the host, and answering `false` would quietly park every
+      # send behind a "session down" backoff instead of surfacing it.
+      def session_ready?(metadata: {})
+        status = connection_status(metadata: metadata)
+        status.is_a?(Hash) && status[:authenticated] == true
+      rescue ConfigurationError
+        raise
+      rescue StandardError => e
+        configuration.logger&.warn("[WhatsAppNotifier] session_ready? failed: #{e.message}")
+        false
+      end
     end
   end
 end

data/lib/whatsapp_notifier/providers/web_automation.rb

@@ -17,19 +17,22 @@ module WhatsAppNotifier
         response = adapter.send_message(payload: payload, session: session)
         persist_session(response.fetch(:session, {}), payload.fetch(:metadata, {}))
 
+        success = response.fetch(:success)
         Result.new(
-          success: response.fetch(:success),
+          success: success,
           provider: :web_automation,
           message_id: response[:message_id],
-          error_code: response[:error_code],
+          error_code: error_code_for(success, response),
           error_message: response[:error_message],
           wait_seconds: response[:wait_seconds],
           metadata: response.fetch(:metadata, {})
         )
       rescue StandardError => e
-        Result.new(success: false, provider: :web_automation, error_code: :delivery_exception, error_message: e.message)
+        Result.new(success: false, provider: :web_automation,
+                   error_code: ErrorCode.from_exception(e), error_message: e.message)
       end
 
+
       def scan_qr(metadata: {})
         raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
 
@@ -127,6 +130,14 @@ module WhatsAppNotifier
 
       private
 
+      # A code the adapter supplied wins; otherwise classify from the error
+      # text, which is all a ≤ 0.8.x service gives us. Successes carry no code.
+      def error_code_for(success, response)
+        return nil if success
+
+        response[:error_code] || ErrorCode.from_message(response[:error_message])
+      end
+
       def session_for(metadata)
         user_id = metadata[:user_id]
         return @store.load unless user_id

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.2"
+  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