vpndetection 5.0.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa0cdfbbc74c41bcfe5ecb123df7dc02f4d9255229d5b96764cd3046f290004a
-  data.tar.gz: 540b91db33957765bed48ab55b3cacc10dab5b55fa8d8a91d51ad21a3cee86de
+  metadata.gz: 199c0adec648e1556593cb36414f58482fdf2f638f59fad25ca04ee43c0de02c
+  data.tar.gz: f8a7d728594094a46cfcac9ba2306ebd351bc3d80b785eabd1743252a7f6588e
 SHA512:
-  metadata.gz: 020525503bb0410d9c9a79b04230b6ce2956798813583d7dee1dd4f92c3f00cee496a273a5d8a4db240a1661d19674d939e8c0ceb9a2949669c2793eb3170a97
-  data.tar.gz: c0071cc728e2a67f3da1e6c33974ef223bc46e8b96057ea4a013909f408fc781246ba9ec4216ec35bd34001428d004f0d7709ea9957dac2689398b8c27349e15
+  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
 
-You can do batch lookups with a list, which parallelizes requests for you efficiently:
+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'])
@@ -84,12 +84,12 @@ results.each do |ip, result|
 end
 ```
 
-Results are keyed by address, so duplicates in your list collapse into a single request and one address failing never loses the rest.
+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.
 
-Concurrency and other variables 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: 32, 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
@@ -19,6 +19,74 @@ module VPNDetection
     def initialize(api_client = ApiClient.default)
       @api_client = api_client
     end
+    # Batch
+    # Answers up to 1000 addresses in one call. Each distinct string in `ips` is one lookup: it costs exactly what `GET /{ip}` costs for that address and comes back with exactly the fields that call would carry for your plan. Exact duplicates collapse to one entry and one lookup.  Both maps in the answer are keyed by the string you sent, so nothing has to be lined up by position; the `ip` inside each result is the normalized form. An address that could not be answered sits in `errors` with the status and message the single lookup would have given, and never disturbs the others: a string that is not an address is a `400` there, and an allowance that runs out part way through leaves the remaining entries as `429`s.  The call itself fails only for the reasons below, and a `429` on the call always carries `Retry-After`: the batch is admitted or refused whole by the rate limit, so a per-entry `429` is always a spent allowance and never a throttle. 
+    # @param batch_lookup_request [BatchLookupRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [BatchLookupResponse]
+    def lookup_batch(batch_lookup_request, opts = {})
+      data, _status_code, _headers = lookup_batch_with_http_info(batch_lookup_request, opts)
+      data
+    end
+
+    # Batch
+    # Answers up to 1000 addresses in one call. Each distinct string in `ips` is one lookup: it costs exactly what `GET /{ip}` costs for that address and comes back with exactly the fields that call would carry for your plan. Exact duplicates collapse to one entry and one lookup.  Both maps in the answer are keyed by the string you sent, so nothing has to be lined up by position; the `ip` inside each result is the normalized form. An address that could not be answered sits in `errors` with the status and message the single lookup would have given, and never disturbs the others: a string that is not an address is a `400` there, and an allowance that runs out part way through leaves the remaining entries as `429`s.  The call itself fails only for the reasons below, and a `429` on the call always carries `Retry-After`: the batch is admitted or refused whole by the rate limit, so a per-entry `429` is always a spent allowance and never a throttle. 
+    # @param batch_lookup_request [BatchLookupRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(BatchLookupResponse, Integer, Hash)>] BatchLookupResponse data, response status code and response headers
+    def lookup_batch_with_http_info(batch_lookup_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: LookupWireApi.lookup_batch ...'
+      end
+      # verify the required parameter 'batch_lookup_request' is set
+      if @api_client.config.client_side_validation && batch_lookup_request.nil?
+        fail ArgumentError, "Missing the required parameter 'batch_lookup_request' when calling LookupWireApi.lookup_batch"
+      end
+      # resource path
+      local_var_path = '/batch'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(batch_lookup_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'BatchLookupResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['apiKeyQuery', 'bearerAuth', 'apiKeyHeader']
+
+      new_options = opts.merge(
+        :operation => :"LookupWireApi.lookup_batch",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: LookupWireApi#lookup_batch\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
     # Lookup
     # Answers what is known about a single IPv4 or IPv6 address. Which fields come back is decided by the plan behind the presented key; with no key the answer is `ip` and `is_vpn`. 
     # @param ip [String] The IPv4 or IPv6 address to classify.

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,10 @@ 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
 
   # A client for the VPNDetection API.
   #
@@ -17,14 +20,20 @@ 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
     #   address.
     # @param cache [Boolean] pass false to disable caching.
     # @param cache_ttl [Numeric] how long an answer stays fresh, in seconds.
-    # @param concurrency [Integer] in-flight requests during a batch.
+    # @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,
@@ -37,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,
@@ -54,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
@@ -77,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
 
@@ -102,21 +115,34 @@ 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
 
-    # Classify many addresses in parallel.
+    # Classify many addresses in as few requests as possible.
     #
-    # Keyed by address rather than positional, so duplicates in the input
-    # collapse to a single request and the caller never has to line two lists
-    # up. An address that fails carries its error as its value, so one bad entry
-    # cannot lose the rest of the answers.
+    # Bogons are answered locally and cached answers are reused; everything else
+    # goes to the batch endpoint in chunks of up to 1000 addresses, with at most
+    # `concurrency` chunks in flight. Keyed by address rather than positional, so
+    # duplicates in the input collapse to a single entry and the caller never has
+    # to line two lists up. An address that fails carries its error as its value,
+    # so one bad entry cannot lose the rest of the answers: the API reports a
+    # 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. 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 = []
@@ -126,7 +152,7 @@ module VPNDetection
         hit.nil? ? pending << ip : answers[ip] = hit
       end
       unless pending.empty?
-        run_batch(pending, 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
@@ -138,37 +164,58 @@ module VPNDetection
 
     # One hydra per call, sized for THIS call. Reusing an instance-level hydra
     # would silently cap a per-call concurrency at the client's setting, and
-    # would not be safe to drive from two threads either.
-    def run_batch(pending, answers, concurrency, retries)
+    # 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, timeout)
       hydra = Typhoeus::Hydra.new(max_concurrency: concurrency)
       attempts = Hash.new(0)
 
-      enqueue = lambda do |ip|
-        request = @transport.lookup_request(ip)
+      enqueue = lambda do |chunk|
+        request = @transport.batch_request(chunk, timeout: timeout)
         request.on_complete do |response|
-          outcome = settle(ip, response, attempts, retries, enqueue)
-          answers[ip] = outcome unless outcome.nil?
+          outcome = settle(chunk, response, attempts, retries, enqueue)
+          answers.merge!(outcome) unless outcome.nil?
         end
         hydra.queue(request)
       end
 
-      pending.each { |ip| enqueue.call(ip) }
+      chunks.each { |chunk| enqueue.call(chunk) }
       hydra.run
     end
 
-    def settle(ip, response, attempts, retries, enqueue)
-      result = Transport.lookup_result(response)
-      @cache&.set(ip, result)
-      result
+    # One POST /batch, mapped back onto the addresses it was asked about. A
+    # chunk-level failure - the call refused, the transport failing, the retries
+    # exhausted - becomes every address's error, exactly as it would have been
+    # had each been looked up alone.
+    def settle(chunk, response, attempts, retries, enqueue)
+      body = Transport.batch_body(response)
+      chunk.to_h do |ip|
+        answer = batch_answer(ip, body)
+        @cache&.set(ip, answer) if answer.is_a?(Result)
+        [ip, answer]
+      end
     rescue Error => e
-      return e unless e.retryable? && attempts[ip] < retries
+      return chunk.to_h { |ip| [ip, e] } unless e.retryable? && attempts[chunk] < retries
 
-      attempts[ip] += 1
+      attempts[chunk] += 1
       # Sleeping here stalls the whole hydra, which is what a server-supplied
       # delay asks for: it is telling every request to this host to back off.
-      sleep(Retries.delay_for(e, attempts[ip]))
-      enqueue.call(ip)
+      sleep(Retries.delay_for(e, attempts[chunk]))
+      enqueue.call(chunk)
       nil
     end
+
+    # Every address lands in exactly one of `results` and `errors`; an address in
+    # neither is the server breaking its own contract, and is reported as such
+    # rather than lost.
+    def batch_answer(ip, body)
+      if (served = body['results'][ip])
+        Result.new(served)
+      elsif (failed = body['errors'][ip])
+        Error.from_entry(failed['status'], failed['error'])
+      else
+        Error.new(:server_error, "the batch answer did not include #{ip}", status: 200)
+      end
+    end
   end
 end

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.
     #