atlas_engine 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dde673ac6063402f30381011574f018aee19ac9d6e9b961c04252cf76cfd49e5
-  data.tar.gz: b5c0adce91a39d744004b902e2b3a4a13544a50af756bb1ace003e391b0d3643
+  metadata.gz: 2ac0ad464ab86fe1db96b5ca3f5a69254d6ad52571d8c83350645c9e031ea58b
+  data.tar.gz: f683950cfa6d89c1cdf4935d8a49d76e416c57220ac29e5aa62adcdaf2a628d5
 SHA512:
-  metadata.gz: dfe8b1e2a4ebe506f55b62a541b57ab22c0cca456ed4ef071007d43e106d0ed0b904389fd22a0424661ca76cd2f7bdc4ed5887866663eaee361f9afd5e7d3ac0
-  data.tar.gz: a632f397142d60a6da29ae440ed686ff920cb15e62349c3abb0ef9a3ccaddd975936870d55aee45867851337f10d46982f6740bbcf3379f9d74aeeed15369577
+  metadata.gz: 79ae2f83d4b4ee2d65a7d6e566bee41ac3b0c5e44f879090b4659151ca9f7987e128badf6f31569530c142ea683b8df6dce10275423469924c44f1477f6480d6
+  data.tar.gz: e1a0e889113742443408d479dba7f1bb294230d4bcfd0af8f128e6c200a19d6c595c1bdf420798ebd2a9cb9caa8fa2cd69ef21ab4361ae066aa6a48861e9f91d

data/README.md

@@ -25,7 +25,6 @@ query validation {
       zip: "K2P 2L8"
     }
     locale: "en"
-    matchingStrategy: LOCAL
   ) {
     validationScope
     concerns {
@@ -70,21 +69,6 @@ presence or absence differs per country.
 
 **Locale:** The language in which to render any messages in the validation API response.
 
-**MatchingStrategy:** The strategy used to evaluate the validity of the address input. Out of the box, Atlas Engine
-supports three different matching strategies: `local`, `es`, and `es_street`.
-  - `local` matching uses the [worldwide](https://github.com/Shopify/worldwide) gem to provide the most basic level of
-  address validation. This may include simple errors (required fields not populated) or more advanced errors (province
-  not belonging to the country, zip code not belonging to the province). This level of matching does not require
-  [ingestion](#ingestion) of country data to work, but the level of support and suggestions it can provide in its
-  responses is minimal.
-  - `es` matching uses data indexed in elasticsearch via our [ingestion](#ingestion) process to validate the city,
-  province, country, and zip code fields of the input address, in addition to all of the basic functionality provided
-  in the `local` strategy. A more detailed explanation for how this strategy works can be found [here](#elasticsearch-matching-strategy).
-  - `es_street` is our most advanced matching strategy and requires the highest quality data indexed in elasticsearch
-  via our [ingestion](#ingestion) process. This matching strategy provides everything that `es` and `local` does along
-  with validation of the address1 and address2 components of the address input. A more detailed explanation of how
-  this strategy works can be found [here](#elasticsearch-matching-strategy).
-
 **Validation Scope:** This response object is populated with the field names from the input that have been successfully
 validated.
 
@@ -109,7 +93,6 @@ query validation {
       zip: "90210"
     }
     locale: "en"
-    matchingStrategy: LOCAL
   ) {
     validationScope
     concerns {
@@ -410,6 +393,20 @@ and the US data is in mysql the rest of the process for creating the elasticsear
 
 ## Elasticsearch Matching Strategy
 
+An optional GraphQL parameter, and the strategy used to evaluate the validity of the address input. Out of the box, Atlas Engine
+supports three different matching strategies: `local`, `es`, and `es_street`.
+  - `local` matching uses the [worldwide](https://github.com/Shopify/worldwide) gem to provide the most basic level of
+  address validation. This may include simple errors (required fields not populated) or more advanced errors (province
+  not belonging to the country, zip code not belonging to the province). This level of matching does not require
+  [ingestion](#ingestion) of country data to work, but the level of support and suggestions it can provide in its
+  responses is minimal.
+  - `es` matching uses data indexed in elasticsearch via our [ingestion](#ingestion) process to validate the city,
+  province, country, and zip code fields of the input address, in addition to all of the basic functionality provided
+  in the `local` strategy.
+  - `es_street` is our most advanced matching strategy and requires the highest quality data indexed in elasticsearch
+  via our [ingestion](#ingestion) process. This matching strategy provides everything that `es` and `local` does along
+  with validation of the address1 and address2 components of the address input.
+
 Once we have successfully created and activated an elasticsearch index using open address data, we may now use
 the more advanced elasticsearch matching strategies `es` and `es_street`.
 

data/app/graphql/atlas_engine/schema.graphql

@@ -47,8 +47,13 @@ enum MatchingStrategy {
   LOCAL
 }
 
+enum MessageFormat {
+  INFORMATIVE
+  INSTRUCTIONAL
+}
+
 type Query {
-  validation(address: AddressInput!, locale: String!, matchingStrategy: MatchingStrategy): Validation!
+  validation(address: AddressInput!, locale: String!, matchingStrategy: MatchingStrategy, messageFormat: MessageFormat): Validation!
 }
 
 """
@@ -60,8 +65,12 @@ type Suggestion {
   city: String
   countryCode: ValidationSupportedCountry
   id: String!
+  line2: String
+  neighborhood: String
   province: String
   provinceCode: String
+  streetName: String
+  streetNumber: String
   zip: String
 }
 

data/app/graphql/atlas_engine/types/address_validation/concern_type.rb

@@ -1,10 +1,12 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 module AtlasEngine
   module Types
     module AddressValidation
       class ConcernType < BaseObject
+        extend T::Sig
+
         description "A piece of relevant information regarding the address validation result." \
           "They can be categorized as either a Warning or Error."
 
@@ -14,6 +16,11 @@ module AtlasEngine
         field :type, Enums::ConcernEnum, null: false
         field :type_level, Int, null: false
         field :suggestion_ids, [String], null: false
+
+        sig { returns(T::Array[String]) }
+        def field_names
+          object.field_names.map { |field_name| field_name.to_s.camelize(:lower) }
+        end
       end
     end
   end

data/app/graphql/atlas_engine/types/address_validation/suggestion_type.rb

@@ -9,7 +9,11 @@ module AtlasEngine
 
         field :id, String, null: false
         field :address1, String, null: true
+        field :street_name, String, null: true
+        field :street_number, String, null: true
         field :address2, String, null: true
+        field :line2, String, null: true
+        field :neighborhood, String, null: true
         field :city, String, null: true
         field :zip, String, null: true
         field :province_code, String, null: true

data/app/graphql/atlas_engine/types/message_format_type.rb

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module Types
+    class MessageFormatType < BaseEnum
+      value :INSTRUCTIONAL, value: "instructional"
+      value :INFORMATIVE, value: "informative"
+    end
+  end
+end

data/app/graphql/atlas_engine/types/query_type.rb

@@ -10,9 +10,10 @@ module AtlasEngine
         argument :address, AddressValidation::AddressInput, required: true
         argument :locale, String, required: true
         argument :matching_strategy, MatchingStrategyType, required: false
+        argument :message_format, MessageFormatType, required: false
       end
 
-      def validation(address:, locale: "en", matching_strategy: nil)
+      def validation(address:, locale: "en", matching_strategy: nil, message_format: nil)
         raise build_graphql_error(AtlasEngine::AddressValidation::Errors::MISSING_PARAMETER) if address.blank?
 
         locale = LocaleFormatHelper.format_locale(locale)
@@ -26,6 +27,7 @@ module AtlasEngine
                 address: address,
                 locale: locale,
                 matching_strategy: matching_strategy,
+                message_format: message_format,
               ),
             )
           end

data/app/lib/atlas_engine/validation_transcriber/address_parsings.rb

@@ -9,22 +9,27 @@ module AtlasEngine
 
       ParsedComponents = T.type_alias { T::Hash[Symbol, String] }
 
-      sig { returns(T::Array[ParsedComponents]) }
-      attr_reader :parsings
-
       sig { params(address_input: AddressValidation::AbstractAddress, locale: T.nilable(String)).void }
       def initialize(address_input:, locale: nil)
-        @parsings = T.let(
+        @address_input = address_input
+        @locale = locale
+      end
+
+      sig { returns(T::Array[ParsedComponents]) }
+      def parsings
+        @parsings ||= T.let(
           begin
-            if address_input.country_code.blank?
+            if @address_input.country_code.blank?
               []
-            else
-              parsing_result = AddressParserFactory.create(address: address_input, locale: locale).parse
-              log_unparsable_address(address_input) if parsing_result.empty?
+            elsif @address_input.street_name.nil? && @address_input.street_number.nil?
+              parsing_result = AddressParserFactory.create(address: @address_input, locale: @locale).parse
+              log_unparsable_address(@address_input) if parsing_result.empty?
               parsing_result
+            else
+              [{ street: @address_input.street_name, building_num: @address_input.street_number }]
             end
           end,
-          T::Array[ParsedComponents],
+          T.nilable(T::Array[ParsedComponents]),
         )
       end
 

data/app/models/atlas_engine/address_validation/es/validators/full_address.rb

@@ -8,12 +8,13 @@ module AtlasEngine
         class FullAddress < FullAddressValidatorBase
           include LogHelper
 
-          attr_reader :address, :result
+          attr_reader :address, :result, :message_format
 
-          sig { params(address: TAddress, result: Result).void }
-          def initialize(address:, result: Result.new)
+          sig { params(address: TAddress, result: Result, message_format: MessageFormat).void }
+          def initialize(address:, result: Result.new, message_format: MessageFormat::Instructional)
             super
             @matching_strategy = MatchingStrategies::Es
+            @message_format = message_format
           end
 
           sig { override.returns(Result) }
@@ -29,16 +30,23 @@ module AtlasEngine
           sig { returns(AddressValidation::Validators::FullAddress::CandidateResultBase) }
           def build_candidate_result
             unless supported_address?(address)
-              return AddressValidation::Validators::FullAddress::UnsupportedScriptResult.new(address:, result:)
+              return AddressValidation::Validators::FullAddress::UnsupportedScriptResult.new(
+                address:,
+                result:,
+                message_format:,
+              )
             end
 
             if best_candidate.nil?
-              AddressValidation::Validators::FullAddress::NoCandidateResult.new(address:, result:)
+              AddressValidation::Validators::FullAddress::NoCandidateResult.new(
+                address:, result:, message_format:,
+              )
             else
               AddressValidation::Validators::FullAddress::CandidateResult.new(
                 address_comparison: T.must(best_candidate),
                 matching_strategy: @matching_strategy,
                 result: result,
+                message_format:,
               )
             end
           end
@@ -100,6 +108,10 @@ module AtlasEngine
               :zip,
               :address1,
               :address2,
+              :street_name,
+              :street_number,
+              :neighborhood,
+              :line2,
             ])
           end
 
@@ -108,6 +120,7 @@ module AtlasEngine
             result.concerns.flat_map(&:code).intersect?([
               :address1_contains_too_many_words,
               :address2_contains_too_many_words,
+              :street_name_contains_too_many_words,
             ])
           end
 

data/app/models/atlas_engine/address_validation/es/validators/full_address_street.rb

@@ -6,8 +6,8 @@ module AtlasEngine
     module Es
       module Validators
         class FullAddressStreet < FullAddress
-          sig { params(address: TAddress, result: Result).void }
-          def initialize(address:, result: Result.new)
+          sig { params(address: TAddress, message_format: MessageFormat, result: Result).void }
+          def initialize(address:, message_format:, result: Result.new)
             super
             @matching_strategy = MatchingStrategies::EsStreet
           end

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

@@ -14,10 +14,14 @@ module AtlasEngine
       sig { returns(AbstractAddress) }
       attr_reader :address
 
-      sig { params(address: AbstractAddress, result: Result).void }
-      def initialize(address:, result:)
+      sig { returns(MessageFormat) }
+      attr_reader :message_format
+
+      sig { params(address: AbstractAddress, result: Result, message_format: MessageFormat).void }
+      def initialize(address:, result:, message_format: MessageFormat::Instructional)
         @address = address
         @result = result
+        @message_format = message_format
       end
 
       sig { abstract.returns(Result) }

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

@@ -0,0 +1,13 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class MessageFormat < T::Enum
+      enums do
+        Instructional = new("instructional")
+        Informative = new("informative")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# typed: strict
+# frozen_string_literal: true
+
+module AtlasEngine
+  module AddressValidation
+    class PredicatePipelineBuilder
+      extend T::Sig
+
+      sig { returns(PredicatePipeline) }
+      attr_reader :predicate_pipeline
+
+      sig { returns(AbstractAddress) }
+      attr_reader :address
+
+      sig { returns(Result) }
+      attr_reader :result
+
+      sig { returns(MessageFormat) }
+      attr_reader :message_format
+
+      sig do
+        params(
+          matching_strategy_name: String,
+          address: AbstractAddress,
+          result: Result,
+          message_format: MessageFormat,
+        ).void
+      end
+      def initialize(matching_strategy_name:, address:, result:, message_format:)
+        @address = address
+        @predicate_pipeline = T.let(PredicatePipeline.find(matching_strategy_name), PredicatePipeline)
+        @result = result
+        @message_format = message_format
+      end
+
+      sig { returns(T::Array[PredicatePipeline::PredicateConfig]) }
+      def pipeline
+        predicate_pipeline.pipeline.reject do |predicate_config|
+          unsupported_fields.include?(predicate_config.field)
+        end
+      end
+
+      sig { returns(T.nilable(FullAddressValidatorBase)) }
+      def full_address_validator
+        predicate_pipeline.full_address_validator&.new(
+          address: address,
+          result: result,
+          message_format: message_format,
+        )
+      end
+
+      sig do
+        returns(T::Array[Symbol])
+      end
+      def unsupported_fields
+        @unsupported_fields ||= T.let(
+          begin
+            unsupported_fields = []
+            unsupported_fields += address1_format == :extended ? [:address1] : [:street_name, :street_number]
+            unsupported_fields += address2_format == :extended ? [:address2] : [:line2, :neighborhood]
+            unsupported_fields
+          end,
+          T.nilable(T::Array[T.untyped]),
+        )
+      end
+
+      private
+
+      sig { returns(Symbol) }
+      def address1_format
+        T.let(
+          [:street_name, :street_number].all? do |field|
+            address.send(field).nil?
+          end ? :standard : :extended,
+          Symbol,
+        )
+      end
+
+      sig { returns(Symbol) }
+      def address2_format
+        T.let(
+          [:neighborhood, :line2].all? do |field|
+            address.send(field).nil?
+          end ? :standard : :extended,
+          Symbol,
+        )
+      end
+    end
+  end
+end

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

@@ -7,6 +7,7 @@ module AtlasEngine
       const :address, AbstractAddress
       const :locale, String, default: "en"
       const :matching_strategy, T.nilable(T.any(String, Symbol)), default: nil
+      const :message_format, T.nilable(T.any(String, Symbol)), default: nil
     end
   end
 end

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

@@ -12,9 +12,21 @@ module AtlasEngine
       sig { returns(T.nilable(String)) }
       attr_accessor :address1
 
+      sig { returns(T.nilable(String)) }
+      attr_accessor :street_name
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :street_number
+
       sig { returns(T.nilable(String)) }
       attr_accessor :address2
 
+      sig { returns(T.nilable(String)) }
+      attr_accessor :line2
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :neighborhood
+
       sig { returns(T.nilable(String)) }
       attr_accessor :city
 
@@ -30,16 +42,25 @@ module AtlasEngine
       sig do
         params(
           address1: T.nilable(String),
+          street_name: T.nilable(String),
+          street_number: T.nilable(String),
           address2: T.nilable(String),
+          line2: T.nilable(String),
+          neighborhood: 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)
+      def initialize(address1: nil, street_name: nil, street_number: nil, address2: nil, line2: nil, neighborhood: nil,
+        city: nil, zip: nil, province_code: nil, country_code: nil)
         @address1 = address1
+        @street_name = street_name
+        @street_number = street_number
         @address2 = address2
+        @line2 = line2
+        @neighborhood = neighborhood
         @city = city
         @zip = zip
         @province_code = province_code
@@ -55,7 +76,11 @@ module AtlasEngine
         {
           id: id,
           address1: address1,
+          street_name: street_name,
+          street_number: street_number,
           address2: address2,
+          line2: line2,
+          neighborhood: neighborhood,
           city: city,
           zip: zip,
           province_code: province_code,

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

@@ -28,6 +28,12 @@ module AtlasEngine
       sig { returns(T.nilable(FullAddressValidatorBase)) }
       attr_reader :full_address_validator
 
+      sig { returns(T::Array[Symbol]) }
+      attr_reader :unsupported_fields
+
+      sig { returns(MessageFormat) }
+      attr_reader :message_format
+
       FIELD_MAP = T.let(
         {
           country: "country_code",
@@ -36,6 +42,10 @@ module AtlasEngine
           city: "city",
           address1: "address1",
           address2: "address2",
+          street_name: "street_name",
+          street_number: "street_number",
+          neighborhood: "neighborhood",
+          line2: "line2",
           phone: "phone",
         },
         T::Hash[Symbol, String],
@@ -47,13 +57,15 @@ module AtlasEngine
           matching_strategy: Strategies,
           locale: String,
           context: T::Hash[T.untyped, T.untyped],
+          message_format: MessageFormat,
         ).void
       end
       def initialize(
         address:,
         matching_strategy:,
         locale: "en",
-        context: {}
+        context: {},
+        message_format: MessageFormat::Instructional
       )
         @address = T.let(address, AbstractAddress)
         @address1 = T.let(address.address1, T.nilable(String))
@@ -65,9 +77,9 @@ module AtlasEngine
         @country_code = T.let(address.country_code, T.nilable(String))
         @context = T.let(context, T::Hash[T.untyped, T.untyped])
         @matching_strategy = T.let(matching_strategy, Strategies)
+        @message_format = T.let(message_format, MessageFormat)
 
         matching_strategy_name = matching_strategy.serialize
-        @predicate_pipeline = T.let(PredicatePipeline.find(matching_strategy_name), PredicatePipeline)
 
         @result = T.let(
           Result.new(
@@ -78,14 +90,14 @@ module AtlasEngine
           ),
           Result,
         )
+        pipeline_builder = PredicatePipelineBuilder.new(matching_strategy_name:, address:, result:, message_format:)
 
-        @full_address_validator = T.let(
-          @predicate_pipeline.full_address_validator&.new(
-            address: @address,
-            result: @result,
-          ),
-          T.nilable(FullAddressValidatorBase),
+        @pipeline = T.let(
+          pipeline_builder.pipeline,
+          T::Array[AtlasEngine::AddressValidation::PredicatePipeline::PredicateConfig],
         )
+        @unsupported_fields = T.let(pipeline_builder.unsupported_fields, T::Array[Symbol])
+        @full_address_validator = T.let(pipeline_builder.full_address_validator, T.nilable(FullAddressValidatorBase))
       end
 
       sig { override.returns(Result) }
@@ -113,15 +125,20 @@ module AtlasEngine
         pipeline_address = Address.from_address(address: address)
         local_concerns = {}
         cache = Validators::Predicates::Cache.new(pipeline_address)
-        @predicate_pipeline.pipeline.each do |config|
+        @pipeline.each do |predicate_config|
           break if local_concerns[:country].present?
 
-          local_concerns[config.field] = [] if local_concerns[config.field].nil?
-          next if local_concerns[config.field].present?
+          local_concerns[predicate_config.field] = [] if local_concerns[predicate_config.field].nil?
+          next if local_concerns[predicate_config.field].present?
 
-          concern = config.class_name.new(field: config.field, address: pipeline_address, cache: cache).evaluate
+          concern = predicate_config.class_name.new(
+            field: predicate_config.field,
+            address: pipeline_address,
+            cache: cache,
+            message_format: message_format,
+          ).evaluate
 
-          local_concerns[config.field] << concern if concern.present?
+          local_concerns[predicate_config.field] << concern if concern.present?
         end
         local_concerns
       end
@@ -129,7 +146,7 @@ module AtlasEngine
       sig { params(local_concerns: T::Hash[Symbol, T::Array[Concern]]).void }
       def populate_result(local_concerns)
         local_concerns.keys.each do |field|
-          if local_concerns[field]&.empty? && [:address2, :phone].exclude?(field)
+          if local_concerns[field]&.empty? && [:address2, :phone].concat(unsupported_fields).exclude?(field)
             result.validation_scope << T.must(FIELD_MAP[field])
           end
 

data/app/models/atlas_engine/address_validation/validators/full_address/candidate_result.rb

@@ -14,10 +14,11 @@ module AtlasEngine
               address_comparison: AddressComparison,
               matching_strategy: AddressValidation::MatchingStrategies,
               result: Result,
+              message_format: MessageFormat,
             ).void
           end
-          def initialize(address_comparison:, matching_strategy:, result:)
-            super(address: address_comparison.address, result: result)
+          def initialize(address_comparison:, matching_strategy:, result:, message_format:)
+            super(address: address_comparison.address, result: result, message_format: message_format)
             @address_comparison = address_comparison
             @candidate = address_comparison.candidate
             @matching_strategy = matching_strategy
@@ -56,11 +57,11 @@ module AtlasEngine
 
           sig { void }
           def add_concerns_without_suggestions
-            concern = InvalidZipConcernBuilder.for(address, [])
+            concern = InvalidZipConcernBuilder.for(address, [], message_format)
             result.concerns << concern if concern
 
             if ConcernBuilder.too_many_unmatched_components?(address, unmatched_components.keys)
-              result.concerns << UnknownAddressConcernBuilder.new(address).build
+              result.concerns << UnknownAddressConcernBuilder.new(address, message_format).build
             end
           end
 
@@ -79,6 +80,7 @@ module AtlasEngine
                 matched_components: matched_components_to_validate.keys,
                 address: address,
                 suggestion_ids: [suggestion.id].compact,
+                message_format: message_format,
               ).build
               result.concerns << concern
             end
@@ -167,7 +169,9 @@ module AtlasEngine
 
             original_street = T.must(unmatched_components_to_validate[:street]).left_sequence.raw_value
 
-            if address.address1.to_s.include?(original_street)
+            if address.street_name.present?
+              :street_name
+            elsif address.address1.to_s.include?(original_street)
               :address1
             elsif address.address2.to_s.include?(original_street)
               :address2

data/app/models/atlas_engine/address_validation/validators/full_address/candidate_result_base.rb

@@ -11,10 +11,11 @@ module AtlasEngine
 
           abstract!
 
-          sig { params(address: AbstractAddress, result: Result).void }
-          def initialize(address:, result:)
+          sig { params(address: AbstractAddress, result: Result, message_format: MessageFormat).void }
+          def initialize(address:, result:, message_format: MessageFormat::Instructional)
             @address = address
             @result = result
+            @message_format = message_format
           end
 
           sig { void }
@@ -22,7 +23,7 @@ module AtlasEngine
 
           private
 
-          attr_reader :result, :address
+          attr_reader :result, :address, :message_format
 
           sig { void }
           def update_result_scope