tracking_number 0.10.5 → 1.0.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: '0361787dd819144799899504060b5fad1c152fd8'
-  data.tar.gz: 93e3270a902aef5ac81580c5add4c7f94872d9ac
+SHA256:
+  metadata.gz: 7732c76f5896712c793106dbc515f67107764228741950d6eff1a73c0daeef9c
+  data.tar.gz: 62d14ce8cc6a9899f01963b28f0234872eba8b0a9b0d5334adb1a4d3d1c23ad0
 SHA512:
-  metadata.gz: 771dd5aa40219a4f6386a2c73ddfda1b10e0a1230ea1b672efc4af8c0d41472080ae6a036f4c90c99384e93024feec8abc9f831b6c593d8ff2da2301690fc51d
-  data.tar.gz: a30fbe05e145adf611bb8a13b375246926c36dd81509d47210f05c227a637e0f7daffe748df739eb692adeb6ef82713a4cf57ae8d45d30770ebec8cc1f02a10e
+  metadata.gz: cdfcbdbff995f2a51f4f2e3896d7abfcc49277ec4b6642a319f89dc8d4470f62903ddbf8fa0118b9c49709494976f88b5133a286362c08ec5421468b8fdfc4fb
+  data.tar.gz: e9410104da284a7a8dd71bb64ea1102f1aae30b504c8d4c92817110b856f40e2e327bd788f651e83f8e3c263ee00916470c7c2f14d8afa6451189a1e23c54ba5

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/data"]
+	path = lib/data
+	url = https://github.com/jkeen/tracking_number_data

data/.travis.yml

@@ -2,11 +2,19 @@ language: ruby
 sudo: false
 cache: bundler
 rvm:
-  - "1.9.3"
-  - "2.0.0"
-  - "2.1.10"
-  - "2.2.7"
-  - "2.3.4"
-  - "2.4.1"
+- 2.0.0
+- 2.1.10
+- 2.2.7
+- 2.3.4
+- 2.4.1
 before_install:
-  - travis_retry gem update --system
+- travis_retry gem update --system
+deploy:
+  provider: rubygems
+  api_key:
+    secure: AkaGJCc8pCkVY5IPVa3dwvS4wvPlMHHkyqrIpi8G5nFiDFjtHjWY7tDUfFCxMrF7WNXWVNg/bgkzwfvoAZcvGVU9grzCDqTC9uvsF5V3hB5FikyQ6h++mJRCiYzfLbjzyAT3FAuB49dXYeZR/eOKPPqn9jMAQPyHd6+PAGE3BeI=
+  gem: tracking_number
+  on:
+    tags: true
+    repo: jkeen/tracking_number
+

data/Gemfile

@@ -1,3 +1,5 @@
 source "http://rubygems.org"
 # Specify your gem's dependencies in tracking_number.gemspec
 gemspec
+
+gem "pry"

data/README.md

@@ -1,35 +1,105 @@
-## tracking_number
+## Tracking Number (v1.x)
 
-This gem identifies valid tracking numbers and the service they're associated with. It can also tell you a little bit about the package purely from the number—there's quite a bit of info tucked away into those numbers, it turns out.
+This gem identifies valid tracking numbers and can tell you a little bit about the shipment just from the number—there's quite a bit of info tucked away into those numbers, it turns out.
+
+It detects tracking numbers from UPS, FedEx, DHL, USPS, OnTrac, Amazon Logistics, and 160+ countries national postal services (S10 standard).
 
 This gem does not do tracking. That is left up to you.
 
+## Usage
+
+#### Checking an individual tracking number
 ```ruby
 t = TrackingNumber.new("MYSTERY_TRACKING_NUMBER")
 # => #<TrackingNumber::Unknown MYSTERY_TRACKING_NUMBER>
-
 t.valid? #=> false
-t.carrier #=> :unknown
 
 t = TrackingNumber.new("1Z879E930346834440")
 # => #<TrackingNumber::UPS 1Z879E930346834440>
-
 t.valid? #=> true
-t.carrier #=> :ups
 ```
-Also can take a block of text and find all the valid tracking numbers within it
+
+#### Searching a block of text
+This will return valid tracking numbers contained within a block of text.
 
 ```ruby
-TrackingNumber.search("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, 1Z879E930346834440
-nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis
-aute 9611020987654312345672 dolor in reprehenderit in voluptate velit esse cillum dolore eu
-fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
-officia deserunt mollit anim id est laborum.")
+TrackingNumber.search("Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, 1Z879E930346834440 nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute 9611020987654312345672 dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.")
 
 #=> [#<TrackingNumber::UPS 1Z879E930346834440>, #<TrackingNumber::FedExGround96 9611020987654312345672>]
 ```
 
+#### Courier Info
+As of 1.0, the possible courier codes are `[:usps, :fedex, :ups, :ontrac, :dhl, :amazon, :s10, :unknown]`. S10 is the international standard used by local government post offices. When packages are shipped internationally via normal post, it's usually an S10 number.
+
+```ruby
+t = TrackingNumber.new("1Z879E930346834440")
+# => #<TrackingNumber::UPS 1Z879E930346834440>
+
+t.valid? #=> true
+t.courier_code #=> :ups
+t.courier_name #=> "UPS"
+
+
+t = TrackingNumber.new("RB123456785GB")
+t.courier_name #=> "Royal Mail Group plc"
+t.courier_code #=> :s10
+
+t = TrackingNumber.new("RB123456785US")
+t.courier_name #=> "United States Postal Service"
+```
+
+#### Service Type
+Some tracking numbers indicate their service type
+
+```ruby
+t = TrackingNumber.new("1Z879E930346834440")
+t.service_type #=> "UPS United States Ground""
+
+t = TrackingNumber.new("1ZXX3150YW44070023")
+t.service_type #=> "UPS SurePost - Delivered by the USPS"
+
+t = TrackingNumber.new("RB123456785US")
+t.service_type #=> "Letter Post Registered"
+```
+
+#### Shipper ID
+Some tracking numbers indicate information about their package
+```ruby
+t = TrackingNumber.new("1Z6072AF0320751583")
+t.shipper_id #=> "6072AF" <-- this is Target
+```
+
+#### Destination Zip
+Some tracking numbers indicate their destination
+
+```ruby
+t = TrackingNumber.new("1001901781990001000300617767839437")
+t.destination_zip #=> "10003"
+```
+
+#### Package Info
+Some tracking numbers indicate information about their package
+
+```ruby
+t = TrackingNumber.new("012345000000002")
+t.package_type #=> "case/carton"
+```
+
+#### Decoding
+Most tracking numbers have a format where each part of the number has meaning. `decode` splits up the number into its known named parts.
+```ruby
+  t = TrackingNumber.new("1Z879E930346834440")
+  t.decode
+
+  #=> {
+  #  :serial_number => "879E93034683444",
+  #  :shipper_id => "879E93",
+  #  :service_type => "03",
+  #  :package_id => "4683444",
+  #  :check_digit => "0"
+  # }   
+```
+
 ## ActiveModel validation
 
 For Rails 3 (or any ActiveModel client), validate your fields as a tracking number:
@@ -46,8 +116,10 @@ class Shipment < ActiveRecord::Base
 end
 ```
 
-## Contributing to tracking_number
+## Where the data comes from
+Starting with the 1.0 release of this gem the data for tracking numbers has been extracted into a separate repository ([tracking_number_data](http://github.com/jkeen/tracking_number_data)) so non-ruby clients can benefit from the detection/documentation that used to be contained deep in the code of this gem. If you want to write a client in some other language, that's the stuff you want.
 
+## Contributing to tracking_number
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
 * Fork the project
@@ -58,5 +130,5 @@ end
 
 ## Copyright
 
-Copyright (c) 2010 Jeff Keen. See LICENSE.txt for
+Copyright (c) 2010-2018 Jeff Keen. See LICENSE.txt for
 further details.

data/Rakefile

@@ -3,6 +3,9 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 require 'rake'
 require 'rake/testtask'
+
+import './lib/tasks/stats.rake'
+
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/*_test.rb'

data/lib/checksum_validations.rb

@@ -0,0 +1,63 @@
+module ChecksumValidations
+  class << self
+    def validates_s10?(sequence, check_digit, extras = {})
+      weighting = [8,6,4,2,3,5,9,7]
+
+      total = 0
+      sequence.chars.to_a.zip(weighting).each do |(a,b)|
+        total += a.to_i * b.to_i
+      end
+
+      remainder = total % 11
+      check = case remainder
+      when 1
+        0
+      when 0
+        5
+      else
+        11 - remainder
+      end
+
+      return check.to_i == check_digit.to_i
+    end
+
+    def validates_sum_product_with_weightings_and_modulo?(sequence, check_digit, extras = {})
+      weighting = extras[:weightings] || []
+
+      total = 0
+      sequence.chars.to_a.zip(weighting).each do |(a,b)|
+        total += a.to_i * b
+      end
+      return (total % extras[:modulo1] % extras[:modulo2]) == check_digit.to_i
+    end
+
+    def validates_mod10?(sequence, check_digit, extras = {})
+      total = 0
+      sequence.chars.each_with_index do |c, i|
+        x = if c[/[0-9]/] # numeric
+          c.to_i
+        else
+          (c[0].ord - 3) % 10
+        end
+
+        if extras[:odds_multiplier] && i.odd?
+          x *= extras[:odds_multiplier].to_i
+        elsif extras[:evens_multiplier] && i.even?
+          x *= extras[:evens_multiplier].to_i
+        end
+
+        total += x
+      end
+
+      check = (total % 10)
+      check = (10 - check) unless (check.zero?)
+
+      return (check.to_i == check_digit.to_i)
+    end
+
+    def validates_mod7?(sequence, check_digit, extras = {})
+      # standard mod 7 check
+      return true if sequence.to_i % 7 == check_digit.to_i
+    end
+  end
+end

data/lib/tasks/stats.rake

@@ -0,0 +1,90 @@
+require 'terminal-table'
+
+def courier_data
+  courier_data = Dir.glob(File.join(File.dirname(__FILE__), "../../lib/data/couriers/*.json")).collect do |file|
+    JSON.parse(File.read(file)).deep_symbolize_keys!
+  end
+end
+
+def all_number_groups
+  number_groups = []
+  courier_data.each do |courier_info|
+    courier_info[:tracking_numbers].each do |tracking_info|
+      test_number = tracking_info[:test_numbers][:valid].first
+      t = TrackingNumber.new(test_number)
+      # keys = t.decode.keys.select { |s| ![:serial_number, :check_digit].include?(s) }
+      number_groups << t.decode.keys
+    end
+  end
+  groups = number_groups.flatten.uniq.sort
+end
+
+def has_key?(tracking_numbers, key)
+  tracking_numbers = [tracking_numbers].flatten
+  tracking_numbers.first.decode[key]
+end
+
+def has_additional_key_info?(tracking_numbers, key)
+  tracking_numbers = [tracking_numbers].flatten
+
+  if key == :service_type
+    tracking_numbers.any? { |t| t.service_type }
+  elsif key == :shipping_container_type
+    tracking_numbers.any? { |t| t.package_info }
+  elsif key == :destination_zip
+    tracking_numbers.any? { |t| t.destination }
+  end
+end
+
+
+  desc "show stats for tracking number types"
+  task :stats do
+    rows = []
+
+    courier_data.each do |courier_info|
+      courier_name = courier_info[:name]
+      courier_code = courier_info[:courier_code].to_sym
+
+      courier_info[:tracking_numbers].each do |tracking_info|
+        tracking_type = tracking_info[:name]
+
+        if tracking_type == "S10"
+          country_count = tracking_info[:additional].detect { |r| r[:regex_group_name] == "CountryCode" }[:lookup].size
+          tracking_type = "S10 (#{country_count} types)"
+        end
+
+        tracking_numbers = tracking_info[:test_numbers][:valid].collect { |n| TrackingNumber.new(n) }
+
+        checksum_status = tracking_numbers.first.valid_checksum? &&
+
+        checksum = tracking_numbers.first.class.const_get(:VALIDATION)[:checksum]
+        if checksum
+          checksum_status = '✓'
+        else
+          checksum_status = ''
+        end
+
+
+        status = all_number_groups.collect do |key|
+           s = has_key?(tracking_numbers, key) ? '✓' : ''
+           s = has_additional_key_info?(tracking_numbers, key) ? '✓+' : s
+
+           s
+        end
+
+        rows << [tracking_type, checksum_status, *status]
+      end
+    end
+
+    additional_headers = all_number_groups.collect { |g|
+      if g.length > 10
+        g.to_s.split('_').join("_\n")
+      else
+        g
+      end
+    }
+
+    table = Terminal::Table.new :title => "Tracking Number Stats [✓ = information present in number, ✓+ = additional information available]", :headings => ['Tracking Number', 'Checksum', *additional_headers], :rows => rows
+
+    puts table
+  end

data/lib/tracking_number.rb

@@ -2,21 +2,83 @@
 
 # Information on validating tracking numbers found here:
 # http://answers.google.com/answers/threadview/id/207899.html
-
+require 'json'
 require 'tracking_number/base'
-require 'tracking_number/usps'
-require 'tracking_number/fedex'
-require 'tracking_number/ups'
-require 'tracking_number/dhl'
-require 'tracking_number/ontrac'
+require 'tracking_number/info'
+require 'tracking_number/unknown'
+require 'checksum_validations'
+require 'active_support'
+require 'active_support/core_ext/string'
+require 'active_support/core_ext/hash'
+require "awesome_print"
 
 if defined?(ActiveModel::EachValidator)
   require 'tracking_number/active_model_validator'
 end
 
-module TrackingNumber
-  TYPES = [UPS, UPSTest, FedExExpress, FedExSmartPost, FedExGround, FedExGround18, FedExGround96, USPS91, USPS20, USPS13, USPSTest, DHLExpress, DHLExpressAir, OnTrac]
+def has_test_numbers?(tracking)
+  return tracking[:test_numbers] && tracking[:test_numbers][:valid]
+end
+
+def test_numbers_return_required_groups?(tracking, regex)
+  test_number = tracking[:test_numbers][:valid][0]
+  matches = test_number.match(regex)
+
+  return matches["SerialNumber"]
+end
+
+def read_courier_info(file)
+  return JSON.parse(File.read(file)).deep_symbolize_keys!
+end
 
+def create_class(klass, courier_info, tracking_info)
+  klass = Class.new(TrackingNumber::Base)
+  klass.const_set("COURIER_CODE", courier_info[:courier_code])
+  info = courier_info.dup
+  info.delete(:tracking_numbers)
+  klass.const_set("COURIER_INFO", info)
+
+  pattern = tracking_info[:regex]
+  pattern = tracking_info[:regex].join if tracking_info[:regex].is_a?(Array)
+
+  verify_pattern = "^#{pattern}$"
+  search_pattern = "\\b#{pattern}\\b"
+
+  klass.const_set("SEARCH_PATTERN", Regexp.new(search_pattern))
+  klass.const_set("VERIFY_PATTERN", Regexp.new(verify_pattern))
+
+  klass.const_set("VALIDATION", tracking_info[:validation])
+  klass.const_set("ADDITIONAL", tracking_info[:additional])
+
+  return klass
+end
+
+def register_class(klass, tracking_name)
+  klass_name = tracking_name.gsub(/[^0-9A-Za-z]/, '')
+  return TrackingNumber.const_set(klass_name, klass)
+end
+
+tracking_number_types = []
+
+Dir.glob(File.join(File.dirname(__FILE__), "data/couriers/*.json")).each do |file|
+  courier_info          = read_courier_info(file)
+
+  courier_info[:tracking_numbers].each do |tracking_info|
+    tracking_name = tracking_info[:name]
+    klass         = create_class(klass, courier_info, tracking_info)
+
+    # Do some basic checks on the data file
+    throw 'missing test numbers' unless has_test_numbers?(tracking_info)
+    throw 'missing regex match groups' unless test_numbers_return_required_groups?(tracking_info, Regexp.new(klass::VERIFY_PATTERN))
+
+    const = register_class(klass, tracking_name)
+    tracking_number_types.push(const)
+  end
+end
+
+TrackingNumber.const_set("TYPES", tracking_number_types)
+
+module TrackingNumber
   def self.search(body)
     TYPES.collect { |type| type.search(body) }.flatten
   end
@@ -30,6 +92,15 @@ module TrackingNumber
     return tn
   end
 
+  def self.detect_all(tracking_number)
+    matches = []
+    for test_klass in (TYPES+[Unknown])
+      tn = test_klass.new(tracking_number)
+      matches << tn if tn.valid?
+    end
+    return matches
+  end
+
   def self.new(tracking_number)
     self.detect(tracking_number)
   end