ip2geo 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cdf86cb50c5d08c734ea15c78ec62d0f218dae67ccdb074b9b889fb0c77681f
+  data.tar.gz: ed6420fd62687669cf430d6525b6415326a595cd60e4fae6a65ce0aae268e182
+SHA512:
+  metadata.gz: 2a7f9f99b598e068ccff78fb2ba2199835a2db6ee086f7871228fcd8e785d321b72b7187bc195a77589acbb6a7f7f170e1d3410044355b913d9e41f2766ac0e0
+  data.tar.gz: 190301f6be0572c93262611ec8cc2ee6f4ec631c9c810755777076daa379bc87ab22eaa5f543ef959584acd46c4ab54f3529d8c6218c1acb0c70917c55bc40c7

data/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2024 Ip2Geo. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this software, via any medium, is strictly prohibited.
+
+No license, express or implied, is granted to any person or entity for any purpose.

data/README.md

@@ -0,0 +1,99 @@
+<div align='center'>
+   <a href='https://axios-http.com'>
+        <img 
+            src='https://cdn-prod.ip2geo.dev/assets/npm/generals/ip2geo.svg' 
+            alt='Ip2Geo Logo' 
+        />
+   </a>
+
+   <br />
+</div>
+
+<p align='center'>
+    Your go-to IP-to-Geo cloud service — fast, accurate, and built for developers. Start free with 2,000 monthly stored conversions.
+</p>
+
+<p align='center'>
+    <a href='https://ip2geo.dev'>
+        <b>
+            Website
+        </b>
+    </a> 
+    •
+    <a href='https://app.ip2geo.dev'>
+        <b>
+            Dashboard
+        </b>
+    </a> 
+    •
+    <a href='https://docs.ip2geo.dev'>
+        <b>
+            Documentation
+        </b>
+    </a>
+    •
+    <a href='https://status.ip2geo.dev'>
+        <b>
+            Services Status
+        </b>
+    </a>
+</p>
+
+<br />
+
+## Intro to the Ruby Gem
+
+This gem provides a lightweight way to integrate Ip2Geo into your Ruby applications.
+
+### Installing
+```bash
+gem install ip2geo
+```
+
+### Initializing
+```ruby
+require 'ip2geo'
+
+Ip2Geo.init(ENV['IP2GEO_API_KEY'])
+```
+
+### Using
+```ruby
+converted_ip = Ip2Geo.convert_ip(ip: '8.8.8.8')
+
+converted_ips = Ip2Geo.convert_ips(
+  ips: [
+    '8.8.8.8',
+    '1.1.1.1',
+    '9.9.9.9',
+    '64.6.64.6'
+  ]
+)
+
+# {
+#     'success' => true,
+#     'code' => 200,
+#     'message' => 'Success',
+#     'data' => { ... },
+#     '_req' => {
+#          'reqId' => 'string',
+#          'resTime' => 123
+#     }
+# }
+
+# {
+#     'success' => true,
+#     'code' => 200,
+#     'message' => 'Success',
+#     'data' => [
+#         {
+#             'ip' => '8.8.8.8',
+#             'conversion' => { ... }
+#         }
+#     ],
+#     '_req' => {
+#          'reqId' => 'string',
+#          'resTime' => 123
+#     }
+# }
+```

data/ip2geo.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+    spec.name          = 'ip2geo'
+    spec.version       = '0.0.1'
+    spec.authors       = ['Ip2Geo']
+    spec.email         = ['support@ip2geo.dev']
+
+    spec.summary       = 'Official Ruby SDK for Ip2Geo - IP to Geolocation API.'
+    spec.description   = 'A lightweight Ruby client for the Ip2Geo cloud service. Get accurate geolocation data for IP addresses including continent, country, city, timezone, ASN, and more.'
+    spec.homepage      = 'https://ip2geo.dev'
+    spec.required_ruby_version = '>= 2.7.0'
+
+    spec.license = 'Nonstandard'
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['changelog_uri'] = 'https://docs.ip2geo.dev/changelog'
+    spec.metadata['documentation_uri'] = 'https://docs.ip2geo.dev'
+
+    spec.files = Dir.glob('lib/**/*') + ['ip2geo.gemspec', 'README.md', 'LICENSE']
+    spec.require_paths = ['lib']
+
+    spec.add_dependency 'json', '~> 2.0'
+end

data/lib/ip2geo/data/constants.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Data
+    API_ENDPOINT = 'https://api.ip2geo.dev'
+    DOCS_URL = 'https://docs.ip2geo.dev'
+    RUBYGEMS_URL = 'https://rubygems.org/api/v1/gems/ip2geo.json'
+
+    IP_TYPES = {
+      IPV4: 'ipv4',
+      IPV6: 'ipv6'
+    }.freeze
+
+    HTTP_METHODS = {
+      ALL: 'all',
+      GET: 'GET',
+      POST: 'POST',
+      DELETE: 'DELETE',
+      OPTIONS: 'OPTIONS'
+    }.freeze
+
+    HEADER_KEYS = {
+      X_API_KEY: 'X-Api-Key'
+    }.freeze
+
+    FILE_TYPES = {
+      JSON: 'json'
+    }.freeze
+
+    FILE_FORMATS = {
+      APPLICATION_JSON: 'application/json'
+    }.freeze
+
+    HEADER_TYPES = {
+      CONTENT_TYPE: 'Content-Type'
+    }.freeze
+
+    ENDPOINTS = {
+      CONVERT: '/convert',
+      CONVERSIONS: {
+        GET: '/conversions/get',
+        LIST: '/conversions/list'
+      }.freeze
+    }.freeze
+
+    SELECT = {
+      CONVERSION: {
+        ID: 'id',
+        UNIQUE_ID: 'uniqueId',
+        DATA: 'data',
+        STATUS: 'status',
+        STARTED_AT: 'startedAt',
+        COMPLETED_AT: 'completedAt',
+        CREATED_AT: 'createdAt',
+        CREDITED: 'credited',
+        CONVERT_ONLY: 'convertOnly'
+      }.freeze,
+      DATA: {
+        IP: 'data.ip',
+        TYPE: 'data.type',
+        IS_EU: 'data.is_eu',
+        CONTINENT: {
+          NAME: 'data.continent.name',
+          CODE: 'data.continent.code',
+          GEONAME_ID: 'data.continent.geoname_id',
+          COUNTRY: {
+            NAME: 'data.continent.country.name',
+            CODE: 'data.continent.country.code',
+            GEONAME_ID: 'data.continent.country.geoname_id',
+            PHONE_CODE: 'data.continent.country.phone_code',
+            CAPITAL: 'data.continent.country.capital',
+            TLD: 'data.continent.country.tld',
+            SUBDIVISION: {
+              NAME: 'data.continent.country.subdivision.name',
+              CODE: 'data.continent.country.subdivision.code'
+            }.freeze,
+            CITY: {
+              NAME: 'data.continent.country.city.name',
+              GEONAME_ID: 'data.continent.country.city.geoname_id',
+              LATITUDE: 'data.continent.country.city.latitude',
+              LONGITUDE: 'data.continent.country.city.longitude',
+              ACCURACY_RADIUS: 'data.continent.country.city.accuracy_radius',
+              METRO_CODE: 'data.continent.country.city.metro_code',
+              POSTAL_CODE: 'data.continent.country.city.postal_code',
+              TIMEZONE: {
+                NAME: 'data.continent.country.city.timezone.name',
+                TIME_NOW: 'data.continent.country.city.timezone.time_now'
+              }.freeze
+            }.freeze,
+            FLAG: {
+              IMG: 'data.continent.country.flag.img',
+              EMOJI: 'data.continent.country.flag.emoji',
+              EMOJI_UNICODE: 'data.continent.country.flag.emoji_unicode'
+            }.freeze,
+            CURRENCY: {
+              NAME: 'data.continent.country.currency.name',
+              CODE: 'data.continent.country.currency.code',
+              SYMBOL: 'data.continent.country.currency.symbol'
+            }.freeze
+          }.freeze
+        }.freeze,
+        REGISTERED_COUNTRY: {
+          NAME: 'data.registered_country.name',
+          CODE: 'data.registered_country.code',
+          GEONAME_ID: 'data.registered_country.geoname_id'
+        }.freeze,
+        ASN: {
+          NUMBER: 'data.asn.number',
+          NAME: 'data.asn.name'
+        }.freeze,
+        COMPLETION_TIME: {
+          MILISECONDS: 'data.completion_time.miliseconds',
+          SECONDS: 'data.completion_time.seconds'
+        }.freeze
+      }.freeze
+    }.freeze
+  end
+end

data/lib/ip2geo/data/messages.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Data
+    MESSAGES = {
+      conversions: {
+        'ip-address-is-required-to-convert-it' => 'IP address is required to convert it.',
+        'invalid-ip-address-so-we-could-not-convert-it' => 'Invalid IP address, so we could not convert it.',
+        'ip-addresses-are-required-to-convert-them' => 'IP addresses are required to convert them.',
+        'all-ip-addresses-are-invalid' => 'All IP addresses are invalid.',
+        'some-ip-addresses-are-invalid' => 'Some IP addresses are invalid.',
+        'conversion-id-is-required' => 'Conversion ID is required.',
+        'conversion-ids-are-required' => 'Conversion IDs are required.'
+      }
+    }.freeze
+
+    def self.translate(key)
+      keys = key.split('.')
+      result = MESSAGES
+
+      keys.each do |k|
+        result = result[k.to_sym] || result[k]
+        return key if result.nil?
+      end
+
+      result
+    end
+  end
+end

data/lib/ip2geo/data/states.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Data
+    class State
+      class << self
+        attr_accessor :auth_key, :version_update_message, :is_version_checked
+
+        def reset!
+          @auth_key = nil
+          @version_update_message = true
+          @is_version_checked = false
+        end
+      end
+
+      reset!
+    end
+  end
+end

data/lib/ip2geo/helpers/check_version.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module Ip2Geo
+  module Helpers
+    class CheckVersion
+      RUBYGEMS_API_URL = 'https://rubygems.org/api/v1/gems/ip2geo.json'
+
+      class << self
+        def call
+          return if Data::State.is_version_checked || !Data::State.version_update_message
+
+          Data::State.is_version_checked = true
+
+          current_version = Ip2Geo::VERSION
+          latest_version = fetch_latest_version
+
+          return unless current_version && latest_version
+          return if current_version == latest_version
+
+          display_update_message(current_version, latest_version)
+        rescue StandardError
+          # Silently fail - version check is non-critical
+        end
+
+        private
+
+        def fetch_latest_version
+          uri = URI.parse(RUBYGEMS_API_URL)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 5
+          http.read_timeout = 5
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          response = http.request(request)
+
+          return nil unless response.is_a?(Net::HTTPSuccess)
+
+          data = JSON.parse(response.body)
+          data['version']
+        rescue StandardError
+          nil
+        end
+
+        def display_update_message(current_version, latest_version)
+          box_width = 70
+          top_border = "\u250C#{"\u2500" * (box_width - 2)}\u2510"
+          bottom_border = "\u2514#{"\u2500" * (box_width - 2)}\u2518"
+
+          lines = [
+            '',
+            top_border,
+            center_text("\e[1m\e[33mUpdate available\e[0m \e[2m#{current_version} \u2192 #{latest_version}\e[0m", box_width),
+            center_text("Changelog: \e[36mhttps://docs.ip2geo.dev/sdk/changelogs\e[0m", box_width),
+            center_text("Run \e[32m`gem update ip2geo`\e[0m to update.", box_width),
+            center_text('', box_width),
+            center_text("Disable this warning using: \e[36mversion_update_message: false\e[0m on init.", box_width),
+            bottom_border,
+            ''
+          ]
+
+          lines.each { |line| warn line }
+        end
+
+        def center_text(text, box_width)
+          visible_length = text.gsub(/\e\[[0-9;]*m/, '').length
+          padding = [(box_width - 2 - visible_length) / 2, 0].max
+          right_padding = [box_width - 2 - padding - visible_length, 0].max
+
+          "\u2502#{' ' * padding}#{text}#{' ' * right_padding}\u2502"
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/helpers/http.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+
+module Ip2Geo
+  module Helpers
+    class Http
+      class << self
+        def request(endpoint, body = nil)
+          uri = URI.parse(endpoint)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.ssl_version = :TLSv1_2
+          http.open_timeout = 30
+          http.read_timeout = 30
+
+          # Fix for macOS certificate CRL verification issues
+          cert_store = OpenSSL::X509::Store.new
+          cert_store.set_default_paths
+          http.cert_store = cert_store
+
+          headers = {
+            Data::HEADER_TYPES[:CONTENT_TYPE] => Data::FILE_FORMATS[:APPLICATION_JSON],
+            Data::HEADER_KEYS[:X_API_KEY] => Data::State.auth_key
+          }
+
+          if body && !body.empty?
+            request = Net::HTTP::Post.new(uri.request_uri, headers)
+            request.body = body.to_json
+          else
+            request = Net::HTTP::Get.new(uri.request_uri, headers)
+          end
+
+          response = http.request(request)
+          JSON.parse(response.body, symbolize_names: false)
+        rescue StandardError => e
+          warn "[Ip2Geo::Http] Error: #{e.message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/helpers/ip_validation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Helpers
+    class IpValidation
+      IPV4_REGEX = /^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/.freeze
+      IPV6_REGEX = /^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$|^([0-9a-fA-F]{1,4}:){1,7}:$|^([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}$|^([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}$|^([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}$|^([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}$|^([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}$|^[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6}|:)$|^:((:[0-9a-fA-F]{1,4}){1,7}|:)$/.freeze
+
+      class << self
+        # Validate an IP address and return if it is IPv4 or IPv6.
+        #
+        # @param ip_address [String] The IP address to validate
+        # @return [Hash] A hash with :ip4 and :ip6 boolean values
+        def validate(ip_address)
+          return { ip4: false, ip6: false } unless ip_address.is_a?(String)
+
+          {
+            ip4: IPV4_REGEX.match?(ip_address),
+            ip6: IPV6_REGEX.match?(ip_address)
+          }
+        rescue StandardError => e
+          warn "[Ip2Geo::IpValidation] Error: #{e.message}"
+          { ip4: false, ip6: false }
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/convert_ip.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class ConvertIP
+      class << self
+        # Get geo information from an IP address.
+        #
+        # @param options [Hash] The options for the conversion
+        # @option options [String] :ip The IP address to retrieve geo information for (required)
+        # @option options [Boolean] :convert_only If true, stores minimal data and charges $0.001 per conversion
+        #   instead of $0.0005 (default: false)
+        # @return [Hash, nil] The API response containing geo data, or nil if the request fails
+        def call(options = {})
+          ip = options[:ip]
+          convert_only = options.fetch(:convert_only, false)
+
+          unless ip
+            return error_response(
+              Data.translate('conversions.ip-address-is-required-to-convert-it')
+            )
+          end
+
+          validation = Helpers::IpValidation.validate(ip)
+
+          unless validation[:ip4] || validation[:ip6]
+            return error_response(
+              Data.translate('conversions.invalid-ip-address-so-we-could-not-convert-it')
+            )
+          end
+
+          url = "#{Data::API_ENDPOINT}#{Data::ENDPOINTS[:CONVERT]}?ip=#{ip}&convertOnly=#{convert_only}"
+          Helpers::Http.request(url)
+        rescue StandardError => e
+          warn "[Ip2Geo::ConvertIP] Error: #{e.message}"
+          nil
+        end
+
+        private
+
+        def error_response(message)
+          {
+            'success' => false,
+            'message' => message,
+            'code' => 400,
+            'data' => nil,
+            '_req' => {
+              'reqId' => nil,
+              'resTime' => 0
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/convert_ips.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class ConvertIPs
+      class << self
+        # Get geo information from multiple IP addresses.
+        #
+        # @param options [Hash] The options for the conversion
+        # @option options [Array<String>] :ips An array of IP addresses to retrieve geo information for (required)
+        # @option options [Boolean] :convert_only If true, stores minimal data and charges $0.001 per conversion
+        #   instead of $0.0005 (default: false)
+        # @return [Hash, nil] The API response containing geo data for all IPs, or nil if the request fails
+        def call(options = {})
+          ips = options[:ips]
+          convert_only = options.fetch(:convert_only, false)
+
+          unless ips.is_a?(Array) && !ips.empty?
+            return error_response(
+              Data.translate('conversions.ip-addresses-are-required-to-convert-them'),
+              nil
+            )
+          end
+
+          valid_ips = []
+          invalid_ips = []
+
+          ips.each do |ip|
+            validation = Helpers::IpValidation.validate(ip)
+            if validation[:ip4] || validation[:ip6]
+              valid_ips << ip
+            else
+              invalid_ips << ip
+            end
+          end
+
+          if invalid_ips.any?
+            all_invalid = invalid_ips.length == ips.length
+            message = all_invalid ? 'conversions.all-ip-addresses-are-invalid' : 'conversions.some-ip-addresses-are-invalid'
+
+            return error_response(
+              Data.translate(message),
+              invalid_ips.map { |ip| { 'ip' => ip, 'conversion' => nil } }
+            )
+          end
+
+          url = "#{Data::API_ENDPOINT}#{Data::ENDPOINTS[:CONVERT]}"
+          body = { ips: ips, convertOnly: convert_only }
+
+          Helpers::Http.request(url, body)
+        rescue StandardError => e
+          warn "[Ip2Geo::ConvertIPs] Error: #{e.message}"
+          nil
+        end
+
+        private
+
+        def error_response(message, data)
+          {
+            'success' => false,
+            'message' => message,
+            'code' => 400,
+            'data' => data,
+            '_req' => {
+              'reqId' => nil,
+              'resTime' => 0
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/get_conversion.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class GetConversion
+      class << self
+        # Retrieve a single conversion by its ID.
+        #
+        # @param options [Hash] The options for retrieving the conversion
+        # @option options [String] :conversion_id The unique identifier of the conversion to retrieve (required)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @return [Hash, nil] The API response containing conversion data, or nil if the request fails
+        def call(options = {})
+          conversion_id = options[:conversion_id]
+          select = options[:select]
+
+          unless conversion_id
+            return error_response(
+              Data.translate('conversions.conversion-id-is-required')
+            )
+          end
+
+          params = []
+          params << "select=#{select.join(',')}" if select.is_a?(Array) && !select.empty?
+
+          query_string = params.empty? ? '' : "?#{params.join('&')}"
+          url = "#{Data::API_ENDPOINT}#{Data::ENDPOINTS[:CONVERSIONS][:GET]}#{query_string}"
+
+          Helpers::Http.request(url, { conversionId: conversion_id })
+        rescue StandardError => e
+          warn "[Ip2Geo::GetConversion] Error: #{e.message}"
+          nil
+        end
+
+        private
+
+        def error_response(message)
+          {
+            'success' => false,
+            'message' => message,
+            'code' => 400,
+            'data' => nil,
+            '_req' => {
+              'reqId' => nil,
+              'resTime' => 0
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/get_conversions.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class GetConversions
+      class << self
+        # Retrieve multiple conversions by their IDs.
+        #
+        # @param options [Hash] The options for retrieving conversions
+        # @option options [Array<String>] :conversion_ids An array of unique identifiers to retrieve (required)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @return [Hash, nil] The API response containing conversions data, or nil if the request fails
+        def call(options = {})
+          conversion_ids = options[:conversion_ids]
+          select = options[:select]
+
+          unless conversion_ids.is_a?(Array) && !conversion_ids.empty?
+            return error_response(
+              Data.translate('conversions.conversion-ids-are-required')
+            )
+          end
+
+          params = []
+          params << "select=#{select.join(',')}" if select.is_a?(Array) && !select.empty?
+
+          query_string = params.empty? ? '' : "?#{params.join('&')}"
+          url = "#{Data::API_ENDPOINT}#{Data::ENDPOINTS[:CONVERSIONS][:GET]}#{query_string}"
+
+          Helpers::Http.request(url, { conversionIds: conversion_ids })
+        rescue StandardError => e
+          warn "[Ip2Geo::GetConversions] Error: #{e.message}"
+          nil
+        end
+
+        private
+
+        def error_response(message)
+          {
+            'success' => false,
+            'message' => message,
+            'code' => 400,
+            'data' => nil,
+            '_req' => {
+              'reqId' => nil,
+              'resTime' => 0
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/init.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class Init
+      class << self
+        # Initializes the SDK with the given API key.
+        #
+        # @param key [String] The API key used to authenticate with Ip2Geo
+        # @param options [Hash] Optional configuration
+        # @option options [Boolean] :version_update_message Whether to display version update messages (default: true)
+        # @return [Boolean] Whether the initialization was successful
+        def call(key, options = {})
+          Data::State.auth_key = key
+          Data::State.version_update_message = options.fetch(:version_update_message, true)
+
+          Helpers::CheckVersion.call
+
+          true
+        rescue StandardError => e
+          Data::State.reset!
+          warn "[Ip2Geo::Init] Error: #{e.message}"
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo/methods/list_conversions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ip2Geo
+  module Methods
+    class ListConversions
+      class << self
+        # List conversions with pagination and optional filtering.
+        #
+        # @param options [Hash] The options for listing conversions
+        # @option options [Integer] :offset The number of conversions to skip (default: 0)
+        # @option options [Integer] :limit The maximum number of conversions to return (default: 50, max: 50)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @option options [String] :ip_search Filter conversions by IP address
+        # @return [Hash, nil] The API response containing conversions list with pagination info, or nil if fails
+        def call(options = {})
+          offset = options.fetch(:offset, 0)
+          limit = options.fetch(:limit, 50)
+          select = options[:select]
+          ip_search = options[:ip_search]
+
+          params = []
+          params << "offset=#{offset}" if offset.positive?
+          params << "limit=#{limit}" if limit != 50
+          params << "select=#{select.join(',')}" if select.is_a?(Array) && !select.empty?
+          params << "ipSearch=#{ip_search}" if ip_search
+
+          query_string = params.empty? ? '' : "?#{params.join('&')}"
+          url = "#{Data::API_ENDPOINT}#{Data::ENDPOINTS[:CONVERSIONS][:LIST]}#{query_string}"
+
+          Helpers::Http.request(url)
+        rescue StandardError => e
+          warn "[Ip2Geo::ListConversions] Error: #{e.message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ip2geo.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Ip2Geo Ruby SDK
+# Official Ruby SDK for Ip2Geo - IP to Geolocation API
+#
+# @example Basic usage
+#   require 'ip2geo'
+#
+#   # Initialize with your API key
+#   Ip2Geo.init('your-api-key')
+#
+#   # Convert a single IP address
+#   result = Ip2Geo.convert_ip(ip: '8.8.8.8')
+#
+#   # Convert multiple IP addresses
+#   result = Ip2Geo.convert_ips(ips: ['8.8.8.8', '1.1.1.1'])
+#
+#   # List your conversions
+#   result = Ip2Geo.list_conversions(limit: 10)
+
+require_relative 'ip2geo/data/constants'
+require_relative 'ip2geo/data/states'
+require_relative 'ip2geo/data/messages'
+require_relative 'ip2geo/helpers/http'
+require_relative 'ip2geo/helpers/ip_validation'
+require_relative 'ip2geo/helpers/check_version'
+require_relative 'ip2geo/methods/init'
+require_relative 'ip2geo/methods/convert_ip'
+require_relative 'ip2geo/methods/convert_ips'
+require_relative 'ip2geo/methods/get_conversion'
+require_relative 'ip2geo/methods/get_conversions'
+require_relative 'ip2geo/methods/list_conversions'
+
+module Ip2Geo
+    VERSION = '0.0.1'
+
+    class << self
+        # Initializes the SDK with the given API key.
+        #
+        # @param key [String] The API key used to authenticate with Ip2Geo
+        # @param options [Hash] Optional configuration
+        # @option options [Boolean] :version_update_message Whether to display version update messages (default: true)
+        # @return [Boolean] Whether the initialization was successful
+        #
+        # @example
+        #   Ip2Geo.init('your-api-key')
+        #   Ip2Geo.init('your-api-key', version_update_message: false)
+        def init(key, options = {})
+            Methods::Init.call(key, options)
+        end
+
+        # Get geo information from an IP address.
+        #
+        # @param options [Hash] The options for the conversion
+        # @option options [String] :ip The IP address to retrieve geo information for (required)
+        # @option options [Boolean] :convert_only If true, stores minimal data (default: false)
+        # @return [Hash, nil] The API response containing geo data
+        #
+        # @example
+        #   result = Ip2Geo.convert_ip(ip: '8.8.8.8')
+        #   result = Ip2Geo.convert_ip(ip: '8.8.8.8', convert_only: true)
+        def convert_ip(options = {})
+            Methods::ConvertIP.call(options)
+        end
+
+        # Get geo information from multiple IP addresses.
+        #
+        # @param options [Hash] The options for the conversion
+        # @option options [Array<String>] :ips An array of IP addresses (required)
+        # @option options [Boolean] :convert_only If true, stores minimal data (default: false)
+        # @return [Hash, nil] The API response containing geo data for all IPs
+        #
+        # @example
+        #   result = Ip2Geo.convert_ips(ips: ['8.8.8.8', '1.1.1.1'])
+        def convert_ips(options = {})
+            Methods::ConvertIPs.call(options)
+        end
+
+        # Retrieve a single conversion by its ID.
+        #
+        # @param options [Hash] The options for retrieving the conversion
+        # @option options [String] :conversion_id The unique identifier (required)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @return [Hash, nil] The API response containing conversion data
+        #
+        # @example
+        #   result = Ip2Geo.get_conversion(conversion_id: 'abc123')
+        #   result = Ip2Geo.get_conversion(conversion_id: 'abc123', select: ['id', 'data.ip'])
+        def get_conversion(options = {})
+            Methods::GetConversion.call(options)
+        end
+
+        # Retrieve multiple conversions by their IDs.
+        #
+        # @param options [Hash] The options for retrieving conversions
+        # @option options [Array<String>] :conversion_ids An array of unique identifiers (required)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @return [Hash, nil] The API response containing conversions data
+        #
+        # @example
+        #   result = Ip2Geo.get_conversions(conversion_ids: ['abc123', 'def456'])
+        def get_conversions(options = {})
+            Methods::GetConversions.call(options)
+        end
+
+        # List conversions with pagination and optional filtering.
+        #
+        # @param options [Hash] The options for listing conversions
+        # @option options [Integer] :offset The number of conversions to skip (default: 0)
+        # @option options [Integer] :limit The maximum number to return (default: 50, max: 50)
+        # @option options [Array<String>] :select Optional array of property names to return
+        # @option options [String] :ip_search Filter conversions by IP address
+        # @return [Hash, nil] The API response containing conversions list with pagination info
+        #
+        # @example
+        #   result = Ip2Geo.list_conversions
+        #   result = Ip2Geo.list_conversions(limit: 10, offset: 20)
+        #   result = Ip2Geo.list_conversions(ip_search: '8.8.8.8')
+        def list_conversions(options = {})
+            Methods::ListConversions.call(options)
+        end
+
+        # Validate an IP address and return if it is IPv4 or IPv6.
+        #
+        # @param ip_address [String] The IP address to validate
+        # @return [Hash] A hash with :ip4 and :ip6 boolean values
+        #
+        # @example
+        #   result = Ip2Geo.ip_validation('8.8.8.8')
+        #   # => { ip4: true, ip6: false }
+        def ip_validation(ip_address)
+            Helpers::IpValidation.validate(ip_address)
+        end
+
+        # SELECT constants for field selection
+        #
+        # @return [Hash] The SELECT constants
+        #
+        # @example
+        #   Ip2Geo.select[:CONVERSION][:ID]
+        #   # => 'id'
+        #   Ip2Geo.select[:DATA][:CONTINENT][:COUNTRY][:NAME]
+        #   # => 'data.continent.country.name'
+        def select
+            Data::SELECT
+        end
+    end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: ip2geo
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ip2Geo
+bindir: bin
+cert_chain: []
+date: 2026-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A lightweight Ruby client for the Ip2Geo cloud service. Get accurate
+  geolocation data for IP addresses including continent, country, city, timezone,
+  ASN, and more.
+email:
+- support@ip2geo.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ip2geo.gemspec
+- lib/ip2geo.rb
+- lib/ip2geo/data/constants.rb
+- lib/ip2geo/data/messages.rb
+- lib/ip2geo/data/states.rb
+- lib/ip2geo/helpers/check_version.rb
+- lib/ip2geo/helpers/http.rb
+- lib/ip2geo/helpers/ip_validation.rb
+- lib/ip2geo/methods/convert_ip.rb
+- lib/ip2geo/methods/convert_ips.rb
+- lib/ip2geo/methods/get_conversion.rb
+- lib/ip2geo/methods/get_conversions.rb
+- lib/ip2geo/methods/init.rb
+- lib/ip2geo/methods/list_conversions.rb
+homepage: https://ip2geo.dev
+licenses:
+- Nonstandard
+metadata:
+  homepage_uri: https://ip2geo.dev
+  changelog_uri: https://docs.ip2geo.dev/changelog
+  documentation_uri: https://docs.ip2geo.dev
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Official Ruby SDK for Ip2Geo - IP to Geolocation API.
+test_files: []