whatsapp_notifier 0.8.2 → 0.9.2

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