after_ship 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 43ff39d94f11902c3bfc5a7acfc36fc4092d5c5a
-  data.tar.gz: bab1423202559d88d3341bf209a002a85e9df8d4
+  metadata.gz: 3060bd34a3212af9a3fc8d11f6639218eb721a21
+  data.tar.gz: 6cc52a30fd7414efb6cfe67a91dd1823191bda4d
 SHA512:
-  metadata.gz: 3aff898828a87d686b144230382a77f21b68f0a324830be48dfe1ba87ef1b919aa97a9e420bd3e23501cefc00e0701637b49f416dcf9a0ebcc194db25a31e686
-  data.tar.gz: ecc0ca8bcd619d082eb59fa7ec8a52f927fd1d1c30c4a007999a57e27fab92c9bbb783f56b3ee4140e66ce43a8e8b14374371ba57e57fd7609175fe73f9df9f2
+  metadata.gz: a40b8f5a968c21b2c61fbe139c729ced7fd0d4ea66930fb1d8fbece394bdf0504d009e20b1d0090fe1cb7083119220230c57d607ac24eeaef0bfbd19efa1054d
+  data.tar.gz: 3bf32a786e3dcd6846363fa46035b67855aa312b46ff804c81570e73b4e07737bc11f6fe8aa9bc5cb59d559424f438e6d7f93a515cc4fd74faa899318b284684

data/.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 
 rvm:
-  - 2.1.2
+  - 2.1.5
   - 1.9.3
   - jruby-19mode
 

data/README.md

@@ -2,9 +2,9 @@
 
 [![Build Status](https://travis-ci.org/ollie/after_ship.svg?branch=master)](https://travis-ci.org/ollie/after_ship)
 
-A smallish library to talking to AfterShip via v3 API.
+A smallish library to talking to AfterShip via v4 API.
 
-You will need an AfterShip API key, see here https://www.aftership.com/docs/api/3.0.
+You will need an AfterShip API key, see here https://www.aftership.com/docs/api/4.
 The JSON is parsed by MultiJson (https://github.com/intridea/multi_json) so
 you may want to drop in your favorite JSON engine.
 
@@ -29,7 +29,7 @@ client = AfterShip.new(api_key: 'your-aftership-api-key')
 ```
 
 Get a list of trackings
-https://www.aftership.com/docs/api/3.0/tracking/get-trackings
+https://www.aftership.com/docs/api/4/trackings/get-trackings
 
 ```ruby
 client.trackings
@@ -44,75 +44,112 @@ client.trackings
 ```
 
 Get a tracking
-https://www.aftership.com/docs/api/3.0/tracking/get-trackings-slug-tracking_number
+https://www.aftership.com/docs/api/4/trackings/get-trackings-slug-tracking_number
 
 ```ruby
 client.tracking('tracking-number', 'ups')
 
-# Will return Tracking object or raise AfterShip::ResourceNotFoundError
-# if not exists:
+# Will return Tracking object or raise AfterShip::Error::NotFound:
 
-#<AfterShip::Tracking:0x007fe555bd9560
+#<AfterShip::Tracking:0x007f838ef44e58
   @active=false,
+  @android=[],
   @courier="UPS",
-  @created_at=#<DateTime: 2014-05-08T15:25:01+00:00 ((2456786j,55501s,0n),+0s,2299161j)>,
-  @updated_at=#<DateTime: 2014-07-18T09:00:47+00:00 ((2456857j,32447s,0n),+0s,2299161j)>>
+  @created_at=#<DateTime: 2014-11-19T15:16:17+00:00 ...>,
   @custom_fields={},
   @customer_name=nil,
+  @delivery_time=8,
   @destination_country_iso3="USA",
   @emails=[],
   @expected_delivery=nil,
-  @order_id="PL-12480166",
+  @id="546cb4414a1a2097122ae7b1",
+  @ios=[],
+  @order_id="PL-66448782",
   @order_id_path=nil,
   @origin_country_iso3="IND",
-  @shipment_package_count=0,
-  @shipment_type="EXPEDITED",
-  @signed_by="FRONT DOOR",
+  @shipment_package_count=1,
+  @shipment_type="UPS SAVER",
+  @shipment_weight=0.5,
+  @shipment_weight_unit="kg",
+  @signed_by="MET CUSTOM",
   @slug="ups",
   @smses=[],
   @source="api",
   @status="Delivered",
   @tag="Delivered",
-  @title="1ZA2207X6790326683",
-  @tracked_count=47,
-  @tracking_number="1ZA2207X6790326683",
-  @unique_token="ly9ueXUJC",
+  @title="1ZA2207X0490715335",
+  @tracked_count=6,
+  @tracking_account_number=nil,
+  @tracking_number="1ZA2207X0490715335",
+  @tracking_postal_code=nil,
+  @tracking_ship_date=nil,
+  @unique_token="-y6ziF438",
+  @updated_at=#<DateTime: 2014-11-19T22:12:32+00:00 ...>,
   @checkpoints=[
-    #<AfterShip::Checkpoint:0x007fe555bb0340
-      @checkpoint_time=#<DateTime: 2014-05-12T14:07:00+00:00 ((2456790j,50820s,0n),+0s,2299161j)>,
-      @city="NEW YORK",
+    #<AfterShip::Checkpoint:0x007f838ef57d50
+      @checkpoint_time=
+      #<DateTime: 2014-11-11T19:12:00+00:00 ...>,
+      @city="MUMBAI",
       @country_iso3=nil,
-      @country_name="US",
+      @country_name="IN",
       @courier="UPS",
-      @created_at=#<DateTime: 2014-05-12T18:34:32+00:00 ((2456790j,66872s,0n),+0s,2299161j)>,
-      @message="DELIVERED",
+      @created_at=
+      #<DateTime: 2014-11-19T15:16:17+00:00 ...>,
+      @message="PICKUP SCAN",
       @slug="ups",
-      @state="NY",
-      @status="Delivered",
-      @tag="Delivered",
-      @zip="10075">
+      @state=nil,
+      @status="In Transit",
+      @tag="InTransit",
+      @zip=nil>,
     #<AfterShip::Checkpoint ...>,
     ...
-  ]>
+  ]
+>
 ```
 
 Create a new tracking
-https://www.aftership.com/docs/api/3.0/tracking/post-trackings
+https://www.aftership.com/docs/api/4/trackings/post-trackings
 
 ```ruby
 client.create_tracking('tracking-number', 'ups', order_id: 'external-id')
 
-# Will return Tracking object or raise AfterShip::InvalidArgumentError
-# if it exists:
+# Will return Tracking object or raise
+# AfterShip::Error::TrackingAlreadyExists:
 
 #<AfterShip::Tracking ...>
 ```
 
 Update a tracking
-https://www.aftership.com/docs/api/3.0/tracking/put-trackings-slug-tracking_number
+https://www.aftership.com/docs/api/4/trackings/put-trackings-slug-tracking_number
 
 ```ruby
 client.update_tracking('tracking-number', 'ups', order_id: 'external-id')
+
+# Will return Tracking object or raise
+# AfterShip::Error::TrackingAlreadyExists:
+
+#<AfterShip::Tracking ...>
+```
+
+Get activated couriers
+https://www.aftership.com/docs/api/4/couriers/get-couriers
+
+```ruby
+client.couriers
+
+# Will return list of Courier objects:
+
+[
+  #<AfterShip::Courier:0x007fa2771d4bf8
+    @name="USPS",
+    @other_name="United States Postal Service",
+    @phone="+1 800-275-8777",
+    @required_fields=[],
+    @slug="usps",
+    @web_url="https://www.usps.com">,
+  #<AfterShip::Courier ...>
+  ...
+]
 ```
 
 ## Contributing

data/after_ship.gemspec

@@ -1,14 +1,14 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'after_ship/version'
+require 'after_ship/core/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'after_ship'
   spec.version       = AfterShip::VERSION
   spec.authors       = ['Oldrich Vetesnik']
   spec.email         = ['oldrich.vetesnik@gmail.com']
-  spec.summary       = 'A smallish library to talking to AfterShip via v3 API.'
+  spec.summary       = 'A smallish library to talking to AfterShip via v4 API.'
   spec.homepage      = 'https://github.com/ollie/after_ship'
   spec.license       = 'MIT'
 
@@ -22,11 +22,11 @@ Gem::Specification.new do |spec|
 
   # Test
   spec.add_development_dependency 'rspec',     '~> 3.1'
-  spec.add_development_dependency 'webmock',   '~> 1.19'
+  spec.add_development_dependency 'webmock',   '~> 1.20'
   spec.add_development_dependency 'simplecov', '~> 0.9'
 
   # Code style, debugging, docs
-  spec.add_development_dependency 'rubocop', '~> 0.26'
+  spec.add_development_dependency 'rubocop', '~> 0.27'
   spec.add_development_dependency 'pry',     '~> 0.10'
   spec.add_development_dependency 'yard',    '~> 0.8'
   spec.add_development_dependency 'rake',    '~> 10.3'

data/lib/after_ship/checkpoint.rb

@@ -1,42 +1,48 @@
 class AfterShip
   # Wrapper object for AfterShip tracking checkpoint:
-  # https://www.aftership.com/docs/api/3.0/tracking/get-trackings-slug-tracking_number
+  # https://www.aftership.com/docs/api/4/trackings/get-trackings-slug-tracking_number
   class Checkpoint
     include Attributes
 
-    # Tracking number, e.g. +1ZA2207X6794165804+.
+    # Date and time of the tracking created.
     #
     # Should always be available.
     #
-    # @return [String]
-    attr_reader :slug
+    # @return [DateTime]
+    attr_reader :created_at
 
-    # Location info (if any)
+    # The unique code of courier for this checkpoint message.
     #
-    # May be empty.
+    # Should always be available.
     #
     # @return [String]
-    attr_accessor :city
+    attr_reader :slug
 
-    # Courier name
+    # Courier name.
+    #
+    # Custom method!
     #
     # @return [String]
     attr_accessor :courier
 
-    # Date and time of the tracking created.
+    # Date and time of the checkpoint, provided by courier.
+    #
+    # Empty String,
+    # YYYY-MM-DD,
+    # YYYY-MM-DDTHH:MM:SS, or
+    # YYYY-MM-DDTHH:MM:SS+TIMEZONE.
     #
     # Should always be available.
     #
     # @return [DateTime]
-    attr_reader :created_at
+    attr_reader :checkpoint_time
 
-    # Country name of the checkpoint, may also contain other location info.
-    # Seems to be Alpha-2 code, e.g. +IN+, +DE+.
+    # Location info (if any).
     #
     # May be empty.
     #
     # @return [String]
-    attr_accessor :country_name
+    attr_accessor :city
 
     # Country ISO Alpha-3 (three letters) of the checkpoint.
     #
@@ -45,6 +51,14 @@ class AfterShip
     # @return [String]
     attr_accessor :country_iso3
 
+    # Country name of the checkpoint, may also contain other location info.
+    # Seems to be Alpha-2 code, e.g. +IN+, +DE+.
+    #
+    # May be empty.
+    #
+    # @return [String]
+    attr_accessor :country_name
+
     # Checkpoint message
     #
     # Should always be available.
@@ -52,6 +66,13 @@ class AfterShip
     # @return [String]
     attr_accessor :message
 
+    # Location info (if any).
+    #
+    # May be empty.
+    #
+    # @return [String]
+    attr_accessor :state
+
     # Status of the checkpoint.
     #
     # Should always be available.
@@ -73,20 +94,6 @@ class AfterShip
     # @return [String]
     attr_accessor :status
 
-    # Date and time of the checkpoint, provided by courier.
-    #
-    # Should always be available.
-    #
-    # @return [DateTime]
-    attr_reader :checkpoint_time
-
-    # Location info (if any).
-    #
-    # May be empty.
-    #
-    # @return [String]
-    attr_accessor :state
-
     # Location info (if any).
     #
     # May be empty.
@@ -101,7 +108,7 @@ class AfterShip
       load_attributes(data)
     end
 
-    # Tracking number, e.g. +1ZA2207X6794165804+.
+    # The unique code of courier for this checkpoint message.
     #
     # Should always be available.
     #

data/lib/after_ship/core/attributes.rb

@@ -0,0 +1,14 @@
+class AfterShip
+  # Extracted attributes loading.
+  module Attributes
+    # Loop through the data hash and for each key call a setter with the value.
+    #
+    # @param data [Hash]
+    def load_attributes(data)
+      data.each do |attribute, value|
+        setter = "#{ attribute }="
+        send(setter, value) if respond_to?(setter)
+      end
+    end
+  end
+end

data/lib/after_ship/core/date_utils.rb

@@ -0,0 +1,76 @@
+class AfterShip
+  # Simple utility class for parsing dates and datetimes.
+  module DateUtils
+    module_function
+
+    # Date:
+    #
+    # +YYYYMMDD+
+    DATE_PLAIN_REGEX = /
+                   \A
+                   \d{4}\d{2}\d{2}
+                   \z
+                 /x
+
+    # Date:
+    #
+    # +YYYY-MM-DD+
+    DATE_REGEX = /
+                   \A
+                   \d{4}-\d{2}-\d{2}
+                   \z
+                 /x
+
+    # Datetime without zone:
+    #
+    # +YYYY-MM-DDTHH:MM:SS+
+    DATETIME_REGEX = /
+                       \A
+                       \d{4}-\d{2}-\d{2}
+                       T
+                       \d{2}:\d{2}:\d{2}
+                       \z
+                     /x
+
+    # Datetime with zone:
+    #
+    # +YYYY-MM-DDTHH:MM:SSZ+
+    # +YYYY-MM-DDTHH:MM:SS+HH:MM+
+    # +YYYY-MM-DDTHH:MM:SS-HH:MM+
+    DATETIME_WITH_ZONE_REGEX = /
+                                 \A
+                                 \d{4}-\d{2}-\d{2}
+                                 T
+                                 \d{2}:\d{2}:\d{2}
+                                 (Z|[+-]\d{2}:\d{2})
+                                 \z
+                               /x
+
+    # Try to parse a date or datetime from a string.
+    #
+    # @param value [String]
+    #   Empty String,
+    #   YYYY-MM-DD,
+    #   YYYY-MM-DDTHH:MM:SS,
+    #   YYYY-MM-DDTHH:MM:SSZ,
+    #   YYYY-MM-DDTHH:MM:SS+HH:MM or
+    #   YYYY-MM-DDTHH:MM:SS-HH:MM.
+    #
+    def parse(value)
+      case value
+      when ''
+        nil
+      when nil
+        nil
+      when DATE_PLAIN_REGEX
+        Date.parse(value)
+      when DATE_REGEX
+        Date.parse(value)
+      when DATETIME_REGEX, DATETIME_WITH_ZONE_REGEX
+        DateTime.parse(value)
+      else
+        fail ArgumentError, "Invalid expected_delivery date #{ value.inspect }"
+      end
+    end
+  end
+end

data/lib/after_ship/core/error.rb

@@ -0,0 +1,29 @@
+class AfterShip
+  # Error classes.
+  # https://www.aftership.com/docs/api/4/errors
+  class Error < StandardError
+    class BadRequest             < Error; end      # 400
+    class InvalidJsonData        < BadRequest; end # 4001, 4002
+    class TrackingAlreadyExists  < BadRequest; end # 4003
+    class TrackingDoesNotExist   < BadRequest; end # 4004
+    class TrackingNumberInvalid  < BadRequest; end # 4005
+    class TrackingObjectRequired < BadRequest; end # 4006
+    class TrackingNumberRequired < BadRequest; end # 4007
+    class FieldInvalid           < BadRequest; end # 4008
+    class FieldRequired          < BadRequest; end # 4009
+    class SlugInvalid            < BadRequest; end # 4010
+    class CourierFieldInvalid    < BadRequest; end # 4011
+    class CourierNotDetected     < BadRequest; end # 4012
+    class RetrackNotAllowed      < BadRequest; end # 4013, 4016
+    class NotificationRequired   < BadRequest; end # 4014
+    class IdInvalid              < BadRequest; end # 4015
+    class Unauthorized           < Error; end      # 401
+    class Forbidden              < Error; end      # 403
+    class NotFound               < Error; end      # 404
+    class TooManyRequests        < Error; end      # 429
+    class InternalError          < Error; end      # 500, 502, 503, 504
+
+    class UnknownError           < Error; end      # Huh?
+    class Timeout                < Error; end      # Uh oh.
+  end
+end

data/lib/after_ship/core/error_handler.rb

@@ -0,0 +1,67 @@
+class AfterShip
+  # Response handling logic.
+  module ErrorHandler
+    module_function
+
+    # These mean that the response is good.
+    SUCCESS_CODES = [200, 201]
+
+    # Map meta codes to error classes.
+    CODE_TO_ERROR_MAP = {
+      400  => Error::BadRequest,
+      4001 => Error::InvalidJsonData,
+      4002 => Error::InvalidJsonData,
+      4003 => Error::TrackingAlreadyExists,
+      4004 => Error::TrackingDoesNotExist,
+      4005 => Error::TrackingNumberInvalid,
+      4006 => Error::TrackingObjectRequired,
+      4007 => Error::TrackingNumberRequired,
+      4008 => Error::FieldInvalid,
+      4009 => Error::FieldRequired,
+      4010 => Error::SlugInvalid,
+      4011 => Error::CourierFieldInvalid,
+      4012 => Error::CourierNotDetected,
+      4013 => Error::RetrackNotAllowed,
+      4016 => Error::RetrackNotAllowed,
+      4014 => Error::NotificationRequired,
+      4015 => Error::IdInvalid,
+      401  => Error::Unauthorized,
+      403  => Error::Forbidden,
+      404  => Error::NotFound,
+      429  => Error::TooManyRequests,
+      500  => Error::InternalError,
+      502  => Error::InternalError,
+      503  => Error::InternalError,
+      504  => Error::InternalError
+    }
+
+    # Did it timeout? If the body empty?
+    #
+    # @param response [Typhoeus::Response]
+    def precheck(response)
+      fail Error::Timeout, "#{ response.effective_url } cannot be reached" if
+        response.timed_out?
+    end
+
+    # Check the meta code of the response. If it isn't 200 or 201, raise an
+    # error.
+    #
+    # @param  meta         [Hash]
+    # @option meta code    [Fixnum]
+    # @option meta message [String, nil]
+    # @option meta type    [String, nil]
+    def check(meta)
+      code = meta.fetch(:code)
+
+      return if SUCCESS_CODES.include?(code)
+
+      error_class = error_class_for(code)
+      fail error_class, meta[:message]
+    end
+
+    # Pick the corresponding error class for the code.
+    def error_class_for(code)
+      CODE_TO_ERROR_MAP[code] || Error::UnknownError
+    end
+  end
+end

data/lib/after_ship/core/request.rb

@@ -0,0 +1,131 @@
+class AfterShip
+  # Gather necessary pieces, assemble a `Typhoeus::Request`, run that,
+  # get a `Typhoeus::Response`, parse that, check for errors, return the
+  # parse JSON.
+  class Request
+    # Shorthand for GET request:
+    #
+    #   request  = Request.new(url: '...', api_key: '...', method: :get)
+    #   response = request.response
+    #
+    # @param  options         [Hash]
+    # @option options api_key [String]    Your API key.
+    # @option options url     [String]    The full endpoint URL.
+    # @option options body    [Hash, nil] Body for the request as a hash.
+    #
+    # @return [Hash]
+    def self.get(options, &block)
+      options[:method] = :get
+      new(options, &block).response
+    end
+
+    # Shorthand for POST request:
+    #
+    #   request  = Request.new(url: '...', api_key: '...', method: :post)
+    #   response = request.response
+    #
+    # @param  options         [Hash]
+    # @option options api_key [String]    Your API key.
+    # @option options url     [String]    The full endpoint URL.
+    # @option options body    [Hash, nil] Body for the request as a hash.
+    #
+    # @return [Hash]
+    def self.post(options, &block)
+      options[:method] = :post
+      new(options, &block).response
+    end
+
+    # Shorthand for PUT request:
+    #
+    #   request  = Request.new(url: '...', api_key: '...', method: :put)
+    #   response = request.response
+    #
+    # @param  options         [Hash]
+    # @option options api_key [String]    Your API key.
+    # @option options url     [String]    The full endpoint URL.
+    # @option options body    [Hash, nil] Body for the request as a hash.
+    #
+    # @return [Hash]
+    def self.put(options, &block)
+      options[:method] = :put
+      new(options, &block).response
+    end
+
+    # Prepare the request to be run later.
+    #
+    # @param  options         [Hash]
+    # @option options api_key [String]    Your API key.
+    # @option options url     [String]    The full endpoint URL.
+    # @option options method  [Symbol]    The HTTP method.
+    # @option options body    [Hash, nil] Body for the request as a hash.
+    # @param  block           [Proc]      Response modifier callback.
+    def initialize(options = {}, &block)
+      @api_key = options.fetch(:api_key)
+      @url     = options.fetch(:url)
+      @method  = options.fetch(:method)
+      @body    = options[:body]
+      @request = typhoeus_request
+      @block   = block
+    end
+
+    # Do the request to the server and handle the response.
+    def response
+      response    = typhoeus_response
+      ErrorHandler.precheck(response)
+      parsed_body = MultiJson.load(response.body, JSON_OPTIONS)
+      ErrorHandler.check(parsed_body.fetch(:meta))
+
+      if @block
+        @block.call(parsed_body)
+      else
+        parsed_body
+      end
+    end
+
+    protected
+
+    # Run the `Typhoeus::Request` and return the response.
+    #
+    # @return [Typhoeus::Request]
+    def typhoeus_response
+      @request.run
+    end
+
+    # Make the `Typhoeus::Request` to be run later.
+    #
+    # @return [Typhoeus::Request]
+    def typhoeus_request
+      request = Typhoeus::Request.new(
+        @url,
+        method:  @method,
+        headers: {
+          'aftership-api-key' => @api_key,
+          'Content-Type'      => 'application/json'
+        }
+      )
+
+      request.options[:body] = MultiJson.dump(@body) if @body
+      make_verbose(request) if AfterShip.debug
+
+      request
+    end
+
+    # Print the low level cURL internals in the console as well as the
+    # request body and response body when it's available.
+    #
+    # @param request [Typhoeus::Request]
+    def make_verbose(request)
+      request.options[:verbose] = true
+
+      request.on_complete do |response|
+        puts
+        puts 'Request body:'
+        puts request.options[:body]
+        puts
+        puts 'Response body:'
+        puts response.body
+        puts
+      end
+    end
+  end
+end

data/lib/after_ship/core/version.rb

@@ -0,0 +1,4 @@
+class AfterShip
+  # Version number, happy now?
+  VERSION = '0.0.4'
+end