sms-pilot-api-v1 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 398583e8c6b3d5ab1ffa33d2e85a412fd779d3332775980d447e2354cdfaf19e
-  data.tar.gz: dfc1c5f424e7c95e9a0829883b701d66da85134d18dc2267e76f3db7756d357a
+  metadata.gz: fb76209647bdda0c204159de74aeb9afd98cb01b6d8979ae9857407e76ff61b1
+  data.tar.gz: 6bcea2c04668198bcbf07babcfec333e90e1cb920a06eb9cb371d2a291f1ca66
 SHA512:
-  metadata.gz: d48222754c8acd857fa867385250ce8de32d92c10e624dfef768077f6399eb289258ddb89137d327a243e5d7a59e4527509c7bfb186fed885e6452284030b079
-  data.tar.gz: f5d14f8fc7558024c8fa5a49a3b2e270487de1cd6d2d4e8aa93d45c10e4d948837c8ac4dc13d85e115ae2ce24e956eaefb3ae43d943bfe2732eee93478a55be6
+  metadata.gz: b21cecdb44421ffe495e0963b9928dedab5e8740680f94937b85eceb1de256bdef23d967e8012e46c124f3a24f27f3fb8eedd541391964ec6dcdd83c21af7300
+  data.tar.gz: a693db49eac9e534a6be8c3132804376783a42c56ae532782cd6459f9c516c6f4610ff234d4a9cb522fe30019c64724c042a649e43a475c6c10bbe7e65baf27e

data/README.md

@@ -44,11 +44,16 @@ 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
@@ -63,6 +68,10 @@ 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
@@ -72,12 +81,14 @@ client.send_sms("+7 (902) 123-45-67", "Привет, мир!")
 
 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
@@ -97,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
@@ -116,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
@@ -133,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
@@ -172,3 +185,8 @@ SMS rejected:
   }
 }
 ```
+
+
+## Documentation
+
+See [structured documentation](https://rubydoc.info/github/sergeypedan/sms-pilot-api-v1/master/SmsPilot/Client) at RubyDoc.

data/lib/sms_pilot/client.rb

@@ -7,7 +7,9 @@ require "uri"
 module SmsPilot
 
   # @!attribute [r] api_key
-  #   @return [String] Your 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
@@ -18,10 +20,16 @@ module SmsPilot
   #   @see #error_description
   #
   # @!attribute [r] locale
-  #   @return [Symbol] Chosen locale (affects only the language of errors)
+  #   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}).
@@ -34,6 +42,7 @@ module SmsPilot
   #
   # @!attribute [r] response_headers
   #   @example
+  #     client.response_headers #=>
   #     {
   #       "Access-Control-Allow-Origin" => "*",
   #       "Connection" => "close",
@@ -57,16 +66,14 @@ module SmsPilot
   #   @see #response_data
   #   @see #response_headers
   #
-  # @!attribute [r] url
-  #   @example
-  #     client.url #=> "https://smspilot.ru/api.php?api_key=XXX&format=json&send=TEXT&to=79021234567"
-  #   @return [String] URL generated by combining <tt>API_ENDPOINT</tt>, your API key, SMS text & phone
-  #
   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
@@ -76,7 +83,6 @@ module SmsPilot
     attr_reader :response_body
     attr_reader :response_headers
     attr_reader :response_status
-    attr_reader :url
 
 
     # @param api_key [String]
@@ -101,7 +107,6 @@ module SmsPilot
       @response_status  = nil
       @response_headers = {}
       @response_body    = nil
-      @url              = nil
     end
 
 
@@ -119,6 +124,7 @@ module SmsPilot
     # @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
@@ -128,14 +134,9 @@ module SmsPilot
       validate_message! message
 
       @phone = normalize_phone(phone)
-      uri    = build_uri(@phone, message)
-      @url   = uri.to_s
+      @uri   = build_uri(@phone, message)
 
-      response = Net::HTTP.get_response(uri)
-
-      @response_body    = response.body
-      @response_status  = response.code.to_i
-      @response_headers = response.each_capitalized.to_h
+      response = persist_response_details Net::HTTP.get_response(@uri)
 
       @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?
@@ -169,6 +170,20 @@ module SmsPilot
     end
 
 
+    # 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>
@@ -306,6 +321,18 @@ module SmsPilot
       @response_data.dig("send", 0, "status")&.to_i if sms_sent?
     end
 
+
+    # 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
 
 
@@ -317,7 +344,7 @@ module SmsPilot
     #   #=> #<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 very unlikely because we provide the URL ourselves
+    # @raise [URI::InvalidURIError] but is almost impossible, because we provide the URL ourselves
     #
     # @see #api_key
     # @see #phone
@@ -346,6 +373,21 @@ module SmsPilot
     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
@@ -353,7 +395,7 @@ module SmsPilot
     # @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
     #
@@ -369,7 +411,7 @@ module SmsPilot
     # @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
     #

data/lib/sms_pilot/version.rb

@@ -3,6 +3,6 @@
 module SmsPilot
 
   # Gem version
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sms-pilot-api-v1
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Sergey Pedan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-09 00:00:00.000000000 Z
+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
@@ -19,7 +19,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".inch.yml"
 - ".rspec"
 - ".yardopts"
 - CHANGELOG.md

data/.inch.yml

@@ -1,11 +0,0 @@
-files:
-
-  # defaults to ["{app,lib}/**/*.rb"]
-  included:
-    - lib/sms_pilot/client.rb
-
-  # defaults to []
-  excluded:
-    - lib/sms_pilot.rb
-    - lib/sms_pilot/errors.rb
-    - lib/sms_pilot/version.rb