Class: Masklen::Client

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

Overview

Client is the main entry point for the masklen.dev IP intelligence API.

Usage:

client = Masklen::Client.new(api_key: "your-key")
result = client.lookup("8.8.8.8")
puts result.location.country

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://masklen.dev"

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: DEFAULT_BASE_URL) ⇒ Client

Create a new client.

api_key - Your masklen.dev API key (required). base_url - Override the default base URL (optional, useful for testing).

Raises:

  • (ArgumentError) 


19
20
21
22
23
24
 
# File 'lib/masklen/client.rb', line 19

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

  @api_key  = api_key
  @base_url = base_url.chomp("/")
end

Instance Method Details

#lookup(ip, fields: nil) ⇒ Object

Look up a specific IPv4 or IPv6 address.

ip - The IP address string to look up. fields - Optional array of field groups to include in the response,

e.g. ["location", "privacy"]. When nil, the API returns all fields.

Returns a LookupResult. Raises Masklen::Error on API errors.

Raises:

  • (ArgumentError) 


34
35
36
37
38
39
40
 
# File 'lib/masklen/client.rb', line 34

def lookup(ip, fields: nil)
  raise ArgumentError, "ip is required" if ip.nil? || ip.to_s.strip.empty?

  query = build_fields_query(fields)
  hash  = request(:get, "/v1/lookup/#{URI.encode_www_form_component(ip.to_s)}", query: query)
  LookupResult.from_hash(hash)
end

#lookup_batch(ips, fields: nil) ⇒ Object

Look up up to 1000 IP addresses in a single request.

ips - Array of IP address strings (max 1000). fields - Optional array of field groups to include in the response.

Returns a BatchResult whose results array contains LookupResult or BatchItemError objects. Raises Masklen::Error on API errors.

Raises:

  • (ArgumentError) 


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

def lookup_batch(ips, fields: nil)
  raise ArgumentError, "ips must be an Array" unless ips.is_a?(Array)
  raise ArgumentError, "ips cannot be empty"  if ips.empty?
  raise ArgumentError, "ips cannot exceed 1000 entries" if ips.length > 1000

  query = build_fields_query(fields)
  body  = JSON.generate({ "ips" => ips })
  hash  = request(:post, "/v1/lookup/batch", query: query, body: body)
  BatchResult.from_hash(hash)
end

#lookup_self(fields: nil) ⇒ Object

Look up the caller’s own IP address (as seen by the API server).

fields - Optional array of field groups to include in the response.

Returns a LookupResult. Raises Masklen::Error on API errors.



48
49
50
51
52
 
# File 'lib/masklen/client.rb', line 48

def lookup_self(fields: nil)
  query = build_fields_query(fields)
  hash  = request(:get, "/v1/lookup", query: query)
  LookupResult.from_hash(hash)
end