smartystreets_ruby_sdk 10.0.0 → 10.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dfe1e04d687c3c2b33c116f12115c921092875761773196e70b05686642147d
-  data.tar.gz: c48c629d5c11195f679fe264b0fe4557e0fc78355e8f51b3ff62ebc463f27da8
+  metadata.gz: cb6d942045e702488251e2568a2130c99ded17b618bb2f944ad158f46ea8e5d1
+  data.tar.gz: 52fb7c510cf53f0730847da505e26b98b8c6c7b2bc904acf774533d3486964c3
 SHA512:
-  metadata.gz: 1fdef4159968f9cdfd3a6e67afefc68ffdddbf527bc4331f424410274b27812c1cfce78c18ca81e8a3ccc817d4b0db267513a116c55e182d43e71e8ffee694c8
-  data.tar.gz: 5fc398cc1452df089d87f0f13869b6ead3ebe387a9698d47881a064b498b8a10b992381e5ec26d95626e0dfdceb56ec47833f15e91601a60f6bbb9de513c4a6c
+  metadata.gz: '09b6013d45389218d20f30509f2f5fdf3e1111fa4838dbbe41da354bbc21a92441d64ebdfb0a2c03adf474e4a7ede41f61f50be1bc27a93b501f6836c4013da8'
+  data.tar.gz: de761e143d3ff251d1a174e3e210a308844d9b0c67e11289577b8de050f39e98297648d7fa6417e91c9b23f11d67ad75d5629a9d67f5144087b13d6fc1776278

data/CLAUDE.md

@@ -44,7 +44,7 @@ URLPrefixSender → CustomQuerySender → LicenseSender → RetrySender → Sign
 ```
 `CustomHeaderSender` is only included when custom headers are configured; `RetrySender` only when max_retries > 0.
 
-**Authentication**: Three credential types — `StaticCredentials` (auth-id/auth-token), `SharedCredentials` (website key/hostname), and `BasicAuthCredentials` (basic auth header). Credentials are passed to `ClientBuilder` and injected into the sender chain via `SigningSender`.
+**Authentication**: Three credential types — `StaticCredentials` (auth-id/auth-token), `SharedCredentials` (website key/hostname), and `BasicAuthCredentials` (basic auth header). Credentials are passed to `ClientBuilder` and injected into the sender chain via `SigningSender`. Embedded/website keys are GET-only, so they are not valid for batch (POST) requests or the US Extract API (POST-only): https://www.smarty.com/docs/cloud/authentication
 
 ### Key Components
 

data/examples/international_autocomplete_example.rb

@@ -4,9 +4,11 @@ require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
 require '../lib/smartystreets_ruby_sdk/client_builder'
 require '../lib/smartystreets_ruby_sdk/international_autocomplete/lookup'
 require '../lib/smartystreets_ruby_sdk/international_autocomplete/client'
+require '../lib/smartystreets_ruby_sdk/international_autocomplete/language_mode'
 
 class InternationalAutocompleteExample
   Lookup = SmartyStreets::InternationalAutocomplete::Lookup
+  LanguageMode = SmartyStreets::InternationalAutocomplete::LanguageMode
 
   def run
     # key = 'Your SmartyStreets Auth Key here'
@@ -30,6 +32,7 @@ class InternationalAutocompleteExample
     lookup.locality = "Paris"
     lookup.max_group_results = 5
     lookup.geolocation = true
+    lookup.language = LanguageMode::NATIVE
 
     # lookup.add_custom_parameter('parameter', 'value')
 

data/examples/international_example.rb

@@ -34,6 +34,7 @@ class InternationalExample
     lookup.administrative_area = 'SP'
     lookup.country = 'Brazil'
     lookup.postal_code = '02516-050'
+    # lookup.max_results = 5 # Optional: maximum number of candidates to return
 
     # lookup.add_custom_parameter('parameter', 'value')
 

data/examples/international_postal_code_example.rb

@@ -28,6 +28,8 @@ class InternationalPostalCodeExample
     lookup.administrative_area = 'SP'
     lookup.country = 'Brazil'
     lookup.postal_code = '02516'
+    # lookup.language = SmartyStreets::InternationalPostalCode::LanguageMode::LATIN # Optional: 'native' or 'latin'
+    # lookup.max_results = 10 # Optional: maximum number of candidates to return
 
     results = client.send_lookup(lookup)
 
@@ -44,6 +46,7 @@ class InternationalPostalCodeExample
       display(candidate.administrative_area)
       display(candidate.super_administrative_area)
       display(candidate.postal_code)
+      display(candidate.thoroughfare)
       puts
     end
   end

data/examples/us_extract_example.rb

@@ -1,5 +1,4 @@
 require '../lib/smartystreets_ruby_sdk/static_credentials'
-require '../lib/smartystreets_ruby_sdk/shared_credentials'
 require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
 require '../lib/smartystreets_ruby_sdk/client_builder'
 require '../lib/smartystreets_ruby_sdk/us_extract/lookup'
@@ -10,12 +9,10 @@ class USExtractExample
   Lookup = SmartyStreets::USExtract::Lookup
 
   def run
-    # key = 'Your SmartyStreets Auth Key here'
-    # referer = 'Your host name here'
-    # We recommend storing your secret keys in environment variables instead---it's safer!
-    # key = ENV['SMARTY_AUTH_WEB']
-    # referer = ENV['SMARTY_AUTH_REFERER']
-    # credentials = SmartyStreets::SharedCredentials.new(key, referer)
+    # We recommend storing your secret keys in environment variables.
+    #
+    # The US Extract API is POST-only and embedded keys are restricted to GET, so this
+    # API requires secret keys: https://www.smarty.com/docs/cloud/authentication
 
     id = ENV['SMARTY_AUTH_ID']
     token = ENV['SMARTY_AUTH_TOKEN']

data/examples/us_street_match_strategy_example.rb

@@ -1,5 +1,4 @@
 require '../lib/smartystreets_ruby_sdk/static_credentials'
-require '../lib/smartystreets_ruby_sdk/shared_credentials'
 require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
 require '../lib/smartystreets_ruby_sdk/client_builder'
 require '../lib/smartystreets_ruby_sdk/batch'
@@ -11,7 +10,11 @@ class USStreetLookupsWithMatchStrategyExample
   MatchType = SmartyStreets::USStreet::MatchType
 
   def run
-    # We recommend storing your secret keys in environment variables instead---it's safer!
+    # We recommend storing your secret keys in environment variables.
+    #
+    # Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so
+    # batches require secret keys: https://www.smarty.com/docs/cloud/authentication
+
     id = ENV['SMARTY_AUTH_ID']
     token = ENV['SMARTY_AUTH_TOKEN']
     credentials = SmartyStreets::BasicAuthCredentials.new(id, token)

data/examples/us_street_multiple_address_example.rb

@@ -1,5 +1,4 @@
 require '../lib/smartystreets_ruby_sdk/static_credentials'
-require '../lib/smartystreets_ruby_sdk/shared_credentials'
 require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
 require '../lib/smartystreets_ruby_sdk/client_builder'
 require '../lib/smartystreets_ruby_sdk/batch'
@@ -10,12 +9,10 @@ class USStreetMultipleAddressExample
   Lookup = SmartyStreets::USStreet::Lookup
 
   def run
-    # key = 'Your SmartyStreets Auth Key here'
-    # referer = 'Your host name here'
-    # We recommend storing your secret keys in environment variables instead---it's safer!
-    # key = ENV['SMARTY_AUTH_WEB']
-    # referer = ENV['SMARTY_AUTH_REFERER']
-    # credentials = SmartyStreets::SharedCredentials.new(key, referer)
+    # We recommend storing your secret keys in environment variables.
+    #
+    # Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so
+    # batches require secret keys: https://www.smarty.com/docs/cloud/authentication
 
     id = ENV['SMARTY_AUTH_ID']
     token = ENV['SMARTY_AUTH_TOKEN']

data/examples/us_zipcode_multiple_lookup_example.rb

@@ -1,5 +1,4 @@
 require '../lib/smartystreets_ruby_sdk/static_credentials'
-require '../lib/smartystreets_ruby_sdk/shared_credentials'
 require '../lib/smartystreets_ruby_sdk/basic_auth_credentials'
 require '../lib/smartystreets_ruby_sdk/client_builder'
 require '../lib/smartystreets_ruby_sdk/batch'
@@ -9,12 +8,10 @@ class USZipcodeMultipleLookupExample
   Lookup = SmartyStreets::USZipcode::Lookup
 
   def run
-    # key = 'Your SmartyStreets Auth Key here'
-    # referer = 'Your host name here'
-    # We recommend storing your secret keys in environment variables instead---it's safer!
-    # key = ENV['SMARTY_AUTH_WEB']
-    # referer = ENV['SMARTY_AUTH_REFERER']
-    # credentials = SmartyStreets::SharedCredentials.new(key, referer)
+    # We recommend storing your secret keys in environment variables.
+    #
+    # Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so
+    # batches require secret keys: https://www.smarty.com/docs/cloud/authentication
 
     id = ENV['SMARTY_AUTH_ID']
     token = ENV['SMARTY_AUTH_TOKEN']

data/lib/smartystreets_ruby_sdk/international_autocomplete/client.rb

@@ -1,6 +1,7 @@
 require_relative '../request'
 require_relative '../exceptions'
 require_relative 'suggestion'
+require_relative 'language_mode'
 
 module SmartyStreets
   module InternationalAutocomplete
@@ -43,6 +44,7 @@ module SmartyStreets
         add_parameter(request, 'geolocation', 'on') if lookup.geolocation
         add_parameter(request, 'include_only_locality', lookup.locality)
         add_parameter(request, 'include_only_postal_code', lookup.postal_code)
+        add_parameter(request, 'language', normalized_language(lookup.language))
 
         for key in lookup.custom_param_hash.keys do
           add_parameter(request, key, lookup.custom_param_hash[key])
@@ -65,6 +67,12 @@ module SmartyStreets
       def add_parameter(request, key, value)
         request.parameters[key] = value unless value.nil? or value.empty?
       end
+
+      def normalized_language(language)
+        return nil if language.nil?
+
+        LanguageMode.from_value(language).value
+      end
     end
   end
 end

data/lib/smartystreets_ruby_sdk/international_autocomplete/language_mode.rb

@@ -0,0 +1,26 @@
+require_relative '../exceptions'
+
+module SmartyStreets
+  module InternationalAutocomplete
+    # A closed set of valid Language values, the closest Ruby equivalent to an enum: a fixed set of frozen
+    # instances rather than an arbitrary string.
+    class LanguageMode < Data.define(:value)
+      NATIVE = new('native')
+      LATIN = new('latin')
+
+      ALL = [NATIVE, LATIN].freeze
+
+      # Resolves a LanguageMode instance or a raw value (eg. from user input or config) into a LanguageMode,
+      # matching 'native'/'latin' regardless of case.
+      def self.from_value(value)
+        return value if value.is_a?(LanguageMode)
+
+        match = ALL.find { |mode| mode.value.casecmp?(value.to_s) }
+        raise SmartyStreets::UnprocessableEntityError,
+              "invalid Language value; must be unset, 'native', or 'latin' (case-insensitive)" if match.nil?
+
+        match
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/international_autocomplete/lookup.rb

@@ -4,9 +4,13 @@ module SmartyStreets
   module InternationalAutocomplete
     # 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.
+    #
+    # @language:: When not set, the output language will match the default for the country.
+    #     When set to language_mode.NATIVE, the results will always be in the language of the output country.
+    #     When set to language_mode.LATIN, the results will always be provided using a Latin character set.
     class Lookup < JSONAble
 
-      attr_accessor :result, :search, :address_id, :country, :max_results, :max_group_results, :geolocation, :locality, :postal_code, :custom_param_hash
+      attr_accessor :result, :search, :address_id, :country, :max_results, :max_group_results, :geolocation, :locality, :postal_code, :language, :custom_param_hash
 
       def initialize(search = nil, address_id = nil, country = nil, max_results = nil, max_group_results = 100, geolocation = false, locality = nil, postal_code = nil, custom_param_hash = nil)
         @result = []
@@ -18,6 +22,7 @@ module SmartyStreets
         @geolocation = geolocation
         @locality = locality
         @postal_code = postal_code
+        @language = nil
         @custom_param_hash = {}
       end
 

data/lib/smartystreets_ruby_sdk/international_autocomplete.rb

@@ -1,6 +1,7 @@
 require_relative './international_autocomplete/lookup'
 require_relative './international_autocomplete/suggestion'
 require_relative './international_autocomplete/client'
+require_relative './international_autocomplete/language_mode'
 
 module SmartyStreets
   module InternationalAutocomplete 

data/lib/smartystreets_ruby_sdk/international_postal_code/candidate.rb

@@ -13,7 +13,8 @@ module SmartyStreets
                   :dependent_locality_name,
                   :double_dependent_locality,
                   :postal_code,
-                  :postal_code_extra
+                  :postal_code_extra,
+                  :thoroughfare
 
       def initialize(obj)
         @input_id = obj['input_id']
@@ -27,6 +28,7 @@ module SmartyStreets
         @double_dependent_locality = obj['double_dependent_locality']
         @postal_code = obj['postal_code']
         @postal_code_extra = obj['postal_code_extra']
+        @thoroughfare = obj['thoroughfare']
       end
     end
   end

data/lib/smartystreets_ruby_sdk/international_postal_code/client.rb

@@ -1,6 +1,8 @@
 require_relative '../request'
 require_relative '../exceptions'
 require_relative 'candidate'
+require_relative 'language_mode'
+require_relative '../max_results'
 
 module SmartyStreets
   module InternationalPostalCode
@@ -35,6 +37,8 @@ module SmartyStreets
         add_parameter(request, 'locality', lookup.locality)
         add_parameter(request, 'administrative_area', lookup.administrative_area)
         add_parameter(request, 'postal_code', lookup.postal_code)
+        add_parameter(request, 'language', normalized_language(lookup.language))
+        add_parameter(request, 'max_results', MaxResults.normalize(lookup.max_results))
 
         request
       end
@@ -53,6 +57,12 @@ module SmartyStreets
       def add_parameter(request, key, value)
         request.parameters[key] = value unless value.nil? or value.empty?
       end
+
+      def normalized_language(language)
+        return nil if language.nil?
+
+        LanguageMode.from_value(language).value
+      end
     end
   end
 end

data/lib/smartystreets_ruby_sdk/international_postal_code/language_mode.rb

@@ -0,0 +1,26 @@
+require_relative '../exceptions'
+
+module SmartyStreets
+  module InternationalPostalCode
+    # A closed set of valid Language values, the closest Ruby equivalent to an enum: a fixed set of frozen
+    # instances rather than an arbitrary string.
+    class LanguageMode < Data.define(:value)
+      NATIVE = new('native')
+      LATIN = new('latin')
+
+      ALL = [NATIVE, LATIN].freeze
+
+      # Resolves a LanguageMode instance or a raw value (eg. from user input or config) into a LanguageMode,
+      # matching 'native'/'latin' regardless of case.
+      def self.from_value(value)
+        return value if value.is_a?(LanguageMode)
+
+        match = ALL.find { |mode| mode.value.casecmp?(value.to_s) }
+        raise SmartyStreets::UnprocessableEntityError,
+              "invalid Language value; must be unset, 'native', or 'latin' (case-insensitive)" if match.nil?
+
+        match
+      end
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/international_postal_code/lookup.rb

@@ -2,9 +2,15 @@ module SmartyStreets
   module InternationalPostalCode
     # Holds the input data for a postal code lookup and the results returned by the API.
     # See https://smartystreets.com/docs/cloud/international-postal-code-api
+    #
+    # @language:: When not set, results are returned using the Latin character set.
+    #     When set to language_mode.NATIVE (JPN only), results are returned in the native character set for that country.
+    #     When set to language_mode.LATIN, results use the Latin character set with accents and other diacritics removed.
+    # @max_results:: Optional. The maximum number of candidates to return. Omitted from the request when unset or 0.
     class Lookup
 
-      attr_accessor :input_id, :country, :locality, :administrative_area, :postal_code, :results
+      attr_accessor :input_id, :country, :locality, :administrative_area, :postal_code, :language, :max_results,
+                    :results
 
       def initialize
         @input_id = nil
@@ -12,6 +18,8 @@ module SmartyStreets
         @locality = nil
         @administrative_area = nil
         @postal_code = nil
+        @language = nil
+        @max_results = nil
         @results = []
       end
     end

data/lib/smartystreets_ruby_sdk/international_postal_code.rb

@@ -1,5 +1,6 @@
 require 'smartystreets_ruby_sdk/international_postal_code/lookup'
 require 'smartystreets_ruby_sdk/international_postal_code/candidate'
 require 'smartystreets_ruby_sdk/international_postal_code/client'
+require 'smartystreets_ruby_sdk/international_postal_code/language_mode'
 
 

data/lib/smartystreets_ruby_sdk/international_street/client.rb

@@ -1,6 +1,7 @@
 require_relative '../request'
 require_relative 'candidate'
 require_relative 'language_mode'
+require_relative '../max_results'
 
 module SmartyStreets
   module InternationalStreet
@@ -57,6 +58,7 @@ module SmartyStreets
         add_parameter(request, 'administrative_area', lookup.administrative_area)
         add_parameter(request, 'postal_code', lookup.postal_code)
         add_parameter(request, 'features', lookup.features)
+        add_parameter(request, 'max_results', MaxResults.normalize(lookup.max_results))
 
         for key in lookup.custom_param_hash.keys do
           add_parameter(request, key, lookup.custom_param_hash[key])

data/lib/smartystreets_ruby_sdk/international_street/lookup.rb

@@ -14,11 +14,12 @@ module SmartyStreets
     # @language:: When not set, the output language will match the language of the input values.
     #     When set to language_mode.NATIVE, the results will always be in the language of the output country.
     #     When set to language_mode.LATIN, the results will always be provided using a Latin character set.
+    # @max_results:: Optional. The maximum number of candidates to return. Omitted from the request when unset or 0.
     class Lookup
 
       attr_accessor :input_id, :freeform, :locality, :postal_code, :address3, :address2, :inputId, :address1,
                     :geocode, :administrative_area, :country, :organization, :language, :address4, :result,
-                    :features, :custom_param_hash
+                    :features, :max_results, :custom_param_hash
 
       def initialize(freeform=nil, country=nil)
         @result = []
@@ -37,6 +38,7 @@ module SmartyStreets
         @administrative_area = nil
         @postal_code = nil
         @features = nil
+        @max_results = nil
         @custom_param_hash = {}
       end
 

data/lib/smartystreets_ruby_sdk/max_results.rb

@@ -0,0 +1,23 @@
+require_relative 'exceptions'
+
+module SmartyStreets
+  # Shared handling for the max_results input: accepts a whole number (or a string holding one),
+  # and returns it as a string only when it is above 0, so it can be sent as a query parameter.
+  # Unset (nil or blank) returns nil; anything that isn't a whole number raises.
+  module MaxResults
+    WHOLE_NUMBER = /\A\s*[+-]?\d+\s*\z/
+
+    def self.normalize(value)
+      return nil if value.nil? || (value.is_a?(String) && value.strip.empty?)
+
+      number = case value
+               when Integer then value
+               when Float then value.to_i if value.finite? && value == value.floor
+               when String then value.to_i if value.match?(WHOLE_NUMBER)
+               end
+      raise SmartyStreets::UnprocessableEntityError, 'invalid max_results value; must be a whole number' if number.nil?
+
+      number.positive? ? number.to_s : nil
+    end
+  end
+end

data/lib/smartystreets_ruby_sdk/version.rb

@@ -1,3 +1,3 @@
 module SmartyStreets
-  VERSION = '10.0.0' # DO NOT EDIT (this is updated by a build job when a new release is published)
+  VERSION = '10.2.0' # DO NOT EDIT (this is updated by a build job when a new release is published)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smartystreets_ruby_sdk
 version: !ruby/object:Gem::Version
-  version: 10.0.0
+  version: 10.2.0
 platform: ruby
 authors:
 - SmartyStreets SDK Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,11 +123,13 @@ files:
 - lib/smartystreets_ruby_sdk/exceptions.rb
 - lib/smartystreets_ruby_sdk/international_autocomplete.rb
 - lib/smartystreets_ruby_sdk/international_autocomplete/client.rb
+- lib/smartystreets_ruby_sdk/international_autocomplete/language_mode.rb
 - lib/smartystreets_ruby_sdk/international_autocomplete/lookup.rb
 - lib/smartystreets_ruby_sdk/international_autocomplete/suggestion.rb
 - lib/smartystreets_ruby_sdk/international_postal_code.rb
 - lib/smartystreets_ruby_sdk/international_postal_code/candidate.rb
 - lib/smartystreets_ruby_sdk/international_postal_code/client.rb
+- lib/smartystreets_ruby_sdk/international_postal_code/language_mode.rb
 - lib/smartystreets_ruby_sdk/international_postal_code/lookup.rb
 - lib/smartystreets_ruby_sdk/international_street.rb
 - lib/smartystreets_ruby_sdk/international_street/analysis.rb
@@ -142,6 +144,7 @@ files:
 - lib/smartystreets_ruby_sdk/json_able.rb
 - lib/smartystreets_ruby_sdk/license_sender.rb
 - lib/smartystreets_ruby_sdk/logger.rb
+- lib/smartystreets_ruby_sdk/max_results.rb
 - lib/smartystreets_ruby_sdk/native_sender.rb
 - lib/smartystreets_ruby_sdk/native_serializer.rb
 - lib/smartystreets_ruby_sdk/proxy.rb