deliveries 0.1.0

data/lib/deliveries/couriers/ups/shipments/create.rb

@@ -0,0 +1,210 @@
+module Deliveries
+  module Couriers
+    module Ups
+      module Shipments
+        class Create
+          include JsonRequest
+          include LabelUtils
+
+          API_VERSION = 'v1807'.freeze
+          TYPES = %i[forward return].freeze
+
+          attr_accessor :shipper, :consignee, :parcels, :reference_code, :type, :collection_point, :language
+
+          def initialize(shipper:, consignee:, parcels:, reference_code:, type: :forward, collection_point: nil, language: nil)
+            raise ArgumentError, 'Invalid value for type' unless TYPES.include?(type)
+
+            self.shipper = shipper
+            self.consignee = consignee
+            self.parcels = parcels
+            self.reference_code = reference_code
+            self.collection_point = collection_point
+            self.type = type
+            self.language = language&.to_sym&.downcase || :en
+          end
+
+          def execute
+            request = {
+              ShipmentRequest: {
+                Request: {
+                  RequestOption: 'nonvalidate'
+                },
+                Shipment: {
+                  Description: Ups.config('default_product.description', default: 'International Goods'),
+
+                  Shipper: shipper_address(with_number: true),
+
+                  PaymentInformation: {
+                    ShipmentCharge: {
+                      Type: '01',
+                      BillShipper: {
+                        AccountNumber: account_number
+                      }
+                    }
+                  },
+
+                  ReferenceNumber: {
+                    Code: 'ON',
+                    Value: reference_code
+                  },
+
+                  Service: {
+                    Code: '11',
+                    Description: 'Standard'
+                  },
+
+                  Package: package_data,
+
+                  LabelSpecification: {
+                    LabelImageFormat: {
+                      Code: 'GIF'
+                    }
+                  }
+                }
+              }
+            }
+
+            if type == :return
+              request[:ShipmentRequest][:Shipment][:ReturnService] = { Code: '9' }
+              request[:ShipmentRequest][:Shipment][:ShipFrom] = consignee_address
+              request[:ShipmentRequest][:Shipment][:ShipTo] = shipper_address
+            else # forward
+              request[:ShipmentRequest][:Shipment][:ShipFrom] = shipper_address
+              request[:ShipmentRequest][:Shipment][:ShipTo] = consignee_address
+
+              if collection_point?
+                request[:ShipmentRequest][:Shipment][:ShipmentIndicationType] = {
+                  Code: '01',
+                  Description: 'DirectToRetail'
+                }
+                request[:ShipmentRequest][:Shipment][:AlternateDeliveryAddress] = collection_point_address
+                request[:ShipmentRequest][:Shipment][:ShipmentServiceOptions] = {
+                  Notification: {
+                    NotificationCode: '012',
+                    EMail: {
+                      EMailAddress: consignee.email
+                    },
+                    Locale: {
+                      Language: locale_language,
+                      Dialect: locale_dialect
+                    }
+                  }
+                }
+              end
+            end
+
+            response = call request
+
+            tracking_code = response.dig(:ShipmentResponse, :ShipmentResults, :ShipmentIdentificationNumber)
+            labels = [response.dig(:ShipmentResponse, :ShipmentResults, :PackageResults)].flatten.map do |p|
+              encoded_gif = p.dig(:ShippingLabel, :GraphicImage)
+              image2pdf Base64.decode64(encoded_gif).force_encoding('binary'), height: 4
+            end
+
+            {
+              tracking_code: tracking_code,
+              label: labels.one? ? labels.first : merge_pdfs(labels)
+            }
+          end
+
+          private
+
+          def api_endpoint
+            if Ups.live?
+              "https://onlinetools.ups.com/ship/#{API_VERSION}/shipments"
+            else
+              "https://wwwcie.ups.com/ship/#{API_VERSION}/shipments"
+            end
+          end
+
+          def collection_point?
+            !@collection_point.nil?
+          end
+
+          def account_number
+            if collection_point?
+              Ups.config(:point_account_number)
+            else
+              Ups.config(:home_account_number)
+            end
+          end
+
+          def locale_language
+            case language
+            when :es then 'SPA'
+            when :fr then 'FRA'
+            when :pt then 'POR'
+            when :it then 'ITA'
+            when :de then 'DEU'
+            when :pl then 'POL'
+            else 'ENG'
+            end
+          end
+
+          def locale_dialect
+            if language == :en
+              'GB'
+            else
+              '97'
+            end
+          end
+
+          def package_data
+            parcels.times.map do
+              {
+                Description: Ups.config('default_product.description', default: 'International Goods'),
+                Packaging: {
+                  Code: '02',
+                  Description: 'Customer Supplied'
+                },
+                PackageWeight: {
+                  UnitOfMeasurement: {
+                    Code: 'KGS'
+                  },
+                  Weight: Ups.config('default_product.weight', default: '1')
+                }
+              }
+            end
+          end
+
+          def shipper_address(with_number: false)
+            address = format_address shipper
+            address[:ShipperNumber] = account_number if with_number
+
+            address
+          end
+
+          def consignee_address
+            format_address consignee
+          end
+
+          def collection_point_address
+            address = format_address collection_point
+            address[:UPSAccessPointID] = collection_point.point_id
+            address.delete :Phone
+            address.delete :EMailAddress
+
+            address
+          end
+
+          def format_address(address)
+            {
+              Name: I18n.transliterate(address.name)[0, 35],
+              AttentionName: I18n.transliterate(address.name)[0, 35],
+              Phone: {
+                Number: address.phone
+              },
+              EMailAddress: address.email,
+              Address: {
+                AddressLine: I18n.transliterate(address.street).scan(/.{1,35}/)[0, 3],
+                City: I18n.transliterate(address.city)[0, 30],
+                PostalCode: address.postcode.to_s[0, 9],
+                CountryCode: address.country.to_s.downcase[0, 2]
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deliveries/couriers/ups/shipments/trace.rb

@@ -0,0 +1,79 @@
+module Deliveries
+  module Couriers
+    module Ups
+      module Shipments
+        class Trace
+          include JsonRequest
+
+          attr_accessor :tracking_code, :language
+
+          def initialize(tracking_code:, language: nil)
+            self.tracking_code = tracking_code
+            self.language = language
+          end
+
+          def execute
+            response = call nil, method: :get, url_params: { inquiry_number: tracking_code },
+                                 query_params: { locale: locale }
+
+            package = response.dig(:trackResponse, :shipment, 0, :package, 0, :activity)
+            raise Error, 'Cannot obtain package activity data' if package.blank?
+
+            activities = package.map do |activity|
+              {
+                status: status(activity.dig(:status, :type), activity.dig(:status, :code)),
+                location: activity.dig(:location, :address, :city),
+                tracked_at: DateTime.parse("#{activity[:date]}T#{activity[:time]}"),
+                description: activity.dig(:status, :description)
+              }
+            end
+
+            activities.sort_by { |activity| activity[:tracked_at] }
+          end
+
+          private
+
+          def api_endpoint
+            if Ups.live?
+              'https://onlinetools.ups.com/track/v1/details/%<inquiry_number>s'
+            else
+              'https://wwwcie.ups.com/track/v1/details/%<inquiry_number>s'
+            end
+          end
+
+          def locale
+            case language&.to_sym&.downcase
+            when :es then 'es_ES'
+            when :fr then 'fr_FR'
+            when :pt then 'pt_PT'
+            when :it then 'it_IT'
+            when :de then 'de_DE'
+            when :en then 'en_GB'
+            when :pl then 'pl_PL'
+            else 'en_US'
+            end
+          end
+
+          def status(type, code)
+            case type&.to_s&.upcase
+            when 'M'
+              :registered
+            when 'I', 'P', 'O'
+              :in_transit
+            when 'D'
+              if %w[2Q ZP].include?(code&.to_s&.upcase)
+                :in_collection_point
+              else
+                :delivered
+              end
+            when 'MV'
+              :canceled
+            else
+              :unknown_status
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deliveries/couriers/ups.rb

@@ -0,0 +1,122 @@
+require_relative 'ups/json_request'
+require_relative 'ups/collection_points/search'
+require_relative 'ups/shipments/create'
+require_relative 'ups/shipments/trace'
+require_relative 'ups/labels/generate'
+
+module Deliveries
+  module Couriers
+    module Ups
+      extend Courier
+
+      COURIER_ID = :ups
+
+      Config = Struct.new(
+        :license_number,
+        :username,
+        :password,
+        :point_account_number,
+        :home_account_number,
+        :default_product
+      )
+
+      module_function
+
+      def get_collection_point(global_point_id:)
+        global_point = CollectionPoint.parse_global_point_id(global_point_id: global_point_id)
+        points = CollectionPoints::Search.new(
+          country: global_point.country,
+          point_id: global_point.point_id
+        ).execute
+
+        raise Error, 'No collection point found by that point ID' if points.empty?
+
+        CollectionPoint.new(**points.first)
+      end
+
+      def get_collection_points(country:, postcode:)
+        points = CollectionPoints::Search.new(
+          country: country,
+          postcode: postcode
+        ).execute
+
+        points.map do |arguments|
+          CollectionPoint.new(**arguments)
+        end
+      end
+
+      def create_shipment(sender:, receiver:, parcels:, reference_code:, collection_point:, shipment_date: nil, language: nil, **)
+        tracking_code, label = Shipments::Create.new(
+          shipper: sender,
+          consignee: receiver,
+          parcels: parcels,
+          reference_code: reference_code,
+          type: :forward,
+          collection_point: collection_point,
+          language: language
+        ).execute.values_at(:tracking_code, :label)
+
+        Deliveries::Shipment.new(
+          courier_id: COURIER_ID,
+          sender: sender,
+          receiver: receiver,
+          parcels: parcels,
+          reference_code: reference_code,
+          tracking_code: tracking_code,
+          shipment_date: shipment_date,
+          label: Label.new(raw: label)
+        )
+      end
+
+      def create_pickup(sender:, receiver:, parcels:, reference_code:, pickup_date: nil, language: nil, **)
+        tracking_code, label = Shipments::Create.new(
+          shipper: receiver,
+          consignee: sender,
+          parcels: parcels,
+          reference_code: reference_code,
+          type: :return,
+          language: language
+        ).execute.values_at(:tracking_code, :label)
+
+        Deliveries::Pickup.new(
+          courier_id: COURIER_ID,
+          sender: sender,
+          receiver: receiver,
+          parcels: parcels,
+          reference_code: reference_code,
+          tracking_code: tracking_code,
+          pickup_date: pickup_date,
+          label: Label.new(raw: label)
+        )
+      end
+
+      def get_label(tracking_code:, **)
+        arguments = Labels::Generate.new(tracking_code: tracking_code).execute
+        Label.new(**arguments)
+      end
+
+      def get_labels(tracking_codes:, **)
+        labels = Deliveries::Labels.new
+
+        tracking_codes.each do |tracking_code|
+          labels << get_label(tracking_code: tracking_code)
+        end
+
+        labels
+      end
+
+      def shipment_info(tracking_code:, language: nil)
+        checkpoints = Shipments::Trace.new(tracking_code: tracking_code, language: language).execute.map do |arguments|
+          Checkpoint.new(**arguments)
+        end
+
+        TrackingInfo.new(courier_id: COURIER_ID, tracking_code: tracking_code, checkpoints: checkpoints,
+                         status: checkpoints.last&.status)
+      end
+
+      def pickup_info(tracking_code:, language: nil)
+        shipment_info(tracking_code: tracking_code, language: language)
+      end
+    end
+  end
+end

data/lib/deliveries/couriers.rb

@@ -0,0 +1,14 @@
+module Deliveries
+  module Couriers
+    Dir["#{File.dirname(__FILE__)}/couriers/*.rb"].each do |f|
+      # Get camelized class name
+      filename = File.basename(f, '.rb')
+
+      # Camelize the string to get the class name
+      courier_class = filename.split('_').map(&:capitalize).join.to_sym
+
+      # Register for autoloading
+      autoload courier_class, f
+    end
+  end
+end

data/lib/deliveries/delivery.rb

@@ -0,0 +1,20 @@
+module Deliveries
+  class Delivery
+    ATTRIBUTES = %i[courier_id sender receiver parcels reference_code tracking_code label].freeze
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(**attributes)
+      self.courier_id = attributes[:courier_id]
+      self.sender = attributes[:sender]
+      self.receiver = attributes[:receiver]
+      self.parcels = attributes[:parcels]
+      self.reference_code = attributes[:reference_code]
+      self.tracking_code = attributes[:tracking_code]
+      self.label = attributes[:label]
+    end
+
+    def attributes
+      ATTRIBUTES.map { |attr| { attr => send(attr) } }.inject(&:merge)
+    end
+  end
+end

data/lib/deliveries/errors.rb

@@ -0,0 +1,22 @@
+module Deliveries
+  # Generic Deliveries exception class.
+  class Error < StandardError; end
+
+  # For errors returned by the client library, like HTTP errors
+  class ClientError < Error; end
+
+  # For errors returned by the API
+  class APIError < Error
+    attr_reader :code
+
+    def initialize(message = nil, code = nil)
+      @code = code
+      super(message)
+    end
+  end
+
+  # Custom API errors.
+  class InvalidDateError < APIError; end
+
+  class InvalidTimeIntervalError < APIError; end
+end

data/lib/deliveries/label.rb

@@ -0,0 +1,20 @@
+module Deliveries
+  class Label
+    attr_reader :url
+
+    def initialize(raw: nil, url: nil)
+      raise ArgumentError, 'Both raw and url cannot be nil' if raw.nil? && url.nil?
+
+      @raw = raw
+      @url = url
+    end
+
+    def raw
+      if @raw
+        @raw
+      elsif @url
+        @raw = URI.parse(@url).read.force_encoding('binary')
+      end
+    end
+  end
+end

data/lib/deliveries/label_utils.rb

@@ -0,0 +1,67 @@
+require 'mini_magick'
+require 'hexapdf'
+
+module Deliveries
+  module LabelUtils
+    module_function
+
+    def image2pdf(bindata, width: nil, height: nil)
+      Tempfile.create do |f|
+        f.binmode
+
+        f << bindata
+
+        image = MiniMagick::Image.open(f.path)
+        image.format 'png' unless image.data['format']&.casecmp?('png')
+
+        doc = HexaPDF::Document.new
+        doc_image = doc.images.add(image.path)
+        iw = doc_image.info.width.to_f
+        ih = doc_image.info.height.to_f
+        media_box =
+          if width.nil? && height.nil?
+            [0, 0, iw, ih]
+          elsif width.nil?
+            width = (height * iw) / ih
+            [0, 0, width * 72, height * 72]
+          elsif height.nil?
+            height = (width * ih) / iw
+            [0, 0, width * 72, height * 72]
+          else
+            [0, 0, iw, ih]
+          end
+
+        if (ih > iw) != (media_box[3] > media_box[2]) && (iw > media_box[2] || ih > media_box[3])
+          media_box[2], media_box[3] = media_box[3], media_box[2]
+        end
+
+        page = doc.pages.add(media_box)
+        pw = page.box(:media).width.to_f
+        ph = page.box(:media).height.to_f
+        ratio = [pw / iw, ph / ih].min
+        iw *= ratio
+        ih *= ratio
+        x = (pw - iw) / 2
+        y = (ph - ih) / 2
+        page.canvas.image(doc_image, at: [x, y], width: iw, height: ih)
+
+        output = StringIO.new
+        doc.write(output)
+        output.string.force_encoding('binary')
+      end
+    end
+
+    def merge_pdfs(*pdfs)
+      doc = HexaPDF::Document.new
+      pdfs.flatten.each do |pdf|
+        HexaPDF::Document.new(io: StringIO.new(pdf)).pages.each do |page|
+          doc.pages << doc.import(page)
+        end
+      end
+
+      output = StringIO.new
+      doc.write(output)
+      output.string.force_encoding('binary')
+    end
+  end
+end

data/lib/deliveries/labels.rb

@@ -0,0 +1,40 @@
+module Deliveries
+  class Labels
+    include LabelUtils
+
+    attr_reader :url
+
+    def initialize(raw: nil, url: nil)
+      @raw = raw
+      @url = url
+      @labels = []
+    end
+
+    def raw
+      if @raw
+        @raw
+      elsif @url
+        @raw = URI.parse(@url).read.force_encoding('binary')
+      elsif !@labels.empty?
+        merge_pdfs @labels.map(&:raw)
+      end
+    end
+
+    def <<(label)
+      raise 'Cannot add labels when raw or url are already set' unless @raw.nil? && @url.nil?
+
+      case label
+      when Label
+        @labels << label
+      when %r{\Ahttps?://}
+        @labels << Label.new(url: label)
+      when String
+        @labels << Label.new(raw: label)
+      else
+        raise "Cannot cast #{label.class.name} to Label"
+      end
+
+      self
+    end
+  end
+end

data/lib/deliveries/pickup.rb

@@ -0,0 +1,15 @@
+module Deliveries
+  class Pickup < Delivery
+    attr_accessor :pickup_date
+
+    def initialize(delivery: nil, **attributes)
+      if delivery.is_a? Deliveries::Delivery
+        super(**delivery.attributes)
+      else
+        super(**attributes)
+      end
+
+      self.pickup_date = attributes[:pickup_date]
+    end
+  end
+end

data/lib/deliveries/shipment.rb

@@ -0,0 +1,15 @@
+module Deliveries
+  class Shipment < Delivery
+    attr_accessor :shipment_date
+
+    def initialize(delivery: nil, **attributes)
+      if delivery.is_a? Deliveries::Delivery
+        super(**delivery.attributes)
+      else
+        super(**attributes)
+      end
+
+      self.shipment_date = attributes[:shipment_date]
+    end
+  end
+end

data/lib/deliveries/tracking_info.rb

@@ -0,0 +1,29 @@
+module Deliveries
+  class TrackingInfo
+    attr_accessor :courier_id, :tracking_code, :status, :checkpoints, :url
+
+    def initialize(courier_id:, tracking_code:, status: nil, checkpoints: nil, url: nil)
+      self.courier_id = courier_id
+      self.tracking_code = tracking_code
+      self.status = status
+      self.checkpoints = checkpoints
+      self.url = url
+    end
+
+    def registered?
+      status == :registered
+    end
+
+    def in_transit?
+      status == :in_transit
+    end
+
+    def in_collection_point?
+      status == :in_collection_point
+    end
+
+    def delivered?
+      status == :delivered
+    end
+  end
+end

data/lib/deliveries/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Deliveries
+  VERSION = '0.1.0'
+end