whatsapp_notifier 0.8.2 → 0.9.1

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.1
 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