vpndetection 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d5875418fd7eb25808f8708537f8a17008502cf24bf3ffcd808595f95f5d8d4
-  data.tar.gz: c695e3f997ddb7284324f8c990a910083b183bb6d379046c27258bd4ceeb09d4
+  metadata.gz: 199c0adec648e1556593cb36414f58482fdf2f638f59fad25ca04ee43c0de02c
+  data.tar.gz: f8a7d728594094a46cfcac9ba2306ebd351bc3d80b785eabd1743252a7f6588e
 SHA512:
-  metadata.gz: c69b0dad9c16c852b58d98faf6356a1f19704126f9963605afd002b7b186b7fdec26511219a68a7d111b4e4e718ca2a5a1415f01121046b0fe67a81bc20d8b6e
-  data.tar.gz: 2bc760ccdcf01d2ca3bb02489e4d12dc390af9e077bc35904d0147b24c4761f99632715c9b6c9ae2789cd48041191e644498681e059251ebe4476719e98a83c7
+  metadata.gz: b148e272ab33acca1a14b5523c448411d92882a6069ba183522e223077ed5185854feeca378608d68009abaf08ee9a1bcffada932cb42e006455992d07e98eb7
+  data.tar.gz: a42507f48287500895380ded3951be855dcfd24311933efc9a50e79c3c81a230ab32a9f9378d7de9aa33a9778f4e15c5f5d55e94c0f8f8f60bae519cc51f6ece

data/README.md

@@ -70,7 +70,7 @@ Usage counts against the anniversary of your subscription, not the calendar mont
 
 ### Batch lookup
 
-Look up many addresses at once. Bogons and cached answers are handled locally, and everything else goes to the batch endpoint in chunks of up to 1000 addresses, in parallel:
+Look up as many addresses as you like at once. Bogons and cached answers are handled locally, and everything else goes to the batch endpoint in chunks of up to 1000 addresses, in parallel:
 
 ```ruby
 results = client.lookup_batch(['45.83.91.1', '8.8.8.8', '1.1.1.1'])
@@ -86,10 +86,10 @@ end
 
 Results are keyed by address, in the order you first listed each one, so duplicates in your list collapse into a single entry and one address failing never loses the rest: it carries its error as its value, with the status the API would have given that address on its own.
 
-How many chunks are in flight at once, and how many times a failed chunk is retried, are configurable per call:
+How many chunks are in flight at once, how many times a failed chunk is retried, and how long each chunk's request may take are configurable per call:
 
 ```ruby
-results = client.lookup_batch(many_ips, concurrency: 4, retries: 4)
+results = client.lookup_batch(many_ips, concurrency: 4, retries: 4, timeout: 5)
 ```
 
 ### Caching
@@ -152,6 +152,16 @@ end
 
 Note that `:rate_limited` and `:quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.
 
+### Timeouts and retries
+
+```ruby
+client = VPNDetection::Client.new(timeout: 10, retries: 4)
+
+result = client.lookup('45.83.91.1', timeout: 2, retries: 0)
+```
+
+`timeout` is in seconds and bounds each attempt, body included, so a call that is retried can take longer in total. It defaults to 30 seconds; before 5.2.0 the default was 10, so pass `timeout: 10` to keep that bound. The client's values are defaults: `lookup`, `lookup_batch`, `my_ip` and `my_entitlement` each take `timeout:` and `retries:` for that call alone, and every `client.oauth` method takes `timeout:`. A database download bounds only its connection with it, because a whole transfer can take minutes.
+
 ### Database downloads
 
 If your key carries the `db.download` scope, the licensed databases are available through `client.database`. A license covers a database FAMILY and a download names one of its versions, so the id comes from `versions`:
@@ -167,6 +177,23 @@ bytes = client.database.download_bytes('cdn_ip_v1', 'csvgz')
 
 `download` streams straight to disk, so nothing bigger than a chunk is ever held in memory whatever the database weighs, and it writes through a neighboring `.part` file so a transfer that dies half way leaves no truncated copy behind. `download_url` hands back the time-limited link and follows nothing, for when you want to run the transfer yourself. `download_bytes` holds the whole file in memory, and the catalog runs from `cdn_ip_v1` at 10 KB to `resproxy_ip_90d_v1` at 1.79 GB, so reach for `download` for anything you have not measured.
 
+### Sign in with OAuth (device flow)
+
+A program running on a person's own machine can let them sign in with their browser and pick one of their API keys, instead of asking them to paste one.
+
+```ruby
+client = VPNDetection::Client.new
+device = client.oauth.device_authorization('your-client-id', scope: 'account.read apikeys.read apikeys.reveal')
+puts "Open #{device.verification_uri} and enter #{device.user_code}"
+
+token = client.oauth.poll_device_token('your-client-id', device)
+raise 'no API key was picked' if token.apikey.nil?
+
+keyed = VPNDetection::Client.new(api_key: token.apikey)
+```
+
+`poll_device_token` raises `VPNDetection::OauthAccessDeniedError` when the person refuses and `VPNDetection::OauthExpiredTokenError` when the code expires first. Client IDs are issued on request from support@vpndetection.io, and `client.oauth.revoke('your-client-id', token.refresh_token)` signs the machine out.
+
 ### Absent is not false
 
 Every field beyond `ip` and `is_vpn` is present when your plan includes it and `nil` when it does not. `nil` means "not in your plan"; `false` means "we checked, and no".

data/lib/vpndetection/api/account_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api/api_keys_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api/authorization_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0
@@ -13,10 +13,12 @@ Generator version: 7.25.0
 require 'cgi'
 
 module VPNDetection
+  # @deprecated Since 5.2.0, and removed in the next major. Use {VPNDetection::Client#oauth}.
   class AuthorizationWireApi
     attr_accessor :api_client
 
     def initialize(api_client = ApiClient.default)
+      warn("#{self.class} is deprecated; use VPNDetection::Client#oauth", category: :deprecated)
       @api_client = api_client
     end
     # Authorize
@@ -257,9 +259,9 @@ module VPNDetection
 
     # Revoke
     # RFC 7009. Always answers 200, including for a token that was never valid - an endpoint that distinguished the two would be a way to test whether a stolen string is a live credential.  Revoking a REFRESH token ends the whole authorization and takes its access tokens with it. Revoking an access token affects only that token. 
-    # @param token [String] 
+    # @param token [String] An access token or a refresh token.
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :client_id 
+    # @option opts [String] :client_id Accepted and not checked.
     # @return [Object]
     def oauth_revoke(token, opts = {})
       data, _status_code, _headers = oauth_revoke_with_http_info(token, opts)
@@ -268,9 +270,9 @@ module VPNDetection
 
     # Revoke
     # RFC 7009. Always answers 200, including for a token that was never valid - an endpoint that distinguished the two would be a way to test whether a stolen string is a live credential.  Revoking a REFRESH token ends the whole authorization and takes its access tokens with it. Revoking an access token affects only that token. 
-    # @param token [String] 
+    # @param token [String] An access token or a refresh token.
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :client_id 
+    # @option opts [String] :client_id Accepted and not checked.
     # @return [Array<(Object, Integer, Hash)>] Object data, response status code and response headers
     def oauth_revoke_with_http_info(token, opts = {})
       if @api_client.config.debugging
@@ -329,14 +331,14 @@ module VPNDetection
 
     # Token
     # Three grant types.  `urn:ietf:params:oauth:grant-type:device_code` polls a device authorization. Until the person approves it answers `authorization_pending`; poll faster than `interval` and it answers `slow_down`, which means widen your interval and keep it widened.  `authorization_code` exchanges a code from `/oauth/authorize`, with the `code_verifier` matching the challenge you sent.  `refresh_token` exchanges a refresh token. The presented token is consumed whatever happens next, so store the new one before using it. 
-    # @param grant_type [String] 
+    # @param grant_type [String] &#x60;urn:ietf:params:oauth:grant-type:device_code&#x60;, &#x60;authorization_code&#x60; or &#x60;refresh_token&#x60;.
     # @param client_id [String] 
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :device_code 
-    # @option opts [String] :code 
-    # @option opts [String] :code_verifier 
-    # @option opts [String] :redirect_uri 
-    # @option opts [String] :refresh_token 
+    # @option opts [String] :device_code Required by the device code grant.
+    # @option opts [String] :code Required by the authorization code grant.
+    # @option opts [String] :code_verifier Required by the authorization code grant.
+    # @option opts [String] :redirect_uri Authorization code grant: the &#x60;redirect_uri&#x60; the code was issued against, exactly.
+    # @option opts [String] :refresh_token Required by the refresh token grant.
     # @return [TokenResponse]
     def oauth_token(grant_type, client_id, opts = {})
       data, _status_code, _headers = oauth_token_with_http_info(grant_type, client_id, opts)
@@ -345,14 +347,14 @@ module VPNDetection
 
     # Token
     # Three grant types.  &#x60;urn:ietf:params:oauth:grant-type:device_code&#x60; polls a device authorization. Until the person approves it answers &#x60;authorization_pending&#x60;; poll faster than &#x60;interval&#x60; and it answers &#x60;slow_down&#x60;, which means widen your interval and keep it widened.  &#x60;authorization_code&#x60; exchanges a code from &#x60;/oauth/authorize&#x60;, with the &#x60;code_verifier&#x60; matching the challenge you sent.  &#x60;refresh_token&#x60; exchanges a refresh token. The presented token is consumed whatever happens next, so store the new one before using it. 
-    # @param grant_type [String] 
+    # @param grant_type [String] &#x60;urn:ietf:params:oauth:grant-type:device_code&#x60;, &#x60;authorization_code&#x60; or &#x60;refresh_token&#x60;.
     # @param client_id [String] 
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :device_code 
-    # @option opts [String] :code 
-    # @option opts [String] :code_verifier 
-    # @option opts [String] :redirect_uri 
-    # @option opts [String] :refresh_token 
+    # @option opts [String] :device_code Required by the device code grant.
+    # @option opts [String] :code Required by the authorization code grant.
+    # @option opts [String] :code_verifier Required by the authorization code grant.
+    # @option opts [String] :redirect_uri Authorization code grant: the &#x60;redirect_uri&#x60; the code was issued against, exactly.
+    # @option opts [String] :refresh_token Required by the refresh token grant.
     # @return [Array<(TokenResponse, Integer, Hash)>] TokenResponse data, response status code and response headers
     def oauth_token_with_http_info(grant_type, client_id, opts = {})
       if @api_client.config.debugging

data/lib/vpndetection/api/database_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0
@@ -285,7 +285,7 @@ module VPNDetection
     # History
     # Recent download attempts for this organization, newest first. Refusals are listed too, so a failed transfer can be accounted for. 
     # @param [Hash] opts the optional parameters
-    # @option opts [Integer] :limit  (default to 50)
+    # @option opts [Integer] :limit How many attempts to return. Clamped to 1 through 200. (default to 50)
     # @return [DownloadList]
     def list_downloads(opts = {})
       data, _status_code, _headers = list_downloads_with_http_info(opts)
@@ -295,7 +295,7 @@ module VPNDetection
     # History
     # Recent download attempts for this organization, newest first. Refusals are listed too, so a failed transfer can be accounted for. 
     # @param [Hash] opts the optional parameters
-    # @option opts [Integer] :limit  (default to 50)
+    # @option opts [Integer] :limit How many attempts to return. Clamped to 1 through 200. (default to 50)
     # @return [Array<(DownloadList, Integer, Hash)>] DownloadList data, response status code and response headers
     def list_downloads_with_http_info(opts = {})
       if @api_client.config.debugging
@@ -305,6 +305,10 @@ module VPNDetection
         fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling DatabaseWireApi.list_downloads, must be smaller than or equal to 200.'
       end
 
+      if @api_client.config.client_side_validation && !opts[:'limit'].nil? && opts[:'limit'] < 1
+        fail ArgumentError, 'invalid value for "opts[:"limit"]" when calling DatabaseWireApi.list_downloads, must be greater than or equal to 1.'
+      end
+
       # resource path
       local_var_path = '/api/v1/database/downloads'
 

data/lib/vpndetection/api/entitlement_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api/lookup_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api/organization_wire_api.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api_client.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api_error.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/api_model_base.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/client.rb

@@ -8,7 +8,7 @@ module VPNDetection
   DEFAULT_CACHE_TTL = 3600
   DEFAULT_CONCURRENCY = 8
   DEFAULT_RETRIES = 2
-  DEFAULT_TIMEOUT = 10
+  DEFAULT_TIMEOUT = 30
   # The most addresses POST /batch takes in one call; a larger batch is sent in
   # chunks of this size.
   BATCH_MAX = 1000
@@ -20,6 +20,8 @@ module VPNDetection
   class Client
     # The licensed dataset downloads, for keys that carry the `db.download` scope.
     attr_reader :database
+    # Signing a person in with OAuth, which needs no API key at all.
+    attr_reader :oauth
 
     # @param api_key [String, nil] omit it entirely to use the free tier, which
     #   answers `ip` and `is_vpn` and allows 1000 requests per day per source
@@ -28,6 +30,10 @@ module VPNDetection
     # @param cache_ttl [Numeric] how long an answer stays fresh, in seconds.
     # @param concurrency [Integer] batch requests - chunks of up to 1000 addresses - in flight during a batch.
     # @param retries [Integer] extra attempts for a transient failure.
+    # @param timeout [Numeric] seconds one request may take before it is
+    #   abandoned. Applies per ATTEMPT, so a retried call may take longer in
+    #   total, and every call that takes `retries:` also takes `timeout:` to
+    #   override it. A dataset transfer bounds only its connect phase with it.
     # @param transport [Transport, nil] override the HTTP layer, mostly for tests.
     def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, cache: true,
                    cache_max_size: DEFAULT_CACHE_MAX_SIZE, cache_ttl: DEFAULT_CACHE_TTL,
@@ -40,6 +46,7 @@ module VPNDetection
       @concurrency = concurrency
       @retries = retries
       @database = DatabaseApi.new(@transport, retries: retries)
+      @oauth = OauthApi.new(@transport, retries: retries)
     end
 
     # Whether an address is private, loopback, link-local, documentation,
@@ -57,14 +64,17 @@ module VPNDetection
     #
     # A bogon is answered locally and never reaches the network. Everything else
     # is served, then cached for this instance.
-    def lookup(ip, retries: nil)
+    #
+    # @param retries [Integer, nil] extra attempts, for THIS call only.
+    # @param timeout [Numeric, nil] seconds each attempt may take, for THIS call only.
+    def lookup(ip, retries: nil, timeout: nil)
       return Bogon.result(ip) if Bogon.bogon?(ip)
 
       hit = @cache&.get(ip)
       return hit unless hit.nil?
 
       result = Retries.with_retries(retries || @retries) do
-        Transport.lookup_result(@transport.lookup_request(ip).run)
+        Transport.lookup_result(@transport.lookup_request(ip, timeout: timeout).run)
       end
       @cache&.set(ip, result)
       result
@@ -80,9 +90,9 @@ module VPNDetection
     # Deliberately NOT cached. The cache is keyed by address, and which address
     # this is IS the question: a machine that moves between networks would
     # otherwise be told where it used to be.
-    def my_ip(retries: nil)
+    def my_ip(retries: nil, timeout: nil)
       Retries.with_retries(retries || @retries) do
-        Transport.lookup_result(@transport.myip_request.run)
+        Transport.lookup_result(@transport.myip_request(timeout: timeout).run)
       end
     end
 
@@ -105,9 +115,9 @@ module VPNDetection
     # cached answer is a wrong one within seconds of the next request.
     #
     # @return [Entitlement]
-    def my_entitlement(retries: nil)
+    def my_entitlement(retries: nil, timeout: nil)
       Retries.with_retries(retries || @retries) do
-        Transport.entitlement_result(@transport.entitlement_request.run)
+        Transport.entitlement_result(@transport.entitlement_request(timeout: timeout).run)
       end
     end
 
@@ -122,10 +132,17 @@ module VPNDetection
     # per-entry failure with the status the single lookup would have answered,
     # and a chunk that fails as a whole marks every address in it.
     #
-    # @param concurrency [Integer, nil] chunks in flight, for THIS batch only.
+    # @param concurrency [Integer, nil] chunks in flight, for THIS batch only. Below 1
+    #   is refused as `:bad_request` before any request, since nothing could ever run.
     # @param retries [Integer, nil] extra attempts for a failed chunk, for THIS batch only.
+    # @param timeout [Numeric, nil] seconds each chunk's attempt may take, for THIS batch only.
     # @return [Hash{String => Result, Error}] in the order the addresses were given
-    def lookup_batch(ips, concurrency: nil, retries: nil)
+    def lookup_batch(ips, concurrency: nil, retries: nil, timeout: nil)
+      limit = concurrency || @concurrency
+      unless limit.is_a?(Numeric) && limit >= 1
+        raise Error.new(:bad_request, "concurrency must be at least 1, not #{limit.inspect}")
+      end
+
       addresses = ips.to_a.uniq
       answers = {}
       pending = []
@@ -135,8 +152,7 @@ module VPNDetection
         hit.nil? ? pending << ip : answers[ip] = hit
       end
       unless pending.empty?
-        run_batch(pending.each_slice(BATCH_MAX).to_a, answers,
-                  concurrency || @concurrency, retries || @retries)
+        run_batch(pending.each_slice(BATCH_MAX).to_a, answers, limit, retries || @retries, timeout)
       end
 
       # Reinstated in input order: a hydra settles in completion order, and a
@@ -150,12 +166,12 @@ module VPNDetection
     # would silently cap a per-call concurrency at the client's setting, and
     # would not be safe to drive from two threads either. Each request is one
     # chunk of up to 1000 addresses.
-    def run_batch(chunks, answers, concurrency, retries)
+    def run_batch(chunks, answers, concurrency, retries, timeout)
       hydra = Typhoeus::Hydra.new(max_concurrency: concurrency)
       attempts = Hash.new(0)
 
       enqueue = lambda do |chunk|
-        request = @transport.batch_request(chunk)
+        request = @transport.batch_request(chunk, timeout: timeout)
         request.on_complete do |response|
           outcome = settle(chunk, response, attempts, retries, enqueue)
           answers.merge!(outcome) unless outcome.nil?

data/lib/vpndetection/configuration.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/database_api.rb

@@ -63,11 +63,7 @@ module VPNDetection
       partial = "#{path}.part"
       begin
         url = download_url(id, format)
-        written = Retries.with_retries(@retries) do
-          # Reopened per attempt, so a retry restarts the file rather than
-          # appending a second copy of the body to a half-written one.
-          File.open(partial, 'wb') { |file| stream(url) { |chunk| file.write(chunk) } }
-        end
+        written = File.open(partial, 'wb') { |file| transfer(url) { |chunk| file.write(chunk) } }
         File.rename(partial, path)
       rescue StandardError
         File.delete(partial) if File.exist?(partial)
@@ -84,11 +80,9 @@ module VPNDetection
     # and use {#download} for anything you have not measured.
     def download_bytes(id, format)
       url = download_url(id, format)
-      Retries.with_retries(@retries) do
-        bytes = String.new(encoding: Encoding::BINARY)
-        stream(url) { |chunk| bytes << chunk }
-        bytes
-      end
+      bytes = String.new(encoding: Encoding::BINARY)
+      transfer(url) { |chunk| bytes << chunk }
+      bytes
     end
 
     private
@@ -106,6 +100,20 @@ module VPNDetection
             "invalid value for \"format\", must be one of #{DatabaseFormat.all_vars}"
     end
 
+    # The transfer of a presigned link, retried only while nothing has reached the
+    # block: object storage failing before the body is as transient as any
+    # outage, while a body that dies part way is not fetched again, because the
+    # bytes already handed over cannot be taken back.
+    def transfer(url, &sink)
+      delivered = false
+      Retries.with_retries(@retries, retry_if: -> { !delivered }) do
+        stream(url) do |chunk|
+          delivered = true
+          sink.call(chunk)
+        end
+      end
+    end
+
     # Runs one transfer of a presigned link, handing each chunk to the block, and
     # returns the bytes that reached it.
     #

data/lib/vpndetection/errors.rb

@@ -38,25 +38,26 @@ module VPNDetection
     def self.from_status(status, headers, body, message: nil)
       message ||= message_of(body) || "request failed with status #{status}"
       retry_after = parse_retry_after(header(headers, 'retry-after'))
+      kind = kind_for(status, headers)
 
+      new(kind, message, status: status, retry_after_seconds: kind == :rate_limited ? retry_after : nil)
+    end
+
+    # What a response with this status is, whatever its body says.
+    def self.kind_for(status, headers)
       case status
-      when 429
-        # Present means transient, absent means an allowance is spent. Nothing
-        # else in the response separates the two.
-        if retry_after.nil?
-          new(:quota_exceeded, message, status: status)
-        else
-          new(:rate_limited, message, status: status, retry_after_seconds: retry_after)
-        end
-      when 400 then new(:bad_request, message, status: status)
-      when 401 then new(:unauthorized, message, status: status)
-      when 403 then new(:forbidden, message, status: status)
+      # Present means transient, absent means an allowance is spent. Nothing
+      # else in the response separates the two.
+      when 429 then parse_retry_after(header(headers, 'retry-after')).nil? ? :quota_exceeded : :rate_limited
+      when 400 then :bad_request
+      when 401 then :unauthorized
+      when 403 then :forbidden
       # Every other 4xx is a CLIENT error. Classifying on the RANGE rather than
       # on an enumerated list is what keeps a 404 from a bad dataset id falling
       # through to the retryable server_error default and being retried twice
       # before it fails.
-      when 400..499 then new(:bad_request, message, status: status)
-      else new(:server_error, message, status: status)
+      when 400..499 then :bad_request
+      else :server_error
       end
     end
 
@@ -111,4 +112,44 @@ module VPNDetection
 
     private_class_method :header, :message_of, :parse_retry_after
   end
+
+  # The authorization server refusing an OAuth request: a 4xx whose body names an
+  # RFC 6749 `error` code. Never retryable, whatever the status, because every
+  # code it can carry answers the request as it was made.
+  #
+  # Not `OauthError`: that constant is the generated model of the error body.
+  class OauthRequestError < Error
+    # The `error` code, such as `slow_down` or `invalid_grant`.
+    attr_reader :error_code
+    # `error_description` when the server sent one as a string, otherwise nil.
+    attr_reader :error_description
+
+    # The refusal a response carries, as the most specific class its code has.
+    def self.for_code(error_code, error_description, status:, headers: {})
+      klass = case error_code
+              when 'access_denied' then OauthAccessDeniedError
+              when 'expired_token' then OauthExpiredTokenError
+              else OauthRequestError
+              end
+      klass.new(error_code, error_description, kind: Error.kind_for(status, headers), status: status)
+    end
+
+    def initialize(error_code, error_description = nil, kind: :bad_request, status: nil)
+      super(kind, error_description.nil? ? error_code : "#{error_code}: #{error_description}", status: status)
+      @error_code = error_code
+      @error_description = error_description
+    end
+
+    def retryable?
+      false
+    end
+  end
+
+  # The person refused the sign-in. Their device code is spent.
+  class OauthAccessDeniedError < OauthRequestError; end
+
+  # The device code is no longer valid: it expired, or was already exchanged or
+  # refused. Raised with no status when {OauthApi#poll_device_token} reaches the
+  # code's lifetime before the server says so.
+  class OauthExpiredTokenError < OauthRequestError; end
 end

data/lib/vpndetection/models/account_create_apikey_request.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_created_apikey.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_org.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_org_ref.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_org_wrap.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_rc.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_revealed_apikey.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/account_user.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0

data/lib/vpndetection/models/apikey_detail.rb

@@ -3,7 +3,7 @@
 
 #The VPNDetection API: classify any IP address, and download the databases behind the answers.  See https://docs.vpndetection.io for guides and https://github.com/vpndetection-io for the official client libraries. 
 
-The version of the OpenAPI document: 2026.09.15
+The version of the OpenAPI document: 2026.09.16
 Contact: support@vpndetection.io
 Generated by: https://openapi-generator.tech
 Generator version: 7.25.0