sms_traffic_sdk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c877028062a36207636853033e3e623612a7ae44daf41d91686d86840f3b75c8
-  data.tar.gz: bd57b25436c7ea9e76d0e68b213730e7f77cf271f28c170d70234a2080e38a97
+  metadata.gz: 7073f3fdf9537cf98008d5c6fac2bbc28457fbe4ef05852ccfd4e3b3a4606fbc
+  data.tar.gz: 7ad131b8ca90beebf7d4e227fa4031655bdc49d7e5db4f12c7ee11763cde8e0a
 SHA512:
-  metadata.gz: 47f4123facc0dcb03f1fbf072cc266199df3fcf7483d6189fdfcee257988d188bec2607aae674575c9efb3153b36bdf69c9a6ac8c9af972bfdc878c0ca4d8577
-  data.tar.gz: 96bf4d2e9ea69cc8d6aad0aa87165f57e88b5163b00fffd034af98ee269d87f257cffdce2731e5793bdb6c539f213f06420db805978591da118b3bcf5cf6cb6c
+  metadata.gz: f22009b2e84816ea0ad7294fd80ec8810dfc99c4ad46a7c66e9f9604f837c31fe5d6ae996639e776cb79501523b50257d20390069412993c704b2456ed3b5fb7
+  data.tar.gz: 4dc45cb30d25dd521d716f16bcb7a4ae530ee9fa3b8d14f0b8ec0cfde6a479c81d41268b1015a7518bdd16d79a11fc4f8c5663d2e8266dc7f34c1d0415202843

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.2.0 - 2026-11-03
+
+### Added
+
+- `Configuration#fallback_host` (default `nil`). When set, the client repeats a request once on that host after a
+  connection failure that proves the server was not reached (`SocketError`, `Errno::ECONNREFUSED`,
+  `Errno::EHOSTUNREACH`, `Errno::ENETUNREACH`, `Net::OpenTimeout`) or after API error 1000. `Client.status` and
+  `Client.balance` also retry after any `ConnectionError` and HTTP 5xx; `Client.deliver` never does, because the
+  provider may already have queued the SMS. With `debug`, the retry is logged in one line without credentials.
+- `Client.balance` returns an `AccountReply`; `AccountReply#balance` is a `BigDecimal` (units as sent by the
+  provider). `bigdecimal` is a runtime dependency.
+- `SmsTraffic::Status` (`FINAL`, `INTERMEDIATE`), `StatusReply::Entry#final?` / `#delivered?`, the same methods on
+  `StatusReply` (optional `sms_id`) and `Sms#final?` / `#delivered?`.
+- `ApiError#retryable?`, `#access_denied?`, `#insufficient_funds?` and `#blocked_phone?`.
+
+### Fixed
+
+- A provider reply with `<result>ERRO</result>` (the spelling in the provider's own example) is now an
+  `ApiError`. `Reply#api_error?` is true for any present `result` other than `OK`.
+- `Sms#update_status` no longer records "No status returned" for an empty `<status>` element (an intermediate
+  provider status); the status stays `sent`. `StatusReply::Entry#status_reported?` tells an empty status from an
+  absent one.
+
 ## 0.1.0 - 2026-11-03
 
 ### Breaking changes

data/README.md

@@ -13,6 +13,8 @@ sending of SMS messages and checking delivery statuses.
 
 - Send SMS messages to single or multiple recipients.
 - Check the delivery status of sent messages.
+- Read the account balance.
+- Fail over to the provider's backup host.
 - **TODO:** Support for various message formats and encodings.
 
 
@@ -44,6 +46,7 @@ SmsTraffic.configure do |config|
   config.login          = 'login'
   config.password       = 'password'
   config.host           = 'https://api.smstraffic.ru'
+  config.fallback_host  = 'https://api2.smstraffic.ru' # optional backup host, default nil
   config.originator     = 'default_originator' # optional, can be given per SMS
   config.open_timeout   = 10                   # seconds, default 10
   config.read_timeout   = 30                   # seconds, default 30
@@ -96,7 +99,42 @@ reply.status('8287713301')           # => 'Delivered'; the id may be omitted whe
 ```
 
 Each entry has `sms_id`, `status`, `error`, `submission_date`, `send_date`, `last_status_change_date`
-(strings as sent by the provider), `error?` and `not_found?`.
+(strings as sent by the provider), `error?`, `not_found?`, `final?`, `delivered?` and `status_reported?`
+(true when the provider sent a status element, even an empty one).
+
+### Final and delivered statuses
+
+Provider statuses `Delivered`, `Non Delivered`, `Rejected`, `Expired`, `Deleted` and `Unknown status` are final;
+an empty status and `Buffered SMSC` are intermediate (`SmsTraffic::Status::FINAL` / `INTERMEDIATE`).
+Comparison is case-insensitive.
+
+```ruby
+reply = SmsTraffic::Client.status('8287713301')
+reply.final?     # => true
+reply.delivered? # => true; pass an sms id when the reply has several entries
+reply.entry.final?
+
+sms.update_status
+sms.final?       # => true for a final stored status; false for 'not-sent' and 'sent'
+sms.delivered?   # => true only for 'delivered'
+```
+
+### Balance
+
+```ruby
+SmsTraffic::Client.balance.balance # => 0.10025e5 (BigDecimal), nil when absent or not a number
+```
+
+The value is returned as the provider sends it; its units are not documented and are not converted.
+
+### Fallback host
+
+Set `config.fallback_host` (the provider documents `https://api2.smstraffic.ru`) to repeat a failed request once
+on the backup host. The request is repeated after `SocketError`, `Errno::ECONNREFUSED`, `Errno::EHOSTUNREACH`,
+`Errno::ENETUNREACH`, `Net::OpenTimeout`, or API error 1000 (temporary server problem). `Client.status` and
+`Client.balance` also retry after any `ConnectionError` (read timeout, reset connection, TLS failure) and HTTP 5xx.
+`Client.deliver` does not, since the provider may already have queued the SMS. The error of the last attempt is raised. With `debug`, the retry is
+logged in one line without credentials.
 
 ### Errors
 
@@ -104,7 +142,8 @@ All errors inherit from `SmsTraffic::Error`:
 
 - `SmsTraffic::ConnectionError` - network, timeout or TLS failure (the original exception is `cause`).
 - `SmsTraffic::HttpError` - non-2xx response; has `status` and `body`.
-- `SmsTraffic::ApiError` - the provider replied `ERROR`; has `code` and `description`.
+- `SmsTraffic::ApiError` - the provider replied `ERROR` (or `ERRO`); has `code` and `description`, and the
+  predicates `retryable?` (1000), `access_denied?` (411, 412), `insufficient_funds?` (415) and `blocked_phone?` (432).
 
 ```ruby
 begin

data/lib/sms_traffic/client/account_reply.rb

@@ -0,0 +1,14 @@
+require 'bigdecimal'
+
+module SmsTraffic
+  class Client
+    class AccountReply < Reply
+      # @return [BigDecimal, nil] account balance as sent by the provider (units are not converted); nil when absent
+      #   or not a number
+      def balance
+        value = fetch_value(to_h, :account).to_s.strip
+        BigDecimal(value, exception: false) unless value.empty?
+      end
+    end
+  end
+end

data/lib/sms_traffic/client/deliver_reply.rb

@@ -1,8 +1,6 @@
 module SmsTraffic
   class Client
     class DeliverReply < Reply
-      OK_RESULT = 'OK'.freeze
-
       # @return [Boolean] result is OK and at least one message was queued
       def ok?
         result == OK_RESULT && !messages.empty?

data/lib/sms_traffic/client/reply.rb

@@ -1,6 +1,7 @@
 module SmsTraffic
   class Client
     class Reply
+      OK_RESULT = 'OK'.freeze
       ERROR_RESULT = 'ERROR'.freeze
 
       attr_reader :xml, :to_h
@@ -23,8 +24,9 @@ module SmsTraffic
         fetch_value(to_h, :description)
       end
 
+      # The provider documents `ERROR` but its example replies `ERRO`, so any result other than OK is an error.
       def api_error?
-        result == ERROR_RESULT
+        !result.nil? && result != OK_RESULT
       end
 
       private

data/lib/sms_traffic/client/status_reply.rb

@@ -4,8 +4,14 @@ module SmsTraffic
       NOT_FOUND = /no such message/i
 
       Entry = Struct.new(
-        :sms_id, :status, :error, :submission_date, :send_date, :last_status_change_date, keyword_init: true
+        :sms_id, :status, :status_reported, :error, :submission_date, :send_date, :last_status_change_date,
+        keyword_init: true
       ) do
+        # @return [Boolean] the provider sent a status element, even an empty one (an intermediate status)
+        def status_reported?
+          status_reported == true
+        end
+
         def error?
           !error.nil?
         end
@@ -13,6 +19,14 @@ module SmsTraffic
         def not_found?
           error? && error.match?(NOT_FOUND)
         end
+
+        def final?
+          Status.final?(status)
+        end
+
+        def delivered?
+          Status.delivered?(status)
+        end
       end
 
       # @return [Array<Entry>]
@@ -33,7 +47,7 @@ module SmsTraffic
         define_method(name) { |sms_id = nil| entry(sms_id)&.public_send(name) }
       end
 
-      %i[error? not_found?].each do |name|
+      %i[error? not_found? final? delivered?].each do |name|
         define_method(name) { |sms_id = nil| entry(sms_id)&.public_send(name) || false }
       end
 
@@ -57,6 +71,10 @@ module SmsTraffic
         to_h.empty? ? [] : [to_h]
       end
 
+      def key?(source, key)
+        source.is_a?(Hash) && (source.key?(key.to_s) || source.key?(key.to_sym))
+      end
+
       def blank_to_nil(value)
         stripped = value&.strip
         stripped unless stripped.nil? || stripped.empty?
@@ -66,6 +84,7 @@ module SmsTraffic
         Entry.new(
           sms_id:                  fetch_value(source, :sms_id),
           status:                  fetch_value(source, :status),
+          status_reported:         key?(source, :status),
           error:                   blank_to_nil(fetch_value(source, :error)),
           # The provider spells this field "submition_date".
           submission_date:         fetch_value(source, :submition_date),

data/lib/sms_traffic/client.rb

@@ -4,6 +4,7 @@ require 'uri'
 require_relative 'client/reply'
 require_relative 'client/deliver_reply'
 require_relative 'client/status_reply'
+require_relative 'client/account_reply'
 
 module SmsTraffic
   class Client
@@ -13,6 +14,10 @@ module SmsTraffic
     CONNECTION_ERRORS = [
       SocketError, SystemCallError, IOError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
     ].freeze
+    # Failures that prove the request never reached the server.
+    UNREACHABLE_ERRORS = [
+      SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Net::OpenTimeout
+    ].freeze
 
     class << self
       # @param phone [String] phone number or phone numbers separated by comma
@@ -23,30 +28,65 @@ module SmsTraffic
       # @raise [ConnectionError, HttpError, ApiError]
       def deliver(phone, message, originator = nil, **options)
         originator ||= SmsTraffic.configuration.originator
-        build_reply(DeliverReply, post(deliver_params(phone, message, originator, **options)))
+        request(DeliverReply, deliver_params(phone, message, originator, **options), read_only: false)
       end
 
       # @param sms_ids [Array<String>] sms ids
       # @return [StatusReply]
       # @raise [ConnectionError, HttpError, ApiError]
       def status(*sms_ids)
-        build_reply(StatusReply, post(status_params(sms_ids)))
+        request(StatusReply, status_params(sms_ids), read_only: true)
+      end
+
+      # @return [AccountReply]
+      # @raise [ConnectionError, HttpError, ApiError]
+      def balance
+        request(AccountReply, account_params, read_only: true)
       end
 
       private
 
-      def build_reply(reply_class, body)
-        reply = reply_class.new(body)
+      # Sends the request to the configured host and, when a fallback host is set, repeats it there once if the
+      # failure allows it.
+      def request(reply_class, form_data, read_only:)
+        config = SmsTraffic.configuration
+        attempt(reply_class, form_data, config.host)
+      rescue Error => e
+        raise unless config.fallback_host && retry_on_fallback?(e, read_only:)
+
+        log("retry on #{config.fallback_host} after #{retry_reason(e)}")
+        attempt(reply_class, form_data, config.fallback_host)
+      end
+
+      # Names the root cause and, for an API error, its code; never the message text.
+      def retry_reason(error)
+        reason = (error.cause&.class || error.class).to_s
+        error.is_a?(ApiError) ? "#{reason} #{error.code}" : reason
+      end
+
+      def attempt(reply_class, form_data, host)
+        reply = reply_class.new(post(form_data, host))
         raise ApiError.new(reply.code, reply.description) if reply.api_error?
 
         reply
       end
 
+      # A read-only request is safe to repeat after any transport failure. A deliver is repeated only when the
+      # request never reached the server, as the provider may already have queued the SMS otherwise.
+      def retry_on_fallback?(error, read_only:)
+        case error
+        when ApiError then error.retryable?
+        when ConnectionError then read_only || UNREACHABLE_ERRORS.any? { |klass| error.cause.is_a?(klass) }
+        when HttpError then read_only && error.status >= 500
+        else false
+        end
+      end
+
       # @param form_data [Hash<Symbol, String|Integer>]
       # @return [String] response body
-      def post(form_data)
+      def post(form_data, host)
         config = SmsTraffic.configuration
-        uri    = URI.join(config.host, ENDPOINT)
+        uri    = URI.join(host, ENDPOINT)
         log("request POST #{uri} #{filter(form_data)}")
 
         response = perform(uri, form_data, config)
@@ -94,12 +134,15 @@ module SmsTraffic
       end
 
       def status_params(sms_ids)
-        {
-          login:     SmsTraffic.configuration.login,
-          password:  SmsTraffic.configuration.password,
-          operation: 'status',
-          sms_id:    sms_ids.join(',')
-        }
+        operation_params('status').merge(sms_id: sms_ids.join(','))
+      end
+
+      def account_params
+        operation_params('account')
+      end
+
+      def operation_params(operation)
+        { login: SmsTraffic.configuration.login, password: SmsTraffic.configuration.password, operation: }
       end
     end
   end

data/lib/sms_traffic/configuration.rb

@@ -3,9 +3,12 @@ require 'nori'
 module SmsTraffic
   class Configuration
     ATTRIBUTES = %i[
-      login password host originator debug logger open_timeout read_timeout validate_phone xml_parser
+      login password host fallback_host originator debug logger open_timeout read_timeout validate_phone xml_parser
     ].freeze
 
+    # Attributes not listed here default to nil.
+    DEFAULTS = { debug: false, open_timeout: 10, read_timeout: 30, validate_phone: true }.freeze
+
     attr_accessor(*ATTRIBUTES)
 
     def initialize
@@ -13,16 +16,8 @@ module SmsTraffic
     end
 
     def reset!
-      self.login          = nil
-      self.password       = nil
-      self.host           = nil
-      self.originator     = nil
-      self.debug          = false
-      self.logger         = nil
-      self.open_timeout   = 10
-      self.read_timeout   = 30
-      self.validate_phone = true
-      self.xml_parser     = Nori.new(advanced_typecasting: false)
+      ATTRIBUTES.each { |attribute| public_send("#{attribute}=", DEFAULTS[attribute]) }
+      self.xml_parser = Nori.new(advanced_typecasting: false)
     end
 
     def validate!

data/lib/sms_traffic/errors.rb

@@ -15,7 +15,7 @@ module SmsTraffic
     end
   end
 
-  # HTTP 200 reply whose result is ERROR.
+  # HTTP 200 reply whose `result` is not `OK` (`ERROR`, `ERRO`).
   class ApiError < Error
     attr_reader :code, :description
 
@@ -24,5 +24,22 @@ module SmsTraffic
       @description = description
       super("#{code}: #{description}")
     end
+
+    # Temporary server problem: retry later or use the backup host.
+    def retryable?
+      code.to_i == 1000
+    end
+
+    def access_denied?
+      [411, 412].include?(code.to_i)
+    end
+
+    def insufficient_funds?
+      code.to_i == 415
+    end
+
+    def blocked_phone?
+      code.to_i == 432
+    end
   end
 end

data/lib/sms_traffic/sms.rb

@@ -37,6 +37,16 @@ module SmsTraffic
       status
     end
 
+    # @return [Boolean] the stored status is a final provider status
+    def final?
+      Status.final?(status)
+    end
+
+    # @return [Boolean] the stored status is Delivered
+    def delivered?
+      Status.delivered?(status)
+    end
+
     private
 
     def mark_sent
@@ -53,6 +63,9 @@ module SmsTraffic
         add_error(entry.error)
       elsif entry&.status
         @status = entry.status.downcase
+      elsif entry&.status_reported?
+        # An empty status element is an intermediate provider status: keep the current one.
+        nil
       else
         add_error("No status returned for sms #{id}")
       end

data/lib/sms_traffic/status.rb

@@ -0,0 +1,26 @@
+module SmsTraffic
+  # Provider delivery statuses (HTTP API v1, operation=status).
+  module Status
+    INTERMEDIATE = ['', 'Buffered SMSC'].freeze
+    DELIVERED = 'Delivered'.freeze
+    FINAL = [DELIVERED, 'Non Delivered', 'Rejected', 'Expired', 'Deleted', 'Unknown status'].freeze
+
+    class << self
+      # @param status [String, nil] provider status, compared case-insensitively
+      def final?(status)
+        matches?(FINAL, status)
+      end
+
+      def delivered?(status)
+        matches?([DELIVERED], status)
+      end
+
+      private
+
+      def matches?(list, status)
+        value = status.to_s.strip
+        list.any? { |item| item.casecmp?(value) }
+      end
+    end
+  end
+end

data/lib/sms_traffic/version.rb

@@ -1,3 +1,3 @@
 module SmsTraffic
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/sms_traffic.rb

@@ -1,5 +1,6 @@
 require_relative 'sms_traffic/version'
 require_relative 'sms_traffic/errors'
+require_relative 'sms_traffic/status'
 require_relative 'sms_traffic/configuration'
 require_relative 'sms_traffic/client'
 require_relative 'sms_traffic/sms'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sms_traffic_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - David Rybolovlev
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -53,12 +67,14 @@ files:
 - README.md
 - lib/sms_traffic.rb
 - lib/sms_traffic/client.rb
+- lib/sms_traffic/client/account_reply.rb
 - lib/sms_traffic/client/deliver_reply.rb
 - lib/sms_traffic/client/reply.rb
 - lib/sms_traffic/client/status_reply.rb
 - lib/sms_traffic/configuration.rb
 - lib/sms_traffic/errors.rb
 - lib/sms_traffic/sms.rb
+- lib/sms_traffic/status.rb
 - lib/sms_traffic/version.rb
 - lib/sms_traffic_sdk.rb
 homepage: https://github.com/golifox/sms_traffic_sdk