smartystreets_ruby_sdk 2.0.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 665c822316222777a6640d2c0c922eed97f710fa
-  data.tar.gz: f3246443b089ecef2430faef09d6e0d36aaf2726
+  metadata.gz: 64962ee9e3575877e78359805f3a0aad0bb6ab33
+  data.tar.gz: a7fe26f68f4dc756ae3955aca126fba7c4c3f0c4
 SHA512:
-  metadata.gz: 4016e6992d6917bee97a08b448288c2fcdbc3b3a57e4e69cde85225eaf90c9defc4e52fa3eeebf4c6ce3b0240de379c122982a9970b65cc80b6f233801c3059f
-  data.tar.gz: 7618b81a005957429f37e371e1c9170e20967daabe3cbd0ee23a4c41cc33b5071bb7d43c14486f4167520ba633ca579e3f300a7ce923f8c6cadc9973c0aefe3e
+  metadata.gz: 5aeb2e1c9161f295dd43400ae198147e357628740c6432c1ee25f28e51d4d89fcf79c4533f89d720bdfc4ec0d1a1cc1cee5d1e6c122fac49c22d67f66bcf18bf
+  data.tar.gz: dc7caf151400097419930d2b8009b6fa7e8b94eef69000c3d0f5287cc4a5266c36f7d78993f6e44efd20205defaf81257d92e31ee01788d0f12c755201637cbb

data/Makefile

@@ -1,6 +1,6 @@
 #!/usr/bin/make -f
 
-SOURCE_VERSION := 2.0
+SOURCE_VERSION := 3.0
 
 tests:
 	ruby -Ilib -e 'ARGV.each { |f| require f }' ./test/smartystreets_ruby_sdk/test*.rb ./test/smartystreets_ruby_sdk/us_street/test*.rb ./test/smartystreets_ruby_sdk/us_zipcode/test*.rb

data/Vagrantfile

@@ -4,10 +4,12 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
   config.vm.box = "boxcutter/ubuntu1404"
   config.vm.synced_folder "~/.identity", "/home/vagrant/.identity", create: true
   config.vm.synced_folder "~/.gnupg", "/home/vagrant/.gnupg", create: true
-  config.vm.provision "shell", path: "https://s3-us-west-1.amazonaws.com/raptr-us-west-1/bootstrap"
 
   # box-specific
-  config.vm.provision "shell", inline: "apt-get install -y ruby"
+  config.vm.provision "shell", inline: "apt-get update"
+  config.vm.provision "shell", inline: "apt-get install -y ruby" # Installs ruby 1.9 but we should install ruby 2.4...
+  config.vm.provision "shell", inline: "apt-get install -y ruby git"
+  config.vm.provision "shell", inline: "gem install minitest"
   config.vm.synced_folder "~/.gem", "/home/vagrant/.gem", create: true
 
   config.vm.provider "virtualbox" do |vb|

data/examples/international_example.rb

@@ -0,0 +1,31 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/international_street/lookup'
+
+class InternationalExample
+  Lookup = InternationalStreet::Lookup
+
+  def run
+    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+    credentials = StaticCredentials.new(auth_id, auth_token)
+    client = ClientBuilder.new(credentials).build_international_street_api_client
+
+    lookup = Lookup.new("Rua Padre Antonio D'Angelo 121 Casa Verde, Sao Paulo", 'Brazil')
+    lookup.geocode = true # Must be expressly set to get latitude and longitude.
+
+    candidates = client.send(lookup) # The candidates are also stored in the lookup's 'result' field.
+
+    first_candidate = candidates[0]
+    puts "Address is #{first_candidate.analysis.verification_status}"
+    puts "Address precision: #{first_candidate.analysis.address_precision}\n\n"
+    puts "First Line: #{first_candidate.address1}"
+    puts "Second Line: #{first_candidate.address2}"
+    puts "Third Line: #{first_candidate.address3}"
+    puts "Fourth Line: #{first_candidate.address4}"
+    puts "Latitude: #{first_candidate.metadata.latitude}"
+    puts "Longitude: #{first_candidate.metadata.longitude}"
+  end
+end
+
+InternationalExample.new.run

data/examples/us_autocomplete_example.rb

@@ -0,0 +1,38 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/us_autocomplete/lookup'
+
+class USAutocompleteExample
+  Lookup = USAutocomplete::Lookup
+
+  def run
+    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+    credentials = StaticCredentials.new(auth_id, auth_token)
+    client = ClientBuilder.new(credentials).build_us_autocomplete_api_client
+    lookup = Lookup.new('4770 Lincoln Ave O')
+
+    client.send(lookup)
+
+    puts '*** Result with no filter ***'
+    puts
+    lookup.result.each do |suggestion|
+      puts suggestion.text
+    end
+
+    lookup.add_state_filter('IL')
+    lookup.max_suggestions = 5
+
+    suggestions = client.send(lookup) # The client will also return the suggestions directly
+
+    puts
+    puts '*** Result with some filters ***'
+
+    suggestions.each do |suggestion|
+      puts suggestion.text
+    end
+
+  end
+end
+
+USAutocompleteExample.new.run

data/examples/us_extract_example.rb

@@ -0,0 +1,52 @@
+require 'smartystreets_ruby_sdk/static_credentials'
+require 'smartystreets_ruby_sdk/client_builder'
+require 'smartystreets_ruby_sdk/us_extract/lookup'
+
+class USExtractExample
+  Lookup = USExtract::Lookup
+
+  def run
+    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
+    auth_token = ENV['SMARTY_AUTH_TOKEN']
+    credentials = StaticCredentials.new(auth_id, auth_token)
+
+    client = ClientBuilder.new(credentials).build_us_extract_api_client
+
+    text = "Here is some text.\r\nMy address is 3785 Las Vegs Av." \
+           "\r\nLos Vegas, Nevada." \
+           "\r\nMeet me at 1 Rosedale Baltimore Maryland, not at 123 Phony Street, Boise Idaho."
+
+    lookup = Lookup.new(text)
+
+    result = client.send(lookup)
+
+    metadata = result.metadata
+    puts "Found #{metadata.address_count} addresses."
+    puts "#{metadata.verified_count} of them were valid."
+    puts
+
+    addresses = result.addresses
+
+    puts "Addresses: \r\n**********************\r\n"
+    addresses.each do |address|
+      puts "\"#{address.text}\"\n\n"
+      puts "Verified? #{address.verified}"
+      if address.candidates.any?
+        puts("\nMatches:")
+
+        address.candidates.each do |candidate|
+          puts candidate.delivery_line_1
+          puts candidate.last_line
+          puts
+        end
+
+      else
+        puts
+      end
+
+      puts "**********************\n"
+    end
+  end
+end
+
+USExtractExample.new.run

data/examples/us_street_multiple_address_example.rb

@@ -1,41 +1,43 @@
 require 'smartystreets_ruby_sdk/static_credentials'
-require 'smartystreets_ruby_sdk/us_street/client_builder'
+require 'smartystreets_ruby_sdk/client_builder'
 require 'smartystreets_ruby_sdk/us_street/lookup'
 
 class USStreetMultipleAddressExample
+  Lookup = USStreet::Lookup
+
   def run
-    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
+    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables.
     auth_token = ENV['SMARTY_AUTH_TOKEN']
     credentials = StaticCredentials.new(auth_id, auth_token)
 
-    client = USStreet::ClientBuilder.new(credentials).build
+    client = ClientBuilder.new(credentials).build_us_street_api_client
     batch = Batch.new
 
-    batch.add(USStreet::Lookup.new)
+    batch.add(Lookup.new)
     batch[0].street = '1600 amphitheatre parkway'
     batch[0].city = 'Mountain view'
     batch[0].state = 'california'
 
-    batch.add(USStreet::Lookup.new('1 Rosedale, Baltimore, Maryland')) # Freeform addresses work too.
+    batch.add(Lookup.new('1 Rosedale, Baltimore, Maryland')) # Freeform addresses work too.
     batch[1].candidates = 10 # Allows up to ten possible matches to be returned (default is 1).
 
-    batch.add(USStreet::Lookup.new('123 Bogus Street, Pretend Lake, Oklahoma'))
+    batch.add(Lookup.new('123 Bogus Street, Pretend Lake, Oklahoma'))
 
-    batch.add(USStreet::Lookup.new)
+    batch.add(Lookup.new)
     batch[3].street = '1 Infinite Loop'
     batch[3].zipcode = '95014' # You can just input the street and ZIP if you want.
 
     begin
       client.send_batch(batch)
     rescue SmartyException => err
-      print(err)
+      puts err
       return
     end
 
     batch.each_with_index do |lookup, i|
       candidates = lookup.result
 
-      if candidates.length == 0
+      if candidates.empty?
         puts "Address #{i} is invalid.\n\n"
         next
       end

data/examples/us_street_single_address_example.rb

@@ -1,5 +1,5 @@
 require 'smartystreets_ruby_sdk/static_credentials'
-require 'smartystreets_ruby_sdk/us_street/client_builder'
+require 'smartystreets_ruby_sdk/client_builder'
 require 'smartystreets_ruby_sdk/us_street/lookup'
 
 class USStreetSingleAddressExample
@@ -8,7 +8,7 @@ class USStreetSingleAddressExample
     auth_token = ENV['SMARTY_AUTH_TOKEN']
     credentials = StaticCredentials.new(auth_id, auth_token)
 
-    client = USStreet::ClientBuilder.new(credentials).build
+    client = ClientBuilder.new(credentials).build_us_street_api_client
 
     lookup = USStreet::Lookup.new
     lookup.street = '1600 Amphitheatre Pkwy'
@@ -24,7 +24,7 @@ class USStreetSingleAddressExample
 
     result = lookup.result
 
-    if result == nil
+    if result nil?
       puts 'No candidates. This means the address is not valid.'
       return
     end

data/examples/us_zipcode_multiple_lookup_example.rb

@@ -1,24 +1,26 @@
 require 'smartystreets_ruby_sdk/static_credentials'
-require 'smartystreets_ruby_sdk/us_zipcode/client_builder'
+require 'smartystreets_ruby_sdk/client_builder'
 require 'smartystreets_ruby_sdk/us_zipcode/lookup'
 
 class USZipcodeMultipleLookupExample
+  Lookup = USZipcode::Lookup
+
   def run
     auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
     auth_token = ENV['SMARTY_AUTH_TOKEN']
     credentials = StaticCredentials.new(auth_id, auth_token)
 
-    client = USZipcode::ClientBuilder.new(credentials).build
+    client = ClientBuilder.new(credentials).build_us_zipcode_api_client
     batch = Batch.new
 
-    batch.add(USZipcode::Lookup.new)
+    batch.add(Lookup.new)
     batch[0].zipcode = '12345' # A Lookup may have a ZIP Code, city and state, or city, state, and ZIP Code
 
-    batch.add(USZipcode::Lookup.new)
+    batch.add(Lookup.new)
     batch[1].city = 'Phoenix'
     batch[1].state = 'Arizona'
 
-    batch.add(USZipcode::Lookup.new('cupertino', 'CA', '95014')) # You can also set these with arguments
+    batch.add(Lookup.new('cupertino', 'CA', '95014')) # You can also set these with arguments
 
 
     begin

data/examples/us_zipcode_single_lookup_example.rb

@@ -1,14 +1,14 @@
 require 'smartystreets_ruby_sdk/static_credentials'
-require 'smartystreets_ruby_sdk/us_zipcode/client_builder'
+require 'smartystreets_ruby_sdk/client_builder'
 require 'smartystreets_ruby_sdk/us_zipcode/lookup'
 
 class UsZipcodeSingleLookupExample
   def run
-    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables
+    auth_id = ENV['SMARTY_AUTH_ID'] # We recommend storing your keys in environment variables.
     auth_token = ENV['SMARTY_AUTH_TOKEN']
     credentials = StaticCredentials.new(auth_id, auth_token)
 
-    client = USZipcode::ClientBuilder.new(credentials).build
+    client = ClientBuilder.new(credentials).build_us_zipcode_api_client
 
     lookup = USZipcode::Lookup.new
     lookup.city = 'Mountain View'

data/lib/smartystreets_ruby_sdk/batch.rb

@@ -10,11 +10,11 @@ class Batch
   end
 
   def add(lookup)
-    return false if is_full
+    return false if full?
 
     @all_lookups.push(lookup)
 
-    return true if lookup.input_id == nil
+    return true if lookup.input_id.nil?
 
     @named_lookups[lookup.input_id] = lookup
     true
@@ -25,10 +25,14 @@ class Batch
     @all_lookups.clear
   end
 
-  def is_full
+  def full?
     size >= MAX_BATCH_SIZE
   end
 
+  def empty?
+    size.zero?
+  end
+
   def size
     @all_lookups.length
   end

data/lib/smartystreets_ruby_sdk/client_builder.rb

@@ -0,0 +1,118 @@
+require_relative 'native_serializer'
+require_relative 'native_sender'
+require_relative 'status_code_sender'
+require_relative 'signing_sender'
+require_relative 'retry_sender'
+require_relative 'url_prefix_sender'
+require_relative 'sleeper'
+require_relative 'logger'
+require_relative 'us_street/client'
+require_relative 'us_zipcode/client'
+require_relative 'us_extract/client'
+require_relative 'us_autocomplete/client'
+require_relative 'international_street/client'
+
+# The ClientBuilder class helps you build a client object for one of the supported SmartyStreets APIs.
+# You can use ClientBuilder's methods to customize settings like maximum retries or timeout duration.
+# These methods are chainable, so you can usually get set up with one line of code.
+class ClientBuilder
+  INTERNATIONAL_STREET_API_URL = 'https://international-street.api.smartystreets.com/verify'.freeze
+  US_AUTOCOMPLETE_API_URL = 'https://us-autocomplete.api.smartystreets.com/suggest'.freeze
+  US_EXTRACT_API_URL = 'https://us-extract.api.smartystreets.com/'.freeze
+  US_STREET_API_URL = 'https://us-street.api.smartystreets.com/street-address'.freeze
+  US_ZIP_CODE_API_URL = 'https://us-zipcode.api.smartystreets.com/lookup'.freeze
+
+  def initialize(signer)
+    @signer = signer
+    @serializer = NativeSerializer.new
+    @http_sender = nil
+    @max_retries = 5
+    @max_timeout = 10000
+    @url_prefix = nil
+  end
+
+  # Sets the maximum number of times to retry sending the request to the API. (Default is 5)
+  #
+  # Returns self to accommodate method chaining.
+  def retry_at_most(max_retries)
+    @max_retries = max_retries
+    self
+  end
+
+  # The maximum time (in milliseconds) to wait for a connection, and also to wait for
+  # the response to be read. (Default is 10000)
+  #
+  # Returns self to accommodate method chaining.
+  def with_max_timeout(max_timeout)
+    @max_timeout = max_timeout
+    self
+  end
+
+  # Default is a series of nested senders. (See build_sender()
+  #
+  # Returns self to accommodate method chaining.
+  def with_sender(sender)
+    @http_sender = sender
+    self
+  end
+
+  # Changes the Serializer from the default.
+  #
+  # Returns self to accommodate method chaining.
+  def with_serializer(serializer)
+    @serializer = serializer
+    self
+  end
+
+  # This may be useful when using a local installation of the SmartyStreets APIs.
+  # base_url is a string that defaults to the URL for the API corresponding to the Client object being built.
+  #
+  # Returns self to accommodate method chaining.
+  def with_base_url(base_url)
+    @url_prefix = base_url
+    self
+  end
+
+  def build_international_street_api_client
+    ensure_url_prefix_not_null(INTERNATIONAL_STREET_API_URL)
+    InternationalStreet::Client.new(build_sender, @serializer)
+  end
+
+  def build_us_autocomplete_api_client
+    ensure_url_prefix_not_null(US_AUTOCOMPLETE_API_URL)
+    USAutocomplete::Client.new(build_sender, @serializer)
+  end
+
+  def build_us_extract_api_client
+    ensure_url_prefix_not_null(US_EXTRACT_API_URL)
+    USExtract::Client.new(build_sender, @serializer)
+  end
+
+  def build_us_street_api_client
+    ensure_url_prefix_not_null(US_STREET_API_URL)
+    USStreet::Client.new(build_sender, @serializer)
+  end
+
+  def build_us_zipcode_api_client
+    ensure_url_prefix_not_null(US_ZIP_CODE_API_URL)
+    USZipcode::Client.new(build_sender, @serializer)
+  end
+
+  def build_sender
+    return @http_sender unless @http_sender.nil?
+
+    sender = NativeSender.new(@max_timeout)
+
+    sender = StatusCodeSender.new(sender)
+
+    sender = SigningSender.new(@signer, sender) unless @signer.nil?
+
+    sender = RetrySender.new(@max_retries, sender, SmartystreetsRubySdk::Sleeper.new, SmartystreetsRubySdk::Logger.new) if @max_retries > 0
+
+    URLPrefixSender.new(@url_prefix, sender)
+  end
+
+  def ensure_url_prefix_not_null(url)
+    @url_prefix = url if @url_prefix.nil?
+  end
+end

data/lib/smartystreets_ruby_sdk/errors.rb

@@ -1,17 +1,25 @@
 BAD_CREDENTIALS = 'Unauthorized: The credentials were provided incorrectly or did not match any existing,
- active credentials.'
+ active credentials.'.freeze
 
 PAYMENT_REQUIRED = 'Payment Required: There is no active subscription
- for the account associated with the credentials submitted with the request.'
+ for the account associated with the credentials submitted with the request.'.freeze
 
-REQUEST_ENTITY_TOO_LARGE = 'Request Entity Too Large: The request body has exceeded the maximum size.'
+FORBIDDEN = 'Because the international service is currently in a limited release phase, only approved accounts' \
+            ' may access the service.'.freeze
+
+REQUEST_ENTITY_TOO_LARGE = 'Request Entity Too Large: The request body has exceeded the maximum size.'.freeze
 
 BAD_REQUEST = 'Bad Request (Malformed Payload): A GET request lacked a street field or the request body of a
- POST request contained malformed JSON.'
+ POST request contained malformed JSON.'.freeze
+
+UNPROCESSABLE_ENTITY = 'GET request lacked required fields.'.freeze
 
 TOO_MANY_REQUESTS = 'When using public "website key" authentication,
-we restrict the number of requests coming from a given source over too short of a time.'
+we restrict the number of requests coming from a given source over too short of a time.'.freeze
+
+INTERNAL_SERVER_ERROR = 'Internal Server Error.'.freeze
 
-INTERNAL_SERVER_ERROR = 'Internal Server Error.'
+SERVICE_UNAVAILABLE = 'Service Unavailable. Try again later.'.freeze
 
-SERVICE_UNAVAILABLE = 'Service Unavailable. Try again later.'
+GATEWAY_TIMEOUT = 'The upstream data provider did not respond in a timely fashion and the request failed. ' \
+                  'A serious, yet rare occurrence indeed.'.freeze