smsru_ruby 1.0.0

data/lib/sms_ru/client.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+# Ruby client for the SMS.ru HTTP API (https://sms.ru/api).
+#
+#   client = SmsRu.new("YOUR_API_ID")
+#   client.deliver("79991234567", "Hello!")
+class SmsRu
+  # Base URL of the SMS.ru HTTP API.
+  BASE_URL = "https://sms.ru"
+
+  # Transport-level exceptions that warrant a retry.
+  RETRIABLE = [
+    Net::OpenTimeout, Net::ReadTimeout, IOError, EOFError, SocketError,
+    Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError
+  ].freeze
+
+  # @param api_id  [String]  your SMS.ru API id
+  # @param timeout [Integer] open/read timeout in seconds
+  # @param test    [Boolean] when true, every deliver defaults to test mode (no charge)
+  # @param retries [Integer] retry attempts on transport failure (0 disables; PHP default is 5)
+  # @param from    [String, nil] default sender name for #deliver (overridable per call)
+  # @param logger  [Logger, nil] optional logger; logs the request path and transport
+  #   failures only — never the api_id, phone numbers, or message text
+  def initialize(api_id, timeout: 30, test: false, retries: 5, from: nil, logger: nil)
+    @api_id = api_id
+    @timeout = timeout
+    @test = test
+    @retries = retries
+    @from = from
+    @logger = logger
+  end
+
+  # Sends a message.
+  #
+  # @param to [String, Array<String>, Hash{String => String}] recipient(s):
+  #   a String for one number, an Array for the same text to many numbers, or a
+  #   Hash of `number => text` pairs for a different text per number.
+  # @param text [String, nil] the message text; required for the String/Array
+  #   forms, must be omitted for the Hash form
+  # @param from [String, nil] an approved sender name
+  # @param time [Integer, nil] schedule the send at this UNIX timestamp
+  # @param ttl [Integer, nil] message lifetime in minutes (1–1440); undelivered
+  #   messages are discarded after this period
+  # @param daytime [Boolean] when true, defer night-time sends to the recipient's daytime
+  # @param translit [Boolean] transliterate Cyrillic to Latin
+  # @param test [Boolean, nil] override the client's global test mode for this call
+  # @param ip [String, nil] the end-user IP (anti-fraud for auth codes)
+  # @param partner_id [Integer, nil] partner program id
+  # @return [SmsRu::SendResult]
+  # @raise [ArgumentError] if `text` is missing (String/Array) or given (Hash)
+  # @raise [SmsRu::ResponseError] if SMS.ru rejects the whole request
+  # @example Send one message
+  #   client.deliver("79991234567", "Hello!")
+  # @example Per-number text
+  #   client.deliver({ "79991234567" => "Hi Alice", "79991234568" => "Hi Bob" })
+  def deliver(to, text = nil, from: nil, time: nil, ttl: nil, daytime: false,
+              translit: false, test: nil, ip: nil, partner_id: nil)
+    params = { from: from || @from, time:, ttl:, ip:, partner_id: }.compact
+    params[:translit] = 1 if translit
+    params[:daytime] = 1 if daytime
+    params[:test] = 1 if test.nil? ? @test : test
+    add_recipients(params, to, text)
+    SendResult.build(request("/sms/send", **params))
+  end
+
+  # Returns the cost and SMS count for a message without sending it.
+  #
+  # @param to [String, Array<String>] recipient(s)
+  # @param text [String, nil] the message text (omit for the price of one SMS)
+  # @param translit [Boolean] transliterate Cyrillic to Latin
+  # @return [SmsRu::Cost]
+  # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+  # @example
+  #   client.cost("79991234567", "How much?").total_cost
+  def cost(to, text = nil, translit: false)
+    # @type var params: Hash[Symbol, untyped]
+    params = { to: Array(to).join(","), text: text }.compact
+    params[:translit] = 1 if translit
+    Cost.build(request("/sms/cost", **params))
+  end
+
+  # Delivery status for one id or an Array of ids.
+  #
+  # @param sms_id [String, Array<String>] one message id or an Array of ids
+  # @return [SmsRu::Status, Array<SmsRu::Status>] a single Status for a String
+  #   argument, or an Array of Status for an Array argument
+  # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+  def status(sms_id)
+    statuses = Status.build_all(request("/sms/status", sms_id: Array(sms_id).join(",")))
+    sms_id.is_a?(Array) ? statuses : statuses.first
+  end
+
+  # Requests a flash-call verification: SMS.ru calls the number; the last 4
+  # digits of the calling number (returned as `code`) are the code the user enters.
+  #
+  # @param phone [String, Integer] the number to call
+  # @param ip [String] the end-user IP (anti-fraud); "-1" for manual/local requests
+  # @param partner_id [Integer, nil] partner program id
+  # @return [SmsRu::Call]
+  # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+  def call(phone, ip: "-1", partner_id: nil)
+    Call.build(request("/code/call", **{ phone: phone.to_s, ip:, partner_id: }.compact))
+  end
+
+  # @return [SmsRu::My] the account-info sub-resource (balance, limit, free_limit, senders)
+  def my = @my ||= My.new(method(:request))
+
+  # @return [SmsRu::Auth] the authentication sub-resource
+  def auth = @auth ||= Auth.new(method(:request))
+
+  # @return [SmsRu::Stoplist] the stoplist sub-resource
+  def stoplist = @stoplist ||= Stoplist.new(method(:request))
+
+  # @return [SmsRu::Callbacks] the callbacks sub-resource
+  def callbacks = @callbacks ||= Callbacks.new(method(:request))
+
+  # @return [SmsRu::CallCheck] the call-check (incoming-call auth) sub-resource
+  def callcheck = @callcheck ||= CallCheck.new(method(:request))
+
+  private
+
+  def add_recipients(params, to, text)
+    if to.is_a?(Hash)
+      raise ArgumentError, "do not pass `text` when `to` is a Hash of number => text" unless text.nil?
+
+      to.each { |phone, message| params[:"multi[#{phone}]"] = message }
+    else
+      raise ArgumentError, "`text` is required" if text.nil?
+
+      params[:to] = Array(to).join(",")
+      params[:msg] = text
+    end
+  end
+
+  def request(path, **params)
+    params[:api_id] = @api_id unless Coerce.string(params[:api_id]) == "none"
+    @logger&.debug("[SmsRu] POST #{path}")
+    uri = URI("#{BASE_URL}#{path}?json=1") #: URI::HTTP
+    perform(uri, URI.encode_www_form(params))
+  end
+
+  def perform(uri, body)
+    attempts = 0
+    begin
+      attempts += 1
+      response = http(uri).post(uri.request_uri, body, "Content-Type" => "application/x-www-form-urlencoded")
+      parse(response.body)
+    rescue *RETRIABLE => e
+      error = e #: StandardError
+      @logger&.warn("[SmsRu] #{uri.path} failed (attempt #{attempts}): #{error.message}")
+      retry if attempts <= @retries
+
+      raise ConnectionError, "Cannot reach SMS.ru: #{error.message}"
+    end
+  end
+
+  def http(uri)
+    host = uri.host #: String
+    http = Net::HTTP.new(host, uri.port)
+    http.use_ssl = true
+    http.open_timeout = @timeout
+    http.read_timeout = @timeout
+    http
+  end
+
+  def parse(raw)
+    data = Coerce.records(JSON.parse(raw.to_s))
+    status = Coerce.string?(data["status"])
+    raise ConnectionError, "Malformed response from SMS.ru" unless status
+    return data if status == "OK"
+
+    raise error_for(data)
+  rescue JSON::ParserError
+    raise ConnectionError, "Invalid JSON from SMS.ru"
+  end
+
+  def error_for(data)
+    code = Coerce.integer(data["status_code"])
+    text = Coerce.string(data["status_text"], "SMS.ru returned an error")
+    error_class(code).new(code: code, text: text)
+  end
+
+  def error_class(code)
+    case code
+    when 200, 300, 301, 302 then AuthError
+    when 201 then InsufficientFundsError
+    else ResponseError
+    end
+  end
+end

data/lib/sms_ru/coerce.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Normalizes loosely-typed SMS.ru JSON values into the types the result
+  # objects declare. SMS.ru is inconsistent on the wire — `/my/limit` returns
+  # `total_limit` as the string `"10"` but `used_today` as the number `0`, and
+  # some counters arrive as `null` — so each field is coerced here rather than
+  # trusted as-is.
+  #
+  # Each type has two helpers: the `?` variant returns nil for a
+  # missing/blank/unparseable value (for the nullable fields), while the plain
+  # variant falls back to a default (`""`/`0`/`0.0`, overridable) for the fields
+  # the API always populates — so call sites declare their nullability by name.
+  #
+  # @api private
+  module Coerce
+    module_function
+
+    # @param value [Object, nil] a raw JSON value
+    # @return [String, nil] the value stringified, or nil when absent
+    # `?` marks the nullable variant, not a boolean predicate, so nil is intended.
+    def string?(value) = value ? String(value) : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+
+    # @param value [Object, nil] a raw JSON value
+    # @param default [String] returned when the value is absent
+    # @return [String] the value stringified, or the default
+    def string(value, default = "") = string?(value) || default
+
+    # @param value [Object, nil] a raw JSON value (number or numeric string)
+    # @return [Integer, nil] the parsed integer, or nil when absent/unparseable
+    def integer?(value) = Integer(value, exception: false)
+
+    # @param value [Object, nil] a raw JSON value (number or numeric string)
+    # @param default [Integer] returned when the value is absent/unparseable
+    # @return [Integer] the parsed integer, or the default
+    def integer(value, default = 0) = integer?(value) || default
+
+    # @param value [Object, nil] a raw JSON value (number or numeric string)
+    # @return [Float, nil] the parsed float, or nil when absent/unparseable
+    def float?(value) = Float(value, exception: false)
+
+    # @param value [Object, nil] a raw JSON value (number or numeric string)
+    # @param default [Float] returned when the value is absent/unparseable
+    # @return [Float] the parsed float, or the default
+    def float(value, default = 0.0) = float?(value) || default
+
+    # @param value [Object, nil] a raw JSON value expected to be an object
+    # @return [Hash] the value when it is a Hash, otherwise an empty Hash
+    def records(value) = Hash.try_convert(value) || {}
+  end
+end

data/lib/sms_ru/data.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Collection helpers shared by results that wrap a `messages` array of
+  # per-recipient entries (each responding to #ok?): SmsRu::SendResult and
+  # SmsRu::Cost. There is intentionally no lookup-by-phone, since one request may
+  # target the same number more than once.
+  module MessageCollection
+    # @return [Boolean] true when every recipient succeeded
+    def ok? = messages.all?(&:ok?)
+
+    # @return [Array] the recipient entries that succeeded
+    def ok = messages.select(&:ok?)
+
+    # @return [Array] the recipient entries that failed
+    def failed = messages.reject(&:ok?)
+  end
+
+  # A single message inside a send response (one entry of the `sms` object).
+  # `error_code`/`error_text` are populated only when this recipient was rejected.
+  #
+  # @!attribute [r] phone
+  #   @return [String] the recipient's phone number
+  # @!attribute [r] sms_id
+  #   @return [String, nil] the message id assigned by SMS.ru (nil when rejected)
+  # @!attribute [r] error_code
+  #   @return [Integer, nil] the rejection code, or nil when accepted
+  # @!attribute [r] error_text
+  #   @return [String, nil] the rejection reason, or nil when accepted
+  class Sms < Data.define(:phone, :sms_id, :error_code, :error_text)
+    # @param phone [String] the recipient's phone number
+    # @param hash [Hash] one entry of the response `sms` object
+    # @return [SmsRu::Sms]
+    def self.build(phone, hash)
+      ok = Coerce.string(hash["status"]) == "OK"
+      new(
+        phone: String(phone),
+        sms_id: Coerce.string?(hash["sms_id"]),
+        error_code: ok ? nil : Coerce.integer(hash["status_code"]),
+        error_text: ok ? nil : Coerce.string(hash["status_text"])
+      )
+    end
+
+    # @return [Boolean] true when this recipient was accepted
+    def ok? = error_code.nil?
+  end
+
+  # Result of SmsRu#deliver. `messages` holds one Sms per recipient; individual
+  # recipients may have failed even when the overall request succeeded (use #ok?
+  # or #failed to tell).
+  #
+  # @!attribute [r] balance
+  #   @return [Float] the account balance after the request
+  # @!attribute [r] messages
+  #   @return [Array<SmsRu::Sms>] one entry per recipient
+  class SendResult < Data.define(:balance, :messages)
+    include MessageCollection
+
+    # @param hash [Hash] the parsed /sms/send response
+    # @return [SmsRu::SendResult]
+    def self.build(hash)
+      messages = Coerce.records(hash["sms"]).map { |phone, sms| Sms.build(phone, sms) }
+      new(balance: Coerce.float(hash["balance"]), messages: messages)
+    end
+  end
+
+  # Delivery status of one message (one entry of a /sms/status response).
+  # `status_code` is the message's delivery state; read it with #delivered?,
+  # #pending?, #failed?, or the SmsRu::Statuses constants.
+  #
+  # @!attribute [r] sms_id
+  #   @return [String] the message id
+  # @!attribute [r] status_code
+  #   @return [Integer] the delivery state code (see SmsRu::Statuses)
+  # @!attribute [r] status_text
+  #   @return [String] the human-readable delivery state
+  # @!attribute [r] cost
+  #   @return [Float, nil] the message cost, when present
+  class Status < Data.define(:sms_id, :status_code, :status_text, :cost)
+    include DeliveryStatus
+
+    # @param sms_id [String] the message id
+    # @param hash [Hash] one entry of the response `sms` object
+    # @return [SmsRu::Status]
+    def self.build(sms_id, hash)
+      new(
+        sms_id: String(sms_id),
+        status_code: Coerce.integer(hash["status_code"], Statuses::NOT_FOUND),
+        status_text: Coerce.string(hash["status_text"]),
+        cost: Coerce.float?(hash["cost"])
+      )
+    end
+
+    # @param hash [Hash] the parsed /sms/status response
+    # @return [Array<SmsRu::Status>] one Status per requested id
+    def self.build_all(hash) = Coerce.records(hash["sms"]).map { |sms_id, sms| build(sms_id, sms) }
+
+    # @return [Boolean] true when the queried id exists (not status code -1)
+    def found? = status_code != Statuses::NOT_FOUND
+  end
+
+  # Per-recipient cost (one entry of a /sms/cost response).
+  # `error_code`/`error_text` are populated only when this recipient cannot be priced.
+  #
+  # @!attribute [r] phone
+  #   @return [String] the recipient's phone number
+  # @!attribute [r] cost
+  #   @return [Float, nil] the price for this recipient, or nil when it errored
+  # @!attribute [r] sms_count
+  #   @return [Integer, nil] the number of SMS segments, or nil when it errored
+  # @!attribute [r] error_code
+  #   @return [Integer, nil] the error code, or nil when priced
+  # @!attribute [r] error_text
+  #   @return [String, nil] the error reason, or nil when priced
+  class CostItem < Data.define(:phone, :cost, :sms_count, :error_code, :error_text)
+    # @param phone [String] the recipient's phone number
+    # @param hash [Hash] one entry of the response `sms` object
+    # @return [SmsRu::CostItem]
+    def self.build(phone, hash)
+      ok = Coerce.string(hash["status"]) == "OK"
+      new(
+        phone: String(phone),
+        cost: Coerce.float?(hash["cost"]),
+        sms_count: Coerce.integer?(hash["sms"]),
+        error_code: ok ? nil : Coerce.integer(hash["status_code"]),
+        error_text: ok ? nil : Coerce.string(hash["status_text"])
+      )
+    end
+
+    # @return [Boolean] true when this recipient was priced successfully
+    def ok? = error_code.nil?
+  end
+
+  # Result of SmsRu#cost.
+  #
+  # @!attribute [r] total_cost
+  #   @return [Float] the total price across all recipients
+  # @!attribute [r] total_sms
+  #   @return [Integer] the total number of SMS segments
+  # @!attribute [r] messages
+  #   @return [Array<SmsRu::CostItem>] one entry per recipient
+  class Cost < Data.define(:total_cost, :total_sms, :messages)
+    include MessageCollection
+
+    # @param hash [Hash] the parsed /sms/cost response
+    # @return [SmsRu::Cost]
+    def self.build(hash)
+      messages = Coerce.records(hash["sms"]).map { |phone, cost| CostItem.build(phone, cost) }
+      new(
+        total_cost: Coerce.float(hash["total_cost"]),
+        total_sms: Coerce.integer(hash["total_sms"]),
+        messages: messages
+      )
+    end
+  end
+
+  # Result of SmsRu#call (flash call). `code` is the last 4 digits of the number
+  # that calls the user — what they read off the incoming call and enter.
+  #
+  # @!attribute [r] code
+  #   @return [String] the 4-digit code (the calling number's last 4 digits)
+  # @!attribute [r] call_id
+  #   @return [String] the call id assigned by SMS.ru
+  # @!attribute [r] cost
+  #   @return [Float] the price of the call
+  # @!attribute [r] balance
+  #   @return [Float] the account balance after the call
+  class Call < Data.define(:code, :call_id, :cost, :balance)
+    # @param hash [Hash] the parsed /code/call response
+    # @return [SmsRu::Call]
+    def self.build(hash)
+      new(
+        code: Coerce.string(hash["code"]),
+        call_id: Coerce.string(hash["call_id"]),
+        cost: Coerce.float(hash["cost"]),
+        balance: Coerce.float(hash["balance"])
+      )
+    end
+  end
+
+  # Result of SmsRu::My#limit (daily sending limit).
+  #
+  # @!attribute [r] total_limit
+  #   @return [Integer] the daily limit
+  # @!attribute [r] used_today
+  #   @return [Integer] the number of messages sent today
+  class Limit < Data.define(:total_limit, :used_today)
+    # @param hash [Hash] the parsed /my/limit response
+    # @return [SmsRu::Limit]
+    def self.build(hash)
+      new(total_limit: Coerce.integer(hash["total_limit"]), used_today: Coerce.integer(hash["used_today"]))
+    end
+
+    # @return [Integer] how many more messages can be sent today
+    def available_today = total_limit - used_today
+  end
+
+  # Result of SmsRu::My#free_limit (free daily messages).
+  #
+  # @!attribute [r] total_free
+  #   @return [Integer] the daily allowance of free messages
+  # @!attribute [r] used_today
+  #   @return [Integer] the number used today (0 when the API omits it)
+  class FreeLimit < Data.define(:total_free, :used_today)
+    # @param hash [Hash] the parsed /my/free response
+    # @return [SmsRu::FreeLimit]
+    def self.build(hash)
+      new(total_free: Coerce.integer(hash["total_free"]), used_today: Coerce.integer(hash["used_today"]))
+    end
+
+    # @return [Integer] how many free messages remain today
+    def available_today = total_free - used_today
+  end
+
+  # Result of SmsRu::CallCheck#add — the number the user must call to authorize.
+  #
+  # @!attribute [r] check_id
+  #   @return [String] the check id to poll with SmsRu::CallCheck#status
+  # @!attribute [r] call_phone
+  #   @return [String] the number the user must call
+  # @!attribute [r] call_phone_pretty
+  #   @return [String] the same number, formatted for display
+  # @!attribute [r] call_phone_html
+  #   @return [String] a mobile-clickable `tel:` link for the number
+  class CallCheckResult < Data.define(:check_id, :call_phone, :call_phone_pretty, :call_phone_html)
+    # @param hash [Hash] the parsed /callcheck/add response
+    # @return [SmsRu::CallCheckResult]
+    def self.build(hash)
+      new(
+        check_id: Coerce.string(hash["check_id"]),
+        call_phone: Coerce.string(hash["call_phone"]),
+        call_phone_pretty: Coerce.string(hash["call_phone_pretty"]),
+        call_phone_html: Coerce.string(hash["call_phone_html"])
+      )
+    end
+  end
+
+  # Result of SmsRu::CallCheck#status — whether the authorizing call has arrived.
+  #
+  # @!attribute [r] status_code
+  #   @return [Integer] the check status code (401 once confirmed)
+  # @!attribute [r] status_text
+  #   @return [String] the human-readable status
+  class CallCheckStatus < Data.define(:status_code, :status_text)
+    # @param hash [Hash] the parsed /callcheck/status response
+    # @return [SmsRu::CallCheckStatus]
+    def self.build(hash)
+      new(status_code: Coerce.integer(hash["check_status"]), status_text: Coerce.string(hash["check_status_text"]))
+    end
+
+    # @return [Boolean] true once the user has placed the authorizing call
+    def confirmed? = status_code == 401
+  end
+
+  # One stoplist entry returned by SmsRu::Stoplist#list.
+  #
+  # @!attribute [r] phone
+  #   @return [String] the stoplisted phone number
+  # @!attribute [r] note
+  #   @return [String] the note you stored with the number
+  class StoplistEntry < Data.define(:phone, :note)
+  end
+end

data/lib/sms_ru/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Base class for every error raised by the gem. Rescue this to catch them all.
+  class Error < StandardError; end
+
+  # Raised when SMS.ru cannot be reached or returns an unparseable body
+  # (network failure, timeout, invalid JSON). Retried up to `retries` times first.
+  class ConnectionError < Error; end
+
+  # Raised when SMS.ru replies with a non-OK status. Carries the API's numeric
+  # `code` and human-readable `text` (status_text).
+  #
+  # @!attribute [r] code
+  #   @return [Integer] the SMS.ru numeric status code
+  # @!attribute [r] text
+  #   @return [String] the human-readable status text
+  class ResponseError < Error
+    attr_reader :code, :text
+
+    # @param code [Integer] the SMS.ru numeric status code
+    # @param text [String] the human-readable status text
+    def initialize(code:, text:)
+      @code = code
+      @text = text
+      super("[#{code}] #{text}")
+    end
+  end
+
+  # Invalid api_id / token / unconfirmed account (codes 200, 300, 301, 302).
+  class AuthError < ResponseError; end
+
+  # Not enough money on the account (code 201).
+  class InsufficientFundsError < ResponseError; end
+end

data/lib/sms_ru/events.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Typed events decoded from an inbound SMS.ru webhook payload. One of these is
+  # produced per record by SmsRu::Webhook.parse.
+  module Events
+    # A delivery-status notification (record type "sms_status").
+    #
+    # @!attribute [r] id
+    #   @return [String] the message id
+    # @!attribute [r] status_code
+    #   @return [Integer, nil] the delivery status code (per /sms/status)
+    # @!attribute [r] created_at
+    #   @return [Time, nil] when SMS.ru created the status
+    # @!attribute [r] raw
+    #   @return [Array<String>] every line of the original record
+    class SmsStatus < Data.define(:id, :status_code, :created_at, :raw)
+      include DeliveryStatus
+
+      # @return [String] the wire record type
+      def type = "sms_status"
+    end
+
+    # A call-authorization notification (record type "callcheck_status").
+    #
+    # @!attribute [r] id
+    #   @return [String] the check id (the one returned by SmsRu::CallCheck#add)
+    # @!attribute [r] status_code
+    #   @return [Integer, nil] the check status code (per /callcheck/status)
+    # @!attribute [r] created_at
+    #   @return [Time, nil] when SMS.ru created the status
+    # @!attribute [r] raw
+    #   @return [Array<String>] every line of the original record
+    class CallcheckStatus < Data.define(:id, :status_code, :created_at, :raw)
+      # @return [String] the wire record type
+      def type = "callcheck_status"
+
+      # @return [Boolean] true when the user placed the authorizing call (code 401)
+      def confirmed? = status_code == 401
+
+      # @return [Boolean] true when the authorization window elapsed (code 402)
+      def expired? = status_code == 402
+    end
+
+    # SMS.ru's periodic heartbeat record (record type "test").
+    #
+    # @!attribute [r] created_at
+    #   @return [Time, nil] when SMS.ru sent the heartbeat
+    # @!attribute [r] raw
+    #   @return [Array<String>] every line of the original record
+    class Test < Data.define(:created_at, :raw)
+      # @return [String] the wire record type
+      def type = "test"
+    end
+
+    # Any record type this gem does not model explicitly. `raw` keeps every line.
+    #
+    # @!attribute [r] type
+    #   @return [String] the wire record type
+    # @!attribute [r] raw
+    #   @return [Array<String>] every line of the original record
+    class Unknown < Data.define(:type, :raw)
+    end
+  end
+end

data/lib/sms_ru/my.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Account information: balance, daily limit, free quota, and approved sender
+  # names. Reached via SmsRu#my, e.g. `client.my.balance`.
+  class My
+    # @api private
+    # @param request [Method] the client's bound `request` method
+    def initialize(request)
+      @request = request
+    end
+
+    # @return [Float] the current account balance, in rubles
+    # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+    def balance = @request.call("/my/balance")["balance"]
+
+    # @return [SmsRu::Limit] the daily sending limit and today's usage
+    # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+    def limit = Limit.build(@request.call("/my/limit"))
+
+    # @return [SmsRu::FreeLimit] the free-message allowance and today's usage
+    # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+    def free_limit = FreeLimit.build(@request.call("/my/free"))
+
+    # @return [Array<String>] the approved sender names on the account
+    # @raise [SmsRu::ResponseError] if SMS.ru rejects the request
+    def senders = @request.call("/my/senders")["senders"] || []
+  end
+end

data/lib/sms_ru/statuses.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class SmsRu
+  # Delivery status codes returned by /sms/status and carried in `sms_status`
+  # webhooks. See https://sms.ru/api/status for the authoritative list.
+  module Statuses
+    # The message id was not found.
+    NOT_FOUND = -1
+    # Accepted and waiting in the SMS.ru queue.
+    QUEUED = 100
+    # Being transmitted to the mobile operator.
+    SENT_TO_OPERATOR = 101
+    # Handed to the operator; in transit to the handset.
+    IN_TRANSIT = 102
+    # Delivered to the handset.
+    DELIVERED = 103
+    # Not delivered: the message's time-to-live expired.
+    EXPIRED = 104
+    # Not delivered: deleted by the operator.
+    DELETED = 105
+    # Not delivered: handset malfunction.
+    PHONE_FAILURE = 106
+    # Not delivered: unknown reason.
+    UNKNOWN_FAILURE = 107
+    # Not delivered: rejected by the operator.
+    REJECTED = 108
+    # Delivered and read (where the channel reports it).
+    READ = 110
+    # Not delivered: no route to the number.
+    NO_ROUTE = 150
+
+    # Codes for a message still on its way (no final outcome yet).
+    PENDING = [QUEUED, SENT_TO_OPERATOR, IN_TRANSIT].freeze
+    # Codes for a message that will not be delivered.
+    FAILED = [EXPIRED, DELETED, PHONE_FAILURE, UNKNOWN_FAILURE, REJECTED, NO_ROUTE].freeze
+  end
+
+  # Delivery-state predicates shared by SmsRu::Status and
+  # SmsRu::Events::SmsStatus. The including object must expose `status_code`.
+  module DeliveryStatus
+    # @return [Boolean] true once the message reached the handset (code 103)
+    def delivered? = status_code == Statuses::DELIVERED
+
+    # @return [Boolean] true while the message is still in transit (codes 100–102)
+    def pending? = !status_code.nil? && Statuses::PENDING.include?(status_code)
+
+    # @return [Boolean] true when the message will not be delivered (codes 104–108, 150)
+    def failed? = !status_code.nil? && Statuses::FAILED.include?(status_code)
+  end
+end