shipping_easy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 05f04872e2e47ff54f0ae7e2b0784421d81aee43
+  data.tar.gz: c6978b8998f1e1cf99ee9394dab5627d4564ccff
+SHA512:
+  metadata.gz: 71f47f2cbe3696252d9fbc11fe3e954cb99d059bf7b08ac37214e455b7868c59f5c20178b1b7bd6061956d8cb5e753d784a0e848ad75fb48521e357462633796
+  data.tar.gz: 986bf7dd0aceb8028709c448a06e71751b55fe5a690ff4f81a81d60df56749d480241ccf32fdb90911189b738cdc4506b63329bb29652ad70cdacb9c7df1c909

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in shipping_easy-ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 ShippingEasy
+
+MIT License
+
+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,25 @@
+# ShippingEasy
+
+Still in development. Please hold.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'shipping_easy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install shipping_easy
+
+## Contributing
+
+1. Fork it
+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`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/shipping_easy.rb

@@ -0,0 +1,25 @@
+require 'rack'
+require "shipping_easy/version"
+
+module ShippingEasy
+
+  class Error < StandardError; end
+
+  class RequestExpiredError < Error
+    def initialize(msg = "The request has expired.")
+      super(msg)
+    end
+  end
+
+  class AccessDeniedError < Error
+    def initialize(msg = "Access denied.")
+      super(msg)
+    end
+  end
+
+  class TimestampFormatError < Error
+    def initialize(msg = "The API timestamp could not be parsed.")
+      super(msg)
+    end
+  end
+end

data/lib/shipping_easy/authenticator.rb

@@ -0,0 +1,100 @@
+module ShippingEasy
+
+  # Authenticates a signed ShippingEasy API request by matching the supplied signature with a freshly calculated one using the API
+  # shared secret. Requests may not be more than 10 minutes old in order to prevent playback attacks.
+  class Authenticator
+
+    EXPIRATION_INTERVAL = 10 * 60
+
+    attr_reader :api_secret,
+                :api_signature,
+                :api_timestamp,
+                :method,
+                :path,
+                :params,
+                :body,
+                :expected_signature
+
+    # Creates a new API authenticator object.
+    #
+    # options - The Hash options used to authenticate the request:
+    #           :api_secret - A ShippingEasy-supplied API secret
+    #           :method - The HTTP method used in the request. Either :get or :post. Default is :get.
+    #           :path - The URI path of the request. E.g. "/api/orders"
+    #           :params - The query params passed in as part of the request.
+    #           :body - The body of the request which should normally be a JSON payload.
+    def initialize(options = {})
+      @api_secret = options.fetch(:api_secret)
+      @method = options.fetch(:method, :get)
+      @path = options.fetch(:path)
+      @body = options.fetch(:body, nil)
+      @params = options.fetch(:params, {})
+      @api_signature = params.delete(:api_signature)
+      @api_timestamp = params.fetch(:api_timestamp, nil).to_i
+      @expected_signature = ShippingEasy::Signature.new(api_secret: @api_secret, method: @method, path: @path, params: @params, body: @body)
+    end
+
+    # Convenience method to instantiate an authenticator and authenticate a signed request.
+    #
+    # options - The Hash options used to authenticate the request:
+    #           :api_secret - A ShippingEasy-supplied API secret
+    #           :method - The HTTP method used in the request. Either :get or :post. Default is :get.
+    #           :path - The URI path of the request. E.g. "/api/orders"
+    #           :params - The query params passed in as part of the request.
+    #           :body - The body of the request which should normally be a JSON payload.
+    #
+    # See #authenticate for more detail.
+    def self.authenticate(options = {})
+      new(options).authenticate
+    end
+
+    # Authenticates the signed request.
+    #
+    # Example:
+    #
+    # authenticator = ShippingEasyShippingEasy::Authenticator.new(api_secret: "XXX",
+    #                                                    method: :post,
+    #                                                    path: "/api/orders",
+    #                                                    params: { test_param: "ABCDE", api_key: "123", api_timestamp: "2014-01-03 10:41:21 -0600" },
+    #                                                    body: "{\"orders\":{\"name\":\"Flip flops\",\"cost\":\"10.00\",\"shipping_cost\":\"2.00\"}}")
+    #
+    # Throws ShippingEasyShippingEasy::RequestExpiredError if the API timestamp is expired.
+    # Throws ShippingEasyShippingEasy::AccessDeniedError if the signature cannot be verified.
+    # Throws ShippingEasyShippingEasy::TimestampFormatError if the timestamp format is invalid
+    #
+    # Returns true if authentication passes.
+    def authenticate
+      raise ShippingEasy::RequestExpiredError if request_expired?
+      raise ShippingEasy::AccessDeniedError unless signatures_match?
+      true
+    end
+
+    # Returns true if the signature included in the request matches our calculated signature.
+    def signatures_match?
+      expected_signature == api_signature
+    end
+
+    # Returns true if the supplied API timestamp has expired.
+    def request_expired?
+      parsed_timestamp < request_expires_at
+    end
+
+    # Returns the time that the request expires, given the supplied API timestamp.
+    #
+    # Returns a Time object.
+    def request_expires_at
+      Time.now - EXPIRATION_INTERVAL
+    end
+
+    # Parses the supplied API timestamp string into a Time object.
+    #
+    # Raises ShippingEasyShippingEasy::TimestampFormatError if the string cannot be converted into a Time object.
+    # Returns a Time object.
+    def parsed_timestamp
+      raise ArgumentError if api_timestamp == 0
+      Time.at(api_timestamp)
+    rescue ArgumentError, TypeError
+      raise ShippingEasy::TimestampFormatError
+    end
+  end
+end

data/lib/shipping_easy/signature.rb

@@ -0,0 +1,82 @@
+module ShippingEasy
+
+  # Used to generate ShippingEasy API signatures or to compare signature with one another.
+  class Signature
+
+    attr_reader :api_secret,
+                :method,
+                :path,
+                :params,
+                :body
+
+    # Creates a new API signature object.
+    #
+    # options - The Hash options used to create a signature:
+    #           :api_secret - A ShippingEasy-supplied API secret
+    #           :method - The HTTP method used in the request. Either :get or :post. Default is :get.
+    #           :path - The URI path of the request. E.g. "/api/orders"
+    #           :params - The query params passed in as part of the request.
+    #           :body - The body of the request which should normally be a JSON payload.
+    #
+    def initialize(options = {})
+      @api_secret = options.delete(:api_secret) || ""
+      @method = options.fetch(:method, :get).to_s.upcase
+      @path = options.delete(:path) || ""
+      @body = options.delete(:body) || ""
+      @params = options.delete(:params) || {}
+      @params.delete(:api_signature) # remove for convenience
+    end
+
+    # Concatenates the parts of the base signature into a plaintext string using the following order:
+    #
+    # 1. Capitilized method of the request. E.g. "POST"
+    # 2. The URI path
+    # 3. The query parameters sorted alphabetically and concatenated together into a URL friendly format: param1=ABC&param2=XYZ
+    # 4. The request body as a string if one exists
+    #
+    # All parts are then concatenated together with an ampersand. The result resembles something like this:
+    #
+    # "POST&/api/orders&param1=ABC&param2=XYZ&{\"orders\":{\"name\":\"Flip flops\",\"cost\":\"10.00\",\"shipping_cost\":\"2.00\"}}"
+    #
+    # Returns a correctly contenated plaintext API signature.
+    def plaintext
+      parts = []
+      parts << method
+      parts << path
+      parts << Rack::Utils.build_query(params.sort)
+      parts << body.to_s unless body.nil? || body == ""
+      parts.join("&")
+    end
+
+    # Encrypts the plaintext signature with the supplied API secret. This signature should be included
+    # when making a ShippingEasy API call.
+    #
+    # Returns an encrypted signature.
+    def encrypted
+      OpenSSL::HMAC::hexdigest("sha256", api_secret, plaintext)
+    end
+
+    # Equality operator to determine if another signature object, or string, matches the current signature. If a string is passed in, it
+    # should represent the encrypted form of the API signature, not the plaintext version.
+    #
+    # It uses a constant time string comparison function to limit the vulnerability of timing attacks.
+    #
+    # Returns true if the supplied string or signature object matches the current object.
+    def ==(other_signature)
+      expected_signature, supplied_signature = self.to_s, other_signature.to_s
+      return false if expected_signature.blank? || supplied_signature.blank? || expected_signature.bytesize != supplied_signature.bytesize
+      l = expected_signature.unpack "C#{expected_signature.bytesize}"
+      res = 0
+      supplied_signature.each_byte { |byte| res |= byte ^ l.shift }
+      res == 0
+    end
+
+    # Returns the encrypted form of the signature.
+    #
+    # Returns an encrypted signature.
+    def to_s
+      encrypted
+    end
+
+  end
+end

data/lib/shipping_easy/version.rb

@@ -0,0 +1,3 @@
+module ShippingEasy
+  VERSION = "0.0.1"
+end

data/shipping_easy.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'shipping_easy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "shipping_easy"
+  spec.version       = ShippingEasy::VERSION
+  spec.authors       = ["ShippingEasy"]
+  spec.email         = ["dev@shippingeasy.com"]
+  spec.description   = "The official ShippingEasy API client for Ruby."
+  spec.summary       = "The official ShippingEasy API client for Ruby."
+  spec.homepage      = "https://github.com/ShippingEasy/shipping_easy-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: shipping_easy
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- ShippingEasy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: The official ShippingEasy API client for Ruby.
+email:
+- dev@shippingeasy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/shipping_easy.rb
+- lib/shipping_easy/authenticator.rb
+- lib/shipping_easy/resources/cancellations.rb
+- lib/shipping_easy/resources/order.rb
+- lib/shipping_easy/resources/store.rb
+- lib/shipping_easy/signature.rb
+- lib/shipping_easy/version.rb
+- shipping_easy.gemspec
+homepage: https://github.com/ShippingEasy/shipping_easy-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: The official ShippingEasy API client for Ruby.
+test_files: []