walinko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fab8530917c42b499678f18a29388a6a022aa95db4244b52aab4521f86769103
+  data.tar.gz: 7229de0b6795beb1cad9e3f3ce3194e48a008029c0b0ea085b035a7df8bc0540
+SHA512:
+  metadata.gz: 9632be9a36b8603403f9bb32007856f0524a6d107ad917103f6e7b3303eebabbd131a49a1269664be6a5a49bcb4c416b9d6cd47c02768dbc35ec0344f6b730dd
+  data.tar.gz: 5f86b31f8b0e9d1aec9fafc54e1d14db11c3abb23bc64e8424415b221f75741b5a9450d2fe726ca773344bddf8993e130a5626b2a9e867f45bbb1a99fef9d0a6

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog — walinko (Ruby)
+
+All notable changes to this gem are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-01
+
+First publishable release. Targets Walinko public API
+`POST /api/v1/public/messages` and `GET /api/v1/public/messages/:tracking_id`.
+
+### Added
+- `Walinko::Client.new(api_key:, base_url:, timeout:, open_timeout:,
+  max_retries:, logger:)`.
+- `client.messages.send` (sync) returning `Walinko::SyncResult`.
+- `client.messages.enqueue` (async) returning `Walinko::AsyncJob`.
+- `client.messages.fetch(tracking_id)` returning `Walinko::MessageStatus`.
+- `client.messages.wait_until_done(tracking_id, timeout:, interval:)` —
+  polls until the delivery reaches a terminal state, raises
+  `Walinko::TimeoutError` if it doesn't.
+- Typed exception hierarchy (`Walinko::Error` →
+  `Walinko::ApiError` / `Walinko::ConnectionError`), with specialized
+  classes for every documented `error_code` (`AuthenticationError`,
+  `BadRequestError`, `ForbiddenError`, `TenantSuspendedError`,
+  `QuotaExceededError`, `NotFoundError`, `ConflictError`,
+  `DeviceDisconnectedError`, `IdempotencyConflictError`,
+  `ValidationError`, `RateLimitError`, `ServerError`,
+  `TimeoutError`).
+- Automatic `Idempotency-Key` generation for `send` / `enqueue` (use
+  `idempotency_key:` to override).
+- Idempotent retry policy: network errors, 429 (honouring `Retry-After`),
+  and 5xx are retried up to `max_retries` with exponential backoff +
+  jitter. The same `Idempotency-Key` is reused on every retry.
+- `client.last_rate_limit` and `client.last_request_id` reflect the
+  most recent response's `X-RateLimit-*` and `X-Request-Id` headers.
+- `Idempotent-Replayed: true` is surfaced on `SyncResult#idempotent_replayed`
+  / `AsyncJob#idempotent_replayed`.
+
+### Internal
+- 100% stdlib transport — no Faraday / HTTPX dependency.
+- Ruby 3.1+ required.
+- 66 RSpec examples covering every documented error code, retry path,
+  and idempotency edge case.

data/README.md

@@ -0,0 +1,136 @@
+# walinko (Ruby)
+
+Official Ruby client for the [Walinko](https://walinko.com) public API.
+
+Send transactional WhatsApp messages from your Ruby app with idempotent
+retries, structured errors, and a tiny dependency footprint (Ruby stdlib
+only).
+
+* Ruby 3.1+
+* Zero runtime dependencies (only `net/http` + `json` from stdlib)
+* MIT licensed
+
+## Install
+
+```bash
+gem install walinko
+```
+
+…or in a `Gemfile`:
+
+```ruby
+gem 'walinko', '~> 0.1'
+```
+
+## Quick start
+
+```ruby
+require 'walinko'
+
+client = Walinko::Client.new(
+  api_key:     ENV.fetch('WALINKO_API_KEY'),
+  base_url:    'https://api.walinko.com',  # optional
+  timeout:     30,                          # optional, seconds
+  max_retries: 2                            # optional
+)
+
+# Sync send — blocks until the message is delivered (or 504 timeout).
+result = client.messages.send(
+  device_id:     1,
+  template_id:   12,
+  variant_index: 0,                              # optional, nil = primary
+  phone:         '+8801617738431',
+  variables:     { name: 'Kazi', dist: 'Dhaka' }
+)
+
+puts result.tracking_id     # tx_...
+puts result.wa_message_id   # 3EB0...
+puts result.status          # "sent"
+
+# Async enqueue + poll.
+job = client.messages.enqueue(
+  device_id: 1, template_id: 12,
+  phone: '+8801617738431',
+  variables: { name: 'Kazi', dist: 'Dhaka' }
+)
+
+final = client.messages.wait_until_done(job.tracking_id, timeout: 60)
+puts final.status           # "sent" | "failed"
+```
+
+## Looking up a delivery
+
+```ruby
+status = client.messages.fetch('tx_767fd2faca0f4037b2a2bbcb91e5735f')
+status.sent?         # true / false
+status.error_code    # nil if sent, e.g. "phone_not_on_whatsapp" if failed
+status.wa_message_id # WhatsApp's id, set on success
+status.created_at    # Time
+status.sent_at       # Time, nil while pending
+```
+
+## Errors
+
+Every error is a subclass of `Walinko::Error`. See
+[`docs/error-codes.md`](../../docs/error-codes.md) for the full mapping.
+
+```ruby
+begin
+  client.messages.send(...)
+rescue Walinko::RateLimitError => e
+  sleep e.retry_after
+  retry
+rescue Walinko::ValidationError => e
+  warn e.fields  # { phone: ['must match pattern …'] }
+rescue Walinko::DeviceDisconnectedError
+  # tell the user to reconnect their device
+rescue Walinko::Error => e
+  Rails.logger.error("Walinko send failed: #{e.message}")
+end
+```
+
+## Idempotency
+
+The SDK auto-generates a UUID `Idempotency-Key` for every `send` / `enqueue`
+call so retries are safe end-to-end. Pass `idempotency_key:` to set your own
+(e.g. tying a send to your domain object).
+
+## Retries
+
+The SDK auto-retries idempotently on:
+
+| Trigger                 | Behaviour                                       |
+| ----------------------- | ----------------------------------------------- |
+| Network errors          | Exponential backoff with jitter                 |
+| HTTP 429                | Honours `Retry-After` (capped at 60s)           |
+| HTTP 500/502/503/504    | Exponential backoff with jitter                 |
+
+`max_retries` (default 2) controls how many additional attempts are made.
+4xx responses (other than 429) are surfaced immediately — the request is
+malformed or the server has rejected it on application grounds, and no
+amount of retrying will help.
+
+## Rate limits
+
+The server enforces 30 req/min/key (sliding window). The SDK exposes the
+latest known window state via:
+
+```ruby
+client.last_rate_limit
+# => #<Walinko::RateLimitSnapshot limit=30 remaining=29>
+client.last_request_id
+# => "req_4f2c..."  (handy for support tickets)
+```
+
+## Development
+
+```bash
+cd sdks/ruby
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](../../LICENSE)

data/lib/walinko/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Walinko
+  # Immutable configuration captured by `Walinko::Client.new`. Validates
+  # required fields and applies defaults.
+  class Configuration
+    DEFAULT_BASE_URL     = 'https://api.walinko.com'
+    DEFAULT_TIMEOUT      = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_MAX_RETRIES  = 2
+
+    attr_reader :api_key, :base_url, :timeout, :open_timeout,
+                :max_retries, :logger
+
+    # @param api_key      [String]   required, e.g. "walk_live_<keyId>.<secret>"
+    # @param base_url     [String]   defaults to "https://api.walinko.com"
+    # @param timeout      [Integer]  per-request read timeout in seconds
+    # @param open_timeout [Integer]  TCP/TLS connection-setup timeout in seconds
+    # @param max_retries  [Integer]  retries on idempotent failures (network, 429, 5xx)
+    # @param logger       [#info,#warn,#error] optional structured logger
+    def initialize(api_key:,
+                   base_url:     DEFAULT_BASE_URL,
+                   timeout:      DEFAULT_TIMEOUT,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT,
+                   max_retries:  DEFAULT_MAX_RETRIES,
+                   logger:       nil)
+      raise ArgumentError, 'api_key is required' if api_key.nil? || api_key.to_s.empty?
+      raise ArgumentError, 'base_url is required' if base_url.nil? || base_url.to_s.empty?
+      raise ArgumentError, 'timeout must be > 0' if timeout.to_i <= 0
+      raise ArgumentError, 'open_timeout must be > 0' if open_timeout.to_i <= 0
+      raise ArgumentError, 'max_retries must be >= 0' if max_retries.to_i.negative?
+
+      @api_key      = api_key.to_s
+      @base_url     = base_url.to_s.sub(%r{/+$}, '')
+      @timeout      = timeout.to_i
+      @open_timeout = open_timeout.to_i
+      @max_retries  = max_retries.to_i
+      @logger       = logger
+    end
+  end
+end

data/lib/walinko/errors.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Walinko
+  # Base class for every exception raised by the SDK. Catch this to handle
+  # anything Walinko throws.
+  class Error < StandardError; end
+
+  # Raised when we couldn't reach the API at all (DNS failure, connection
+  # refused, TLS handshake failed, socket reset, etc.). These are retried
+  # automatically up to `max_retries`; if you see one, the retry budget was
+  # exhausted.
+  class ConnectionError < Error
+    attr_reader :cause_class
+
+    def initialize(message, cause_class: nil)
+      super(message)
+      @cause_class = cause_class
+    end
+  end
+
+  # Base class for every error response returned by the API. Carries the
+  # full diagnostic payload — HTTP status, server-side `error_code`, the
+  # `X-Request-Id` (handy for support tickets), and the optional `details`
+  # blob.
+  class ApiError < Error
+    attr_reader :http_status, :error_code, :request_id, :details, :body
+
+    def initialize(message, http_status:, error_code: nil, request_id: nil,
+                   details: nil, body: nil)
+      super(message)
+      @http_status = http_status
+      @error_code  = error_code
+      @request_id  = request_id
+      @details     = details || {}
+      @body        = body
+    end
+
+    def inspect
+      parts = [self.class.name, "status=#{http_status}"]
+      parts << "code=#{error_code}" if error_code
+      parts << "request_id=#{request_id}" if request_id
+      "#<#{parts.join(' ')} message=#{message.inspect}>"
+    end
+  end
+
+  # 401 — missing / malformed / expired / revoked / unknown API key.
+  # All five are returned with the same generic message on purpose.
+  class AuthenticationError < ApiError; end
+
+  # 400 — malformed request, unknown body shape, or `variant_index` out of
+  # range. Validation errors are raised as `ValidationError` instead.
+  class BadRequestError < ApiError; end
+
+  # 403 — generic forbidden. See specialized subclasses below.
+  class ForbiddenError < ApiError; end
+
+  # 403 + `error_code: tenant_suspended` — tenant account is suspended or
+  # scheduled for deletion.
+  class TenantSuspendedError < ForbiddenError; end
+
+  # 403 + `error_code: quota_exceeded` — tenant has hit its monthly /
+  # daily / balance message limit. `details[:resets_at]` (when present)
+  # tells you when the limit resets.
+  class QuotaExceededError < ForbiddenError; end
+
+  # 404 — device, template, or tracking id not found for this tenant.
+  class NotFoundError < ApiError; end
+
+  # 409 — generic conflict. See specialized subclasses below.
+  class ConflictError < ApiError; end
+
+  # 409 + `error_code: device_disconnected` — device session is not
+  # connected. Reconnect from the dashboard, then retry.
+  class DeviceDisconnectedError < ConflictError; end
+
+  # 409 + `error_code: idempotency_conflict` — `Idempotency-Key` was
+  # previously used with a *different* payload. Use a new key.
+  class IdempotencyConflictError < ConflictError; end
+
+  # 422 — semantic validation failure. For DTO validation errors (the
+  # default class-validator path), `#fields` returns a `{field => [reason,
+  # ...]}` map. For `phone_not_on_whatsapp` the map is empty and the
+  # reason is in `#message`.
+  class ValidationError < ApiError
+    # @return [Hash{String => Array<String>}]
+    def fields
+      f = details[:fields] || details['fields']
+      f.is_a?(Hash) ? f : {}
+    end
+  end
+
+  # 429 — sliding-window rate limit (default 30 req/min/key) exceeded.
+  # `#retry_after` is the recommended sleep in seconds (parsed from
+  # `Retry-After` header).
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  # 5xx — server-side failure. Outcome of the underlying send may or may
+  # not have happened; replay with the same `Idempotency-Key` is safe.
+  class ServerError < ApiError; end
+
+  # 504 — WhatsApp send did not complete within the server's 15s window.
+  # Outcome unknown; replay with the same `Idempotency-Key` is safe.
+  class TimeoutError < ApiError; end
+
+  # Internal: maps an HTTP status + server `error_code` to one of the
+  # typed exception classes above. Public so users can introspect the
+  # mapping in tests if they want.
+  module ErrorMapping
+    BY_HTTP_STATUS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => ValidationError,
+      429 => RateLimitError,
+      504 => TimeoutError
+    }.freeze
+
+    BY_ERROR_CODE = {
+      'tenant_suspended' => TenantSuspendedError,
+      'quota_exceeded' => QuotaExceededError,
+      'device_disconnected' => DeviceDisconnectedError,
+      'idempotency_conflict' => IdempotencyConflictError
+    }.freeze
+
+    # @return [Class<ApiError>]
+    def self.for(http_status:, error_code: nil)
+      BY_ERROR_CODE[error_code.to_s] ||
+        BY_HTTP_STATUS[http_status] ||
+        (http_status.between?(500, 599) ? ServerError : ApiError)
+    end
+  end
+end

data/lib/walinko/http_client.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'errors'
+require_relative 'result'
+
+module Walinko
+  # Internal HTTP transport. Owns the wire format (JSON in/out, header
+  # naming), retry policy, and error mapping. The `Messages` resource is
+  # the only consumer.
+  #
+  # Public methods are documented but treat anything outside `request` as
+  # internal — minor versions may refactor.
+  class HttpClient
+    Response = Struct.new(
+      :status,
+      :body,
+      :request_id,
+      :rate_limit,
+      :idempotent_replayed,
+      keyword_init: true
+    )
+
+    # Statuses we consider transient and retry automatically.
+    RETRYABLE_HTTP_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    # Backoff curve (seconds). Index = attempt number (0 = first retry).
+    # Caps at the last entry.
+    BACKOFF_SECONDS = [0.25, 0.75, 1.75, 3.75].freeze
+
+    # Cap on `Retry-After` honoring — don't let the server make us sleep
+    # forever.
+    MAX_RETRY_AFTER_SECONDS = 60
+
+    attr_reader :last_request_id, :last_rate_limit
+
+    # @param config [Walinko::Configuration]
+    def initialize(config)
+      @config = config
+    end
+
+    # Issues an HTTP request with the configured retry policy.
+    #
+    # @param method [Symbol] :get / :post
+    # @param path   [String] e.g. "/api/v1/public/messages"
+    # @param body   [Hash, nil] JSON-encoded into the request body
+    # @param headers [Hash{String => String}] extra headers to merge
+    # @return [Response]
+    # @raise [Walinko::ApiError, Walinko::ConnectionError]
+    def request(method:, path:, body: nil, headers: {})
+      attempt = 0
+
+      loop do
+        result = perform(method: method, path: path, body: body, headers: headers)
+        return result if result.is_a?(Response)
+
+        # `result` is a retryable error (Exception subclass) — decide
+        # whether to retry.
+        attempt += 1
+        raise result if attempt > @config.max_retries
+
+        sleep_for = sleep_seconds(result, attempt)
+        log(:warn,
+            "retrying after #{sleep_for}s (attempt #{attempt}/#{@config.max_retries}): #{result.message}")
+        sleep(sleep_for) if sleep_for.positive?
+      end
+    end
+
+    private
+
+    # Returns either a `Response` (success) or an Exception instance
+    # representing a retryable failure. Non-retryable failures are
+    # raised directly.
+    def perform(method:, path:, body:, headers:)
+      uri = URI.join("#{@config.base_url}/", path.sub(%r{^/}, ''))
+      req = build_request(method, uri, body: body, headers: headers)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.read_timeout = @config.timeout
+      http.open_timeout = @config.open_timeout
+      http.write_timeout = @config.timeout if http.respond_to?(:write_timeout=)
+
+      raw = http.request(req)
+      handle_response(raw)
+    rescue *connection_error_classes => e
+      ConnectionError.new("#{e.class}: #{e.message}", cause_class: e.class)
+    rescue ConnectionError => e
+      e
+    end
+
+    # Network/timeout errors that should map to ConnectionError and be
+    # retried.
+    def connection_error_classes
+      [
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH,  Errno::ETIMEDOUT,  Errno::EPIPE,
+        SocketError, IOError,
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+        OpenSSL::SSL::SSLError,
+        EOFError
+      ]
+    end
+
+    def build_request(method, uri, body:, headers:)
+      request_class =
+        case method
+        when :get  then Net::HTTP::Get
+        when :post then Net::HTTP::Post
+        else raise ArgumentError, "Unsupported method #{method.inspect}"
+        end
+
+      req = request_class.new(uri.request_uri)
+      req['Authorization'] = "Bearer #{@config.api_key}"
+      req['Accept']        = 'application/json'
+      headers.each { |k, v| req[k] = v unless v.nil? }
+      if body
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body)
+      end
+      req
+    end
+
+    def handle_response(raw)
+      status = raw.code.to_i
+      request_id = raw['X-Request-Id'] || raw['x-request-id']
+      rate_limit = parse_rate_limit(raw)
+      replayed   = raw['Idempotent-Replayed'] == 'true'
+
+      @last_request_id = request_id
+      @last_rate_limit = rate_limit
+
+      parsed = safe_parse_json(raw.body)
+
+      if (200..299).cover?(status)
+        return Response.new(
+          status: status,
+          body: parsed,
+          request_id: request_id,
+          rate_limit: rate_limit,
+          idempotent_replayed: replayed
+        )
+      end
+
+      build_api_error(status, parsed, raw)
+    end
+
+    # Builds the typed exception. For retryable statuses returns the
+    # exception (caller decides whether to retry); for non-retryable
+    # statuses raises immediately.
+    def build_api_error(status, body, raw)
+      message    = (body.is_a?(Hash) && body['message']) || "HTTP #{status}"
+      error_code = body.is_a?(Hash) ? body['error_code'] : nil
+      details    = body.is_a?(Hash) ? body['details']    : nil
+      request_id = raw['X-Request-Id'] || raw['x-request-id']
+
+      klass = ErrorMapping.for(http_status: status, error_code: error_code)
+
+      err =
+        if klass <= RateLimitError
+          retry_after = parse_retry_after(raw)
+          klass.new(message,
+                    http_status: status, error_code: error_code,
+                    request_id: request_id, details: stringify_keys(details),
+                    body: body, retry_after: retry_after)
+        else
+          klass.new(message,
+                    http_status: status, error_code: error_code,
+                    request_id: request_id, details: stringify_keys(details),
+                    body: body)
+        end
+
+      return err if RETRYABLE_HTTP_STATUSES.include?(status)
+
+      raise err
+    end
+
+    def parse_rate_limit(raw)
+      limit_h     = raw['X-RateLimit-Limit']
+      remaining_h = raw['X-RateLimit-Remaining']
+      return nil if limit_h.nil? && remaining_h.nil?
+
+      RateLimitSnapshot.new(
+        limit: limit_h&.to_i,
+        remaining: remaining_h&.to_i
+      )
+    end
+
+    def parse_retry_after(raw)
+      v = raw['Retry-After']
+      return nil if v.nil?
+
+      v.to_i.positive? ? v.to_i : nil
+    end
+
+    def safe_parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def stringify_keys(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+
+    def sleep_seconds(error, attempt)
+      if error.is_a?(RateLimitError) && error.retry_after
+        return [error.retry_after, MAX_RETRY_AFTER_SECONDS].min
+      end
+
+      base = BACKOFF_SECONDS[[attempt - 1, BACKOFF_SECONDS.size - 1].min]
+      base + (rand * 0.1) # tiny jitter
+    end
+
+    def log(level, message)
+      logger = @config.logger
+      return unless logger.respond_to?(level)
+
+      logger.public_send(level, "[walinko] #{message}")
+    end
+  end
+end

data/lib/walinko/messages.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'errors'
+require_relative 'http_client'
+require_relative 'result'
+
+module Walinko
+  # The `messages` resource on `Walinko::Client`. Wraps:
+  #
+  #   POST /api/v1/public/messages
+  #   GET  /api/v1/public/messages/:tracking_id
+  class Messages
+    SEND_PATH = '/api/v1/public/messages'
+
+    # @api private
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    # Synchronous send: blocks until the WhatsApp gateway acknowledges
+    # delivery (or the server's 15s timeout fires).
+    #
+    # @param device_id      [Integer] required
+    # @param template_id    [Integer] required
+    # @param phone          [String]  required, E.164 (`+8801617738431`)
+    # @param variables      [Hash]    optional `{ name: 'value' }` map
+    # @param variant_index  [Integer] optional, 0 = primary
+    # @param idempotency_key [String] optional; auto-generated otherwise
+    # @return [Walinko::SyncResult]
+    def send(device_id:, template_id:, phone:,
+             variables: nil, variant_index: nil,
+             idempotency_key: nil)
+      payload = build_payload(
+        device_id: device_id, template_id: template_id,
+        phone: phone, variables: variables,
+        variant_index: variant_index, async: false
+      )
+
+      response = post(payload, idempotency_key: idempotency_key)
+      data = extract_data(response.body)
+
+      SyncResult.new(
+        data: data,
+        request_id: response.request_id,
+        rate_limit: response.rate_limit,
+        idempotent_replayed: response.idempotent_replayed
+      )
+    end
+
+    # Asynchronous enqueue: server returns immediately with a tracking id;
+    # the actual WhatsApp send happens out-of-band. Poll `fetch` (or use
+    # `wait_until_done`) for the final state.
+    #
+    # @return [Walinko::AsyncJob]
+    def enqueue(device_id:, template_id:, phone:,
+                variables: nil, variant_index: nil,
+                idempotency_key: nil)
+      payload = build_payload(
+        device_id: device_id, template_id: template_id,
+        phone: phone, variables: variables,
+        variant_index: variant_index, async: true
+      )
+
+      response = post(payload, idempotency_key: idempotency_key)
+      data = extract_data(response.body)
+
+      AsyncJob.new(
+        data: data,
+        request_id: response.request_id,
+        rate_limit: response.rate_limit,
+        idempotent_replayed: response.idempotent_replayed
+      )
+    end
+
+    # Look up a delivery by its tracking id.
+    #
+    # @param tracking_id [String] e.g. `tx_767fd2faca0f4037b2a2bbcb91e5735f`
+    # @return [Walinko::MessageStatus]
+    def fetch(tracking_id)
+      raise ArgumentError, 'tracking_id is required' if tracking_id.nil? || tracking_id.to_s.empty?
+
+      response = @http.request(method: :get, path: "#{SEND_PATH}/#{tracking_id}")
+      data = extract_data(response.body)
+
+      MessageStatus.new(data: data, request_id: response.request_id)
+    end
+
+    # Poll `fetch` until the delivery reaches a terminal state (sent /
+    # failed) or the timeout expires.
+    #
+    # @param tracking_id [String]
+    # @param timeout  [Integer] max seconds to wait, default 60
+    # @param interval [Numeric] seconds between polls, default 2
+    # @return [Walinko::MessageStatus]
+    # @raise  [Walinko::TimeoutError] if the message is still pending
+    #         when `timeout` elapses (the message is *not* failed —
+    #         continue polling later if you need to)
+    def wait_until_done(tracking_id, timeout: 60, interval: 2)
+      raise ArgumentError, 'timeout must be > 0'  if timeout.to_i  <= 0
+      raise ArgumentError, 'interval must be > 0' if interval.to_f <= 0
+
+      deadline = monotonic_now + timeout.to_f
+      loop do
+        status = fetch(tracking_id)
+        return status if status.done?
+
+        if monotonic_now + interval.to_f >= deadline
+          raise TimeoutError.new(
+            "Timed out waiting for #{tracking_id} after #{timeout}s (still #{status.status})",
+            http_status: 504,
+            error_code: 'send_timeout',
+            request_id: status.request_id,
+            details: { 'last_status' => status.status }
+          )
+        end
+
+        sleep(interval.to_f)
+      end
+    end
+
+    private
+
+    def post(payload, idempotency_key:)
+      key = idempotency_key&.to_s
+      key = generate_idempotency_key if key.nil? || key.empty?
+
+      @http.request(
+        method: :post,
+        path: SEND_PATH,
+        body: payload,
+        headers: { 'Idempotency-Key' => key }
+      )
+    end
+
+    def build_payload(device_id:, template_id:, phone:,
+                      variables:, variant_index:, async:)
+      raise ArgumentError, 'device_id is required'   if device_id.nil?
+      raise ArgumentError, 'template_id is required' if template_id.nil?
+      raise ArgumentError, 'phone is required'       if phone.nil? || phone.to_s.empty?
+
+      payload = {
+        'device_id' => Integer(device_id),
+        'template_id' => Integer(template_id),
+        'phone' => phone.to_s,
+        'async' => async
+      }
+      payload['variant_index'] = Integer(variant_index) unless variant_index.nil?
+      payload['variables']     = stringify_variables(variables) if variables
+      payload
+    end
+
+    def stringify_variables(variables)
+      raise ArgumentError, 'variables must be a Hash' unless variables.is_a?(Hash)
+
+      variables.each_with_object({}) do |(k, v), out|
+        out[k.to_s] = v.nil? ? '' : v.to_s
+      end
+    end
+
+    def extract_data(body)
+      return {} unless body.is_a?(Hash)
+
+      data = body['data']
+      data.is_a?(Hash) ? data : {}
+    end
+
+    def generate_idempotency_key
+      "walinko-rb-#{SecureRandom.uuid}"
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/walinko/result.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Walinko
+  # Returned by `client.messages.send(...)` (sync mode). Wraps the
+  # `data` block of a 200 OK response.
+  class SyncResult
+    attr_reader :tracking_id, :status, :device_id, :template_id,
+                :variant_index, :phone, :sent_at, :wa_message_id,
+                :request_id, :rate_limit, :idempotent_replayed
+
+    def initialize(data:, request_id:, rate_limit:, idempotent_replayed:)
+      @tracking_id         = data['tracking_id']
+      @status              = data['status']
+      @device_id           = data['device_id']
+      @template_id         = data['template_id']
+      @variant_index       = data['variant_index']
+      @phone               = data['phone']
+      @sent_at             = parse_time(data['sent_at'])
+      @wa_message_id       = data['wa_message_id']
+      @request_id          = request_id
+      @rate_limit          = rate_limit
+      @idempotent_replayed = idempotent_replayed
+    end
+
+    def sent?
+      status == 'sent'
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil? || value.to_s.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # Returned by `client.messages.enqueue(...)` (async mode). Wraps the
+  # `data` block of a 202 Accepted response.
+  class AsyncJob
+    attr_reader :tracking_id, :status, :status_url,
+                :request_id, :rate_limit, :idempotent_replayed
+
+    def initialize(data:, request_id:, rate_limit:, idempotent_replayed:)
+      @tracking_id         = data['tracking_id']
+      @status              = data['status']
+      @status_url          = data['status_url']
+      @request_id          = request_id
+      @rate_limit          = rate_limit
+      @idempotent_replayed = idempotent_replayed
+    end
+
+    def queued?
+      status == 'queued'
+    end
+  end
+
+  # Returned by `client.messages.fetch(tracking_id)`. Wraps the `data`
+  # block of `GET /messages/:trackingId`.
+  class MessageStatus
+    attr_reader :tracking_id, :status, :device_id, :template_id,
+                :variant_index, :phone, :wa_message_id,
+                :error_code, :error_message,
+                :sent_at, :created_at,
+                :request_id
+
+    def initialize(data:, request_id:)
+      @tracking_id   = data['tracking_id']
+      @status        = data['status']
+      @device_id     = data['device_id']
+      @template_id   = data['template_id']
+      @variant_index = data['variant_index']
+      @phone         = data['phone']
+      @wa_message_id = data['wa_message_id']
+      @error_code    = data['error_code']
+      @error_message = data['error_message']
+      @sent_at       = parse_time(data['sent_at'])
+      @created_at    = parse_time(data['created_at'])
+      @request_id    = request_id
+    end
+
+    def sent?;    status == 'sent';   end
+    def failed?;  status == 'failed'; end
+    def pending?; %w[queued sending].include?(status); end
+    def done?;    sent? || failed?; end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil? || value.to_s.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # Snapshot of the server-reported rate-limit window from the most
+  # recent response.
+  class RateLimitSnapshot
+    attr_reader :limit, :remaining
+
+    def initialize(limit:, remaining:)
+      @limit     = limit
+      @remaining = remaining
+    end
+
+    def saturated?
+      remaining.is_a?(Integer) && remaining <= 0
+    end
+  end
+end

data/lib/walinko/version.rb

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

data/lib/walinko.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'walinko/version'
+require_relative 'walinko/errors'
+require_relative 'walinko/configuration'
+require_relative 'walinko/result'
+require_relative 'walinko/http_client'
+require_relative 'walinko/messages'
+
+# Walinko Ruby SDK — server-to-server client for the Walinko public API.
+#
+# See the README for a quick-start; the contract is pinned in
+# `walinko-sdk/docs/openapi.yaml`.
+#
+# TODO(walinko-webhooks): when the server starts emitting webhooks,
+# `Walinko::Client#webhooks` (e.g. `client.webhooks.verify(payload, sig)`)
+# will land here. Reserving the namespace so v1 callers don't break.
+module Walinko
+  class Client
+    # @return [Walinko::Configuration]
+    attr_reader :config
+
+    # @return [Walinko::Messages]
+    attr_reader :messages
+
+    # @param api_key      [String] required, e.g. "walk_live_<keyId>.<secret>"
+    # @param base_url     [String] optional, defaults to "https://api.walinko.com"
+    # @param timeout      [Integer] read timeout in seconds (default 30)
+    # @param open_timeout [Integer] connection timeout in seconds (default 10)
+    # @param max_retries  [Integer] retries on idempotent failures (default 2)
+    # @param logger       [#info,#warn,#error] optional structured logger
+    def initialize(api_key:, **opts)
+      @config = Configuration.new(api_key: api_key, **opts)
+      @http   = HttpClient.new(@config)
+      @messages = Messages.new(@http)
+    end
+
+    # Snapshot of the rate-limit window from the most recent response.
+    # Returns `nil` until the first call has completed.
+    # @return [Walinko::RateLimitSnapshot, nil]
+    def last_rate_limit
+      @http.last_rate_limit
+    end
+
+    # The `X-Request-Id` from the most recent response (or `nil`).
+    # Useful when filing support tickets.
+    # @return [String, nil]
+    def last_request_id
+      @http.last_request_id
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: walinko
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Walinko
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+description: |
+  Server-to-server Ruby client for the Walinko public API. Provides
+  ergonomic helpers for sending transactional WhatsApp messages, idempotent
+  retries, structured errors, and lookups by tracking id.
+email:
+- support@walinko.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/walinko.rb
+- lib/walinko/configuration.rb
+- lib/walinko/errors.rb
+- lib/walinko/http_client.rb
+- lib/walinko/messages.rb
+- lib/walinko/result.rb
+- lib/walinko/version.rb
+homepage: https://github.com/walinko/walinko-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/walinko/walinko-sdk
+  source_code_uri: https://github.com/walinko/walinko-sdk/tree/main/sdks/ruby
+  changelog_uri: https://github.com/walinko/walinko-sdk/blob/main/sdks/ruby/CHANGELOG.md
+  documentation_uri: https://walinko.com/docs/api
+  bug_tracker_uri: https://github.com/walinko/walinko-sdk/issues
+  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.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Walinko public API.
+test_files: []