active_sms 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8d1dd6ad22373355ea92034148d7c7372236d84
-  data.tar.gz: 4efc65029b7a1ea4692ce9d89184e6c3f02cae5c
+  metadata.gz: 79322cdd7ad16ca0bf27f33d9d363fe19e5858d9
+  data.tar.gz: 059ec6de57e4b9162f2a7fa2821fea6b036cb274
 SHA512:
-  metadata.gz: 793130b952a78ed1c5fe860aa3c1c35820ca5e0f65dc1bb6dca2a90dc91d2553e1f4fa606353054c5fbb69819934fac62e3672d2e8fe3219ab8af9f666689006
-  data.tar.gz: e7cbb4c1f177f929fbd64f31071686adf4df787df3d99d09a9b22566264c5710854c52a5d77b88302fb80fa40134fb8d78c03ce05989c64fad527ce58b4c1d54
+  metadata.gz: 213f02915314a030ab1ea55948a06153fc85db1204a39ce9785c93abb21b35c01346f8e9278b5185ff854832acb39a4ddfa1cba997c1033efaf63539215c0c24
+  data.tar.gz: ad8204fd9cc3084865499f351577c47253a17f459f44a4c2d11b9ce2eb3d8f69d10c1a2cd870f14b1736889b8dc16b775cd77e662f9524ca27517a736dcc50c8

data/Guardfile

@@ -13,3 +13,7 @@ guard :rspec, cmd: "bundle exec rspec" do
   watch(%r{^lib/(.+)\.rb$}) { |m| rspec.spec.call(m[1]) }
   watch(%r{^spec/support/(.+)\.rb$}) { |m| rspec.spec.call(m[1]) }
 end
+
+guard "yard" do
+  watch(%r{lib/.+\.rb})
+end

data/README.md

@@ -1,34 +1,208 @@
 # ActiveSMS
 
 [![Build Status](https://travis-ci.org/Fedcomp/active_sms.svg?branch=master)](https://travis-ci.org/Fedcomp/active_sms)
+[![Gem Version](https://badge.fury.io/rb/active_sms.svg)](https://badge.fury.io/rb/active_sms)
 
-Easily send sms using various sms backends!
-The gem is work in progress now.
+Unified way to send SMS in ruby!
+Allows you to switch SMS services
+without having to rewrite any code that actually sends SMS.
+Supports multiple backends.
+Sending SMS is not pain anymore!
 
-## Installation
+## Installation and usage
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'active_sms'
+gem "active_sms"
 ```
 
-And then execute:
+Then somewhere in your initialization code:
 
-    $ bundle
+```ruby
+ActiveSMS.configure do |config|
+  c.register_backend :my_backend_name, ActiveSMS::Backend::NullSender
+  c.default_backend = :my_backend_name
+end
+```
 
-Or install it yourself as:
+Now, whenever you need to send SMS, just do:
 
-    $ gem install active_sms
+```ruby
+phone = "799999999"
+text = "My sms text"
 
-## Usage
+ActiveSMS.send_sms(phone, text)
+```
 
-To be done.
+Now your code is capable of sending sms.
+Later you may add any sms-backend you want, or even write your own.
 
-## Contributing
+### 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.
+
+At this moment i made ready to use implementation for only one service:
+
+<table>
+  <tr>
+    <th>Gem name</th>
+    <th>Sms service name</th>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://github.com/Fedcomp/active_sms-backend-smsru">
+        active_sms-backend-smsru
+      </a>
+    </td>
+    <td><a href="https://sms.ru">sms-ru</a></td>
+  </tr>
+</table>
+
+The gem documentation should be self explanatory.
+
+### Writing your own sms backend
+
+Here's simple class that can be used by ActiveSMS:
+
+```ruby
+require "active_sms"
+
+class ActiveSMS::Backend::MyCustomBackend < ActiveSMS::Backend::Base
+  def initialize(params = {})
+    # your initialization which parses params if needed.
+    # the params here is the ones you set in initializer
+
+    @token = params.delete(:token)
+  end
+
+  def send_sms(phone, sms_text)
+    # your code to call your sms service
+    # or somehow 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:
+    respond_with_status :not_enough_funds
+  end
+end
+```
+
+Then in initializer:
+
+```ruby
+ActiveSMS.configure do |c|
+  c.register_backend :my_custom_backend,
+                     ActiveSMS::Backend::MyCustomBackend,
+                     token: ENV["token"]
+
+  c.default_backend = :my_custom_backend
+end
+```
+
+Usage:
+
+```ruby
+# somewhere in your code
+result = ActiveSMS.send_sms(phone, text)
+
+if result.success?
+  # do stuff
+else
+  # request failed
+  fail_status = result.status
+  # :not_enough_funds for example
+end
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/Fedcomp/active_sms.
+### Multiple backends
+
+You can specify which backend to use per call:
+
+```ruby
+ActiveSMS.configure do |c|
+  c.register_backend :my_custom_backend,
+                     ActiveSMS::Backend::MyCustomBackend,
+                     token: ENV["token"]
+
+  c.register_backend :null_sender, ActiveSMS::Backend::NullSender
+  c.default_backend = :my_custom_backend
+end
+
+phone = "799999999"
+text = "My sms text"
+
+# Uses default backend
+ActiveSMS.send_sms(phone, text)
+
+# Uses backend you specify
+ActiveSMS.send_sms(phone, text, backend: :null_sender)
+```
+
+### Real life example
+
+If you develop application in group,
+you probably don't want them all to send real SMS,
+and instead you would prefer to emulate sending,
+including SMS text preview (like SMS codes for registration).
+
+However, on production you want
+to actually send them using your service.
+Here's how you can achieve that:
+
+```ruby
+ActiveSMS.configure do |c|
+  if development?
+    c.register_backend :my_custom_backend,  ActiveSMS::Backend::NullSender
+    c.register_backend :my_custom_backend2, ActiveSMS::Backend::NullSender
+  end
+
+  if production?
+    c.register_backend :my_custom_backend,
+                       ActiveSMS::Backend::MyCustomBackend,
+                       token: ENV["token"]
+
+    c.register_backend :my_custom_backend2,
+                       ActiveSMS::Backend::MyCustomBackend2,
+                       token: ENV["token2"]
+  end
+
+  c.default_backend = :my_custom_backend
+end
+
+phone = "799999999"
+text = "My sms text"
+
+# Uses default backend
+ActiveSMS.send_sms(phone, text)
+
+# Uses backend you specify
+ActiveSMS.send_sms(phone, text, backend: :my_custom_backend2)
+
+# depending on your initializer it will use different backends
+# in different environments.
+```
+
+Of course `development?` and `production?` is not real methods.
+You have to detect environment yourself.
+
+While possible, i strongly discourage to use more than two backends
+(One default, another is required in certain situations for some reason).
+It may make your code mess ;)
+
+## Testing
+
+I am planning to make rspec matcher to test if sms was sent.
+For now you may just mock `ActiveSMS.send_sms` and check it was executed.
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/Fedcomp/active_sms
 
 ## License
 

data/active_sms.gemspec

@@ -10,31 +10,16 @@ Gem::Specification.new do |spec|
   spec.email         = ["aglergen@gmail.com"]
 
   spec.summary       = "Easily send sms using various sms backends!"
-  spec.description   = <<-DESCRIPTION
-                          Say you want to send sms in your app.
-                          You think it's simple.
-                          What (most likely) you do?
-                          you create simple class to do it.
-                          Then you need to mock it in tests,
-                          and need to use different backend
-                          in different environments, or even
-                          use multiple backends in single environment.
-                          This gems aims at solving most common cases
-                          for sending sms in your app
-                        DESCRIPTION
 
   spec.homepage      = "https://github.com/Fedcomp/active_sms"
   spec.license       = "MIT"
 
-  # Prevent pushing this gem to RubyGems.org.
-  # To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata["allowed_push_host"] = "https://rubygems.org"
-  else
+  unless spec.respond_to?(:metadata)
     raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
   end
 
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
   spec.files         = `git ls-files -z`
                        .split("\x0")
                        .reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -50,4 +35,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "guard-rspec", "~> 4.7"
   spec.add_development_dependency "pry-byebug", "~> 3.4"
   spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "guard-yard"
 end

data/lib/active_sms/backend/base.rb

@@ -1,10 +1,22 @@
 module ActiveSMS::Backend
-  # TODO: Documentation
-  # rubocop:ignore Style/Documentation
+  # Base class for any sms provider service.
+  # Provides basic structure and helper methods.
+  # While not necessary to be subclassed now, may be necessary later.
   class Base
+    # In initializer you may
+    # accept secrets which were defined in initializer
+    # or other configuration options if any.
+    #
+    # @params [Hash] List of arguments received from configure code.
     def initialize(params = {})
     end
 
+    # Interface for sending sms.
+    # 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)
     def send_sms(_phone, _text)
       raise NotImplementedError,
             "You should create your own class for every sms service you use"

data/lib/active_sms/backend/null_sender.rb

@@ -1,6 +1,10 @@
 # Sms backend to not send anything.
 # Purely for usage in tests
 class ActiveSMS::Backend::NullSender < ActiveSMS::Backend::Base
+  # Method that emulates sms sending. Does nothing. Called by `ActiveSMS.send_sms`
+  #
+  # @_phone [String] Phone number to send sms (not used in this implementation)
+  # @_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

@@ -1,21 +1,26 @@
-# rubocop:ignore Style/Documentation
+# :nodoc:
 module ActiveSMS
+  # @return [ActiveSMS::Configuration] object with configuration options
   def self.config
     @@config ||= Configuration.new
   end
 
+  # Allows to configure ActiveSMS options and register backends
   def self.configure
     yield(config)
   end
 
+  # resets ActiveSMS configuration to default
   def self.reset!
     @@config = nil
   end
 
-  # TODO: Documentation
-  # rubocop:ignore Style/Documentation
+  # Configuration object for ActiveSMS
   class Configuration
+    # returns key of the default sms backend
     attr_reader :default_backend
+
+    # returns list of registered sms backends
     attr_reader :backends
 
     def initialize
@@ -23,6 +28,9 @@ module ActiveSMS
       self.default_backend = :null_sender
     end
 
+    # Specify default sms backend. It must be registered.
+    #
+    # @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
 
@@ -33,6 +41,11 @@ module ActiveSMS
       @default_backend = value
     end
 
+    # 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
     def register_backend(key, classname, params = {})
       raise ArgumentError, "backend key must be a symbol!" unless key.is_a? Symbol
 
@@ -47,6 +60,9 @@ module ActiveSMS
       define_backend(key, classname, params)
     end
 
+    # Removes registered sms backend
+    #
+    # @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,15 +1,19 @@
-# rubocop:ignore Style/Documentation
+# Response object.
+# Generated on each ActiveSMS.send_sms by backend implementations.
 class ActiveSMS::Response
+  # Sms sending status. Anything other than :success considered as failure.
   attr_reader :status
 
   def initialize(args = {})
     @status = args.delete(:status)
   end
 
+  # @return [Boolean] whether request was succesful or not.
   def success?
     @status == :success
   end
 
+  # @return [Boolean] whether request has failed or not.
   def failed?
     !success?
   end

data/lib/active_sms/sending.rb

@@ -1,18 +1,39 @@
-# rubocop:ignore Style/Documentation
+# :nodoc:
 module ActiveSMS
   class << self
-    def send_sms(phone, text)
-      current_backend.new(current_backend_params)
-                     .send_sms(phone, text)
+    # 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
+    def send_sms(phone, text, args = {})
+      backend_name = args.delete(:backend)
+      backend_class(backend_name).new(backend_params(backend_name))
+                                 .send_sms(phone, text)
     end
 
-    def current_backend
+    private
+
+    def backend_class(name)
+      return default_backend_class if name.nil?
+
+      if ActiveSMS.config.backends[name].nil?
+        raise ArgumentError, "#{name} backend is not registered"
+      end
+
+      ActiveSMS.config.backends[name][:class]
+    end
+
+    def default_backend_class
       ActiveSMS.config.backends[ActiveSMS.config.default_backend][:class]
     end
 
-    private
+    def backend_params(name)
+      return default_backend_params if name.nil?
+      ActiveSMS.config.backends[name][:params]
+    end
 
-    def current_backend_params
+    def default_backend_params
       ActiveSMS.config.backends[ActiveSMS.config.default_backend][:params]
     end
   end

data/lib/active_sms/version.rb

@@ -1,3 +1,3 @@
 module ActiveSMS
-  VERSION = "0.0.1".freeze
+  VERSION = "0.1.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_sms
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Fedcomp
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-04 00:00:00.000000000 Z
+date: 2016-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,17 +108,21 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |2
-                            Say you want to send sms in your app.
-                            You think it's simple.
-                            What (most likely) you do?
-                            you create simple class to do it.
-                            Then you need to mock it in tests,
-                            and need to use different backend
-                            in different environments, or even
-                            use multiple backends in single environment.
-                            This gems aims at solving most common cases
-                            for sending sms in your app
+- !ruby/object:Gem::Dependency
+  name: guard-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
 email:
 - aglergen@gmail.com
 executables: []