vpndetection 5.9.0 → 5.10.0

data/lib/vpndetection/result.rb

@@ -24,6 +24,15 @@ module VPNDetection
 
     DETAILS = %w[vpn hosting relay tor cdn resproxy dcproxy mobproxy pubproxy].freeze
 
+    # Where the address is, and the AS announcing it: every keyed answer carries
+    # both, each member present, an empty string or AS 0 where nothing is known.
+    LOCATION = %w[
+      continent continent_name country country_name timezone currency_code currency_name currency_symbol
+      flag_emoji flag_unicode
+    ].freeze
+
+    ASN = %w[asn name domain type prefix].freeze
+
     # The response exactly as it came off the wire, with its original names.
     # Frozen, because the cache hands this same object to every later caller of
     # the address.
@@ -66,7 +75,7 @@ module VPNDetection
     end
 
     # Whether the address belongs to a hosting or cloud provider, or nil when
-    # your plan does not include it. Starter and above.
+    # your plan does not include it. Every paid plan.
     def is_hosting
       @raw['is_hosting']
     end
@@ -77,7 +86,7 @@ module VPNDetection
     end
 
     # Whether the address is a privacy relay egress, or nil when your plan does
-    # not include it. Starter and above.
+    # not include it. Free and paid plans.
     def is_relay
       @raw['is_relay']
     end
@@ -88,7 +97,7 @@ module VPNDetection
     end
 
     # Whether the address is a Tor node, or nil when your plan does not include
-    # it. Starter and above.
+    # it. Free and paid plans.
     def is_tor
       @raw['is_tor']
     end
@@ -99,7 +108,7 @@ module VPNDetection
     end
 
     # Whether the address belongs to a CDN, or nil when your plan does not
-    # include it. Starter and above.
+    # include it. Every paid plan.
     def is_cdn
       @raw['is_cdn']
     end
@@ -110,7 +119,7 @@ module VPNDetection
     end
 
     # Whether the address was seen in a residential proxy pool, or nil when your
-    # plan does not include it. Scale and above.
+    # plan does not include it. Every paid plan.
     def is_resproxy
       @raw['is_resproxy']
     end
@@ -121,7 +130,7 @@ module VPNDetection
     end
 
     # Whether the address was seen in a datacenter proxy pool, or nil when your
-    # plan does not include it. Scale and above.
+    # plan does not include it. Every paid plan.
     def is_dcproxy
       @raw['is_dcproxy']
     end
@@ -132,7 +141,7 @@ module VPNDetection
     end
 
     # Whether the address was seen in a mobile proxy pool, or nil when your plan
-    # does not include it. Scale and above.
+    # does not include it. Every paid plan.
     def is_mobproxy
       @raw['is_mobproxy']
     end
@@ -144,7 +153,7 @@ module VPNDetection
 
     # Whether a public proxy, one anyone can connect through, listens on the
     # address or sends its traffic out from it, or nil when your plan does not
-    # include it. Scale and above.
+    # include it. Every paid plan.
     def is_pubproxy
       @raw['is_pubproxy']
     end
@@ -154,42 +163,43 @@ module VPNDetection
       @raw['is_pubproxy'] == true
     end
 
-    # Detail for `is_vpn`: provider, last_seen, and on max confidence and method.
+    # Detail for `is_vpn`: provider, last_seen and confidence. Every paid plan.
+    # `method` is deprecated: no plan is answered with it since 2026-10-20.
     def vpn
       @raw['vpn']
     end
 
-    # Detail for `is_hosting`. Scale and above.
+    # Detail for `is_hosting`. Every paid plan.
     def hosting
       @raw['hosting']
     end
 
-    # Detail for `is_relay`. Scale and above.
+    # Detail for `is_relay`. Free and paid plans.
     def relay
       @raw['relay']
     end
 
-    # Detail for `is_tor`. Scale and above.
+    # Detail for `is_tor`. Free and paid plans.
     def tor
       @raw['tor']
     end
 
-    # Detail for `is_cdn`. Scale and above.
+    # Detail for `is_cdn`. Every paid plan.
     def cdn
       @raw['cdn']
     end
 
-    # Detail for `is_resproxy`. Max only.
+    # Detail for `is_resproxy`. Every paid plan.
     def resproxy
       @raw['resproxy']
     end
 
-    # Detail for `is_dcproxy`. Max only.
+    # Detail for `is_dcproxy`. Every paid plan.
     def dcproxy
       @raw['dcproxy']
     end
 
-    # Detail for `is_mobproxy`. Max only.
+    # Detail for `is_mobproxy`. Every paid plan.
     def mobproxy
       @raw['mobproxy']
     end
@@ -198,11 +208,25 @@ module VPNDetection
     # num_proxies, last_seen and last_usable. num_ports is 0 when the address
     # is only an exit and num_proxies 0 when it is only an entry; last_usable is
     # an empty string when no request through a proxy on the address was
-    # answered. Max only.
+    # answered. Every paid plan.
     def pubproxy
       @raw['pubproxy']
     end
 
+    # Where the address is: continent, country, timezone, the country's
+    # currency and flag, as a wire hash (`result.location['country']`). Free and
+    # paid plans.
+    def location
+      @raw['location']
+    end
+
+    # The AS announcing the address: asn, name, domain, type and prefix, as a
+    # wire hash (`result.asn['name']`), with asn 0 where none does. Free and paid
+    # plans.
+    def asn
+      @raw['asn']
+    end
+
     def to_h
       @raw
     end

data/lib/vpndetection/transport.rb

@@ -86,11 +86,18 @@ module VPNDetection
     # the spec requires. The generated reader raised a RuntimeError, a
     # JSON::ParserError or an ArgumentError for those, none of them retried, and
     # handed an empty or non-object body back as nil, as if it were the answer.
+    #
+    # Every member present is checked against the type the spec gives it, at any
+    # depth, before the answer is handed back: the generated reader converts with
+    # `to_i`, so `"version":"x"` came back as 0 and `"version":"3"` as 3, and it
+    # skips a list member sent as null, so `"versions": null` came back as nil
+    # (5.9.0, measured 2026-10-20).
     def deserialize(response, return_type)
       data = super
-      return data unless data.nil?
+      raise Error.new(:server_error, "the API answered with no #{return_type}", status: response.code) if data.nil?
 
-      raise Error.new(:server_error, "the API answered with no #{return_type}", status: response.code)
+      Transport.check_type!(JSON.parse(response.body.to_s), return_type.to_s, 'the answer')
+      data
     rescue Error
       raise
     rescue StandardError => e
@@ -182,6 +189,7 @@ module VPNDetection
 
       body = parse_object(response)
       begin
+        check_type!(body, 'Entitlement', 'the answer')
         Entitlement.build_from_hash(body)
       rescue StandardError => e
         raise Error.new(:server_error, "could not read the answer as Entitlement: #{e.message}",
@@ -194,15 +202,21 @@ module VPNDetection
       raise Error.from_status(response.code, response.headers, response.body) unless response.success?
 
       body = parse_object(response)
-      return Result.new(body) if lookup_answer?(body)
-
-      raise Error.new(:server_error, 'the answer carried no ip and is_vpn', status: response.code)
+      begin
+        check_type!(body, 'LookupResponse', 'the answer')
+      rescue TypeError => e
+        raise Error.new(:server_error, "could not read the answer as LookupResponse: #{e.message}",
+                        status: response.code)
+      end
+      Result.new(body)
     end
 
-    # Whether a parsed body is a lookup's answer: every plan's carries `ip` and
-    # `is_vpn`, so one without them is a 2xx the call cannot read.
-    def self.lookup_answer?(body)
-      body.is_a?(Hash) && body['ip'].is_a?(String) && [true, false].include?(body['is_vpn'])
+    # Whether a parsed value is the generated `type`: a batch entry that is not
+    # is that address's error alone.
+    def self.conforms?(value, type)
+      check_type!(value, type, 'the entry')
+    rescue TypeError
+      false
     end
 
     # The two maps of a batch answer, each present even when empty. An answer
@@ -269,5 +283,85 @@ module VPNDetection
     end
 
     private_class_method :transport_failure?, :parse_object, :oauth_refusal
+
+    # The members the spec requires of each answer a lookup, a batch, the
+    # entitlement or a database call reads. One that is not nullable must be
+    # there and not null. Every plan's lookup carries `ip` and `is_vpn`, and a
+    # detail's members are as optional as the plan makes them.
+    # test/client_test.rb holds this to spec/openapi.yaml.
+    REQUIRED = {
+      'LookupResponse' => %i[ip is_vpn],
+      'VpnDetail' => [],
+      'ClassDetail' => [],
+      'ProxyDetail' => [],
+      'PubproxyDetail' => [],
+      'Location' => %i[continent continent_name country country_name timezone currency_code currency_name
+                       currency_symbol flag_emoji flag_unicode],
+      'Asn' => %i[asn name domain type prefix],
+      'BatchLookupError' => %i[status error],
+      'Entitlement' => %i[org_id apikey plan usage],
+      'EntitlementApikey' => %i[id expires allowed_cidrs],
+      'EntitlementPlan' => %i[key tier],
+      'EntitlementUsage' => %i[requests quota hard_limit window_start window_end],
+      'DatabaseList' => %i[databases],
+      'Database' => %i[base name summary license_type starts expires renews_at notice_due_at in_term standing
+                       open versions],
+      'DatabaseVersion' => %i[id version formats],
+      'DatabaseFormatSize' => %i[format bytes],
+      'DatabaseMetadata' => %i[id updated entries schema],
+      'DatabaseMetadataColumn' => %i[name type],
+      'DatabaseChecksumsResponse' => %i[id format checksums],
+      'DbChecksums' => %i[md5 sha1 sha256 sha512],
+      'DownloadList' => %i[downloads],
+      'Download' => %i[dataset_id format outcome sample open bytes http_status apikey_id client_ip user_agent
+                       created],
+    }.freeze
+
+    # True when the parsed `value` has the generated `type`, a model's members
+    # recursively; raises TypeError naming where it does not. No list entry or
+    # map value the spec describes may be null: through 5.9.0 one came back as
+    # nil, or as 0 in `size`, and a lookup's `"is_hosting": "yes"` came back as
+    # the answer.
+    def self.check_type!(value, type, where)
+      raise TypeError, "#{where} is null" if value.nil?
+
+      typed =
+        case type
+        when 'String', 'Date', 'Time' then value.is_a?(String)
+        when 'Integer' then value.is_a?(Integer)
+        when 'Float' then value.is_a?(Numeric)
+        when 'Boolean' then [true, false].include?(value)
+        when 'Object' then true
+        when /\AArray<(?<inner>.+)>\z/
+          inner = Regexp.last_match(:inner)
+          value.is_a?(Array) && value.each_with_index.all? { |v, i| check_type!(v, inner, "#{where}[#{i}]") }
+        when /\AHash<String, ?(?<inner>.+)>\z/
+          inner = Regexp.last_match(:inner)
+          value.is_a?(Hash) && value.all? { |k, v| check_type!(v, inner, "#{where}.#{k}") }
+        else
+          model = VPNDetection.const_get(type)
+          if model.respond_to?(:openapi_types)
+            value.is_a?(Hash) && model.openapi_types.all? { |attr, member| check_member!(model, attr, member, value, where) }
+          else
+            value.is_a?(String) # an enum
+          end
+        end
+      return true if typed
+
+      raise TypeError, "#{where} is not a #{type}"
+    end
+
+    # A member absent or null reads as absent, unless the spec requires it and
+    # does not make it nullable.
+    def self.check_member!(model, attr, member, value, where)
+      key = model.attribute_map[attr].to_s
+      return check_type!(value[key], member.to_s, "#{where}.#{key}") unless value[key].nil?
+      return true unless REQUIRED.fetch(model.name.split('::').last).include?(attr)
+      return true if model.openapi_nullable.include?(attr)
+
+      raise TypeError, "#{where}.#{key} is #{value.key?(key) ? 'null' : 'missing'}"
+    end
+
+    private_class_method :check_member!
   end
 end

data/lib/vpndetection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VPNDetection
-  VERSION = '5.9.0'
+  VERSION = '5.10.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 5.9.0
+  version: 5.10.0
 platform: ruby
 authors:
 - Mslm Dev
@@ -78,6 +78,7 @@ files:
 - lib/vpndetection/models/account_user.rb
 - lib/vpndetection/models/apikey_detail.rb
 - lib/vpndetection/models/apikey_list.rb
+- lib/vpndetection/models/asn.rb
 - lib/vpndetection/models/batch_lookup_error.rb
 - lib/vpndetection/models/batch_lookup_request.rb
 - lib/vpndetection/models/batch_lookup_response.rb
@@ -103,6 +104,7 @@ files:
 - lib/vpndetection/models/entitlement_usage.rb
 - lib/vpndetection/models/error_envelope.rb
 - lib/vpndetection/models/identity.rb
+- lib/vpndetection/models/location.rb
 - lib/vpndetection/models/lookup_error.rb
 - lib/vpndetection/models/lookup_response.rb
 - lib/vpndetection/models/oauth_error.rb