whatsapp_notifier 0.8.2 → 0.9.2

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/package.json

@@ -7,7 +7,7 @@
   },
   "dependencies": {
     "hono": "^4.12.9",
-    "whatsapp-web.js": "1.34.6",
+    "whatsapp-web.js": "1.34.7",
     "qrcode": "^1.5.4"
   },
   "devDependencies": {

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

data/spec/session_ready_spec.rb

@@ -0,0 +1,114 @@
+require "spec_helper"
+
+# WhatsAppNotifier.session_ready? — the one call hosts make before sending, so
+# they stop each writing their own "authenticated == true, rescue to false".
+RSpec.describe "session readiness" do
+  def configure(adapter)
+    WhatsAppNotifier.configure do |config|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_adapter = adapter
+      config.logger = Logger.new(nil)
+      config.warn_on_risky_provider = false
+    end
+  end
+
+  def adapter_returning(status)
+    adapter = double(send_message: { success: true, session: {} }, fetch_qr_code: "qr")
+    allow(adapter).to receive(:connection_status).and_return(status)
+    adapter
+  end
+
+  def adapter_raising(error)
+    adapter = double(send_message: { success: true, session: {} }, fetch_qr_code: "qr")
+    allow(adapter).to receive(:connection_status).and_raise(error)
+    adapter
+  end
+
+  it "is true only when the service reports an authenticated session" do
+    configure(adapter_returning(state: "AUTHENTICATED", authenticated: true))
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(true)
+  end
+
+  it "is false when the session is not authenticated" do
+    configure(adapter_returning(state: "QR_REQUIRED", authenticated: false))
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(false)
+  end
+
+  # Truthy-but-not-true (a "yes" string from a sloppy adapter) must not read
+  # as ready — the check is deliberately exact.
+  it "is false for a truthy non-true authenticated value" do
+    configure(adapter_returning(authenticated: "yes"))
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(false)
+  end
+
+  it "is false when the adapter answers with something that is not a hash" do
+    configure(adapter_returning(nil))
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(false)
+  end
+
+  # An unreachable status endpoint means the service is down, so sends can't
+  # succeed either — not ready, and logged rather than raised.
+  it "is false and logs when the status endpoint is unreachable" do
+    logger = double(warn: true)
+    configure(adapter_raising(Errno::ECONNREFUSED))
+    WhatsAppNotifier.configuration.logger = logger
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(false)
+    expect(logger).to have_received(:warn).with(/session_ready\? failed/)
+  end
+
+  it "survives a nil logger" do
+    configure(adapter_raising(Errno::ECONNREFUSED))
+    WhatsAppNotifier.configuration.logger = nil
+
+    expect(WhatsAppNotifier.session_ready?(user_id: 7)).to be(false)
+  end
+
+  # A ConfigurationError is a boot-time mistake in the HOST. Swallowing it
+  # would quietly park every campaign behind a "session down" backoff.
+  it "does not swallow a configuration error" do
+    configure(adapter_returning(authenticated: true))
+    WhatsAppNotifier.configuration.web_automation_enabled = false
+
+    expect { WhatsAppNotifier.session_ready?(user_id: 7) }
+      .to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+  end
+
+  it "passes the user id through as status metadata" do
+    adapter = adapter_returning(authenticated: true)
+    configure(adapter)
+
+    WhatsAppNotifier.session_ready?(user_id: 42)
+
+    expect(adapter).to have_received(:connection_status).with(metadata: { user_id: 42 })
+  end
+
+  it "accepts a metadata hash instead of user_id" do
+    adapter = adapter_returning(authenticated: true)
+    configure(adapter)
+
+    WhatsAppNotifier.session_ready?(metadata: { user_id: 9, tenant: "x" })
+
+    expect(adapter).to have_received(:connection_status).with(metadata: { user_id: 9, tenant: "x" })
+  end
+
+  it "asks for the default session when neither is given" do
+    adapter = adapter_returning(authenticated: true)
+    configure(adapter)
+
+    WhatsAppNotifier.session_ready?
+
+    expect(adapter).to have_received(:connection_status).with(metadata: {})
+  end
+
+  it "is not implemented by a bare provider" do
+    provider = WhatsAppNotifier::Providers::Base.new(configuration: WhatsAppNotifier.configuration)
+
+    expect { provider.session_ready? }.to raise_error(NotImplementedError)
+  end
+end

data/spec/web_adapter_spec.rb

@@ -104,6 +104,41 @@ RSpec.describe WhatsAppNotifier::WebAdapter do
     end.to raise_error(/service request failed/)
   end
 
+  # The status is what ErrorCode classifies on — re-deriving it from the
+  # message text would be a regex round-trip through our own string.
+  it "carries the HTTP status on the raised service error" do
+    allow(Net::HTTP).to receive(:start)
+      .and_return(http_failure(code: "401", body: JSON.generate({ error: "User not authenticated" })))
+
+    expect { adapter.send_message(payload: { to: "+1", body: "hi" }, session: {}) }
+      .to raise_error(WhatsAppNotifier::ServiceError) { |error|
+        expect(error.status.to_i).to eq(401)
+        # Pre-0.9.0 this was a bare RuntimeError; hosts rescue that class by
+        # name around media fetches and status polls.
+        expect(error).to be_a(RuntimeError)
+        # Wording unchanged from 0.8.x — hosts that fingerprinted it still match.
+        expect(error.message).to eq("service request failed (401): User not authenticated")
+      }
+  end
+
+  # Forward compatibility: a future service can name the failure itself and
+  # the gem stops guessing from text.
+  it "normalizes an error code the service supplied" do
+    response = http_success(body: { "success" => false, "errorCode" => "NUMBER_NOT_REGISTERED", "error" => "boom" })
+    allow(Net::HTTP).to receive(:start).and_return(response)
+
+    result = adapter.send_message(payload: { to: "+1", body: "hi" }, session: {})
+
+    expect(result).to include(success: false, error_code: :not_on_whatsapp, error_message: "boom")
+  end
+
+  it "leaves error_code nil when the service does not send one" do
+    response = http_success(body: { "success" => false, "error" => "boom" })
+    allow(Net::HTTP).to receive(:start).and_return(response)
+
+    expect(adapter.send_message(payload: { to: "+1", body: "hi" }, session: {})[:error_code]).to be_nil
+  end
+
   it "handles empty and invalid response bodies gracefully" do
     empty_body = instance_double(Net::HTTPOK, body: "", code: "200", is_a?: true)
     invalid_body = instance_double(Net::HTTPInternalServerError, body: "raw-error", code: "500", is_a?: false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whatsapp_notifier
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.2
 platform: ruby
 authors:
 - Kshitiz Sinha
@@ -56,6 +56,7 @@ files:
 - app/controllers/whatsapp_notifier/sessions_controller.rb
 - bin/whatsapp_notifier
 - config/routes.rb
+- docs/CONFIGURATION.md
 - docs/bulk_messaging_policy.md
 - docs/graphify.md
 - docs/rails_setup.md
@@ -72,6 +73,7 @@ files:
 - lib/whatsapp_notifier/configuration.rb
 - lib/whatsapp_notifier/doctor.rb
 - lib/whatsapp_notifier/engine.rb
+- lib/whatsapp_notifier/error_code.rb
 - lib/whatsapp_notifier/errors.rb
 - lib/whatsapp_notifier/jobs/send_message_job.rb
 - lib/whatsapp_notifier/notification.rb
@@ -107,6 +109,7 @@ files:
 - spec/client_spec.rb
 - spec/configuration_spec.rb
 - spec/doctor_spec.rb
+- spec/error_code_spec.rb
 - spec/generators/install_service_generator_spec.rb
 - spec/jobs/send_message_job_spec.rb
 - spec/notification_spec.rb
@@ -116,6 +119,7 @@ files:
 - spec/result_spec.rb
 - spec/session/qr_service_spec.rb
 - spec/session/store_spec.rb
+- spec/session_ready_spec.rb
 - spec/spec_helper.rb
 - spec/web_adapter_spec.rb
 - spec/whatsapp_notifier_spec.rb