waha-ruby 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6143fc09b5ea2bfb45b55cba490a5b2f4b2527800991e8207f9f838c363998f
-  data.tar.gz: e740e63e91ffadba7ee5919d36722f973847c86818c244753535f98dca9cd70d
+  metadata.gz: 36cfca6cd9f43620fcc84fe54c821262683471a4a56c74f8f757e07044e3cc46
+  data.tar.gz: f393af7a3285bfc18fa6684c943d6aae31046c283447f960ba37e571c99dce6f
 SHA512:
-  metadata.gz: 63f59ffd2b58f82e9ca8e925b5e8c07958e8e508f12a1df49c73cc9ffaf3311b7be6546632d988b987ac35cd11169bfe9effd2896642763a371501a6e04a2462
-  data.tar.gz: 4dee276f3bbfbb301a9f4beaa499c92e0bbba61ada941acef1487bcbe041539f21746f071679b8359044bb11d97a8761905ff06d37cc5b64cf3353b8001f39ec
+  metadata.gz: 621b3f6e2a63cf06ff933cad60c07e09dafd9b6d3eea473d718604a6ff8f7f580bea029e21e3abc074996b9804141b9c4f16d2afdef2869a38badd12d6985050
+  data.tar.gz: 0b3f6c7db0e5c4ec5222021d445334d45bf53af6fbb2b766555633ccdfd560cd15ca167a87287b8ba3e2dae3ddb405afa37181f4848c80c8817fcd2a13eb5900

data/CHANGELOG.md

@@ -8,6 +8,39 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-16
+
+### Added
+
+- `Waha.configure`, `Waha.configuration`, `Waha.configured?`, and
+  `Waha.client(session:, **overrides)` for opt-in process-wide defaults.
+  Every call builds a fresh client; instances are never cached.
+- `Waha.valid_chat_id?` for `@c.us`, `@g.us`, and `@lid` ids, plus
+  `Waha.group_chat_id` to append the `@g.us` suffix when absent.
+- `Waha::Resources::Chats#list` for `GET /api/{session}/chats`.
+- `Waha::Resources::Groups` (`client.groups`) with `list` and `get`.
+- `Waha::Resources::Sessions#update` (`PUT /api/sessions/{name}`).
+- `Waha::Resources::Sessions#qr_data_url`, returning the QR PNG as a
+  browser-ready `data:image/png;base64,` URL.
+- `Waha::Resources::Sessions#ready?`, a WORKING-status predicate.
+- `Waha::ServerError` (>= 500) and `Waha::RateLimitError` (429), plus
+  `Waha::Error#retryable?` covering transport failures, 408, and 429.
+- Opt-in Rails adapter `Waha::Rails::SessionState` (aliased as
+  `Waha::SessionState`), which memoizes session readiness in `Rails.cache`.
+
+### Changed
+
+- `Waha::Resources::Messages#send_image`, `#send_file`, and `#send_voice`
+  now accept `mimetype: nil`: the MIME type is read from the data URL prefix
+  when omitted, and left out of the payload for remote URLs so WAHA can
+  detect it.
+- Text, media, seen, and typing requests accept both `200` and `201`
+  responses across WAHA engines.
+- `Waha::Resources::Sessions#qr` treats `format: "image"` as binary, not JSON.
+- `Waha::Client` exposes `session`.
+
+## [0.1.1] - 2026-09-09
+
 ### Fixed
 
 - `Waha::Webhook.verify!` fails closed when the secret is nil, empty, or
@@ -44,5 +77,7 @@ and this project adheres to
   install generator for the `waha.rb` initializer.
 - Typed `Waha::Error` (operation, status, bounded redacted details) with
   provider payload redaction.
-[Unreleased]: https://github.com/develoz-com/waha-ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/develoz-com/waha-ruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/develoz-com/waha-ruby/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/develoz-com/waha-ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/develoz-com/waha-ruby/releases/tag/v0.1.0

data/README.md

@@ -39,6 +39,21 @@ client.messages.send_text(chat_id: "5511999999999@c.us", text: "Olá")
 
 Every request uses the client's default session unless a resource method accepts an explicit `session:` override. Keep credentials in environment variables or a secret manager; do not commit them.
 
+Applications that prefer process-wide defaults can configure the module once and build a fresh client per call:
+
+```ruby
+Waha.configure do |config|
+  config.base_url = ENV.fetch("WAHA_BASE_URL")
+  config.api_key = ENV["WAHA_API_KEY"]
+  config.session = ENV.fetch("WAHA_SESSION", "default")
+end
+
+Waha.configured?                 # => true
+Waha.client(session: "default")  # a new Waha::Client, never cached
+```
+
+`Waha.client` never caches instances, so per-call session overrides cannot leak across callers.
+
 ## API guide
 
 The complete v0.1 resource map, argument conventions, raw return shapes, file payloads, errors, GOWS helpers, webhook verification, and Rails integration are in [docs/api.md](docs/api.md). For setup and secret handling, see [docs/installation.md](docs/installation.md).

data/lib/waha/client.rb

@@ -6,6 +6,7 @@ module Waha
       sessions: Resources::Sessions,
       messages: Resources::Messages,
       chats: Resources::Chats,
+      groups: Resources::Groups,
       contacts: Resources::Contacts,
       presence: Resources::Presence,
       webhooks: Resources::Webhooks,
@@ -19,6 +20,8 @@ module Waha
       @resources = {}
     end
 
+    attr_reader :session
+
     RESOURCES.each do |name, resource_class|
       define_method(name) do
         @resources[name] ||= build_resource(name, resource_class)

data/lib/waha/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Waha
+  DEFAULT_TIMEOUT = 30
+  DEFAULT_SESSION = "default"
+
+  # Process-wide defaults for Waha.client. Rails applications can set these in
+  # an initializer; framework-neutral callers can pass keywords to Waha.client.
+  # No client instances are cached here.
+  Configuration = Struct.new(:base_url, :api_key, :session, :timeout) do
+    def initialize(base_url: nil, api_key: nil, session: nil, timeout: nil)
+      super(
+        base_url || default_base_url,
+        api_key || ENV.fetch("WAHA_API_KEY", nil),
+        session || default_session,
+        timeout || DEFAULT_TIMEOUT
+      )
+    end
+
+    alias_method :session_name, :session
+    alias_method :session_name=, :session=
+
+    private
+
+    def default_base_url
+      ENV.fetch("WAHA_BASE_URL", nil) || ENV.fetch("WAHA_API_URL", nil)
+    end
+
+    def default_session
+      ENV.fetch("WAHA_SESSION", nil) || ENV.fetch("WAHA_SESSION_NAME", nil) || DEFAULT_SESSION
+    end
+  end
+end

data/lib/waha/error.rb

@@ -5,6 +5,8 @@ module Waha
     MESSAGE_LIMIT = 600
     DETAILS_LIMIT = 450
 
+    RETRYABLE_STATUSES = [408, 429].freeze
+
     attr_reader :operation, :status, :details
 
     def initialize(operation:, status: nil, details: nil)
@@ -14,6 +16,12 @@ module Waha
       super(build_message.slice(0, MESSAGE_LIMIT))
     end
 
+    # Retryable failures: transport problems, WAHA server errors, rate limits, timeouts.
+    def retryable?
+      is_a?(ServerError) || is_a?(RateLimitError) || is_a?(TransportError) ||
+        RETRYABLE_STATUSES.include?(status)
+    end
+
     private
 
     def sanitize(details)
@@ -30,6 +38,8 @@ module Waha
   end
 
   class ApiError < Error; end
+  class ServerError < ApiError; end
+  class RateLimitError < ApiError; end
   class TransportError < Error; end
   class ValidationError < Error; end
   class VerificationError < Error; end

data/lib/waha/rails/session_state.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Waha
+  module Rails
+    module SessionState
+      CACHE_KEY_PREFIX = "waha:session_active"
+      CACHE_TTL = 30
+
+      module_function
+
+      def active?(session_name: Waha.configuration.session_name)
+        return false unless Waha.configured?
+
+        ::Rails.cache.fetch(cache_key(session_name), expires_in: CACHE_TTL) do
+          Waha.client(session: session_name).sessions.ready?
+        end
+      end
+
+      def cache_key(session_name)
+        "#{CACHE_KEY_PREFIX}:#{session_name}"
+      end
+    end
+  end
+end

data/lib/waha/rails.rb

@@ -4,5 +4,10 @@ require "waha"
 require "active_support"
 require "rails/railtie"
 require_relative "rails/controller_concern"
+require_relative "rails/session_state"
 require_relative "rails/railtie"
 require_relative "../generators/waha/install/install_generator"
+
+module Waha
+  SessionState = Waha::Rails::SessionState
+end

data/lib/waha/resources/chats.rb

@@ -3,6 +3,17 @@
 module Waha
   module Resources
     class Chats < Resource
+      def list(session: nil, **query)
+        name = session_name(session, "list_chats")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/chats",
+          operation: "list_chats",
+          expected_status: 200,
+          query: Support.query_hash(Support.compact_hash(query))
+        )
+      end
+
       def overview(ids: nil, limit: nil, offset: nil, session: nil, **query)
         name = session_name(session, "chats_overview")
         transport.request(

data/lib/waha/resources/groups.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Groups < Resource
+      def list(session: nil, **query)
+        name = session_name(session, "list_groups")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/groups",
+          operation: "list_groups",
+          expected_status: 200,
+          query: Support.query_hash(Support.compact_hash(query))
+        )
+      end
+
+      def get(group_id:, session: nil)
+        name = session_name(session, "get_group")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/groups/#{segment(group_id)}",
+          operation: "get_group",
+          expected_status: 200
+        )
+      end
+    end
+  end
+end

data/lib/waha/resources/messages.rb

@@ -7,6 +7,8 @@ module Waha
     class Messages < Resource
       DATA_MEDIA_CHARS = "a-zA-Z0-9!/:[:space:]\u0023$&'()*+,;=?~_-"
       DATA_URL_PATTERN = Regexp.new("\\Adata:[#{DATA_MEDIA_CHARS}]*;base64,", Regexp::IGNORECASE)
+      DATA_URL_MIMETYPE_PATTERN = Regexp.new("\\Adata:([^;,]+);base64,", Regexp::IGNORECASE)
+      SUCCESS_STATUSES = [200, 201].freeze
 
       def send_text(chat_id:, text:, id: nil, reply_to: nil, session: nil)
         body = { session: session_name(session, "send_text"), chatId: chat_id, text: }
@@ -16,7 +18,7 @@ module Waha
           method: :post,
           path: "/api/sendText",
           operation: "send_text",
-          expected_status: 201,
+          expected_status: SUCCESS_STATUSES,
           body:
         )
       end
@@ -62,7 +64,7 @@ module Waha
           method: :post,
           path: "/api/sendSeen",
           operation: "send_seen",
-          expected_status: 201,
+          expected_status: SUCCESS_STATUSES,
           body:
         )
       end
@@ -85,36 +87,36 @@ module Waha
         )
       end
 
-      def send_image(chat_id:, file:, mimetype:, filename: nil, caption: nil, reply_to: nil, session: nil)
+      def send_image(chat_id:, file:, mimetype: nil, 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,
+          expected_status: SUCCESS_STATUSES,
           body:
         )
       end
 
-      def send_file(chat_id:, file:, mimetype:, filename: nil, caption: nil, reply_to: nil, session: nil)
+      def send_file(chat_id:, file:, mimetype: nil, 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,
+          expected_status: SUCCESS_STATUSES,
           body:
         )
       end
 
-      def send_voice(chat_id:, file:, mimetype:, filename: nil, reply_to: nil, convert: nil, session: nil)
+      def send_voice(chat_id:, file:, mimetype: nil, 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,
+          expected_status: SUCCESS_STATUSES,
           body:
         )
       end
@@ -139,20 +141,39 @@ module Waha
 
       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)
+          remote_file_payload(file, mimetype, filename)
         elsif data_url?(file)
-          payload.merge(data: file.split(",", 2).last)
+          inline_file_payload(operation, file, mimetype, filename)
         else
           raise ValidationError.new(operation:, details: "file must be an http(s) URL or data URL")
         end
       end
 
+      # WAHA detects the MIME type of remote URLs; an explicit mimetype wins.
+      def remote_file_payload(file, mimetype, filename)
+        payload = {}
+        payload[:mimetype] = mimetype unless mimetype.to_s.empty?
+        payload[:filename] = filename unless filename.nil?
+        payload.merge(url: file)
+      end
+
+      # Data URLs carry their MIME type in the prefix when none is supplied.
+      def inline_file_payload(operation, file, mimetype, filename)
+        resolved_mimetype = mimetype.to_s.empty? ? data_url_mimetype(file) : mimetype
+        raise ValidationError.new(operation:, details: "mimetype is required") if resolved_mimetype.to_s.empty?
+
+        payload = { mimetype: resolved_mimetype }
+        payload[:filename] = filename unless filename.nil?
+        payload.merge(data: file.split(",", 2).last)
+      end
+
+      def data_url_mimetype(value)
+        match = DATA_URL_MIMETYPE_PATTERN.match(value.to_s)
+        match && match[1]
+      end
+
       def http_url?(value)
         uri = URI.parse(value.to_s)
         uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
@@ -169,7 +190,7 @@ module Waha
           method: :post,
           path: "/api/#{endpoint}",
           operation:,
-          expected_status: 201,
+          expected_status: SUCCESS_STATUSES,
           body: { session: session_name(session, operation), chatId: chat_id }
         )
       end

data/lib/waha/resources/sessions.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require "base64"
+
 module Waha
   module Resources
     class Sessions < Resource
+      WORKING_STATUS = "WORKING"
+
       def list(all: nil)
         transport.request(
           method: :get,
@@ -24,13 +28,13 @@ module Waha
       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:)
-        )
+        write_session("create_session", :post, "/api/sessions", { name:, start:, config: })
+      end
+
+      def update(session: nil, name: nil, config: nil)
+        session_key = session_name(session, "update_session")
+        write_session("update_session", :put, "/api/sessions/#{segment(session_key)}",
+                      { name: name || session_key, config: })
       end
 
       def start(session: nil)
@@ -61,17 +65,29 @@ module Waha
 
       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
+          response: qr_response_format(format)
         )
       end
 
+      # PNG bytes rendered as a browser-ready data URL.
+      def qr_data_url(session: nil)
+        png = qr(format: "image", session:)
+        "data:image/png;base64,#{Base64.strict_encode64(png.to_s)}"
+      end
+
+      # WAHA reports WORKING for an authenticated, usable session.
+      def ready?(session: nil)
+        Support.value(get(session:), "status") == WORKING_STATUS
+      rescue Waha::Error
+        false
+      end
+
       def request_code(phone_number:, method: nil, session: nil)
         name = session_name(session, "request_code")
         transport.request(
@@ -85,6 +101,14 @@ module Waha
 
       private
 
+      def write_session(operation, method, path, body)
+        transport.request(method:, path:, operation:, expected_status: [200, 201], body: Support.compact_hash(body))
+      end
+
+      def qr_response_format(format)
+        format.to_s == "image" || format.nil? ? :binary : :json
+      end
+
       def action(operation, action, session:, body: nil)
         name = session_name(session, operation)
         transport.request(

data/lib/waha/transport/faraday.rb

@@ -101,7 +101,14 @@ module Waha
         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:)
+        raise error_for(response.status).new(operation:, status: response.status, details:)
+      end
+
+      def error_for(status)
+        return RateLimitError if status == 429
+        return ServerError if status.to_i >= 500
+
+        ApiError
       end
 
       def parse_response(response, format, operation)

data/lib/waha/version.rb

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

data/lib/waha.rb

@@ -3,11 +3,13 @@
 require "waha/version"
 require "waha/error"
 require "waha/support"
+require "waha/configuration"
 require "waha/transport/faraday"
 require "waha/resource"
 require "waha/resources/sessions"
 require "waha/resources/messages"
 require "waha/resources/chats"
+require "waha/resources/groups"
 require "waha/resources/contacts"
 require "waha/resources/presence"
 require "waha/resources/webhooks"
@@ -15,3 +17,49 @@ require "waha/resources/media"
 require "waha/gows"
 require "waha/webhook"
 require "waha/client"
+
+module Waha
+  CHAT_ID_PATTERN = /\A[\d-]+@(?:[cg]\.us|lid)\z/
+  GROUP_CHAT_ID_SUFFIX = "@g.us"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Resets configuration; primarily useful for tests and forked workers.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def configured?
+      !configuration.base_url.to_s.strip.empty?
+    end
+
+    # Builds a fresh client per call. Client instances are never cached so
+    # per-request session overrides can never leak across callers.
+    def client(session: nil, **overrides)
+      Waha::Client.new(
+        base_url: overrides.fetch(:base_url, configuration.base_url),
+        api_key: overrides.fetch(:api_key, configuration.api_key),
+        session: session || overrides.fetch(:session, configuration.session),
+        timeout: overrides.fetch(:timeout, configuration.timeout)
+      )
+    end
+
+    # True for contact (@c.us), group (@g.us), and lid (@lid) chat IDs.
+    def valid_chat_id?(chat_id)
+      !chat_id.to_s.strip.empty? && CHAT_ID_PATTERN.match?(chat_id.to_s)
+    end
+
+    # Appends the @g.us suffix when absent so bare numeric group IDs are usable.
+    def group_chat_id(id)
+      text = id.to_s
+      text.end_with?(GROUP_CHAT_ID_SUFFIX) ? text : "#{text}#{GROUP_CHAT_ID_SUFFIX}"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waha-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Mauricio Zaffari
@@ -229,14 +229,17 @@ files:
 - lib/generators/waha/install/templates/waha.rb
 - lib/waha.rb
 - lib/waha/client.rb
+- lib/waha/configuration.rb
 - lib/waha/error.rb
 - lib/waha/gows.rb
 - lib/waha/rails.rb
 - lib/waha/rails/controller_concern.rb
 - lib/waha/rails/railtie.rb
+- lib/waha/rails/session_state.rb
 - lib/waha/resource.rb
 - lib/waha/resources/chats.rb
 - lib/waha/resources/contacts.rb
+- lib/waha/resources/groups.rb
 - lib/waha/resources/media.rb
 - lib/waha/resources/messages.rb
 - lib/waha/resources/presence.rb
@@ -251,7 +254,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/develoz-com/waha-ruby
-  source_code_uri: https://github.com/develoz-com/waha-ruby/tree/v0.1.1
+  source_code_uri: https://github.com/develoz-com/waha-ruby/tree/v0.2.0
   changelog_uri: https://github.com/develoz-com/waha-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []