ararahq 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76d8cd62472512d57be879f384202d4c0075c6e281328e265ad8103391232c1a
+  data.tar.gz: efc27423be8a8a20e965fb81e74d463b217631cd8bdfb8f7f07529807fabdae5
+SHA512:
+  metadata.gz: 5150377594577e64ce679080a5bde8ed93b993a6ec48031d502391f82d5af9f894392c62b19e568121aa3f37b6ee59bc48b32e16762ef89e1d0ea195c561285b
+  data.tar.gz: 7b21d10c51ac110ee75f197cd706a97c3c97d2c1c9e7131191d7e684af38e67fd8853e8cc180a8dfa54032559c3a2c7cb70d728fe10c203b315a57b83c6ac65e

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 1.0.0 - 2026-09-24
+
+Primeira versão publicada no RubyGems. Alinha o SDK ao contrato da API por chave.
+
+### Breaking
+- `messages.send` foi removido (sobrescrevia `Object#send`). Use `messages.send_message` ou `messages.deliver`.
+- `templates.get`, `get_status` e `delete` recebem o `id` (UUID) do template, não o nome. Para buscar por nome, `templates.find_by_name` (filtro local sobre `list`).
+- `templates.list`, `smart_links.list`, `campaigns.list` e `wallet.transactions` devolvem `Arara::Page` (`data` + `pagination`).
+- Removidos `users`, `organizations` (webhook) e `api_keys`: não são alcançáveis por chave. Use `auth.me` (`GET /auth/me`).
+- 403 sem `code` agora levanta `Arara::AuthenticationError`.
+
+### Added
+- `Idempotency-Key` automático (UUID v4) em `messages.send_message`, `messages.send_batch` e `campaigns.create`, reaproveitado em todas as retentativas.
+- `sender`, `type`, `interactive`, `charge`, `location`, `reaction`, `reply_to`, `smart_link_param`, `smart_link_url` e `mode` no envio.
+- `messages.get`, `messages.send_batch` (até 1000), `messages.list_by_batch`.
+- `templates.analytics`, `templates.template_analytics`, filtros e paginação em `templates.list`; paginação em `smart_links.list`.
+- `opt_outs` (`list`, `create`, `get`, `delete`).
+- Erros `PlanFeatureLockedError` (`feature`, `current_plan`, `upgrade_to`), `PaymentRequiredError` (402) e `UnprocessableEntityError` (422).
+- LICENSE MIT e suíte de testes (minitest).
+
+### Fixed
+- `Retry-After` em formato de data não derruba mais a chamada (`require "time"`).
+- POST/PATCH sem `Idempotency-Key` não é mais repetido em 5xx, 429 ou erro de rede.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arara HQ
+
+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,124 @@
+# AraraHQ Ruby SDK
+
+Official Ruby client for the [AraraHQ](https://ararahq.com) WhatsApp API. Zero runtime dependencies: pure Ruby stdlib (`net/http`, `json`, `uri`, `time`, `securerandom`). Ruby >= 3.0.
+
+## Install
+
+```ruby
+gem "ararahq"
+```
+
+```bash
+gem install ararahq
+```
+
+## Usage
+
+```ruby
+require "arara"
+
+client = Arara::Client.new(api_key: "ara_live_...")
+
+# Send a template message. `deliver` is an alias of `send_message`.
+result = client.messages.send_message(
+  receiver: "5511999998888",          # also accepts "+55..." and "whatsapp:+55..."
+  sender: "+5511888887777",           # optional: which of your numbers sends it
+  template_name: "boas_vindas",
+  template_variables: ["Micael"],
+  idempotency_key: "order-1234"       # optional: generated when omitted
+)
+puts result["id"]
+
+client.messages.get(result["id"])
+
+# Up to 1000 receivers of the same template
+client.messages.send_batch(
+  template_name: "boas_vindas",
+  messages: [{ "receiver" => "5511999998888", "variables" => ["Ana"] }]
+)
+
+# Paginated lists return Arara::Page (Enumerable over `data`)
+page = client.templates.list(status: "APPROVED", page: 0, size: 50)
+page.each { |template| puts template["id"] }
+page.pagination.total_pages
+page.next_page?
+
+# Templates are addressed by id (UUID)
+client.templates.get_status(page.data.first["id"])
+client.templates.find_by_name("boas_vindas") # local filter over list
+
+# Campaigns (idempotency key is auto-generated when omitted)
+client.campaigns.create(
+  {
+    "name" => "Reativação Julho",
+    "templateName" => "reativacao",
+    "contacts" => [{ "to" => "5511999998888", "variables" => ["Micael"] }]
+  }
+)
+```
+
+Responses are parsed from JSON into plain Ruby `Hash` objects with string keys, exactly as the API returns them.
+
+## Configuration
+
+```ruby
+Arara::Client.new(
+  api_key: "ara_live_...",
+  base_url: "https://api.ararahq.com", # default
+  timeout: 10,                          # seconds, default
+  max_retries: 3                        # default
+)
+```
+
+`GET`, `PUT` and `DELETE`, and any request carrying an `Idempotency-Key`, are retried on `429`, `5xx` and network errors with exponential backoff, honoring `Retry-After`. A `POST`/`PATCH` without `Idempotency-Key` is never retried. `messages.send_message`, `messages.send_batch` and `campaigns.create` always send one (a UUID v4 when you do not pass yours), reused across retries, so a retry never duplicates a send.
+
+## Resources
+
+`auth`, `messages`, `templates`, `contacts`, `conversations`, `wallet`, `numbers`, `smart_links`, `campaigns`, `opt_outs`.
+
+## API key permissions
+
+`READ` keys can `GET` messages, campaigns, templates and numbers. Sending needs `MESSAGES_SEND` (messages) or `CAMPAIGNS_SEND` (campaigns); creating templates needs `TEMPLATES_WRITE`; `contacts` writes need `CONTACTS_WRITE`.
+
+These require an `ADMIN` key: `auth.me`, `contacts` (reads), `conversations`, `wallet` and `opt_outs`. Permissions are enforced by the API.
+
+## Errors
+
+Every failed request raises an `Arara::Error` (or a subclass) with `status_code`, `code`, `message`, `details` and `retry_after`.
+
+| Status | Class |
+|---|---|
+| 400 | `Arara::BadRequestError` |
+| 401, 403 without `code` (invalid key or missing permission) | `Arara::AuthenticationError` |
+| 402 | `Arara::PaymentRequiredError` |
+| 403 `PLAN_FEATURE_LOCKED` | `Arara::PlanFeatureLockedError` (`feature`, `current_plan`, `upgrade_to`) |
+| 403 with another `code` | `Arara::PermissionError` |
+| 404 | `Arara::NotFoundError` |
+| 409 | `Arara::ConflictError` |
+| 422 | `Arara::UnprocessableEntityError` (e.g. `INVALID_RECIPIENT`, `TEMPLATE_PAUSED`) |
+| 429 | `Arara::RateLimitError` |
+| 5xx | `Arara::ServerError` |
+| network | `Arara::NetworkError` |
+
+```ruby
+begin
+  client.messages.send_message(receiver: "5511999998888", template_name: "x")
+rescue Arara::PlanFeatureLockedError => e
+  puts "upgrade to #{e.upgrade_to}"
+rescue Arara::RateLimitError => e
+  puts "retry after #{e.retry_after}s"
+rescue Arara::Error => e
+  puts "#{e.code}: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/arara.gemspec

@@ -0,0 +1,23 @@
+require_relative "lib/arara/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ararahq"
+  spec.version = Arara::VERSION
+  spec.authors = ["AraraHQ"]
+  spec.email = ["dev@ararahq.com"]
+
+  spec.summary = "Official Ruby SDK for the AraraHQ WhatsApp API."
+  spec.description = "Ruby client for the AraraHQ API: messages, templates, contacts, " \
+                     "conversations, campaigns, wallet, numbers, smart links and opt-outs. Zero runtime dependencies."
+  spec.homepage = "https://ararahq.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ararahq/arara-ruby-sdk"
+  spec.metadata["changelog_uri"] = "https://github.com/ararahq/arara-ruby-sdk/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir["lib/**/*.rb"] + ["README.md", "CHANGELOG.md", "LICENSE", "arara.gemspec"]
+  spec.require_paths = ["lib"]
+end

data/lib/arara/client.rb

@@ -0,0 +1,38 @@
+require_relative "http_client"
+require_relative "resources/auth"
+require_relative "resources/messages"
+require_relative "resources/templates"
+require_relative "resources/contacts"
+require_relative "resources/conversations"
+require_relative "resources/wallet"
+require_relative "resources/numbers"
+require_relative "resources/smart_links"
+require_relative "resources/campaigns"
+require_relative "resources/opt_outs"
+
+module Arara
+  class Client
+    DEFAULT_BASE_URL = "https://api.ararahq.com".freeze
+    DEFAULT_TIMEOUT = 10
+
+    attr_reader :auth, :messages, :templates, :contacts, :conversations, :wallet,
+                :numbers, :smart_links, :campaigns, :opt_outs
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: HttpClient::DEFAULT_MAX_RETRIES)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
+
+      http = HttpClient.new(api_key: api_key, base_url: base_url, timeout: timeout, max_retries: max_retries)
+      @auth = Resources::Auth.new(http)
+      @messages = Resources::Messages.new(http)
+      @templates = Resources::Templates.new(http)
+      @contacts = Resources::Contacts.new(http)
+      @conversations = Resources::Conversations.new(http)
+      @wallet = Resources::Wallet.new(http)
+      @numbers = Resources::Numbers.new(http)
+      @smart_links = Resources::SmartLinks.new(http)
+      @campaigns = Resources::Campaigns.new(http)
+      @opt_outs = Resources::OptOuts.new(http)
+    end
+  end
+end

data/lib/arara/errors.rb

@@ -0,0 +1,87 @@
+module Arara
+  class Error < StandardError
+    attr_reader :status_code, :code, :details, :retry_after
+
+    def initialize(message, code: nil, status_code: nil, details: nil, retry_after: nil)
+      super(message)
+      @code = code
+      @status_code = status_code
+      @details = details
+      @retry_after = retry_after
+    end
+  end
+
+  class BadRequestError < Error; end
+
+  class AuthenticationError < Error; end
+
+  class PaymentRequiredError < Error; end
+
+  class PermissionError < Error; end
+
+  class PlanFeatureLockedError < PermissionError
+    def feature
+      detail("feature")
+    end
+
+    def current_plan
+      detail("currentPlan")
+    end
+
+    def upgrade_to
+      detail("upgradeTo")
+    end
+
+    private
+
+    def detail(key)
+      details.is_a?(Hash) ? details[key] : nil
+    end
+  end
+
+  class NotFoundError < Error; end
+
+  class ConflictError < Error; end
+
+  class UnprocessableEntityError < Error; end
+
+  class RateLimitError < Error; end
+
+  class ServerError < Error; end
+
+  class NetworkError < Error; end
+
+  PLAN_FEATURE_LOCKED = "PLAN_FEATURE_LOCKED".freeze
+  SERVER_ERROR_THRESHOLD = 500
+
+  STATUS_ERRORS = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    402 => PaymentRequiredError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError
+  }.freeze
+
+  module_function
+
+  def error_for_status(status_code, message, code: nil, details: nil, retry_after: nil)
+    klass = error_class_for(status_code, code)
+    klass.new(message, code: code, status_code: status_code, details: details, retry_after: retry_after)
+  end
+
+  def error_class_for(status_code, code)
+    return forbidden_error_class(code) if status_code == 403
+    return STATUS_ERRORS[status_code] if STATUS_ERRORS.key?(status_code)
+
+    status_code && status_code >= SERVER_ERROR_THRESHOLD ? ServerError : Error
+  end
+
+  def forbidden_error_class(code)
+    return AuthenticationError if code.nil? || code.to_s.empty?
+    return PlanFeatureLockedError if code == PLAN_FEATURE_LOCKED
+
+    PermissionError
+  end
+end

data/lib/arara/http_client.rb

@@ -0,0 +1,186 @@
+require "net/http"
+require "uri"
+require "json"
+require "time"
+require_relative "errors"
+
+module Arara
+  class HttpClient
+    DEFAULT_MAX_RETRIES = 3
+    BASE_RETRY_DELAY = 0.5
+    MAX_RETRY_DELAY = 30.0
+    RATE_LIMIT_STATUS = 429
+    SERVER_ERROR_THRESHOLD = 500
+    IDEMPOTENT_METHODS = %i[get put delete].freeze
+
+    def initialize(api_key:, base_url:, timeout: 10, max_retries: DEFAULT_MAX_RETRIES)
+      @api_key = api_key
+      @base_uri = URI.parse(base_url.to_s.sub(%r{/+\z}, ""))
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+
+    def get(path, params: nil)
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: nil, params: nil, idempotency_key: nil)
+      request(:post, path, body: body, params: params, idempotency_key: idempotency_key)
+    end
+
+    def patch(path, body: nil, params: nil)
+      request(:patch, path, body: body, params: params)
+    end
+
+    def put(path, body: nil, params: nil)
+      request(:put, path, body: body, params: params)
+    end
+
+    def delete(path, params: nil)
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: nil, idempotency_key: nil)
+      idempotency_key = normalize_idempotency_key(idempotency_key)
+      attempt = 0
+      loop do
+        response = perform(method, path, body, params, idempotency_key)
+        status = response.code.to_i
+        return handle_success(response) if status < 400
+
+        if retry_allowed?(method, idempotency_key) && retryable?(status) && attempt < @max_retries
+          sleep(retry_delay(attempt, response))
+          attempt += 1
+          next
+        end
+        raise error_from_response(status, response)
+      rescue Timeout::Error, IOError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise NetworkError.new(e.message) if attempt >= @max_retries || !retry_allowed?(method, idempotency_key)
+
+        sleep(retry_delay(attempt, nil))
+        attempt += 1
+      end
+    end
+
+    def perform(method, path, body, params, idempotency_key)
+      uri = build_uri(path, params)
+      request = build_request(method, uri, body, idempotency_key)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.request(request)
+    end
+
+    def build_uri(path, params)
+      uri = @base_uri.dup
+      uri.path = "#{@base_uri.path}#{path}"
+      unless params.nil? || params.empty?
+        cleaned = params.reject { |_, value| value.nil? }
+        uri.query = URI.encode_www_form(cleaned) unless cleaned.empty?
+      end
+      uri
+    end
+
+    def build_request(method, uri, body, idempotency_key)
+      klass = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+      request = klass.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"] = "application/json"
+      request["Idempotency-Key"] = idempotency_key if idempotency_key
+      unless body.nil?
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+      request
+    end
+
+    def handle_success(response)
+      return nil if response.code.to_i == 204
+
+      raw = response.body
+      return nil if raw.nil? || raw.strip.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raise Error.new("Failed to parse Arara API response as JSON")
+    end
+
+    def normalize_idempotency_key(key)
+      normalized = key.to_s.strip
+      normalized.empty? ? nil : normalized
+    end
+
+    def retry_allowed?(method, idempotency_key)
+      IDEMPOTENT_METHODS.include?(method) || !idempotency_key.nil?
+    end
+
+    def retryable?(status)
+      status == RATE_LIMIT_STATUS || status >= SERVER_ERROR_THRESHOLD
+    end
+
+    def retry_delay(attempt, response)
+      after = response && parse_retry_after(response["Retry-After"])
+      return [after, MAX_RETRY_DELAY].min if after
+
+      [BASE_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY].min
+    end
+
+    def parse_retry_after(header)
+      return nil if header.nil? || header.strip.empty?
+
+      seconds = Float(header, exception: false)
+      return seconds if seconds && seconds >= 0
+
+      begin
+        [(Time.httpdate(header) - Time.now).ceil, 0].max
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+
+    def error_from_response(status, response)
+      envelope = parse_error_envelope(response.body)
+      message = envelope[:message] || "Arara API request failed with status #{status}"
+      Arara.error_for_status(
+        status,
+        message,
+        code: envelope[:code],
+        details: envelope[:details],
+        retry_after: parse_retry_after(response["Retry-After"])
+      )
+    end
+
+    def parse_error_envelope(raw)
+      return {} if raw.nil? || raw.strip.empty?
+
+      parsed = JSON.parse(raw)
+      return {} unless parsed.is_a?(Hash)
+
+      inner = parsed["error"]
+      return spring_error(parsed) if inner.is_a?(String)
+      return {} unless inner.is_a?(Hash)
+
+      {
+        code: inner["code"],
+        message: inner["message"],
+        details: inner["details"].is_a?(Hash) ? inner["details"] : nil
+      }
+    rescue JSON::ParserError
+      {}
+    end
+
+    def spring_error(parsed)
+      message = parsed["message"]
+      { message: message.is_a?(String) && !message.strip.empty? ? message : nil }
+    end
+  end
+end

data/lib/arara/page.rb

@@ -0,0 +1,57 @@
+module Arara
+  Pagination = Struct.new(:page, :size, :total_elements, :total_pages, keyword_init: true)
+
+  class Page
+    include Enumerable
+
+    attr_reader :data, :pagination, :raw
+
+    def self.from_data(response)
+      body = require_list(response, "data")
+      meta = body["pagination"].is_a?(Hash) ? body["pagination"] : {}
+      new(
+        data: body["data"],
+        pagination: Pagination.new(
+          page: meta["page"], size: meta["size"],
+          total_elements: meta["totalElements"], total_pages: meta["totalPages"]
+        ),
+        raw: response
+      )
+    end
+
+    def self.from_content(response, page:, size:)
+      body = require_list(response, "content")
+      new(
+        data: body["content"],
+        pagination: Pagination.new(
+          page: page, size: size,
+          total_elements: body["totalElements"], total_pages: body["totalPages"]
+        ),
+        raw: response
+      )
+    end
+
+    def self.require_list(response, field)
+      return response if response.is_a?(Hash) && response[field].is_a?(Array)
+
+      raise Arara::Error.new("Unexpected paginated response from Arara API: missing \"#{field}\" list")
+    end
+    private_class_method :require_list
+
+    def initialize(data:, pagination:, raw: nil)
+      @data = data
+      @pagination = pagination
+      @raw = raw
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def next_page?
+      return false if @pagination.page.nil? || @pagination.total_pages.nil?
+
+      @pagination.page + 1 < @pagination.total_pages
+    end
+  end
+end

data/lib/arara/resources/auth.rb

@@ -0,0 +1,12 @@
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class Auth < BaseResource
+      # Get the user that owns the API key. GET /auth/me (requires an ADMIN key)
+      def me
+        @http.get("/auth/me")
+      end
+    end
+  end
+end

data/lib/arara/resources/base_resource.rb

@@ -0,0 +1,18 @@
+require "securerandom"
+
+module Arara
+  module Resources
+    class BaseResource
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      def idempotency_key_or_generate(key)
+        normalized = key.to_s.strip
+        normalized.empty? ? SecureRandom.uuid : normalized
+      end
+    end
+  end
+end

data/lib/arara/resources/campaigns.rb

@@ -0,0 +1,38 @@
+require "securerandom"
+require_relative "base_resource"
+require_relative "../page"
+
+module Arara
+  module Resources
+    class Campaigns < BaseResource
+      DEFAULT_PAGE_SIZE = 20
+
+      # Create a campaign. POST /v1/campaigns
+      def create(payload, idempotency_key: nil)
+        key = idempotency_key_or_generate(idempotency_key)
+        @http.post("/v1/campaigns", body: payload, idempotency_key: key)
+      end
+
+      # List campaigns. GET /v1/campaigns. Returns an Arara::Page.
+      def list(page: 0, size: DEFAULT_PAGE_SIZE, status: nil)
+        response = @http.get("/v1/campaigns", params: { "page" => page, "size" => size, "status" => status })
+        Arara::Page.from_content(response, page: page, size: size)
+      end
+
+      # Estimate campaign cost. GET /v1/campaigns/estimate
+      def estimate(template_name:, count:)
+        @http.get("/v1/campaigns/estimate", params: { "templateName" => template_name, "count" => count })
+      end
+
+      # Get a campaign by id. GET /v1/campaigns/{id}
+      def get(id)
+        @http.get("/v1/campaigns/#{id}")
+      end
+
+      # Cancel a campaign. POST /v1/campaigns/{id}/cancel
+      def cancel(id)
+        @http.post("/v1/campaigns/#{id}/cancel")
+      end
+    end
+  end
+end

data/lib/arara/resources/contacts.rb

@@ -0,0 +1,52 @@
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class Contacts < BaseResource
+      # List contacts. GET /v1/contacts
+      def list(page: 0, size: 20, q: nil, lifecycle: nil)
+        @http.get("/v1/contacts", params: { "page" => page, "size" => size, "q" => q, "lifecycle" => lifecycle })
+      end
+
+      # Import a batch of contacts. POST /v1/contacts/batch
+      def import_batch(contacts)
+        @http.post("/v1/contacts/batch", body: contacts)
+      end
+
+      # Get contact lifecycle stats. GET /v1/contacts/stats
+      def stats
+        @http.get("/v1/contacts/stats")
+      end
+
+      # List reactivation candidates. GET /v1/contacts/reactivation
+      def reactivation_candidates(limit: 100)
+        @http.get("/v1/contacts/reactivation", params: { "limit" => limit })
+      end
+
+      # List distinct contact tags. GET /v1/contacts/tags
+      def list_tags
+        @http.get("/v1/contacts/tags")
+      end
+
+      # Get a contact by phone. GET /v1/contacts/{phone}
+      def get(phone)
+        @http.get("/v1/contacts/#{phone}")
+      end
+
+      # Update a contact by phone. PATCH /v1/contacts/{phone}
+      def update(phone, name: nil, email: nil, tags: nil)
+        payload = {
+          "name" => name,
+          "email" => email,
+          "tags" => tags
+        }.reject { |_, value| value.nil? }
+        @http.patch("/v1/contacts/#{phone}", body: payload)
+      end
+
+      # List a contact's recent messages. GET /v1/contacts/{phone}/messages
+      def messages(phone, limit: 30)
+        @http.get("/v1/contacts/#{phone}/messages", params: { "limit" => limit })
+      end
+    end
+  end
+end

data/lib/arara/resources/conversations.rb

@@ -0,0 +1,39 @@
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class Conversations < BaseResource
+      # List conversations. GET /v1/conversations
+      def list(status: nil, lead_status: nil, page: 0, size: 20)
+        @http.get("/v1/conversations", params: {
+          "status" => status, "leadStatus" => lead_status, "page" => page, "size" => size
+        })
+      end
+
+      # Get lead status stats. GET /v1/conversations/lead-stats
+      def lead_stats
+        @http.get("/v1/conversations/lead-stats")
+      end
+
+      # List messages in a conversation. GET /v1/conversations/{conversationId}/messages
+      def messages(conversation_id, page: 0, size: 50)
+        @http.get("/v1/conversations/#{conversation_id}/messages", params: { "page" => page, "size" => size })
+      end
+
+      # Reply within an open conversation window. POST /v1/conversations/reply
+      def reply(conversation_id:, body:)
+        @http.post("/v1/conversations/reply", body: { "conversationId" => conversation_id, "body" => body })
+      end
+
+      # Update a conversation status. PATCH /v1/conversations/{conversationId}/status
+      def update_status(conversation_id, status)
+        @http.patch("/v1/conversations/#{conversation_id}/status", body: { "status" => status })
+      end
+
+      # Check the 24h window status for phones. POST /v1/conversations/window-status
+      def window_status(phones)
+        @http.post("/v1/conversations/window-status", body: { "phones" => phones })
+      end
+    end
+  end
+end

data/lib/arara/resources/messages.rb

@@ -0,0 +1,69 @@
+require "securerandom"
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class Messages < BaseResource
+      BASE_PATH = "/v1/messages".freeze
+      MAX_BATCH_SIZE = 1000
+
+      PAYLOAD_FIELDS = {
+        receiver: "receiver",
+        sender: "sender",
+        type: "type",
+        template_name: "templateName",
+        template_variables: "templateVariables",
+        body: "body",
+        interactive: "interactive",
+        charge: "charge",
+        location: "location",
+        reaction: "reaction",
+        reply_to: "replyTo",
+        smart_link_param: "smartLinkParam",
+        smart_link_url: "smartLinkUrl",
+        scheduled_at: "scheduled_at",
+        mode: "mode",
+        media_url: "media_url"
+      }.freeze
+
+      # Send a WhatsApp message. POST /v1/messages
+      # An Idempotency-Key is generated when omitted and reused on every retry.
+      def send_message(receiver:, idempotency_key: nil, **fields)
+        unknown = fields.keys - PAYLOAD_FIELDS.keys
+        raise ArgumentError, "unknown message fields: #{unknown.join(', ')}" unless unknown.empty?
+
+        payload = build_payload(fields.merge(receiver: receiver))
+        @http.post(BASE_PATH, body: payload, idempotency_key: idempotency_key_or_generate(idempotency_key))
+      end
+
+      alias deliver send_message
+
+      # Send the same template to up to 1000 receivers. POST /v1/messages/batch
+      def send_batch(template_name:, messages:, idempotency_key: nil)
+        raise ArgumentError, "messages must not be empty" if messages.nil? || messages.empty?
+        raise ArgumentError, "messages must have at most #{MAX_BATCH_SIZE} items" if messages.size > MAX_BATCH_SIZE
+
+        payload = { "templateName" => template_name, "messages" => messages }
+        @http.post("#{BASE_PATH}/batch", body: payload, idempotency_key: idempotency_key_or_generate(idempotency_key))
+      end
+
+      # Get a message by id. GET /v1/messages/{id}
+      def get(id)
+        @http.get("#{BASE_PATH}/#{id}")
+      end
+
+      # List the messages of a batch. GET /v1/messages?batchId=
+      def list_by_batch(batch_id)
+        @http.get(BASE_PATH, params: { "batchId" => batch_id })
+      end
+
+      private
+
+      def build_payload(fields)
+        fields.each_with_object({}) do |(key, value), payload|
+          payload[PAYLOAD_FIELDS.fetch(key)] = value unless value.nil?
+        end
+      end
+    end
+  end
+end

data/lib/arara/resources/numbers.rb

@@ -0,0 +1,57 @@
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class Numbers < BaseResource
+      BASE_PATH = "/v1/organizations/me/numbers".freeze
+
+      # List numbers with plan slot info. GET /v1/organizations/me/numbers
+      def list
+        @http.get(BASE_PATH)
+      end
+
+      # Update a number. PATCH /v1/organizations/me/numbers/{id}
+      def update(id, alias_name: nil, is_default: nil, name: nil, description: nil)
+        payload = {
+          "alias" => alias_name,
+          "isDefault" => is_default,
+          "name" => name,
+          "description" => description
+        }.reject { |_, value| value.nil? }
+        @http.patch("#{BASE_PATH}/#{id}", body: payload)
+      end
+
+      # Deactivate a number. DELETE /v1/organizations/me/numbers/{id}
+      def delete(id)
+        @http.delete("#{BASE_PATH}/#{id}")
+      end
+
+      # Request a new dedicated number. POST /v1/organizations/me/numbers/request
+      def request(reason: nil, expected_volume: nil, area_code: nil, display_name: nil, profile_picture_url: nil)
+        payload = {
+          "reason" => reason,
+          "expectedVolume" => expected_volume,
+          "areaCode" => area_code,
+          "displayName" => display_name,
+          "profilePictureUrl" => profile_picture_url
+        }.reject { |_, value| value.nil? }
+        @http.post("#{BASE_PATH}/request", body: payload)
+      end
+
+      # List number provisioning requests. GET /v1/organizations/me/numbers/requests
+      def list_requests
+        @http.get("#{BASE_PATH}/requests")
+      end
+
+      # Sync a number's health from the provider. POST /v1/organizations/me/numbers/{id}/sync
+      def sync(id)
+        @http.post("#{BASE_PATH}/#{id}/sync")
+      end
+
+      # Get warming recommendations for a number. GET /v1/organizations/me/numbers/{id}/warming
+      def warming(id)
+        @http.get("#{BASE_PATH}/#{id}/warming")
+      end
+    end
+  end
+end

data/lib/arara/resources/opt_outs.rb

@@ -0,0 +1,31 @@
+require "uri"
+require_relative "base_resource"
+
+module Arara
+  module Resources
+    class OptOuts < BaseResource
+      BASE_PATH = "/v1/opt-outs".freeze
+
+      # List opt-outs. GET /v1/opt-outs (requires an ADMIN key)
+      def list
+        @http.get(BASE_PATH)
+      end
+
+      # Opt a phone out. POST /v1/opt-outs (requires an ADMIN key)
+      def create(phone:, reason: nil)
+        payload = { "phone" => phone, "reason" => reason }.reject { |_, value| value.nil? }
+        @http.post(BASE_PATH, body: payload)
+      end
+
+      # Get the opt-out of a phone. GET /v1/opt-outs/{phone}
+      def get(phone)
+        @http.get("#{BASE_PATH}/#{URI.encode_www_form_component(phone)}")
+      end
+
+      # Remove the opt-out of a phone. DELETE /v1/opt-outs/{phone}
+      def delete(phone)
+        @http.delete("#{BASE_PATH}/#{URI.encode_www_form_component(phone)}")
+      end
+    end
+  end
+end

data/lib/arara/resources/smart_links.rb

@@ -0,0 +1,42 @@
+require_relative "base_resource"
+require_relative "../page"
+
+module Arara
+  module Resources
+    class SmartLinks < BaseResource
+      BASE_PATH = "/v1/smart-links/whatsapp".freeze
+      DEFAULT_PAGE_SIZE = 50
+
+      # Create a WhatsApp smart link. POST /v1/smart-links/whatsapp
+      def create(name:, phone_number:, default_text: nil, qr_code_color: nil)
+        payload = {
+          "name" => name,
+          "phoneNumber" => phone_number,
+          "defaultText" => default_text,
+          "qrCodeColor" => qr_code_color
+        }.reject { |_, value| value.nil? }
+        @http.post(BASE_PATH, body: payload)
+      end
+
+      # Update a WhatsApp smart link. PUT /v1/smart-links/whatsapp/{id}
+      def update(id, name: nil, default_text: nil, qr_code_color: nil)
+        payload = {
+          "name" => name,
+          "defaultText" => default_text,
+          "qrCodeColor" => qr_code_color
+        }.reject { |_, value| value.nil? }
+        @http.put("#{BASE_PATH}/#{id}", body: payload)
+      end
+
+      # List WhatsApp smart links. GET /v1/smart-links/whatsapp. Returns an Arara::Page.
+      def list(page: 0, size: DEFAULT_PAGE_SIZE)
+        Arara::Page.from_data(@http.get(BASE_PATH, params: { "page" => page, "size" => size }))
+      end
+
+      # Get smart link click stats. GET /v1/smart-links/whatsapp/{id}/stats
+      def stats(id)
+        @http.get("#{BASE_PATH}/#{id}/stats")
+      end
+    end
+  end
+end

data/lib/arara/resources/templates.rb

@@ -0,0 +1,61 @@
+require_relative "base_resource"
+require_relative "../page"
+
+module Arara
+  module Resources
+    class Templates < BaseResource
+      BASE_PATH = "/v1/templates".freeze
+      DEFAULT_PAGE_SIZE = 50
+      DEFAULT_PERIOD = "30d".freeze
+
+      # List templates. GET /v1/templates. Returns an Arara::Page.
+      def list(name: nil, status: nil, page: 0, size: DEFAULT_PAGE_SIZE)
+        response = @http.get(BASE_PATH, params: { "name" => name, "status" => status, "page" => page, "size" => size })
+        Arara::Page.from_data(response)
+      end
+
+      # Find a template by exact name, walking every page of the filtered list. Returns nil when absent.
+      def find_by_name(name)
+        page_number = 0
+        loop do
+          page = list(name: name, page: page_number)
+          match = page.find { |template| template["name"] == name }
+          return match if match
+          return nil unless page.next_page?
+
+          page_number += 1
+        end
+      end
+
+      # Create a template for Meta approval. POST /v1/templates
+      def create(payload)
+        @http.post(BASE_PATH, body: payload)
+      end
+
+      # Get a template by id (UUID). GET /v1/templates/{id}
+      def get(id)
+        @http.get("#{BASE_PATH}/#{id}")
+      end
+
+      # Get template status from provider. GET /v1/templates/{id}/status
+      def get_status(id)
+        @http.get("#{BASE_PATH}/#{id}/status")
+      end
+
+      # Delete a template by id (UUID). DELETE /v1/templates/{id}
+      def delete(id)
+        @http.delete("#{BASE_PATH}/#{id}")
+      end
+
+      # Analytics of all templates. GET /v1/templates/analytics
+      def analytics(period: DEFAULT_PERIOD)
+        @http.get("#{BASE_PATH}/analytics", params: { "period" => period })
+      end
+
+      # Analytics of one template. GET /v1/templates/{id}/analytics
+      def template_analytics(id, period: DEFAULT_PERIOD)
+        @http.get("#{BASE_PATH}/#{id}/analytics", params: { "period" => period })
+      end
+    end
+  end
+end

data/lib/arara/resources/wallet.rb

@@ -0,0 +1,31 @@
+require_relative "base_resource"
+require_relative "../page"
+
+module Arara
+  module Resources
+    class Wallet < BaseResource
+      DEFAULT_PAGE_SIZE = 20
+
+      # List wallet transactions. GET /v1/wallet/transactions. Returns an Arara::Page.
+      def transactions(page: 0, size: DEFAULT_PAGE_SIZE)
+        response = @http.get("/v1/wallet/transactions", params: { "page" => page, "size" => size })
+        Arara::Page.from_content(response, page: page, size: size)
+      end
+
+      # Get auto-recharge settings. GET /v1/wallet/auto-recharge
+      def get_auto_recharge
+        @http.get("/v1/wallet/auto-recharge")
+      end
+
+      # Update auto-recharge settings. PATCH /v1/wallet/auto-recharge
+      def update_auto_recharge(enabled: nil, threshold: nil, amount: nil)
+        payload = {
+          "enabled" => enabled,
+          "threshold" => threshold,
+          "amount" => amount
+        }.reject { |_, value| value.nil? }
+        @http.patch("/v1/wallet/auto-recharge", body: payload)
+      end
+    end
+  end
+end

data/lib/arara/version.rb

@@ -0,0 +1,3 @@
+module Arara
+  VERSION = "1.0.0".freeze
+end

data/lib/arara.rb

@@ -0,0 +1,7 @@
+require_relative "arara/version"
+require_relative "arara/errors"
+require_relative "arara/page"
+require_relative "arara/client"
+
+module Arara
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: ararahq
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- AraraHQ
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies: []
+description: 'Ruby client for the AraraHQ API: messages, templates, contacts, conversations,
+  campaigns, wallet, numbers, smart links and opt-outs. Zero runtime dependencies.'
+email:
+- dev@ararahq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- arara.gemspec
+- lib/arara.rb
+- lib/arara/client.rb
+- lib/arara/errors.rb
+- lib/arara/http_client.rb
+- lib/arara/page.rb
+- lib/arara/resources/auth.rb
+- lib/arara/resources/base_resource.rb
+- lib/arara/resources/campaigns.rb
+- lib/arara/resources/contacts.rb
+- lib/arara/resources/conversations.rb
+- lib/arara/resources/messages.rb
+- lib/arara/resources/numbers.rb
+- lib/arara/resources/opt_outs.rb
+- lib/arara/resources/smart_links.rb
+- lib/arara/resources/templates.rb
+- lib/arara/resources/wallet.rb
+- lib/arara/version.rb
+homepage: https://ararahq.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://ararahq.com
+  source_code_uri: https://github.com/ararahq/arara-ruby-sdk
+  changelog_uri: https://github.com/ararahq/arara-ruby-sdk/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the AraraHQ WhatsApp API.
+test_files: []