eztexting 0.3.0

data/Manifest

@@ -0,0 +1,18 @@
+LICENSE
+Manifest
+README.textile
+RELEASE_NOTES
+Rakefile
+VERSION
+examples/example_script.rb
+lib/eztexting.rb
+lib/eztexting/availablity.rb
+lib/eztexting/base.rb
+lib/eztexting/credits.rb
+lib/eztexting/keywords.rb
+lib/eztexting/lookup.rb
+lib/eztexting/sms.rb
+lib/eztexting/voice.rb
+spec/eztexting/eztexting_spec.rb
+spec/spec.opts
+spec/spec_helper.rb

data/README.textile

@@ -0,0 +1,62 @@
+h1. Eztexting Gem
+
+0.3.0
+
+This is a gem built to make the eztexting api's as easy to use as possible. They allow for use of all of what the API offers in a 
+very easy and clear fashion.
+
+h2. Dependencies
+
+This gem relies on HTTParty for making its requests. That is the only runtime dependency. The testing uses rspec and the documentation
+is written to be viewed with YARD.
+
+h2. API Calls Available
+These are the following calls available and their corresponding classes to use them
+
+* SMS (Eztexting::Sms)
+* Credit Purchase and Balance Check (Eztexting::Credits)
+* Keyword Check and Configuration (Eztexting::Keyword)
+* Carrier Lookups (Eztexting::Lookup)
+* Voice Broadcast (Eztexting::Broadcast)
+  
+h2. How To Use / How The Gem Is Setup
+
+Basically all you need to do is call the connect method on the Eztexting module. Once thats done then your credentials are cached and you 
+can use any of the classes to interact with the Eztexting service. 
+
+**All API calls require your user name and password** which is why you call 
+the connect method and cache them. By doing this you enter your credentials once and then they merged with the options for the api call you 
+want to make. This makes interacting with the Eztexting API far less irritating as there is no state or authentication and the credentials 
+must be passed along through every request.
+
+
+h2. Examples
+
+<notextile><pre>
+  
+# Setup the connection for making requests.
+Eztexting.connect!('username','password')
+# => "credentials cached"  
+  
+# Make a hash with the required keys of subject, message and phonenumber
+# and then send out the SMS. Its that simple. 3 lines, 2 if you condense the creation of the Hash into the Method call
+# The response will be an array , the first element will be the response mapped from the code to the literal that the Eztexting
+# documentation lists out. The second element will be the raw value. In some cases this bit is important , in the credit balance
+# check this would be the number of credits. 
+options = {:subject => "testing out how awesome eztexting is", :phonenumber => "5165551234", :message => "Wow this is so simple and easy to use"}
+Eztexting::Sms.single(options)
+# => ["Message Sent",1]
+
+# Check Your Credit Count
+Eztexting::Credits.balance
+# => ["The amount of plan and additional credits available", 54353]
+
+# Check If A Keyword Is Available
+Eztexting::Availablity.check("my_keyowrd_to_check")
+# => ["The Keyword Is Available", 1]
+
+# Make Voice Broadcast
+options = {:phonenumbers => 51659232132, :soundsource => "http://mywebsite.com/dunder_mifflin_is_a_part_of_sabre.wav", :callerid => 4013210192}
+Eztexting::Voice.broadcast(options)
+# => ["Campaign Sent",1]
+</pre></notextile>

data/RELEASE_NOTES

@@ -0,0 +1,7 @@
+EzTexting.connect!("joshm","qwerty")
+message = {:phonenumber=>"5164920096", :password=>"qwerty", :user=>"joshm", :message=>"test", :subject=>"testddsada"}
+
+EzTexting::Sms.single(message)
+// 1
+EzTexting::Credits.check?
+// 689

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'  
+require 'rake'  
+require 'echoe'  
+require 'yard'
+  
+Echoe.new('eztexting', '0.3.0') do |p|  
+  p.description     = "A Gem to make using eztexting simple and fun"  
+  p.url             = "http://github.com/EzTexting/eztexting"  
+  p.author          = "David Malin"  
+  p.email           = "dmalin@eztexting.com"  
+  p.ignore_pattern  = ["tmp/*", "script/*"]  
+  p.development_dependencies = []  
+  p.runtime_dependencies = ["httparty >=0.6.0"]
+end  
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']   # optional
+  t.options = ['--any', '--extra', '--opts'] # optional
+end
+
+  
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/examples/example_script.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+require 'eztexting'
+
+# Cache your credentials for all subsequent requests, this is required, you must do this so that all of 
+# your requests can have the right parameters. All requests to the api require the userame and password.
+Eztexting.connect!(username,password)
+
+# Now you ready to make full use of the api. The api calls are implemented as subclasses of a base class. This
+# class has the posting method that merges in the username and password each time that you initialized in the 
+# connect method. 
+#
+# All you have to do is pass in the call specific parameters, the username and password will be injected,
+# here cheeck the availablity of the money keyword
+Eztexting::Availability.check("money")
+
+
+# Now lets make an acutal text message. Make a hash with the parameters for the api call
+msg = {:phonenumber=>"5165551234", :message=>"My First Text MEssage", :subject=>"This is an awesome service. I love eztexting"}
+Eztexting::Sms.single(msg)

data/eztexting.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{eztexting}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["David Malin"]
+  s.date = %q{2010-09-08}
+  s.description = %q{A Gem to make using eztexting simple and fun}
+  s.email = %q{dmalin@eztexting.com}
+  s.extra_rdoc_files = ["LICENSE", "README.textile", "lib/eztexting.rb", "lib/eztexting/availablity.rb", "lib/eztexting/base.rb", "lib/eztexting/credits.rb", "lib/eztexting/keywords.rb", "lib/eztexting/lookup.rb", "lib/eztexting/sms.rb", "lib/eztexting/voice.rb"]
+  s.files = ["LICENSE", "Manifest", "README.textile", "RELEASE_NOTES", "Rakefile", "VERSION", "examples/example_script.rb", "lib/eztexting.rb", "lib/eztexting/availablity.rb", "lib/eztexting/base.rb", "lib/eztexting/credits.rb", "lib/eztexting/keywords.rb", "lib/eztexting/lookup.rb", "lib/eztexting/sms.rb", "lib/eztexting/voice.rb", "spec/eztexting/eztexting_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "eztexting.gemspec"]
+  s.homepage = %q{http://github.com/EzTexting/eztexting}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Eztexting", "--main", "README.textile"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{eztexting}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A Gem to make using eztexting simple and fun}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<httparty>, [">= 0.6.0"])
+    else
+      s.add_dependency(%q<httparty>, [">= 0.6.0"])
+    end
+  else
+    s.add_dependency(%q<httparty>, [">= 0.6.0"])
+  end
+end

data/lib/eztexting.rb

@@ -0,0 +1,29 @@
+require 'httparty'
+require 'eztexting/base'
+require 'eztexting/availablity'
+require 'eztexting/credits'
+require 'eztexting/keywords'
+require 'eztexting/lookup'
+require 'eztexting/sms'
+require 'eztexting/voice'
+
+module Eztexting
+  include HTTParty
+  
+  # Sets up the connection that the other classes
+  # use to be able communicate with the api
+  def self.connect!(username,password)
+    # HTTParty Method to store base url
+    self.base_uri "https://app.eztexting.com/api"
+    
+    # Catch the username and password for use in all calls
+    @username = username
+    @password  = password 
+    puts "credentials cached"
+  end
+  
+  def self.credentials
+    {:user => @username, :pass => @password}
+  end
+  
+end

data/lib/eztexting/availablity.rb

@@ -0,0 +1,38 @@
+module Eztexting
+  class Availability < Base
+    
+    # Check the availablity of a keyword 
+    # @param [String] This is the keyword that you would like to check the status of.
+    # @return [Array] The first element will be weather the keyword is free or a status message , the second element is the raw response
+    def self.check(keyword)
+      location = "/keyword/check/"
+      options  = {:keyword => keyword}
+      
+      response = self.do_post(location,options)
+      response_result = self.process(response)
+      
+      return self.processed_reponse(response_result,response)
+    end
+    
+    
+    private
+    
+    def self.process(response)
+      api_result = case response
+      when "1"
+        "The keyword is available"
+      when "0"
+        "The keyword is no available"
+      when "-1" 
+        "Invalid user and/or password or API is not allowed for your account"
+      when "-10"
+        "error"
+      else
+        "error"
+      end
+      
+      return api_result
+    end
+    
+  end
+end

data/lib/eztexting/base.rb

@@ -0,0 +1,35 @@
+module Eztexting
+  class Base
+    
+    # This method never is really called by itself it is called from the classses do the work of the actual 
+    # interaction with the api itself. 
+    def self.do_post(uri,options)
+      options  = options || {}
+      options  = options.merge!(Eztexting.credentials)
+      location = uri
+      
+      response = Eztexting.post(location, :body => options)
+      return response.body
+    end
+    
+    # This is a default result mapping. The response from the API is usually a coded number (except for the balance call which returns
+    # the acutal number of credits). Here we map over those values to a response. This is sometimes overidden by the subclasses as thses
+    # mappings to not apply the same way to all commands
+    def self.process(response)
+      api_result = case response
+      when "-1"
+        "Invalid user and/or password or API is not allowed for your account"
+      when "-10"
+        "Unknown error (please contact our support dept.)"
+      else
+        "successful"
+      end
+    end
+    
+    # This just assembles the data to be returned from do_post in a nice clean way 
+    def self.processed_reponse(response_result,response_body)
+      [response_result,response_body]
+    end
+    
+  end
+end

data/lib/eztexting/credits.rb

@@ -0,0 +1,69 @@
+module Eztexting
+  class Credits < Base
+    
+    # Check the balance of credits left on your account
+    # @return [Array] The return is an array of two elements, if the call was sucessfull the you should get the success and the second element will be the number of credits available.
+    def self.balance
+      location = "/credits/check/"
+      
+      response = self.do_post(location,{})  
+      response_result = if response.to_i > 0
+        "The amount of plan and additional credits available"
+      elsif response == -1
+        "Invalid user and/or password or API is not allowed for your account"
+      else
+        "Unknown error (please contact our support dept.)"
+      end
+      
+      return self.processed_reponse(response_result,response)
+    end
+    
+    # Purchase more credits for your account
+    # @param [Hash] This takes alot of keys that are all required, you need a full billing address and a full credit card
+    # @return [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.purchase(opts={})
+      location = "/credits/buy/"
+      options = {
+        :credits => opts[:credits],
+        :firstname => opts[:first_name],
+        :lastname => opts[:last_name],
+        :address => opts[:address], 
+        :city => opts[:city], 
+        :state => opts[:state], 
+        :zip => opts[:zip], 
+        :country => opts[:country], 
+        :type => opts[:cc_type], 
+        :ccnumber => opts[:cc_number],
+        :cccode => opts[:cc_verification_code], 
+        :expm => opts[:cc_expiration_month], 
+        :expy => opts[:cc_expiration_year]
+      }
+      
+      response = self.do_post(location,options)
+      response_result = self.process(response)
+
+      return self.processed_reponse(response_result,response)
+    end
+    
+    private
+    def self.process(response)
+      api_result = case response
+      when "1"
+        "Purchase Was Sucessful"
+      when "0"
+        "The Purchase Was Declined"
+      when "-1" 
+        "Invalid user and/or password or API is not allowed for your account"
+      when "-2"
+        "Request declined because it is less than $5.00 minimum purchase."
+      when "-10"
+        "Unknown error (please contact our support dept.)"
+      else
+        "Unknown error (please contact our support dept.)"
+      end
+      
+      return api_result
+    end
+    
+  end
+end

data/lib/eztexting/keywords.rb

@@ -0,0 +1,46 @@
+module Eztexting
+  class Keywords < Base
+
+    # Rent a keyword
+    # @param [Hash] This requires alot of parameters in the hash you pass in. You need to pass in a full address, credit card with all the info and the keyword
+    # @return [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.rent(opts={})
+      location = "/keyword/rent/"
+      options = {
+        :keyword => opts[:keyword],
+        :firstname => opts[:first_name],
+        :lastname => opts[:last_name],
+        :address => opts[:address], 
+        :city => opts[:city], 
+        :state => opts[:state], 
+        :zip => opts[:zip], 
+        :country => opts[:country], 
+        :type => opts[:cc_type], 
+        :ccnumber => opts[:cc_number],
+        :cccode => opts[:cc_verification_code], 
+        :expm => opts[:cc_expiration_month], 
+        :expy => opts[:cc_expiration_year]
+      }
+      
+      response = self.do_post(location,options)
+    end
+    
+    # Configure A Keyword
+    # param [Hash] This requires only four keys, the keyword your targeting, its group, an autoreply and a url
+    # @return [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.configure
+      location = "/keyword/setup"
+      options = {
+        :keyword => opts[:keyword],
+        :group => opts[:group],
+        :autoreply => opts[:autoreply],
+        :url => opts[:url]
+      }
+      
+      response = self.do_post(location,options)      
+    end
+    
+
+    
+  end
+end

data/lib/eztexting/lookup.rb

@@ -0,0 +1,18 @@
+module Eztexting
+  class Lookup < Base
+    
+    # Lookup the carrier for a telephone mobile number
+    # @param [String] phone_number is the number to be passed in to check the carrier
+    # @return [Array] the first element would be the carrier if the request was successful, the second  will bethe raw data
+    def self.carrier(phone_number)
+      location = "/lookup"
+      options  = {:phonenumber => phone_number}  
+      
+      response = self.do_post(location,options)
+      response_result = self.process(response)
+      
+      return self.processed_reponse(response_result,response)
+    end
+    
+  end
+end

data/lib/eztexting/sms.rb

@@ -0,0 +1,59 @@
+module Eztexting
+  class Sms < Base
+    
+    # Send out a singular SMS
+    # @param [Hash] opts is a hash with keys/value pairs of subject, message and phone number. The phonenumber, subject and message are required by the API
+    # @return [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.single(opts={})
+      location = "/sending"
+      
+      response = self.do_post(location,opts)
+      response_result = self.process(response)
+
+      return self.processed_reponse(response_result,response)  
+    end
+    
+    # Send Out Multiple Messages
+    # @param [Array] messages is an array of hashes which are hashes that are identical to the hash passed into the single SMS method. This requires the same keys as the single method
+    # @return [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.multi(messages)
+      location = "/sending"
+      results = []
+        
+      messages.each_with_index do |msg, i|
+        opts = msg
+        response = self.do_post(location,opts)
+        response_result = self.process(response)
+        results << {:message => i, :result => response_result}
+      end
+      
+      return results
+    end
+    
+    private
+    
+    def self.process(response)
+      api_result = case response
+      when "1"
+        "Message sent"
+      when "-1"
+        "Invalid user and/or password or API is not allowed for your account"
+      when "-2" 
+        "Credit limit reached"
+      when "-5"
+        "Local opt out (the recipient/number is on your opt-out list.)"
+      when "-7"
+        "Invalid message or subject"
+      when "-104"
+        "Globally opted out phone number (the phone number has been opted out from all messages sent from our short code)"
+      when "-106"
+        "Incorrectly formatted phone number (number must be 10 digits)"
+      else
+        "Unknown error (please contact our support dept.)"
+      end
+      
+      return api_result
+    end
+    
+  end
+end

data/lib/eztexting/voice.rb

@@ -0,0 +1,49 @@
+module Eztexting
+  class Voice < Base
+    
+    # Use the Voicebroadcast feature of the API
+    # @param [Hash] This has needs the following keys, phonenumbers to call, the recording src and the caller_id value
+    # @return  [Array] The return is an array of two elements, the mapped error code according to the extexting and the raw response
+    def self.broadcast(opts={})
+      location = "/voicemessages/"
+      
+      options = {
+        :phonenumbers => phone_numbers,
+        :soundsource => opts[:recording],
+        :callerid => opts[:called_id]
+      }
+      response = self.do_post(location,options)
+      response_result = self.process(response)
+
+      return self.processed_reponse(response_result,response)
+    end
+    
+    
+    private
+    
+    def self.process(response)
+      api_result = case response
+      when "1"
+        "Campaign Sent"
+      when "-1"
+        "Invalid user and/or password or API is not allowed for your account"
+      when "-2" 
+        "Credit limit reached"
+      when "-3"
+        "Invalid callerid"
+      when "-4"
+        "Invalid array of phone numbers"
+      when "-5"
+        "Invalid soundfile (make sure you provided the correct file name with the extension)"
+      when "-6"
+        "Invalid soundsource (make sure you provided the correct path to the file with the extension)"
+      when "-7"
+        "Invalid request (make sure you use the correct names of variables)"
+      else
+        "Unknown error (please contact our support dept.)"
+      end
+      
+      return api_result
+    end
+  end
+end

data/spec/eztexting/eztexting_spec.rb

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe "EzTexting" do
+  
+  describe "sms" do
+    it "call do_http post with a URI of /sending" do
+      msg = {:phonenumber=>"5163177477", :message=>"Caprica", :subject=>"Cylons have destroyed the entire fleet"}
+      response = Eztexting::Sms.single(msg)
+      response.last
+    end
+  end
+  
+  describe "eztexting" do
+    it "should store the username and password as instance vars when the connect method is called" do
+      Eztexting.connect!("BillAdama","Pupser")
+      Eztexting.credentials[:user].should eql("BillAdama")
+      Eztexting.credentials[:pass].should eql("Pupser")
+    end
+  
+    it "does something" do
+    
+    end
+  end
+end

data/spec/spec.opts

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

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+require File.expand_path(File.dirname(__FILE__) + "/../lib/eztexting")
+
+require 'spec'
+
+Spec::Runner.configure do |config|
+
+end
+
+# Redefine the do_post method so that it does not actually make an outgoing post, we are not interested in testing
+# httpary, just the parameters passed in and how the method is called from other parts of the application
+module Eztexting
+  class Base
+    
+    def self.do_post(uri,options)
+      return [uri,options]
+    end
+
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification 
+name: eztexting
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- David Malin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-08 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.0
+    version: 
+description: A Gem to make using eztexting simple and fun
+email: dmalin@eztexting.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+- lib/eztexting.rb
+- lib/eztexting/availablity.rb
+- lib/eztexting/base.rb
+- lib/eztexting/credits.rb
+- lib/eztexting/keywords.rb
+- lib/eztexting/lookup.rb
+- lib/eztexting/sms.rb
+- lib/eztexting/voice.rb
+files: 
+- LICENSE
+- Manifest
+- README.textile
+- RELEASE_NOTES
+- Rakefile
+- VERSION
+- examples/example_script.rb
+- lib/eztexting.rb
+- lib/eztexting/availablity.rb
+- lib/eztexting/base.rb
+- lib/eztexting/credits.rb
+- lib/eztexting/keywords.rb
+- lib/eztexting/lookup.rb
+- lib/eztexting/sms.rb
+- lib/eztexting/voice.rb
+- spec/eztexting/eztexting_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- eztexting.gemspec
+has_rdoc: true
+homepage: http://github.com/EzTexting/eztexting
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Eztexting
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: eztexting
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A Gem to make using eztexting simple and fun
+test_files: []
+