voipfone_client 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37f340ce592c3b388bdfb7c98340793eeb79deb7
-  data.tar.gz: 7ccd3c5a76eb5901acb6e3c4b9266a4acce49b1a
+  metadata.gz: 674d936e84e8ce57b7812a00109d9a0b3c9215e1
+  data.tar.gz: 2b20d0fbbf04be97aadd6e6ed045104e1381b071
 SHA512:
-  metadata.gz: 94d775d0d8379aaf9deac0e4b714970bf926e4c10ce9d83cceda82bcb3cd53a95d3406210dca66cc7ab5318f0f767b6dd5426ff80b332746c946893f838c2710
-  data.tar.gz: e95d03921ab1de9ec1558358dce8bee2d87ac53022326e3993ecfd3215d18f36ff7771aef9db52e66ac55f55b9614dc9f29c23fa6dba5b4fa27a096aa1f64e43
+  metadata.gz: 81af18eb50031ea7abd7a30cfe8d4143ff1545af826bafba7512931c7cac09e2f6dac6bec03717967fc88aa0482c77095d4211b79ba0a7db914bf67cb7e52ceb
+  data.tar.gz: 3e779ee451c959c3136598f32d1c643dfc5b45f5df8c1fe2a3dd5dba78f1dc8535932f7ab686fee2f49aa9c1b9d48084d4e13afae48a3229971979cf8cb79688

data/README.md

@@ -4,6 +4,11 @@ A gem to programatically manipulate your [Voipfone](http://www.voipfone.co.uk) a
 
 Voipfone is a brilliant SIP VOIP provider with a very neat set of features, but unfortunately no API. So this gem hopefully fills that gap by using the same JSON API their web interface uses.
 
+## A quick note about using your account balance
+This is rather obvious, but let's say it anyway! This client uses your Voipfone account. Sending SMS messages, setting diverts, setting up calls and other functions will use up your account balance! We're not magically doing stuff for free here.
+
+[Here's a page about Voipfone's charges](https://www.voipfone.co.uk/prices_new.php). We think they're very good value.
+
 ## Installation
 
 This gem is in Rubygems, so you can add this line to your application's Gemfile:
@@ -20,29 +25,98 @@ Or you can manually install the gem using:
 
 ##Configuration and Use
 
-Before you can instantiate a `VoipfoneClient::Client` object, you need to need to configure it:
+Before you can use the gem you need to configure it:
 
 ```ruby
 VoipfoneClient.configure do |config|
 	config.username = "your@email.address"
 	config.password = "yourpass"
+	config.user_agent_string = "something" #default is set to "VoipfoneClient/[version] http://github.com/errorstudio/voipfone_client" in voipfone_client.rb
 end
 ```
 
 This approach gives us lots of options for adding more config options in the future.
 
-After that you can create a new object to call Voipfone:
+After you've done that, there are various classes which you can use to access different parts of your Voipfone Account.
+
+### VoipfoneClient::Account
+The `Voipfone::Account` class has methods relating to your account:
+
+* `balance()` returns your balance as a float
+* `details` returns a hash of your account details (email, name etc)
+* `phone numbers()` returns an array of phone numbers associated with your account
+* `voicemail()` gives you a list of your voicemails, but not (yet) the audio. Pull requests welcome!
+
+### Voipfone::RegisteredMobile
+The `Voipfone::RegisteredMobile` class only has one class method at the moment, `Voipfone::RegisteredMobile.all()` which returns an array of `Voipfone::RegisteredMobile` objects. These respond to `number()` and `name()`.
+
+These are particularly useful to know for sending SMS messages, because the 'from' number has to be in this list. You can't send an SMS from an arbitrary number.
+
+```ruby
+
+include VoipfoneClient
+mobiles = RegisteredMobile.all #this will be an array
+m = mobiles.first
+m.name #this will be the name of the mobile
+m.number #this will be the number of the mobile
+
+```
+
+### Voipfone::SMS
+The `Voipfone::SMS` class allows you to send SMS messages from your account.
+
+You need to make sure that you're sending _from_ a number which is in the list of registered mobiles.
+
+``` ruby
+include VoipfoneClient
+s = SMS.new
+s.from = "[sender number]" # a number which is in the list of registered mobiles at voipfone
+s.to = "[recipient number]" #your recipient number
+s.message = "your message" #message is truncated at 160 chars; UTF-8 not supported.
+
+Spaces are stripped from phone numbers (which need to be supplied as a string); international format with a + symbol is OK.
+
+### Voipfone::GlobalDivert
+The `Voipfone::GlobalDivert` class handles diverts for your whole account (all extensions).
+
+Diverts are one of four __types__ in Voipfone, which we describe thus:
+
+* `:all` - divert all the time
+* `:fail` - divert when something's gone wrong with your VOIP equipment
+* `:busy` - divert when all lines are busy
+* `:noanswer` - divert when there's no answer on any line (we haven't experimented about the relationship between this and voicemail)
+
+You can get a list of all the diverts on your account with the `Voipfone::GlobalDivert.all()` class method, which returns an array of diverts, each with their type and number.
+
+To create a divert, you need to set a __type__ and a __number__:
 
 ```ruby
-c = VoipfoneClient::Client.new
-c.account_balance #will return your balance as a float
+
+include VoipfoneClient
+d = GlobalDivert.new
+d.type = :all # divert for all calls - e.g. your whole team is out of the office; our most common use-case
+d.number = "your number as a strong" # this can be any phone number
+d.save # will return true on success
+
 ```
+In the Voipfone web interface you have to set up a list of divert recipients (and you can do that in this client too), but you don't _need_ to - you can set any number for a divert. As with all other numbers you set, it should be passed in as a string, spaces will be stripped, the + symbol is allowed.
+
+##To Do
+
+There's quite a list of stuff which would be nice to do. If you feel inclined, we'd love pull requests.
+
+* Find a way to get the audio for voicemails
+* per-extension diverts
+* Setting up calls
+* Downloading call records
+* Downloading invoices
+
 
 ## Contributing
 
 We'd love your input!
 
-1. Fork it ( http://github.com/errorstudio/voipfone_client/fork )
+1. Fork the repo ( http://github.com/errorstudio/voipfone_client/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/voipfone_client/account.rb

@@ -0,0 +1,29 @@
+module VoipfoneClient
+  class Account < Session
+    # Return the balance of the account as a float.
+    # @return [Float] Account balance as a float. Should be rounded to 2dp before presentation.     
+    def balance
+      request = @browser.get("#{VoipfoneClient::API_GET_URL}?balance&builder")
+      parse_response(request)["balance"]
+    end
+
+    def details
+      request = @browser.get("#{VoipfoneClient::API_GET_URL}?account")
+      parse_response(request)
+    end
+
+    # Return the phone numbers for this account, as strings
+    # @return [Array] Phone numbers as strings.
+    def phone_numbers
+      request = @browser.get("#{VoipfoneClient::API_GET_URL}?nums")
+      parse_response(request)["nums"].collect {|n| n.first}
+    end
+
+    #Return a list of voicemail entries, with details for each
+    #@return [Hash] of voicemail information. This includes a reference to a WAV file which isn't accessible (yet?)
+    def voicemail
+      request = @browser.get("#{VoipfoneClient::API_GET_URL}?vm_view")
+      parse_response(request)["vm_view"].first["voicemail"]
+    end
+  end
+end

data/lib/voipfone_client/divert_list_item.rb

@@ -1,8 +1,8 @@
 module VoipfoneClient
-  class DivertListItem < Client
+  class DivertListItem < Session
     attr_accessor :name, :number
 
-    # Constructor for `DivertListItem` which accepts the name and number of the phone number to add to the diverts list.
+    # Constructor for {DivertListItem} which accepts the name and number of the phone number to add to the diverts list.
     # @param name [String] the name of the phone to be diverted to
     # @param number [String] the number of the phone to be diverted to.
     def initialize(name: nil, number: nil)
@@ -14,7 +14,7 @@ module VoipfoneClient
     # Add a new number to the list of numbers which can be diverted to. Requires a name
     # and a phone number, which will have spaces stripped from it. May be in international
     # format.
-    # @return [Boolean] true on success or a failure message (in which case a `VoipfoneAPIError` will be raised)
+    # @return [Boolean] true on success or a failure message (in which case a {VoipfoneAPIError} will be raised)
     def save
       if @name.nil? || @number.nil?
         raise ArgumentError, "You need to include a name and number to add to the diverts list"

data/lib/voipfone_client/global_divert.rb

@@ -7,11 +7,11 @@ module VoipfoneClient
   #  - when there is a failure in the phone system
   #  - when the phone(s) are busy
   #  - when there's no answer
-  class GlobalDivert < Client
+  class GlobalDivert < Session
     attr_accessor :type, :number
 
-    # Constructor for `GlobalDivert` which allows you to pass in a `DivertListItem` to be used as the receiving number.
-    # @param divert_list_item [DivertListItem] a `DivertListItem` object which will be used to fill the `GlobalDivert` number.
+    # Constructor for {GlobalDivert} which allows you to pass in a {DivertListItem} to be used as the receiving number.
+    # @param divert_list_item [DivertListItem] a {DivertListItem} object which will be used to fill the {GlobalDivert} number.
     # You still need to specify the divert type.
     def initialize(divert_list_item = nil)
       if divert_list_item.is_a?(DivertListItem)
@@ -30,7 +30,7 @@ module VoipfoneClient
     }
 
     #Save the divert on your account
-    # @return [Boolean] true on success, or a failure message (in which case a `VoipfoneAPIError` will be raised)
+    # @return [Boolean] true on success, or a failure message (in which case a {VoipfoneAPIError} will be raised)
     def save
       if @type.nil? || @number.nil?
         raise ArgumentError, "You need to set a divert type and divert number before you can save the divert."
@@ -39,13 +39,13 @@ module VoipfoneClient
     end
 
     #Clear all diverts
-    # @return [Boolean] true on success, or a failure message (in which case a `VoipfoneAPIError` will be raised)
+    # @return [Boolean] true on success, or a failure message (in which case a {VoipfoneAPIError} will be raised)
     def clear!
       set_diverts()
     end
     class << self
       # Get current diverts
-      # @return [Array] A nested set of arrays with divert information for each type of divert currently set
+      # @return [Array] An array of {GlobalDivert} objects with divert information for each type of divert currently set
       def all
         g = self.new
         request = g.browser.get("#{VoipfoneClient::API_GET_URL}?divertsMain")
@@ -56,6 +56,13 @@ module VoipfoneClient
           divert
         end
       end
+
+      # Clear all diverts - this is a class method
+    # @return [Boolean] true on success, or a failure message (in which case a {VoipfoneAPIError} will be raised)
+      def clear!
+        g = self.new
+        g.clear!
+      end
     end
 
     private
@@ -70,7 +77,7 @@ module VoipfoneClient
     # @param fail [String] The number to which calls will be diverted in the event of a failure
     # @param busy [String] The number to which calls will be diverted if the phones are busy
     # @param no_answer [String] The number to which calls will be diverted if there's no answer
-    # @return [Boolean] true on success, or a failure message (in which case a `VoipfoneAPIError` will be raised)
+    # @return [Boolean] true on success, or a failure message (in which case a {VoipfoneAPIError} will be raised)
     def set_diverts(all: nil, fail: nil, busy: nil, no_answer: nil)
       all ||= ""
       fail ||= ""

data/lib/voipfone_client/registered_mobile.rb

@@ -1,5 +1,5 @@
 module VoipfoneClient
-	class RegisteredMobile < Client
+	class RegisteredMobile < Session
     attr_accessor :number, :name
 
     class << self

data/lib/voipfone_client/session.rb

@@ -0,0 +1,74 @@
+module VoipfoneClient
+  class Session
+    attr_reader :browser
+    # Intantiates a new Voipfone client, with username and password from the [VoipfoneClient::Configuration] class
+    # @return [VoipfoneClient::Client] the object created
+    def initialize
+      if VoipfoneClient.configuration.username.nil? || VoipfoneClient.configuration.password.nil?
+        raise LoginCredentialsMissing, "You need to include a username and password to log in."
+      end
+      @browser = Mechanize.new
+      @browser.user_agent = VoipfoneClient.configuration.user_agent_string
+      login()
+    end
+
+    # check if the user is authenticated. This is a little convoluted because the voipfone private API
+    # always returns '200 OK', but returns 'authfirst' for every response if there is no authentication.
+    # So we make a request to a simple endpoint and expect an empty hash; if we get 'authfirst' we're not authenticated
+    # @return [Boolean] to identify whether we're authenticated or not.
+    def authenticated?
+      request = @browser.get("#{VoipfoneClient::API_GET_URL}?builder")
+      response = parse_response(request)["builder"]
+      if response == "authfirst"
+        return false
+      else
+        return true
+      end
+    end
+
+    # login to Voipfone, using the configured username and password. 
+    # Unless explicitly specified, this method caches cookies on disk to
+    # allow classes inheriting {Voipfone::Session} to use these instead of
+    # logging in each time.
+    # @return [Boolean] true on success or {NotAuthenticatedError} on failure
+    def login
+      username = VoipfoneClient.configuration.username
+      password = VoipfoneClient.configuration.password
+      cookie_file = File.join(VoipfoneClient::TMP_FOLDER,"cookies")
+
+      # load existing cookies from the file on disk
+      if File.exists?(cookie_file)
+        @browser.cookie_jar.load(cookie_file)
+      end
+
+      # if we're authenticated at this point, we're done.
+      return true if authenticated?
+
+      # …otherwise we need to login to the service
+      login_url = "#{VoipfoneClient::BASE_URL}/login.php?method=process"
+      @browser.post(login_url,{"hash" => "urlHash", "login" => username, "password" => password})
+
+      # If we're authenticated at this point, save the cookies and return true
+      if authenticated?
+        @browser.cookie_jar.save(cookie_file, session: true)
+        return true
+      # otherwise, we've tried to authenticate and failed, which means we have a 
+      # bad username / password combo and it's time to raise an error.
+      else
+        raise NotAuthenticatedError, "Username or Password weren't accepted."
+      end
+    end
+
+    # Responses from the private Voipfone API are always in the form ["message", {content}]
+    # We will strip the message (hopefully "OK"), raise if not OK, and return the content.
+    # @param request [JSON] The raw request response from the Voipfone API
+    # @return [Hash] the parsed JSON
+    def parse_response(request)
+      raw = JSON.parse(request.body)
+      unless raw.first == "ok" || raw.first == "OK"
+        raise VoipfoneAPIError, raw.first
+      end
+      raw.last
+    end
+  end
+end

data/lib/voipfone_client/sms.rb

@@ -1,5 +1,5 @@
 module VoipfoneClient
-  class SMS < Client
+  class SMS < Session
     attr_accessor :from, :to, :message
 
     # Constructor to create an SMS - optionally pass in to, from and message

data/lib/voipfone_client/version.rb

@@ -1,3 +1,3 @@
 module VoipfoneClient
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/voipfone_client.rb

@@ -5,8 +5,9 @@ require_rel 'voipfone_client'
 
 module VoipfoneClient
   BASE_URL = "https://www.voipfone.co.uk"
-  API_GET_URL = "https://www.voipfone.co.uk/api/srv"
-  API_POST_URL = "https://www.voipfone.co.uk/api/upd"
+  API_GET_URL = "#{BASE_URL}/api/srv"
+  API_POST_URL = "#{BASE_URL}/api/upd"
+  TMP_FOLDER = File.join(File.dirname(__FILE__),"..","/tmp")
 
   class << self
     attr_accessor :configuration
@@ -23,8 +24,11 @@ module VoipfoneClient
   class Configuration
     attr_accessor :username, :password, :user_agent_string
 
+    # Configuration initializer, to set up default configuration options
     def initialize
-
+      
+      # By default we set the user agent string to "VoipfoneClient/[version] http://github.com/errorstudio/voipfone_client"
+      @user_agent_string = "VoipfoneClient/#{VoipfoneClient::VERSION} (http://github.com/errorstudio/voipfone_client)"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: voipfone_client
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Error Creative Studio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-11 00:00:00.000000000 Z
+date: 2014-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,17 +96,14 @@ files:
 - README.md
 - Rakefile
 - lib/voipfone_client.rb
-- lib/voipfone_client/account_balance.rb
-- lib/voipfone_client/account_details.rb
-- lib/voipfone_client/client.rb
+- lib/voipfone_client/account.rb
 - lib/voipfone_client/divert_list_item.rb
 - lib/voipfone_client/errors.rb
 - lib/voipfone_client/global_divert.rb
-- lib/voipfone_client/phone_numbers.rb
 - lib/voipfone_client/registered_mobile.rb
+- lib/voipfone_client/session.rb
 - lib/voipfone_client/sms.rb
 - lib/voipfone_client/version.rb
-- lib/voipfone_client/voicemail.rb
 - voipfone_client.gemspec
 homepage: https://github.com/errorstudio/voipfone_client
 licenses:

data/lib/voipfone_client/account_balance.rb

@@ -1,8 +0,0 @@
-class VoipfoneClient::Client
-  # Return the balance of the account as a float.
-  # @return [Float] Account balance as a float. Should be rounded to 2dp before presentation.     
-  def account_balance
-    request = @browser.get("#{VoipfoneClient::API_GET_URL}?balance&builder")
-    parse_response(request)["balance"]
-  end
-end

data/lib/voipfone_client/account_details.rb

@@ -1,8 +0,0 @@
-class VoipfoneClient::Client
-	# Return the basic account details, as stored by Voipfone.
-  # @return [Hash] of account details
-	def account_details
-		request = @browser.get("#{VoipfoneClient::API_GET_URL}?account")
-		parse_response(request)
-	end
-end

data/lib/voipfone_client/client.rb

@@ -1,34 +0,0 @@
-module VoipfoneClient
-	class Client
-		attr_reader :browser
-		#  Intantiates a new Voipfone client, with username and password from the `VoipfoneClient::Configuration` class
-		# @return [VoipfoneClient::Client] the object created
-		def initialize()
-			if VoipfoneClient.configuration.username.nil? || VoipfoneClient.configuration.password.nil?
-				raise LoginCredentialsMissing, "You need to include a username and password to log in."
-			end
-			username = VoipfoneClient.configuration.username
-			password = VoipfoneClient.configuration.password
-			@browser = Mechanize.new
-			login_url = "#{VoipfoneClient::BASE_URL}/login.php?method=process"
-			@browser.post(login_url,{"hash" => "urlHash", "login" => username, "password" => password})
-			#We'll do a call to a cheap endpoint (the balance) and if it returns 'authfirst', there's a problem
-			#with the username / password. Oddly it still returns 200 OK.
-			if account_balance == "authfirst"
-				raise NotAuthenticatedError, "Username or Password weren't accepted. You'll need to instantiate a new VoipfoneClient::Client object."
-			end
-		end
-
-		# Responses from the private Voipfone API are always in the form ["message", {content}]
-		# We will strip the message (hopefully "OK"), raise if not OK, and return the content.
-		# @param request [JSON] The raw request response from the Voipfone API
-		# @return [Hash] the parsed JSON
-		def parse_response(request)
-			raw = JSON.parse(request.body)
-			unless raw.first == "ok" || raw.first == "OK"
-				raise VoipfoneAPIError, raw.first
-			end
-			raw.last
-		end
-	end
-end

data/lib/voipfone_client/phone_numbers.rb

@@ -1,10 +0,0 @@
-module VoipfoneClient
-	class Client
-    # Return the phone numbers for this account, as strings
-    # @return [Array] Phone numbers as strings.
-		def phone_numbers
-      request = @browser.get("#{VoipfoneClient::API_GET_URL}?nums")
-      parse_response(request)["nums"].collect {|n| n.first}
-		end
-	end
-end

data/lib/voipfone_client/voicemail.rb

@@ -1,8 +0,0 @@
-class VoipfoneClient::Client
-  #Return a list of voicemail entries, with details for each
-  #@return [Hash] of voicemail information. This includes a reference to a WAV file which isn't accessible (yet?)
-  def voicemail
-    request = @browser.get("#{VoipfoneClient::API_GET_URL}?vm_view")
-    parse_response(request)["vm_view"].first["voicemail"]
-  end
-end