Class: VerifIP::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/verifip/client.rb

Overview

Client for the VerifIP IP fraud scoring API.

Examples:

client = VerifIP::Client.new(api_key: "vip_your_key")
result = client.check("185.220.101.1")
puts result.fraud_score  # => 70

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.verifip.com"
DEFAULT_TIMEOUT = 
30
DEFAULT_MAX_RETRIES = 
3
RETRYABLE_STATUSES = 
[429, 500, 502, 503, 504].freeze
USER_AGENT = 
"verifip-ruby/#{VerifIP::VERSION}"

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES) ⇒ Client

Create a new VerifIP client.

Parameters:

  • api_key (String) —

    your VerifIP API key (starts with “vip_”)

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    API base URL (default: api.verifip.com)

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    request timeout in seconds (default: 30)

  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    max retry attempts on 429/5xx (default: 3)

Raises:

  • (ArgumentError) 


33
34
35
36
37
38
39
40
41
42
 
# File 'lib/verifip/client.rb', line 33

def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
  raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?

  @api_key         = api_key
  @base_url        = base_url.chomp("/")
  @timeout         = timeout
  @max_retries     = max_retries
  @rate_limit_info = nil
  @mutex           = Mutex.new
end

Instance Method Details

#assess(ip: "", email: "", phone: "", url: "") ⇒ AssessResponse

Perform a multi-signal risk assessment.

Parameters:

  • ip (String) (defaults to: "") —

    optional IP address

  • email (String) (defaults to: "") —

    optional email address

  • phone (String) (defaults to: "") —

    optional phone number

  • url (String) (defaults to: "") —

    optional URL

Returns:

Raises:

  • (ArgumentError) 


151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/verifip/client.rb', line 151

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

#check(ip) ⇒ CheckResponse

Check a single IP address for fraud risk.

Parameters:

  • ip (String) —

    IPv4 or IPv6 address

Returns:

Raises:



51
52
53
54
55
56
 
# File 'lib/verifip/client.rb', line 51

def check(ip)
  raise ArgumentError, "ip is required" if ip.nil? || ip.empty?

  data = request(:get, "/v1/check?ip=#{URI.encode_uri_component(ip)}", auth: true)
  CheckResponse.from_hash(data)
end

#check_batch(ips) ⇒ BatchResponse

Check multiple IP addresses in a single request.

Requires Starter plan or higher. Maximum 100 IPs per request.

Parameters:

  • ips (Array<String>) —

    list of IPv4/IPv6 addresses (1-100)

Returns:

Raises:

  • (ArgumentError) 


64
65
66
67
68
69
70
71
 
# File 'lib/verifip/client.rb', line 64

def check_batch(ips)
  raise ArgumentError, "ips list is required and cannot be empty" if ips.nil? || ips.empty?
  raise ArgumentError, "Maximum 100 IPs per batch request" if ips.size > 100

  body = JSON.generate({ ips: ips })
  data = request(:post, "/v1/check/batch", body: body, auth: true)
  BatchResponse.from_hash(data)
end

#check_email(email) ⇒ EmailResponse

Check an email address for fraud risk.

Parameters:

  • email (String) —

    email address to check

Returns:

Raises:

  • (ArgumentError) 


85
86
87
88
89
90
 
# File 'lib/verifip/client.rb', line 85

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_phone(phone) ⇒ PhoneResponse

Check a phone number for fraud risk.

Parameters:

  • phone (String) —

    phone number to check

Returns:

Raises:

  • (ArgumentError) 


96
97
98
99
100
101
 
# File 'lib/verifip/client.rb', line 96

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_url(url) ⇒ URLResponse

Check a URL for fraud risk.

Parameters:

  • url (String) —

    URL to check

Returns:

Raises:

  • (ArgumentError) 


107
108
109
110
111
112
 
# File 'lib/verifip/client.rb', line 107

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

#check_whois(ip) ⇒ WHOISResponse

Perform a WHOIS lookup for an IP address.

Parameters:

  • ip (String) —

    IPv4 or IPv6 address

Returns:

Raises:

  • (ArgumentError) 


118
119
120
121
122
123
 
# File 'lib/verifip/client.rb', line 118

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

#health ⇒ HealthResponse

Check API server health status. Does not require authentication.

Returns:



76
77
78
79
 
# File 'lib/verifip/client.rb', line 76

def health
  data = request(:get, "/health", auth: false)
  HealthResponse.from_hash(data)
end

#inspect ⇒ Object 



165
 
# File 'lib/verifip/client.rb', line 165

def inspect = to_s

#rate_limit_info ⇒ RateLimitInfo?

Returns most recently observed rate limit info.

Returns:

  • (RateLimitInfo, nil) —

    most recently observed rate limit info



23
24
25
 
# File 'lib/verifip/client.rb', line 23

def rate_limit_info
  @mutex.synchronize { @rate_limit_info }
end

#report(ip, is_fraud, category: "", comment: "") ⇒ ReportResponse

Submit a fraud report for an IP address.

Parameters:

  • ip (String) —

    IPv4 or IPv6 address

  • is_fraud (Boolean) —

    whether the IP was used for fraud

  • category (String) (defaults to: "") —

    optional fraud category

  • comment (String) (defaults to: "") —

    optional comment

Returns:

Raises:

  • (ArgumentError) 


132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/verifip/client.rb', line 132

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

#to_s ⇒ Object 



164
 
# File 'lib/verifip/client.rb', line 164

def to_s = "VerifIP::Client(base_url=#{@base_url})"