Class: SmartyStreets::ClientBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/smartystreets_ruby_sdk/client_builder.rb

Overview

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.

Constant Summary collapse

INTERNATIONAL_STREET_API_URL = 
'https://international-street.api.smarty.com/verify'.freeze
INTERNATIONAL_AUTOCOMPLETE_API_URL = 
"https://international-autocomplete.api.smarty.com/v2/lookup".freeze
US_AUTOCOMPLETE_PRO_API_URL = 
'https://us-autocomplete-pro.api.smarty.com/lookup'.freeze
US_AUTOCOMPLETE_API_URL = 
'https://us-autocomplete.api.smarty.com/v2/lookup'.freeze
US_EXTRACT_API_URL = 
'https://us-extract.api.smarty.com/'.freeze
US_STREET_API_URL = 
'https://us-street.api.smarty.com/street-address'.freeze
US_ZIP_CODE_API_URL = 
'https://us-zipcode.api.smarty.com/lookup'.freeze
US_REVERSE_GEO_API_URL = 
'https://us-reverse-geo.api.smarty.com/lookup'.freeze
US_ENRICHMENT_API_URL = 
'https://us-enrichment.api.smarty.com/lookup'.freeze
INTERNATIONAL_POSTAL_CODE_API_URL = 
'https://international-postal-code.api.smarty.com/lookup'.freeze

Instance Method Summary collapse

Constructor Details

#initialize(signer) ⇒ ClientBuilder

Returns a new instance of ClientBuilder.



40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 40

def initialize(signer)
  @signer = signer
  @serializer = NativeSerializer.new
  @http_sender = nil
  @max_retries = 5
  @max_timeout = 10
  @url_prefix = nil
  @proxy = nil
  @header = nil
  @append_headers = {}
  @licenses = %w()
  @debug = nil
  @queries = {}
end

Instance Method Details

#build_international_autocomplete_api_client ⇒ Object 



180
181
182
183
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 180

def build_international_autocomplete_api_client
  ensure_url_prefix_not_null(INTERNATIONAL_AUTOCOMPLETE_API_URL)
  InternationalAutocomplete::Client.new(build_sender, @serializer)
end

#build_international_postal_code_api_client ⇒ Object 



220
221
222
223
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 220

def build_international_postal_code_api_client
  ensure_url_prefix_not_null(INTERNATIONAL_POSTAL_CODE_API_URL)
  InternationalPostalCode::Client.new(build_sender, @serializer)
end

#build_international_street_api_client ⇒ Object

<editor-fold desc=“Build methods”>



175
176
177
178
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 175

def build_international_street_api_client
  ensure_url_prefix_not_null(INTERNATIONAL_STREET_API_URL)
  InternationalStreet::Client.new(build_sender, @serializer)
end

#build_sender ⇒ Object

</editor-fold>



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 227

def build_sender
  if @http_sender
    conflicts = []
    conflicts << 'with_max_timeout' if @max_timeout != 10
    conflicts << 'with_proxy' if @proxy
    conflicts << 'with_debug' if @debug
    raise ArgumentError, "with_sender cannot be combined with: #{conflicts.join(', ')}. These options only apply to the built-in HTTP transport." unless conflicts.empty?
  end
  sender = @http_sender || NativeSender.new(@max_timeout, @proxy, @debug)

  sender = StatusCodeSender.new(sender)

  sender = CustomHeaderSender.new(sender, @header, @append_headers) unless @header.nil?

  sender = SigningSender.new(@signer, sender) unless @signer.nil?

  sender = RetrySender.new(@max_retries, sender, SmartyStreets::Sleeper.new,SmartyStreets::Logger.new) if @max_retries > 0

  sender = LicenseSender.new(sender, @licenses)

  sender = CustomQuerySender.new(sender, @queries)

  URLPrefixSender.new(@url_prefix, sender)
end

#build_us_autocomplete_api_client ⇒ Object 



190
191
192
193
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 190

def build_us_autocomplete_api_client
  ensure_url_prefix_not_null(US_AUTOCOMPLETE_API_URL)
  USAutocomplete::Client.new(build_sender, @serializer)
end

#build_us_autocomplete_pro_api_client ⇒ Object 



185
186
187
188
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 185

def build_us_autocomplete_pro_api_client
  ensure_url_prefix_not_null(US_AUTOCOMPLETE_PRO_API_URL)
  USAutocompletePro::Client.new(build_sender, @serializer)
end

#build_us_enrichment_api_client ⇒ Object 



215
216
217
218
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 215

def build_us_enrichment_api_client
  ensure_url_prefix_not_null(US_ENRICHMENT_API_URL)
  USEnrichment::Client.new(build_sender, @serializer)
end

#build_us_extract_api_client ⇒ Object 



195
196
197
198
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 195

def build_us_extract_api_client
  ensure_url_prefix_not_null(US_EXTRACT_API_URL)
  USExtract::Client.new(build_sender, @serializer)
end

#build_us_reverse_geo_api_client ⇒ Object 



210
211
212
213
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 210

def build_us_reverse_geo_api_client
  ensure_url_prefix_not_null(US_REVERSE_GEO_API_URL)
  USReverseGeo::Client.new(build_sender, @serializer)
end

#build_us_street_api_client ⇒ Object 



200
201
202
203
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 200

def build_us_street_api_client
  ensure_url_prefix_not_null(US_STREET_API_URL)
  USStreet::Client.new(build_sender, @serializer)
end

#build_us_zipcode_api_client ⇒ Object 



205
206
207
208
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 205

def build_us_zipcode_api_client
  ensure_url_prefix_not_null(US_ZIP_CODE_API_URL)
  USZipcode::Client.new(build_sender, @serializer)
end

#ensure_url_prefix_not_null(url) ⇒ Object 



252
253
254
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 252

def ensure_url_prefix_not_null(url)
  @url_prefix = url if @url_prefix.nil?
end

#retry_at_most(max_retries) ⇒ Object

Sets the maximum number of times to retry sending the request to the API. (Default is 5)

Returns self to accommodate method chaining.



58
59
60
61
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 58

def retry_at_most(max_retries)
  @max_retries = max_retries
  self
end

#with_appended_header(key, value, separator) ⇒ Object

Appends the provided value to the existing header value using the specified separator, rather than adding a separate header value. This is useful for single-value headers like User-Agent.

Returns self to accommodate method chaining.



119
120
121
122
123
124
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 119

def with_appended_header(key, value, separator)
  @header = {} if @header.nil?
  @append_headers[key] = separator
  @header[key] = (@header[key] || []).concat([value])
  self
end

#with_base_url(base_url) ⇒ Object

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.



91
92
93
94
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 91

def with_base_url(base_url)
  @url_prefix = base_url
  self
end

#with_custom_comma_separated_query(key, value) ⇒ Object

Allows the caller to specify key and value pair and appends the value to the current value associated with the key, separated by a comma.

Returns self to accommodate method chaining.



146
147
148
149
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 146

def with_custom_comma_separated_query(key, value)
  @queries[key] = [@queries[key], value].compact.join(',')
  self
end

#with_custom_headers(header) ⇒ Object

Allows you to submit custom headers using a Hash. headers is a Hash object.

Returns self to accommodate method chaining.



109
110
111
112
113
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 109

def with_custom_headers(header)
  @header = header
  @append_headers = {}
  self
end

#with_custom_query(key, value) ⇒ Object

Allows the caller to specify key and value pair that is added to the request query.

Returns self to accommodate method chaining.



137
138
139
140
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 137

def with_custom_query(key, value)
  @queries[key] = value
  self
end

#with_debug ⇒ Object

Enables debug mode, which will print information about the HTTP request and response to $stdout.

Returns self to accommodate method chaining.



168
169
170
171
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 168

def with_debug
  @debug = true
  self
end

#with_feature_component_analysis ⇒ Object

Adds to the request query to use the component analysis feature.

Returns self to accommodate method chaining.



154
155
156
157
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 154

def with_feature_component_analysis()
  self.with_custom_comma_separated_query("features", "component-analysis")
  self
end

#with_feature_iana_time_zone ⇒ Object

with_feature_iana_time_zone turns on the IANA timezone feature for the request.



160
161
162
163
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 160

def with_feature_iana_time_zone()
  self.with_custom_comma_separated_query("features", "iana-timezone")
  self
end

#with_licenses(licenses) ⇒ Object

Allows the caller to specify the subscription license (aka “track”) they wish to use.

Returns self to accommodate method chaining.



129
130
131
132
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 129

def with_licenses(licenses)
  @licenses.concat licenses
  self
end

#with_max_timeout(max_timeout) ⇒ Object

The maximum time (in seconds) to wait for the response to be read. (Default is 10)

Returns self to accommodate method chaining.



66
67
68
69
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 66

def with_max_timeout(max_timeout)
  @max_timeout = max_timeout
  self
end

#with_proxy(host, port, username, password) ⇒ Object

Assigns a proxy through which all requests will be sent. proxy is a Proxy object from this module.

Returns self to accommodate method chaining.



100
101
102
103
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 100

def with_proxy(host, port, username, password)
  @proxy = SmartyStreets::Proxy.new(host, port, username, password)
  self
end

#with_sender(sender) ⇒ Object

Sets the innermost HTTP transport sender while keeping the full middleware chain intact.

Returns self to accommodate method chaining.



74
75
76
77
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 74

def with_sender(sender)
  @http_sender = sender
  self
end

#with_serializer(serializer) ⇒ Object

Changes the Serializer from the default.

Returns self to accommodate method chaining.



82
83
84
85
 
# File 'lib/smartystreets_ruby_sdk/client_builder.rb', line 82

def with_serializer(serializer)
  @serializer = serializer
  self
end