ipgeolocation_sdk 1.0.0 → 2.0.1

data/lib/ipgeolocation_sdk/client.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "time"
+
+module IpgeolocationSdk
+  class IpGeolocationClient
+    def self.default_user_agent
+      "ipgeolocation-ruby-sdk/#{VERSION}"
+    end
+
+    def initialize(config, transport = nil)
+      raise TypeError, "config must not be nil" if config.nil?
+
+      @config =
+        case config
+        when IpGeolocationClientConfig
+          config
+        when Hash
+          IpGeolocationClientConfig.new(**config)
+        else
+          raise TypeError, "config must be an IpGeolocationClientConfig or hash"
+        end
+
+      @transport = transport || NetHttpTransport.new
+      @owns_transport = transport.nil?
+      @closed = false
+    end
+
+    attr_reader :config
+
+    def inspect
+      "#<#{self.class} config=#{@config.inspect} closed=#{@closed}>"
+    end
+
+    def lookup_ip_geolocation(request = nil)
+      ensure_open
+      typed_request = to_lookup_request(request)
+      validate_lookup_request_base
+      Serde.validate_json_output(typed_request.output)
+
+      response, duration_ms = execute_with_metrics(build_lookup_http_request(typed_request))
+      raise Serde.to_api_error(response.status_code, response.body) unless success_status?(response.status_code)
+
+      ApiResponse.new(
+        data: Serde.parse_single_lookup(response.body),
+        metadata: Serde.to_metadata(response.status_code, duration_ms, response.headers)
+      )
+    end
+
+    def lookup_ip_geolocation_raw(request = nil)
+      ensure_open
+      typed_request = to_lookup_request(request)
+      validate_lookup_request_base
+
+      response, duration_ms = execute_with_metrics(build_lookup_http_request(typed_request))
+      raise Serde.to_api_error(response.status_code, response.body) unless success_status?(response.status_code)
+
+      ApiResponse.new(
+        data: response.body,
+        metadata: Serde.to_metadata(response.status_code, duration_ms, response.headers)
+      )
+    end
+
+    def bulk_lookup_ip_geolocation(request)
+      ensure_open
+      typed_request = to_bulk_request(request)
+      validate_bulk_request_base
+      Serde.validate_json_output(typed_request.output)
+
+      response, duration_ms = execute_with_metrics(build_bulk_http_request(typed_request))
+      raise Serde.to_api_error(response.status_code, response.body) unless success_status?(response.status_code)
+
+      ApiResponse.new(
+        data: Serde.parse_bulk_lookup(response.body),
+        metadata: Serde.to_metadata(response.status_code, duration_ms, response.headers)
+      )
+    end
+
+    def bulk_lookup_ip_geolocation_raw(request)
+      ensure_open
+      typed_request = to_bulk_request(request)
+      validate_bulk_request_base
+
+      response, duration_ms = execute_with_metrics(build_bulk_http_request(typed_request))
+      raise Serde.to_api_error(response.status_code, response.body) unless success_status?(response.status_code)
+
+      ApiResponse.new(
+        data: response.body,
+        metadata: Serde.to_metadata(response.status_code, duration_ms, response.headers)
+      )
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      @transport.close if @owns_transport && @transport.respond_to?(:close)
+      nil
+    end
+
+    private
+
+    def ensure_open
+      raise ValidationError, "client is closed" if @closed
+    end
+
+    def validate_lookup_request_base
+      return unless @config.api_key.nil? && @config.request_origin.nil?
+
+      raise ValidationError, "single lookup requires api_key or request_origin in client config"
+    end
+
+    def validate_bulk_request_base
+      raise ValidationError, "bulk lookup requires api_key in client config" if @config.api_key.nil?
+    end
+
+    def to_lookup_request(request)
+      case request
+      when nil
+        LookupIpGeolocationRequest.new
+      when LookupIpGeolocationRequest
+        request
+      when Hash
+        LookupIpGeolocationRequest.new(**request)
+      else
+        raise TypeError, "request must be a LookupIpGeolocationRequest, hash, or nil"
+      end
+    end
+
+    def to_bulk_request(request)
+      case request
+      when BulkLookupIpGeolocationRequest
+        request
+      when Hash
+        BulkLookupIpGeolocationRequest.new(**request)
+      when nil
+        raise ValidationError, "request must not be nil"
+      else
+        raise TypeError, "request must be a BulkLookupIpGeolocationRequest or hash"
+      end
+    end
+
+    def build_lookup_http_request(request)
+      output = request.output || ResponseFormat::JSON
+      query = Serde.build_query(
+        "apiKey" => @config.api_key,
+        "ip" => request.ip,
+        "lang" => request.lang,
+        "include" => request.include.empty? ? nil : request.include.join(","),
+        "fields" => request.fields.empty? ? nil : request.fields.join(","),
+        "excludes" => request.excludes.empty? ? nil : request.excludes.join(","),
+        "output" => output
+      )
+
+      headers = Serde.merge_headers(
+        request.headers,
+        @config.request_origin.nil? ? nil : { "Origin" => [@config.request_origin].freeze },
+        {
+          "User-Agent" => Serde.resolve_user_agent_header(
+            request.user_agent,
+            request.headers,
+            self.class.default_user_agent
+          ),
+          "Accept" => [output == ResponseFormat::XML ? "application/xml" : "application/json"].freeze
+        }.freeze
+      )
+
+      HttpRequestData.new(
+        url: "#{@config.base_url}/v3/ipgeo#{query}",
+        method: "GET",
+        headers: headers,
+        body: nil,
+        connect_timeout: @config.connect_timeout,
+        read_timeout: @config.read_timeout
+      )
+    end
+
+    def build_bulk_http_request(request)
+      output = request.output || ResponseFormat::JSON
+      query = Serde.build_query(
+        "apiKey" => @config.api_key,
+        "lang" => request.lang,
+        "include" => request.include.empty? ? nil : request.include.join(","),
+        "fields" => request.fields.empty? ? nil : request.fields.join(","),
+        "excludes" => request.excludes.empty? ? nil : request.excludes.join(","),
+        "output" => output
+      )
+
+      payload = JSON.generate({ ips: request.ips })
+      headers = Serde.merge_headers(
+        request.headers,
+        @config.request_origin.nil? ? nil : { "Origin" => [@config.request_origin].freeze },
+        {
+          "User-Agent" => Serde.resolve_user_agent_header(
+            request.user_agent,
+            request.headers,
+            self.class.default_user_agent
+          ),
+          "Accept" => [output == ResponseFormat::XML ? "application/xml" : "application/json"].freeze,
+          "Content-Type" => ["application/json"].freeze
+        }.freeze
+      )
+
+      HttpRequestData.new(
+        url: "#{@config.base_url}/v3/ipgeo-bulk#{query}",
+        method: "POST",
+        headers: headers,
+        body: payload,
+        connect_timeout: @config.connect_timeout,
+        read_timeout: @config.read_timeout
+      )
+    rescue JSON::GeneratorError => error
+      raise SerializationError.new("Failed to serialize bulk lookup request body", cause: error)
+    end
+
+    def execute_with_metrics(request)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = @transport.send_request(request)
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).floor
+      [response, [duration_ms, 0].max]
+    end
+
+    def success_status?(status_code)
+      status_code / 100 == 2
+    end
+  end
+end

data/lib/ipgeolocation_sdk/client_config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module IpgeolocationSdk
+  class IpGeolocationClientConfig < ValueObject
+    DEFAULT_BASE_URL = "https://api.ipgeolocation.io"
+    DEFAULT_CONNECT_TIMEOUT = 10.0
+    DEFAULT_READ_TIMEOUT = 30.0
+
+    attributes :api_key, :request_origin, :base_url, :connect_timeout, :read_timeout
+
+    def initialize(
+      api_key: nil,
+      request_origin: nil,
+      base_url: DEFAULT_BASE_URL,
+      connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT
+    )
+      super(
+        api_key: normalize_api_key(api_key),
+        request_origin: normalize_request_origin(request_origin),
+        base_url: normalize_base_url(base_url),
+        connect_timeout: normalize_timeout(connect_timeout, "connect_timeout"),
+        read_timeout: normalize_timeout(read_timeout, "read_timeout")
+      )
+    end
+
+    def inspect
+      "#<#{self.class} #{to_h(mode: JsonOutputMode::FULL).inspect}>"
+    end
+
+    private
+
+    def normalize_api_key(value)
+      return nil if value.nil?
+      raise TypeError, "api_key must be a string" unless value.is_a?(String)
+
+      normalized = value.strip
+      raise ValidationError, "api_key must not be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_request_origin(value)
+      return nil if value.nil?
+      raise TypeError, "request_origin must be a string" unless value.is_a?(String)
+
+      normalized = value.strip
+      raise ValidationError, "request_origin must not be blank" if normalized.empty?
+      raise ValidationError, "request_origin must not contain CR or LF" if normalized.include?("\r") || normalized.include?("\n")
+
+      uri = parse_uri(normalized, "request_origin must be an absolute http or https origin")
+
+      unless %w[http https].include?(uri.scheme) && uri.host
+        raise ValidationError, "request_origin must be an absolute http or https origin"
+      end
+      raise ValidationError, "request_origin must not include a path" unless ["", "/"].include?(uri.path.to_s)
+      raise ValidationError, "request_origin must not include params, query, or fragment" unless [nil, ""].include?(uri.query) && [nil, ""].include?(uri.fragment)
+      raise ValidationError, "request_origin must not include userinfo" unless uri.userinfo.nil?
+
+      "#{uri.scheme}://#{uri.host}#{port_suffix(uri)}"
+    end
+
+    def normalize_base_url(value)
+      raise TypeError, "base_url must be a string" unless value.is_a?(String)
+
+      normalized = value.strip.sub(%r{/+\z}, "")
+      raise ValidationError, "base_url must not be blank" if normalized.empty?
+
+      uri = parse_uri(normalized, "base_url must be an absolute http or https URL")
+
+      unless %w[http https].include?(uri.scheme) && uri.host
+        raise ValidationError, "base_url must be an absolute http or https URL"
+      end
+      raise ValidationError, "base_url must not include params, query, or fragment" unless [nil, ""].include?(uri.query) && [nil, ""].include?(uri.fragment)
+      raise ValidationError, "base_url must not include userinfo" unless uri.userinfo.nil?
+
+      normalized
+    end
+
+    def normalize_timeout(value, field)
+      raise TypeError, "#{field} must be a number" unless value.is_a?(Numeric) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+
+      normalized = value.to_f
+      raise ValidationError, "#{field} must be finite" unless normalized.finite?
+      raise ValidationError, "#{field} must be greater than zero" unless normalized.positive?
+
+      normalized
+    end
+
+    def parse_uri(value, message)
+      URI.parse(value)
+    rescue URI::InvalidURIError
+      raise ValidationError, message
+    end
+
+    def port_suffix(uri)
+      return "" if uri.port.nil?
+      return "" if uri.scheme == "http" && uri.port == 80
+      return "" if uri.scheme == "https" && uri.port == 443
+
+      ":#{uri.port}"
+    end
+  end
+end

data/lib/ipgeolocation_sdk/enums.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module IpgeolocationSdk
+  module Language
+    EN = "en"
+    DE = "de"
+    RU = "ru"
+    JA = "ja"
+    FR = "fr"
+    CN = "cn"
+    ES = "es"
+    CS = "cs"
+    IT = "it"
+    KO = "ko"
+    FA = "fa"
+    PT = "pt"
+
+    VALUES = [
+      EN, DE, RU, JA, FR, CN, ES, CS, IT, KO, FA, PT
+    ].freeze
+
+    module_function
+
+    def from_code(code)
+      normalized = normalize_token(code, "code")
+      value = VALUES.find { |item| item.casecmp?(normalized) }
+      raise ValidationError, "Unsupported language code: #{code}" if value.nil?
+
+      value
+    end
+
+    def valid?(code)
+      VALUES.any? { |item| item.casecmp?(code.to_s.strip) }
+    end
+
+    def normalize(value)
+      return nil if value.nil?
+
+      from_code(value)
+    end
+
+    def normalize_token(value, field)
+      raise TypeError, "#{field} must be a string or symbol" unless value.is_a?(String) || value.is_a?(Symbol)
+
+      normalized = value.to_s.strip
+      raise ValidationError, "#{field} must not be blank" if normalized.empty?
+
+      normalized
+    end
+    private_class_method :normalize_token
+  end
+
+  module ResponseFormat
+    JSON = "json"
+    XML = "xml"
+
+    VALUES = [JSON, XML].freeze
+
+    module_function
+
+    def normalize(value)
+      return JSON if value.nil?
+      raise TypeError, "output must be a string or symbol" unless value.is_a?(String) || value.is_a?(Symbol)
+
+      normalized = value.to_s.strip.downcase
+      return normalized if VALUES.include?(normalized)
+
+      raise ValidationError, "output must be either 'json' or 'xml'"
+    end
+  end
+
+  module JsonOutputMode
+    COMPACT = "compact"
+    FULL = "full"
+
+    VALUES = [COMPACT, FULL].freeze
+
+    module_function
+
+    def normalize(value)
+      return COMPACT if value.nil?
+      raise TypeError, "mode must be a string or symbol" unless value.is_a?(String) || value.is_a?(Symbol)
+
+      normalized = value.to_s.strip.downcase
+      return normalized if VALUES.include?(normalized)
+
+      raise ValidationError, "mode must be either 'compact' or 'full'"
+    end
+  end
+
+  module LocationConfidence
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    UNKNOWN = "unknown"
+
+    VALUES = [HIGH, MEDIUM, LOW, UNKNOWN].freeze
+
+    module_function
+
+    def normalize(value)
+      return nil if value.nil?
+
+      normalized = value.to_s.strip.downcase
+      return normalized if VALUES.include?(normalized)
+
+      UNKNOWN
+    end
+  end
+end

data/lib/ipgeolocation_sdk/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module IpgeolocationSdk
+  class IpGeolocationError < StandardError
+    attr_reader :cause
+
+    def initialize(message, cause: nil)
+      super(message)
+      @cause = cause
+    end
+  end
+
+  class ValidationError < IpGeolocationError; end
+  class SerializationError < IpGeolocationError; end
+  class TransportError < IpGeolocationError; end
+  class RequestTimeoutError < TransportError; end
+
+  class ApiError < IpGeolocationError
+    attr_reader :status_code, :api_message
+
+    def initialize(message, status_code, api_message = nil)
+      super(message)
+      @status_code = status_code
+      @api_message = api_message
+    end
+  end
+
+  class BadRequestError < ApiError; end
+  class UnauthorizedError < ApiError; end
+  class NotFoundError < ApiError; end
+  class MethodNotAllowedError < ApiError; end
+  class PayloadTooLargeError < ApiError; end
+  class UnsupportedMediaTypeError < ApiError; end
+  class LockedError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ClientClosedRequestError < ApiError; end
+  class ServerError < ApiError; end
+end

data/lib/ipgeolocation_sdk/json_output.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module IpgeolocationSdk
+  module JsonOutput
+    module_function
+
+    def to_json(value, mode = JsonOutputMode::COMPACT)
+      write(value, mode, pretty: false)
+    end
+
+    def to_pretty_json(value, mode = JsonOutputMode::COMPACT)
+      write(value, mode, pretty: true)
+    end
+
+    def write(value, mode, pretty:)
+      normalized_mode = JsonOutputMode.normalize(mode)
+      payload = Serde.to_plain_data(value, normalized_mode)
+      if pretty
+        JSON.pretty_generate(payload)
+      else
+        JSON.generate(payload)
+      end
+    rescue StandardError => error
+      raise SerializationError.new("Failed to serialize output as JSON", cause: error)
+    end
+    private_class_method :write
+  end
+end

data/lib/ipgeolocation_sdk/models.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module IpgeolocationSdk
+  class ApiResponse < ValueObject
+    attributes :data, :metadata
+  end
+
+  class ApiResponseMetadata < ValueObject
+    attributes :credits_charged, :successful_records, :status_code, :duration_ms, :raw_headers
+
+    def initialize(
+      credits_charged: nil,
+      successful_records: nil,
+      status_code:,
+      duration_ms:,
+      raw_headers: {}
+    )
+      validate_optional_integer(credits_charged, "credits_charged")
+      validate_optional_integer(successful_records, "successful_records")
+      validate_status_code(status_code)
+      validate_duration(duration_ms)
+
+      normalized_headers = normalize_headers(raw_headers)
+
+      super(
+        credits_charged: credits_charged,
+        successful_records: successful_records,
+        status_code: status_code,
+        duration_ms: duration_ms,
+        raw_headers: normalized_headers
+      )
+    end
+
+    def header_values(name)
+      raise TypeError, "header name must be a string" unless name.is_a?(String)
+
+      normalized_name = name.strip
+      raise ArgumentError, "header name must not be blank" if normalized_name.empty?
+
+      raw_headers.each do |key, values|
+        return values if key.casecmp?(normalized_name)
+      end
+
+      EMPTY_HEADER_VALUES
+    end
+
+    def first_header_value(name)
+      header_values(name).first
+    end
+
+    EMPTY_HEADER_VALUES = [].freeze
+
+    private
+
+    def validate_optional_integer(value, field)
+      return if value.nil?
+      raise TypeError, "#{field} must be an integer" unless value.is_a?(Integer)
+      raise ArgumentError, "#{field} must be greater than or equal to zero" if value.negative?
+    end
+
+    def validate_status_code(value)
+      raise TypeError, "status_code must be an integer" unless value.is_a?(Integer)
+      raise ArgumentError, "status_code must be between 100 and 599" unless value.between?(100, 599)
+    end
+
+    def validate_duration(value)
+      raise TypeError, "duration_ms must be an integer" unless value.is_a?(Integer)
+      raise ArgumentError, "duration_ms must be greater than or equal to zero" if value.negative?
+    end
+
+    def normalize_headers(input)
+      raise TypeError, "raw_headers must be a hash" unless input.is_a?(Hash)
+
+      input.each_with_object({}) do |(key, values), result|
+        next if key.nil?
+
+        name = key.to_s
+        next if name.strip.empty?
+        raise TypeError, "raw_headers values must be arrays of strings" unless values.is_a?(Array)
+        normalized_values = values.map do |value|
+          raise TypeError, "raw_headers values must contain only strings" unless value.is_a?(String)
+
+          value
+        end
+        result[name] = normalized_values.freeze
+      end.freeze
+    end
+  end
+
+  class Abuse < ValueObject
+    attributes :route, :country, :name, :organization, :kind, :address, :emails, :phone_numbers
+  end
+
+  class Asn < ValueObject
+    attributes :as_number, :organization, :country, :type, :domain, :date_allocated, :rir
+  end
+
+  class Company < ValueObject
+    attributes :name, :type, :domain
+  end
+
+  class CountryMetadata < ValueObject
+    attributes :calling_code, :tld, :languages
+  end
+
+  class Currency < ValueObject
+    attributes :code, :name, :symbol
+  end
+
+  class DstTransition < ValueObject
+    attributes :utc_time, :duration, :gap, :date_time_after, :date_time_before, :overlap
+  end
+
+  class Location < ValueObject
+    attributes :continent_code, :continent_name, :country_code2, :country_code3,
+               :country_name, :country_name_official, :country_capital, :state_prov,
+               :state_code, :district, :city, :locality, :accuracy_radius, :confidence,
+               :dma_code, :zipcode, :latitude, :longitude, :is_eu, :country_flag,
+               :geoname_id, :country_emoji
+  end
+
+  class Network < ValueObject
+    attributes :connection_type, :route, :is_anycast
+  end
+
+  class Security < ValueObject
+    attributes :threat_score, :is_tor, :is_proxy, :proxy_provider_names,
+               :proxy_confidence_score, :proxy_last_seen, :is_residential_proxy,
+               :is_vpn, :vpn_provider_names, :vpn_confidence_score, :vpn_last_seen,
+               :is_relay, :relay_provider_name, :is_anonymous, :is_known_attacker,
+               :is_bot, :is_spam, :is_cloud_provider, :cloud_provider_name
+  end
+
+  class TimeZoneInfo < ValueObject
+    attributes :name, :offset, :offset_with_dst, :current_time, :current_time_unix,
+               :current_tz_abbreviation, :current_tz_full_name, :standard_tz_abbreviation,
+               :standard_tz_full_name, :is_dst, :dst_savings, :dst_exists,
+               :dst_tz_abbreviation, :dst_tz_full_name, :dst_start, :dst_end
+  end
+
+  class UserAgentDevice < ValueObject
+    attributes :name, :type, :brand, :cpu
+  end
+
+  class UserAgentEngine < ValueObject
+    attributes :name, :type, :version, :version_major
+  end
+
+  class UserAgentOperatingSystem < ValueObject
+    attributes :name, :type, :version, :version_major, :build
+  end
+
+  class UserAgent < ValueObject
+    attributes :user_agent_string, :name, :type, :version, :version_major,
+               :device, :engine, :operating_system
+  end
+
+  class IpGeolocationResponse < ValueObject
+    attributes :ip, :domain, :hostname, :location, :country_metadata, :network,
+               :currency, :asn, :company, :security, :abuse, :time_zone, :user_agent
+  end
+
+  class BulkLookupSuccess < ValueObject
+    attributes :data
+
+    def success
+      true
+    end
+
+    alias success? success
+  end
+
+  class BulkLookupErrorDetails < ValueObject
+    attributes :message
+  end
+
+  class BulkLookupError < ValueObject
+    attributes :error
+
+    def success
+      false
+    end
+
+    alias success? success
+  end
+end