sms-pilot-api-v1 0.0.3 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c7152ee4bb497bc839d159e8cdc7bb9b9b5735179a8c5ced0176924acd53727
-  data.tar.gz: 9dfa498a10e6b68c6115ed42ff4a6b678a18b4b31ad2532f1092095d9efe9a60
+  metadata.gz: fb76209647bdda0c204159de74aeb9afd98cb01b6d8979ae9857407e76ff61b1
+  data.tar.gz: 6bcea2c04668198bcbf07babcfec333e90e1cb920a06eb9cb371d2a291f1ca66
 SHA512:
-  metadata.gz: fb942ccb1bfab86c399c1c0567885d8ca0b43ca54f3e832d6316d6ad2838beb7d1ade363f537247aff90aa8090886a78f2ac0187c9e82c077ade0944bb4e5497
-  data.tar.gz: 6ca91958e3d50371b7a48c7679b6a6285f6ff9d8389e2e2a0605e02f6eea85359e2b873366351d762fe48bad1bf288c3f9d94244fa8c0ac5a09a1c85230ae5de
+  metadata.gz: b21cecdb44421ffe495e0963b9928dedab5e8740680f94937b85eceb1de256bdef23d967e8012e46c124f3a24f27f3fb8eedd541391964ec6dcdd83c21af7300
+  data.tar.gz: a693db49eac9e534a6be8c3132804376783a42c56ae532782cd6459f9c516c6f4610ff234d4a9cb522fe30019c64724c042a649e43a475c6c10bbe7e65baf27e

data/.gitignore

@@ -1,3 +1,5 @@
+.DS_Storage
+.rspec_status
 /.bundle/
 /.yardoc
 /_yardoc/
@@ -6,6 +8,3 @@
 /pkg/
 /spec/reports/
 /tmp/
-
-# rspec failure tracking
-.rspec_status

data/.yardopts

@@ -0,0 +1,8 @@
+--private
+--protected
+-m markdown
+-M redcarpet
+-
+lib/**/*.rb
+CHANGELOG.md
+README.md

data/CHANGELOG.md

@@ -1,5 +1,28 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2021-05-06
+## [0.0.7] - 9 May 2021
+
+- Returns original values from validation methods
+- Offloads parsing response body to a method
+- Improves documentation
+- Adds CodeClimate badges
+- Writes tests for `#initialize` and `#api_key`
+
+## [0.0.6] - 9 May 2021
+
+- Corrects cost type
+- Switches to PRY in console
+
+## [0.0.5] - 9 May 2021
+
+- Adds locale support (RU / EN)
+
+## [0.0.4] - 9 May 2021
+
+- Drop dependence on HTTP.rb gem
+- Corrects what `#send_sms` returns (could return String errors instead of Booleans)
+- Adds extensive [documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client) via YARD & RubyDoc
+
+## [0.0.3] - 6 May 2021
 
 - Initial release

data/Gemfile

@@ -5,5 +5,6 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in gemspec
 gemspec
 
+gem "pry"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -1,32 +1,17 @@
 PATH
   remote: .
   specs:
-    sms-pilot-api-v1 (0.1.0)
-      http (>= 4.4)
+    sms-pilot-api-v1 (0.0.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
-      public_suffix (>= 2.0.2, < 5.0)
+    coderay (1.1.3)
     diff-lcs (1.4.4)
-    domain_name (0.5.20190701)
-      unf (>= 0.0.5, < 1.0.0)
-    ffi (1.15.0)
-    ffi-compiler (1.0.1)
-      ffi (>= 1.0.0)
-      rake
-    http (4.4.1)
-      addressable (~> 2.3)
-      http-cookie (~> 1.0)
-      http-form_data (~> 2.2)
-      http-parser (~> 1.2.0)
-    http-cookie (1.0.3)
-      domain_name (~> 0.5)
-    http-form_data (2.3.0)
-    http-parser (1.2.3)
-      ffi-compiler (>= 1.0, < 2.0)
-    public_suffix (4.0.6)
+    method_source (1.0.0)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rake (13.0.3)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
@@ -41,17 +26,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.7.7)
 
 PLATFORMS
   x86_64-darwin-17
 
 DEPENDENCIES
+  pry
   rake (~> 13.0)
   rspec (~> 3.0)
   sms-pilot-api-v1!
 
 BUNDLED WITH
-   2.2.11
+   2.2.17

data/README.md

@@ -1,6 +1,11 @@
 # SmsPilot API v1 client
 
-Обёртка отправки GET-запроса на API endpoint сервиса SMS Pilot (API v1) для удобства доступа к ошибкам, статусам, цене SMS и т. п.
+[![Gem Version](https://badge.fury.io/rb/sms-pilot-api-v1.svg)](https://badge.fury.io/rb/sms-pilot-api-v1)
+[![Maintainability](https://api.codeclimate.com/v1/badges/42765c3098d5f531a3f7/maintainability)](https://codeclimate.com/github/sergeypedan/sms-pilot-api-v1/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/42765c3098d5f531a3f7/test_coverage)](https://codeclimate.com/github/sergeypedan/sms-pilot-api-v1/test_coverage)
+[![Inch CI documentation](https://inch-ci.org/github/sergeypedan/sms-pilot-api-v1.svg?branch=master&style=flat)](https://inch-ci.org/github/sergeypedan/sms-pilot-api-v1)
+
+Simple wrapper around SMS pilot API v1. Version 1 because it returns more data within its standard response.
 
 ## Installation
 
@@ -16,7 +21,7 @@ from GitHub:
 gem "sms-pilot-api-v1", git: "https://github.com/sergeypedan/sms-pilot-api-v1.git"
 ```
 
-## Usage
+## Playground
 
 Test sending SMS from console with a test API key (find it at the end of this page):
 
@@ -25,24 +30,36 @@ cd $(bundle info sms-pilot-api-v1 --path)
 bin/console
 ```
 
+
+## Usage
+
 ### Initialize
 
 ```ruby
-client = SmsPilot::Client.new(api_key: "XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ")
-#<SmsPilot::Client:0x00007fb1c602d490 @api_key="XXXXX...", @error=nil, @response_status=nil, @response_headers=nil, @response_body=nil, @response_data={}, @url=nil>
+require "sms_pilot"
+
+key = "XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ"
+
+client = SmsPilot::Client.new(api_key: key)
+client = SmsPilot::Client.new(api_key: key, locale: :en) # Available locales are [:en, :ru]
 ```
 
+Method [documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client#initialize-instance_method) at RubyDoc.
+
 ### Before sending
 
+There are a bunch of methods describing the state of affairs:
+
 ```ruby
 client.api_key          # => "YOUR API KEY"
 client.balance          # => nil
+client.broadcast_id     # => nil
 client.error            # => nil
 client.phone            # => nil
 client.rejected?        # => false
 client.response_body    # => nil
 client.response_data    # => {}
-client.response_headers # => nil
+client.response_headers # => {}
 client.response_status  # => nil
 client.sender_blocked?  # => false
 client.sms_cost         # => nil
@@ -51,20 +68,27 @@ client.sms_status       # => nil
 client.url              # => nil
 ```
 
+before the request is sent they return obvious nils or empty structures; after the request they are populated with data.
+
+See [structured documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client) for those methods at RubyDoc.
+
 ### Sending SMS
 
 ```ruby
-client.send_sms("+7 (902) 123-45-67", "Привет, мир!") # => true
+client.send_sms("+7 (902) 123-45-67", "Привет, мир!")
+# => true
 ```
 
 Returns result of `sms_sent?`, so it’s either `true` or `false`.
 
+Method [documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client#send_sms-instance_method) at RubyDoc.
 
 ### Sending SMS succeeded
 
 ```ruby
 client.api_key          # => "YOUR API KEY"
 client.balance          # => 20006.97
+client.broadcast_id     # => 10000
 client.error            # => nil
 client.phone            # => "79021234567"
 client.rejected?        # => false
@@ -84,6 +108,7 @@ client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&form
 ```ruby
 client.api_key          # => "YOUR API KEY"
 client.balance          # => nil
+client.broadcast_id     # => 10000
 client.error            # => "Неправильный API-ключ (см. настройки API в личном кабинете) (код ошибки: 101)"
 client.phone            # => "79021234567"
 client.rejected?        # => true
@@ -103,6 +128,7 @@ client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&form
 ```ruby
 client.api_key          # => "YOUR API KEY"
 client.balance          # => nil
+client.broadcast_id     # => 10000
 client.error            # => "HTTP request failed with code 404"
 client.phone            # => "79021234567"
 client.rejected?        # => false
@@ -120,9 +146,9 @@ client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&form
 
 ## SMS pilot API docs
 
-- [web version](https://smspilot.ru/apikey.php) — см. вкладку PHP, в остальных ничего нет
+- [Web version](https://smspilot.ru/apikey.php) — см. вкладку PHP, в остальных ничего нет
 - [PDF version](https://smspilot.ru/download/SMSPilotRu-HTTP-v1.9.19.pdf) — тут намного подробнее
-- [Коды ошибок](https://smspilot.ru/apikey.php#err)
+- [API error code](https://smspilot.ru/apikey.php#err)
 
 
 ## Test API key
@@ -140,10 +166,11 @@ SMS sent:
 
 ```json
 {
+  "balance": "11908.50",
+  "cost": "1.68",
   "send": [
     { "server_id": "10000", "phone": "79021234567", "price": "1.68", "status": "0" }
-  ],
-  "balance": "11908.50", "cost": "1.68"
+  ]
 }
 ```
 
@@ -158,3 +185,8 @@ SMS rejected:
   }
 }
 ```
+
+
+## Documentation
+
+See [structured documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client) at RubyDoc.

data/bin/console

@@ -8,8 +8,5 @@ require "sms_pilot"
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require "pry"
+Pry.start

data/lib/sms_pilot.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+# Module that for now encompasses only API client
+#
+module SmsPilot
+end
+
 require_relative "sms_pilot/version"
 require_relative "sms_pilot/errors"
 require_relative "sms_pilot/client"
-

data/lib/sms_pilot/client.rb

@@ -1,146 +1,461 @@
 # frozen_string_literal: true
 
-require "http"
+require "json"
+require "net/https"
 require "uri"
 
 module SmsPilot
 
-  API_ENDPOINT = "https://smspilot.ru/api.php".freeze
-
+  # @!attribute [r] api_key
+  #   @return [String] your API key
+  #   @example
+  #     client.api_key #=> "XXX..."
+  #
+  # @!attribute [r] error
+  #   Error message returned from the API, combined with the error code
+  #   @example
+  #     client.error #=> "Пользователь временно блокирован (спорная ситуация) (error code: 122)"
+  #   @return [nil, String]
+  #   @see #error_code
+  #   @see #error_description
+  #
+  # @!attribute [r] locale
+  #   Chosen locale (affects only the language of errors)
+  #
+  #   @return [Symbol]
+  #   @example
+  #     client.locale #=> :ru
+  #
+  # @!attribute [r] phone
+  #   @return [nil, String] phone after normalization
+  #   @example
+  #     client.phone #=> "79021234567"
+  #
+  # @!attribute [r] response_body
+  #   Response format is JSON (because we request it that way in {#build_uri}).
+  #   @example
+  #     "{\"send\":[{\"server_id\":\"10000\",\"phone\":\"79021234567\",\"price\":\"1.68\",\"status\":\"0\"}],\"balance\":\"20006.97\",\"cost\":\"1.68\"}"
+  #   @return [nil, String] Unmodified HTTP resonse body that API returned
+  #   @see #response_data
+  #   @see #response_headers
+  #   @see #response_status
+  #
+  # @!attribute [r] response_headers
+  #   @example
+  #     client.response_headers #=>
+  #     {
+  #       "Access-Control-Allow-Origin" => "*",
+  #       "Connection" => "close",
+  #       "Content-Length" => "179",
+  #       "Content-Type" => "application/json; charset=utf-8",
+  #       "Date" => "Thu, 06 May 2021 04:52:58 GMT",
+  #       "Server" => "nginx"
+  #     }
+  #   @return [nil, String] Unmodified HTTP resonse headers that API returned.
+  #   @see #response_body
+  #   @see #response_data
+  #   @see #response_status
+  #
+  # @!attribute [r] response_status
+  #   HTTP status of the request to the API. 200 in case of success.
+  #   @example
+  #     client.response_status #=> 200
+  #
+  #   @return [nil, Integer]
+  #   @see #response_body
+  #   @see #response_data
+  #   @see #response_headers
+  #
   class Client
 
+    # Check current API endpoint URL at {https://smspilot.ru/apikey.php#api1}
+    #
+    API_ENDPOINT = "https://smspilot.ru/api.php".freeze
+
+    # Locale influences only the language of API errors
+    #
+    AVAILABLE_LOCALES = [:ru, :en].freeze
+
     attr_reader :api_key
     attr_reader :error
+    attr_reader :locale
     attr_reader :phone
     attr_reader :response_body
-    attr_reader :response_data
     attr_reader :response_headers
     attr_reader :response_status
-    attr_reader :url
-
 
-    def initialize(api_key:)
-      fail TypeError, "API key must be a String, you pass a #{api_key.class} (#{api_key})" unless api_key.is_a? String
-      fail TypeError, "API key cannot be empty" if api_key == ""
 
-      @api_key          = api_key
+    # @param api_key [String]
+    # @param locale [Symbol]
+    #
+    # @return [SmsPilot::Client]
+    # @raise [SmsPilot::InvalidAPIkeyError] if you pass anything but a non-empty String
+    # @raise [SmsPilot::InvalidLocaleError] if you pass anything but <tt>:ru</tt> or <tt>:en</tt>
+    #
+    # @see https://smspilot.ru/my-settings.php Get your production API key here
+    # @see https://smspilot.ru/apikey.php Get your development API key here
+    # @note Current development API key is <tt>"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ"</tt>
+    #
+    # @example
+    #   client = SmsPilot::Client.new(api_key: ENV["SMS_PILOT_API_KEY"])
+    #   client = SmsPilot::Client.new(api_key: ENV["SMS_PILOT_API_KEY"], locale: :en)
+    #
+    def initialize(api_key:, locale: AVAILABLE_LOCALES[0])
+      @api_key          = validate_api_key!(api_key)
       @error            = nil
+      @locale           = validate_locale!(locale)
       @response_status  = nil
-      @response_headers = nil
+      @response_headers = {}
       @response_body    = nil
-      @response_data    = {}
-      @url              = nil
     end
 
-    def send_sms(phone, text)
-      fail TypeError, "`phone` must be a String, you pass a #{phone.class} (#{phone})" unless phone.is_a? String
-      fail TypeError,  "`text` must be a String, you pass a #{ text.class} (#{ text})" unless text.is_a? String
-      fail ArgumentError, "`phone` cannot be empty" if phone == ""
-      fail ArgumentError,  "`text` cannot be empty" if  text == ""
-      fail ArgumentError, "`phone` must contain digits" if phone.scan(/\d/).none?
 
-      @phone = normalize_phone(phone)
-      @url   = build_url(@phone, text)
+    # @!group Main
 
-      response = HTTP.timeout(connect: 15, read: 30).accept(:json).get(@url)
-      @response_status  = response.status.code
-      @response_headers = response.headers.to_h
-      @response_body    = response.body.to_s
+    # Send HTTP request to the API to ask them to transmit your SMS
+    #
+    # @return [Boolean] <tt>true</tt> if the SMS has been sent, <tt>false</tt> otherwise
+    #
+    # @param [String] phone The phone to send the SMS to. In free-form, will be sanitized.
+    # @param [String] message The text of your message.
+    #
+    # @raise [SmsPilot::InvalidPhoneError] if you pass anythig but a String with the <tt>phone</tt> argument
+    # @raise [SmsPilot::InvalidMessageError] if you pass anythig but a String with the <tt>message</tt> argument
+    # @raise [SmsPilot::InvalidMessageError] if your message is empty
+    # @raise [SmsPilot::InvalidPhoneError] if your phone is empty
+    # @raise [SmsPilot::InvalidPhoneError] if your phone has no digits
+    # @raise [URI::InvalidURIError] but is almost impossible, because we provide the URL ourselves
+    #
+    # @example
+    #   client.send_sms("+7 (902) 123-45-67", "Привет, мир!") # => true
+    #
+    def send_sms(phone, message)
+      validate_phone! phone
+      validate_message! message
 
-      unless response.status.success?
-        @error = "HTTP request failed with code #{response.status.code}"
-        return false
-      end
+      @phone = normalize_phone(phone)
+      @uri   = build_uri(@phone, message)
+
+      response = persist_response_details Net::HTTP.get_response(@uri)
 
-      @response_data = JSON.parse @response_body
+      @error = "HTTP request failed with code #{response.code}"   and return false unless response.is_a?(Net::HTTPSuccess)
+      @error = "#{error_description} (error code: #{error_code})" and return false if rejected?
 
-      return @error = "#{error_description} (код ошибки: #{error_code})" if rejected?
-      return true
+      true
 
     rescue JSON::ParserError => error
       @error = "API returned invalid JSON. #{error.message}"
+      return false
 
-    rescue HTTP::Error => error
-      @error = error.message
-
-    rescue => error
+    rescue SocketError, EOFError, IOError, SystemCallError,
+           Timeout::Error, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+           Net::ProtocolError, OpenSSL::SSL::SSLError => error
       @error = error.message
+      return false
     end
 
+    # @!endgroup
+
 
+    # @!group State accessors
+
+    # Your current balance, remaining after sending that latest SMS.
+    #
+    # @return [nil, Float] Always <tt>nil</tt> before you send SMS and if the SMS was not sent, always Float after successfull SMS transmission.
+    # @example
+    #   client.balance #=> 20215.25
+    #
     def balance
-      @response_data["balance"]&.to_f if sms_sent?
+      response_data["balance"]&.to_f if sms_sent?
     end
 
 
-    # Коды ошибок: https://smspilot.ru/apikey.php#err
-    # Расшифровка ошибки пишется в @error
+    # SMS broadcast ID (API documentation calls it “server ID” but it makes no sense, as it is clearly the ID of the transmission, not of a server)
+    #
+    # @example
+    #   client.broadcast_id #=> 10000
+    #
+    # @return [nil, Integer]
+    #
+    # @see #response_data
+    #
+    def broadcast_id
+      @response_data.dig("send", 0, "server_id")&.to_i if sms_sent?
+    end
+
+
+    # Numerical code of the error that occured when sending the SMS. In the range from 0 to 715 (which may change).
+    #
+    # @return [nil, Integer] <tt>nil</tt> is returned before sending SMS. Otherwise <tt>Integer</tt>
+    # @example
+    #   client.error_code #=> 122
+    # @see #error
+    # @see #error_description
+    # @see https://smspilot.ru/apikey.php#err Error codes at the API documentation website
     #
     def error_code
       @response_data.dig("error", "code")&.to_i if rejected?
     end
 
 
-    # Коды ошибок: https://smspilot.ru/apikey.php#err
-    # Расшифровка ошибки пишется в @error
+    # Description of the error that occured when sending the SMS
+    #
+    # @return [nil, String] <tt>nil</tt> is returned before sending SMS. Otherwise <tt>String</tt>
+    # @example
+    #   client.error_description #=> "Пользователь временно блокирован (спорная ситуация)"
+    # @see #error
+    # @see #error_code
+    # @see https://smspilot.ru/apikey.php#err Error codes at the API documentation website
     #
     def error_description
-      @response_data.dig("error", "description_ru") if rejected?
+      method_name = (@locale == :ru) ? "description_ru" : "description"
+      @response_data.dig("error", method_name) if rejected?
     end
 
 
-    # HTTP запрос удался, но API отказался отправлять SMS
+    # Did the API reject your request to send that SMS
+    #
+    # @return [Boolean] <tt>false</tt> is returned before sending SMS. Otherwise the <tt>Boolean</tt> corresponds to whether your request to send an SMS was rejected.
+    # @example
+    #   client.rejected? #=> false
+    #
     def rejected?
       return false if sms_sent?
-      @response_data["error"].is_a? Hash
+      response_data["error"].is_a? Hash
+    end
+
+
+    # Parses <tt>@response_body</tt> and memoizes result in <tt>@response_data</tt>
+    #
+    # @example
+    #   {
+    #     "balance" => "20006.97",
+    #     "cost" => "1.68",
+    #     "send" => [
+    #       {
+    #         "phone" => "79021234567",
+    #         "price" => "1.68",
+    #         "server_id" => "10000",
+    #         "status" => "0"
+    #       }
+    #     ]
+    #   }
+    #
+    # @return [Hash]
+    # @raise [JSON::ParserError] which is rescued in {#send_sms}
+    #
+    # @see #response_body
+    # @see #response_headers
+    # @see #response_status
+    #
+    def response_data
+      return {} unless @response_body
+      @response_data ||= JSON.parse @response_body
     end
 
 
-    # API сообщает, что мы заблокированы
+    # Did the API block you
     #
-    # 105 из-за низкого баланса
-    # 106 за спам/ошибки
-    # 107 за недостоверные учетные данные / недоступна эл. почта / проблемы с телефоном
-    # 122 спорная ситуация
+    # Error code | Description
+    # :---|:------------------
+    # 105 | из-за низкого баланса
+    # 106 | за спам/ошибки
+    # 107 | за недостоверные учетные данные / недоступна эл. почта / проблемы с телефоном
+    # 122 | спорная ситуация
     #
-    # Расшифровка ошибки пишется в @error
+    # @return [Boolean] <tt>nil</tt> is returned before sending SMS. Otherwise the <tt>Boolean</tt> corresponds to whether the API has blocked you.
+    # @example
+    #   client.sender_blocked? #=> false
+    # @see #error
+    # @see https://smspilot.ru/apikey.php#err Error codes at the API documentation website
     #
     def sender_blocked?
       [105, 106, 107, 122].include? error_code
     end
 
 
-    # Цена отправленной только что SMS
+    # The cost of the SMS that has just been sent, in RUB
+    #
+    # @return [nil, Float]
+    # @example
+    #   client.sms_cost #=> 2.63
+    #
     def sms_cost
-      @response_data["cost"] if sms_sent?
+      response_data["cost"]&.to_f if sms_sent?
     end
 
 
-    # API успешно отправил SMS
+    # Has the SMS transmission been a success.
+    #
+    # @return [Boolean] <tt>nil</tt> is returned before sending SMS. Otherwise the <tt>Boolean</tt> corresponds to the result of SMS transmission.
+    # @see #sms_status
+    # @see #rejected?
+    # @see #error
+    #
+    # @example
+    #   client.sms_sent? #=> true
+    #
     def sms_sent?
-      @response_data["send"] != nil
+      response_data["send"] != nil
     end
 
 
-    # Статус доставки SMS
-    # https://smspilot.ru/apikey.php#status
+    # SMS delivery status, as returned by the API
+    #
+    # @return [nil, Integer] <tt>nil</tt> is returned before sending SMS or if the request was rejected. Otherwise an <tt>Integer</tt> in the range of [-2..3] is returned.
+    # @see https://smspilot.ru/apikey.php#status List of available statuses at API documentation website
+    #
+    # Code | Name          | Final? | Description
+    # ----:|:--------------|:-------|:-------------
+    # -2   | Ошибка        | Да     | Ошибка, неправильные параметры запроса
+    # -1   | Не доставлено | Да     | Сообщение не доставлено (не в сети, заблокирован, не взял трубку), PING — не в сети, HLR — не обслуживается (заблокирован)
+    #  0   | Новое         | Нет    | Новое сообщение/запрос, ожидает обработки у нас на сервере
+    #  1   | В очереди     | Нет    | Сообщение или запрос ожидают отправки на сервере оператора
+    #  2   | Доставлено    | Да     | Доставлено, звонок совершен, PING — в сети, HLR — обслуживается
+    #  3   | Отложено      | Нет    | Отложенная отправка, отправка сообщения/запроса запланирована на другое время
+    #
+    # @example
+    #   client.sms_status #=> 2
     #
     def sms_status
       @response_data.dig("send", 0, "status")&.to_i if sms_sent?
     end
 
 
-    private
+    # URL generated by combining <tt>API_ENDPOINT</tt>, your API key, SMS text & phone
+    #
+    # @example
+    #   client.url #=> "https://smspilot.ru/api.php?api_key=XXX&format=json&send=TEXT&to=79021234567"
+    #
+    # @return [nil, String]
+    #
+    def url
+      @uri&.to_s
+    end
+
+    # @!endgroup
+
 
-    def build_url(phone, text)
-      URI.parse(API_ENDPOINT).tap do |url|
-        url.query = URI.encode_www_form({ apikey: @api_key, format: :json, send: text, to: phone })
-      end.to_s
+    # The URI we will send an HTTP request to
+    # @private
+    #
+    # @example
+    #   build_uri("79021234567", "Hello, World!")
+    #   #=> #<URI::HTTPS https://smspilot.ru/api.php?apikey=XXX…&format=json&send=Hello%2C+World%21&to=79021234567>
+    #
+    # @return [URI]
+    # @raise [URI::InvalidURIError] but is almost impossible, because we provide the URL ourselves
+    #
+    # @see #api_key
+    # @see #phone
+    # @see #validate_phone!
+    # @see #validate_message!
+    #
+    private def build_uri(phone, text)
+      URI.parse(API_ENDPOINT).tap do |uri|
+        uri.query = URI.encode_www_form({ apikey: @api_key, format: :json, send: text, to: phone })
+      end
     end
 
-    def normalize_phone(phone)
+
+    # Cleans up your phone from anything but digits. Also replaces 8 to 7 if it is the first digit.
+    #
+    # @private
+    # @param [String] phone
+    # @return [String]
+    #
+    # @example
+    #   normalize_phone("8 (902) 123-45-67") #=> 79021234567
+    #   normalize_phone("+7-902-123-45-67")  #=> 79021234567
+    #
+    private def normalize_phone(phone)
       phone.gsub(/[^0-9]/, '').sub(/^8/, '7').gsub('+7', '8')
     end
 
+
+    # Saves response details into instance variables
+    # @private
+    #
+    # @return [response]
+    # @raise [TypeError] unless a Net::HTTPResponse passed
+    #
+    private def persist_response_details(response)
+      fail TypeError, "Net::HTTPResponse expected, you pass a #{response.class}" unless response.is_a? Net::HTTPResponse
+      @response_body    = response.body
+      @response_status  = response.code.to_i
+      @response_headers = response.each_capitalized.to_h
+      response
+    end
+
+
+    # @!group Validations
+
+    # Validates api_key
+    #
+    # @private
+    # @return [String] the original value passed into the method, only if it was valid
+    # @param [String] api_key
+    #
+    # @raise [SmsPilot::InvalidError] if api_key is not a String
+    # @raise [SmsPilot::InvalidError] if api_key is an empty String
+    #
+    private def validate_api_key!(api_key)
+      fail SmsPilot::InvalidAPIkeyError, "API key must be a String, you pass a #{api_key.class} (#{api_key})" unless api_key.is_a? String
+      fail SmsPilot::InvalidAPIkeyError, "API key cannot be empty" if api_key == ""
+      return api_key
+    end
+
+
+    # Validates locale
+    #
+    # @private
+    # @return [Symbol] the original value passed into the method, only if it was valid
+    # @param [Symbol] locale
+    #
+    # @raise [SmsPilot::InvalidError] if locale is not a Symbol
+    # @raise [SmsPilot::InvalidError] if locale is unrecognized
+    #
+    private def validate_locale!(locale)
+      fail SmsPilot::InvalidLocaleError, "locale must be a Symbol" unless locale.is_a? Symbol
+      fail SmsPilot::InvalidLocaleError, "API does not support locale :#{locale}; choose one of #{AVAILABLE_LOCALES.inspect}" unless AVAILABLE_LOCALES.include? locale
+      return locale
+    end
+
+
+    # Validates message
+    # @private
+    #
+    # @param [String] message
+    # @return [String] the original value passed into the method, only if it was valid
+    #
+    # @raise [SmsPilot::InvalidMessageError] if you pass anythig but a String with the <tt>message</tt> argument
+    # @raise [SmsPilot::InvalidMessageError] if your message is empty
+    #
+    private def validate_message!(message)
+      fail SmsPilot::InvalidMessageError, "SMS message must be a String, you pass a #{ message.class} (#{ message})" unless message.is_a? String
+      fail SmsPilot::InvalidMessageError, "SMS message cannot be empty" if  message == ""
+      message
+    end
+
+
+    # Validates phone
+    # @private
+    #
+    # @param [String] phone
+    # @return [String] the original value passed into the method, only if it was valid
+    #
+    # @raise [SmsPilot::InvalidPhoneError] if you pass anythig but a String with the <tt>phone</tt> argument
+    # @raise [SmsPilot::InvalidPhoneError] if your phone is empty
+    # @raise [SmsPilot::InvalidPhoneError] if your phone has no digits
+    #
+    private def validate_phone!(phone)
+      fail SmsPilot::InvalidPhoneError, "phone must be a String, you pass a #{phone.class} (#{phone})" unless phone.is_a? String
+      fail SmsPilot::InvalidPhoneError, "phone cannot be empty" if phone == ""
+      fail SmsPilot::InvalidPhoneError, "phone must contain digits" if phone.scan(/\d/).none?
+      phone
+    end
+
+    # @!endgroup
+
   end
 end

data/lib/sms_pilot/errors.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
 module SmsPilot
-  class Error < StandardError; end
+
+  class InvalidAPIkeyError  < ArgumentError; end
+  class InvalidMessageError < ArgumentError; end
+  class InvalidPhoneError   < ArgumentError; end
+  class InvalidLocaleError  < ArgumentError; end
+
 end

data/lib/sms_pilot/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module SmsPilot
-  VERSION = "0.0.3"
+
+  # Gem version
+  VERSION = "0.0.8"
+
 end

data/sms-pilot-api-v1.gemspec

@@ -3,33 +3,34 @@
 require_relative "lib/sms_pilot/version"
 
 Gem::Specification.new do |spec|
+  spec.name        =  "sms-pilot-api-v1"
   spec.authors     = ["Sergey Pedan"]
   spec.summary     =  "Simple wrapper around SMS pilot API v1"
   spec.description =  "#{spec.summary}. Version 1 because it returns more data within its standard response"
   spec.email       = ["sergey.pedan@gmail.com"]
-  spec.homepage    =  "https://github.com/sergeypedan/sms-pilot-api-v1"
+  spec.homepage    =  "https://github.com/sergeypedan/#{spec.name}"
   spec.license     =  "MIT"
-  spec.name        =  "sms-pilot-api-v1"
   spec.version     =   SmsPilot::VERSION
 
   spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
 
   spec.metadata = {
-    "changelog_uri"     => "#{spec.homepage}/blob/master/Changelog.md",
-    "documentation_uri" => "#{spec.homepage}#usage",
-    "homepage_uri"      =>  spec.homepage,
-    "source_code_uri"   =>  spec.homepage
+        "changelog_uri" => "#{spec.homepage}/blob/master/CHANGELOG.md",
+    "documentation_uri" => "https://rubydoc.info/github/sergeypedan/#{spec.name}/master/",
+         "homepage_uri" =>  spec.homepage,
+      "source_code_uri" =>  spec.homepage
   }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|pkg|doc)/}) }
   end
 
-  spec.bindir        =  "bin"
+  spec.bindir        =  "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "http", "~> 4"
+  # spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
 
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: sms-pilot-api-v1
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.8
 platform: ruby
 authors:
 - Sergey Pedan
 autorequire:
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2021-05-06 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: http
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4'
+date: 2021-05-10 00:00:00.000000000 Z
+dependencies: []
 description: Simple wrapper around SMS pilot API v1. Version 1 because it returns
   more data within its standard response
 email:
@@ -34,6 +20,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -45,14 +32,13 @@ files:
 - lib/sms_pilot/client.rb
 - lib/sms_pilot/errors.rb
 - lib/sms_pilot/version.rb
-- sms-pilot-api-v1-0.0.2.gem
 - sms-pilot-api-v1.gemspec
 homepage: https://github.com/sergeypedan/sms-pilot-api-v1
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://github.com/sergeypedan/sms-pilot-api-v1/blob/master/Changelog.md
-  documentation_uri: https://github.com/sergeypedan/sms-pilot-api-v1#usage
+  changelog_uri: https://github.com/sergeypedan/sms-pilot-api-v1/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/
   homepage_uri: https://github.com/sergeypedan/sms-pilot-api-v1
   source_code_uri: https://github.com/sergeypedan/sms-pilot-api-v1
 post_install_message:
@@ -70,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.5
+rubygems_version: 3.2.8
 signing_key:
 specification_version: 4
 summary: Simple wrapper around SMS pilot API v1