waha-ruby 0.1.0

data/lib/waha/resources/messages.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Waha
+  module Resources
+    class Messages < Resource
+      DATA_MEDIA_CHARS = "a-zA-Z0-9!/:[:space:]\u0023$&'()*+,;=?~_-"
+      DATA_URL_PATTERN = Regexp.new("\\Adata:[#{DATA_MEDIA_CHARS}]*;base64,", Regexp::IGNORECASE)
+
+      def send_text(chat_id:, text:, id: nil, reply_to: nil, session: nil)
+        body = { session: session_name(session, "send_text"), chatId: chat_id, text: }
+        body[:id] = id unless id.nil?
+        body[:reply_to] = reply_to unless reply_to.nil?
+        transport.request(
+          method: :post,
+          path: "/api/sendText",
+          operation: "send_text",
+          expected_status: 201,
+          body:
+        )
+      end
+
+      def edit(chat_id:, message_id:, text:, session: nil)
+        name = session_name(session, "edit_message")
+        transport.request(
+          method: :put,
+          path: message_path(name, chat_id, message_id),
+          operation: "edit_message",
+          expected_status: 200,
+          body: { text: }
+        )
+      end
+
+      def list(chat_id:, limit: 100, offset: nil, session: nil, **query)
+        name = session_name(session, "list_messages")
+        query = Support.query_hash(compact_hash(query.merge(limit:, offset:)))
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/chats/#{segment(chat_id)}/messages",
+          operation: "list_messages",
+          expected_status: 200,
+          query:
+        )
+      end
+
+      def find(chat_id:, message_id:, download_media: nil, session: nil)
+        name = session_name(session, "find_message")
+        transport.request(
+          method: :get,
+          path: message_path(name, chat_id, message_id),
+          operation: "find_message",
+          expected_status: 200,
+          query: Support.query_hash(compact_hash(download_media:))
+        )
+      end
+
+      def send_seen(chat_id:, message_ids: nil, session: nil)
+        body = { session: session_name(session, "send_seen"), chatId: chat_id }
+        body[:messageIds] = Array(message_ids) unless message_ids.nil?
+        transport.request(
+          method: :post,
+          path: "/api/sendSeen",
+          operation: "send_seen",
+          expected_status: 201,
+          body:
+        )
+      end
+
+      def start_typing(chat_id:, session: nil)
+        typing("start_typing", "startTyping", chat_id:, session:)
+      end
+
+      def stop_typing(chat_id:, session: nil)
+        typing("stop_typing", "stopTyping", chat_id:, session:)
+      end
+
+      def new_message_id(session: nil)
+        name = session_name(session, "new_message_id")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/new-message-id",
+          operation: "new_message_id",
+          expected_status: 200
+        )
+      end
+
+      def send_image(chat_id:, file:, mimetype:, filename: nil, caption: nil, reply_to: nil, session: nil)
+        body = file_body("send_image", { chat_id:, file:, mimetype:, filename:, caption:, reply_to:, session: })
+        transport.request(
+          method: :post,
+          path: "/api/sendImage",
+          operation: "send_image",
+          expected_status: 201,
+          body:
+        )
+      end
+
+      def send_file(chat_id:, file:, mimetype:, filename: nil, caption: nil, reply_to: nil, session: nil)
+        body = file_body("send_file", { chat_id:, file:, mimetype:, filename:, caption:, reply_to:, session: })
+        transport.request(
+          method: :post,
+          path: "/api/sendFile",
+          operation: "send_file",
+          expected_status: 201,
+          body:
+        )
+      end
+
+      def send_voice(chat_id:, file:, mimetype:, filename: nil, reply_to: nil, convert: nil, session: nil)
+        body = file_body("send_voice", { chat_id:, file:, mimetype:, filename:, reply_to:, session: })
+        body[:convert] = convert unless convert.nil?
+        transport.request(
+          method: :post,
+          path: "/api/sendVoice",
+          operation: "send_voice",
+          expected_status: 201,
+          body:
+        )
+      end
+
+      private
+
+      def file_body(operation, attributes)
+        file_payload = file_payload(
+          operation,
+          file: attributes[:file],
+          mimetype: attributes[:mimetype],
+          filename: attributes[:filename]
+        )
+        Support.compact_hash(
+          session: session_name(attributes[:session], operation),
+          chatId: attributes[:chat_id],
+          file: file_payload,
+          caption: attributes[:caption],
+          reply_to: attributes[:reply_to]
+        )
+      end
+
+      def file_payload(operation, file:, mimetype:, filename:)
+        raise ValidationError.new(operation:, details: "file must be a non-empty string") if file.to_s.empty?
+        raise ValidationError.new(operation:, details: "mimetype is required") if mimetype.to_s.empty?
+
+        payload = { mimetype: }
+        payload[:filename] = filename unless filename.nil?
+
+        if http_url?(file)
+          payload.merge(url: file)
+        elsif data_url?(file)
+          payload.merge(data: file.split(",", 2).last)
+        else
+          raise ValidationError.new(operation:, details: "file must be an http(s) URL or data URL")
+        end
+      end
+
+      def http_url?(value)
+        uri = URI.parse(value.to_s)
+        uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def data_url?(value)
+        DATA_URL_PATTERN.match?(value.to_s)
+      end
+
+      def typing(operation, endpoint, chat_id:, session:)
+        transport.request(
+          method: :post,
+          path: "/api/#{endpoint}",
+          operation:,
+          expected_status: 201,
+          body: { session: session_name(session, operation), chatId: chat_id }
+        )
+      end
+
+      def message_path(session_name, chat_id, message_id)
+        "/api/#{segment(session_name)}/chats/#{segment(chat_id)}/messages/#{segment(message_id)}"
+      end
+
+      def compact_hash(hash)
+        Support.compact_hash(hash)
+      end
+    end
+  end
+end

data/lib/waha/resources/presence.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Presence < Resource
+      def subscribe(chat_id:, session: nil)
+        name = session_name(session, "subscribe_presence")
+        transport.request(
+          method: :post,
+          path: "/api/#{segment(name)}/presence/#{segment(chat_id)}/subscribe",
+          operation: "subscribe_presence",
+          expected_status: [200, 201]
+        )
+      end
+
+      def list(session: nil)
+        name = session_name(session, "list_presence")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/presence",
+          operation: "list_presence",
+          expected_status: 200
+        )
+      end
+
+      def get(chat_id:, session: nil)
+        name = session_name(session, "get_presence")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/presence/#{segment(chat_id)}",
+          operation: "get_presence",
+          expected_status: 200
+        )
+      end
+    end
+  end
+end

data/lib/waha/resources/sessions.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Sessions < Resource
+      def list(all: nil)
+        transport.request(
+          method: :get,
+          path: "/api/sessions/",
+          operation: "list_sessions",
+          expected_status: 200,
+          query: Support.compact_hash(all: all)
+        )
+      end
+
+      def get(session: nil)
+        name = session_name(session, "get_session")
+        transport.request(
+          method: :get,
+          path: "/api/sessions/#{segment(name)}",
+          operation: "get_session",
+          expected_status: 200
+        )
+      end
+
+      def create(name:, start: nil, config: nil)
+        transport.request(
+          method: :post,
+          path: "/api/sessions",
+          operation: "create_session",
+          expected_status: [200, 201],
+          body: Support.compact_hash(name:, start:, config:)
+        )
+      end
+
+      def start(session: nil)
+        action("start_session", "start", session:)
+      end
+
+      def stop(session: nil)
+        action("stop_session", "stop", session:)
+      end
+
+      def restart(session: nil)
+        action("restart_session", "restart", session:)
+      end
+
+      def logout(session: nil)
+        action("logout_session", "logout", session:, body: {})
+      end
+
+      def destroy(session: nil)
+        name = session_name(session, "delete_session")
+        transport.request(
+          method: :delete,
+          path: "/api/sessions/#{segment(name)}",
+          operation: "delete_session",
+          expected_status: [200, 204]
+        )
+      end
+
+      def qr(format: nil, session: nil)
+        name = session_name(session, "session_qr")
+        response_format = format.nil? ? :binary : :json
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/auth/qr",
+          operation: "session_qr",
+          expected_status: 200,
+          query: Support.compact_hash(format: format),
+          response: response_format
+        )
+      end
+
+      def request_code(phone_number:, method: nil, session: nil)
+        name = session_name(session, "request_code")
+        transport.request(
+          method: :post,
+          path: "/api/#{segment(name)}/auth/request-code",
+          operation: "request_code",
+          expected_status: [200, 201],
+          body: Support.compact_hash(phoneNumber: phone_number, method: method)
+        )
+      end
+
+      private
+
+      def action(operation, action, session:, body: nil)
+        name = session_name(session, operation)
+        transport.request(
+          method: :post,
+          path: "/api/sessions/#{segment(name)}/#{action}",
+          operation:,
+          expected_status: [200, 201],
+          body:
+        )
+      end
+    end
+  end
+end

data/lib/waha/resources/webhooks.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Webhooks < Resource
+      def initialize(transport:, session:, sessions:)
+        super(transport:, session:)
+        @sessions = sessions
+      end
+
+      def configure(url:, events:, hmac_secret: nil, retries: nil, session: nil)
+        name = session_name(session, "configure_webhook")
+        session_data = @sessions.get(session: name)
+        config = session_config(session_data)
+        desired_config = config_with_webhook(config, url:, events:, hmac_secret:, retries:)
+        return :unchanged if desired_config == config
+
+        put_session(name, session_name_value(session_data, name), desired_config)
+        :updated
+      end
+
+      private
+
+      def session_config(session_data)
+        config = Support.value(session_data, "config")
+        unless config.is_a?(Hash)
+          raise ApiError.new(operation: "configure_webhook", details: "session response is missing config")
+        end
+
+        config
+      end
+
+      def config_with_webhook(config, url:, events:, hmac_secret:, retries:)
+        webhooks = Array(Support.value(config, "webhooks"))
+        index = webhooks.index { |webhook| matching_webhook?(webhook, url) }
+        kept = webhooks.reject { |webhook| matching_webhook?(webhook, url) }
+        kept.insert(index || kept.length, desired_webhook(url:, events:, hmac_secret:, retries:))
+        deep_dup(config).merge("webhooks" => kept)
+      end
+
+      def matching_webhook?(webhook, url)
+        webhook.is_a?(Hash) && webhook["url"] == url
+      end
+
+      def desired_webhook(url:, events:, hmac_secret:, retries:)
+        webhook = { "url" => url, "events" => Array(events).map(&:to_s) }
+        webhook["hmac"] = { "key" => hmac_secret } unless hmac_secret.nil?
+        webhook["retries"] = retries unless retries.nil?
+        webhook
+      end
+
+      def put_session(session_name, name, config)
+        transport.request(
+          method: :put,
+          path: "/api/sessions/#{segment(session_name)}",
+          operation: "configure_webhook",
+          expected_status: 200,
+          body: { name:, config: }
+        )
+      end
+
+      def session_name_value(session_data, fallback)
+        Support.value(session_data, "name") || fallback
+      end
+
+      def deep_dup(value, seen = {})
+        return value unless value.is_a?(Hash) || value.is_a?(Array)
+        return seen[value] if seen.key?(value)
+
+        copy = value.is_a?(Hash) ? {} : []
+        seen[value] = copy
+        copy_dup_children(value, copy, seen)
+      end
+
+      def copy_dup_children(value, copy, seen)
+        if value.is_a?(Hash)
+          value.each { |key, nested| copy[key] = deep_dup(nested, seen) }
+        else
+          value.each { |nested| copy << deep_dup(nested, seen) }
+        end
+        copy
+      end
+    end
+  end
+end

data/lib/waha/support.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Waha
+  module Support
+    module_function
+
+    def segment(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def value(hash, key)
+      return unless hash.is_a?(Hash)
+
+      hash[key.to_s] || hash[key.to_sym]
+    end
+
+    QUERY_KEY_MAP = {
+      download_media: "downloadMedia",
+      sort_by: "sortBy",
+      sort_order: "sortOrder",
+      last_message_timestamp: "lastMessageTimestamp",
+      last_message_lid: "lastMessageId",
+      contact_id: "contactId",
+      phone_number: "phoneNumber"
+    }.freeze
+
+    def compact_hash(hash)
+      hash.compact
+    end
+
+    def query_hash(hash)
+      hash.each_with_object({}) do |(key, value), query|
+        query[QUERY_KEY_MAP.fetch(key, key)] = value
+      end
+    end
+  end
+end

data/lib/waha/transport/faraday.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "faraday"
+
+module Waha
+  module Transport
+    class Faraday
+      JSON_HEADERS = { "Content-Type" => "application/json" }.freeze
+
+      def initialize(base_url:, api_key:, timeout:)
+        @base_url = base_url.to_s.delete_suffix("/")
+        @api_key = api_key
+        @timeout = timeout
+        @connection = ::Faraday.new do |conn|
+          conn.adapter ::Faraday.default_adapter
+        end
+      end
+
+      def request(**call_attributes)
+        operation = call_attributes.fetch(:operation)
+        response = validated_response_mode(call_attributes[:response] || :json)
+        http_response = dispatch_request(call_attributes)
+        verify_status!(http_response, call_attributes.fetch(:expected_status), operation)
+        parse_response(http_response, response, operation)
+      rescue Waha::Error
+        raise
+      rescue JSON::GeneratorError, JSON::ParserError
+        raise TransportError.new(operation:, details: "invalid JSON response")
+      rescue StandardError => e
+        raise TransportError.new(operation:, details: "transport failure (#{e.class})")
+      end
+
+      def escape_path_segment(value)
+        URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+      end
+
+      private
+
+      def dispatch_request(call_attributes)
+        method = call_attributes.fetch(:method)
+        url = request_url(call_attributes.fetch(:path))
+
+        @connection.public_send(method) do |req|
+          configure_request(req, url, call_attributes)
+        end
+      end
+
+      def configure_request(req, url, call_attributes)
+        req.url(url)
+        req.headers = request_headers(call_attributes[:headers])
+        req.body = request_body(call_attributes[:body])
+        req.params = call_attributes[:query] if call_attributes[:query]&.any?
+        configure_timeouts(req.options, call_attributes[:timeout])
+      end
+
+      def configure_timeouts(options, custom_timeout)
+        timeout = custom_timeout || @timeout
+        options.timeout = timeout
+        options.open_timeout = timeout
+      end
+
+      def request_headers(custom_headers)
+        default_headers.merge(custom_headers || {}).compact
+      end
+
+      def request_body(body)
+        return if body.nil?
+
+        JSON.generate(body)
+      end
+
+      def validated_response_mode(response)
+        return response if %i[json binary].include?(response)
+
+        raise ValidationError.new(operation: "request", details: "unsupported response mode")
+      end
+
+      def default_headers
+        JSON_HEADERS.merge(
+          "X-Api-Key" => @api_key,
+          "User-Agent" => "waha-ruby/#{Waha::VERSION}"
+        )
+      end
+
+      def request_url(path)
+        text = path.to_s
+        uri = URI.parse(text)
+        return uri.to_s if uri.absolute?
+
+        raise URI::InvalidURIError unless text.start_with?("/")
+        raise URI::InvalidURIError if text.start_with?("//")
+
+        "#{@base_url}#{text}"
+      rescue URI::InvalidURIError
+        raise ValidationError.new(operation: "request", details: "invalid request URL")
+      end
+
+      def verify_status!(response, expected_status, operation)
+        return if Array(expected_status).include?(response.status)
+
+        details = response.body.to_s.empty? ? "empty provider error response" : "[REDACTED]"
+        raise ApiError.new(operation:, status: response.status, details:)
+      end
+
+      def parse_response(response, format, operation)
+        return response.body if format == :binary
+        return nil if response.body.to_s.strip.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise TransportError.new(operation:, status: response.status, details: "invalid JSON response")
+      end
+    end
+  end
+end

data/lib/waha/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Waha
+  VERSION = "0.1.0"
+end

data/lib/waha/webhook.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Waha
+  module Webhook
+    DIGEST = "sha512"
+
+    module_function
+
+    def verify!(body:, signature:, algorithm:, secret:)
+      verify_algorithm!(algorithm)
+      signature_text = verified_signature_text(signature)
+      expected = OpenSSL::HMAC.hexdigest(DIGEST, secret.to_s, body.to_s)
+      return true if secure_compare?(signature_text, expected)
+
+      raise VerificationError.new(operation: "verify_webhook", details: "signature mismatch")
+    end
+
+    def verify_algorithm!(algorithm)
+      return if algorithm.to_s.strip.downcase == DIGEST
+
+      raise VerificationError.new(operation: "verify_webhook", details: "unsupported algorithm")
+    end
+    private_class_method :verify_algorithm!
+
+    def verified_signature_text(signature)
+      text = signature.to_s
+      expected_length = OpenSSL::Digest.new(DIGEST).digest_length * 2
+      return text if text.length == expected_length && text.match?(/\A[0-9a-fA-F]+\z/)
+
+      raise VerificationError.new(operation: "verify_webhook", details: "malformed signature")
+    end
+    private_class_method :verified_signature_text
+
+    def secure_compare?(signature, expected)
+      signature.bytesize == expected.bytesize && secure_bytes_equal?(signature, expected)
+    end
+    private_class_method :secure_compare?
+
+    def secure_bytes_equal?(left, right)
+      left_bytes = left.unpack("C*")
+      right_bytes = right.unpack("C*")
+      comparison = left_bytes.zip(right_bytes).reduce(0) { |result, pair| result | (pair[0] ^ pair[1]) }
+      comparison.zero?
+    end
+    private_class_method :secure_bytes_equal?
+  end
+end

data/lib/waha.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "waha/version"
+require "waha/error"
+require "waha/support"
+require "waha/transport/faraday"
+require "waha/resource"
+require "waha/resources/sessions"
+require "waha/resources/messages"
+require "waha/resources/chats"
+require "waha/resources/contacts"
+require "waha/resources/presence"
+require "waha/resources/webhooks"
+require "waha/resources/media"
+require "waha/gows"
+require "waha/webhook"
+require "waha/client"