cargowise-ts 1.0.0.alpha

data/lib/cargowise/client.rb

@@ -0,0 +1,113 @@
+# coding: utf-8
+
+require 'savon'
+require 'cargowise/order_search'
+require 'cargowise/shipment_search'
+
+module Cargowise
+
+  # The starting point for accessing data from your logistics provider. See
+  # the README for usage tips.
+  #
+  # You should create a new Client instance for each company API you plan
+  # to query.
+  #
+  class Client
+
+    def initialize(opts = {})
+      @order_uri = opts[:order_uri]
+      @shipment_uri = opts[:shipment_uri]
+      @code = opts[:company_code]
+      @username = opts[:username]
+      @password = opts[:password]
+    end
+
+    # begin an order search. See the docs for Cargowise::OrderSearch for info
+    # on what you can do with the object returned from this method.
+    def orders
+      OrderSearch.new(orders_client)
+    end
+
+    # begin a shipment search. See the docs for Cargowise::ShipmentSearch for
+    # info on what you can do with the object returned from this method.
+    def shipments
+      ShipmentSearch.new(shipments_client)
+    end
+
+    def orders_hello
+      response = orders_client.call(:hello)
+      response.xpath("//tns:HelloResponse/tns:HelloResult/text()", {"tns" => Cargowise::DEFAULT_NS}).to_s
+    end
+
+    def shipments_hello
+      response = shipments_client.call(:hello)
+      response.xpath("//tns:HelloResponse/tns:HelloResult/text()", {"tns" => Cargowise::DEFAULT_NS}).to_s
+    end
+
+    # Find the base URI for the web interface at this client
+    #
+    def base_uri
+      uri = @shipment_uri || @order_uri || ""
+      uri.to_s[/(.+)\/WebService.+/,1]
+    end
+
+    private
+
+    def orders_client
+      build_client(order_wsdl_path, @order_uri)
+    end
+
+    def order_wsdl_path
+      File.join(
+        File.dirname(__FILE__),
+        "order_wsdl.xml"
+      )
+    end
+
+    def shipments_client
+      build_client(shipment_wsdl_path, @shipment_uri)
+    end
+
+    def shipment_wsdl_path
+      File.join(
+        File.dirname(__FILE__),
+        "shipment_wsdl.xml"
+      )
+    end
+
+    # TODO: make some of these configurable via the initialize to Cargowise::Client. Will enable
+    #       providers that need special treatment to work (like OHL) to be configured differently
+    #       by the calling code
+    def build_client(wsdl_path, endpoint_uri)
+      Savon.client(
+        wsdl: wsdl_path,
+        endpoint: endpoint_uri,
+
+        # Cargowise servers can be super slow to respond, this gives them time
+        # to have a smoko before responding to our queries.
+        read_timeout: 240,
+
+        # OHL uses cargowise and has a load balancer that freaks out if we use
+        # the OpenSSL 1.0.1 default of TLS1.1.
+        ssl_version: :TLSv1,
+
+        # savon 2.2.0 ignores the above ssl_version unless this is set to
+        # false. Annoying.
+        ssl_verify_mode: :none,
+
+        # turn off logging to keep me sane. Change this to true when developing
+        log: false,
+
+        # the cargowsie API requires auth details in the SOAP header of every
+        # request
+        soap_header: {
+          "tns:WebTrackerSOAPHeader" => {
+            "tns:CompanyCode" => @code,
+            "tns:UserName" => @username,
+            "tns:Password" => @password
+          }
+        }
+      )
+    end
+  end
+end

data/lib/cargowise/consol.rb

@@ -0,0 +1,29 @@
+# coding: utf-8
+
+require 'cargowise/abstract_result'
+
+module Cargowise
+
+  # Extra shipping detail associated with a Shipment. Not built
+  # directly, but available via the consols() attribute
+  # of the Shipment model.
+  #
+  class Consol < AbstractResult
+
+    attr_reader :master_bill, :console_mode, :transport_mode
+    attr_reader :vessel_name, :voyage_flight
+    attr_reader :load_port, :discharge_port
+
+    def initialize(node)
+      @node = node
+
+      @master_bill    = text_value("./MasterBill")
+      @console_mode   = text_value("./ConsolMode")
+      @transport_mode = text_value("./TransportMode")
+      @vessel_name    = text_value("./VesselName")
+      @voyage_flight  = text_value("./VoyageFlight")
+      @load_port      = text_value("./LoadPort")
+      @discharge_port = text_value("./DischargePort")
+    end
+  end
+end

data/lib/cargowise/document.rb

@@ -0,0 +1,23 @@
+# coding: utf-8
+
+require 'cargowise/abstract_result'
+
+module Cargowise
+
+  # A document that is associated with a Shipment. Not built
+  # directly, but available via the documents() attribute
+  # of the Shipment model.
+  #
+  class Document < AbstractResult
+
+    attr_reader :date, :description, :link
+
+    def initialize(node)
+      @node = node
+
+      @date        = time_value("./Date")
+      @description = text_value("./Description")
+      @link        = text_value("./Link")
+    end
+  end
+end

data/lib/cargowise/invoice.rb

@@ -0,0 +1,30 @@
+# coding: utf-8
+
+require 'cargowise/abstract_result'
+
+module Cargowise
+
+  # An invoice that is associated with a Shipment. Not built
+  # directly, but available via the invoices() attribute
+  # of the Shipment model.
+  #
+  class Invoice < AbstractResult
+
+    attr_reader :number, :issuer, :type, :date, :due_date
+    attr_reader :currency, :total, :outstanding
+    attr_reader :link
+
+    def initialize(node)
+      @node = node
+
+      @number      = text_value("./InvoiceNumber")
+      @issuer      = text_value("./IssuerName")
+      @date        = time_value("./InvoiceDate")
+      @due_date    = time_value("./DueDate")
+      @currency    = text_value("./Currency")
+      @total       = decimal_value("./TotalAmount")
+      @outstanding = decimal_value("./OutstandingAmount")
+      @link        = text_value("./Link")
+    end
+  end
+end

data/lib/cargowise/order.rb

@@ -0,0 +1,64 @@
+# coding: utf-8
+
+require 'cargowise/abstract_result'
+require 'cargowise/shipment'
+
+module Cargowise
+
+  # A purchase order that is being shipped to from a supplier to
+  # you via a logistics company.
+  #
+  # Typcially you will setup an arrangement with your account manager
+  # where they are sent copies of POs so they can be entered into the
+  # database and tracked.
+  #
+  # All order objects are read-only, see the object attributes to see
+  # what information is available.
+  #
+  # Use class find methods to retrieve order info from your logistics
+  # company.
+  #
+  #     Order.find_by_order_number(...)
+  #     Order.find_incomplete(...)
+  #     etc
+  #
+  class Order < AbstractResult
+
+    attr_reader :order_number, :order_status, :description, :datetime
+    attr_reader :order_total, :transport_mode, :container_mode
+    attr_reader :invoice_number
+
+    attr_reader :buyer_name
+
+    attr_reader :supplier_name
+
+    attr_reader :shipments
+
+    def initialize(node)
+      @node = node
+
+      @order_number = text_value("./OrderIdentifier/OrderNumber")
+      @invoice_number = text_value("./OrderDetail/InvoiceNumber")
+      @order_status = text_value("./OrderDetail/OrderStatus")
+      @description  = text_value("./OrderDetail/Description")
+      @datetime     = time_value("./OrderDetail/OrderDateTime")
+      @order_total  = decimal_value("./OrderDetail/OrderTotal")
+      @transport_mode = text_value("./OrderDetail/TransportMode")
+      @container_mode = text_value("./OrderDetail/ContainerMode")
+
+      @buyer_name   = text_value("./OrderDetail/Buyer/OrganisationDetails/Name")
+
+      @supplier_name = text_value("./OrderDetail/Supplier/OrganisationDetails/Name")
+
+      @shipments = node_array("./Shipment").map { |node|
+        Shipment.new(node)
+      }
+    end
+
+    def to_xml
+      @node.to_xml
+    end
+
+  end
+
+end

data/lib/cargowise/order_search.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+require 'cargowise/order'
+
+module Cargowise
+
+  class OrderSearch
+
+    def initialize(savon_client)
+      @savon_client = savon_client
+    end
+
+    # find all orders with an OrderNumber that matches ref
+    #
+    def by_order_number(ref)
+      filter_hash = {
+        "tns:Filter" => {
+          "tns:Number" => {
+            "tns:NumberSearchField" => "OrderNumber",
+            "tns:NumberValue" => ref
+          }
+        }
+      }
+      get_order_list(filter_hash)
+    end
+
+    # find all orders with a ShipmentNumber that matches ref
+    #
+    def by_shipment_number(ref)
+      filter_hash = {
+        "tns:Filter" => {
+          "tns:Number" => {
+            "tns:NumberSearchField" => "ShipmentNumber",
+            "tns:NumberValue" => ref
+          }
+        }
+      }
+      get_order_list(filter_hash)
+    end
+
+    # find all orders still marked as incomplete.
+    #
+    def incomplete
+      filter_hash = {
+        "tns:Filter" => { "tns:OrderStatus" => "INC" }
+        }
+      get_order_list(filter_hash)
+    end
+
+    private
+
+    # return an array of orders. Each order *should* correspond to a buyer PO.
+    #
+    # filter_hash should be a hash that will be serialised into an
+    # XML fragment specifying the search criteria. See the WSDL documentation
+    # for samples
+    #
+    def get_order_list(filter_hash)
+      response = @savon_client.call(:get_order_list, message: filter_hash)
+      response.xpath("//tns:GetOrderListResult/tns:WebOrder", {"tns" => Cargowise::DEFAULT_NS}).map do |node|
+        Cargowise::Order.new(node)
+      end
+    end
+
+  end
+end
+