parseapi 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6598fb8f4a05494418599738f387ab8137099ddb12ac09f63ca42410d6b4b89
-  data.tar.gz: 9de6f2540a617508c1c9a298361db8218e5f0460fb4a03e1e2c04a85179badca
+  metadata.gz: b27f8a145b9ad37ccd82a61e8e175665416036116ed037bb68640d5bd17d3d5c
+  data.tar.gz: 216cee2f23076dbe2cdcb1339313a157356d63cae236c2204d795fa17242cda7
 SHA512:
-  metadata.gz: 2599c0832bed2f4306ac4f1b5eb31a2d4757546a7349178a8c7bd693605ee091b107cec97c2005d0ed002afa9e2758f0b22d86c679fd15efffad1bd6fa0453d4
-  data.tar.gz: 3d6a7f151089a85c0e76624f84cdd788df87a329371669505efd3179ec98c682017248e969072949f3975c70687ae4d9dfc766fec0949211df22a89374c80533
+  metadata.gz: 63b2f6b437f1c2e77b8d39a7da11b497a473616f22ac819cc838253495f1ec2b9b146a5f7f6f89025df9a2bc66e18b58a7037b9156bdfc84bc39116280757df2
+  data.tar.gz: 3fd6e9ef3a55d5c35a7ae693573b17b1fe84aa41936e2836de0def9c1819f0347ee8d49bbff0718d794fc279a26a7b4520d3383805f6e56ca83b6ad806808ec6

data/README.md

@@ -13,7 +13,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.7.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
+This SDK explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
 
 Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
 
@@ -44,6 +44,35 @@ Results are plain data. Pass a returned code or coordinate to another operation
 
 Use `parse.postal('28202', country: 'US', deep: true)` for US ZIP tax references. `deep.tax` names the levy and `deep.tax_rate` is a percentage, so `7.9` means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. `nil` means unknown and `0` means known zero. Country `deep.tax_id_format` and `deep.tax_id_regex` describe registration-number format only. Use `vat` for a metered registration check with `deep` explicitly enabled.
 
+## Company directory
+
+Find candidates, then fetch the profile you selected.
+
+```ruby
+candidates = parse.company_search(query: 'GitLab', country: 'US', limit: 5)
+selected_id = 'co_caczn6wf36hj' # Explicitly chosen after reviewing candidates.
+profile = parse.company_id(selected_id, deep: true)
+unless candidates['next'].nil?
+  next_page = parse.company_search(
+    query: 'GitLab', country: 'US', limit: 5, cursor: candidates['next']
+  )
+end
+coverage = parse.company_coverage
+```
+
+Use at most one selector: `query` for a name, `domain`, `ticker`, or `identifier`; country or exact industry filters also allow discovery without a selector. The API validates selectors and filters. Use `country` to scope candidates, `exchange` with a ticker, and `authority` with an identifier. Search returns `companies` and an opaque `next` cursor. Review candidate identity and match details before choosing a stable Company ID. Pass `next` as `cursor` with the same selector, filters and limit to continue that result set.
+
+Directory profiles are plain JSON data. `deep` belongs to each company in search results and adds legal/reference detail plus nullable `description`, `logo`, `founded`, and the `social_profiles`, `phone_numbers`, `email_addresses`, `domains` and `sources` collections. A logo is a reported URL. `founded` has `value` and `precision`, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
+
+Company directory social profiles contain `platform`, `url` and `handle`; unknown metadata stays null. Phone and email records use `type` for the source-reported purpose. Earlier response fields remain readable by the client.
+
+The recipe requests one candidate page, one explicitly chosen profile and directory coverage, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. `lang` applies to national company-number lookup, while directory calls use the source labels.
+
+Discovery example: `parse.company_search(country: 'US', industry: '0700', industry_type: 'sic')`
+
+Supply `industry` and `industry_type` together. The supported namespace is `sic`, with an exact four-digit string such as `0700`; leading zeros are meaningful. Country-only discovery is also supported. Filters intersect and may narrow an existing selector. Country matches the profile country, not a headquarters or operating-presence claim. Unknown values do not match a requested filter. Filter-only candidates use `match.field: "filters"` and `match.value: null`; reuse the same filters and limit with a returned cursor. Counts describe this directory edition, not complete country coverage.
+
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -53,9 +82,9 @@ parse.ip('8.8.8.8')
 parse.ip_self
 parse.email('hello@gmail.com')
 parse.vat('DE136695976')
-parse.iban('DE89370400440532013000')
-parse.bin('424242')
-parse.npi('1881018208')
+parse.bank('DE89370400440532013000')
+parse.card('424242')
+parse.provider('1881018208')
 parse.phone('+14155552671')
 parse.carrier('+14155552671')
 parse.caller('+14155552671')
@@ -67,6 +96,11 @@ 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.company_id('co_caczn6wf36hj', deep: true)
+parse.company_search(domain: 'about.gitlab.com')
+parse.company_search(ticker: 'GTLB', exchange: 'Nasdaq')
+parse.company_search(identifier: '0001653482', authority: 'sec')
+parse.company_coverage
 parse.city('charlotte', country: 'US')
 parse.city_id('city_mb8mbqrkz8zb')
 parse.city_search('char', country: 'US', limit: 10)
@@ -107,16 +141,18 @@ parse.mx('example.com')
 parse.dns('example.com')
 parse.dns('_dmarc.example.com', type: 'TXT')
 parse.useragent(ua_string)
-parse.vin('1HGCM82633A004352')
-parse.naics('541511')
-parse.naics_search('coffee shop', limit: 5)
+parse.vehicle('1HGCM82633A004352')
+parse.industry('541511')
+parse.industry_search('coffee shop', limit: 5)
 parse.tariff('8471.30.01.00', origin: 'CN', deep: true)
 parse.tariff_search('sunglasses')
 parse.emoji('rocket')
 parse.emoji_search('fire')
 ```
 
-NAICS paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
+The existing NAICS lookup and search methods remain available as compatibility names for Industry.
+
+Industry paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
 
 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.
 
@@ -132,7 +168,7 @@ Choose display names for one request:
 parse.country('DE', lang: 'fr')
 ```
 
-`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, Company and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
+`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, national Company number lookup and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
 
 The next call keeps its usual default unless it also supplies `lang`. Existing `deep` rules still apply. Date `format` and measurement `locale` remain explicit input-parsing controls.
 
@@ -235,6 +271,32 @@ Address search uses context from the form: prefer postal, or city and state. An
 
 HLR reports status at the last check. `live` means assigned and `connected` means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep diagnostics stay within the same metered lookup.
 
+Bank returns core `checks` for input, country, length, structure, checksum and national rules, plus an `issues` list. States are `passed`, `failed`, `not_checked` or `not_supported`. Unsupported national checking is not a failure. `valid` covers the implemented format and checksum rules, not account existence, ownership or payment reachability. Directory names and BICs may be null independently. Older responses may omit `checks` and `issues`, and future states and issue codes remain strings. Pass the original input unchanged so the API can report invalid characters. Deep `account` remains the BBAN remainder.
+
+Bank inputs use `POST /bank` JSON bodies, keeping IBAN and account values out of request URLs. Pass original strings; the server owns normalization and validation. Avoid logging request bodies. IBAN deep can include `directory` with the immutable `edition`, resolved `country` and actual `match` grain (`bank`, `branch`, `prefix` or `none`); it is absent if no directory lookup ran. A match does not prove complete country coverage or payment reachability.
+
+Use country requirements to build supported input fields. US ACH has an explicit helper with no deep option. It checks the routing format/ABA checksum and account-field syntax; `account_checksum` is `not_supported`. It preserves account characters and leading zeros. A nullable bank name is routing-directory identity, not account existence, ownership or ACH eligibility. The examples below are synthetic test inputs, not payment instructions.
+
+```ruby
+parse.bank_requirements('US', format: 'us_ach')
+parse.bank_us_ach(routing: '011000015', account: '0001234567')
+```
+
+## Provider lookup
+
+```ruby
+provider = parse.provider('1881018208')
+profile = parse.provider('1881018208', deep: true)
+```
+
+Pass the original NPI as a string. `valid` checks its format and checksum; `registered` means a match in the stored NPPES snapshot. `active` reflects recorded NPI deactivation, not licensure. `excluded` is an NPI-only OIG LEIE match; `false` is not a complete exclusion clearance. These directory facts do not verify credentials, current practice contact or payment eligibility.
+
+Invalid input returns `valid: false` with unknown provider fields. A checksum-valid number missing from the snapshot returns `registered: false`; unavailable storage remains an API error. Preserve `null` as unknown.
+
+The default pooled lookup includes provider identity, specialty and practice contact where held. Paid `deep` adds `deactivated_at`, `medicare`, `opt_out` and `enrollments` from stored source files, with no separate check meter or live verification. `enrollments: null` means unavailable; `[]` means no enrollment rows are returned. The API omits unrequested `deep` and returns `{}` when requested on Free.
+
+Paid Deep also returns `taxonomies` in published order, with taxonomy code, specialty label, primary flag and provider-reported license number/state, plus `enumerated_at`, `updated_at` and `reactivated_at` record dates. Reported licenses are not verified licenses. Null lists mean unavailable; empty lists mean the edition contains no entries. Core `sources` is available on every plan: NPPES, LEIE, PECOS and opt-out each have nullable edition metadata (`edition`, `published_at`, `through`, `imported_at`). Provider record dates are separate from source publication and completed import dates. Older responses may omit these additions. Edition details remain null until a verified source is served.
+
 ## Deep
 
 Choose enrichment for the question you need answered.
@@ -245,10 +307,11 @@ Choose enrichment for the question you need answered.
 | Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
 | Email | A metered mailbox check with deliverability, catch-all, status, reason and address hints, using included email checks or enabled on-demand usage. |
 | VAT | A metered registry check where supported, using included VAT checks or enabled on-demand usage. |
-| Phone, Time, Date, Currency, Language, Emoji, IBAN, Point | Optional detail in the same pooled request on every plan. |
+| Phone, Time, Date, Currency, Language, Emoji, Bank, Point | Optional detail in the same pooled request on every plan. |
 | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
-| Name, NAICS | Name evidence or the industry definition profile on paid plans. |
-| VIN, NPI, Tariff, Company | The complete product detail bag on paid plans. |
+| Name, Industry | Name evidence or the industry definition profile on paid plans. |
+| NPI | Deactivation date, Medicare enrollment, opt-out and enrollment rows from stored sources on paid plans. Exclusion evidence stays core. |
+| Vehicle, Tariff, Company | The complete product detail bag on paid plans. |
 | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
 | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
 
@@ -267,7 +330,7 @@ ip.dig('deep', 'datacenter') # true, false, or nil
 
 ## Errors
 
-Every non-2xx response raises `ParseAPI::Error` with `status`, `code`, `docs`, and `request_id`. Branch on `code`.
+Every non-2xx response raises `ParseAPI::Error` with `status`, `code`, `docs`, and `request_id`, plus nullable `retry_after` header metadata. Branch on `code`.
 
 ```ruby
 begin
@@ -292,11 +355,13 @@ Ordinary lookups retry network errors and HTTP 429, 500, 502, 503, and 504 up to
 
 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.
 
+Automatic retries honor numeric and HTTP-date `Retry-After` values up to five seconds. A longer server wait returns the original API error immediately, with the raw header in `retry_after`, so the application can schedule a later attempt. Missing or invalid headers use ordinary backoff.
+
 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.
+For testing or instrumentation, pass a callable as `transport:`. For GET it receives the URL and request-header hash. For Bank POST it also receives a third `"POST"` argument and fourth serialized JSON body argument. Accept optional method/body parameters when supplying a custom transport. It 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.
 
@@ -304,12 +369,34 @@ Requires Ruby 3.0 or later. Standard library only, zero dependencies.
 
 Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)
 
-BIN lookup accepts 6-11 digits as a string, including leading zeros. Spaces and hyphens are accepted. `prefix` is the actual longest match and can be shorter than the input. Unknown reference fields are null. `deep` adds an empty object on every plan.
+## Card
+
+Send 2–11 leading digits as a string. Core returns `bin`, `brand`, `brand_name`
+and a CDN SVG `logo`. Brand detection uses reviewed network rules independently
+of issuer records. Unknown or ambiguous prefixes return null brand fields and a
+generic logo; a known network without reviewed artwork also uses the generic logo.
+
+Optional Deep adds `prefix`, `issuer`, `country`, `type` and `prepaid`, included
+in the same pooled request on every plan. Six or more digits enable directory
+matching. Fewer digits return all-null Deep fields. Compare `deep.prefix` with
+`bin`: equal is an exact recorded match; shorter is broader; null is no match.
+The longest row wins, including null fields. `prepaid: null` means unknown, not
+false. This is partial reference data, not card validity or payment acceptance.
 
+```ruby
+card = parse.card("51")
+puts card["logo"]
+details = parse.card("43737400", deep: true)
+issuer = details["deep"]["issuer"]
+```
+
+Leading zeros are preserved. Only ASCII spaces, tabs, CR, LF and hyphens are
+removed; raw input is limited to 64 characters. Invalid prefixes are rejected
+before dispatch, accepted input is forwarded unchanged. Never send a full card number.
 
 ## Optional detail
 
-The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, NAICS and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep` or each `targets` item; only the source has `deep.next_dst`.
 
 ```ruby
 basic = parse.time('America/New_York')
@@ -330,3 +417,5 @@ Pass a public hostname without a scheme, path, port or IP address. Stack returns
 Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.
 
 Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.
+
+Vehicle lookups use `vin` as the input and response field. Existing VIN methods remain available for compatibility.

data/lib/parseapi/client.rb

@@ -6,14 +6,15 @@ require 'time'
 module ParseAPI
 	# Every non-2xx response from the API. Branch on +code+, never on the message.
 	class Error < StandardError
-		attr_reader :status, :code, :docs, :request_id
+		attr_reader :status, :code, :docs, :request_id, :retry_after
 
-		def initialize(status:, code:, message:, docs: nil, request_id: nil)
+		def initialize(status:, code:, message:, docs: nil, request_id: nil, retry_after: nil)
 			super(message)
 			@status = status
 			@code = code
 			@docs = docs
 			@request_id = request_id
+			@retry_after = retry_after
 		end
 	end
 
@@ -155,6 +156,23 @@ module ParseAPI
 			get("/company/#{seg(number)}", country: country, deep: deep, lang: lang)
 		end
 
+		# Fetch a directory profile by its stable Company ID.
+		def company_id(id, deep: false)
+			get("/company/id/#{seg(id)}", deep: deep)
+		end
+
+		# Use at most one selector, or discover by country, industry or selected registration. The API
+		# validates filters; pair the four-digit industry string with industry_type: "sic". Pass a
+		# returned cursor with the same selector and filters. Deep belongs to each result.
+		def company_search(query: nil, domain: nil, ticker: nil, identifier: nil, country: nil, exchange: nil, authority: nil, limit: nil, cursor: nil, deep: false, industry: nil, industry_type: nil)
+			get('/company', q: query, domain: domain, ticker: ticker, identifier: identifier, country: country, exchange: exchange, authority: authority, limit: limit, cursor: cursor, deep: deep, industry: industry, industry_type: industry_type)
+		end
+
+		# Read the directory edition and source coverage.
+		def company_coverage
+			get('/company/directory/coverage')
+		end
+
 		# Parse an email and check its format and domain. Deep explicitly requests a metered
 		# deliverability check. Deep checks use one attempt by default. An explicit retry count can
 		# repeat paid usage.
@@ -173,16 +191,39 @@ module ParseAPI
 			get("/iban/#{seg(iban)}", country: country, deep: deep)
 		end
 
-		# Look up a 6-11 digit card prefix, preserving leading zeros.
 		def bin(bin, deep: false)
 			get("/bin/#{seg(bin)}", deep: deep)
 		end
 
-
 		def npi(npi, deep: false, lang: nil)
 			get("/npi/#{seg(npi)}", deep: deep, lang: lang)
 		end
 
+		def bank(iban, country: nil, deep: false)
+			get("/bank", {}, {}, { iban: iban, country: country, deep: deep }.reject { |_key, value| value.nil? })
+		end
+
+		# Look up a 2-11 digit card prefix, preserving leading zeros.
+		def card(bin, deep: false)
+			raise ArgumentError, 'parseapi: Card requires a 2-11 digit prefix string.' unless bin.is_a?(String) && bin.length <= 64 && /\A[0-9]{2,11}\z/.match?(bin.delete(" \t\r\n-"))
+			get("/card/#{seg(bin)}", deep: deep)
+		end
+
+
+		# US routing/account syntax only; not account or ACH eligibility verification.
+		def bank_us_ach(routing:, account:)
+			get('/bank', {}, {}, { format: 'us_ach', country: 'US', routing: routing, account: account })
+		end
+
+		# Describe accepted fields and check scope, not directory completeness.
+		def bank_requirements(country, format: nil)
+			get('/bank/requirements', country: country, format: format)
+		end
+
+		def provider(npi, deep: false, lang: nil)
+			get("/provider/#{seg(npi)}", deep: deep, lang: lang)
+		end
+
 		# Parse a phone number and its formats. Pass country for national numbers when needed. Deep
 		# adds numbering-plan geography on every plan. Carrier, caller, and HLR are separate metered lookups.
 		def phone(number, country: nil, deep: false)
@@ -240,18 +281,31 @@ module ParseAPI
 			get('/useragent', { deep: deep }, { 'User-Agent' => ua })
 		end
 
+		def vehicle(vin, deep: false)
+			get("/vehicle/#{seg(vin)}", deep: deep)
+		end
+
 		def vin(vin, deep: false)
 			get("/vin/#{seg(vin)}", deep: deep)
 		end
 
 		# US NAICS 2022 definition and hierarchy.
+		# Compatibility names for Industry.
 		def naics(code, deep: false)
-			get("/naics/#{seg(code)}", deep: deep)
+			industry(code, deep: deep)
 		end
 
-		# Keyword search. Limit defaults to 10 and accepts 1-50.
 		def naics_search(query, limit: nil, deep: false)
-			get('/naics', q: query, limit: limit, deep: deep)
+			industry_search(query, limit: limit, deep: deep)
+		end
+
+		def industry(code, deep: false)
+			get("/industry/#{seg(code)}", deep: deep)
+		end
+
+		# Keyword search. Limit defaults to 10 and accepts 1-50.
+		def industry_search(query, limit: nil, deep: false)
+			get('/industry', q: query, limit: limit, deep: deep)
 		end
 
 		# Look up the general US duty schedule line. Paid deep adds units and the special and other
@@ -393,17 +447,22 @@ module ParseAPI
 			URI.encode_www_form_component(value.to_s).gsub('+', '%20')
 		end
 
-		def get(path, params = {}, headers = {})
+		def get(path, params = {}, headers = {}, json = nil)
 			retries = retries_for(path, params)
 			query = params.reject { |_name, value| value.nil? || value == false }
 			uri = @base_url.dup
 			uri.path = path
 			uri.query = URI.encode_www_form(query) unless query.empty?
 
+			encoded = json.nil? ? nil : JSON.generate(json)
 			attempt = 0
 			loop do
 				begin
-					status, response_headers, body = execute(uri, request_headers(headers))
+					status, response_headers, body = if encoded.nil?
+						execute(uri, request_headers(headers))
+					else
+						execute(uri, request_headers(headers.merge('Content-Type' => 'application/json')), 'POST', encoded)
+					end
 				rescue *NETWORK_ERRORS
 					raise if attempt >= retries
 
@@ -414,13 +473,14 @@ module ParseAPI
 
 				return JSON.parse(body) if (200..299).cover?(status)
 
-				if RETRY_STATUS.include?(status) && attempt < retries
-					sleep(retry_delay(attempt, response_headers['retry-after']))
+				retry_after = response_headers['retry-after']
+				if RETRY_STATUS.include?(status) && attempt < retries && (wait = retry_delay(attempt, retry_after))
+					sleep(wait)
 					attempt += 1
 					next
 				end
 
-				raise build_error(status, body)
+				raise build_error(status, body, retry_after)
 			end
 		end
 
@@ -429,12 +489,13 @@ module ParseAPI
 		end
 
 		# Returns [status, headers_hash, body_string]. Overridden in tests.
-		def execute(uri, headers)
-			return @transport.call(uri.to_s, headers) if @transport
+		def execute(uri, headers, method = 'GET', body = nil)
+			return (method == 'GET' ? @transport.call(uri.to_s, headers) : @transport.call(uri.to_s, headers, method, body)) if @transport
 
 			timeout = !@timeout_explicit && uri.path.start_with?('/stack/') ? 35 : @timeout
 			http = connection(timeout)
-			request = Net::HTTP::Get.new(uri.request_uri)
+			request = (method == 'POST' ? Net::HTTP::Post : Net::HTTP::Get).new(uri.request_uri)
+			request.body = body unless body.nil?
 			headers.each { |name, value| request[name] = value }
 			response = http.request(request)
 			header_hash = {}
@@ -459,15 +520,18 @@ 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.finite? && seconds >= 0
+				if /\A[0-9]+(?:\.[0-9]+)?\z/.match?(retry_after.strip)
+					seconds = Float(retry_after, exception: false)
+					return seconds && seconds.finite? && seconds <= RETRY_AFTER_CAP ? seconds : nil
+				end
 				begin
-					return [[Time.httpdate(retry_after) - Time.now, 0].max, RETRY_AFTER_CAP].min
+					seconds = [Time.httpdate(retry_after) - Time.now, 0].max
+					return seconds > RETRY_AFTER_CAP ? nil : seconds
 				rescue ArgumentError
 					# Fall back to jitter when the header is not a delay or HTTP date.
 				end
 			end
-			rand * 0.25 * (2**attempt)
+			rand * [0.25 * (2**[attempt, 5].min), RETRY_AFTER_CAP].min
 		end
 
 		def retries_for(path, params)
@@ -478,7 +542,7 @@ module ParseAPI
 			metered ? 0 : DEFAULT_RETRIES
 		end
 
-		def build_error(status, body)
+		def build_error(status, body, retry_after = nil)
 			parsed = begin
 				JSON.parse(body)
 			rescue JSON::ParserError
@@ -490,7 +554,8 @@ module ParseAPI
 				code: parsed['code'].is_a?(String) ? parsed['code'] : 'unknown_error',
 				message: parsed['message'].is_a?(String) ? parsed['message'] : "Request failed with status #{status}",
 				docs: parsed['docs'].is_a?(String) ? parsed['docs'] : nil,
-				request_id: parsed['request_id'].is_a?(String) ? parsed['request_id'] : nil
+				request_id: parsed['request_id'].is_a?(String) ? parsed['request_id'] : nil,
+				retry_after: retry_after
 			)
 		end
 	end

data/lib/parseapi/version.rb

@@ -1,3 +1,3 @@
 module ParseAPI
-	VERSION = '1.7.0'.freeze
+	VERSION = '1.9.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parseapi
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - ParseAPI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-24 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email: