smartystreets_ruby_sdk 2.0.2 → 3.0.0

data/lib/smartystreets_ruby_sdk/us_autocomplete/geolocation_type.rb

@@ -0,0 +1,5 @@
+module GeolocationType
+  CITY = 'city'
+  STATE = 'state'
+  NONE = 'null'
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/lookup.rb

@@ -0,0 +1,34 @@
+require_relative '../json_able'
+
+module USAutocomplete
+  # In addition to holding all of the input data for this lookup, this class also will contain the result
+  # of the lookup after it comes back from the API.
+  #
+  # See "https://smartystreets.com/docs/cloud/us-autocomplete-api#http-request-input-fields"
+  class Lookup < JSONAble
+
+    attr_accessor :result, :prefix, :state_filter, :prefer, :max_suggestions, :geolocate_type, :city_filter
+
+    def initialize(prefix=nil, suggestions=nil, city_filter=nil, state_filter=nil, prefer=nil, geolocate_type=nil)
+      @result = []
+      @prefix = prefix
+      @max_suggestions = suggestions
+      @city_filter = city_filter ? city_filter : []
+      @state_filter = state_filter ? state_filter : []
+      @prefer = prefer ? prefer : []
+      @geolocate_type = geolocate_type
+    end
+
+    def add_city_filter(city)
+      @city_filter.push(city)
+    end
+
+    def add_state_filter(state)
+      @state_filter.push(state)
+    end
+
+    def add_prefer(prefer)
+      @prefer.push(prefer)
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_autocomplete/suggestion.rb

@@ -0,0 +1,14 @@
+module USAutocomplete
+  # See "https://smartystreets.com/docs/cloud/us-autocomplete-api#http-response"
+  class Suggestion
+
+    attr_reader :text, :street_line, :state, :city
+
+    def initialize(obj)
+      @text = obj.fetch('text', nil)
+      @street_line = obj.fetch('street_line', nil)
+      @city = obj.fetch('city', nil)
+      @state = obj.fetch('state', nil)
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_extract.rb

@@ -0,0 +1,8 @@
+require_relative './us_extract/lookup'
+require_relative './us_extract/address'
+require_relative './us_extract/metadata'
+require_relative './us_extract/result'
+require_relative './us_extract/client'
+
+module USExtract
+end

data/lib/smartystreets_ruby_sdk/us_extract/address.rb

@@ -0,0 +1,22 @@
+require_relative '../us_street/candidate'
+
+module USExtract
+# See "https://smartystreets.com/docs/cloud/us-extract-api#http-response-status"
+  class Address
+    attr_reader :text, :start, :verified, :end, :line, :candidates
+
+    def initialize(obj)
+      @text = obj['text']
+      @verified = obj['verified']
+      @line = obj['line']
+      @start = obj['start']
+      @end = obj['end']
+      candidates = obj.fetch('api_output', [])
+      @candidates = []
+
+      candidates.each { |candidate|
+        @candidates.push(USStreet::Candidate.new(candidate))
+      }
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_extract/client.rb

@@ -0,0 +1,46 @@
+require_relative '../request'
+require_relative '../exceptions'
+require_relative 'result'
+
+module USExtract
+  # It is recommended to instantiate this class using ClientBuilder.build_us_extract_api_client()
+  class Client
+    def initialize(sender, serializer)
+      @sender = sender
+      @serializer = serializer
+    end
+
+    # Sends a Lookup object to the US Extract Code API and stores the result in the Lookup's result field.
+    # It also returns the result directly.
+    def send(lookup)
+      if lookup.nil? or lookup.text.nil? or not lookup.text.is_a? String or lookup.text.empty?
+        raise SmartyException, 'Client.send() requires a Lookup with the "text" field set'
+      end
+
+      request = build_request(lookup)
+      response = @sender.send(request)
+      result = Result.new(@serializer.deserialize(response.payload))
+
+      lookup.result = result
+    end
+
+    def build_request(lookup)
+      request = Request.new
+      request.content_type = 'text/plain'
+      request.payload = lookup.text
+
+      add_parameter(request, 'html', lookup.html.to_s)
+      add_parameter(request, 'aggressive', lookup.aggressive.to_s)
+      add_parameter(request, 'addr_line_breaks', lookup.addresses_have_line_breaks.to_s)
+      add_parameter(request, 'addr_per_line', lookup.addresses_per_line.to_s)
+
+      request
+    end
+
+    def add_parameter(request, key, value)
+      if value and not value.empty?
+        request.parameters[key] = value
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_extract/lookup.rb

@@ -0,0 +1,20 @@
+require_relative '../json_able'
+
+module USExtract
+  # In addition to holding all of the input data for this lookup, this class also will contain the result
+  # of the lookup after it comes back from the API.
+  #
+  # See "https://smartystreets.com/docs/cloud/us-extract-api#http-request-input-fields"
+  class Lookup < JSONAble
+    attr_accessor :text, :result, :aggressive, :addresses_per_line, :html, :addresses_have_line_breaks
+
+    def initialize(text=nil, html=nil, aggressive=nil, addresses_have_line_breaks=nil, addresses_per_line=nil)
+      @text = text
+      @html = html
+      @aggressive = aggressive
+      @addresses_have_line_breaks = addresses_have_line_breaks
+      @addresses_per_line = addresses_per_line
+      @result = nil
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_extract/metadata.rb

@@ -0,0 +1,15 @@
+module USExtract
+  # See "https://smartystreets.com/docs/cloud/us-extract-api#http-response-status"
+  class Metadata
+    attr_reader :unicode, :lines, :verified_count, :character_count, :bytes, :address_count
+
+    def initialize(obj)
+      @lines = obj['lines']
+      @unicode = obj['unicode']
+      @address_count = obj['address_count']
+      @verified_count = obj['verified_count']
+      @bytes = obj['bytes']
+      @character_count = obj['character_count']
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_extract/result.rb

@@ -0,0 +1,19 @@
+require_relative './address'
+require_relative './metadata'
+
+module USExtract
+  # See "https://smartystreets.com/docs/cloud/us-extract-api#http-response-status"
+  class Result
+    attr_reader :metadata, :addresses
+
+    def initialize(obj)
+      @metadata = Metadata.new(obj.fetch('meta', {}))
+      addresses = obj.fetch('addresses', [])
+      @addresses = []
+
+      addresses.each { |address|
+        @addresses.push(Address.new(address))
+      }
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_street.rb

@@ -1,10 +1,10 @@
 require_relative './us_street/analysis'
 require_relative './us_street/candidate'
 require_relative './us_street/client'
-require_relative './us_street/client_builder'
 require_relative './us_street/components'
 require_relative './us_street/lookup'
 require_relative './us_street/metadata'
+require_relative './us_street/match_type'
 
 module USStreet
 end

data/lib/smartystreets_ruby_sdk/us_street/analysis.rb

@@ -1,4 +1,5 @@
 module USStreet
+  # See "https://smartystreets.com/docs/cloud/us-street-api#analysis"
   class Analysis
     attr_reader :lacs_link_code, :active, :footnotes, :lacs_link_indicator, :dpv_match_code, :is_suite_link_match,
                 :is_ews_match, :dpv_footnotes, :cmra, :vacant

data/lib/smartystreets_ruby_sdk/us_street/candidate.rb

@@ -3,6 +3,7 @@ require_relative 'metadata'
 require_relative 'analysis'
 
 module USStreet
+  # See "https://smartystreets.com/docs/cloud/us-street-api#metadata"
   class Candidate
     attr_reader :input_index, :candidate_index, :addressee, :delivery_line_1, :delivery_line_2, :delivery_point_barcode,
                 :last_line, :metadata, :components, :analysis

data/lib/smartystreets_ruby_sdk/us_street/client.rb

@@ -3,22 +3,26 @@ require_relative '../request'
 require_relative 'candidate'
 
 module USStreet
+  # It is recommended to instantiate this class using ClientBuilder.build_us_street_api_client
   class Client
     def initialize(sender, serializer)
       @sender = sender
       @serializer = serializer
     end
 
+    # Sends a Lookup object to the US Street API and stores the result in the Lookup's result field.
     def send_lookup(lookup)
       batch = Batch.new
       batch.add(lookup)
       send_batch(batch)
     end
 
+    # Sends a Batch object containing no more than 100 Lookup objects to the US Street API and stores the
+    # results in the result field of the Lookup object.
     def send_batch(batch)
       smarty_request = Request.new
 
-      return if batch.size == 0
+      return if batch.empty?
 
       converted_lookups = remap_keys(batch.all_lookups)
       smarty_request.payload = @serializer.serialize(converted_lookups)
@@ -35,7 +39,7 @@ module USStreet
 
     def remap_keys(obj)
       converted_obj = []
-      obj.each { |lookup|
+      obj.each do |lookup|
         converted_lookup = {}
 
         converted_lookup['street'] = lookup.street
@@ -51,15 +55,15 @@ module USStreet
         converted_lookup['candidates'] = lookup.candidates
 
         converted_obj.push(converted_lookup)
-      }
+      end
       converted_obj
     end
 
     def assign_candidates_to_lookups(batch, candidates)
-      candidates.each { |raw_candidate|
+      candidates.each do |raw_candidate|
         candidate = Candidate.new(raw_candidate)
         batch[candidate.input_index].result.push(candidate)
-      }
+      end
     end
   end
 end

data/lib/smartystreets_ruby_sdk/us_street/components.rb

@@ -1,4 +1,7 @@
 module USStreet
+  # This class contains the matched address broken down into its fundamental pieces.
+  #
+  # See "https://smartystreets.com/docs/cloud/us-street-api#components"
   class Components
     attr_reader :street_postdirection, :delivery_point_check_digit, :secondary_designator, :secondary_number, :zipcode,
                 :pmb_number, :state_abbreviation, :extra_secondary_designator, :urbanization, :street_name, :city_name,

data/lib/smartystreets_ruby_sdk/us_street/lookup.rb

@@ -1,6 +1,12 @@
 require_relative '../json_able'
 
 module USStreet
+  # In addition to holding all of the input data for this lookup, this class also will contain
+  # the result of the lookup after it comes back from the API.
+  #
+  # See "https://smartystreets.com/docs/cloud/us-street-api#input-fields"
+  #
+  # @match:: Must be set to 'strict', 'range', or 'invalid'. Constants for these are in match_type.rb
   class Lookup < JSONAble
     attr_accessor :input_id, :street, :street2, :secondary, :city, :state, :zipcode, :lastline, :addressee, :urbanization,
                   :match, :candidates, :result

data/lib/smartystreets_ruby_sdk/us_street/match_type.rb

@@ -0,0 +1,5 @@
+module MatchType
+  STRICT = 'strict'.freeze
+  RANGE = 'range'.freeze
+  INVALID = 'invalid'.freeze
+end

data/lib/smartystreets_ruby_sdk/us_street/metadata.rb

@@ -1,4 +1,5 @@
 module USStreet
+  # See "https://smartystreets.com/docs/cloud/us-street-api#metadata"
   class Metadata
     attr_reader :elot_sort, :longitude, :elot_sequence, :county_fips, :building_default_indicator, :rdi,
                 :congressional_district, :latitude, :precision, :time_zone, :zip_type, :county_name, :utc_offset,

data/lib/smartystreets_ruby_sdk/us_zipcode.rb

@@ -1,9 +1,9 @@
 require_relative './us_zipcode/city'
 require_relative './us_zipcode/client'
-require_relative './us_zipcode/client_builder'
 require_relative './us_zipcode/lookup'
 require_relative './us_zipcode/result'
 require_relative './us_zipcode/zip_code'
+require_relative './us_zipcode/alternate_county'
 
 module USZipcode
 end

data/lib/smartystreets_ruby_sdk/us_zipcode/alternate_county.rb

@@ -0,0 +1,13 @@
+module USZipcode
+  # See "https://smartystreets.com/docs/cloud/us-zipcode-api#zipcodes"
+  class AlternateCounty
+    attr_reader :state_abbreviation, :state, :county_name, :county_fips
+
+    def initialize(obj)
+      @county_fips = obj.fetch('county_fips', nil)
+      @county_name = obj.fetch('county_name', nil)
+      @state_abbreviation = obj.fetch('state_abbreviation', nil)
+      @state = obj.fetch('state', nil)
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/us_zipcode/city.rb

@@ -1,4 +1,6 @@
 module USZipcode
+  # Known in the SmartyStreets US ZIP Code API documentation as a city_state
+  # See "https://smartystreets.com/docs/cloud/us-zipcode-api#cities"
   class City
     attr_reader :mailable_city, :state_abbreviation, :state, :city
 

data/lib/smartystreets_ruby_sdk/us_zipcode/client.rb

@@ -3,22 +3,26 @@ require_relative '../batch'
 require_relative '../request'
 
 module USZipcode
+  # It is recommended to instantiate this class using ClientBuilder.build_us_zipcode_api_client.
   class Client
     def initialize(sender, serializer)
       @sender = sender
       @serializer = serializer
     end
 
+    # Sends a Lookup object to the US ZIP Code API and stores the result in the Lookup's result field.
     def send_lookup(lookup)
       batch = Batch.new
       batch.add(lookup)
       send_batch(batch)
     end
 
+    # Sends a Batch object containing no more than 100 Lookup objects to the US ZIP Code API and stores the
+    # results in the result field of the Lookup object.
     def send_batch(batch)
       smarty_request = Request.new
 
-      return if batch.size == 0
+      return if batch.empty?
 
       converted_lookups = remap_keys(batch.all_lookups)
       smarty_request.payload = @serializer.serialize(converted_lookups)
@@ -44,14 +48,18 @@ module USZipcode
       obj.each do |lookup|
         converted_lookup = {}
 
-        converted_lookup['city'] = lookup.city
-        converted_lookup['state'] = lookup.state
-        converted_lookup['zipcode'] = lookup.zipcode
+        add_field(converted_lookup, 'city', lookup.city)
+        add_field(converted_lookup, 'state', lookup.state)
+        add_field(converted_lookup, 'zipcode', lookup.zipcode)
 
         converted_obj.push(converted_lookup)
       end
 
       converted_obj
     end
+
+    def add_field(converted_lookup, key, value)
+      converted_lookup[key] = value unless value.nil? or value.empty?
+    end
   end
 end

data/lib/smartystreets_ruby_sdk/us_zipcode/lookup.rb

@@ -1,5 +1,9 @@
 require_relative '../json_able'
 module USZipcode
+  # In addition to holding all of the input data for this lookup, this class also
+  #   will contain the result of the lookup after it comes back from the API.
+  #
+  #   See "https://smartystreets.com/docs/cloud/us-zipcode-api#http-request-input-fields"
   class Lookup < JSONAble
     attr_accessor :result, :state, :zipcode, :input_id, :city
 

data/lib/smartystreets_ruby_sdk/us_zipcode/result.rb

@@ -2,6 +2,7 @@ require_relative 'city'
 require_relative 'zip_code'
 
 module USZipcode
+  # See "https://smartystreets.com/docs/cloud/us-zipcode-api#root"
   class Result
     attr_reader :reason, :input_index, :cities, :zipcodes, :status
 
@@ -16,8 +17,8 @@ module USZipcode
       @zipcodes = convert_zipcodes
     end
 
-    def is_valid?
-      @status == nil and @reason == nil
+    def valid?
+      @status.nil? and @reason.nil?
     end
 
     def convert_cities

data/lib/smartystreets_ruby_sdk/us_zipcode/zip_code.rb

@@ -1,6 +1,11 @@
+require_relative 'alternate_county'
+
 module USZipcode
+  # See "https://smartystreets.com/docs/cloud/us-zipcode-api#zipcodes"
   class ZipCode
-    attr_reader :longitude, :county_name, :zipcode, :zipcode_type, :county_fips, :latitude, :precision, :default_city, :alternate_counties
+    attr_reader :longitude, :county_name, :zipcode, :zipcode_type, :county_fips,
+                :latitude, :precision, :default_city, :alternate_counties,
+                :state_abbreviation, :state
 
     def initialize(obj)
       @zipcode = obj['zipcode']
@@ -11,7 +16,15 @@ module USZipcode
       @latitude = obj['latitude']
       @longitude = obj['longitude']
       @precision = obj['precision']
-      @alternate_counties = obj.fetch('alternate_counties', [])
+      @state = obj['state']
+      @state_abbreviation = obj['state_abbreviation']
+      alternate_counties = obj.fetch('alternate_counties', [])
+
+      @alternate_counties = []
+
+      alternate_counties.each do |county|
+        @alternate_counties.push(USZipcode::AlternateCounty.new(county))
+      end
     end
   end
-end
+end