elk 0.0.4 → 0.0.5

data/README.MD

@@ -52,7 +52,6 @@ Get all numbers
 Change number settings
 
     number.sms_url = 'http://myservice.se/callback/newsms.php'
-    number.country = 'no'
     number.save
     # => true
 

data/lib/elk.rb

@@ -3,42 +3,70 @@ require 'json/pure'
 require 'open-uri'
 require 'rest_client'
 require 'time'
-# Internal
-require 'elk/number'
-require 'elk/sms'
 
+# Base module
+# Used for to configure username and password through Elk.configure
 module Elk
+  # Base domain for 46elks API
   BASE_DOMAIN = 'api.46elks.com'
+  # API version supported
   API_VERSION = 'a1'
-  VERSION = '0.0.4'
+  # Elk version
+  VERSION     = '0.0.5'
 
+  # When the authentication can't be done
   class AuthError < RuntimeError; end
+  # Raised when the API server isn't working
   class ServerError < RuntimeError; end
+  # Generic exception when 46elks API gives a response Elk can't parse
   class BadResponse < RuntimeError; end
+  # Generic exception when Elk calls 46elk API the wrong way
   class BadRequest < RuntimeError; end
+  # Raised when required paremeters are omitted
   class MissingParameter < RuntimeError; end
 
   class << self
+    # API Username from 46elks.com
     attr_accessor :username
+    # API Password from 46elks.com
     attr_accessor :password
+    # Defaults to Elk::BASE_DOMAIN, but can be overriden for testing
     attr_accessor :base_domain
 
+    # Set up authentication credentials, has to be done before using Elk::Number and Elk::SMS
+    #
+    #   Elk.configure do |config|
+    #     config.username = 'USERNAME'
+    #     config.password = 'PASSWORD
+    #   end
     def configure
       yield self
     end
 
+    # Base URL used for calling 46elks API
     def base_url
+      if not username or not password
+        raise AuthError, "API username and password required"
+      end
+
       "https://#{username}:#{password}@#{(base_domain || BASE_DOMAIN)}/#{API_VERSION}"
     end
 
+    # Wrapper for Elk.execute(:get)
     def get(path, parameters = {})
       execute(:get, path, parameters)
     end
 
+    # Wrapper for Elk::execute(:post)
     def post(path, parameters = {})
       execute(:post, path, parameters)
     end
 
+    # Wrapper around RestClient::RestClient.execute
+    #
+    # * Sets accept header to json
+    # * Handles some exceptions
+    #
     def execute(method, path, parameters, headers={:accept => :json}, &block)
       payload = {}.merge(parameters)
       url = base_url + path
@@ -51,6 +79,7 @@ module Elk
       raise BadRequest, e.http_body
     end
 
+    # Wrapper around JSON.parse, symbolize names
     def parse_json(body)
       JSON.parse(body, :symbolize_names => true)
     rescue JSON::ParserError
@@ -59,10 +88,17 @@ module Elk
   end
 end
 
-class Hash
+# --
+# TODO: Not that nice to create methods in Hash
+# --
+class Hash #:nodoc: all
   def require_keys!(required_keys)
     unless (missing_parameters = required_keys - self.keys).empty?
       raise Elk::MissingParameter, "Requires #{missing_parameters.collect {|s| ":#{s}"}.join(', ')} parameters"
     end
   end
-end
+end
+
+# Internal
+require 'elk/number'
+require 'elk/sms'

data/lib/elk/number.rb

@@ -1,15 +1,17 @@
 module Elk
+  # Allocate and manage numbers used for SMS/MMS/Voice
   class Number
-    attr_reader :number_id, :number, :capabilities, :loaded_at
-    attr_accessor :country, :sms_url
+    attr_reader :number_id, :number, :capabilities, :loaded_at #:nodoc:
+    attr_accessor :country, :sms_url, :voice_start_url #:nodoc:
 
-    def initialize(parameters)
+    def initialize(parameters) #:nodoc:
       set_paramaters(parameters)
     end
 
-    def set_paramaters(parameters)
+    def set_paramaters(parameters) #:nodoc:
       @country      = parameters[:country]
       @sms_url      = parameters[:sms_url]
+      @voice_start_url = parameters[:voice_start_url]
       @status       = parameters[:active]
       @number_id    = parameters[:id]
       @number       = parameters[:number]
@@ -17,6 +19,7 @@ module Elk
       @loaded_at    = Time.now
     end
 
+    # Status of a number, if it's :active or :deallocated
     def status
       case @status
       when 'yes'
@@ -28,30 +31,43 @@ module Elk
       end
     end
 
+    # Reloads a number from the API server
     def reload
       response = Elk.get("/Numbers/#{self.number_id}")
       self.set_paramaters(Elk.parse_json(response.body))
       response.code == 200
     end
 
+    # Updates or allocates a number
     def save
-      response = Elk.post("/Numbers/#{self.number_id}", {:country => self.country, :sms_url => self.sms_url})
+      attributes = {:sms_url => self.sms_url, :voice_start => self.voice_start_url}
+      # If new URL, send country, otherwise not
+      if !self.number_id
+        attributes[:country] = self.country
+      end
+      response = Elk.post("/Numbers/#{self.number_id}", attributes)
       response.code == 200
     end
 
+    # Deallocates a number, once allocated, a number cannot be used again, ever!
     def deallocate!
       response = Elk.post("/Numbers/#{self.number_id}", {:active => 'no'})
-      @status = 'no'
+      self.set_paramaters(Elk.parse_json(response.body))
       response.code == 200
     end
 
     class << self
+      # Allocates a phone number
+      #
+      # * Required parameters: :country
+      # * Optional parameters: :sms_url, :voice_start_url
       def allocate(parameters)
-        parameters.require_keys!([:sms_url, :country])
+        parameters.require_keys!([:country])
         response = Elk.post('/Numbers', parameters)
         self.new(Elk.parse_json(response.body))
       end
 
+      # Returns all Elk::Numbers, regardless of status (allocated/deallocated)
       def all
         response = Elk.get('/Numbers')
 

data/lib/elk/sms.rb

@@ -1,12 +1,13 @@
 module Elk
+  # Used to send SMS through 46elks SMS-gateway
   class SMS
-    attr_reader :from, :to, :message, :message_id, :created_at, :loaded_at
+    attr_reader :from, :to, :message, :message_id, :created_at, :loaded_at #:nodoc:
 
-    def initialize(parameters)
+    def initialize(parameters) #:nodoc:
       set_parameters(parameters)
     end
 
-    def set_parameters(parameters)
+    def set_parameters(parameters) #:nodoc:
       @from       = parameters[:from]
       @to         = parameters[:to]
       @message    = parameters[:message]
@@ -15,6 +16,7 @@ module Elk
       @loaded_at  = Time.now
     end
 
+    # Reloads a SMS from server
     def reload
       response = Elk.get("/SMS/#{self.message_id}")
       self.set_parameters(Elk.parse_json(response.body))
@@ -22,6 +24,12 @@ module Elk
     end
 
     class << self
+      # Send SMS
+      # Required parameters
+      #
+      # * :from - Either the one of the allocated numbers or arbitrary alphanumeric string of at most 11 characters
+      # * :to - Any phone number capable of receiving SMS
+      # * :message - Any UTF-8 text Splitting and joining multi-part SMS messages are automatically handled by the API
       def send(parameters)
         parameters.require_keys!([:from, :message, :to])
 
@@ -34,13 +42,13 @@ module Elk
         self.new(Elk.parse_json(response.body))
       end
 
+      # Get sent and received messages. Limited by the API to 100 latest
       def all
         response = Elk.get('/SMS')
         Elk.parse_json(response.body)[:smses].collect do |n|
           self.new(n)
         end
       end
-
     end
   end
 end

data/spec/elk_spec.rb

@@ -2,6 +2,31 @@ require 'spec_helper'
 require 'elk'
 
 describe Elk do
+  it 'should detect missing username and/or password' do
+    expect { Elk.base_url }.to raise_error(Elk::AuthError)
+
+    Elk.configure do |config|
+      config.username = nil
+      config.password = 'PASSWORD'
+    end
+
+    expect { Elk.base_url }.to raise_error(Elk::AuthError)
+
+    Elk.configure do |config|
+      config.username = 'USERNAME'
+      config.password = nil
+    end
+
+    expect { Elk.base_url }.to raise_error(Elk::AuthError)
+
+    Elk.configure do |config|
+      config.username = 'USERNAME'
+      config.password = 'PASSWORD'
+    end
+
+    expect { Elk.base_url }.to_not raise_error(Elk::AuthError)
+  end
+
   it 'should handle garbage json' do
     bad_response_body = fixture('bad_response_body.txt').read
 
@@ -50,7 +75,7 @@ describe Elk do
         with(:headers => {'Accept'=>'application/json'}).
         to_return(fixture('gets_allocated_numbers.txt'))
       stub_request(:post, "https://USERNAME:PASSWORD@api.46elks.com/a1/Numbers/nea19c8e291676fb7003fa1d63bba7899").
-        with(:body => {"country" => "no", "sms_url" => "http://otherhost/receive"},
+        with(:body => {"sms_url" => "http://otherhost/receive", "voice_start" => ""},
         :headers => {'Accept'=>'application/json', 'Content-Type'=>'application/x-www-form-urlencoded'}).
         to_return(fixture('updates_a_number.txt'))
 

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--format progress
+--loadby mtime
+--reverse

metadata

@@ -1,112 +1,79 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: elk
-version: !ruby/object:Gem::Version 
-  hash: 23
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 4
-  version: 0.0.4
+version: !ruby/object:Gem::Version
+  version: 0.0.5
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Johan Eckerstroem
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-07-18 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-10-20 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json_pure
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70113756837920 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 1
-        - 5
-        - 2
+      - !ruby/object:Gem::Version
         version: 1.5.2
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rest-client
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70113756837920
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: &70113756836920 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 9
-        segments: 
-        - 1
-        - 6
-        - 3
+      - !ruby/object:Gem::Version
         version: 1.6.3
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70113756836920
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70113756836380 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 63
-        segments: 
-        - 0
-        - 9
-        - 2
+      - !ruby/object:Gem::Version
         version: 0.9.2
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70113756836380
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70113756835800 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 2
-        - 6
-        - 0
+      - !ruby/object:Gem::Version
         version: 2.6.0
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: webmock
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *70113756835800
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: &70113756835100 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 1
-        - 6
-        - 4
+      - !ruby/object:Gem::Version
         version: 1.6.4
   type: :development
-  version_requirements: *id005
-description: Used to configure numbers, send/reciev SMS/MMS/Voice messages at 46elks
+  prerelease: false
+  version_requirements: *70113756835100
+description: Elk can be used to allocate a phone numbers, manage the numbers and send
+  SMS through these numbers.
 email: johan@duh.se
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.MD
-files: 
+files:
 - lib/elk/number.rb
 - lib/elk/sms.rb
 - lib/elk.rb
@@ -125,41 +92,32 @@ files:
 - spec/fixtures/server_error.txt
 - spec/fixtures/sms_history.txt
 - spec/fixtures/updates_a_number.txt
+- spec/spec.opts
 - spec/spec_helper.rb
 - README.MD
-has_rdoc: true
-homepage: 
+homepage: https://github.com/jage/elk
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-requirements: []
-
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- API account at 46elks.com
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Client library for 46elks SMS/MMS/Voice service.
 test_files: []
-