active_sms 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f43dbcec303c16dfb88899f1ba8d3e2ddfabbcb9
-  data.tar.gz: 72e62060817e39e792f8399e843b3255e344f7fa
+  metadata.gz: 59e9b08c771768bd28c41dd03a642630f202797d
+  data.tar.gz: 2894e6c82dd8e1c5aae0fe5bfb6548c748f17fbe
 SHA512:
-  metadata.gz: 43d8e793fa4bd36ae722d02a12a0ac7a1ac43b1ec6fcc35e7dc3d4a8e8e788a0990152c0f87565a82048507990d4b3df4ee162494eadd4654ea1626a86170a1a
-  data.tar.gz: 5ea42d6c63e10fb618485531617aecf2f9afcaeff35060a631f6ba4e3f8987f88991691ca8ff8cc4b7a96bf8d453e50be7a02b967134fab4e97cb5855c2cf970
+  metadata.gz: a0d690df8f46ccd4496df62a2104c8fb83d032e2430e8cbeeeeb720ad1afe2a7aa3cca21150c6873c06623cda55e02d28848f88f74bb0fa06709fabdeeea93a4
+  data.tar.gz: 66c9c108d4f6bb4cd20dc73eb234f1a7e8174c840b6a9be38dc702ef40dac3d278dd6814d20fe4d7e15412b14bc70d5ebaf9827317ef8f002dd2c762336d3625

data/.rubocop.yml

@@ -1,3 +1,6 @@
+AllCops:
+  TargetRubyVersion: 2.1
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes
   ConsistentQuotesInMultiline: true

data/README.md

@@ -20,24 +20,27 @@ gem "active_sms"
 Then somewhere in your initialization code:
 
 ```ruby
+require "active_sms"
+require "logger"
+
 ActiveSMS.configure do |config|
-  c.register_backend :my_backend_name,
-                     ActiveSMS::Backend::Logger,
-                     logger: Logger.new(STDOUT),
-                     severity: :info
+  config.register_backend :my_backend_name,
+                          ActiveSMS::Backend::Logger,
+                          logger: Logger.new(STDOUT),
+                          severity: :info
 
-  c.default_backend = :my_backend_name
+  config.default_backend = :my_backend_name
 end
 ```
 
 Now, whenever you need to send SMS, just do:
 
 ```ruby
-phone = "799999999"
+phone = "+10000000000"
 text = "My sms text"
 
-# Should print to console [SMS] 79999999999: text
-ActiveSMS.send_sms("79999999999", "text")
+# Should print to console [SMS] +10000000000: text
+ActiveSMS.send_sms(phone, text)
 ```
 
 Now your code is capable of sending sms.
@@ -46,29 +49,37 @@ Later you may add any sms-backend you want, or even write your own.
 ### Adding real sms backend
 
 If you followed steps above, you code still doesn't *really* send sms.
-It uses `ActiveSMS::Backend::NullSender`
-which actually does nothing when called.
-To actually send sms you need to pick gem-provider
-or write your own simple class.
+It uses `ActiveSMS::Backend::Logger`
+which actually just print sms contents to console.
+To actually send sms you need *gem-provider*
+or your own simple class.
 
-At this moment i made ready to use implementation for only one service:
+Here's a list of my implementations for some sms services.
 
 <table>
   <tr>
     <th>Gem name</th>
     <th>Sms service name</th>
   </tr>
+  <tr>
+    <td>
+      <a href="https://github.com/Fedcomp/active_sms-backend-aws">
+        active_sms-backend-aws
+      </a>
+    </td>
+    <td><a href="https://aws.amazon.com/ru/documentation/sns/">Amazon Web Services SNS</a></td>
+  </tr>
   <tr>
     <td>
       <a href="https://github.com/Fedcomp/active_sms-backend-smsru">
         active_sms-backend-smsru
-      </a>
+      </a> (russian)
     </td>
-    <td><a href="https://sms.ru">sms-ru</a></td>
+    <td><a href="https://sms.ru">sms.ru</a></td>
   </tr>
 </table>
 
-The gem documentation should be self explanatory.
+These gems documentation should be self explanatory.
 
 ### Writing your own sms backend
 
@@ -82,18 +93,22 @@ class ActiveSMS::Backend::MyCustomBackend < ActiveSMS::Backend::Base
     # your initialization which parses params if needed.
     # the params here is the ones you set in initializer
 
+    # (you may also use keyword arguments instead)
     @token = params.delete(:token)
   end
 
   def send_sms(phone, sms_text)
     # your code to call your sms service
-    # or somehow send actual sms
+    # or somehow else send actual sms
 
     # if everything went fine, you may use helper from base class:
     respond_with_status :success
 
-    # Or if you want to return failed status code:
+    # any other than :success response considered as failure
     respond_with_status :not_enough_funds
+
+    # optionally you may return some metadata
+    respond_with_status :success, meta: { funds_left: 42 }
   end
 end
 ```
@@ -101,6 +116,9 @@ end
 Then in initializer:
 
 ```ruby
+require "active_sms"
+require_relative "mycustombackend"
+
 ActiveSMS.configure do |c|
   c.register_backend :my_custom_backend,
                      ActiveSMS::Backend::MyCustomBackend,
@@ -123,6 +141,10 @@ else
   fail_status = result.status
   # :not_enough_funds for example
 end
+
+# (optionally) Read metadata if any.
+# Not recommended for control flow.
+result.meta
 ```
 
 ### Multiple backends
@@ -130,6 +152,9 @@ end
 You can specify which backend to use per call:
 
 ```ruby
+require "active_sms"
+require_relative "mycustombackend"
+
 ActiveSMS.configure do |c|
   c.register_backend :my_custom_backend,
                      ActiveSMS::Backend::MyCustomBackend,
@@ -161,6 +186,10 @@ to actually send them using your service.
 Here's how you can achieve that:
 
 ```ruby
+require "active_sms"
+require_relative "mycustombackend"
+require_relative "mycustombackend2"
+
 ActiveSMS.configure do |c|
   if development?
     c.register_backend :my_custom_backend,
@@ -168,7 +197,7 @@ ActiveSMS.configure do |c|
                        logger: Logger.new(STDOUT),
                        severity: :info
 
-   # You can also specify different formatter for second one
+   # You can also, for example, specify different formatter for second one
    logger = Logger.new(STDOUT)
    logger.formatter = proc do |severity, datetime, progname, msg|
      "[MYBackend2]: #{msg}\n"
@@ -181,6 +210,7 @@ ActiveSMS.configure do |c|
   end
 
   if test?
+    # Null sender does nothing when called for sending sms
     c.register_backend :my_custom_backend,  ActiveSMS::Backend::NullSender
     c.register_backend :my_custom_backend2, ActiveSMS::Backend::NullSender
   end
@@ -211,8 +241,8 @@ ActiveSMS.send_sms(phone, text, backend: :my_custom_backend2)
 # in different environments.
 ```
 
-Of course `development?` and `production?` is not real methods.
-You have to detect environment yourself.
+Of course `development?`, `test?` and `production?` are not real methods.
+You have to detect environment yourself somehow.
 
 While possible, i strongly discourage to use more than two backends
 (One default, another is required in certain situations for some reason).
@@ -227,6 +257,20 @@ For now you may just mock `ActiveSMS.send_sms` and check it was executed.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Fedcomp/active_sms
 
+## Submitting a Pull Request
+1. Fork the [official repository](https://github.com/Fedcomp/active_sms).
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add, commit, and push your changes.
+5. Submit a pull request.
+
+* Please add tests if you changed code. Contributions without tests won't be accepted.
+* If you don't know how to add tests, please put in a PR and leave a comment
+  asking for help.
+* Please don't update the Gem version.
+
+( Inspired by https://github.com/thoughtbot/factory_girl/blob/master/CONTRIBUTING.md )
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/active_sms.gemspec

@@ -1,4 +1,3 @@
-# coding: utf-8
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "active_sms/version"

data/lib/active_sms.rb

@@ -6,6 +6,6 @@ require "active_sms/configuration"
 require "active_sms/response"
 require "active_sms/sending"
 
-# rubocop:ignore Style/Documentation
+# :nodoc:
 module ActiveSMS
 end

data/lib/active_sms/backend/base.rb

@@ -7,7 +7,7 @@ module ActiveSMS::Backend
     # accept secrets which were defined in initializer
     # or other configuration options if any.
     #
-    # @params [Hash] List of arguments received from configure code.
+    # @param params [Hash] List of arguments received from configure code.
     def initialize(params = {})
     end
 
@@ -15,8 +15,8 @@ module ActiveSMS::Backend
     # Every subclass should implement method itself.
     # Raises error in default implementation.
     #
-    # @_phone [String] Phone number to send sms (not used in this implementation)
-    # @_text  [String] Sms text (not used in this implementation)
+    # @param _phone [String] Phone number to send sms (not used in this implementation)
+    # @param _text  [String] Sms text (not used in this implementation)
     def send_sms(_phone, _text)
       raise NotImplementedError,
             "You should create your own class for every sms service you use"
@@ -24,8 +24,15 @@ module ActiveSMS::Backend
 
     protected
 
-    def respond_with_status(status)
-      ActiveSMS::Response.new(status: status)
+    # Returns ActiveSMS::Reponse object with status and meta
+    #
+    # @param status [Symbol]
+    #   Query status, any other than :success considered as failure
+    # @param meta [Hash]
+    #   Optional metadata you can return from api or implementation
+    # @return [ActiveSMS::Reponse] Response object with meta and status
+    def respond_with_status(status, meta: nil)
+      ActiveSMS::Response.new(status: status, meta: meta)
     end
   end
 end

data/lib/active_sms/backend/logger.rb

@@ -1,11 +1,11 @@
-# Sms backend for logging outgoing sms
-# instead of actually sending them
+# Sms backend for logging outgoing sms instead of actually sending them
 class ActiveSMS::Backend::Logger < ActiveSMS::Backend::Base
-  # has anyone heard how to receive log levels from logger itself?
+  # Log level validation, all invalid values lead to ArgumentError.
+  # Has anyone heard how to receive log levels from ruby logger itself?
   LOG_SEVERITY = [:debug, :info, :warn, :error, :fatal, :unknown].freeze
 
   # @param logger [::Logger] Class implementing logger interface
-  # @param severity [Symbol] Backend will use log severity you provide
+  # @param severity [Symbol] Severity to log with
   def initialize(logger: Logger.new(STDOUT), severity: :info)
     @logger   = logger
     @severity = severity
@@ -18,8 +18,8 @@ class ActiveSMS::Backend::Logger < ActiveSMS::Backend::Base
 
   # Method that sends phone and text to logger
   #
-  # @phone [String] Phone number to send sms
-  # @text  [String] Sms text
+  # @param phone [String] Phone number to send sms
+  # @param text  [String] Sms text
   def send_sms(phone, text)
     @logger.send(@severity, "[SMS] #{phone}: #{text}")
     respond_with_status :success

data/lib/active_sms/backend/null_sender.rb

@@ -1,10 +1,10 @@
-# Sms backend to not send anything.
-# Purely for usage in tests
+# Sms backend for mocking sending.
+# Purely for usage in tests.
 class ActiveSMS::Backend::NullSender < ActiveSMS::Backend::Base
-  # Method that emulates sms sending. Does nothing. Called by `ActiveSMS.send_sms`
+  # Method that emulates sms sending. Does nothing.
   #
-  # @_phone [String] Phone number to send sms (not used in this implementation)
-  # @_text  [String] Sms text (not used in this implementation)
+  # @param _phone [String] Phone number to send sms (not used in this implementation)
+  # @param _text  [String] Sms text (not used in this implementation)
   def send_sms(_phone, _text)
     respond_with_status :success
   end

data/lib/active_sms/configuration.rb

@@ -30,7 +30,7 @@ module ActiveSMS
 
     # Specify default sms backend. It must be registered.
     #
-    # @value [Symbol] Backend key which will be used as default
+    # @param value [Symbol] Backend key which will be used as default
     def default_backend=(value)
       raise ArgumentError, "default_backend must be a symbol!" unless value.is_a? Symbol
 
@@ -43,9 +43,10 @@ module ActiveSMS
 
     # Register sms provider backend
     #
-    # @key [Symbol] Key for acessing backend in any part of ActiveSMS
-    # @classname [Class] Real class implementation of sms backend
-    # @params [Hash] Optional params for backend. Useful for passing tokens and options
+    # @param key [Symbol] Key for acessing backend in any part of ActiveSMS
+    # @param classname [Class] Real class implementation of sms backend
+    # @param params [Hash]
+    #   Optional params for backend. Useful for passing tokens and options
     def register_backend(key, classname, params = {})
       raise ArgumentError, "backend key must be a symbol!" unless key.is_a? Symbol
 
@@ -62,7 +63,7 @@ module ActiveSMS
 
     # Removes registered sms backend
     #
-    # @key [Symbol] Key of already registered backend
+    # @param key [Symbol] Key of already registered backend
     def remove_backend(key)
       if key == default_backend
         raise ArgumentError, "Removing default_backend is prohibited"

data/lib/active_sms/response.rb

@@ -1,11 +1,19 @@
 # Response object.
 # Generated on each ActiveSMS.send_sms by backend implementations.
 class ActiveSMS::Response
-  # Sms sending status. Anything other than :success considered as failure.
+  # see initialize
   attr_reader :status
 
-  def initialize(args = {})
-    @status = args.delete(:status)
+  # see initialize
+  attr_accessor :meta
+
+  # @param status [Symbol]
+  #   Status of sms request. Anything other than *:success* considered as failure.
+  # @param meta [Hash]
+  #   Meta information which optionally can be returned by backend.
+  def initialize(status:, meta: nil)
+    @status = status
+    @meta = meta
   end
 
   # @return [Boolean] whether request was succesful or not.

data/lib/active_sms/sending.rb

@@ -3,9 +3,9 @@ module ActiveSMS
   class << self
     # Core of the gem, method responsible for sending sms
     #
-    # @phone [String] Phone number for sms
-    # @text  [String] Text for sms
-    # @args  [Hash] Additional options for delivery. Currently only :backend
+    # @param phone [String] Phone number for sms
+    # @param text  [String] Text for sms
+    # @param args  [Hash] Additional options for delivery. Currently only :backend
     def send_sms(phone, text, args = {})
       backend_name = args.delete(:backend)
       backend_class(backend_name).new(backend_params(backend_name))

data/lib/active_sms/version.rb

@@ -1,3 +1,3 @@
 module ActiveSMS
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_sms
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Fedcomp
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-11 00:00:00.000000000 Z
+date: 2016-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler