masklen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6079eabf7927a845e4bf6c10badae83dac6e028f2a0e4c7815a8d2745723c295
+  data.tar.gz: 6ee8e4a6f9c0084b979729060d5388d4044bef02c01ace8c2ccab58438506c2f
+SHA512:
+  metadata.gz: 1164448a63590a6869f555a5c0e360938bd4562124eb3d5aacae37c11fbf072bb53e164c0b0eb30de998582802c127ad4164d0b50421d193bac293f4024a4383
+  data.tar.gz: 75f709d8290831b5b68809158c610d4197ceeea85ecc573417d2a943c4296098f12803686f67ecee6dc4036bbbd516d10c07c8384e8c7562e2b94e2ec0fe13ab

data/README.md

@@ -0,0 +1,183 @@
+# masklen
+
+Official Ruby SDK for the [masklen.dev](https://masklen.dev) IP intelligence API.
+
+Look up geolocation, network, privacy, and locale data for any IPv4 or IPv6 address. Zero external dependencies -- uses only Ruby stdlib.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "masklen"
+```
+
+Or install directly:
+
+```sh
+gem install masklen
+```
+
+## Quick start
+
+```ruby
+require "masklen"
+
+client = Masklen::Client.new(api_key: "your-api-key")
+
+# 1. Look up a specific IP address
+result = client.lookup("8.8.8.8")
+puts result.ip                   # "8.8.8.8"
+puts result.location.country     # "United States"
+puts result.network.isp          # "Google LLC"
+puts result.privacy.threat_level # "low"
+
+# 2. Look up your own IP (the caller's IP as seen by the server)
+self_result = client.lookup_self
+puts self_result.location.city
+
+# 3. Batch lookup (up to 1000 IPs per request)
+batch = client.lookup_batch(["8.8.8.8", "1.1.1.1"])
+batch.results.each do |r|
+  if r.is_a?(Masklen::LookupResult)
+    puts "#{r.ip} -> #{r.location&.country}"
+  else
+    # r is a Masklen::BatchItemError
+    puts "#{r.ip} error: #{r.error_message}"
+  end
+end
+```
+
+## Method signatures
+
+```ruby
+# Initialise the client
+client = Masklen::Client.new(
+  api_key:  "your-api-key",          # required
+  base_url: "https://masklen.dev"    # optional, defaults to production
+)
+
+# Single IP lookup
+result = client.lookup(ip, fields: nil)
+
+# Caller's own IP
+result = client.lookup_self(fields: nil)
+
+# Batch lookup
+batch = client.lookup_batch(ips, fields: nil)
+```
+
+## Filtering fields
+
+All three methods accept an optional `fields:` array. Pass one or more of:
+
+- `"location"` -- city, region, country, coordinates, timezone
+- `"network"` -- ASN, ISP, organisation, domain
+- `"privacy"` -- VPN, proxy, Tor, hosting, threat level
+- `"locale"` -- currency, calling code, languages, flag
+
+```ruby
+# Fetch only location and privacy data to reduce response size
+result = client.lookup("8.8.8.8", fields: ["location", "privacy"])
+puts result.location.city
+puts result.privacy.vpn
+
+# Omit fields entirely to receive all data
+result = client.lookup("8.8.8.8")
+```
+
+## Response types
+
+All types are `Struct` subclasses with keyword arguments.
+
+### LookupResult
+
+| Field      | Type         |
+|------------|--------------|
+| `ip`       | String       |
+| `location` | Location, nil |
+| `network`  | Network, nil |
+| `privacy`  | Privacy, nil |
+| `locale`   | Locale, nil  |
+
+### Location
+
+| Field          | Type         |
+|----------------|--------------|
+| `city`         | String, nil  |
+| `region`       | String, nil  |
+| `country`      | String, nil  |
+| `country_code` | String, nil  |
+| `latitude`     | Float, nil   |
+| `longitude`    | Float, nil   |
+| `postal_code`  | String, nil  |
+| `timezone`     | String, nil  |
+
+### Network
+
+| Field          | Type        |
+|----------------|-------------|
+| `asn`          | String, nil |
+| `isp`          | String, nil |
+| `organization` | String, nil |
+| `domain`       | String, nil |
+
+### Privacy
+
+| Field          | Type    |
+|----------------|---------|
+| `vpn`          | Boolean |
+| `proxy`        | Boolean |
+| `tor`          | Boolean |
+| `hosting`      | Boolean |
+| `threat_level` | String ("low" or "medium") |
+
+### Locale
+
+| Field             | Type          |
+|-------------------|---------------|
+| `currency`        | String, nil   |
+| `currency_symbol` | String, nil   |
+| `calling_code`    | String, nil   |
+| `languages`       | Array<String> |
+| `flag`            | String, nil   |
+
+### BatchResult
+
+| Field     | Type                                  |
+|-----------|---------------------------------------|
+| `results` | Array<LookupResult, BatchItemError> |
+
+### BatchItemError
+
+| Field           | Type   |
+|-----------------|--------|
+| `ip`            | String |
+| `error_code`    | String |
+| `error_message` | String |
+
+## Error handling
+
+All API errors raise `Masklen::Error`, a subclass of `StandardError`.
+
+```ruby
+begin
+  result = client.lookup("8.8.8.8")
+rescue Masklen::Error => e
+  puts e.status_code    # HTTP status, e.g. 401
+  puts e.error_code     # machine-readable code, e.g. "unauthorized"
+  puts e.error_message  # human-readable message
+  puts e.message        # full formatted message string
+end
+```
+
+Network errors (timeouts, connection refused, DNS failures) are also wrapped in `Masklen::Error` with `status_code: 0` and `error_code: "network_error"`.
+
+## Requirements
+
+- Ruby 3.0 or later
+- No external runtime dependencies (stdlib only: `net/http`, `uri`, `json`)
+
+## License
+
+MIT

data/lib/masklen/client.rb

@@ -0,0 +1,170 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Masklen
+  # 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
+  class Client
+    DEFAULT_BASE_URL = "https://masklen.dev"
+
+    # Create a new client.
+    #
+    # api_key  - Your masklen.dev API key (required).
+    # base_url - Override the default base URL (optional, useful for testing).
+    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
+
+    # 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.
+    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
+
+    # 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.
+    def lookup_self(fields: nil)
+      query = build_fields_query(fields)
+      hash  = request(:get, "/v1/lookup", query: query)
+      LookupResult.from_hash(hash)
+    end
+
+    # 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.
+    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
+
+    private
+
+    # Build the query hash for the optional fields parameter.
+    # Returns nil when fields is nil or empty.
+    def build_fields_query(fields)
+      return nil if fields.nil? || fields.empty?
+
+      { "fields" => fields.join(",") }
+    end
+
+    # Perform an HTTP request against the masklen.dev API.
+    #
+    # method - :get or :post (Symbol).
+    # path   - URL path string, e.g. "/v1/lookup/8.8.8.8".
+    # query  - Optional Hash of query-string parameters.
+    # body   - Optional request body string (used for POST).
+    #
+    # Returns a parsed Hash from the JSON response body.
+    # Raises Masklen::Error when the server responds with a non-2xx status.
+    # Raises Masklen::Error wrapping network failures (SocketError, Timeout::Error, etc.).
+    def request(method, path, query: nil, body: nil)
+      uri = build_uri(path, query)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.read_timeout = 30
+      http.open_timeout = 10
+
+      req = build_request(method, uri, body)
+
+      begin
+        response = http.start { |conn| conn.request(req) }
+      rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+             Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
+        raise Masklen::Error.new(
+          status_code:   0,
+          error_code:    "network_error",
+          error_message: e.message
+        )
+      end
+
+      parse_response(response)
+    end
+
+    # Construct the full URI for a request, appending query parameters when present.
+    def build_uri(path, query)
+      uri = URI.parse("#{@base_url}#{path}")
+      if query && !query.empty?
+        uri.query = URI.encode_www_form(query)
+      end
+      uri
+    end
+
+    # Build a Net::HTTP request object with the required headers.
+    def build_request(method, uri, body)
+      req = case method
+            when :get  then Net::HTTP::Get.new(uri)
+            when :post then Net::HTTP::Post.new(uri)
+            else raise ArgumentError, "Unsupported HTTP method: #{method}"
+            end
+
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Accept"]        = "application/json"
+      req["User-Agent"]    = "masklen-ruby/#{Masklen::VERSION}"
+
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = body
+      end
+
+      req
+    end
+
+    # Parse the HTTP response into a Hash.
+    # Raises Masklen::Error for non-2xx status codes.
+    def parse_response(response)
+      status = response.code.to_i
+
+      parsed = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      return parsed if status >= 200 && status < 300
+
+      # Attempt to extract API error details from the response body.
+      error_code    = parsed["error_code"]    || "unknown_error"
+      error_message = parsed["error_message"] || parsed["message"] || response.message || "Unknown error"
+
+      raise Masklen::Error.new(
+        status_code:   status,
+        error_code:    error_code,
+        error_message: error_message
+      )
+    end
+  end
+end

data/lib/masklen/error.rb

@@ -0,0 +1,18 @@
+module Masklen
+  # Raised when the API returns a non-2xx response or when a network error occurs.
+  #
+  # Attributes:
+  #   status_code    - HTTP status code returned by the server (Integer)
+  #   error_code     - machine-readable error code from the API response body (String)
+  #   error_message  - human-readable description from the API response body (String)
+  class Error < StandardError
+    attr_reader :status_code, :error_code, :error_message
+
+    def initialize(status_code:, error_code:, error_message:)
+      @status_code   = status_code
+      @error_code    = error_code
+      @error_message = error_message
+      super("Masklen API error #{status_code} (#{error_code}): #{error_message}")
+    end
+  end
+end

data/lib/masklen/types.rb

@@ -0,0 +1,158 @@
+module Masklen
+  # Geographic location data for an IP address.
+  Location = Struct.new(
+    :city,
+    :region,
+    :country,
+    :country_code,
+    :latitude,
+    :longitude,
+    :postal_code,
+    :timezone,
+    keyword_init: true
+  ) do
+    # Build a Location from a parsed JSON hash. Returns nil if hash is nil.
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(
+        city:         hash["city"],
+        region:       hash["region"],
+        country:      hash["country"],
+        country_code: hash["country_code"],
+        latitude:     hash["latitude"],
+        longitude:    hash["longitude"],
+        postal_code:  hash["postal_code"],
+        timezone:     hash["timezone"]
+      )
+    end
+  end
+
+  # Network and ASN data for an IP address.
+  Network = Struct.new(
+    :asn,
+    :isp,
+    :organization,
+    :domain,
+    keyword_init: true
+  ) do
+    # Build a Network from a parsed JSON hash. Returns nil if hash is nil.
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(
+        asn:          hash["asn"],
+        isp:          hash["isp"],
+        organization: hash["organization"],
+        domain:       hash["domain"]
+      )
+    end
+  end
+
+  # Privacy and threat indicators for an IP address.
+  #
+  # threat_level is "low" or "medium".
+  Privacy = Struct.new(
+    :vpn,
+    :proxy,
+    :tor,
+    :hosting,
+    :threat_level,
+    keyword_init: true
+  ) do
+    # Build a Privacy from a parsed JSON hash. Returns nil if hash is nil.
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(
+        vpn:          hash["vpn"],
+        proxy:        hash["proxy"],
+        tor:          hash["tor"],
+        hosting:      hash["hosting"],
+        threat_level: hash["threat_level"]
+      )
+    end
+  end
+
+  # Locale and regional data for an IP address.
+  Locale = Struct.new(
+    :currency,
+    :currency_symbol,
+    :calling_code,
+    :languages,
+    :flag,
+    keyword_init: true
+  ) do
+    # Build a Locale from a parsed JSON hash. Returns nil if hash is nil.
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(
+        currency:        hash["currency"],
+        currency_symbol: hash["currency_symbol"],
+        calling_code:    hash["calling_code"],
+        languages:       hash["languages"] || [],
+        flag:            hash["flag"]
+      )
+    end
+  end
+
+  # The primary result returned for a single IP lookup.
+  LookupResult = Struct.new(
+    :ip,
+    :location,
+    :network,
+    :privacy,
+    :locale,
+    keyword_init: true
+  ) do
+    # Build a LookupResult from a parsed JSON hash.
+    def self.from_hash(hash)
+      new(
+        ip:       hash["ip"],
+        location: Location.from_hash(hash["location"]),
+        network:  Network.from_hash(hash["network"]),
+        privacy:  Privacy.from_hash(hash["privacy"]),
+        locale:   Locale.from_hash(hash["locale"])
+      )
+    end
+  end
+
+  # Represents a failed entry inside a batch lookup response.
+  BatchItemError = Struct.new(
+    :ip,
+    :error_code,
+    :error_message,
+    keyword_init: true
+  ) do
+    # Build a BatchItemError from a parsed JSON hash.
+    def self.from_hash(hash)
+      new(
+        ip:            hash["ip"],
+        error_code:    hash["error_code"],
+        error_message: hash["error_message"]
+      )
+    end
+  end
+
+  # The result of a batch IP lookup. Each entry in results is either a
+  # LookupResult or a BatchItemError.
+  BatchResult = Struct.new(
+    :results,
+    keyword_init: true
+  ) do
+    # Build a BatchResult from a parsed JSON hash.
+    # Each element in the "results" array is mapped to a LookupResult when it
+    # has an "ip" key and no "error_code", or to a BatchItemError otherwise.
+    def self.from_hash(hash)
+      items = (hash["results"] || []).map do |item|
+        if item.key?("error_code")
+          BatchItemError.from_hash(item)
+        else
+          LookupResult.from_hash(item)
+        end
+      end
+      new(results: items)
+    end
+  end
+end

data/lib/masklen/version.rb

@@ -0,0 +1,3 @@
+module Masklen
+  VERSION = "1.0.0"
+end

data/lib/masklen.rb

@@ -0,0 +1,25 @@
+require_relative "masklen/version"
+require_relative "masklen/error"
+require_relative "masklen/types"
+require_relative "masklen/client"
+
+# Masklen is the official Ruby SDK for the masklen.dev IP intelligence API.
+#
+# Quick start:
+#   require "masklen"
+#
+#   client = Masklen::Client.new(api_key: "your-api-key")
+#
+#   # Look up a specific IP
+#   result = client.lookup("8.8.8.8")
+#   puts result.location.country
+#
+#   # Look up the caller's own IP
+#   self_result = client.lookup_self(fields: ["location", "privacy"])
+#   puts self_result.privacy.vpn
+#
+#   # Batch lookup
+#   batch = client.lookup_batch(["8.8.8.8", "1.1.1.1"])
+#   batch.results.each { |r| puts r.ip }
+module Masklen
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: masklen
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- masklen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-24 00:00:00.000000000 Z
+dependencies: []
+description: Look up geolocation, network, privacy, and locale data for any IP address.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/masklen.rb
+- lib/masklen/client.rb
+- lib/masklen/error.rb
+- lib/masklen/types.rb
+- lib/masklen/version.rb
+homepage: https://masklen.dev
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for the masklen.dev IP intelligence API
+test_files: []