atlas_engine 0.1.0

data/app/models/atlas_engine/address_validation/field.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Field
+      extend T::Sig
+
+      Name = T.type_alias { T.any(String, Symbol) }
+      Value = T.type_alias { T.nilable(String) }
+
+      sig { returns(Name) }
+      attr_reader :name
+
+      sig { returns(Value) }
+      attr_reader :value
+
+      sig { params(name: Name, value: Value).void }
+      def initialize(name:, value:)
+        @name = name
+        @value = value
+      end
+
+      sig { returns(T::Hash[Symbol, T.any(Name, Value)]) }
+      def attributes
+        { name: name, value: value }
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/full_address_validator_base.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class FullAddressValidatorBase
+      extend T::Sig
+      extend T::Helpers
+      abstract!
+
+      sig { returns(Result) }
+      attr_reader :result
+
+      sig { returns(AbstractAddress) }
+      attr_reader :address
+
+      sig { params(address: AbstractAddress, result: Result).void }
+      def initialize(address:, result:)
+        @address = address
+        @result = result
+      end
+
+      sig { abstract.returns(Result) }
+      def validate; end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/log_emitter.rb

@@ -0,0 +1,66 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class LogEmitter
+      extend T::Sig
+      include LogHelper
+
+      sig { returns(AbstractAddress) }
+      attr_reader :address
+
+      sig { returns(AddressValidation::Result) }
+      attr_reader :result
+
+      sig { returns(T::Array[Symbol]) }
+      attr_reader :fields
+
+      sig do
+        params(
+          address: AbstractAddress,
+          result: AddressValidation::Result,
+        ).void
+      end
+      def initialize(address:, result:)
+        @address = address
+        @result = result
+        @fields = [:country, :province, :zip, :city, :street, :phone]
+      end
+
+      sig { void }
+      def run
+        formatted_address = I18n.with_locale(:en) do
+          Worldwide.address(**address.to_h).single_line
+        end
+        data = {
+          country_code: address.country_code,
+          formatted_address: formatted_address,
+          concerns: concern_codes,
+          suggestions: result.suggestions.map(&:attributes),
+          candidate: result.candidate,
+          validation_id: result.id,
+        }
+
+        if concern_codes.any?
+          log_info("[AddressValidation] Concern(s) found when validating address", data)
+        else
+          log_info("[AddressValidation] Address validated, no concerns returned", data)
+        end
+      end
+
+      sig { returns(T::Array[Symbol]) }
+      def concern_codes
+        fields.flat_map do |field|
+          if field.equal?(:street)
+            result.concerns.select do |c|
+              c.attributes[:code] =~ /^(missing_building_number|address1|address2|street).*/
+            end
+          else
+            result.concerns.select { |c| c.attributes[:code] =~ /^#{field}.*/ }
+          end
+        end.map(&:code)
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/matching_strategies.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class MatchingStrategies < T::Enum
+      include Strategies
+
+      enums do
+        Es = new("es")
+        EsStreet = new("es_street")
+        Local = new("local")
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/normalizer.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Normalizer
+      extend T::Sig
+
+      sig do
+        params(
+          string: String,
+        ).returns(String)
+      end
+      def normalize(string)
+        string
+          .gsub("Æ", "AE")
+          .gsub("Œ", "OE")
+          .gsub("æ", "ae")
+          .gsub("œ", "oe")
+          .gsub("  ", " ")
+          # normalizes Arabic characters
+          .tr("آ", "ا")
+          .tr("أ", "ا")
+          .tr("إ", "ا")
+          .tr("ئ", "ي")
+          .tr("ة", "ه")
+          .tr("ى", "ي")
+          # removes Arabic stretching characters and diacritics
+          .gsub(/[\u064B|\u064C|\u064D|\u064E|\u064F|\u0650|\u0651|\u0652|\u0640]/, "")
+          # TODO: Strip hyphens for USPS not zip
+          .gsub(/[!@%&"'*,.();:]/, "")
+          .downcase
+          .tr(T.unsafe(AtlasEngine::ValidationTranscriber::Constants.instance).with_diacritics,
+            T.unsafe(AtlasEngine::ValidationTranscriber::Constants.instance).without_diacritics)
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/predicate_pipeline.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class PredicatePipeline < FrozenRecord::Base
+      extend T::Sig
+
+      VALIDATION_PIPELINES_ROOT = T.let(File.join(AtlasEngine::Engine.root, "db/data/validation_pipelines"), String)
+
+      module Backend
+        extend FrozenRecord::Backends::Yaml
+
+        class << self
+          extend T::Sig
+
+          sig { params(file_path: String).returns(T.untyped) }
+          def load(file_path)
+            # FrozenRecord's default is to operate on a single YAML file containing all the records.
+            # A custom backend like ours, that uses separate files, must load all of them and return an array.
+            Dir[File.join(PredicatePipeline.pipeline_path, "*.yml")].map do |validation_pipeline|
+              super(validation_pipeline)
+            end
+          end
+        end
+      end
+
+      class << self
+        extend T::Sig
+
+        sig { returns(String) }
+        def pipeline_path
+          @pipeline_path ||= T.let(VALIDATION_PIPELINES_ROOT, T.nilable(String))
+        end
+
+        sig { params(pipeline_path: String).void }
+        attr_writer :pipeline_path
+      end
+
+      self.base_path = VALIDATION_PIPELINES_ROOT
+      self.backend = Backend
+
+      sig { returns(T::Array[PredicateConfig]) }
+      def pipeline
+        attributes.dig("pipeline").map do |config|
+          PredicateConfig.new(
+            class_name: config["class"].constantize,
+            field: config["field"].to_sym,
+          )
+        end
+      end
+
+      sig { returns(T.nilable(T::Class[FullAddressValidatorBase])) }
+      def full_address_validator
+        attributes.dig("full_address_validator")&.constantize
+      end
+
+      class PredicateConfig
+        extend T::Sig
+
+        sig { returns(Symbol) }
+        attr_reader :field
+
+        sig { returns(T::Class[Validators::Predicates::Predicate]) }
+        attr_reader :class_name
+
+        sig do
+          params(
+            class_name: T::Class[Validators::Predicates::Predicate],
+            field: Symbol,
+          ).void
+        end
+        def initialize(class_name:, field:)
+          @field = field
+          @class_name = class_name
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/request.rb

@@ -0,0 +1,12 @@
+# typed: false
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Request < T::Struct
+      const :address, AbstractAddress
+      const :locale, String, default: "en"
+      const :matching_strategy, T.nilable(T.any(String, Symbol)), default: nil
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/result.rb

@@ -0,0 +1,154 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Result
+      extend T::Sig
+
+      SORTED_VALIDATION_SCOPES = T.let(
+        [:country_code, :province_code, :zip, :city, :address1, :address2, :phone].freeze,
+        T::Array[Symbol],
+      )
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :client_request_id
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :origin
+
+      sig { returns(T::Array[Field]) }
+      attr_accessor :fields
+
+      sig { returns(T::Array[Concern]) }
+      attr_accessor :concerns
+
+      sig { returns(T::Array[Suggestion]) }
+      attr_accessor :suggestions
+
+      sig { returns(T::Array[String]) }
+      attr_accessor :validation_scope
+
+      sig { returns(String) }
+      attr_accessor :locale
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :candidate
+
+      sig { returns(T::Array[Errors]) }
+      attr_accessor :errors
+
+      sig { returns(String) }
+      attr_reader :id
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :matching_strategy
+
+      alias_attribute :components, :fields
+
+      sig do
+        params(
+          client_request_id: T.nilable(String),
+          origin: T.nilable(String),
+          fields: T::Array[Field],
+          concerns: T::Array[Concern],
+          suggestions: T::Array[Suggestion],
+          validation_scope: T::Array[String],
+          errors: T::Array[Errors],
+          locale: String,
+          candidate: T.nilable(String),
+          matching_strategy: T.nilable(String),
+        ).void
+      end
+      def initialize(
+        client_request_id: nil,
+        origin: nil,
+        fields: [],
+        concerns: [],
+        suggestions: [],
+        validation_scope: [],
+        errors: [],
+        locale: "en",
+        candidate: nil,
+        matching_strategy: nil
+      )
+        @origin = origin
+        @client_request_id = client_request_id
+        @fields = fields
+        @concerns = concerns
+        @suggestions = suggestions
+        @validation_scope = validation_scope
+        @errors = errors
+        @locale = locale
+        @candidate = candidate
+        @matching_strategy = matching_strategy
+
+        # For now, this UUID isn't predicated on anything and is random.
+        # There could be need in the future to help make this unique on all requests.
+        # For now, what is important is that it one is simply generated and assigned.
+        @id = T.let(generate_id, String)
+      end
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def attributes
+        {
+          id: id,
+          fields: fields.map(&:attributes),
+          concerns: concerns.map(&:attributes),
+          suggestions: suggestions.map(&:attributes),
+          validation_scope: validation_scope,
+          locale: locale,
+        }
+      end
+
+      sig do
+        params(
+          code: Symbol,
+          type: String,
+          type_level: Integer,
+          suggestion_ids: T::Array[String],
+          field_names: T::Array[Symbol],
+          message: String,
+        ).returns(Concern)
+      end
+      def add_concern(code:, type:, type_level:, suggestion_ids:, field_names:, message:)
+        new_concern = Concern.new(
+          field_names: field_names,
+          code: code,
+          type: type,
+          type_level: type_level,
+          suggestion_ids: suggestion_ids,
+          message: message,
+        )
+        concerns << new_concern
+        new_concern
+      end
+
+      sig do
+        params(suggestions_to_add: T::Array[Suggestion]).returns(T::Array[T::Array[Suggestion]])
+      end
+      def add_suggestions(suggestions_to_add)
+        suggestions_to_add.map { |suggestion| suggestions << suggestion }
+      end
+
+      sig { returns(String) }
+      def completion_service
+        "AddressValidation"
+      end
+
+      sig { returns(T::Hash[Symbol, T.nilable(String)]) }
+      def address
+        fields.each_with_object({}) do |field, hash|
+          hash[field.name.to_sym] = field.value.to_s
+        end
+      end
+
+      private
+
+      sig { returns(String) }
+      def generate_id
+        Digest::UUID.uuid_v4
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/runs_validation.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module RunsValidation
+      extend T::Sig
+      extend T::Helpers
+
+      interface!
+
+      sig { abstract.returns(Result) }
+      def run; end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/session.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "forwardable"
+
+module AtlasEngine
+  module AddressValidation
+    class Session
+      extend Forwardable
+      extend T::Sig
+
+      sig { returns(AbstractAddress) }
+      attr_reader :address
+
+      sig { returns(MatchingStrategies) }
+      attr_accessor :matching_strategy
+
+      sig { returns(T::Hash[String, AtlasEngine::AddressValidation::DatastoreBase]) }
+      attr_reader :datastore_hash
+
+      def_delegators :@address, :address1, :address2, :city, :province_code, :country_code, :zip, :phone
+
+      sig do
+        params(
+          address: AbstractAddress,
+          matching_strategy: MatchingStrategies,
+        ).void
+      end
+      def initialize(address:, matching_strategy: MatchingStrategies::Es)
+        @address = address
+        @matching_strategy = matching_strategy
+        @datastore_hash = T.let({}, T::Hash[String, AtlasEngine::AddressValidation::DatastoreBase])
+      end
+
+      sig { params(locale: T.nilable(String)).returns(ValidationTranscriber::AddressParsings) }
+      def parsings(locale: nil)
+        datastore(locale: locale).parsings
+      end
+
+      sig { params(locale: T.nilable(String)).returns(AtlasEngine::AddressValidation::DatastoreBase) }
+      def datastore(locale: nil)
+        key = locale || "default"
+        @datastore_hash[key] ||= AtlasEngine::AddressValidation::Es::Datastore.new(address: address, locale: locale)
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/statsd_emitter.rb

@@ -0,0 +1,72 @@
+# typed: true
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class StatsdEmitter
+      extend T::Sig
+      attr_reader :address, :result, :components
+
+      sig { params(address: AbstractAddress, result: Result, components: T.nilable(T::Array[Symbol])).void }
+      def initialize(address:, result:,
+        components: [:country, :province, :zip, :city, :street, :building_number, :phone])
+        @address = address
+        @result = result
+        @components = components
+      end
+
+      sig { void }
+      def run
+        components.each do |component|
+          emit(component)
+        end
+      end
+
+      sig { params(component: Symbol).void }
+      def emit(component)
+        concerns = component_concerns(component)
+        ending_breadcrumb = concerns.present? ? "invalid" : "valid"
+
+        country_code = if address.country_code.blank? || !Worldwide.region(code: address.country_code).country?
+          "no_country"
+        else
+          Worldwide.region(code: address.country_code).iso_code
+        end
+
+        I18n.with_locale("en") do
+          tags = {
+            country: country_code,
+            component: component,
+          }.compact
+
+          if concerns.empty?
+            StatsD.increment("AddressValidation.#{ending_breadcrumb}", tags: tags)
+          else
+            concerns.each do |concern|
+              tags.merge!(concern.attributes.slice(:code, :type))
+
+              StatsD.increment("AddressValidation.#{ending_breadcrumb}", tags: tags)
+            end
+          end
+        end
+
+        nil
+      end
+
+      sig { params(component: Symbol).returns(T::Array[Concern]) }
+      def component_concerns(component)
+        if component.equal?(:street)
+          result.concerns.select do |c|
+            c.attributes[:code] =~ /^(address1|address2|street).*/
+          end
+        elsif component.equal?(:building_number)
+          result.concerns.select do |c|
+            c.attributes[:code] =~ /^(missing_building_number).*/
+          end
+        else
+          result.concerns.select { |c| c.attributes[:code] =~ /^#{component}.*/ }
+        end
+      end
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/strategies.rb

@@ -0,0 +1,10 @@
+# typed: false
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    module Strategies
+      extend T::Helpers
+    end
+  end
+end

data/app/models/atlas_engine/address_validation/suggestion.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class Suggestion
+      extend T::Sig
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :id
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :address1
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :address2
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :city
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :zip
+
+      sig { params(province_code: T.nilable(String)).returns(T.nilable(String)) }
+      attr_writer :province_code
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :country_code
+
+      sig do
+        params(
+          address1: T.nilable(String),
+          address2: T.nilable(String),
+          city: T.nilable(String),
+          zip: T.nilable(String),
+          province_code: T.nilable(String),
+          country_code: T.nilable(String),
+        ).void
+      end
+      def initialize(address1: nil, address2: nil, city: nil, zip: nil, province_code: nil, country_code: nil)
+        @address1 = address1
+        @address2 = address2
+        @city = city
+        @zip = zip
+        @province_code = province_code
+        @original_country_code = country_code
+        @country_code = country_code
+
+        # generate_id uses the values of the attributes to calculate the UUID, so must be called after they're set
+        @id = T.let(generate_id, String)
+      end
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def attributes
+        {
+          id: id,
+          address1: address1,
+          address2: address2,
+          city: city,
+          zip: zip,
+          province_code: province_code,
+          province: province,
+          country_code: country_code,
+        }
+      end
+
+      sig { returns(T.nilable(String)) }
+      def province
+        return if @original_country_code.nil? || @province_code.nil?
+
+        province = Worldwide.region(code: @original_country_code)&.zone(code: @province_code)
+        province.province? ? province.full_name : nil
+      end
+
+      sig { returns(T.nilable(String)) }
+      def province_code
+        return @province_code if @province_code.blank?
+
+        # This hack is required since checkout-web is using province codes differently for Japan Vs Other countries
+        # Japan province codes are expected as full ISO codes (JP-14)
+        # while other countries are expected as 2 digit subdivision codes (e.g. ON)
+        # we can remove this logic if the client can accept 2 digit subdivision codes / ISO codes as standard response
+        province = Worldwide.region(code: @original_country_code)&.zone(code: @province_code)
+        return @province_code unless province.province?
+
+        province.legacy_code
+      end
+
+      private
+
+      sig { returns(String) }
+      def generate_id
+        Digest::UUID.uuid_v5(Digest::UUID::OID_NAMESPACE, attributes.except(:id).to_s)
+      end
+    end
+  end
+end