opensms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a17384937f73b877c763bb9b088637508a42b0a31dd2bb3fa729cbafa264877a
+  data.tar.gz: 7b69b1f9c8775fc52f5487decd20e56794f57b397828835a1a7d724277e7491b
+SHA512:
+  metadata.gz: f5aec7b0fa7ea901aaa99c775ba7ccb00e323a27300b2be33e6e591104ac36a20bc8540f8d74d3a983696815de678a2df7d42d9b24647576ec4d6178ae74183f
+  data.tar.gz: a9afec572d9b9e706d40653ec5045c76b79f4a2a818f745cf68cffb1f69bfb9aa546d7fc84bdd5b1cea78ba2aceffbb108ce169523c0d4d6bb866606d4c08401

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opensms
+
+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,301 @@
+# opensms (Ruby)
+
+Official Ruby client for [opensms](https://opensms.io): prepaid SMS for Africa.
+
+Ruby 3.0+, zero runtime dependencies (standard library only).
+
+## Install
+
+```ruby
+# Gemfile, once the gem is published
+gem "opensms"
+```
+
+Not on RubyGems yet: until then, install from this checkout with
+`gem "opensms", path: "path/to/sdks/packages/ruby"` in your Gemfile, or
+`gem build opensms.gemspec && gem install ./opensms-0.1.0.gem`.
+
+## Usage
+
+```ruby
+require "opensms"
+
+client = Opensms::Client.new(api_key: ENV.fetch("OPENSMS_API_KEY"))
+
+msg = client.messages.send(to: "+254712345678", text: "Your order has shipped")
+puts msg[:id], msg[:status]
+```
+
+The key selects the environment: `sk_test_...` keys run in the sandbox
+(`client.environment == "sandbox"`), `sk_live_...` keys send real traffic
+(`"live"`). A malformed key raises `ArgumentError` before any network call.
+
+Methods take keyword arguments (or a Hash with String or Symbol keys) using
+the API's snake_case field names. Responses are plain Ruby `Hash`/`Array`
+values with symbol keys, exactly as the API returns them: money stays a
+decimal string, timestamps stay RFC 3339 strings, and unknown fields are
+kept. Unknown request parameters raise `ArgumentError` locally, because the
+API rejects unknown fields. Time-like inputs (`scheduled_at`, `date_from`,
+`date_to`, analytics `from`/`to`) accept a `Time`, `Date` or string.
+
+## More
+
+One example per resource. See [`../../spec/SURFACE.md`](https://github.com/opensms-io/opensms-sdks/blob/main/spec/SURFACE.md)
+for the full surface.
+
+### messages
+
+```ruby
+msg = client.messages.send(to: "+254712345678", text: "Hi Ada", sender_id: "ACME")
+client.messages.list(limit: 20, status: "delivered", country: "KE")
+client.messages.get(msg[:id])
+client.messages.attempts(msg[:id])   # delivery attempts (Array)
+client.messages.cancel(msg[:id])     # only queued or scheduled messages; never auto-retried
+```
+
+### batches
+
+```ruby
+batch = client.batches.create(items: [
+  { to: "+254712345678", text: "Hello 1" },
+  { to: "+254712345679", text: "Hello 2" }
+], dedupe: true)
+client.batches.validation(batch[:id])   # per-row report
+client.batches.start(batch[:id])        # batches are created "ready" and send nothing until started
+client.batches.list_items(batch[:id], status: "delivered")
+client.batches.stop(batch[:id])
+```
+
+### otp
+
+```ruby
+otp = client.otp.send(to: "+254712345678", length: 6, ttl_seconds: 300)
+res = client.otp.verify(otp_id: otp[:otp_id], code: "123456")
+res[:valid]          # true / false
+res[:attempts_left]  # a wrong code burns an attempt, so verify is never auto-retried
+```
+
+### lookups
+
+```ruby
+lookup = client.lookups.create(to: "+254712345678")
+client.lookups.get(lookup[:id])
+```
+
+### contacts
+
+```ruby
+contact = client.contacts.create(e164: "+254712345678", name: "Ada", attributes: { tier: "gold" })
+client.contacts.update(contact[:id], name: "Ada L")   # partial update
+client.contacts.list(limit: 50)
+client.contacts.delete(contact[:id])
+```
+
+### contact_groups
+
+```ruby
+group = client.contact_groups.create(name: "VIP", contact_ids: [contact[:id]])
+client.contact_groups.send(group[:id], text: "Hi all")   # returns a running Batch
+client.contact_groups.send(group[:id], template_id: "tpl-id", variables: { name: "Ada" })
+client.contact_groups.delete(group[:id])
+```
+
+### templates
+
+```ruby
+tpl = client.templates.create(name: "welcome", body: "Hi {{name}}", traffic_type: "transactional")
+client.templates.update(tpl[:id], body: "Hello {{name}}")
+client.templates.list
+```
+
+### webhooks
+
+```ruby
+hook = client.webhooks.create(url: "https://you.example/opensms", events: ["message.delivered", "message.failed"])
+secret = hook[:secret]   # whsec_..., returned only once: store it
+
+client.webhooks.update(hook[:id], url: "https://you.example/v2", events: ["message.delivered"], enabled: true)
+client.webhooks.test(hook[:id])   # queues a webhook.test delivery
+```
+
+`update` is a full replacement: `url`, `events` and `enabled` are all required.
+See [Webhooks](#webhooks) below for signature verification.
+
+### inbound
+
+```ruby
+client.inbound.list
+client.inbound.reply("inbound-id", text: "Thanks!")   # live keys only
+```
+
+### numbers
+
+```ruby
+client.numbers.available(country: "KE", kind: "long_code")
+number = client.numbers.assign(country: "KE", kind: "long_code")   # charges the wallet; live keys only
+client.numbers.create_rule(number[:id], match: "keyword", pattern: "STOP", action: "webhook",
+                                        target: "https://you.example/inbound")
+client.numbers.release(number[:id])
+```
+
+### sender_ids
+
+```ruby
+quote = client.sender_ids.quote(countries: ["KE", "NG"])
+sender = client.sender_ids.create(value: "ACME", kind: "alphanumeric", countries: ["KE"],
+                                  use_case: "transactional", documents: ["doc-id-1"],
+                                  quote_id: quote[:quote_id])   # may charge fees: never auto-retried
+client.sender_ids.update(sender[:id], use_case: "otp", countries: ["KE"], documents: ["doc-id-1"])
+
+draft = client.sender_ids.create_draft(source: "application", value: "ACME", kind: "alphanumeric", countries: ["KE"])
+client.sender_ids.update_draft(draft[:id], version: draft[:version], sample_message: "Your code is 1234")
+```
+
+Document upload and download are console-only and not part of the SDK.
+
+### suppressions
+
+```ruby
+sup = client.suppressions.create(e164: "+254712345678", reason: "manual")   # never auto-retried
+client.suppressions.import([{ e164: "+254712345679", reason: "complaint" }])
+client.suppressions.delete(sup[:id])
+```
+
+### compliance
+
+```ruby
+client.compliance.list_countries
+client.compliance.get_country("KE")
+client.compliance.list_content_rules
+```
+
+### wallet
+
+```ruby
+client.wallet.balances               # [{ currency: "KES", balance: "100.000000", ... }]
+entries = client.wallet.ledger(limit: 100)
+older = client.wallet.ledger(limit: 100, before: entries.map { |e| e[:id] }.min)   # pages with `before`
+client.wallet.create_topup(amount: "1000", currency: "KES", channel: "mobile_money", email: "billing@you.example")
+```
+
+### pricing
+
+```ruby
+client.pricing.get(product: "sms", country: "KE")
+```
+
+### analytics
+
+```ruby
+client.analytics.overview(range: "7d")
+client.analytics.by_country(from: Date.today - 30, to: Date.today)
+client.analytics.timeseries(range: "2d", bucket: "hour")
+```
+
+### sandbox
+
+```ruby
+client.sandbox.list_messages(limit: 10)   # rendered text of sandbox sends, including OTP codes
+```
+
+### countries
+
+```ruby
+client.countries.list
+client.countries.carriers("KE")
+```
+
+### Pagination
+
+Cursor lists return an `Opensms::Page` with `items` and `next_cursor` (nil on
+the last page). `client.paginate` walks every page lazily:
+
+```ruby
+client.paginate(:messages, :list, limit: 50).each { |m| puts m[:id] }
+client.paginate(client.contacts.method(:list), limit: 200).to_a
+```
+
+## Errors and retries
+
+Every non-2xx response raises `Opensms::Error`, mapped from the API's
+RFC 9457 problem body:
+
+| Accessor | Meaning |
+| --- | --- |
+| `status` | HTTP status (`0` for a network failure or timeout) |
+| `type` | problem `type` (`"about:blank"` or a problems URI) |
+| `title` | HTTP reason title, e.g. `"Bad Request"` |
+| `detail` | human-readable detail (also `e.message`) |
+| `code` | machine code, absent on most errors |
+| `errors` | field-error map, when present |
+| `request_id` | set on message and OTP admission rejections |
+| `retry_after` | seconds, when the API asked to wait |
+| `trace_id` | present when the API attaches one |
+| `body` | raw decoded body (or raw text when not JSON) |
+
+**Branch on `status`, not `code`.** Most opensms errors carry no `code`; use
+`detail` for display. Insufficient API key scope is `401` on `messages` and
+`otp`, but `403` everywhere else.
+
+Retries: `429`, `500`, `502`, `503`, `504`, network errors and timeouts are
+retried up to `max_retries` times (default 2), only when safe. `GET`, `PUT`,
+`PATCH` and `DELETE` are always retryable. A `POST` is retried only when it
+carries an `Idempotency-Key`; the SDK generates a UUIDv4 per call and reuses
+it unchanged across retries of that call, so a retried send is never
+duplicated. `Retry-After` is honoured (seconds or HTTP date); if it asks for
+more than 60 seconds the SDK does not wait, it raises `Opensms::Error` with
+`retry_after` set. Otherwise the delay is exponential backoff with full
+jitter, capped at 8 seconds. Never retried: other `4xx` responses, and
+`messages.cancel`, `otp.verify`, `sender_ids.create`,
+`sender_ids.create_draft`, `suppressions.create` and `suppressions.import`.
+
+```ruby
+begin
+  client.messages.send(to: "+254712345678", text: "hi")
+rescue Opensms::Error => e
+  warn "#{e.status} #{e.code}: #{e.detail}"
+end
+```
+
+## Webhooks
+
+Every delivery carries `X-OpenSMS-Signature: t=<unix>,v1=<hex>`, an
+HMAC-SHA256 of `"<t>.<raw body>"` keyed with the endpoint's `whsec_...`
+secret used verbatim. Verify the raw body before parsing; no API key is
+needed:
+
+```ruby
+payload = request.body.read
+header = request.get_header("HTTP_X_OPENSMS_SIGNATURE")
+
+begin
+  event = Opensms::Webhook.construct_event(payload, header, ENV.fetch("OPENSMS_WEBHOOK_SECRET"))
+  case event.type
+  when "message.delivered" then mark_delivered(event.data[:id])
+  end
+rescue Opensms::Error => e
+  # e.code is "invalid_signature" or "expired_signature"
+  head :bad_request
+end
+
+Opensms::Webhook.verify_signature(payload, header, secret)                        # => true / false
+Opensms::Webhook.verify_signature(payload, header, secret, tolerance_seconds: 60) # default 300
+```
+
+The same helpers are available as `client.webhooks.verify_signature` and
+`client.webhooks.construct_event`.
+
+## Testing
+
+```sh
+rake test         # offline unit tests, no network
+rake integration  # live scenario against a sandbox; skipped unless OPENSMS_BASE_URL and OPENSMS_API_KEY are set
+```
+
+See the monorepo [root README](https://github.com/opensms-io/opensms-sdks) and
+[`../../spec/SURFACE.md`](https://github.com/opensms-io/opensms-sdks/blob/main/spec/SURFACE.md) for the API surface this
+SDK implements.
+
+## License
+
+MIT

data/lib/opensms/client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "models"
+require_relative "pagination"
+Dir[File.join(__dir__, "resources", "*.rb")].sort.each { |f| require f }
+
+module Opensms
+  # OpenSMS API client. Composes the HTTP transport with the resource groups.
+  #
+  # @example
+  #   client = Opensms::Client.new(api_key: ENV.fetch("OPENSMS_API_KEY"))
+  #   msg = client.messages.send(to: "+254700000012", text: "Hello")
+  #   puts msg[:id]
+  class Client
+    include Pagination
+
+    RESOURCES = {
+      messages: Resources::Messages,
+      batches: Resources::Batches,
+      otp: Resources::Otp,
+      lookups: Resources::Lookups,
+      contacts: Resources::Contacts,
+      contact_groups: Resources::ContactGroups,
+      templates: Resources::Templates,
+      webhooks: Resources::Webhooks,
+      inbound: Resources::Inbound,
+      numbers: Resources::Numbers,
+      sender_ids: Resources::SenderIds,
+      suppressions: Resources::Suppressions,
+      compliance: Resources::Compliance,
+      wallet: Resources::Wallet,
+      pricing: Resources::Pricing,
+      analytics: Resources::Analytics,
+      sandbox: Resources::Sandbox,
+      countries: Resources::Countries
+    }.freeze
+
+    RESOURCES.each_key { |name| attr_reader name }
+
+    # @return [String] "sandbox" for sk_test_ keys, "live" for sk_live_ keys
+    attr_reader :environment
+    # @return [String] the base URL with trailing slashes removed
+    attr_reader :base_url
+
+    # @param api_key [String] required; "sk_test_..." or "sk_live_..."
+    # @param base_url [String] default "https://api.opensms.io"
+    # @param timeout [Numeric] per-attempt timeout in seconds, default 30
+    # @param max_retries [Integer] retries after the first attempt, default 2
+    # @param http_client [#call, nil] replaces the Net::HTTP adapter (see {Opensms::NetHttpClient})
+    # @param sleeper [#call, nil] called with the retry delay in seconds
+    # @raise [ArgumentError] for a malformed key (no network call is made)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(api_key:, base_url: Transport::DEFAULT_BASE_URL, timeout: 30, max_retries: 2,
+                   http_client: nil, sleeper: nil, random: nil)
+      transport = Transport.new(api_key: api_key, base_url: base_url, timeout: timeout, max_retries: max_retries,
+                                http_client: http_client, sleeper: sleeper, random: random)
+      @environment = transport.environment
+      @base_url = transport.base_url
+      RESOURCES.each { |name, klass| instance_variable_set(:"@#{name}", klass.new(transport)) }
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+end

data/lib/opensms/error.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Opensms
+  # Raised for every non-2xx API response, for transport failures that survive
+  # all retries (status 0), and for webhook signature failures (status 0, code
+  # "invalid_signature" or "expired_signature").
+  #
+  # Fields map the RFC 9457 problem+json body the API returns. Most OpenSMS
+  # errors carry no +code+, so branch on {#status} and show {#detail}.
+  # Insufficient scope is 401 on messages and otp, but 403 everywhere else.
+  class Error < StandardError
+    # @return [Integer] HTTP status (0 when there was no response)
+    attr_reader :status
+    # @return [String, nil] problem +type+ ("about:blank" or a problems URI)
+    attr_reader :type
+    # @return [String, nil] problem +title+ ("Bad Request", ...)
+    attr_reader :title
+    # @return [String, nil] problem +detail+, human readable
+    attr_reader :detail
+    # @return [String, nil] optional machine code ("invalid_message_id", ...)
+    attr_reader :code
+    # @return [String, nil] problem +trace_id+
+    attr_reader :trace_id
+    # @return [Hash{Symbol=>Array<String>}, nil] field validation errors
+    attr_reader :errors
+    # @return [String, nil] the X-Request-ID response header
+    attr_reader :request_id
+    # @return [Numeric, nil] Retry-After in seconds
+    attr_reader :retry_after
+    # @return [Object, nil] raw decoded body (symbol keys), or the raw text if not JSON
+    attr_reader :body
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(status:, message: nil, type: nil, title: nil, detail: nil, code: nil, trace_id: nil,
+                   errors: nil, request_id: nil, retry_after: nil, body: nil)
+      @status = status
+      @type = type
+      @title = title
+      @detail = detail
+      @code = code
+      @trace_id = trace_id
+      @errors = errors
+      @request_id = request_id
+      @retry_after = retry_after
+      @body = body
+      super(message || detail || title || "OpenSMS request failed with status #{status}")
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Build an error from an HTTP response.
+    #
+    # @param status [Integer]
+    # @param headers [Hash{String=>String}] lower-cased header names
+    # @param raw [String, nil] response body text
+    # @param retry_after [Numeric, nil]
+    # @return [Opensms::Error]
+    def self.from_response(status, headers, raw, retry_after: nil)
+      parsed = nil
+      if raw && !raw.strip.empty?
+        begin
+          parsed = JSON.parse(raw, symbolize_names: true)
+        rescue JSON::ParserError
+          parsed = nil
+        end
+      end
+      problem = parsed.is_a?(Hash) ? parsed : {}
+      str = ->(v) { v.is_a?(String) ? v : nil }
+      new(
+        status: status,
+        type: str.call(problem[:type]),
+        title: str.call(problem[:title]),
+        detail: str.call(problem[:detail]),
+        code: str.call(problem[:code]),
+        trace_id: str.call(problem[:trace_id]),
+        errors: problem[:errors].is_a?(Hash) ? problem[:errors] : nil,
+        request_id: headers["x-request-id"],
+        retry_after: retry_after,
+        body: parsed.nil? ? raw : parsed
+      )
+    end
+  end
+end

data/lib/opensms/models.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Opensms
+  # One page of a cursor-paginated list: +items+ plus +next_cursor+ (nil on
+  # the last page). Items are Hashes with the API's snake_case field names as
+  # symbol keys, for example +page.items.first[:traffic_type]+.
+  #
+  # Page is Enumerable over the items of this page only; use
+  # {Opensms::Client#paginate} to walk every page.
+  class Page
+    include Enumerable
+
+    # @return [Array<Hash>]
+    attr_reader :items
+    # @return [String, nil]
+    attr_reader :next_cursor
+
+    # @param items [Array<Hash>]
+    # @param next_cursor [String, nil]
+    def initialize(items, next_cursor)
+      @items = items || []
+      @next_cursor = next_cursor
+    end
+
+    # Build a Page from a decoded +{items, next_cursor}+ body.
+    #
+    # @param body [Hash, nil]
+    # @return [Opensms::Page]
+    def self.from(body)
+      body ||= {}
+      new(body[:items], body[:next_cursor])
+    end
+
+    def each(&block)
+      @items.each(&block)
+    end
+
+    # @return [Hash] the page as a Hash (+{items:, next_cursor:}+)
+    def to_h
+      { items: @items, next_cursor: @next_cursor }
+    end
+  end
+
+  # A verified webhook delivery envelope, returned by
+  # {Opensms::Webhook.construct_event}. Wire fields: id, type, workspace_id,
+  # environment, created_at, data.
+  WebhookEvent = Struct.new(:id, :type, :workspace_id, :environment, :created_at, :data, keyword_init: true) do
+    # @param hash [Hash] decoded envelope with symbol keys
+    # @return [Opensms::WebhookEvent]
+    def self.from(hash)
+      new(
+        id: hash[:id],
+        type: hash[:type],
+        workspace_id: hash[:workspace_id],
+        environment: hash[:environment],
+        created_at: hash[:created_at],
+        data: hash[:data]
+      )
+    end
+  end
+
+  # Request-side model mapping. Response models are plain Hashes (symbol keys,
+  # wire names, money kept as decimal strings, timestamps kept as RFC 3339
+  # strings, unknown fields preserved). Wire names are already snake_case, so
+  # Ruby names are the wire names; this module is the one place that decides
+  # which fields a request may carry and how values are serialized.
+  module Models
+    module_function
+
+    # Select the allowed keys from +params+ (String or Symbol keys), raise on
+    # unknown or missing required keys, drop nils and serialize time values.
+    #
+    # @param params [Hash]
+    # @param allowed [Array<Symbol>]
+    # @param required [Array<Symbol>]
+    # @param times [Array<Symbol>] keys whose values are serialized as RFC 3339
+    # @return [Hash]
+    def build(params, allowed, required: [], times: [])
+      params = symbolize(params || {})
+      unknown = params.keys - allowed
+      raise ArgumentError, "Opensms: unknown parameter(s): #{unknown.join(', ')}" unless unknown.empty?
+
+      missing = required.select { |k| params[k].nil? }
+      raise ArgumentError, "Opensms: missing required parameter(s): #{missing.join(', ')}" unless missing.empty?
+
+      params.each_with_object({}) do |(k, v), out|
+        next if v.nil?
+
+        out[k] = times.include?(k) ? time(v) : v
+      end
+    end
+
+    # Serialize a Time/DateTime as RFC 3339 UTC, a Date as YYYY-MM-DD, and
+    # pass strings through.
+    #
+    # @param value [Time, DateTime, Date, String]
+    # @return [String]
+    def time(value)
+      case value
+      when DateTime then value.new_offset(0).iso8601
+      when Time then value.getutc.iso8601
+      when Date then value.iso8601
+      else value.to_s
+      end
+    end
+
+    # Shallow-symbolize the keys of a Hash.
+    def symbolize(hash)
+      raise ArgumentError, "Opensms: parameters must be a Hash" unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/opensms/pagination.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Opensms
+  # Auto-pagination over cursor lists. Mixed into {Opensms::Client}.
+  module Pagination
+    # Lazily walk every page of a cursor list, feeding +next_cursor+ back as
+    # +cursor+ until it is nil.
+    #
+    # @example
+    #   client.paginate(:messages, :list, limit: 50).each { |m| puts m[:id] }
+    #   client.paginate(:batches, :list_items, batch_id, limit: 100).first(10)
+    #   client.paginate(client.contacts.method(:list), limit: 200).to_a
+    #
+    # @overload paginate(resource, method, *args, **params)
+    #   @param resource [Symbol] a client resource name (:messages, ...)
+    #   @param method [Symbol] a list method returning {Opensms::Page}
+    # @overload paginate(callable, *args, **params)
+    #   @param callable [#call] returns {Opensms::Page}
+    # @return [Enumerator<Hash>]
+    def paginate(target, *args, **params)
+      fn = target.respond_to?(:call) ? target : public_send(target).method(args.shift)
+      Enumerator.new do |yielder|
+        query = params.dup
+        loop do
+          page = fn.call(*args, **query)
+          page.items.each { |item| yielder << item }
+          break if page.next_cursor.nil? || page.next_cursor.to_s.empty?
+
+          query = query.merge(cursor: page.next_cursor)
+        end
+      end.lazy
+    end
+  end
+end

data/lib/opensms/resources/analytics.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Opensms
+  module Resources
+    # The +analytics+ resource: delivery and spend metrics. Every method takes
+    # the same optional query: :currency, :range ("30d"), or :from / :to
+    # (Time, Date or string; not combined with :range), and :bucket
+    # (day|hour). Accessed as +client.analytics+.
+    class Analytics < Base
+      QUERY = %i[currency range from to bucket].freeze
+
+      # GET /v1/analytics/overview -> Metrics + { from:, to:, currency:, environment: }.
+      def overview(params = nil, **kwargs)
+        fetch("overview", params, kwargs)
+      end
+
+      # GET /v1/analytics/by-country -> Array<Metrics + { key:, name: }>.
+      def by_country(params = nil, **kwargs)
+        fetch("by-country", params, kwargs)
+      end
+
+      # GET /v1/analytics/by-carrier -> Array<Metrics + { key:, name: }>.
+      def by_carrier(params = nil, **kwargs)
+        fetch("by-carrier", params, kwargs)
+      end
+
+      # GET /v1/analytics/by-sender-id -> Array<Metrics + { key:, name: }>.
+      def by_sender_id(params = nil, **kwargs)
+        fetch("by-sender-id", params, kwargs)
+      end
+
+      # GET /v1/analytics/timeseries -> Array<Metrics + { bucket: }>.
+      def timeseries(params = nil, **kwargs)
+        fetch("timeseries", params, kwargs)
+      end
+
+      private
+
+      def fetch(name, params, kwargs)
+        http_get("/v1/analytics/#{name}", Models.build(merge(params, kwargs), QUERY, times: %i[from to]))
+      end
+    end
+  end
+end