waha-ruby 0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Contributions must keep the public API explicit, framework-neutral, and compatible with the declared v0.1 contract. Do not add runtime dependencies without a concrete API need.
+
+## Setup
+
+This repository uses [asdf](https://asdf-vm.com/) and `.tool-versions`.
+
+```bash
+asdf install
+ruby --version
+bundle install
+```
+
+`bin/setup` is a convenience wrapper for `bundle install`.
+
+Run focused tests while working:
+
+```bash
+bundle exec rspec spec/path/to/spec.rb
+```
+
+Before submitting, run the complete repository gate:
+
+```bash
+bin/ci
+```
+
+`bin/ci` runs RSpec, RuboCop, Reek on `lib`, Flay with mass threshold 150 on `lib`, and Bundler Audit. Do not add exclusions to silence warnings in new code. Fix the design or update a rule only when it reflects an established project convention.
+
+Use double-quoted Ruby strings and frozen string literals. Keep changes within the owned surface for the task; runtime API and API specs require their own focused review.
+
+## Documentation
+
+Update `README.md` for concise user-facing navigation and `docs/api.md` for signatures, return behavior, configuration, and security details. Do not copy upstream WAHA code. Link to the official Apache-2.0 project instead.
+
+## Release setup
+
+RubyGems trusted publishing requires no long-lived token:
+
+1. Create a GitHub environment named `rubygems` with no secrets.
+2. Add a pending trusted publisher for gem `waha-ruby` on RubyGems with owner `develoz-com`, repository `waha-ruby`, workflow `release.yml`, and environment `rubygems`.
+3. Keep the repository's release workflow pinned to the reviewed action SHAs.
+
+## Release process
+
+1. Bump `Waha::VERSION` in `lib/waha/version.rb` and add user-facing changes under `Unreleased` in `CHANGELOG.md`.
+2. Run `bin/ci` and review the package contents with `gem build waha-ruby.gemspec`.
+3. Merge to `main`.
+4. Publish a stable GitHub Release tagged `vX.Y.Z` at the current `main` commit.
+5. Let `release.yml` validate the tag, build and inspect the exact gem, publish through RubyGems OIDC, verify API visibility/SHA, and finalize `CHANGELOG.md`.
+
+Prereleases are not supported. If publication succeeds but changelog finalization fails, rerun the same workflow; do not create another tag or publish a second version.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2026 Mauricio Zaffari, Develoz
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# waha-ruby
+
+Framework-neutral Ruby client for the [WAHA](https://waha.dev/) WhatsApp HTTP API. It provides resource-oriented access to sessions, messages, media, chats, contacts, presence, webhooks, and explicit GOWS helpers, with an opt-in Rails adapter.
+
+> `waha-ruby` is an independent community project, not an official WAHA project. WAHA is documented at [waha.dev](https://waha.dev/) and developed at [devlikeapro/waha](https://github.com/devlikeapro/waha). This gem links to the Apache-2.0 upstream project and does not copy its code.
+
+## Requirements
+
+- Ruby 4.0.5 or newer
+- WAHA v2025.9 or a compatible WAHA HTTP API deployment
+- An API key when the WAHA deployment requires one
+
+The gem is tested against the declared v0.1 API surface. WAHA server versions can add or change response fields; the client returns parsed provider JSON without imposing a domain model.
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem "waha-ruby"
+```
+
+Then run `bundle install`. The only runtime dependency is `faraday`.
+
+## Quick start
+
+```ruby
+require "waha"
+
+client = Waha::Client.new(
+  base_url: ENV.fetch("WAHA_BASE_URL"),
+  api_key: ENV["WAHA_API_KEY"],
+  session: ENV.fetch("WAHA_SESSION", "default")
+)
+
+client.sessions.list
+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.
+
+## 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).
+
+## Security
+
+The client sends `X-Api-Key` to WAHA and never logs credentials. Error details are bounded and redacted before they are placed in `Waha::Error` messages. Treat raw response hashes as untrusted provider data and redact message text, phone numbers, media URLs, and API keys before logging or persisting them. Webhook verification must run against the exact raw request body before JSON parsing.
+
+## Development
+
+```bash
+asdf install
+bundle install
+bundle exec rspec path/to/spec.rb
+bin/ci
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for quality rules and releases. See [CHANGELOG.md](CHANGELOG.md) for changes.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run RuboCop linter"
+task :rubocop do
+  sh "bundle exec rubocop"
+end
+
+desc "Run CI checks (RSpec, RuboCop, Reek, Flay, and Bundler Audit)"
+task :ci do
+  sh "bin/ci"
+end
+
+task default: :spec

data/lib/generators/waha/install/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Waha
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        copy_file "waha.rb", "config/initializers/waha.rb"
+      end
+    end
+  end
+end

data/lib/generators/waha/install/templates/waha.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Keep WAHA credentials in the application environment. The factory creates a
+# fresh client for each caller, so session-specific state is never shared.
+Rails.application.config.waha.client_factory = lambda do |session: ENV.fetch("WAHA_SESSION")|
+  Waha::Client.new(
+    base_url: ENV.fetch("WAHA_BASE_URL"),
+    api_key: ENV.fetch("WAHA_API_KEY"),
+    session: session
+  )
+end
+
+# Used by Waha::Rails::ControllerConcern#verify_waha_webhook!.
+Rails.application.config.waha.webhook_secret = -> { ENV.fetch("WAHA_WEBHOOK_HMAC_KEY") }

data/lib/waha/client.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Waha
+  class Client
+    RESOURCES = {
+      sessions: Resources::Sessions,
+      messages: Resources::Messages,
+      chats: Resources::Chats,
+      contacts: Resources::Contacts,
+      presence: Resources::Presence,
+      webhooks: Resources::Webhooks,
+      media: Resources::Media
+    }.freeze
+
+    def initialize(base_url:, api_key:, session: nil, timeout: 30, transport: nil)
+      @base_url = base_url
+      @session = session
+      @transport = transport || Transport::Faraday.new(base_url:, api_key:, timeout:)
+      @resources = {}
+    end
+
+    RESOURCES.each do |name, resource_class|
+      define_method(name) do
+        @resources[name] ||= build_resource(name, resource_class)
+      end
+    end
+
+    private
+
+    def build_resource(name, resource_class)
+      return resource_class.new(transport: @transport, base_url: @base_url) if name == :media
+      return resource_class.new(transport: @transport, session: @session, sessions:) if name == :webhooks
+
+      resource_class.new(transport: @transport, session: @session)
+    end
+  end
+end

data/lib/waha/error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Waha
+  class Error < StandardError
+    MESSAGE_LIMIT = 600
+    DETAILS_LIMIT = 450
+
+    attr_reader :operation, :status, :details
+
+    def initialize(operation:, status: nil, details: nil)
+      @operation = operation.to_s.slice(0, 80)
+      @status = status
+      @details = sanitize(details)
+      super(build_message.slice(0, MESSAGE_LIMIT))
+    end
+
+    private
+
+    def sanitize(details)
+      text = details.to_s
+      text = "operation failed" if text.empty?
+      text.gsub(%r{data:[^\s,;]+;base64,[A-Za-z0-9+/=]+}i, "[REDACTED]")
+          .slice(0, DETAILS_LIMIT)
+    end
+
+    def build_message
+      status_text = status.nil? ? "unknown" : status
+      "WAHA #{operation} failed (status #{status_text}): #{details}"
+    end
+  end
+
+  class ApiError < Error; end
+  class TransportError < Error; end
+  class ValidationError < Error; end
+  class VerificationError < Error; end
+end

data/lib/waha/gows.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Waha
+  module Gows
+    DIRECT_CHAT_ID_PATTERN = /\A\d+@c\.us\z/
+
+    module MessageId
+      RAW_PATTERN = /\A3EB0[0-9A-F]{18}\z/
+      CANONICAL_PATTERN = /\Atrue_[^\s]+_3EB0[0-9A-F]{18}\z/
+
+      module_function
+
+      def valid_raw?(raw_id)
+        raw_id.is_a?(String) && RAW_PATTERN.match?(raw_id)
+      end
+
+      def canonical(chat_id:, raw_id:)
+        unless chat_id.is_a?(String) && !chat_id.empty?
+          raise ValidationError.new(operation: "canonical_message_id", details: "chat_id is required")
+        end
+        unless valid_raw?(raw_id)
+          raise ValidationError.new(operation: "canonical_message_id", details: "raw_id must be a valid GOWS id")
+        end
+
+        "true_#{chat_id}_#{raw_id}"
+      end
+
+      def valid_canonical?(message_id)
+        return false unless message_id.is_a?(String)
+        return false unless CANONICAL_PATTERN.match?(message_id)
+
+        raw_id = message_id.to_s.split("_").last
+        valid_raw?(raw_id)
+      end
+    end
+
+    module_function
+
+    def valid_direct_chat_id?(chat_id)
+      chat_id.is_a?(String) && DIRECT_CHAT_ID_PATTERN.match?(chat_id)
+    end
+
+    class EditResponseValidator
+      TARGET_ID_LENGTH = 22
+
+      EDIT_MISSING_MESSAGE = "edit protocol response missing"
+      TARGET_MISMATCH_MESSAGE = "edit protocol response targeted another message"
+      TEXT_MISMATCH_MESSAGE = "edit protocol response text mismatch"
+
+      def initialize(parsed_response:, message_id:, text:, status: nil)
+        @parsed_response = parsed_response
+        @message_id = message_id
+        @text = text
+        @status = status
+      end
+
+      def validate!
+        protocol_message = extract_protocol_message
+        raise_error!(EDIT_MISSING_MESSAGE) unless protocol_message.is_a?(Hash)
+
+        raise_error!(TARGET_MISMATCH_MESSAGE) unless target_matches?(protocol_message)
+        raise_error!(TEXT_MISMATCH_MESSAGE) unless text_matches?(protocol_message)
+
+        @parsed_response
+      end
+
+      private
+
+      def extract_protocol_message
+        data = hash_value(@parsed_response, "_data")
+        message = hash_value(data, "Message")
+        raw_message = hash_value(data, "RawMessage")
+
+        hash_value(message, "protocolMessage") || hash_value(raw_message, "protocolMessage")
+      end
+
+      def target_matches?(protocol_message)
+        target_id = nested_value(protocol_message, "key", "ID")
+        target_id.is_a?(String) &&
+          target_id.length == TARGET_ID_LENGTH &&
+          @message_id.to_s.end_with?(target_id)
+      end
+
+      def text_matches?(protocol_message)
+        nested_value(protocol_message, "editedMessage", "extendedTextMessage", "text") == @text
+      end
+
+      def nested_value(value, *keys)
+        keys.reduce(value) { |nested, key| hash_value(nested, key) }
+      end
+
+      def hash_value(value, key)
+        return unless value.is_a?(Hash)
+
+        value[key] || value[key.to_sym]
+      end
+
+      def raise_error!(details)
+        raise ApiError.new(operation: "edit_message", status: @status, details:)
+      end
+    end
+  end
+end

data/lib/waha/rails/controller_concern.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Waha
+  module Rails
+    module ControllerConcern
+      extend ActiveSupport::Concern
+
+      private
+
+      def verify_waha_webhook!
+        raw_body = request.body.read
+        Waha::Webhook.verify!(
+          body: raw_body,
+          signature: request.headers["X-Webhook-Hmac"],
+          algorithm: request.headers["X-Webhook-Hmac-Algorithm"],
+          secret: waha_webhook_secret
+        )
+      ensure
+        request.body.rewind
+      end
+
+      def waha_webhook_secret
+        configured_secret = ::Rails.application.config.waha.webhook_secret
+        configured_secret.respond_to?(:call) ? configured_secret.call : configured_secret
+      end
+    end
+  end
+end

data/lib/waha/rails/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_support/ordered_options"
+
+module Waha
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.waha = ActiveSupport::OrderedOptions.new
+    end
+  end
+end

data/lib/waha/rails.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "waha"
+require "active_support"
+require "rails/railtie"
+require_relative "rails/controller_concern"
+require_relative "rails/railtie"
+require_relative "../generators/waha/install/install_generator"

data/lib/waha/resource.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Waha
+  class Resource
+    def initialize(transport:, session:)
+      @transport = transport
+      @session = session
+    end
+
+    private
+
+    attr_reader :transport
+
+    def session_name(override, operation)
+      value = override || @session
+      return value unless value.nil? || value.to_s.empty?
+
+      raise ValidationError.new(operation:, details: "session is required")
+    end
+
+    def segment(value)
+      transport.escape_path_segment(value)
+    end
+  end
+end

data/lib/waha/resources/chats.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Chats < Resource
+      def overview(ids: nil, limit: nil, offset: nil, session: nil, **query)
+        name = session_name(session, "chats_overview")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/chats/overview",
+          operation: "chats_overview",
+          expected_status: 200,
+          query: Support.query_hash(Support.compact_hash(query.merge(ids:, limit:, offset:)))
+        )
+      end
+
+      def messages(chat_id:, limit: 100, offset: nil, session: nil, **query)
+        name = session_name(session, "chat_messages")
+        transport.request(
+          method: :get,
+          path: "/api/#{segment(name)}/chats/#{segment(chat_id)}/messages",
+          operation: "chat_messages",
+          expected_status: 200,
+          query: Support.query_hash(Support.compact_hash(query.merge(limit:, offset:)))
+        )
+      end
+    end
+  end
+end

data/lib/waha/resources/contacts.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Waha
+  module Resources
+    class Contacts < Resource
+      def list(session: nil, **query)
+        transport.request(
+          method: :get,
+          path: "/api/contacts/all",
+          operation: "list_contacts",
+          expected_status: 200,
+          query: Support.compact_hash(query.merge(session: session_name(session, "list_contacts")))
+        )
+      end
+
+      def get(contact_id:, session: nil)
+        transport.request(
+          method: :get,
+          path: "/api/contacts",
+          operation: "get_contact",
+          expected_status: 200,
+          query: { session: session_name(session, "get_contact"), contactId: contact_id }
+        )
+      end
+
+      def check_exists(phone:, session: nil)
+        transport.request(
+          method: :get,
+          path: "/api/contacts/check-exists",
+          operation: "check_contact_exists",
+          expected_status: 200,
+          query: { session: session_name(session, "check_contact_exists"), phone: }
+        )
+      end
+    end
+  end
+end

data/lib/waha/resources/media.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Waha
+  module Resources
+    class Media < Resource
+      DOWNLOAD_TIMEOUT = 60
+
+      def initialize(transport:, base_url:)
+        super(transport:, session: nil)
+        @base_url = base_url
+      end
+
+      def download(url:)
+        transport.request(
+          method: :get,
+          path: resolved_url(url),
+          operation: "download_media",
+          expected_status: 200,
+          headers: { "Content-Type" => nil },
+          timeout: DOWNLOAD_TIMEOUT,
+          response: :binary
+        )
+      end
+
+      private
+
+      def resolved_url(url)
+        uri = parse_uri(url)
+
+        unless uri.absolute?
+          raise ValidationError.new(operation: "download_media", details: "media URL must be absolute")
+        end
+        unless uri.is_a?(URI::HTTP)
+          raise ValidationError.new(operation: "download_media", details: "unsupported media URL scheme")
+        end
+
+        return uri.to_s unless uri.host == "localhost"
+
+        rebase_to_base_url(uri)
+      end
+
+      def rebase_to_base_url(uri)
+        base_uri = URI.parse(@base_url)
+        uri.scheme = base_uri.scheme
+        uri.host = base_uri.host
+        uri.port = base_uri.port
+        uri.to_s
+      end
+
+      def parse_uri(url)
+        text = url.to_s
+        uri = URI.parse(text)
+        raise URI::InvalidURIError if text.include?("//") && uri.host.to_s.empty?
+
+        uri
+      rescue URI::InvalidURIError
+        raise ValidationError.new(operation: "download_media", details: "invalid media URL")
+      end
+    end
+  end
+end