freight_kit 0.1.20 → 0.1.22

data/lib/freight_kit/platforms/next_tms/graphql_client/query/shipments.rb

@@ -0,0 +1,110 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      class GraphQLClient
+        module Query
+          class Shipments
+            DETAILS = Client.parse(<<~GRAPHQL)
+              query($filter: ShipmentFilter, $page: Int, $pageSize: Int, $sort: [String!]) {
+                shipments(filter: $filter, page: $page, pageSize: $pageSize, sort: $sort) {
+                  items {
+                    bol
+                    bookedAt
+                    brokerCarrier {
+                      account
+                      carrier {
+                        id
+                        mcNumber
+                        name
+                        scac
+                      }
+                      id
+                    }
+                    brokerCustomer {
+                      customer {
+                        id
+                        name
+                      }
+                      id
+                    }
+                    canceledAt
+                    createdAt
+                    customerReference
+                    deliveredAt
+                    deliveryAppointmentAt
+                    deliveryAppointmentOn
+                    deliveryEtaOn
+                    departedOriginTerminalAt
+                    dispatchedAt
+                    events {
+                      city
+                      countryAlpha2
+                      id
+                      name
+                      occurredAt
+                      regionIso31662
+                      typeCode
+                      zipCode
+                    }
+                    id
+                    loadId
+                    lostOn
+                    outForDeliveryAt
+                    pendingAppointmentSince
+                    pickedUpAt
+                    pickupDriverAssignedAt
+                    pickupOn
+                    pro
+                    receiverAddress {
+                      city
+                      country {
+                        alpha2Code
+                      }
+                      id
+                      region {
+                        abbreviation
+                      }
+                      street
+                      street2
+                      timeZoneName
+                      zipCode
+                    }
+                    receiverName
+                    shipperAddress {
+                      city
+                      country {
+                        alpha2Code
+                      }
+                      id
+                      region {
+                        abbreviation
+                      }
+                      street
+                      street2
+                      timeZoneName
+                      zipCode
+                    }
+                    shipperBol
+                    shipperName
+                    shipperReference
+                    status
+                    totalChargesCents
+                    totalChargesCurrency
+                    truckload
+                    updatedAt
+                  }
+                  page
+                  pageSize
+                  pages
+                  totalItems
+                  updatedAt
+                  version
+                }
+              }
+            GRAPHQL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/graphql_client.rb

@@ -0,0 +1,22 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      # Parses each `Query::*::DETAILS` document against the Next TMS schema when it loads, so a wrong field or argument
+      # fails at boot rather than at request time.
+      class GraphQLClient
+        # Sends documents to the tenant in `context[:platform]`, so one parsed document serves every tenant.
+        class HTTPAdapter
+          def execute(document:, context: {}, operation_name: nil, variables: {})
+            context.fetch(:platform).execute(document.to_query_string, operation_name:, variables:)
+          end
+        end
+
+        # Introspection of the GraphQL API, which every tenant shares
+        SCHEMA_PATH = File.expand_path('../../../../schemas/next_tms.json', __dir__).freeze
+
+        Schema = GraphQL::Client.load_schema(JSON.parse(File.read(SCHEMA_PATH)))
+        Client = GraphQL::Client.new(schema: Schema, execute: HTTPAdapter.new)
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/address.rb

@@ -0,0 +1,22 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        # Embedded in other records, so it has no query of its own and is always loaded.
+        class Address < Base
+          def city = @city ||= attribute(:city)
+          def country = @country ||= attribute(:country)&.dig(:alpha2_code)&.then { |code| ActiveUtils::Country.find(code) }
+          def loaded? = true
+          def region = @region ||= attribute(:region)&.dig(:abbreviation)
+          def street = @street ||= attribute(:street)
+          def street2 = @street2 ||= attribute(:street2)
+          def time_zone_name = @time_zone_name ||= attribute(:time_zone_name)
+
+          def to_location = Location.new(address1: street, address2: street2, city:, country:, postal_code: zip_code, province: region)
+
+          def zip_code = @zip_code ||= attribute(:zip_code)
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/base.rb

@@ -0,0 +1,120 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        # A Next TMS record, loaded lazily from the tenant's GraphQL API with the {GraphQLClient::Query} of the same name.
+        # Records from a collection are loaded. Records from an association hold only the fields that its query selects
+        # for it, and load the rest when one is read.
+        class Base
+          class << self
+            attr_accessor :orm
+
+            delegate :count,
+                     :find,
+                     :find_by,
+                     :find_by!,
+                     :first,
+                     :first!,
+                     :ids,
+                     :last,
+                     :limit,
+                     :none,
+                     :not,
+                     :offset,
+                     :order,
+                     :pluck,
+                     :where,
+                     to: :all
+
+            def all = Collection.new(self)
+            def association_type_mapping = {}
+
+            def build_association(name, data)
+              return if data&.dig(:id).blank?
+
+              class_name = association_type_mapping[name.to_sym] || name.to_s.classify
+              orm.const_get(class_name).new(data[:id], **data.except(:id))
+            end
+
+            def build_associations(name, items) = Array(items).filter_map { |data| build_association(name.to_s.singularize, data) }
+
+            # @return [Symbol] The collection query, e.g. `:broker_carriers` for {GraphQLClient::Query::BrokerCarriers}.
+            def collection_operation = graphql_name.pluralize.underscore.to_sym
+
+            # @return [Symbol] The singular query, e.g. `:broker_carrier` for {GraphQLClient::Query::BrokerCarrier}.
+            def element_operation = graphql_name.underscore.to_sym
+
+            def graphql_name = superclass == Base ? name.demodulize : superclass.graphql_name
+
+            def platform
+              raise ArgumentError, "#{name} is not bound to a tenant, use e.g. FreightKit::Carriers::JFJTransportation::ORM" if orm.nil?
+
+              orm.platform
+            end
+          end
+
+          # Instance variables that {#reload} keeps, all others memoize attributes
+          STATE = %i[@attributes @id @loaded].freeze
+
+          attr_reader :id
+
+          delegate :orm, :platform, to: :class
+
+          def initialize(id, created_at: nil, loaded: false, updated_at: nil, **attributes)
+            raise ArgumentError, 'id cannot be blank' if id.blank?
+
+            @attributes = { created_at:, updated_at: }.compact.merge(attributes)
+            # The API returns IDs without leading zeros, so `'01'` and `'1'` are the same record
+            @id = id.is_a?(String) && id.match?(/\A\d+\z/) ? id.to_i.to_s : id
+            @loaded = loaded
+          end
+
+          def ==(other) = other.instance_of?(self.class) && other.id.to_s == id.to_s
+          alias eql? ==
+
+          def attribute(key)
+            reload unless @attributes.key?(key) || loaded?
+
+            @attributes[key]
+          end
+
+          def attributes
+            reload unless loaded?
+
+            @attributes
+          end
+
+          def hash = [self.class, id.to_s].hash
+          def inspect = "#<#{self.class.name} id=#{id}>"
+          def loaded? = @loaded
+
+          # Loads every attribute, from {FreightKit.cache} when present.
+          def reload = load(cache: true)
+
+          # Loads every attribute from the API.
+          def reload! = load(cache: false)
+
+          private
+
+          def date(key) = attribute(key)&.then { |value| Date.iso8601(value) }
+          def fetch_association(name) = self.class.build_association(name, attribute(name))
+          def fetch_associations(name) = self.class.build_associations(name, attribute(name))
+
+          def load(cache:)
+            operation = self.class.element_operation
+            data = platform.query(operation, cache:, id:)[operation]
+            raise RecordNotFoundError, "Couldn't find #{self.class.name} with id #{id}" if data.nil?
+
+            (instance_variables - STATE).each { |variable| remove_instance_variable(variable) }
+            @attributes = data.except(:id)
+            @loaded = true
+
+            self
+          end
+
+          def time(key) = attribute(key)&.then { |value| Time.iso8601(value) }
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/broker_carrier.rb

@@ -0,0 +1,18 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        class BrokerCarrier < Base
+          def account = @account ||= attribute(:account)
+          def account_desc = @account_desc ||= attribute(:account_desc)
+          def broker_customer = @broker_customer ||= fetch_association(:broker_customer)
+          def carrier = @carrier ||= fetch_association(:carrier)
+          def create_invoice_on_pickup? = attribute(:create_invoice_on_pickup)
+          def days_to_pay_after_invoice_date = @days_to_pay_after_invoice_date ||= attribute(:days_to_pay_after_invoice_date)
+          def shipments = @shipments ||= orm::Shipment.where(broker_carrier: self)
+          def shipments_count = @shipments_count ||= attribute(:shipments_count)
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/broker_customer.rb

@@ -0,0 +1,22 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        class BrokerCustomer < Base
+          class << self
+            def association_type_mapping = super.merge(office_address: 'Address', primary_pickup_address: 'Address')
+          end
+
+          def accounting_customer_id = @accounting_customer_id ||= attribute(:accounting_customer_id)
+          def broker_carriers = @broker_carriers ||= orm::BrokerCarrier.where(broker_customer: self)
+          def can_quote? = attribute(:can_quote)
+          def customer = @customer ||= fetch_association(:customer)
+          def office_address = @office_address ||= fetch_association(:office_address)
+          def primary_pickup_address = @primary_pickup_address ||= fetch_association(:primary_pickup_address)
+          def shipments = @shipments ||= orm::Shipment.where(broker_customer: self)
+          def valid_freight_classes = @valid_freight_classes ||= attribute(:valid_freight_classes)
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/carrier.rb

@@ -0,0 +1,14 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        class Carrier < Base
+          def broker_carriers = @broker_carriers ||= orm::BrokerCarrier.where(carrier: self)
+          def mc_number = @mc_number ||= attribute(:mc_number)
+          def name = @name ||= attribute(:name)
+          def scac = @scac ||= attribute(:scac)
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/collection.rb

@@ -0,0 +1,335 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        # A lazy, chainable query of a collection field, e.g. `shipments(filter:, page:, pageSize:, sort:)`.
+        #
+        # Conditions become ransack predicates (`where(pro: '123')` => `proEq`), so only the filter fields the tenant
+        # generates from the model's ransackable attributes work. Without {#limit}, {#to_a} fetches every page.
+        class Collection
+          include Enumerable
+
+          # Pairs of opposite predicates, e.g. `delivered_at_gteq` is the opposite of `delivered_at_lt`
+          NEGATIONS = {
+            'cont' => 'not_cont', 'end' => 'not_end', 'eq' => 'not_eq', 'gt' => 'lteq', 'gteq' => 'lt', 'in' => 'not_in',
+            'start' => 'not_start'
+          }.freeze
+          PAGE_SIZE = 100 # the API's maximum
+          PREDICATE = /_(cont|end|eq|gt|gteq|in|lt|lteq|not_cont|not_end|not_eq|not_in|not_start|null|start)\z/
+
+          attr_reader :filter, :orm_class, :page, :page_size, :sort, :updated_at, :version
+
+          attr_writer :orm_objects
+
+          delegate :[], :each, :each_with_index, :map, to: :to_a
+
+          def initialize(orm_class, **options)
+            raise ArgumentError, 'orm_class must be descended from FreightKit::Platforms::NextTMS::ORM::Base' unless orm_class < Base
+
+            @filter = options[:filter] || {}
+            @none = options[:none] || false
+            @offset = options[:offset]
+            @orm_class = orm_class
+            @page = options[:page]
+            @page_size = options[:page_size]
+            @sort = Array(options[:sort]).compact.presence
+            @total_items = options[:total_items]
+            @updated_at = options[:updated_at]
+          end
+
+          # Arguments and blocks need the records, the bare forms only the total
+          def any?(*args, &) = args.empty? && !block_given? ? total_items.positive? : super
+          def blank? = !any?
+          def count(*args, &) = args.empty? && !block_given? ? total_items : super
+          def empty? = total_items.zero?
+
+          # The singular query cannot apply the collection's filter, so a filtered collection filters by ID too, and a
+          # limited one searches its page
+          def find(id)
+            record = if @none then nil
+                     elsif page_size.present? then to_a.find { |item| integer_id(item.id).to_s == integer_id(id).to_s }
+                     elsif filter.blank? then orm_class.new(id).reload
+                     else where(id:).limit(1).first
+                     end
+
+            record || raise(RecordNotFoundError, "Couldn't find #{orm_class} with id #{id}")
+          end
+
+          def find_by(**conditions)
+            find_by!(**conditions)
+          rescue RecordNotFoundError
+            nil
+          end
+
+          def find_by!(**conditions)
+            return find(conditions[:id]) if conditions.keys == [:id]
+
+            where(**conditions).limit(1).first || raise(RecordNotFoundError, "Couldn't find #{orm_class} with #{conditions}")
+          end
+
+          def first = page_size.present? ? orm_objects.first : limit(1).orm_objects.first
+          def first! = first || raise(RecordNotFoundError, "Couldn't find #{orm_class}")
+
+          def ids = pluck(:id)
+          def inspect = "#<#{self.class.name} orm_class=#{orm_class}>"
+
+          def last
+            return orm_objects.last if page_size.present?
+
+            offset(total_items - 1).limit(1).orm_objects.first unless empty?
+          end
+
+          def limit(page_size)
+            raise ArgumentError, 'page_size must be 1..100' unless page_size.is_a?(Integer) && page_size.between?(1, PAGE_SIZE)
+
+            new_instance(page: @offset ? offset_page(@offset, page_size) : page || 1, page_size:)
+          end
+
+          def new_instance(**options)
+            self.class.new(
+              orm_class,
+              filter: options.fetch(:filter, filter),
+              none: options.fetch(:none, @none),
+              offset: options.fetch(:offset, @offset),
+              page: options.fetch(:page, page),
+              page_size: options.fetch(:page_size, page_size),
+              sort: options.fetch(:sort, sort),
+              total_items: options[:total_items],
+              updated_at: options.fetch(:updated_at, updated_at)
+            )
+          end
+
+          def none = new_instance(none: true, total_items: 0, page: 1, page_size: 1).tap { |collection| collection.orm_objects = [] }
+          def not(**conditions) = merge(conditions.map { |key, value| build_negated_filter(key => value) })
+
+          def offset(value)
+            raise ArgumentError, 'Offset must be a non-negative integer' unless value.is_a?(Integer) && value >= 0
+
+            page_size.present? ? new_instance(offset: value, page: offset_page(value, page_size)) : new_instance(offset: value)
+          end
+
+          def order(*orders, **order_hash)
+            sort_strings = if order_hash.any?
+                             order_hash.map { |attribute, direction| "#{attribute}:#{direction || :asc}" }
+                           else
+                             orders.map { |(attribute, direction)| "#{attribute}:#{direction || :asc}" }
+                           end
+
+            new_instance(sort: sort_strings)
+          end
+
+          def orm_objects = @orm_objects ||= fetch_orm_objects
+          def pluck(attribute) = map(&attribute)
+
+          def present? = any?
+
+          def sample
+            collection = page_size.present? ? self : limit(10)
+            collection.to_a.sample
+          end
+          alias take sample
+
+          def to_a
+            @to_a ||= if @orm_objects || page_size.present?
+                        orm_objects
+                      else
+                        raise ArgumentError, 'offset needs a limit, since the API pages' if @offset
+
+                        first = new_instance(page: page || 1, page_size: PAGE_SIZE).tap(&:orm_objects)
+                        pages = ((first.page + 1)..first.total_pages).map { |page| new_instance(page:, page_size: PAGE_SIZE).orm_objects }
+                        @total_items = first.total_items
+                        @updated_at = first.updated_at
+                        @version = first.version
+
+                        [first.orm_objects, *pages].flatten
+                      end
+          end
+
+          def total_items
+            return 0 if @none
+            return @total_items if @total_items.present?
+
+            @total_items = (page_size.present? ? self : new_instance(page: 1, page_size: 1)).tap(&:orm_objects).total_items
+          end
+          alias length total_items
+          alias size total_items
+
+          def total_pages
+            return if total_items.blank? || page_size.blank?
+
+            (total_items.to_f / page_size).ceil
+          end
+
+          def where(**conditions)
+            conditions.blank? ? self : merge(conditions.map { |key, value| build_filter(key => value) })
+          end
+
+          protected
+
+          def fetch_orm_objects
+            return @orm_objects = [] if @none
+
+            operation = orm_class.collection_operation
+            variables = { filter: serialize(filter).presence, page:, page_size:, sort: }
+            data = orm_class.platform.query(operation, cache: true, **variables)[operation]
+
+            raise ResponseError, 'data[:page] is blank' if data&.dig(:page).blank?
+            raise ResponseError, 'data[:page_size] is blank' if data[:page_size].blank?
+            raise ResponseError, 'data[:total_items] is blank' if data[:total_items].blank?
+
+            @page = data[:page]
+            @page_size = data[:page_size]
+            @total_items = data[:total_items]
+            @updated_at = data[:updated_at]
+            @version = data[:version]
+
+            data[:items].map { |item| orm_class.new(item[:id], loaded: true, **item.except(:id)) }
+          end
+
+          private
+
+          # Contradictory alternatives match nothing, so they drop out
+          def alternatives(conditions)
+            conditions.filter_map { |condition| combine({}, condition.map { |key, value| build_filter(key => value) }) }
+          end
+
+          # Whether the filter knows the key only by its foreign key, e.g. `broker_carrier_id_null` but no `broker_carrier_null`
+          def association?(key)
+            arguments = GraphQLClient::Schema.types["#{orm_class.graphql_name}Filter"].arguments
+
+            arguments.exclude?("#{key.to_s.camelize(:lower)}Null") && arguments.key?("#{key.to_s.camelize(:lower)}IdNull")
+          end
+
+          def build_filter(**conditions)
+            conditions.each_with_object({}) do |(key, value), filter|
+              next filter[:or] = alternatives(value) if key == :or
+
+              value = integer_ids(value) if id_attribute?(key)
+              next filter[key] = value if key.to_s.match?(PREDICATE)
+
+              case value
+              when Array
+                next filter[:"#{key}_id_in"] = value.map { |record| integer_id(record.id) } if value.any? && value.all?(Base)
+
+                filter[:"#{key}_in"] = value
+              when Base
+                filter[:"#{key}_id_eq"] = integer_id(value.id)
+              when Collection
+                filter[:"#{key}_id_in"] = value.ids.map { |id| integer_id(id) }
+              when nil
+                filter[:"#{association?(key) ? "#{key}_id" : key}_null"] = true
+              when Range
+                filter[:"#{key}_gteq"] = value.begin unless value.begin.nil?
+                filter[:"#{key}_#{value.exclude_end? ? 'lt' : 'lteq'}"] = value.end unless value.end.nil?
+              else
+                filter[:"#{key}_eq"] = value
+              end
+            end
+          end
+
+          # Filter fields are ANDed, so only a condition that becomes one predicate can be negated
+          def build_negated_filter(**conditions)
+            conditions.each_with_object({}) do |(key, value), filter|
+              predicates = build_filter(key => value)
+              raise ArgumentError, "Can't negate #{key}: #{value.inspect}, negate each condition instead" if key == :or || predicates.many?
+
+              predicate, value = predicates.first
+              match = predicate.to_s.match(PREDICATE)
+              next filter[predicate] = !value if match[1] == 'null'
+
+              filter[:"#{match.pre_match}_#{NEGATIONS[match[1]] || NEGATIONS.key(match[1])}"] = value
+            end
+          end
+
+          # ANDs each condition's predicates with `base`, since a filter has one value per predicate, and conditions such as
+          # `id:` and `id_eq:` share one.
+          #
+          # @return [Hash, nil] Nil when the predicates contradict each other.
+          def combine(base, predicates_by_condition)
+            predicates_by_condition.flat_map(&:to_a).each_with_object(base.dup) do |(key, value), result|
+              old = result[key]
+              next result[key] = value if old.nil? || comparable(old) == comparable(value)
+              raise ArgumentError, 'A query takes one or:, combine the alternatives instead' if key == :or
+
+              match = key.to_s.match(PREDICATE)
+              case match[1]
+              when 'eq', 'null' then return nil
+              when 'gt', 'gteq' then result[key] = [old, value].max_by { |bound| comparable(bound) }
+              when 'in' then result[key] = old.select { |item| comparable(value).include?(comparable(item)) }
+              when 'lt', 'lteq' then result[key] = [old, value].min_by { |bound| comparable(bound) }
+              when 'not_eq'
+                not_in = :"#{match.pre_match}_not_in"
+                result.delete(key)
+                result[not_in] = [*result[not_in], old, value].uniq { |item| comparable(item) }
+              when 'not_in' then result[key] = (old + value).uniq { |item| comparable(item) }
+              else raise ArgumentError, "A query takes one #{key}"
+              end
+            end
+          end
+
+          # Values can be ISO 8601 strings, of dates or of times with different offsets, so they compare by date or instant
+          def comparable(value)
+            case value
+            when Array then value.map { |item| comparable(item) }
+            when Hash then value.transform_values { |item| comparable(item) }
+            when String then value.match?(/\A\d{4}-\d{2}-\d{2}\z/) ? Date.iso8601(value) : Time.iso8601(value)
+            when Symbol then value.to_s
+            else value
+            end
+          rescue ArgumentError
+            value
+          end
+
+          # `id` and `*_id`, with or without a predicate
+          def id_attribute?(key) = key.to_s.sub(PREDICATE, '').then { |attribute| attribute == 'id' || attribute.end_with?('_id') }
+
+          # GraphQL serializes IDs as strings, but ID filters take the integer column
+          def integer_id(id) = Integer(id, 10, exception: false) || id
+
+          def integer_ids(value)
+            case value
+            when Array then value.map { |id| integer_id(id) }
+            when Range then Range.new(integer_id(value.begin), integer_id(value.end), value.exclude_end?)
+            else integer_id(value)
+            end
+          end
+
+          def merge(predicates_by_condition)
+            merged = combine(filter, predicates_by_condition)&.then { |combined| satisfiable(combined) }
+
+            merged ? new_instance(filter: merged) : none
+          end
+
+          # The API pages, so the offset must start a page
+          def offset_page(offset, page_size)
+            raise ArgumentError, "offset #{offset} must be a multiple of the limit #{page_size}" unless (offset % page_size).zero?
+
+            (offset / page_size) + 1
+          end
+
+          # The API ignores empty lists, so an empty list matches nothing, and an empty exclusion excludes nothing
+          def satisfiable(conditions)
+            conditions = conditions.reject { |key, value| value == [] && key.end_with?('_not_in') }
+            return if conditions.any? { |_, value| value == [] }
+            return conditions unless conditions.key?(:or)
+
+            alternatives = conditions[:or].filter_map { |alternative| satisfiable(alternative) }
+            return if alternatives.empty?
+
+            alternatives.any?(&:empty?) ? conditions.except(:or) : conditions.merge(or: alternatives)
+          end
+
+          def serialize(value)
+            case value
+            when Array then value.map { |item| serialize(item) }
+            when Date, Time then value.iso8601
+            when Hash then value.transform_values { |item| serialize(item) }
+            when Symbol then value.to_s
+            else value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/freight_kit/platforms/next_tms/orm/customer.rb

@@ -0,0 +1,12 @@
+module FreightKit
+  module Platforms
+    class NextTMS
+      module ORM
+        class Customer < Base
+          def broker_customers = @broker_customers ||= orm::BrokerCustomer.where(customer: self)
+          def name = @name ||= attribute(:name)
+        end
+      end
+    end
+  end
+end