tracking_number 0.10.5 → 3.0.0

data/lib/tracking_number.rb

@@ -1,36 +1,88 @@
 # Identify if tracking numbers are valid, and which service they belong to
 
-# Information on validating tracking numbers found here:
-# http://answers.google.com/answers/threadview/id/207899.html
-
+require 'json'
+require 'tracking_number/checksum_validations'
+require 'tracking_number/loader'
 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/partnership'
+require 'tracking_number/unknown'
+require 'active_support/all'
 
 if defined?(ActiveModel::EachValidator)
   require 'tracking_number/active_model_validator'
 end
 
+TrackingNumber::Loader.load_tracking_number_data
+
 module TrackingNumber
-  TYPES = [UPS, UPSTest, FedExExpress, FedExSmartPost, FedExGround, FedExGround18, FedExGround96, USPS91, USPS20, USPS13, USPSTest, DHLExpress, DHLExpressAir, OnTrac]
+  def self.search(body, match: :carrier)
+    matches = TYPES.collect { |type| type.search(body) }.flatten
+
+    # Some tracking numbers (e.g. Fedex Smartpost) are partnerships between two parties, where one party is the shipper (e.g. Fedex)
+    # and the other party is the [last mile] carrier (e.g. USPS). We're probably interested in the last mile aspect of
+    # the partnership, so by default we'll show those
 
-  def self.search(body)
-    TYPES.collect { |type| type.search(body) }.flatten
+    # Tracking numbers without a partnership are both the shipper and carrier.
+
+    case match
+    when :carrier
+      matches.filter(&:carrier?)
+    when :shipper
+      matches.filter(&:shipper?)
+    when :all
+      matches
+    else
+      matches
+    end
+  end
+
+  def self.detect(tracking_number, match: :carrier)
+    all_matches = search(tracking_number, match: match)
+
+    if all_matches.empty?
+      Unknown.new(tracking_number)
+    else
+      all_matches.max_by(&:confidence)
+    end
   end
 
-  def self.detect(tracking_number)
-    tn = nil
-    for test_klass in (TYPES+[Unknown])
+  def self.detect_all(tracking_number)
+    matches = []
+    (TYPES + [Unknown]).each do |test_klass|
       tn = test_klass.new(tracking_number)
-      break if tn.valid?
+      matches << tn if tn.valid?
     end
-    return tn
+
+    matches
   end
 
   def self.new(tracking_number)
-    self.detect(tracking_number)
+    detect(tracking_number)
+  end
+
+  # Renamed in tracking_number_data 2.0. The old constant still describes the same barcode.
+  RENAMED_TYPES = { USPS91: :USPSIMpbC, USPS22: :USPSIMpbN, USPS34v2: :USPSIMpbC }.freeze
+
+  # Removed in tracking_number_data 2.0. An alias would answer is_a? for every IMpb number,
+  # which is the claim the data stopped making, so these raise instead.
+  WITHDRAWN_TYPES = {
+    FedExSmartPost: 'USPSIMpbC',
+    DHLECommerce30: 'USPSIMpbC'
+  }.freeze
+
+  def self.const_missing(name)
+    if (renamed = RENAMED_TYPES[name])
+      warn "TrackingNumber::#{name} is now TrackingNumber::#{renamed}"
+      return const_get(renamed)
+    end
+
+    if (replacement = WITHDRAWN_TYPES[name])
+      raise NameError, "TrackingNumber::#{name} no longer exists. These are USPS IMpb barcodes " \
+                       "carrying nothing that identifies the shipper, so they now decode as " \
+                       "TrackingNumber::#{replacement}."
+    end
+
+    super
   end
 end

data/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "tracking_number",
+  "version": "1.x.x-semantic-release",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jkeen/tracking_number.git"
+  },
+  "author": "jkeen",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jkeen/tracking_number/issues"
+  },
+  "homepage": "https://github.com/jkeen/tracking_number#readme",
+  "scripts": {
+    "semantic-release": "semantic-release"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "semantic-release": "^19.0.3",
+    "semantic-release-rubygem": "^1.2.0"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "releaseRules": [
+            {
+              "type": "*!",
+              "release": "major"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            }
+          ],
+          "parserOpts": {
+            "noteKeywords": [
+              "BREAKING CHANGE",
+              "BREAKING CHANGES",
+              "BREAKING"
+            ]
+          }
+        }
+      ],
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/changelog",
+        {
+          "changelogTitle": "tracking_number changelog",
+          "changelogFile": "CHANGELOG.md"
+        }
+      ],
+      "semantic-release-rubygem",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md"
+          ],
+          "message": "${nextRelease.version} CHANGELOG [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ],
+    "debug": false,
+    "dryRun": false
+  }
+}

data/test/partnership_test.rb

@@ -0,0 +1,71 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+# No shipped definition declares partners currently at the tracking number data 2.0 release, 
+# but the concept is still supported in the data spec, and should be tested, so we're faking it here
+
+class PartnershipTest < Minitest::Test
+  NUMBER = 'ZZ1234567890'.freeze
+
+  def setup
+    @shipper = build_class('test_shipper', partner_id: 'test_carrier', partner_type: 'carrier')
+    @carrier = build_class('test_carrier', partner_id: 'test_shipper', partner_type: 'shipper')
+
+    TrackingNumber::TYPES.push(@shipper, @carrier)
+  end
+
+  def teardown
+    TrackingNumber::TYPES.delete(@shipper)
+    TrackingNumber::TYPES.delete(@carrier)
+  end
+
+  should "report a partnership from both sides" do
+    assert @shipper.new(NUMBER).partnership?
+    assert @carrier.new(NUMBER).partnership?
+  end
+
+  should "pair each side with the other" do
+    partners = @carrier.new(NUMBER).partners
+
+    assert_instance_of @shipper, partners.shipper
+    assert_instance_of @carrier, partners.carrier
+  end
+
+  should "report which side of the partnership each is" do
+    assert @shipper.new(NUMBER).shipper?
+    assert !@shipper.new(NUMBER).carrier?
+
+    assert @carrier.new(NUMBER).carrier?
+    assert !@carrier.new(NUMBER).shipper?
+  end
+
+  should "only match the carrier side when searching by default" do
+    matches = TrackingNumber.search("shipped as #{NUMBER} today")
+
+    assert_equal [@carrier], matches.collect(&:class)
+  end
+
+  should "match both sides when searching for all" do
+    matches = TrackingNumber.search("shipped as #{NUMBER} today", match: :all)
+
+    assert_equal [@shipper, @carrier], matches.collect(&:class)
+  end
+
+  private
+
+  def build_class(id, partner_id:, partner_type:)
+    pattern = 'Z\s*Z\s*(?<SerialNumber>([0-9]\s*){10})'
+
+    klass = Class.new(TrackingNumber::Base)
+    klass.const_set('ID', id)
+    klass.const_set('COURIER_CODE', id.to_sym)
+    klass.const_set('COURIER_INFO', name: id, courier_code: id.to_sym)
+    klass.const_set('SEARCH_PATTERN', Regexp.new("\\b#{pattern}\\b"))
+    klass.const_set('VERIFY_PATTERN', Regexp.new("^#{pattern}$"))
+    klass.const_set('VALIDATION', {})
+    klass.const_set('ADDITIONAL', nil)
+    klass.const_set('TRACKING_URL', nil)
+    klass.const_set('PARTNERS', [{ partner_id: partner_id, partner_type: partner_type }])
+
+    klass
+  end
+end

data/test/renamed_types_test.rb

@@ -0,0 +1,44 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class RenamedTypesTest < Minitest::Test
+  NUMBER = '420112139261290983497923666238'.freeze
+
+  should "resolve a renamed constant to the definition that replaced it" do
+    assert_equal TrackingNumber::USPSIMpbC, silenced { TrackingNumber::USPS91 }
+    assert_equal TrackingNumber::USPSIMpbN, silenced { TrackingNumber::USPS22 }
+    assert_equal TrackingNumber::USPSIMpbC, silenced { TrackingNumber::USPS34v2 }
+  end
+
+  should "keep is_a? answering for a renamed constant" do
+    assert TrackingNumber.new(NUMBER).is_a?(silenced { TrackingNumber::USPS91 })
+  end
+
+  should "warn once a renamed constant is reached for" do
+    _, err = capture_io { TrackingNumber::USPS91 }
+
+    assert_match(/USPS91 is now TrackingNumber::USPSIMpbC/, err)
+  end
+
+  # An alias would answer is_a? for every IMpb number, including labels these carriers never touched
+  should "refuse a withdrawn constant and name its replacement" do
+    error = assert_raises(NameError) { TrackingNumber::FedExSmartPost }
+    assert_match(/no longer exists/, error.message)
+    assert_match(/USPSIMpbC/, error.message)
+
+    assert_raises(NameError) { TrackingNumber::DHLECommerce30 }
+  end
+
+  should "leave an unrelated missing constant alone" do
+    error = assert_raises(NameError) { TrackingNumber::NotADefinition }
+
+    assert_match(/uninitialized constant/, error.message)
+  end
+
+  private
+
+  def silenced
+    resolved = nil
+    capture_io { resolved = yield }
+    resolved
+  end
+end

data/test/test_helper.rb

@@ -2,6 +2,7 @@ require 'simplecov'
 SimpleCov.start
 require 'rubygems'
 require 'minitest/autorun'
+require 'minitest/reporters'
 require 'shoulda'
 require 'active_model'
 
@@ -9,14 +10,14 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'tracking_number'
 
+Minitest::Reporters.use! [Minitest::Reporters::DefaultReporter.new(:color => true)]
+
 class Minitest::Test
   def possible_numbers(tracking)
     tracking = tracking.to_s
     possible_numbers = []
     possible_numbers << tracking
     possible_numbers << tracking.to_s.gsub(" ", "")
-    possible_numbers << tracking.chars.to_a.join(" ")
-    possible_numbers << tracking.chars.to_a.join("  ")
     possible_numbers << tracking.slice(0, (tracking.length / 2)) + "  " + tracking.slice((tracking.length / 2), tracking.length)
 
     possible_numbers.flatten.uniq
@@ -33,7 +34,7 @@ class Minitest::Test
   def should_detect_number_variants(valid_number, type)
     possible_strings(valid_number).each do |string|
       results = type.search(string)
-      assert_equal 1, results.size, "could not find #{type} #{valid_number} in #{string}"
+      assert_equal 1, results.size, "could not find #{type} #{valid_number} in #{string} using search regex: #{type::SEARCH_PATTERN}"
     end
   end
 
@@ -44,10 +45,16 @@ class Minitest::Test
     assert t.valid?
   end
 
-  def should_fail_on_check_digit_changes(valid_number)
-    digits = valid_number.chars.to_a
-    last = digits.pop.to_i
-    digits << (last  < 2 ? last + 3 : last - 3).to_s
+  def should_be_invalid_number(invalid_number, type, carrier)
+    t = TrackingNumber.new(invalid_number)
+    assert !t.valid?
+  end
+
+  def should_fail_on_check_digit_changes(valid_number, klass)
+    digits = valid_number.gsub(/\s/, "").chars.compact.to_a
+    position = digits.join.match(klass::VERIFY_PATTERN).begin("CheckDigit")
+    current = digits[position].to_i
+    digits[position] = (current <= 2 ? current + 3 : current - 3).to_s
     invalid_number = digits.join
     t = TrackingNumber.new(invalid_number)
     assert !t.valid?, "#{invalid_number} reported as a valid #{t.class}, and it shouldn't be"

data/test/tracking_number_meta_test.rb

@@ -0,0 +1,145 @@
+require 'test_helper'
+
+def load_courier_data(name = :all)
+  if name == :all
+    Dir.glob(File.join(File.dirname(__FILE__), "../lib/data/couriers/*.json")).collect do |file|
+      JSON.parse(File.read(file)).deep_symbolize_keys!
+    end
+  else
+    return JSON.parse(File.join(File.dirname(__FILE__), "../lib/data/couriers/#{name}.json"))
+  end
+end
+
+class TrackingNumberMetaTest < Minitest::Test
+  load_courier_data(:all).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|
+      klass_name = tracking_info[:name].gsub(/[^0-9A-Za-z]/, '')
+      klass = "TrackingNumber::#{klass_name}".constantize
+
+      describe "[#{tracking_info[:name]}]" do
+        tracking_info[:test_numbers][:valid].each do |valid_number|
+          should "detect #{valid_number} as #{klass_name}" do
+            #TODO fix this multiple matching thing
+            matches = TrackingNumber.search(valid_number, match: :all)
+            assert matches.collect(&:class).include?(klass)
+          end
+
+          if tracking_info[:validation][:checksum]
+            # only run this test if number format has checksum
+            should "fail on check digit changes with #{valid_number}" do
+              should_fail_on_check_digit_changes(valid_number, klass)
+            end
+          end
+
+          should "detect #{valid_number} regardless of spacing" do
+            should_detect_number_variants(valid_number, "TrackingNumber::#{klass_name}".constantize)
+          end
+
+          context "number test" do
+            tracking_number = klass.new(valid_number)
+
+            should "validate #{valid_number} with #{klass_name}" do
+              assert_equal courier_code, tracking_number.carrier
+              assert tracking_number.valid?, "should be valid"
+            end
+
+            should "return correct courier code on #{valid_number} when calling #courier_code" do
+              tracking_number = klass.new(valid_number)
+              assert_equal courier_info[:courier_code].to_sym, tracking_number.courier_code
+              assert_equal courier_info[:courier_code].to_sym,tracking_number.courier_code
+            end
+
+            should "return correct courier name on #{valid_number} when calling #courier_name" do
+              if (tracking_number.matching_additional["Courier"])
+                assert_equal tracking_number.matching_additional["Courier"][:courier], tracking_number.courier_name
+              else
+                assert_equal courier_name, tracking_number.courier_name
+              end
+            end
+
+            should "not throw an error when calling #service_type on #{valid_number}" do
+              service_type = tracking_number.service_type
+              assert service_type.is_a?(String) || service_type.nil?
+            end
+
+            should "not throw an error when calling #destination on #{valid_number}" do
+              assert tracking_number.destination_zip.is_a?(String) || tracking_number.destination_zip.nil?
+            end
+
+            should "not throw an error when calling #shipper on #{valid_number}" do
+              t = klass.new(valid_number)
+              assert tracking_number.shipper_id.is_a?(String) || tracking_number.shipper_id.nil?
+            end
+
+            should "not throw an error when calling #package_type on #{valid_number}" do
+              t = klass.new(valid_number)
+              assert tracking_number.package_type.is_a?(String) || tracking_number.package_type.nil?
+            end
+
+            should "not throw an error when calling #decode on #{valid_number}" do
+              t = klass.new(valid_number)
+              decode = tracking_number.decode
+              assert decode.is_a?(Hash)
+            end
+
+          end
+        end
+
+        tracking_info[:test_numbers][:invalid].each do |invalid_number|
+          should "not validate #{invalid_number} with #{klass_name}" do
+            t = klass.new(invalid_number)
+            assert !t.valid?, "should not be valid"
+          end
+
+          should "not throw an error when calling #service_type on invalid number #{invalid_number}" do
+            t = klass.new(invalid_number)
+            service_type = t.service_type
+            assert service_type.is_a?(String) || service_type.nil?
+          end
+
+          should "not throw an error when calling #destination_zip on invalid number #{invalid_number}" do
+            t = klass.new(invalid_number)
+            destination = t.destination_zip
+            assert  destination.is_a?(String) || destination.nil?
+          end
+
+          should "not throw an error when calling #shipper_id on invalid number #{invalid_number}" do
+            t = klass.new(invalid_number)
+            shipper = t.shipper_id
+            assert shipper.is_a?(String) || shipper.nil?
+          end
+
+          should "not throw an error when calling #package_type on invalid number #{invalid_number}" do
+            t = klass.new(invalid_number)
+            assert t.package_type.is_a?(String) || t.package_type.nil?
+          end
+
+          should "not throw an error when calling #decode on invalid number #{invalid_number}" do
+            t = klass.new(invalid_number)
+            decode = t.decode
+            assert decode.is_a?(Hash)
+          end
+        end
+      end
+    end
+  end
+
+  test_numbers = []
+  load_courier_data(:all).each do |courier_info|
+    courier_info[:tracking_numbers].each do |tracking_info|
+      test_numbers << tracking_info[:test_numbers][:valid]
+    end
+  end
+
+  test_numbers.flatten!
+
+  test_numbers.each do |number|
+    matches = TrackingNumber.detect_all(number)
+    if (matches.size > 1)
+      puts "WARNING: #{number.gsub(/\s/, '')} matched multiple types => #{matches.collect { |m| m.class.to_s.split("::").last}}"
+    end
+  end
+end