whatsapp_notifier 0.2.0

data/lib/whatsapp_notifier/client.rb

@@ -0,0 +1,43 @@
+module WhatsAppNotifier
+  class Client
+    def initialize(configuration:)
+      @configuration = configuration
+      @providers = {}
+    end
+
+    def deliver(to:, body:, metadata: {}, provider: nil, idempotency_key: nil)
+      payload = {
+        to: to,
+        body: body,
+        metadata: metadata,
+        idempotency_key: idempotency_key
+      }
+      provider_for(provider || @configuration.provider).deliver(payload)
+    end
+
+    def deliver_bulk(messages, provider: nil, sleeper: ->(seconds) { sleep(seconds) }, rng: Random.new)
+      Bulk::Dispatcher.new(client: self, configuration: @configuration, sleeper: sleeper, rng: rng).deliver(messages, provider: provider)
+    end
+
+    def scan_qr(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).scan_qr(metadata: metadata)
+    end
+
+    def connection_status(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).connection_status(metadata: metadata)
+    end
+
+    private
+
+    def provider_for(key)
+      @providers[key] ||= build_provider(key)
+    end
+
+    def build_provider(key)
+      provider_key = key.to_sym
+      raise ConfigurationError, "unknown provider: #{key.inspect}" unless provider_key == :web_automation
+
+      Providers::WebAutomation.new(configuration: @configuration)
+    end
+  end
+end

data/lib/whatsapp_notifier/configuration.rb

@@ -0,0 +1,41 @@
+require "logger"
+
+module WhatsAppNotifier
+  class Configuration
+    attr_accessor :provider, :web_adapter, :web_session_path,
+                  :bulk_base_delay_seconds, :bulk_jitter_seconds, :bulk_max_recipients,
+                  :bulk_max_attempts, :bulk_retryable_error_codes, :logger,
+                  :web_automation_enabled, :warn_on_risky_provider
+
+    def initialize
+      @provider = :web_automation
+      @web_adapter = WebAdapter.new
+      @web_session_path = "tmp/whatsapp_notifier/session.json"
+      @bulk_base_delay_seconds = 1.0
+      @bulk_jitter_seconds = 0.3
+      @bulk_max_recipients = 500
+      @bulk_max_attempts = 3
+      @bulk_retryable_error_codes = %i[rate_limited network_error temporary_failure].freeze
+      @logger = Logger.new($stdout)
+      @web_automation_enabled = true
+      @warn_on_risky_provider = true
+    end
+
+    def validate!
+      raise ConfigurationError, "provider is required" if provider.nil?
+      raise ConfigurationError, "only :web_automation provider is supported" unless provider.to_sym == :web_automation
+      raise ConfigurationError, "bulk_max_recipients must be positive" if bulk_max_recipients.to_i <= 0
+      raise ConfigurationError, "bulk_max_attempts must be positive" if bulk_max_attempts.to_i <= 0
+      raise ConfigurationError, "web_adapter must be configured and respond to send_message, fetch_qr_code, connection_status" unless valid_web_adapter?
+    end
+
+    private
+
+    def valid_web_adapter?
+      return false unless web_adapter
+
+      required_methods = %i[send_message fetch_qr_code connection_status]
+      required_methods.all? { |method_name| web_adapter.respond_to?(method_name) }
+    end
+  end
+end

data/lib/whatsapp_notifier/doctor.rb

@@ -0,0 +1,103 @@
+require "fileutils"
+
+module WhatsAppNotifier
+  module Doctor
+    module_function
+
+    DEFAULT_PORT = 3001
+
+    def run(io: $stdout, env: ENV, app_root: Dir.pwd)
+      checks = [
+        check_bun,
+        check_chromium(env: env),
+        check_session_dir(env: env, app_root: app_root),
+        check_service_url(env: env)
+      ]
+
+      checks.each do |check|
+        icon = check[:ok] ? "PASS" : "FAIL"
+        io.puts("#{icon}: #{check[:name]}")
+        io.puts("  #{check[:message]}")
+      end
+
+      failed = checks.reject { |check| check[:ok] }
+      return true if failed.empty?
+
+      io.puts("")
+      io.puts("Quick fixes:")
+      failed.each { |check| io.puts("- #{check[:fix]}") if check[:fix] }
+      false
+    end
+
+    def session_dir(env: ENV, app_root: Dir.pwd)
+      env["WHATSAPP_SESSION_DIR"] || File.expand_path("tmp/whatsapp_notifier/.wwebjs_auth", app_root)
+    end
+
+    def default_service_url
+      "http://127.0.0.1:#{DEFAULT_PORT}"
+    end
+
+    def check_bun
+      if system("bun --version > /dev/null 2>&1")
+        { ok: true, name: "Bun installed", message: "bun is available in PATH." }
+      else
+        {
+          ok: false,
+          name: "Bun installed",
+          message: "bun is missing.",
+          fix: "Install Bun from https://bun.sh then rerun `bundle exec whatsapp_notifier doctor`."
+        }
+      end
+    end
+
+    def check_chromium(env: ENV)
+      executable = env["PUPPETEER_EXECUTABLE_PATH"]
+      if executable && File.executable?(executable)
+        return { ok: true, name: "Chromium path", message: "Using PUPPETEER_EXECUTABLE_PATH=#{executable}." }
+      end
+
+      common_paths = ["/usr/bin/chromium", "/usr/bin/chromium-browser", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"]
+      found = common_paths.find { |path| File.executable?(path) }
+
+      if found
+        { ok: true, name: "Chromium path", message: "Detected Chromium-compatible executable at #{found}." }
+      else
+        {
+          ok: false,
+          name: "Chromium path",
+          message: "No Chromium executable found.",
+          fix: "Install Chromium/Chrome or set PUPPETEER_EXECUTABLE_PATH=/path/to/chrome."
+        }
+      end
+    end
+
+    def check_session_dir(env: ENV, app_root: Dir.pwd)
+      dir = session_dir(env: env, app_root: app_root)
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, ".write_test"), "ok")
+      File.delete(File.join(dir, ".write_test"))
+      { ok: true, name: "Session directory", message: "Writable directory at #{dir}." }
+    rescue StandardError => e
+      {
+        ok: false,
+        name: "Session directory",
+        message: "Cannot write to #{dir}: #{e.message}",
+        fix: "Ensure the directory is writable or set WHATSAPP_SESSION_DIR to a writable path."
+      }
+    end
+
+    def check_service_url(env: ENV)
+      service_url = env["WHATSAPP_NOTIFIER_SERVICE_URL"] || env["WHATSAPP_SERVICE_URL"] || default_service_url
+      if service_url.match?(%r{\Ahttps?://})
+        { ok: true, name: "Service URL", message: "Using #{service_url}." }
+      else
+        {
+          ok: false,
+          name: "Service URL",
+          message: "Invalid URL: #{service_url.inspect}",
+          fix: "Set WHATSAPP_NOTIFIER_SERVICE_URL to something like #{default_service_url}."
+        }
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/errors.rb

@@ -0,0 +1,5 @@
+module WhatsAppNotifier
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class DeliveryError < Error; end
+end

data/lib/whatsapp_notifier/jobs/send_message_job.rb

@@ -0,0 +1,20 @@
+module WhatsAppNotifier
+  module Jobs
+    class SendMessageJob
+      def self.perform_later(notification_class_name, params)
+        raise LoadError, "ActiveJob is required for deliver_later" unless defined?(::ActiveJob::Base)
+
+        perform_now(notification_class_name, params)
+      end
+
+      def self.perform_now(notification_class_name, params)
+        new.perform(notification_class_name, params)
+      end
+
+      def perform(notification_class_name, params)
+        klass = notification_class_name.split("::").inject(Object) { |ctx, const| ctx.const_get(const) }
+        klass.with(params).deliver_now
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/notification.rb

@@ -0,0 +1,93 @@
+module WhatsAppNotifier
+  class Notification
+    class << self
+      attr_accessor :default_to, :default_provider, :default_template
+
+      def with(params = {})
+        new(params)
+      end
+
+      def to(value = nil)
+        return default_to if value.nil?
+        self.default_to = value
+      end
+
+      def provider(value = nil)
+        return default_provider if value.nil?
+        self.default_provider = value
+      end
+
+      def template(name = nil, body = nil)
+        @templates ||= {}
+        return default_template if name.nil?
+
+        self.default_template = name.to_sym
+        @templates[name.to_sym] = body if body
+      end
+
+      def templates
+        @templates ||= {}
+      end
+
+      def deliver_now(params = {})
+        with(params).deliver_now
+      end
+
+      def deliver_later(params = {})
+        Jobs::SendMessageJob.perform_later(name, params)
+      end
+    end
+
+    attr_reader :params
+
+    def initialize(params = {})
+      @params = params
+    end
+
+    def message
+      return render_template if template_name
+
+      raise NotImplementedError, "#{self.class.name} must implement #message or define template"
+    end
+
+    def to
+      params[:to] || self.class.default_to
+    end
+
+    def provider
+      params[:provider] || self.class.default_provider
+    end
+
+    def metadata
+      params[:metadata] || {}
+    end
+
+    def template_name
+      (params[:template] || self.class.default_template)&.to_sym
+    end
+
+    def template_params
+      params[:params] || {}
+    end
+
+    def deliver_now
+      raise ConfigurationError, "recipient is required" if to.nil? || to.to_s.strip.empty?
+
+      WhatsAppNotifier.deliver(
+        to: to,
+        body: message,
+        provider: provider,
+        metadata: metadata
+      )
+    end
+
+    private
+
+    def render_template
+      body = self.class.templates[template_name]
+      raise ConfigurationError, "template not found: #{template_name}" unless body
+
+      body.gsub(/\{\{(\w+)\}\}/) { |_match| template_params[Regexp.last_match(1).to_sym].to_s }
+    end
+  end
+end

data/lib/whatsapp_notifier/providers/base.rb

@@ -0,0 +1,24 @@
+module WhatsAppNotifier
+  module Providers
+    class Base
+      attr_reader :configuration
+
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def deliver(_payload)
+        raise NotImplementedError, "#{self.class.name} must implement #deliver"
+      end
+
+      def scan_qr(metadata: {})
+        raise NotImplementedError, "#{self.class.name} does not support QR scanning"
+      end
+
+      def connection_status(metadata: {})
+        raise NotImplementedError, "#{self.class.name} does not support status checking"
+      end
+
+    end
+  end
+end

data/lib/whatsapp_notifier/providers/web_automation.rb

@@ -0,0 +1,85 @@
+module WhatsAppNotifier
+  module Providers
+    class WebAutomation < Base
+      def initialize(configuration:)
+        super
+        @store = Session::Store.new(path: configuration.web_session_path)
+      end
+
+      def deliver(payload)
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter must be configured for web_automation provider" unless adapter.respond_to?(:send_message)
+
+        warn_risk_once
+        session = session_for(payload.fetch(:metadata, {}))
+        response = adapter.send_message(payload: payload, session: session)
+        persist_session(response.fetch(:session, {}), payload.fetch(:metadata, {}))
+
+        Result.new(
+          success: response.fetch(:success),
+          provider: :web_automation,
+          message_id: response[:message_id],
+          error_code: response[:error_code],
+          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)
+      end
+
+      def scan_qr(metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter must be configured for web_automation provider" unless adapter.respond_to?(:fetch_qr_code)
+
+        Session::QrService.new(store: @store, adapter: adapter).qr_code(metadata: metadata)
+      end
+
+      def connection_status(metadata: {})
+        raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
+
+        adapter = configuration.web_adapter
+        raise ConfigurationError, "web_adapter must be configured for web_automation provider" unless adapter.respond_to?(:connection_status)
+
+        adapter.connection_status(metadata: metadata)
+      end
+
+
+      private
+
+      def session_for(metadata)
+        user_id = metadata[:user_id]
+        return @store.load unless user_id
+
+        all_sessions = @store.load
+        all_sessions.fetch(:users, {}).fetch(user_key(user_id), {})
+      end
+
+      def persist_session(next_session, metadata)
+        user_id = metadata[:user_id]
+        return @store.save(next_session) unless user_id
+
+        all_sessions = @store.load
+        users = all_sessions.fetch(:users, {})
+        users[user_key(user_id)] = next_session
+        @store.save(all_sessions.merge(users: users))
+      end
+
+      def user_key(user_id)
+        user_id.to_s.to_sym
+      end
+
+      def warn_risk_once
+        return unless configuration.warn_on_risky_provider
+        return if defined?(@risk_warned) && @risk_warned
+
+        configuration.logger.warn("web_automation provider uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.")
+        @risk_warned = true
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/railtie.rb

@@ -0,0 +1,14 @@
+module WhatsAppNotifier
+  class Railtie < ::Rails::Railtie
+    config.whatsapp_notifier = {}
+
+    initializer "whatsapp_notifier.configure" do |app|
+      WhatsAppNotifier.configure do |config|
+        app.config.whatsapp_notifier.each do |key, value|
+          setter = "#{key}="
+          config.public_send(setter, value) if config.respond_to?(setter)
+        end
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/result.rb

@@ -0,0 +1,23 @@
+module WhatsAppNotifier
+  class Result
+    attr_reader :success, :provider, :message_id, :error_code, :error_message, :wait_seconds, :metadata
+
+    def initialize(success:, provider:, message_id: nil, error_code: nil, error_message: nil, wait_seconds: nil, metadata: {})
+      @success = success
+      @provider = provider
+      @message_id = message_id
+      @error_code = error_code
+      @error_message = error_message
+      @wait_seconds = wait_seconds
+      @metadata = metadata
+    end
+
+    def success?
+      success
+    end
+
+    def failure?
+      !success?
+    end
+  end
+end