postalmethods 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 2008-09-22
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2008 Postal Methods, Inc
+Created 2008 by James Cox <james-at-imaj.es>
+
+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/Manifest.txt

@@ -0,0 +1,31 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/postalmethods.rb
+lib/postalmethods/version.rb
+lib/postalmethods/document_processor.rb
+lib/postalmethods/exceptions.rb
+lib/postalmethods/get_letter_status.rb
+lib/postalmethods/send_letter.rb
+lib/postalmethods/utility.rb
+script/console
+script/destroy
+script/generate
+setup.rb
+spec/document_processor_spec.rb
+spec/get_letter_status_spec.rb
+spec/postalmethods_spec.rb
+spec/send_letter_spec.rb
+spec/utility_spec.rb
+spec/rcov.opts
+spec/spec.opts
+spec/spec_helper.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+

data/PostInstall.txt

@@ -0,0 +1,6 @@
+
+For more information on working with Postal Methods, 
+see the API reference here:
+
+http://www.postalmethods.com/resources/quickstart
+

data/README.txt

@@ -0,0 +1,35 @@
+= postalmethods
+
+* Info: http://www.postalmethods.com/resources/quickstart
+* Code: http://github.com/imajes/postalmethods/tree/master
+
+== DESCRIPTION:
+
+API wrapper library for the postal methods api.
+
+== FEATURES/PROBLEMS:
+
+* Provides access to all of the API methods with appropriate 
+  exceptions as necessary.
+
+== SYNOPSIS:
+
+require 'postalmethods'
+
+@doc = open(File.dirname(__FILE__) + '/../doc/sample.pdf')
+@client = PostalMethods::Client.new(:user => "user", :password => "password")
+rv = @client.send_letter(@doc, "description of doc")
+puts rv
+
+== REQUIREMENTS:
+
+* This gem relies on the soap4r gem.
+
+== INSTALL:
+
+* sudo gem install postalmethods
+* get a developer account at postalmethods.com
+
+== LICENSE:
+
+* See License.txt

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,73 @@
+require 'postalmethods/version'
+
+AUTHOR = 'James Cox'  # can also be an array of Authors
+EMAIL = "james-at-imaj.es"
+DESCRIPTION = "Wrapper for the Postal Methods API"
+GEM_NAME = 'postalmethods' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'postalmethods' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+#  ['activesupport', '>= 1.3.1']
+]    # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "imajes"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = Postalmethods::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'postalmethods documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/postalmethods.rb

@@ -0,0 +1,51 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+module PostalMethods
+  
+  class Client
+    
+      require 'rubygems'
+      gem 'soap4r'
+      require 'soap/rpc/driver'
+      require 'soap/wsdlDriver'
+  
+      require 'postalmethods/exceptions.rb'
+      require 'postalmethods/document_processor.rb'
+      require 'postalmethods/send_letter.rb'
+      require 'postalmethods/get_letter_status.rb'
+      require 'postalmethods/utility.rb'
+
+
+      # include modules
+      include SendLetter
+      include DocumentProcessor
+      include GetLetterStatus
+      include UtilityMethods
+    
+      attr_accessor :api_uri, :username, :password, :to_send, :rpc_driver, :prepared
+  
+      def initialize(opts = {})
+        if opts[:username].nil? || opts[:password].nil?
+          raise PostalMethods::NoCredentialsException
+        end
+        
+        ## declare here so we can override in tests, etc.
+        self.api_uri = "http://api.postalmethods.com/PostalWS.asmx?WSDL"
+                
+        self.username = opts[:username]
+        self.password = opts[:password]
+      end
+
+      def prepare!
+        begin
+          self.rpc_driver ||= SOAP::WSDLDriverFactory.new(self.api_uri).create_rpc_driver
+        rescue SocketError, RuntimeError
+          raise PostalMethods::NoConnectionError
+        end
+        self.prepared = true
+        return self
+      end
+      
+  end
+end

data/lib/postalmethods/document_processor.rb

@@ -0,0 +1,25 @@
+module PostalMethods
+  module DocumentProcessor
+   
+   def document=(doc)
+     unless doc.class == File
+       doc = open(doc)
+     end
+     
+     self.to_send = {} if self.to_send.nil?
+     
+     self.to_send[:extension] = doc.path.to_s.split('.').last
+     self.to_send[:bytes] = doc.read
+     self.to_send[:name] = File.basename(doc.path)
+     self.to_send[:file_obj] = doc
+   end
+
+   def document?
+     true unless self.to_send.nil?
+   end
+
+   def document
+     self.to_send
+   end
+  end
+end

data/lib/postalmethods/exceptions.rb

@@ -0,0 +1,97 @@
+module PostalMethods
+
+  class GenericCodeError < Exception
+    def initialize
+      super("You have reached a code error in the ruby gem. Please report to the forums")
+    end
+  end
+
+  class NoCredentialsException < Exception
+    def initialize
+      super("You have failed to provide any credentials")
+    end
+  end
+  
+  class NoPreparationException < Exception
+    def initialize
+      super("You must prepare the client first with @client.prepare!")
+    end
+  end
+  
+  class InvalidLetterIDsRange < Exception
+    def initialize
+      super("You need to supply an array or a list of ids, comma seperated.")
+    end
+  end
+  
+  class NoConnectionError < Exception
+    def initialize
+      super("Error connecting to the API server. If you are sure you are online, Please call support.")
+    end
+  end
+  
+  ## base api exception - stolen from Halcyon
+  ## http://github.com/mtodd/halcyon/tree/master/LICENSE
+  
+  class APIException < Exception
+    attr_accessor :status, :body
+    def initialize(status, body)
+      @status = status
+      @body = body
+      super "[#{@status}] #{@body}"
+    end
+  end  
+  
+  API_STATUS_CODES = {
+    -3000 => "OK: Successfully received the request",
+    -3001 => "This user is not authorized to access the specified item",
+    -3003 => "Not Authenticated",
+    -3004 => "The specified extension is not supported",
+    -3010 => "Rejected: no funds available",
+    -3020 => "The file specified is unavailable (it may still be being processed, please try later)",
+    -3022 => "Cancellation Denied: The letter was physically processed and cannot be cancelled",
+    -3113 => "Rejected: the city field contains more than 30 characters",
+    -3114 => "Rejected: the state field contains more than 30 characters", 
+    -3115 => "There was no data returned for your query",
+    -3116 => "The specified letter (ID) does not exist in the system",
+    -3117 => "Rejected: the company field contains more than 45 characters",
+    -3118 => "Rejected: the address1 field contains more than 45 characters",
+    -3119 => "Rejected: the address2 field contains more than 45 characters",
+    -3120 => "Rejected: the AttentionLine1 field contains more than 45 characters",
+    -3121 => "Rejected: the AttentionLine2 field contains more than 45 characters",
+    -3122 => "Rejected: the AttentionLine3 field contains more than 45 characters",
+    -3123 => "Rejected: the PostalCode/ZIP field contains more than 15 characters",
+    -3124 => "Rejected: the Country field contains more than 30 characters",
+    -3150 => "General System Error: Contact technical support",
+    -3500 => "Warning: too many attempts were made for this method",
+    -4001 => "The username field is empty or missing",
+    -4002 => "The password field is empty or missing",
+    -4003 => "The MyDescription field is empty or missing - please contact support",
+    -4004 => "The FileExtension field is empty or missing - please contact support",
+    -4005 => "The FileBinaryData field is empty or missing - please contact support",
+    -4006 => "The Address1 field is empty or missing",
+    -4007 => "The city field is empty or missing",
+    -4008 => "The Attention1 or Company fields are empty or missing",
+    -4009 => "The ID field is empty or missing.",
+    -4010 => "The MinID field is empty or missing",
+    -4011 => "The MaxID field is empty or missing",
+  }
+  
+  #--
+  # Classify Status Codes
+  #++
+  
+  API_STATUS_CODES.to_a.each do |http_status|
+    status, body = http_status
+    class_eval <<-"end;"
+      class APIStatusCode#{status.to_s.gsub(/( |\-)/,'')}Exception < PostalMethods::APIException
+        def initialize(body=nil)
+          body = '#{body}' if body.nil?
+          super(#{status}, body)
+        end
+      end
+    end;
+  end
+  
+  
+end

data/lib/postalmethods/get_letter_status.rb

@@ -0,0 +1,69 @@
+module PostalMethods
+  
+  module GetLetterStatus
+    
+    def get_letter_status(id)
+      raise PostalMethods::NoPreparationException unless self.prepared 
+
+      ## get status
+      opts = {:Username => self.username, :Password => self.password, :ID => id}
+      
+      rv = @rpc_driver.getLetterStatus(opts)
+      
+            ws_status = rv.getLetterStatusResult.resultCode.to_i
+      delivery_status = rv.getLetterStatusResult.status.to_i
+          last_update = rv.getLetterStatusResult.lastUpdateTime
+      
+      if ws_status == -3000
+        return [delivery_status, last_update]
+      elsif API_STATUS_CODES.has_key?(ws_status)
+        instance_eval("raise APIStatusCode#{ws_status.to_s.gsub(/( |\-)/,'')}Exception")
+      end
+
+    end
+
+    def get_letter_status_multiple(ids)
+      raise PostalMethods::NoPreparationException unless self.prepared
+
+      if ids.class == Array
+        ids = ids.join(",")
+      end
+      
+      # minimal input checking - let api take care of it
+      return PostalMethods::InvalidLetterIDsRange unless ids.class == String
+
+      ## get status
+      opts = {:Username => self.username, :Password => self.password, :ID => ids}
+      
+      rv = @rpc_driver.getLetterStatus_Multiple(opts)
+      
+      ws_status = rv.getLetterStatus_MultipleResult.resultCode.to_i
+      
+      if ws_status == -3000
+        return rv.getLetterStatus_MultipleResult.letterStatuses.letterStatus
+      elsif API_STATUS_CODES.has_key?(ws_status)
+        instance_eval("raise APIStatusCode#{ws_status.to_s.gsub(/( |\-)/,'')}Exception")
+      end
+
+    end
+
+    def get_letter_status_range(minid, maxid)
+      raise PostalMethods::NoPreparationException unless self.prepared 
+
+      ## get status
+      opts = {:Username => self.username, :Password => self.password, :MinID => minid.to_i, :MaxID => maxid.to_i}
+      
+      rv = @rpc_driver.getLetterStatus_Range(opts)
+
+      ws_status = rv.getLetterStatus_RangeResult.resultCode.to_i
+      
+      if ws_status == -3000
+        return rv.getLetterStatus_RangeResult.letterStatuses.letterStatus
+      elsif API_STATUS_CODES.has_key?(ws_status)
+        instance_eval("raise APIStatusCode#{ws_status.to_s.gsub(/( |\-)/,'')}Exception")
+      end
+
+    end
+    
+  end
+end