pactrac 0.0.1

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2012, Michael Alexander
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met: 
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer. 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies, 
+either expressed or implied, of Miniand.

data/README.md

@@ -0,0 +1,148 @@
+PacTrac - International package tracking for Ruby
+=================================================
+
+PacTrac is a library which can be used via API and CLI to fetch raw tracking
+data.  In the initial alpha, only DHL is supported, but a number of other
+methods are in the process of being added.
+
+Installation
+============
+
+```bash
+gem install pactrac
+```
+
+CLI
+===
+
+The binary `pactrac` is included with the gem, usable from the command line.
+
+### Basic usage
+
+If not specified, the carrier company is guessed.
+
+```bash
+$ pactrac track 1234567890
+```
+
+### Specifying carrier
+
+```bash
+$ pactrac track 1234567890 --carrier Dhl
+```
+
+### Verifying the request
+
+Some shipping carriers, such as EMS, require CAPTCHA style verifications.  The
+CLI allows for this by downloading the CAPTCHA image to a temporary directory,
+and allowing you to run the command again adding your verification input.
+
+```bash
+$ be pactrac track EE123456789CN
+EMS requires verification, please view the image at
+file:///tmp/pactrac_1345961387_ems.jpg and run pactrac again using the following
+command:
+
+pactrac track EE123456789CN --carrier Ems --cookie JSESSIONID\=WrTlQ59KBnfpq1pWp
+hgySgYPTSln1p6rrhDd2pSvFyJt2LJGQ9dr\!-1493181672\;\ TS79e94e\=4f22237fc7dc1c7bf7
+176dda6b8992a70d84d223c37efee05039bc0060ac0ec5c32dd2e9
+--verify YOUR_VERIFICATION_HERE
+```
+
+API
+===
+
+To include PacTrac, add `require 'pactrac'` to your script.
+
+### Returning error status as part of a pair
+
+A number of functions which expect failure return a pair of values instead of
+just one, to avoid returning different types and to avoid exceptions as control
+flow.  The first value is an error struct, with offsets `valid` and `msg`.  If
+`valid` is true then the function call was successful, if it is false then `msg`
+will be populated with an error message.
+
+### Discover a carrier based on a tracking number
+
+```ruby
+PacTrac::Carrier.for_tracking_number('EE123456789')
+```
+
+Returns a pair of values, the first an Err struct, the second is the
+corresponding carrier module.
+
+### Request tracking information
+
+```ruby
+require 'pactrac'
+
+carrier = PacTrac::Carrier.for_tracking_number('1234567890')
+session = carrier.start_session   # Start an HTTP session, used in requests
+err, response = carrier.tracking_request('1234567890', session)
+raise 'Error getting tracking information' unless err.valid
+raise 'Verification needed' if response.requires_verification
+err, tracking_data = carrier.parse_tracking_data(response)
+raise 'Error getting response' unless err.valid
+puts "Delivery via #{carrier.title} from #{tracking_data[:origin]} to
+  #{tracking_data[:destination]}"
+# Output updates ordered by latest
+tracking_data[:updates].sort_by { |u| u[:at] }.reverse.each do |u|
+  puts "Update time #{u[:at]}: package at #{u[:location]} with message
+    #{u[:message]}"
+end
+```
+
+### Sending verification data
+
+If you have made a tracking request and it requires verification, the
+`requires_verification` value in the tracking data struct will be true, and the
+`verification_image` will be set as a URI for the location of the image.
+Usually the image is downloaded to the local filesystem (file://) for checking.
+
+After manually checking the verification image, a second request is made to the
+server.  The cookies from the previous request need to be sent to the new
+request.
+
+```ruby
+require 'pactrac'
+require 'pactrac/http/cookie'
+
+carrier = PacTrac::Carrier.for_tracking_number('EE123456789CN')
+session = carrier.start_session   # Start an HTTP session, used in requests
+err, response = carrier.tracking_request('EE123456789CN', session)
+raise "Error getting tracking information, #{err.msg}" unless err.valid
+if response.requires_verification
+  session.cookies = PacTrac::Http::Cookie.from_response(response)
+  err, response = carrier.verify('EE123456789CN', 'JHRPDS', session)
+  raise "Error verifying, #{err.msg}" unless err.valid
+end
+err, tracking_data = carrier.parse_tracking_data(response)
+raise "Error getting response, #{err.msg}" unless err.valid
+puts "Delivery via #{carrier.title} from #{tracking_data[:origin]} to
+  #{tracking_data[:destination]}"
+# Output updates ordered by latest
+tracking_data[:updates].sort_by { |u| u[:at] }.reverse.each do |u|
+  puts "Update time #{u[:at]}: package at #{u[:location]} with message
+    #{u[:message]}"
+end
+```
+
+Supported carriers
+==================
+
+*  EMS - PacTrac::Carrier::Ems
+*  DHL - PacTrac::Carrier::Dhl
+
+Testing
+=======
+
+Automated testing is done through rspec, and can be run from rake using
+`rake spec`.
+
+Style
+=====
+
+The gem is written in a functional style, avoiding side effects of functions and
+aiming to keep them pure.  The gem is also written to avoid returning different
+types, so many functions return a pair of values, one for exit status / message,
+and the other for the actual return value.

data/bin/pactrac

@@ -0,0 +1,107 @@
+#!/usr/bin/ruby
+require 'pactrac'
+require 'pactrac/http/cookie'
+require 'terminal-table'
+require 'commander/import'
+require 'shellwords'
+require 'colorize'
+
+program :name, 'PacTrac'
+program :version, '0.0.1'
+program :description, 'Internation package tracker in Ruby'
+
+command :track do |c|
+  c.syntax = 'pactrac track <tracking_number> [options]'
+  c.description = 'Track a package by tracking number'
+  c.option '--carrier STRING', String,
+    'Specify the carrier, otherwise carrier is detected'
+  c.option '--cookie STRING', String,
+    'Specify cookie data to set when verifying'
+  c.option '--verify STRING', String,
+    'Specify the verification string'
+  c.action do |args, options|
+    tracking_number = args.first
+    if tracking_number.nil?
+      $stderr.puts("Please specify a tracking number".red)
+      exit(1)
+    end
+    carrier = nil
+    if options.carrier.nil?
+      err, carrier = PacTrac::Carrier.for_tracking_number(
+        tracking_number)
+      unless err.valid
+        $stderr.puts(
+          "Could not match to a carrier, please specify with --carrier".red)
+        exit(2)
+      end
+    else
+      begin
+        carrier = PacTrac::Carrier.const_get(options.carrier)
+      rescue
+        $stderr.puts("No carrier with the name #{options.carrier}".red)
+        exit(3)
+      end
+    end
+    session = carrier.start_session
+    if options.verify.nil?
+      err, resp = carrier.tracking_request(tracking_number, session)
+    else
+      unless options.cookie.nil?
+        session.cookies = PacTrac::Http::Cookie.from_request_header_value(
+          options.cookie)
+      end
+      err, resp = carrier.verify(tracking_number, options.verify, session)
+    end
+    unless err.valid
+      $stderr.puts("Error requesting tracking data: #{err.msg}".red)
+      exit(4)
+    end
+    if resp.requires_verification
+      $stdout.puts("#{carrier.title} requires verification, please view the " +
+        "image at #{resp.verification_image.green} and run pactrac again " +
+        "using the following command:")
+      $stdout.puts
+      cookies = PacTrac::Http::Cookie.from_response(resp)
+      cookies_string = cookies.length == 0 ? '' : ' --cookie ' +
+        Shellwords.escape(PacTrac::Http::Cookie.to_request_header_value(
+          cookies))
+      $stdout.puts("pactrac track #{Shellwords.escape(tracking_number)
+        } --carrier #{carrier.name.split('::').last}#{cookies_string
+        } --verify " + "YOUR_VERIFICATION_HERE".green)
+      exit(5)
+    else
+      err, tracking_data = carrier.parse_tracking_data(resp)
+      unless err.valid
+        $stderr.puts("Error parsing tracking data: #{err.msg}".red)
+        exit(6)
+      end
+    end
+
+    # Discovers headings from updates
+    headings = [ :at, :location, :message ]
+    tracking_data[:updates].each do |u|
+      u.keys.each do |key|
+        headings << key unless headings.include?(key)
+      end
+    end
+    rows = tracking_data[:updates].sort_by { |u| u[:at] }.reverse.map do |u|
+      headings.map { |heading| u[heading] }
+    end
+
+    PacTrac::Http::Session.finish(session)
+    $stdout.puts("Tracking number: #{tracking_number}")
+    $stdout.puts("Carrier: #{carrier.title}")
+    unless tracking_data[:origin].nil?
+      $stdout.puts("Origin: #{tracking_data[:origin]}")
+    end
+    unless tracking_data[:destination].nil?
+      $stdout.puts("Destination: #{tracking_data[:destination]}")
+    end
+    $stdout.puts
+
+    puts Terminal::Table.new(:headings => headings.map { |h|
+      h.to_s.capitalize }, :rows => rows)
+  end
+end
+
+default_command :help

data/lib/pactrac.rb

@@ -0,0 +1,2 @@
+require 'pactrac/carrier'
+require 'pactrac/err'

data/lib/pactrac/carrier.rb

@@ -0,0 +1,20 @@
+require 'pactrac/carrier/dhl'
+require 'pactrac/carrier/ems'
+require 'pactrac/err'
+
+module PacTrac
+  module Carrier
+    module_function
+
+    def all
+      [Carrier::Dhl, Carrier::Ems]
+    end
+
+    def for_tracking_number(tracking_number)
+      all.each do |c|
+        return Err.new(true), c if c.tracking_number_relevant?(tracking_number)
+      end
+      return Err.new(false, 'unable to match tracking number to carrier')
+    end
+  end
+end

data/lib/pactrac/carrier/dhl.rb

@@ -0,0 +1,81 @@
+require 'nokogiri'
+require 'pactrac/err'
+require 'pactrac/response'
+require 'pactrac/http'
+require 'pactrac/http/session'
+require 'net/http'
+require 'date'
+
+module PacTrac
+  module Carrier
+    module Dhl
+      module_function
+
+      def title
+        'DHL'
+      end
+
+      def tracking_number_relevant?(tracking_number)
+        tracking_number.strip.match(/^\d{10}$/)
+      end
+
+      def tracking_request(tracking_number, session)
+        err, raw = Http.request(Net::HTTP::Get.new(
+          "/content/g0/en/express/tracking.shtml" +
+          "?brand=DHL&AWB=#{tracking_number}%0D%0A", 'User-Agent' =>
+            'Mozilla/5.0 (Windows NT 6.0) AppleWebKit/537.1 (KHTML, like' +
+            ' Gecko) Chrome/21.0.1180.75 Safari/537.1'), session)
+        unless err.valid
+          return Err.new(false,
+            "there was a problem connecting to the DHL server, #{err.msg}")
+        end
+        return Err.new(true), Response.new(raw, false)
+      end
+
+      def parse_tracking_data(response)
+        doc = Nokogiri::HTML(response.raw.body)
+        table = doc.css('.clpt_tracking_results table').first
+        if table.nil?
+          return Err.new(false, 'unable to find tracking data table')
+        end
+        tracking_data = { :updates => [] }
+        origin_node = table.css('#orginURL4').first
+        if origin_node.nil?
+          return Err.new(false, 'unable to find origin')
+        end
+        tracking_data[:origin] = origin_node.content
+        destination_node = table.css('#destinationURL4').first
+        if destination_node.nil?
+          return Err.new(false, 'unable to find destination')
+        end
+        tracking_data[:destination] = destination_node.content
+        current_date = nil
+        table.children.each do |section|
+          next unless ['thead', 'tbody'].include?(section.name.to_s)
+          next if section.attribute('class').to_s == 'tophead'
+          section.css('tr').each do |row|
+            cells = row.css('td, th')
+            first_cell = cells.first
+            case
+            when first_cell.name == 'th' # Date cell
+              current_date = Date.parse(first_cell.content)
+            when first_cell.attribute('class').to_s != 'emptyRow'
+              next if current_date.nil?
+              tracking_data[:updates] << {
+                :message => cells[1].content.strip,
+                :location => cells[2].content.strip,
+                :at => DateTime.parse(
+                  "#{current_date.to_s}T#{cells[3].content.to_s}"),
+              }
+            end
+          end
+        end
+        return Err.new(true), tracking_data
+      end
+
+      def start_session
+        Http::Session.start('www.dhl.com', 80)
+      end
+    end
+  end
+end

data/lib/pactrac/carrier/ems.rb

@@ -0,0 +1,87 @@
+require 'nokogiri'
+require 'pactrac/err'
+require 'pactrac/response'
+require 'pactrac/http'
+require 'pactrac/http/session'
+require 'pactrac/http/cookie'
+require 'pactrac/verify/file'
+require 'net/http'
+require 'date'
+
+module PacTrac
+  module Carrier
+    module Ems
+      module_function
+
+      def title
+        'EMS'
+      end
+
+      def tracking_number_relevant?(tracking_number)
+        tracking_number.strip.match(/^EE\d+CN$/)
+      end
+
+      def tracking_request(tracking_number, session)
+        err, raw = Http.request(Net::HTTP::Get.new('/english.html',
+          'User-Agent' => user_agent), session)
+        return err unless err.valid
+        # Get validation image
+        err, raw = Http.request(Net::HTTP::Get.new('/ems/rand',
+          'User-Agent' => user_agent), session)
+        unless err.valid
+          return Err.new(false,
+            "there was a problem connecting to the EMS server, #{err.msg}")
+        end
+        f = Verify::File.create('ems.jpg', raw.body)
+        return Err.new(true), Response.new(raw, true, "file://#{f}")
+      end
+
+      def verify(tracking_number, verification, session)
+        req = Net::HTTP::Post.new('/ems/order/singleQuery_e',
+          'User-Agent' => user_agent)
+        req.set_form_data({ :mailNum => tracking_number, :checkCode =>
+          verification })
+        if session.cookies
+          req['Cookie'] = Http::Cookie.to_request_header_value(session.cookies)
+        end
+        err, raw = Http.request(req, session)
+        unless err.valid
+          return Err.new(false,
+            "there was a problem connecting to the EMS server, #{err.msg}")
+        end
+        if raw.body.match(/failure/i)
+          return Err.new(false, 'failure to verify using given code')
+        end
+        return Err.new(true), Response.new(raw, false)
+      end
+
+      def parse_tracking_data(response)
+        doc = Nokogiri::HTML(response.raw.body)
+        table = doc.css('.mailnum_result_box table')
+        if table.nil?
+          return Err.new(false, 'unable to find tracking data table')
+        end        
+        tracking_data = { :updates => [] }
+        table.css('tr').each do |row|
+          cells = row.css('td')
+          next if cells.nil? or cells.length < 2
+          tracking_data[:updates] << {
+            :at => DateTime.parse(cells[0].content.to_s),
+            :location => cells[1].content.to_s.strip,
+            :message => cells[2].content.to_s.strip,
+          }
+        end
+        return Err.new(true), tracking_data
+      end
+
+      def start_session
+        Http::Session.start('www.ems.com.cn', 80)
+      end
+
+      def user_agent
+        'Mozilla/5.0 (Windows NT 6.0) AppleWebKit/537.1 (KHTML, like' +
+          ' Gecko) Chrome/21.0.1180.75 Safari/537.1'
+      end
+    end
+  end
+end

data/lib/pactrac/err.rb

@@ -0,0 +1,3 @@
+module PacTrac
+  Err = Struct.new(:valid, :msg)
+end

data/lib/pactrac/http.rb

@@ -0,0 +1,22 @@
+require 'timeout'
+require 'net/http'
+
+module PacTrac
+  module Http
+    module_function
+
+    def request(req, session)
+      raw = nil
+      begin
+        Timeout::timeout(10) do
+          raw = session.session.request(req)
+        end
+      rescue Timeout::Error => e
+        return Err.new(false, 'tracking request took too long to respond')
+      rescue Net::HTTPError => e
+        return Err.new(false, 'error making tracking request')
+      end
+      return Err.new(true), raw
+    end
+  end
+end

data/lib/pactrac/http/cookie.rb

@@ -0,0 +1,58 @@
+require 'uri'
+
+module PacTrac
+  module Http
+    module Cookie
+      module_function
+
+      def from_response(response)
+        from_raw(response.raw)
+      end
+
+      def from_raw(raw)
+        cookies = {}
+        raw.get_fields('Set-Cookie').each do |c|
+          key, value = from_response_header_value(c)
+          cookies[key] = value
+        end
+        cookies
+      end
+
+      def from_response_header_value(header_value)
+        header_value.split(/\s*;\s*/)[0].split(/\s*=\s*/)[0,2].map {|t|
+          URI.unescape(t) }
+      end
+
+      def update_from_response(response, cookies)
+        update_from_raw(response.raw, cookies)
+      end
+
+      def update_from_raw(raw, cookies)
+        c = cookies.clone
+        from_raw(raw).each do |key, value|
+          c[key] = value
+        end
+        c
+      end
+
+      def to_request_header_value(cookies)
+        cookies.map { |key, value|
+          "#{URI.escape(key, ',;=')}=#{URI.escape(value, ',;=')}"
+        }.join('; ')
+      end
+
+      def to_request_header(cookies)
+        "Cookie: #{to_request_header_value(cookies)}"
+      end
+
+      def from_request_header_value(header_value)
+        header_value.split(/\s*;\s*/).reject{ |v| v.strip == '' }.map { |p| 
+          p.split(/\s*=\s*/)[0,2].map {|t| URI.unescape(t) }
+        }.inject({}) { |hash, (key, value)|
+          hash[key] = value
+          hash
+        }
+      end
+    end
+  end
+end

data/lib/pactrac/http/session.rb

@@ -0,0 +1,19 @@
+require 'net/http'
+
+module PacTrac
+  module Http
+    module Session
+      module_function
+
+      Store = Struct.new(:session, :cookies)
+
+      def start(address, port)
+        Store.new(Net::HTTP.start(address, port), {})
+      end
+
+      def finish(session)
+        session.session.finish
+      end
+    end
+  end
+end

data/lib/pactrac/response.rb

@@ -0,0 +1,3 @@
+module PacTrac
+  Response = Struct.new(:raw, :requires_verification, :verification_image)
+end

data/lib/pactrac/verify/file.rb

@@ -0,0 +1,17 @@
+require 'tmpdir'
+
+module PacTrac
+  module Verify
+    module File
+      module_function
+
+      def create(name, data)
+        filename = ::File.join(Dir.tmpdir, "pactrac_#{Time.now.to_i}_#{name}")
+        ::File.open(filename, 'w') do |f|
+          f.write(data)
+        end
+        filename
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification 
+name: pactrac
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Alexander
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-08-23 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 5
+        - 5
+        version: 1.5.5
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: commander
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 63
+        segments: 
+        - 4
+        - 1
+        - 2
+        version: 4.1.2
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: terminal-table
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 4
+        - 5
+        version: 1.4.5
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: colorize
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 5
+        - 8
+        version: 0.5.8
+  type: :runtime
+  version_requirements: *id004
+description: International package tracking for Ruby
+email: beefsack@gmail.com
+executables: 
+- pactrac
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/pactrac/carrier/dhl.rb
+- lib/pactrac/carrier/ems.rb
+- lib/pactrac/err.rb
+- lib/pactrac/http.rb
+- lib/pactrac/http/session.rb
+- lib/pactrac/http/cookie.rb
+- lib/pactrac/carrier.rb
+- lib/pactrac/verify/file.rb
+- lib/pactrac/response.rb
+- lib/pactrac.rb
+- bin/pactrac
+- LICENSE
+- README.md
+homepage: https://github.com/Miniand/pactrac
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: pactrac
+test_files: []
+