postmaster 1.0.0

data/README.md

@@ -0,0 +1,57 @@
+# Postmaster
+
+Developer Friendly Shipping
+
+Postmaster takes the pain out of sending shipments via UPS, Fedex, and USPS.
+Save money before you ship, while you ship, and after you ship.
+
+https://www.postmaster.io/
+
+## Requirements
+
+- [Ruby](http://www.ruby-lang.org/) 1.8.7 or above.
+- [rest-client](https://github.com/archiloque/rest-client) 1.4 or above.
+- [multi_json](https://github.com/intridea/multi_json) 1.0.2 or above.
+
+## Installation
+
+You can install using [gem](#gem) or from [source](#source). 
+
+### Gem
+
+Add this line to your application's Gemfile:
+
+    gem 'postmaster'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install postmaster
+    
+### Source
+
+Download the postmaster-ruby source:
+
+    $ git clone https://github.com/postmaster/postmaster-ruby
+
+If you want to build the gem from source:
+
+    $ cd postmaster-ruby
+    $ gem build postmaster.gemspec
+
+## Usage
+
+See https://postmaster.io/docs for tutorials and documentation.
+
+## Issues
+
+Please use appropriately tagged github [issues](https://github.com/postmaster/postmaster-api/issues) 
+to request features or report bugs.
+
+## Testing
+    
+    $ cd tests
+    $ PM_API_KEY=your-api-key rake test

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'rake/testtask'
+require 'rcov/rcovtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+Rcov::RcovTask.new do |t|
+  t.test_files = FileList['test/test_*.rb']
+  #t.verbose = true     # uncomment to see the executed command
+end
+
+
+task :default => [:test]
+

data/lib/example.rb

@@ -0,0 +1,42 @@
+require "postmaster"
+
+Postmaster.api_key = "example-api-key"
+
+result = Postmaster::AddressValidation.validate(
+  :company => "ASLS",
+  :contact => "Joe Smith",
+  :line1 => "1110 Someplace Ave.",
+  :city => "Austin",
+  :state => "TX",
+  :zip => "78704",
+  :country => "US"
+)
+
+result = Postmaster::Shipment.create(
+  :to => {
+    :company => "ASLS",
+    :contact => "Joe Smith",
+    :line1 => "1110 Someplace Ave.",
+    :city => "Austin",
+    :state => "TX",
+    :zip_code => "78704",
+    :phone_no => "919-720-7941",
+    :country => "US"
+  },
+  :carrier => "ups",
+  :service => "2DAY",
+  :package => {
+    :value => 55,
+    :weight => 1.5,
+    :length => 10,
+    :width => 6,
+    :height => 8,
+  },
+  :reference => "Order # 54321"
+)
+
+shipment = Postmaster::Shipment.retrieve(1)
+result = shipment.track()
+
+shipment = Postmaster::Shipment.retrieve(1)
+result = shipment.void()

data/lib/postmaster.rb

@@ -0,0 +1,208 @@
+# Postmaster Ruby bindings
+require 'pp'
+require 'cgi'
+require 'set'
+require 'rubygems'
+require 'openssl'
+
+gem 'rest-client', '~> 1.4'
+require 'rest_client'
+require 'multi_json'
+
+# Version
+require 'postmaster/version'
+
+# API operations
+require 'postmaster/api_operations/create'
+require 'postmaster/api_operations/list'
+
+# Resources
+require 'postmaster/util'
+require 'postmaster/json'
+require 'postmaster/postmaster_object'
+require 'postmaster/api_resource'
+
+require 'postmaster/address'
+require 'postmaster/shipment'
+require 'postmaster/package'
+require 'postmaster/tracking'
+
+# Errors
+require 'postmaster/errors/postmaster_error'
+require 'postmaster/errors/api_error'
+require 'postmaster/errors/api_connection_error'
+require 'postmaster/errors/invalid_request_error'
+require 'postmaster/errors/authentication_error'
+
+
+module Postmaster
+  @@api_key = nil
+  @@api_base = 'https://api.postmaster.io'
+
+  def self.api_url(url='')
+    self.api_base + url
+  end
+
+  def self.api_key=(api_key)
+    @@api_key = api_key
+  end
+
+  def self.api_key
+    @@api_key
+  end
+
+  def self.api_base=(api_base)
+    @@api_base = api_base
+  end
+
+  def self.api_base
+    @@api_base
+  end
+
+  def self.request(method, url, params={}, headers={})
+    api_key = self.api_key
+    raise AuthenticationError.new('No API key provided.  (HINT: set your API key using "Postmaster.api_key = <API-KEY>".)') unless api_key
+
+    uname = (@@uname ||= RUBY_PLATFORM =~ /linux|darwin/i ? `uname -a 2>/dev/null`.strip : nil)
+    lang_version = "#{RUBY_VERSION} p#{RUBY_PATCHLEVEL} (#{RUBY_RELEASE_DATE})"
+    ua = {
+      :bindings_version => Postmaster::VERSION,
+      :lang => 'ruby',
+      :lang_version => lang_version,
+      :platform => RUBY_PLATFORM,
+      :publisher => 'postmaster',
+      :uname => uname
+    }
+
+    params = Util.objects_to_ids(params)
+    url = self.api_url(url)
+    case method.to_s.downcase.to_sym
+    when :get, :head, :delete
+      # Make params into GET parameters
+      if params && params.count > 0
+        query_string = Util.flatten_params(params).collect{|key, value| "#{key}=#{Util.url_encode(value)}"}.join('&')
+        url += "?#{query_string}"
+      end
+      payload = nil
+    else
+      payload = Util.flatten_params(params).collect{|(key, value)| "#{key}=#{Util.url_encode(value)}"}.join('&')
+    end
+
+    begin
+      headers = { :x_postmaster_client_user_agent => Postmaster::JSON.dump(ua) }.merge(headers)
+    rescue => e
+      headers = {
+        :x_postmaster_client_raw_user_agent => ua.inspect,
+        :error => "#{e} (#{e.class})"
+      }.merge(headers)
+    end
+
+    headers = {
+      :user_agent => "Postmaster/v1 RubyBindings/#{Postmaster::VERSION}",
+      :content_type => 'application/x-www-form-urlencoded'
+    }.merge(headers)
+
+    opts = {
+      :method => method,
+      :url => url,
+      :headers => headers,
+      :open_timeout => 60,
+      :payload => payload,
+      :timeout => 80,
+      :user => api_key,
+      :password => "",
+    }
+
+    begin
+      response = execute_request(opts)
+    rescue SocketError => e
+      self.handle_restclient_error(e)
+    rescue NoMethodError => e
+      # Work around RestClient bug
+      if e.message =~ /\WRequestFailed\W/
+        e = APIConnectionError.new('Unexpected HTTP response code')
+        self.handle_restclient_error(e)
+      else
+        raise
+      end
+    rescue RestClient::ExceptionWithResponse => e
+      if rcode = e.http_code and rbody = e.http_body
+        self.handle_api_error(rcode, rbody)
+      else
+        self.handle_restclient_error(e)
+      end
+    rescue RestClient::Exception, Errno::ECONNREFUSED => e
+      self.handle_restclient_error(e)
+    end
+
+    rbody = response.body
+    rcode = response.code
+    begin
+      # Would use :symbolize_names => true, but apparently there is
+      # some library out there that makes symbolize_names not work.
+      resp = Postmaster::JSON.load(rbody)
+    rescue MultiJson::DecodeError
+      raise APIError.new("Invalid response object from API: #{rbody.inspect} (HTTP response code was #{rcode})", rcode, rbody)
+    end
+
+    resp = Util.symbolize_names(resp)
+    resp
+  end
+
+  private
+
+  def self.execute_request(opts)
+    RestClient::Request.execute(opts)
+  end
+
+  def self.handle_api_error(rcode, rbody)
+    begin
+      error_obj = Postmaster::JSON.load(rbody)
+      error_obj = Util.symbolize_names(error_obj)
+      error = error_obj[:error] or raise PostmasterError.new # escape from parsing
+    rescue MultiJson::DecodeError, PostmasterError
+      raise APIError.new("Invalid response object from API: #{rbody.inspect} (HTTP response code was #{rcode})", rcode, rbody)
+    end
+
+    case rcode
+    when 400, 404 then
+      raise invalid_request_error(error, rcode, rbody, error_obj)
+    when 401
+      raise authentication_error(error, rcode, rbody, error_obj)
+    when 403
+      raise permission_error(error, rcode, rbody, error_obj)
+    else
+      raise api_error(error, rcode, rbody, error_obj)
+    end
+  end
+
+  def self.invalid_request_error(error, rcode, rbody, error_obj)
+    InvalidRequestError.new(error[:message], error[:param], rcode, rbody, error_obj)
+  end
+
+  def self.authentication_error(error, rcode, rbody, error_obj)
+    AuthenticationError.new(error[:message], rcode, rbody, error_obj)
+  end
+
+  def self.permission_error(error, rcode, rbody, error_obj)
+    PermissionError.new(error[:message], error[:param], error[:code], rcode, rbody, error_obj)
+  end
+
+  def self.api_error(error, rcode, rbody, error_obj)
+    APIError.new(error[:message], rcode, rbody, error_obj)
+  end
+
+  def self.handle_restclient_error(e)
+    case e
+    when RestClient::ServerBrokeConnection, RestClient::RequestTimeout
+      message = "Could not connect to Postmaster ($apiBase). Please check your internet connection and try again. If this problem persists, let us know at support@postmaster.io."
+    when RestClient::SSLCertificateNotVerified
+      message = "Could not verify Postmaster's SSL certificate. If this problem persists, let us know at support@postmaster.io."
+    else
+      message = "Unexpected error communicating with Postmaster. If this problem persists, let us know at support@postmaster.io."
+    end
+    message += "\n\n(Network error: #{e.message})"
+    raise APIConnectionError.new(message)
+  end
+end
+

data/lib/postmaster/address.rb

@@ -0,0 +1,17 @@
+module Postmaster
+
+  class Address < APIResource
+  end
+
+  class AddressProposal < APIResource
+  end
+  
+  class AddressValidation < APIResource
+  
+    def self.validate(params={})
+      response = Postmaster.request(:post, '/v1/validate', params)
+      self.construct_from(response)
+    end
+
+  end
+end

data/lib/postmaster/api_operations/create.rb

@@ -0,0 +1,16 @@
+module Postmaster
+  module APIOperations
+    module Create
+      module ClassMethods
+        def create(params={})
+          response = Postmaster.request(:post, self.url, params)
+          self.construct_from(response)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/postmaster/api_operations/list.rb

@@ -0,0 +1,16 @@
+module Postmaster
+  module APIOperations
+    module List
+      module ClassMethods
+        def all(filters={})
+          response = Postmaster.request(:get, url, filters)
+          response[:results].map { |i| self.construct_from(i) }
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/postmaster/api_resource.rb

@@ -0,0 +1,36 @@
+module Postmaster
+  class APIResource < PostmasterObject
+    def self.class_name
+      self.name.split('::')[-1]
+    end
+
+    def self.url()
+      if self == APIResource
+        raise NotImplementedError.new('APIResource is an abstract class.  You should perform actions on its subclasses (Charge, Customer, etc.)')
+      end
+      "/v1/#{CGI.escape(class_name.downcase)}s"
+    end
+
+    def url(action=nil)
+      unless id = self['id']
+        raise InvalidRequestError.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}", 'id')
+      end
+      if action.nil?
+        return "#{self.class.url}/#{CGI.escape(id.to_s)}"
+      end
+      "#{self.class.url}/#{CGI.escape(id.to_s)}/#{CGI.escape(action)}"
+    end
+
+    def refresh
+      response = Postmaster.request(:get, url)
+      refresh_from(response)
+      self
+    end
+
+    def self.retrieve(id)
+      instance = self.new(id)
+      instance.refresh
+      instance
+    end
+  end
+end

data/lib/postmaster/errors/api_connection_error.rb

@@ -0,0 +1,4 @@
+module Postmaster
+  class APIConnectionError < PostmasterError
+  end
+end

data/lib/postmaster/errors/api_error.rb

@@ -0,0 +1,4 @@
+module Postmaster
+  class APIError < PostmasterError
+  end
+end

data/lib/postmaster/errors/authentication_error.rb

@@ -0,0 +1,4 @@
+module Postmaster
+  class AuthenticationError < PostmasterError
+  end
+end

data/lib/postmaster/errors/invalid_request_error.rb

@@ -0,0 +1,10 @@
+module Postmaster
+  class InvalidRequestError < PostmasterError
+    attr_accessor :param
+
+    def initialize(message, param, http_status=nil, http_body=nil, json_body=nil)
+      super(message, http_status, http_body, json_body)
+      @param = param
+    end
+  end
+end