sms_traffic_sdk 0.0.8 → 0.2.0

data/lib/sms_traffic/client.rb

@@ -1,78 +1,148 @@
 require 'net/http'
+require 'openssl'
+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
-    class << self
-      attr_reader :uri
+    ENDPOINT = 'multi.php'.freeze
+    FILTERED = '[FILTERED]'.freeze
+    FILTERED_PARAMS = %i[login password message].freeze
+    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
 
-      # @param phone [String] phone number
+    class << self
+      # @param phone [String] phone number or phone numbers separated by comma
       # @param message [String] message
-      # @param originator [String] originator (subject)
+      # @param originator [String] originator (subject), defaults to the configured one
       # @param options [Hash] additional options
+      # @return [DeliverReply]
+      # @raise [ConnectionError, HttpError, ApiError]
       def deliver(phone, message, originator = nil, **options)
         originator ||= SmsTraffic.configuration.originator
-        form_data = deliver_params(phone, message, originator, **options)
-        response = perform_request(form_data)
-        Response.new(response, type: :deliver)
+        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)
+        request(StatusReply, status_params(sms_ids), read_only: true)
       end
 
-      # @param message_id [String] message id
-      def status(*message_ids)
-        form_data = status_params(message_ids)
-        response = perform_request(form_data)
-        Response.new(response, type: :status)
+      # @return [AccountReply]
+      # @raise [ConnectionError, HttpError, ApiError]
+      def balance
+        request(AccountReply, account_params, read_only: true)
       end
 
       private
 
-      # @return [Net::HTTP]
-      def connection
-        host, logger = SmsTraffic.configuration.values_at(:host, :logger)
+      # 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
 
-        @uri ||= URI.join(host, 'multi.php')
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.read_timeout = 30
-        http.use_ssl = (uri.scheme == 'https')
-        http.set_debug_output(logger)
-        http
+      # 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 [Net::HTTPResponse]
-      def perform_request(form_data)
-        connection.start do |http|
+      # @return [String] response body
+      def post(form_data, host)
+        config = SmsTraffic.configuration
+        uri    = URI.join(host, ENDPOINT)
+        log("request POST #{uri} #{filter(form_data)}")
+
+        response = perform(uri, form_data, config)
+        log("response #{response.code} (#{response.body.to_s.bytesize} bytes)")
+        successful_body(response)
+      rescue *CONNECTION_ERRORS => e
+        raise ConnectionError, "#{e.class}: #{e.message}"
+      end
+
+      def successful_body(response)
+        raise HttpError.new(response.code.to_i, response.body) unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
+      end
+
+      def perform(uri, form_data, config)
+        options = { use_ssl: uri.scheme == 'https', open_timeout: config.open_timeout,
+                    read_timeout: config.read_timeout }
+        Net::HTTP.start(uri.host, uri.port, **options) do |http|
           request = Net::HTTP::Post.new(uri.request_uri)
           request.set_form_data(form_data)
           http.request(request)
         end
       end
 
-      # @param phone [String] phone number or phone numbers separated by comma
-      # @param message [String] message
-      # @param originator [String] originator (subject)
-      # @param options [Hash] additional options
-      # @return [Hash<Symbol, String|Integer>]
+      def log(line)
+        config = SmsTraffic.configuration
+        config.logger.debug("[SmsTraffic] #{line}") if config.debug
+      end
+
+      def filter(form_data)
+        form_data.to_h { |key, value| [key, FILTERED_PARAMS.include?(key) ? FILTERED : value] }
+      end
+
       def deliver_params(phone, message, originator, **options)
         {
           login:        SmsTraffic.configuration.login,
           password:     SmsTraffic.configuration.password,
           phones:       phone,
-          message:      message,
+          message:,
           want_sms_ids: 1,
           rus:          5,
-          originator:   originator
+          originator:
         }.merge(options)
       end
 
-      # @param message_ids [Array<String>] message ids
-      # @return [Hash<Symbol, String|Integer>]
-      def status_params(*message_ids)
-        {
-          login:     SmsTraffic.configuration.login,
-          password:  SmsTraffic.configuration.password,
-          operation: 'status',
-          sms_id:    message_ids.join(',')
-        }
+      def status_params(sms_ids)
+        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

@@ -1,75 +1,34 @@
-require 'singleton'
 require 'nori'
 
 module SmsTraffic
   class Configuration
-    include Singleton
+    ATTRIBUTES = %i[
+      login password host fallback_host originator debug logger open_timeout read_timeout validate_phone xml_parser
+    ].freeze
 
-    attr_accessor :login, :password, :host, :originator, :debug, :logger, :xml_parser, :validate_phone
+    # 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
-      self.debug          = default_configuration[:debug]
-      self.logger         = default_configuration[:logger]
-      self.xml_parser     = default_configuration[:xml_parser]
-      self.validate_phone = default_configuration[:validate_phone]
-      super
+      reset!
     end
 
     def reset!
-      default_configuration.each do |key, value|
-        send("#{key}=", value)
-      end
+      ATTRIBUTES.each { |attribute| public_send("#{attribute}=", DEFAULTS[attribute]) }
+      self.xml_parser = Nori.new(advanced_typecasting: false)
     end
 
     def validate!
-      validation_rules.each do |key, value|
-        raise ArgumentError, "#{key} should be defined for #{self}." if value.nil?
-      end
+      raise ArgumentError, 'login should be defined' if login.nil?
+      raise ArgumentError, 'password should be defined' if password.nil?
+      raise ArgumentError, 'host should be defined' if host.nil?
+      raise ArgumentError, 'logger should be defined when debug is enabled' if debug && logger.nil?
     end
 
     def to_h
-      {
-        login:      login,
-        password:   password,
-        host:       host,
-        originator: originator,
-        debug:      debug,
-        logger:     logger,
-        xml_parser: xml_parser
-      }
-    end
-
-    def values_at(*keys)
-      to_h.values_at(*keys)
-    end
-
-    private
-
-    def default_configuration
-      {
-        login:          nil,
-        password:       nil,
-        host:           nil,
-        originator:     nil,
-        debug:          false,
-        logger:         $stdout,
-        xml_parser:     default_xml_parser,
-        validate_phone: true
-      }
-    end
-
-    def validation_rules
-      {
-        'Login'        => login,
-        'Password'     => password,
-        'Server'       => host,
-        'Originator'   => originator,
-        'Debug logger' => debug && !logger ? nil : true
-      }
-    end
-
-    def default_xml_parser
-      @default_xml_parser ||= Nori.new(advanced_typecasting: true).freeze
+      ATTRIBUTES.to_h { |attribute| [attribute, public_send(attribute)] }
     end
   end
 end

data/lib/sms_traffic/errors.rb

@@ -0,0 +1,45 @@
+module SmsTraffic
+  class Error < StandardError; end
+
+  # Network or TLS failure; the original exception is available as +cause+.
+  class ConnectionError < Error; end
+
+  # Non-2xx HTTP status.
+  class HttpError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body   = body
+      super("HTTP #{status}")
+    end
+  end
+
+  # HTTP 200 reply whose `result` is not `OK` (`ERROR`, `ERRO`).
+  class ApiError < Error
+    attr_reader :code, :description
+
+    def initialize(code, description)
+      @code        = code
+      @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

@@ -1,55 +1,80 @@
 module SmsTraffic
   class Sms
+    PHONE_FORMAT = /\A\d{11,}\z/
+
     attr_accessor :phone, :message, :originator
-    attr_reader :id, :status, :errors, :response
+    attr_reader :id, :status, :errors, :reply
 
     def initialize(phone, message, originator: nil)
       @phone      = phone
       @message    = message
       @originator = originator || SmsTraffic.configuration.originator
-      @response   = nil
+      @reply      = nil
       @status     = 'not-sent'
       @errors     = []
       validate!
     end
 
-    def deliver # rubocop:disable Metrics/MethodLength
-      # @type [Client::Response]
-      @response = Client.deliver(phone, message, originator)
-
-      unless @response.success?
-        @errors << @response.error_description
-        return false
-      end
+    # @return [Boolean] true when the provider enqueued the sms
+    def deliver
+      @reply = Client.deliver(phone, message, originator)
 
-      # @type [Client::Response::Reply]
-      reply = @response.reply
-
-      if reply.ok?
-        @status = 'sent'
-        @id     = reply.sms_id || reply.sms_ids.values.first
-        true
-      else
-        @errors << (reply.error_description || 'Sms has been not enqueued')
-        false
-      end
+      reply.ok? ? mark_sent : add_error(reply.error_description)
+      reply.ok?
+    rescue SmsTraffic::Error => e
+      add_error(e.message)
+      false
     end
 
+    # @return [String] the current status; unchanged when the check fails
     def update_status
       return status if id.nil?
 
-      response = Client.status(id)
-      return response.code unless response.success?
+      apply_entry(Client.status(id).entry(id))
+      status
+    rescue SmsTraffic::Error => e
+      add_error(e.message)
+      status
+    end
+
+    # @return [Boolean] the stored status is a final provider status
+    def final?
+      Status.final?(status)
+    end
 
-      @status = response.reply.status.downcase
+    # @return [Boolean] the stored status is Delivered
+    def delivered?
+      Status.delivered?(status)
     end
 
     private
 
+    def mark_sent
+      @status = 'sent'
+      @id     = reply.sms_id
+    end
+
+    def add_error(error)
+      @errors << error
+    end
+
+    def apply_entry(entry)
+      if entry&.error?
+        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
+    end
+
     def validate! # rubocop:disable Metrics/AbcSize
       raise ArgumentError, "Phone should be assigned to #{self.class}." if phone.nil?
 
-      if SmsTraffic.configuration.validate_phone && phone.to_s !~ /^[0-9]{11,}$/
+      if SmsTraffic.configuration.validate_phone && !PHONE_FORMAT.match?(phone.to_s)
         raise ArgumentError, 'Phone number should contain only numbers. Minimum length is 11.'
       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.0.8'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/sms_traffic.rb

@@ -1,19 +1,17 @@
-require 'zeitwerk'
-
-loader = Zeitwerk::Loader.for_gem
-loader.ignore("#{__dir__}/sms_traffic/version.rb")
-loader.enable_reloading
-loader.setup
-
 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'
 
 module SmsTraffic
   class << self
     def configuration
-      @configuration ||= Configuration.instance
+      @configuration ||= Configuration.new
     end
 
-    def configure(&_block)
+    def configure
       yield(configuration) if block_given?
       configuration.validate!
     end

data/lib/sms_traffic_sdk.rb

@@ -0,0 +1 @@
+require_relative 'sms_traffic'

metadata

@@ -1,96 +1,90 @@
 --- !ruby/object:Gem::Specification
 name: sms_traffic_sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.2.0
 platform: ruby
 authors:
 - David Rybolovlev
-bindir: exe
+autorequire:
+bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
-  name: nori
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '1.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '1.12'
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: nori
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.8'
 description: |-
   Ruby Gem as a SDK for interacting with the SMS Traffic HTTP API (smstraffic.ru/api).
                           This gem provides a convenient way to integrate SMS Traffic services into Ruby applications,
                           enabling tasks such as sending SMS messages, checking delivery status, and others.
 email:
 - i@golifox.ru
-executables:
-- konsierge-sms.rb
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".env.template"
-- ".fasterer.yml"
-- ".github/workflows/ci.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".tool-versions"
-- Gemfile
+- CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
-- exe/konsierge-sms.rb
 - 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/response.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
-- sms_traffic_sdk.gemspec
-homepage: https://github.com/golifox/sms_traffic
+- lib/sms_traffic_sdk.rb
+homepage: https://github.com/golifox/sms_traffic_sdk
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/golifox/sms_traffic_sdk
+  changelog_uri: https://github.com/golifox/sms_traffic_sdk/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -98,14 +92,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Send sms via SmsTraffic service.
 test_files: []

data/.env.template

@@ -1,4 +0,0 @@
-SMS_TRAFFIC_HOST=SMS_TRAFFIC_HOST
-SMS_TRAFFIC_LOGIN=SMS_TRAFFIC_LOGIN
-SMS_TRAFFIC_PASSWORD=SMS_TRAFFIC_PASSWORD
-SMS_TRAFFIC_ORIGINATOR=SMS_TRAFFIC_ORIGINATOR

data/.fasterer.yml

@@ -1,2 +0,0 @@
-speedups:
-  fetch_with_argument_vs_block: false