parseapi 0.2.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4c6ab4b71acb2d8fbfd29ee797b05b3c731be5bd57f00df8a3147fadc40b9aa
-  data.tar.gz: 176cf120dac886d1cfdfca1622ad6b0ffc575fc6730606bf43d6c0e9c4562561
+  metadata.gz: 69e639b49f6986257ea0f5cf3b5424867fd563efd4d6762e06657c0349e2071b
+  data.tar.gz: 7212244b17194211f3a5a400a932df526dc4ff6ce04d7fc28ed94ede12486ebd
 SHA512:
-  metadata.gz: d17692b3a20373508da5a33fa90dfbbbdfc7f4c9b8f7d033e305962177c158254e81e09444294e72ea05cea355f3499ddeba3325be697122a52bbe720bc42c82
-  data.tar.gz: 90ad0d41b12be8866972c02bc8b484898b8009237e9d34584689e7d57fa8da836f664e037c3594666240f149364aab0126558b0a75fc08606d828a4fc912c46c
+  metadata.gz: 255d9d9ae3fddb1bd3e35ba6fd5d9fb06a74c8d8a603bd24d29bc558f5d0b2587fdb5a60df2cf2bae3be703234febfa72c61c22e508d72b1e5ebc045eef74ab0
+  data.tar.gz: 6438c6a8761ecb4b5cbb77af884ebfb20b2e755d51f52ce1832d553e845322804b6c4184498eb49203c1d78ecdca608cc263a5a9606bc69cf91c9ea388a2c205

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 parseAPI
+Copyright (c) 2026 ParseAPI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,3 @@
-# parseapi
-
-Official parseAPI client for Ruby.
-
 ```bash
 gem install parseapi
 ```
@@ -34,6 +30,9 @@ parse.postal('SW1A 1AA')
 parse.postal('28202', country: 'US')
 parse.postal_nearby('28202', country: 'US', radius: 40)
 parse.postal_distance('28202', '10001', country: 'US')
+parse.address('1600 Pennsylvania Ave NW, Washington, DC 20500', country: 'US')
+parse.address_search('123 main', country: 'US', postal: '27401')
+parse.company('732829320', country: 'FR')
 parse.city('charlotte', country: 'US')
 parse.city_id('city_mb8mbqrkz8zb')
 parse.city_search('char', country: 'US', limit: 10)
@@ -47,25 +46,36 @@ parse.state_districts('NC', country: 'US')
 parse.district('37081')
 parse.continent('NA')
 parse.continent_countries('NA')
+parse.bloc('EU')
+parse.bloc_countries('SCHENGEN')
 parse.currency('USD')
 parse.currency_rate('USD', 'EUR')
 parse.language('en')
 parse.name('BILLY OSHALL')
 parse.timezone('America/New_York')
+parse.timezone('America/New_York', at: '2026-09-05T15:00', to: 'Europe/London')
+parse.timezone_at(35.2271, -80.8431)
+parse.date('03/04/2026', format: 'mdy')
+parse.date_today(to: '2026-12-25')
 parse.holiday('US', year: 2026)
 parse.holiday_date('US', '2026-12-25')
 parse.elevation(35.2271, -80.8431)
 parse.point(36.0726, -79.792)
 parse.weather(40.7128, -74.006)
+parse.weather(40.7128, -74.006, deep: true, date: '2026-09-01')
 parse.domain('example.com')
+parse.asn('AS13335')
+parse.mac('00:1B:63:84:45:E6')
 parse.mx('example.com')
 parse.useragent(ua_string)
 parse.vin('1HGCM82633A004352')
+parse.tariff('8471.30.01.00', origin: 'CN', deep: true)
+parse.tariff_search('sunglasses')
 parse.emoji('rocket')
 parse.emoji_search('fire')
 ```
 
-Responses are plain hashes, exactly the JSON the API returns.
+Each lookup returns a plain hash with string keys. Related lookups are separate calls, such as `country_states('US')`. Reading the result makes no further requests. New response fields and `nil` values are preserved.
 
 ## Deep
 
@@ -95,11 +105,20 @@ end
 ```ruby
 parse = ParseAPI.new(
   'your-api-key',
-  timeout: 10, # per-attempt timeout in seconds
-  retries: 2   # automatic retries on network errors, 429, and 5xx
+  timeout: 10 # connect, read, and write timeout in seconds
 )
 ```
 
+Ordinary lookups retry network errors and HTTP 429, 500, 502, 503, and 504 up to twice. Carrier, caller, and HLR lookups, plus email and VAT with `deep: true`, make one attempt by default because repeating them can repeat paid usage. Address with `deep: true` also uses one attempt, reserving that behavior for future verification. This does not mean address deep currently has a separate charge.
+
+Pass `retries: 0` to make every lookup a single attempt. An explicit count such as `retries: 2` applies to every lookup, including paid ones. A retried request can count toward usage even when the first response was lost. Omit `retries` or pass `nil` to use the defaults above.
+
+Reuse one client for successive lookups. Call `parse.close` to release its connection when finished. A later lookup opens a new connection. Use a separate client in each concurrent thread.
+
+Network failures raise native Ruby exceptions. An invalid JSON response raises `JSON::ParserError`.
+
+For testing or instrumentation, pass a callable as `transport:`. It receives the URL and request-header hash and returns `[status, lowercase_response_headers, body]`. Custom transports should use the supplied headers and keep redirect following disabled.
+
 Requires Ruby 3.0 or later. Standard library only, zero dependencies.
 
 ## Docs

data/lib/parseapi/client.rb

@@ -1,6 +1,7 @@
 require 'json'
 require 'net/http'
 require 'uri'
+require 'time'
 
 module ParseAPI
 	# Every non-2xx response from the API. Branch on +code+, never on the message.
@@ -22,21 +23,37 @@ module ParseAPI
 		DEFAULT_RETRIES = 2
 		RETRY_STATUS = [429, 500, 502, 503, 504].freeze
 		RETRY_AFTER_CAP = 5.0
+		METERED_CORE = %w[carrier caller hlr litigator reassigned].freeze
 		NETWORK_ERRORS = [
 			Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
 			Net::OpenTimeout, Net::ReadTimeout, IOError, EOFError, SocketError
 		].freeze
 
-		def initialize(api_key = nil, base_url: nil, timeout: nil, retries: nil)
+		def initialize(api_key = nil, base_url: nil, timeout: nil, retries: nil, transport: nil)
 			@api_key = api_key || ENV['PARSEAPI_KEY']
 			raise ArgumentError, 'parseapi: missing API key. Pass one or set PARSEAPI_KEY.' if @api_key.nil? || @api_key.empty?
 
 			@base_url = URI((base_url || ENV['PARSEAPI_BASE_URL'] || DEFAULT_BASE_URL).sub(%r{/+\z}, ''))
 			@timeout = timeout || DEFAULT_TIMEOUT
-			@retries = retries || DEFAULT_RETRIES
+			@retries = retries
+			raise ArgumentError, 'parseapi: timeout must be a finite positive number.' unless @timeout.is_a?(Numeric) && @timeout.finite? && @timeout > 0
+			raise ArgumentError, 'parseapi: retries must be a non-negative integer or nil.' unless @retries.nil? || (@retries.is_a?(Integer) && @retries >= 0)
+			raise ArgumentError, 'parseapi: transport must be callable.' unless transport.nil? || transport.respond_to?(:call)
+			@transport = transport
 			@http = nil
 		end
 
+		# Release the connection. A later lookup opens a new one.
+		def close
+			@http.finish if @http&.started?
+			@http = nil
+			nil
+		end
+
+		def inspect
+			"#<#{self.class} api_key=[REDACTED] timeout=#{@timeout} retries=#{@retries.nil? ? 'auto' : @retries}>"
+		end
+
 		# --- Lookup methods (one per endpoint, named after the route) ---
 
 		def ip(ip, deep: false)
@@ -91,8 +108,8 @@ module ParseAPI
 			get("/city/id/#{seg(id)}")
 		end
 
-		def city_search(q, country: nil, state: nil, limit: nil)
-			get('/city', q: q, country: country, state: state, limit: limit)
+		def city_search(query, country: nil, state: nil, limit: nil)
+			get('/city', q: query, country: country, state: state, limit: limit)
 		end
 
 		def city_nearest(lat, lon)
@@ -115,6 +132,18 @@ module ParseAPI
 			get("/postal/#{seg(from)}/distance/#{seg(to)}", country: country)
 		end
 
+		def address(address, country: nil, deep: false)
+			get("/address/#{seg(address)}", country: country, deep: deep)
+		end
+
+		def address_search(query, country: nil, postal: nil, city: nil, state: nil, ip: nil)
+			get('/address', q: query, country: country, postal: postal, city: city, state: state, ip: ip)
+		end
+
+		def company(number, country: nil, deep: false)
+			get("/company/#{seg(number)}", country: country, deep: deep)
+		end
+
 		def email(email, deep: false)
 			get("/email/#{seg(email)}", deep: deep)
 		end
@@ -151,6 +180,14 @@ module ParseAPI
 			get("/domain/#{seg(domain)}", deep: deep)
 		end
 
+		def asn(asn)
+			get("/asn/#{seg(asn)}")
+		end
+
+		def mac(mac)
+			get("/mac/#{seg(mac)}")
+		end
+
 		def mx(domain)
 			get("/mx/#{seg(domain)}")
 		end
@@ -167,8 +204,8 @@ module ParseAPI
 			get("/tariff/#{seg(code)}", deep: deep, origin: origin)
 		end
 
-		def tariff_search(q)
-			get('/tariff', q: q)
+		def tariff_search(query)
+			get('/tariff', q: query)
 		end
 
 		def currency(code)
@@ -187,8 +224,20 @@ module ParseAPI
 			get("/name/#{seg(name)}")
 		end
 
-		def timezone(id, at: nil)
-			get("/timezone/#{seg(id)}", at: at)
+		def timezone(id, at: nil, to: nil)
+			get("/timezone/#{seg(id)}", at: at, to: to)
+		end
+
+		def timezone_at(lat, lon, at: nil)
+			get('/timezone', lat: lat, lon: lon, at: at)
+		end
+
+		def date(date, format: nil, to: nil)
+			get("/date/#{seg(date)}", format: format, to: to)
+		end
+
+		def date_today(to: nil)
+			get('/date', to: to)
 		end
 
 		def holiday(country, year: nil)
@@ -207,16 +256,16 @@ module ParseAPI
 			get('/point', lat: lat, lon: lon, deep: deep)
 		end
 
-		def weather(lat, lon, deep: false)
-			get('/weather', lat: lat, lon: lon, deep: deep)
+		def weather(lat, lon, deep: false, date: nil)
+			get('/weather', lat: lat, lon: lon, deep: deep, date: date)
 		end
 
 		def emoji(emoji)
 			get("/emoji/#{seg(emoji)}")
 		end
 
-		def emoji_search(q, limit: nil)
-			get('/emoji', q: q, limit: limit)
+		def emoji_search(query, limit: nil)
+			get('/emoji', q: query, limit: limit)
 		end
 
 		private
@@ -226,6 +275,7 @@ module ParseAPI
 		end
 
 		def get(path, params = {}, headers = {})
+			retries = retries_for(path, params)
 			query = params.reject { |_name, value| value.nil? || value == false }
 			uri = @base_url.dup
 			uri.path = path
@@ -236,7 +286,7 @@ module ParseAPI
 				begin
 					status, response_headers, body = execute(uri, request_headers(headers))
 				rescue *NETWORK_ERRORS
-					raise if attempt >= @retries
+					raise if attempt >= retries
 
 					sleep(retry_delay(attempt, nil))
 					attempt += 1
@@ -245,7 +295,7 @@ module ParseAPI
 
 				return JSON.parse(body) if (200..299).cover?(status)
 
-				if RETRY_STATUS.include?(status) && attempt < @retries
+				if RETRY_STATUS.include?(status) && attempt < retries
 					sleep(retry_delay(attempt, response_headers['retry-after']))
 					attempt += 1
 					next
@@ -261,6 +311,8 @@ module ParseAPI
 
 		# Returns [status, headers_hash, body_string]. Overridden in tests.
 		def execute(uri, headers)
+			return @transport.call(uri.to_s, headers) if @transport
+
 			http = connection
 			request = Net::HTTP::Get.new(uri.request_uri)
 			headers.each { |name, value| request[name] = value }
@@ -276,6 +328,9 @@ module ParseAPI
 				@http.use_ssl = @base_url.scheme == 'https'
 				@http.open_timeout = @timeout
 				@http.read_timeout = @timeout
+				@http.write_timeout = @timeout
+				# The client owns retries, including retries: 0.
+				@http.max_retries = 0
 				@http.keep_alive_timeout = 30
 			end
 			@http.start unless @http.started?
@@ -285,11 +340,24 @@ module ParseAPI
 		def retry_delay(attempt, retry_after)
 			if retry_after
 				seconds = Float(retry_after, exception: false)
-				return [seconds, RETRY_AFTER_CAP].min if seconds && seconds >= 0
+				return [seconds, RETRY_AFTER_CAP].min if seconds && seconds.finite? && seconds >= 0
+				begin
+					return [[Time.httpdate(retry_after) - Time.now, 0].max, RETRY_AFTER_CAP].min
+				rescue ArgumentError
+					# Fall back to jitter when the header is not a delay or HTTP date.
+				end
 			end
 			rand * 0.25 * (2**attempt)
 		end
 
+		def retries_for(path, params)
+			return @retries unless @retries.nil?
+
+			product = path.split('/', 3)[1]
+			metered = METERED_CORE.include?(product) || (%w[email vat address].include?(product) && params[:deep] == true)
+			metered ? 0 : DEFAULT_RETRIES
+		end
+
 		def build_error(status, body)
 			parsed = begin
 				JSON.parse(body)

data/lib/parseapi/version.rb

@@ -1,3 +1,3 @@
 module ParseAPI
-	VERSION = '0.2.1'.freeze
+	VERSION = '0.3.2'.freeze
 end

data/lib/parseapi.rb

@@ -1,7 +1,7 @@
 require_relative 'parseapi/version'
 require_relative 'parseapi/client'
 
-# Official parseAPI client for Ruby.
+# Official ParseAPI client for Ruby.
 #
 #   parse = ParseAPI.new('your-api-key')
 #   parse.country('US')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parseapi
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.2
 platform: ruby
 authors:
-- parseAPI
+- ParseAPI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -47,5 +47,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official parseAPI client for Ruby. One key, minimal JSON, fast.
+summary: Official ParseAPI client for Ruby. One key, minimal JSON, fast.
 test_files: []