verifip 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 976d3bc6eb7004ffb3dcec07a331edfe33fc134799ddc67a863e5a56d1d7cd53
-  data.tar.gz: cee1aef34074819ce6226be796ba1e24c34430b586921e7a94bc3da5cae85c03
+  metadata.gz: e99ded51e832b1176e27fad783ead281c84558bc6068281a3c3b0d592bba427a
+  data.tar.gz: 392d5354097484e8300e83aae37861a86a4569f5b629e5511b325591078c89fa
 SHA512:
-  metadata.gz: f54e009ed0b87b3d2fb7c99f0da390dd85d9c14f653c55d160b236d7b428184b213eb90e906849e828abf1df45487a9f97f0a861e2f24cc9bc6939143e0da0cb
-  data.tar.gz: fef5d94aec23f5a6f270670790cdf005e3782f39470cf4e2f86739be1ab93c10740b64ed48cbcf268195938c5d7ea5d4e561a6b9f0579046bd68b8d3c33191e3
+  metadata.gz: d028b0428cfb862608aeaa9ab614c2cb0b0f9f7b1ef65cfb0e0334656aeb619baf415a880750120c7c11e7b09519570c042b4bfd4863e0f664c661e2dcd83d18
+  data.tar.gz: 4403542ed7c9a49ec9d47ce17a847617e7ec95716a90c5fac13fb5a41adf9b1aff38235a5e59d33a3016012cdf7b36359dcd47dc0fda5ee871e432c5cf3a82a9

data/lib/verifip/client.rb

@@ -78,6 +78,89 @@ module VerifIP
       HealthResponse.from_hash(data)
     end
 
+    # Check an email address for fraud risk.
+    #
+    # @param email [String] email address to check
+    # @return [EmailResponse]
+    def check_email(email)
+      raise ArgumentError, "email is required" if email.nil? || email.empty?
+
+      data = request(:get, "/v1/email?email=#{URI.encode_uri_component(email)}", auth: true)
+      EmailResponse.from_hash(data)
+    end
+
+    # Check a phone number for fraud risk.
+    #
+    # @param phone [String] phone number to check
+    # @return [PhoneResponse]
+    def check_phone(phone)
+      raise ArgumentError, "phone is required" if phone.nil? || phone.empty?
+
+      data = request(:get, "/v1/phone?phone=#{URI.encode_uri_component(phone)}", auth: true)
+      PhoneResponse.from_hash(data)
+    end
+
+    # Check a URL for fraud risk.
+    #
+    # @param url [String] URL to check
+    # @return [URLResponse]
+    def check_url(url)
+      raise ArgumentError, "url is required" if url.nil? || url.empty?
+
+      data = request(:get, "/v1/url?url=#{URI.encode_uri_component(url)}", auth: true)
+      URLResponse.from_hash(data)
+    end
+
+    # Perform a WHOIS lookup for an IP address.
+    #
+    # @param ip [String] IPv4 or IPv6 address
+    # @return [WHOISResponse]
+    def check_whois(ip)
+      raise ArgumentError, "ip is required" if ip.nil? || ip.empty?
+
+      data = request(:get, "/v1/whois?ip=#{URI.encode_uri_component(ip)}", auth: true)
+      WHOISResponse.from_hash(data)
+    end
+
+    # Submit a fraud report for an IP address.
+    #
+    # @param ip [String] IPv4 or IPv6 address
+    # @param is_fraud [Boolean] whether the IP was used for fraud
+    # @param category [String] optional fraud category
+    # @param comment [String] optional comment
+    # @return [ReportResponse]
+    def report(ip, is_fraud, category: "", comment: "")
+      raise ArgumentError, "ip is required" if ip.nil? || ip.empty?
+
+      payload = { ip: ip, is_fraud: is_fraud }
+      payload[:category] = category unless category.empty?
+      payload[:comment] = comment unless comment.empty?
+
+      body = JSON.generate(payload)
+      data = request(:post, "/v1/report", body: body, auth: true)
+      ReportResponse.from_hash(data)
+    end
+
+    # Perform a multi-signal risk assessment.
+    #
+    # @param ip [String] optional IP address
+    # @param email [String] optional email address
+    # @param phone [String] optional phone number
+    # @param url [String] optional URL
+    # @return [AssessResponse]
+    def assess(ip: "", email: "", phone: "", url: "")
+      params = []
+      params << "ip=#{URI.encode_uri_component(ip)}" unless ip.empty?
+      params << "email=#{URI.encode_uri_component(email)}" unless email.empty?
+      params << "phone=#{URI.encode_uri_component(phone)}" unless phone.empty?
+      params << "url=#{URI.encode_uri_component(url)}" unless url.empty?
+
+      raise ArgumentError, "at least one parameter is required" if params.empty?
+
+      data = request(:get, "/v1/assess?#{params.join('&')}", auth: true)
+      AssessResponse.from_hash(data)
+    end
+
     def to_s = "VerifIP::Client(base_url=#{@base_url})"
     def inspect = to_s
 

data/lib/verifip/models.rb

@@ -115,6 +115,246 @@ module VerifIP
     def inspect = to_s
   end
 
+  # Response from an email risk check.
+  class EmailResponse
+    FIELDS = %i[
+      request_id email risk_score valid_syntax mx_found is_disposable
+      is_free_provider is_role_based domain_age_days domain
+      signal_breakdown error
+    ].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id       = kwargs.fetch(:request_id, "")
+      @email            = kwargs.fetch(:email, "")
+      @risk_score       = kwargs.fetch(:risk_score, 0)
+      @valid_syntax     = kwargs.fetch(:valid_syntax, false)
+      @mx_found         = kwargs.fetch(:mx_found, false)
+      @is_disposable    = kwargs.fetch(:is_disposable, false)
+      @is_free_provider = kwargs.fetch(:is_free_provider, false)
+      @is_role_based    = kwargs.fetch(:is_role_based, false)
+      @domain_age_days  = kwargs.fetch(:domain_age_days, 0)
+      @domain           = kwargs.fetch(:domain, "")
+      @signal_breakdown = kwargs.fetch(:signal_breakdown, {})
+      @error            = kwargs.fetch(:error, nil)
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "EmailResponse(email=#{@email}, risk_score=#{@risk_score})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
+  # Response from a phone number risk check.
+  class PhoneResponse
+    FIELDS = %i[
+      request_id phone risk_score valid country_code carrier
+      line_type is_voip signal_breakdown error
+    ].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id       = kwargs.fetch(:request_id, "")
+      @phone            = kwargs.fetch(:phone, "")
+      @risk_score       = kwargs.fetch(:risk_score, 0)
+      @valid            = kwargs.fetch(:valid, false)
+      @country_code     = kwargs.fetch(:country_code, "")
+      @carrier          = kwargs.fetch(:carrier, "")
+      @line_type        = kwargs.fetch(:line_type, "")
+      @is_voip          = kwargs.fetch(:is_voip, false)
+      @signal_breakdown = kwargs.fetch(:signal_breakdown, {})
+      @error            = kwargs.fetch(:error, nil)
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def voip? = @is_voip
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "PhoneResponse(phone=#{@phone}, risk_score=#{@risk_score})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
+  # Response from a URL risk check.
+  class URLResponse
+    FIELDS = %i[
+      request_id url risk_score is_phishing is_malware
+      safe_browsing_threat in_phishtank spamhaus_dbl domain_age_days
+      ssl_valid ssl_issuer signal_breakdown error
+    ].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id           = kwargs.fetch(:request_id, "")
+      @url                  = kwargs.fetch(:url, "")
+      @risk_score           = kwargs.fetch(:risk_score, 0)
+      @is_phishing          = kwargs.fetch(:is_phishing, false)
+      @is_malware           = kwargs.fetch(:is_malware, false)
+      @safe_browsing_threat = kwargs.fetch(:safe_browsing_threat, "")
+      @in_phishtank         = kwargs.fetch(:in_phishtank, false)
+      @spamhaus_dbl         = kwargs.fetch(:spamhaus_dbl, false)
+      @domain_age_days      = kwargs.fetch(:domain_age_days, 0)
+      @ssl_valid            = kwargs.fetch(:ssl_valid, false)
+      @ssl_issuer           = kwargs.fetch(:ssl_issuer, "")
+      @signal_breakdown     = kwargs.fetch(:signal_breakdown, {})
+      @error                = kwargs.fetch(:error, nil)
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def phishing? = @is_phishing
+    def malware?  = @is_malware
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "URLResponse(url=#{@url}, risk_score=#{@risk_score})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
+  # Response from a WHOIS lookup.
+  class WHOISResponse
+    FIELDS = %i[
+      request_id ip network_cidr network_name org_name abuse_contact
+      rir allocation_date country_code asn asn_org
+    ].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id      = kwargs.fetch(:request_id, "")
+      @ip              = kwargs.fetch(:ip, "")
+      @network_cidr    = kwargs.fetch(:network_cidr, "")
+      @network_name    = kwargs.fetch(:network_name, "")
+      @org_name        = kwargs.fetch(:org_name, "")
+      @abuse_contact   = kwargs.fetch(:abuse_contact, "")
+      @rir             = kwargs.fetch(:rir, "")
+      @allocation_date = kwargs.fetch(:allocation_date, "")
+      @country_code    = kwargs.fetch(:country_code, "")
+      @asn             = kwargs.fetch(:asn, 0)
+      @asn_org         = kwargs.fetch(:asn_org, "")
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "WHOISResponse(ip=#{@ip}, network_cidr=#{@network_cidr})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
+  # Response from a fraud report submission.
+  class ReportResponse
+    FIELDS = %i[request_id status message].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id = kwargs.fetch(:request_id, "")
+      @status     = kwargs.fetch(:status, "")
+      @message    = kwargs.fetch(:message, "")
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "ReportResponse(status=#{@status}, message=#{@message})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
+  # Response from a multi-signal risk assessment.
+  class AssessResponse
+    FIELDS = %i[request_id overall_risk ip email phone url].freeze
+
+    attr_reader(*FIELDS)
+
+    def initialize(**kwargs)
+      @request_id  = kwargs.fetch(:request_id, "")
+      @overall_risk = kwargs.fetch(:overall_risk, 0)
+      @ip          = kwargs.fetch(:ip, nil)
+      @email       = kwargs.fetch(:email, nil)
+      @phone       = kwargs.fetch(:phone, nil)
+      @url         = kwargs.fetch(:url, nil)
+    end
+
+    def self.from_hash(hash)
+      hash = _symbolize(hash)
+      hash[:ip]    = CheckResponse.from_hash(hash[:ip]) if hash[:ip].is_a?(Hash)
+      hash[:email] = EmailResponse.from_hash(hash[:email]) if hash[:email].is_a?(Hash)
+      hash[:phone] = PhoneResponse.from_hash(hash[:phone]) if hash[:phone].is_a?(Hash)
+      hash[:url]   = URLResponse.from_hash(hash[:url]) if hash[:url].is_a?(Hash)
+      new(**hash.slice(*FIELDS))
+    end
+
+    def to_h
+      FIELDS.each_with_object({}) { |f, h| h[f] = send(f) }
+    end
+
+    def to_s = "AssessResponse(overall_risk=#{@overall_risk})"
+    def inspect = to_s
+
+    def self._symbolize(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+    private_class_method :_symbolize
+  end
+
   # Rate limit information parsed from response headers.
   class RateLimitInfo
     # @return [Integer] maximum requests in the current window

data/lib/verifip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VerifIP
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verifip
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - VerifIP
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec