ipregistry 1.0.0

data/lib/ipregistry/models/base.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  # Value objects wrapping the JSON payloads returned by the Ipregistry API.
+  #
+  # Nested objects are always present (never nil), so chained access such as
+  # +info.location.country.name+ never raises even when the API omitted a
+  # section; absent fields return nil and absent flags return false.
+  module Models
+    # Base class for all response models. Wraps the decoded JSON hash and
+    # exposes convenient readers declared with a small class-level DSL.
+    class Base
+      # @param data [Hash, nil] the decoded JSON payload
+      def initialize(data = {})
+        @data = data.is_a?(Hash) ? data : {}
+      end
+
+      # The raw decoded payload backing this model.
+      # @return [Hash]
+      def to_h
+        @data
+      end
+
+      # Raw access to any field of the payload, including ones without a
+      # dedicated reader.
+      def [](key)
+        @data[key.to_s]
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.to_h == @data
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @data].hash
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@data.inspect}>"
+      end
+
+      class << self
+        private
+
+        # Declares readers returning the raw value of same-named JSON fields.
+        def field(*names)
+          names.each do |name|
+            key = name.to_s
+            define_method(name) { @data[key] }
+          end
+        end
+
+        # Declares a predicate method (+name?+) for a boolean JSON field.
+        def flag(name, key: name.to_s)
+          define_method(:"#{name}?") { @data[key] ? true : false }
+        end
+
+        # Declares a reader wrapping a nested JSON object in another model.
+        # The wrapped object is always returned, even when the field is
+        # absent, so chained access is nil-safe.
+        def embeds(name, model, key: name.to_s)
+          define_method(name) do
+            @embedded ||= {}
+            @embedded[name] ||= Models.const_get(model).new(@data[key])
+          end
+        end
+
+        # Declares a reader wrapping a nested JSON array in a list of models.
+        def embeds_many(name, model, key: name.to_s)
+          define_method(name) do
+            @embedded ||= {}
+            @embedded[name] ||= begin
+              klass = Models.const_get(model)
+              elements = @data[key]
+              elements.is_a?(Array) ? elements.map { |element| klass.new(element) }.freeze : [].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ipregistry/models/ip_info.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  module Models
+    # Mobile carrier information associated with an IP address. MCC is the
+    # Mobile Country Code and MNC the Mobile Network Code.
+    class Carrier < Base
+      field :name, :mcc, :mnc
+    end
+
+    # Ownership information for the IP address. The type classifies the kind
+    # of company ("business", "education", "government", "hosting", or "isp").
+    class Company < Base
+      field :name, :domain, :type
+    end
+
+    # Network connection information for the IP address. The ASN is the
+    # Autonomous System Number (nil when unknown), and the type classifies
+    # the network ("business", "education", "government", "hosting",
+    # "inactive", or "isp").
+    class Connection < Base
+      field :asn, :domain, :organization, :route, :type
+    end
+
+    # Prefix and suffix applied around a formatted monetary value (for example
+    # the currency symbol and a sign).
+    class CurrencyFormatAffix < Base
+      field :prefix, :suffix
+    end
+
+    # How monetary values are formatted for a currency.
+    class CurrencyFormat < Base
+      field :decimal_separator, :group_separator
+
+      embeds :negative, :CurrencyFormatAffix
+      embeds :positive, :CurrencyFormatAffix
+    end
+
+    # Currency information for the IP address location.
+    class Currency < Base
+      field :code, :name, :name_native, :plural, :plural_native,
+            :symbol, :symbol_native
+
+      embeds :format, :CurrencyFormat
+    end
+
+    # Threat-intelligence flags for the IP address.
+    class Security < Base
+      flag :abuser, key: "is_abuser"
+      flag :attacker, key: "is_attacker"
+      flag :bogon, key: "is_bogon"
+      flag :cloud_provider, key: "is_cloud_provider"
+      flag :proxy, key: "is_proxy"
+      flag :relay, key: "is_relay"
+      flag :tor, key: "is_tor"
+      flag :tor_exit, key: "is_tor_exit"
+      flag :anonymous, key: "is_anonymous"
+      flag :threat, key: "is_threat"
+      flag :vpn, key: "is_vpn"
+    end
+
+    # Time zone information for the IP address location. The offset is the
+    # current offset from UTC in seconds.
+    class TimeZone < Base
+      field :id, :abbreviation, :current_time, :name, :offset
+
+      flag :in_daylight_saving
+    end
+
+    # The comprehensive set of information associated with an IP address
+    # returned by the Ipregistry API.
+    #
+    # Nested objects (carrier, company, connection, currency, location,
+    # security, and time_zone) are always present, so chained access never
+    # raises even when the API omitted them; absent fields return nil.
+    class IpInfo < Base
+      # ip is the IP address the data refers to; type is the IP version
+      # ("IPv4" or "IPv6"); hostname is the reverse-DNS hostname, when
+      # hostname resolution is requested and available.
+      field :ip, :type, :hostname
+
+      embeds :carrier, :Carrier
+      embeds :company, :Company
+      embeds :connection, :Connection
+      embeds :currency, :Currency
+      embeds :location, :Location
+      embeds :security, :Security
+      embeds :time_zone, :TimeZone
+
+      def ipv4? = @data["type"] == "IPv4"
+
+      def ipv6? = @data["type"] == "IPv6"
+    end
+
+    # IpInfo enriched with parsed User-Agent data. Returned by
+    # {Client#lookup_origin}, where the User-Agent of the calling client is
+    # known.
+    class RequesterIpInfo < IpInfo
+      # The parsed User-Agent of the requester, or nil when the API did not
+      # return any.
+      # @return [UserAgent, nil]
+      def user_agent
+        value = @data["user_agent"]
+        return nil unless value.is_a?(Hash)
+
+        @embedded ||= {}
+        @embedded[:user_agent] ||= UserAgent.new(value)
+      end
+    end
+  end
+end

data/lib/ipregistry/models/location.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  module Models
+    # Continent-level information for a location.
+    class Continent < Base
+      field :code, :name
+    end
+
+    # Language information.
+    class Language < Base
+      field :code, :name
+
+      # The language's name in the language itself.
+      def native_name
+        @data["native"]
+      end
+    end
+
+    # Representations of a country flag across several icon sets.
+    class Flag < Base
+      field :emoji, :emoji_unicode, :emojitwo, :noto, :twemoji, :wikimedia
+    end
+
+    # Country-level information for a location.
+    class Country < Base
+      # area is the total land area in square kilometers; borders lists the
+      # ISO 3166-1 alpha-2 codes of bordering countries; code is the ISO
+      # 3166-1 alpha-2 country code (for example "US"); population is the
+      # estimated number of inhabitants; population_density is the number of
+      # inhabitants per square kilometer; tld is the country-code top-level
+      # domain (for example ".us").
+      field :area, :calling_code, :capital, :code, :name,
+            :population, :population_density, :tld
+
+      embeds :flag, :Flag
+      embeds_many :languages, :Language
+
+      # ISO 3166-1 alpha-2 codes of bordering countries.
+      # @return [Array<String>]
+      def borders
+        value = @data["borders"]
+        value.is_a?(Array) ? value : []
+      end
+    end
+
+    # Administrative region (state/province) information. The code is
+    # typically the ISO 3166-2 subdivision code.
+    class Region < Base
+      field :code, :name
+    end
+
+    # Geographical location associated with an IP address.
+    class Location < Base
+      # city, postal, and the decimal-degree latitude/longitude (nil when
+      # unavailable).
+      field :city, :postal, :latitude, :longitude
+
+      embeds :continent, :Continent
+      embeds :country, :Country
+      embeds :region, :Region
+      # The primary language spoken at the location.
+      embeds :language, :Language
+
+      # Whether the location is within a European Union member state.
+      flag :in_eu
+    end
+  end
+end

data/lib/ipregistry/models/user_agent.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  module Models
+    # Device data parsed from a User-Agent string.
+    class UserAgentDevice < Base
+      field :brand, :name, :type
+    end
+
+    # Layout-engine data parsed from a User-Agent string.
+    class UserAgentEngine < Base
+      field :name, :type, :version, :version_major
+    end
+
+    # Operating-system data parsed from a User-Agent string.
+    class UserAgentOperatingSystem < Base
+      field :name, :type, :version
+    end
+
+    # Structured data parsed from a raw User-Agent string. The header field
+    # is the raw User-Agent string that was parsed.
+    class UserAgent < Base
+      field :header, :name, :type, :version, :version_major
+
+      embeds :device, :UserAgentDevice
+      embeds :engine, :UserAgentEngine
+      embeds :operating_system, :UserAgentOperatingSystem, key: "os"
+      alias os operating_system
+    end
+  end
+end

data/lib/ipregistry/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ipregistry
+  # Version of the client library, reported as part of the User-Agent header
+  # sent with every request to the Ipregistry API.
+  VERSION = "1.0.0"
+end

data/lib/ipregistry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "ipregistry/version"
+require_relative "ipregistry/errors"
+require_relative "ipregistry/cache"
+require_relative "ipregistry/models/base"
+require_relative "ipregistry/models/location"
+require_relative "ipregistry/models/ip_info"
+require_relative "ipregistry/models/user_agent"
+require_relative "ipregistry/batch_response"
+require_relative "ipregistry/client"
+
+# Official Ruby client for the Ipregistry API (https://ipregistry.co), a fast
+# and reliable IP geolocation and threat data service.
+#
+#   client = Ipregistry::Client.new("YOUR_API_KEY")
+#   info = client.lookup("8.8.8.8")
+#   info.location.country.name # => "United States"
+#   info.security.vpn?         # => false
+module Ipregistry
+  # Reports whether the given raw User-Agent string looks like a crawler or
+  # bot. It is a lightweight heuristic — useful for skipping IP lookups on
+  # automated traffic — that matches the substrings "bot", "spider", and
+  # "slurp" case-insensitively.
+  #
+  #   unless Ipregistry.bot?(request.user_agent)
+  #     info = client.lookup(request.remote_ip)
+  #   end
+  def self.bot?(user_agent)
+    value = user_agent.to_s.downcase
+    value.include?("bot") || value.include?("spider") || value.include?("slurp")
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: ipregistry
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ipregistry
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Look up IP addresses (single, batch, or the requester's own) and parse
+  User-Agent strings with the Ipregistry API. Returns carrier, company, connection,
+  currency, location, time zone, and threat data. Zero runtime dependencies, optional
+  in-memory caching, and automatic retries with exponential backoff.
+email:
+- support@ipregistry.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ipregistry.rb
+- lib/ipregistry/batch_response.rb
+- lib/ipregistry/cache.rb
+- lib/ipregistry/client.rb
+- lib/ipregistry/errors.rb
+- lib/ipregistry/models/base.rb
+- lib/ipregistry/models/ip_info.rb
+- lib/ipregistry/models/location.rb
+- lib/ipregistry/models/user_agent.rb
+- lib/ipregistry/version.rb
+homepage: https://github.com/ipregistry/ipregistry-ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/ipregistry/ipregistry-ruby
+  source_code_uri: https://github.com/ipregistry/ipregistry-ruby
+  changelog_uri: https://github.com/ipregistry/ipregistry-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ipregistry/ipregistry-ruby/issues
+  documentation_uri: https://ipregistry.co/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the Ipregistry IP geolocation and threat data API
+test_files: []