burstsms 0.1.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in burst_sms.gemspec
+gemspec

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Made in Data Pty Ltd and David Barlow
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+Software), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# Burst Sms   [![Build Status](https://secure.travis-ci.org/madeindata/Burst-Sms.png?branch=master)](http://travis-ci.org/madeindata/Burst-Sms)
+
+Rubygem for the Burst SMS API. Sends SMS to Australian mobiles  
+For use with a [burstsms.com.au](http://burstsms.com.au) account.
+
+Installation
+------------
+
+    gem install 'burstsms'
+
+or add the following line to Gemfile:  
+
+    gem 'burstsms'
+ 
+and run `bundle` from your shell.
+
+Usage
+-----
+**Create an authenticated instance**
+
+    @burstsms = BurstSms::API.new('api_key', 'secret')
+    
+**Responses**    
+Responses from the API are converted into ruby objects with attributes you can access. 
+ 
+Available attributes for each method are listed in their description below.  
+
+Every method will return a `error` attribute if something goes wrong
+
+
+**Send a SMS** - [messages.multiple](http://burstsms.com/api-documentation/messages.multiple)
+
+    @burstsms.send_message('caller_id', 'recipients', 'message')
+    
+    Response attributes :result :total_recipients :total_recipients_queued :message_id :contact_list_addition
+
+  `caller_id` Can be a Number upto 15 digits or a alpha-numeric string upto 11 characters.  
+  `recipient/s` A single mobile number or an array of mobile numbers for multiple recipients.  
+  `message` String containing sms message to send.  
+  optional:  
+  `sendtime` Set specific time to send message.  
+  `contact_list` Add recipients to an existing contact list in your account.
+  
+  *__NOTE:__The gem handles conversion of mobile numbers to the format required by the API. Also duplicate and invalid numbers will be deleted from the array.*  
+  __example__: you can pass in an array of numbers like `['+61 414 899 766', '0403 855 555', '0403-855-445']` and it will be converted to `['61414899766', '61403855555', '61403855445']`
+  
+------
+
+Additional Methods  
+------------------
+  
+**Send a SMS to an existing list** - [messages.add](http://burstsms.com/api-documentation/messages.add)
+
+    @burstsms.add_message('caller_id', 'list_id', 'message')
+    
+    #returns :total :time :result :message_id :list_id :message :cost :balance :charge_error
+
+**Retrieve history of sent messages** - [messages.get](http://burstsms.com/api-documentation/messages.get)
+
+    @burstsms.get_messages()  #takes optional arguments offset and limit(default is 50)
+    
+    #returns :total :time :messages
+    #messages return :id :list_id :mobile_from :message :datetime_send :datetime_actioned :recipient_count :status :schedule
+    
+**Retrieve responses from a message** - [messages.responses](http://burstsms.com/api-documentation/messages.responses)
+
+    @burstsms.message_responses('message_id')   #takes optional arguments offset and limit(default is 50)  
+    
+    #returns :total :time :replies
+    #replies return :firstname :lastname :mobile :message :datetime_entry_orig
+
+**Retrieve Contact Lists** - [contact-lists.get](http://burstsms.com/api-documentation/contact-lists.get)
+
+    @burstsms.get_lists()  #takes optional arguments offset and limit(default is 50) 
+    
+    #returns :total :time :lists
+    #lists return :id :name :recipient_count
+
+**Add Contact List** - [contact-lists.add](http://burstsms.com/api-documentation/contact-lists.add)
+
+    @burstsms.add_list('name of new list')    
+    
+    #returns :total :time :name :list_id :recipient_count
+    
+**Delete Contact List** - [contact-lists.delete](http://burstsms.com/api-documentation/contact-lists.delete)
+
+    @burstsms.delete_list('list_id')  
+    
+    #returns :total :time :response  
+    
+**Retrieve Contact List Recipients** - [contact-lists.get-recipients](http://burstsms.com/api-documentation/contact-lists.get-recipients)
+
+    @burstsms.get_list_recipients('list_id')   #takes optional arguments offset and limit(default is 50)  
+
+    #returns :total :time :recipients 
+    #recipients return :firstname :lastname :mobile :datetime_entry :dest_country :bounce_count
+    
+**Retrieve Contact List Unsubscribed** - [contact-lists.get-unsubscribed](http://burstsms.com/api-documentation/contact-lists.get-unsubscribed)
+
+    @burstsms.get_list_unsubscribed('list_id')   #takes optional arguments offset and limit(default is 50)  
+
+    #returns :total :time :recipients 
+    #recipients return :firstname :lastname :mobile :datetime_entry :dest_country :bounce_count    
+    
+**Add Contact List Recipient** - [contact-lists.add-recipient](http://burstsms.com/api-documentation/contact-lists.add-recipient)
+
+    @burstsms.add_list_recipient("list_id", "mobile_number", :firstname => 'Bob', :lastname => 'Smith') #name fields optional    
+
+    #returns :total :time :result :list_id
+    #refer to Burst Sms docs for possible result values  
+    
+**Delete Contact List Recipient** - [contact-lists.delete-recipient](http://burstsms.com/api-documentation/contact-lists.delete-recipient)
+
+    @burstsms.delete_list_recipient("list_id", "mobile_number")    
+
+    #returns :total :time :result
+    #refer to Burst Sms docs for possible result values  
+
+------
+**TODO**
+
+- Complete 'contact-lists.add-multiple-recipients'
+- Add reseller API functions.
+
+Licence
+-------
+
+Copyright © 2012 *Made in Data Pty Ltd* and *David Barlow* [@madeindata](http://twitter.com/madeindata). Refer to terms in LICENCE file.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/burstsms.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "burstsms/version"
+
+Gem::Specification.new do |s|
+  s.name        = "burstsms"
+  s.version     = BurstSms::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Barlow"]
+  s.email       = ["david@madeindata.com"]
+  s.homepage    = "https://github.com/madeindata/Burst-Sms"
+  s.summary     = %q{Ruby Interface for the Burst SMS gateway}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  
+  s.add_dependency "unhappymapper"
+  s.add_dependency "httparty"
+  
+  s.add_development_dependency "rspec", "~> 2.6"
+  s.add_development_dependency "webmock", "~> 1.7.10"
+  s.add_development_dependency 'rake'
+  
+end

data/lib/burstsms.rb

@@ -0,0 +1,37 @@
+require 'uri'
+require 'happymapper'
+require 'httparty'
+
+
+module BurstSms
+  
+  class ParamBuilder
+    include HappyMapper
+    tag 'params'
+    def initialize(parameters={})
+      parameters.each do |property,value|
+        self.class.element property, String unless respond_to?("#{property}=")
+        send("#{property}=",value) if respond_to?("#{property}=")   
+      end
+    end
+  end
+    
+end
+
+
+require 'burstsms/messages_multiple'
+require 'burstsms/messages_get'
+require 'burstsms/messages_add'
+require 'burstsms/message_responses'
+require 'burstsms/lists_get'
+require 'burstsms/lists_add'
+require 'burstsms/lists_delete'
+require 'burstsms/lists_get_recipients'
+require 'burstsms/lists_get_unsubscribed'
+require 'burstsms/lists_add_recipient'
+require 'burstsms/lists_delete_recipient'
+
+
+require 'burstsms/api'
+
+

data/lib/burstsms/api.rb

@@ -0,0 +1,78 @@
+require 'happymapper'
+
+module BurstSms
+  API_URL = "https://burstsms.com/api"
+  API_VERSION = 0.3
+  
+  class API
+    include HappyMapper
+
+    include MessagesMultiple
+    include MessagesGet
+    include MessagesAdd
+    include MessageResponses
+    
+    include ListsGet
+    include ListsAdd
+    include ListsDelete
+    include ListsGetRecipients
+    include ListsGetUnsubscribed
+    include ListsAddRecipient
+    include ListsDeleteRecipient
+
+    tag 'request'
+    
+    element :version, Float
+    element :key, String
+    element :secret, String
+    element :api_method, String, :tag => 'method_'
+    
+    has_one :params, String
+    
+    
+    
+    def initialize(api_key, api_secret)
+      self.key = api_key
+      self.secret = api_secret
+      self.version = BurstSms::API_VERSION
+    end
+    
+    
+    
+    private
+    
+    def sanitize_numbers(recipients)
+      Array(recipients).map{|n| n.gsub(/[^0-9]/i, '').gsub(/\A(04)|\A(4)/, '614')}.delete_if{|n| n.length != 11 || !n.start_with?('614')}.uniq.join(',')
+    end
+    
+    def encode_msg(message)
+      URI.escape( message, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))
+    end
+    
+    def check_valid_sender(from)
+      sender = from.gsub(/[^0-9a-z_\s]/i, '')
+      if sender =~ /\D/ 
+        raise "Sender ID is too Long" if sender.length > 11
+      else
+        raise "Sender Number is too Long" if sender.length > 15
+      end
+      return sender
+    end
+    
+    def build_request(api_call, parameters={})
+      self.params = ParamBuilder.new(parameters)
+      self.api_method = api_call
+      self.to_xml()
+    end
+    
+    def post_to_api(request_xml)
+      #XML request has to be wrapped as a 'request' param in body
+      response = HTTParty.post( BurstSms::API_URL, :body => "request=#{request_xml}" )
+    end
+    
+  end
+  
+  
+
+
+end

data/lib/burstsms/lists_add.rb

@@ -0,0 +1,30 @@
+require 'happymapper'
+
+module BurstSms
+  module ListsAdd
+
+    def add_list(name)
+      response = post_to_api(add_list_body(name))
+      Response.parse(response.body)
+    end
+    
+    def add_list_body(name)
+      build_request("contact-lists.add", :name => name)
+    end
+    
+    class Response
+      include HappyMapper
+      tag 'xml'
+  
+      element :total, String
+      element :time, Time
+      element :timestamp, String
+      element :error, String
+      
+      element :name, String, :xpath => "data/name"
+      element :recipient_count, String, :xpath => "data/recipient_count"
+      element :list_id, String, :xpath => "data/id"
+    
+    end
+  end
+end

data/lib/burstsms/lists_add_recipient.rb

@@ -0,0 +1,34 @@
+require 'happymapper'
+
+module BurstSms
+  module ListsAddRecipient
+
+    def add_list_recipient(list_id, mobile, options={})
+      response = post_to_api(add_list_recipient_body(list_id, mobile, options))
+      Response.parse(response.body)
+    end
+    
+    def add_list_recipient_body(list_id, mobile, options={})
+      build_request("contact-lists.add-recipient",  :list_id => list_id,
+                                                    :mobile => mobile,
+                                                    :firstname => (options.has_key?(:firstname) ? options[:firstname] : nil),
+                                                    :lastname => (options.has_key?(:lastname) ? options[:lastname] : nil),
+                                                    :mobile_dest_country => (options.has_key?(:mobile_dest_country) ? options[:mobile_dest_country] : nil)
+                                                    )
+    end
+    
+    class Response
+      include HappyMapper
+      tag 'xml'
+  
+      element :total, String
+      element :time, Time
+      element :timestamp, String
+      element :error, String
+      
+      element :result, String, :xpath => "data/result"
+      element :list_id, String, :xpath => "data/list_id"
+    
+    end
+  end
+end

data/lib/burstsms/lists_delete.rb

@@ -0,0 +1,28 @@
+require 'happymapper'
+
+module BurstSms
+  module ListsDelete
+    
+    def delete_list(id)
+      @response = post_to_api(delete_list_body(id))
+      Response.parse(@response.body)
+    end
+    
+    def delete_list_body(id)
+      build_request("contact-lists.delete", :id => id)
+    end
+
+    class Response
+      include HappyMapper
+      tag 'xml'
+      
+      element :error, String
+      element :total, String
+      element :time, String
+      element :timestamp, String
+      element :response, String
+      
+    
+    end
+  end
+end

data/lib/burstsms/lists_delete_recipient.rb

@@ -0,0 +1,29 @@
+require 'happymapper'
+
+module BurstSms
+  module ListsDeleteRecipient
+    
+    def delete_list_recipient(list_id, mobile)
+      @response = post_to_api(delete_list_recipient_body(list_id, mobile))
+      Response.parse(@response.body)
+    end
+    
+    def delete_list_recipient_body(list_id, mobile)
+      build_request("contact-lists.delete-recipient", :list_id => list_id,
+                                                      :mobile => mobile)
+    end
+
+    class Response
+      include HappyMapper
+      tag 'xml'
+      
+      element :error, String
+      element :total, String
+      element :time, String
+      element :timestamp, String
+      element :result, String
+      
+    
+    end
+  end
+end