xposedornot 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4c6f59511c16092f89dfb4fdcd4895ed02bcf0211c64e37d69590b0779a1dac
+  data.tar.gz: c72af4274f83ad204506429f0125a59c22107aecc43d642901bd037b31b77951
+SHA512:
+  metadata.gz: 7dfcc6cd13edcf040601f28b05cdef3561837a90a968008deed98d4931465255c566796f4efa09958249b64de010f1c132884c007dc2ea96f11154369a947081
+  data.tar.gz: 43b6a2f5634af3d7edd0a3761648cd88c6197255da94062eccf4a75c6a2af9554eb4c4d1a11b07b86bc4d0a5674f7550ed3d0918ca0716a1b3821312ff60d1dc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XposedOrNot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,287 @@
+<p align="center">
+  <a href="https://xposedornot.com">
+    <img src="https://xposedornot.com/static/logos/xon.png" alt="XposedOrNot" width="200">
+  </a>
+</p>
+
+<h1 align="center">xposedornot</h1>
+
+<p align="center">
+  Official Ruby SDK for the <a href="https://xposedornot.com">XposedOrNot</a> API<br>
+  <em>Check if your email has been exposed in data breaches</em>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/xposedornot"><img src="https://img.shields.io/gem/v/xposedornot.svg" alt="Gem Version"></a>
+  <a href="https://github.com/XposedOrNot/XposedOrNot-Ruby/actions"><img src="https://img.shields.io/github/actions/workflow/status/XposedOrNot/XposedOrNot-Ruby/build.yml?branch=main" alt="Build Status"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.ruby-lang.org"><img src="https://img.shields.io/badge/Ruby-%3E%3D%203.0-red.svg" alt="Ruby Version"></a>
+</p>
+
+---
+
+> **Note:** This SDK uses the free public API from [XposedOrNot.com](https://xposedornot.com) - a free service to check if your email has been compromised in data breaches. Visit the [XposedOrNot website](https://xposedornot.com) to learn more about the service and check your email manually.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [check_email](#check_emailemail)
+  - [get_breaches](#get_breachesdomain)
+  - [breach_analytics](#breach_analyticsemail)
+  - [check_password](#check_passwordpassword)
+- [Error Handling](#error-handling)
+- [Rate Limits](#rate-limits)
+- [Configuration](#configuration)
+- [Contributing](#contributing)
+- [License](#license)
+- [Links](#links)
+
+---
+
+## Features
+
+- **Simple API** - Easy-to-use methods for checking email breaches and password exposure
+- **Detailed Analytics** - Get breach details, risk scores, and metrics
+- **Password Safety** - Check password exposure using k-anonymity (only a hash prefix is sent)
+- **Error Handling** - Custom error classes for different scenarios
+- **Configurable** - Timeout, retries, custom headers, and Plus API support
+- **Secure** - HTTPS enforced, input validation, no sensitive data logging
+
+## Installation
+
+```bash
+gem install xposedornot
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'xposedornot'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+
+## Quick Start
+
+```ruby
+require 'xposedornot'
+
+client = XposedOrNot::Client.new
+
+# Check if an email has been breached
+result = client.check_email('test@example.com')
+
+if result.breached?
+  puts "Email found in #{result.breaches.length} breaches:"
+  result.breaches.each { |breach| puts "  - #{breach}" }
+else
+  puts 'Good news! Email not found in any known breaches.'
+end
+```
+
+## API Reference
+
+### Constructor
+
+```ruby
+client = XposedOrNot::Client.new(api_key: nil, **options)
+```
+
+See [Configuration](#configuration) for all available options.
+
+### Methods
+
+#### `check_email(email)`
+
+Check if an email address has been exposed in any data breaches. When an API key is configured, uses the Plus API for detailed results including `breach_id` and `password_risk`. Otherwise, uses the free API.
+
+```ruby
+# Free API
+client = XposedOrNot::Client.new
+result = client.check_email('user@example.com')
+puts result.breached?   # => true / false
+puts result.breaches     # => ["Breach1", "Breach2"]
+
+# Plus API (detailed results)
+client = XposedOrNot::Client.new(api_key: 'your-api-key')
+result = client.check_email('user@example.com')
+puts result.breaches.first.breach_id
+puts result.breaches.first.password_risk
+```
+
+#### `get_breaches(domain:)`
+
+Get a list of all known data breaches, optionally filtered by domain.
+
+```ruby
+# Get all breaches
+breaches = client.get_breaches
+
+# Filter by domain
+adobe_breaches = client.get_breaches(domain: 'adobe.com')
+
+breaches.each do |breach|
+  puts "#{breach.breach_id} - #{breach.domain} (#{breach.exposed_records} records)"
+end
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `domain` | `String` | Optional. Filter breaches by domain |
+
+**Returns:** `Array<Models::Breach>` with properties such as `breach_id`, `breached_date`, `domain`, `industry`, `exposed_data`, `exposed_records`, and `verified`.
+
+#### `breach_analytics(email)`
+
+Get detailed breach analytics for an email address, including breach summaries, metrics, and paste exposures.
+
+```ruby
+analytics = client.breach_analytics('user@example.com')
+
+puts analytics.breaches_details.length
+puts analytics.breaches_summary
+puts analytics.breach_metrics
+puts analytics.exposed_pastes
+```
+
+#### `check_password(password)`
+
+Check if a password has been exposed in data breaches. The password is hashed locally using Keccak-512 and only the first 10 hex characters of the digest are sent to the API, preserving anonymity via k-anonymity.
+
+```ruby
+result = client.check_password('mypassword')
+
+if result.exposed?
+  puts "This password has been seen #{result.count} time(s) in breaches!"
+else
+  puts 'Password not found in any known breaches.'
+end
+```
+
+## Error Handling
+
+The library provides custom error classes for different scenarios:
+
+```ruby
+begin
+  result = client.check_email('test@example.com')
+rescue XposedOrNot::ValidationError => e
+  puts "Invalid input: #{e.message}"
+rescue XposedOrNot::RateLimitError
+  puts 'Rate limited. Try again later.'
+rescue XposedOrNot::NotFoundError
+  puts 'Email not found in any breaches.'
+rescue XposedOrNot::AuthenticationError
+  puts 'Invalid API key.'
+rescue XposedOrNot::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue XposedOrNot::APIError => e
+  puts "API error (#{e.status}): #{e.message}"
+end
+```
+
+### Error Classes
+
+| Error Class | Description |
+|-------------|-------------|
+| `XposedOrNotError` | Base error class for all errors |
+| `ValidationError` | Invalid input (e.g., malformed email, blank password) |
+| `RateLimitError` | API rate limit exceeded (HTTP 429) |
+| `NotFoundError` | Resource not found (HTTP 404) |
+| `AuthenticationError` | Authentication failed (HTTP 401/403) |
+| `NetworkError` | Network connectivity issues or timeouts |
+| `APIError` | General API error (exposes `.status` for the HTTP code) |
+
+## Rate Limits
+
+The XposedOrNot API has the following rate limits:
+
+- 2 requests per second
+- 50-100 requests per hour
+- 100-1000 requests per day
+
+The client includes automatic retry with exponential backoff for `429` responses and built-in client-side throttling (1 request per second) for the free API.
+
+## Configuration
+
+```ruby
+client = XposedOrNot::Client.new(
+  api_key:        'your-api-key',  # Optional. Enables Plus API access
+  timeout:        15,              # Request timeout in seconds (default: 30)
+  max_retries:    5,               # Max retries on 429 responses (default: 3)
+  custom_headers: { 'X-Custom' => 'value' }
+)
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | `String` | `nil` | API key for Plus API access |
+| `base_url` | `String` | `https://api.xposedornot.com` | Base URL for the free API |
+| `plus_base_url` | `String` | `https://plus-api.xposedornot.com` | Base URL for the Plus API |
+| `passwords_base_url` | `String` | `https://passwords.xposedornot.com/api` | Base URL for the password API |
+| `timeout` | `Integer` | `30` | Request timeout in seconds |
+| `max_retries` | `Integer` | `3` | Max retry attempts on 429 responses |
+| `custom_headers` | `Hash` | `{}` | Custom headers for all requests |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/XposedOrNot/XposedOrNot-Ruby.git
+cd XposedOrNot-Ruby
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+## License
+
+MIT - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [XposedOrNot Website](https://xposedornot.com)
+- [API Documentation](https://xposedornot.com/api_doc)
+- [RubyGems Package](https://rubygems.org/gems/xposedornot)
+- [GitHub Repository](https://github.com/XposedOrNot/XposedOrNot-Ruby)
+- [XposedOrNot API Repository](https://github.com/XposedOrNot/XposedOrNot-API)
+
+---
+
+<p align="center">
+  Made with care by <a href="https://xposedornot.com">XposedOrNot</a>
+</p>

data/lib/xposedornot/client.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module XposedOrNot
+  # Main client for interacting with the XposedOrNot API.
+  #
+  # @example Free API usage
+  #   client = XposedOrNot::Client.new
+  #   result = client.check_email("test@example.com")
+  #
+  # @example Plus API usage
+  #   client = XposedOrNot::Client.new(api_key: "your-api-key")
+  #   result = client.check_email("test@example.com")
+  class Client
+    include Endpoints::Email
+    include Endpoints::Breaches
+    include Endpoints::Password
+
+    # @return [Configuration] the client configuration
+    attr_reader :config
+
+    # @param api_key [String, nil] API key for Plus API access
+    # @param options [Hash] additional configuration options
+    # @option options [String] :base_url override default free API base URL
+    # @option options [String] :plus_base_url override default Plus API base URL
+    # @option options [String] :passwords_base_url override default passwords API base URL
+    # @option options [Integer] :timeout request timeout in seconds
+    # @option options [Integer] :max_retries max retries on 429 responses
+    # @option options [Hash] :custom_headers additional headers
+    def initialize(api_key: nil, **options)
+      @config = Configuration.new(api_key: api_key, **options)
+      @last_request_time = nil
+      @mutex = Mutex.new
+    end
+
+    private
+
+    # Resolves the base URL for a given API target.
+    #
+    # @param base [Symbol] one of :free, :plus, :passwords
+    # @return [String]
+    def base_url_for(base)
+      case base
+      when :plus
+        @config.plus_base_url
+      when :passwords
+        @config.passwords_base_url
+      else
+        @config.base_url
+      end
+    end
+
+    # Enforces client-side rate limiting for free API (1 req/sec).
+    # Skipped when an API key is configured.
+    #
+    # @return [void]
+    def rate_limit!
+      return if @config.plus_api?
+
+      @mutex.synchronize do
+        if @last_request_time
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_request_time
+          sleep(1.0 - elapsed) if elapsed < 1.0
+        end
+        @last_request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # Builds a Faraday connection for the given base URL.
+    #
+    # @param url [String] the base URL
+    # @return [Faraday::Connection]
+    def connection(url)
+      Faraday.new(url: url) do |f|
+        f.request :retry,
+                  max: @config.max_retries,
+                  interval: 1,
+                  backoff_factor: 2,
+                  retry_statuses: [429],
+                  exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
+
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = @config.timeout
+
+        f.headers["Content-Type"] = "application/json"
+        f.headers["Accept"] = "application/json"
+        f.headers["x-api-key"] = @config.api_key if @config.plus_api?
+
+        @config.custom_headers.each do |key, value|
+          f.headers[key.to_s] = value.to_s
+        end
+
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Makes an HTTP request and handles error responses.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @param path [String] request path
+    # @param base [Symbol] API target (:free, :plus, :passwords)
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed JSON response
+    # @raise [RateLimitError, NotFoundError, AuthenticationError, APIError, NetworkError]
+    def request(method, path, base: :free, params: {})
+      rate_limit!
+
+      url = base_url_for(base)
+      conn = connection(url)
+
+      response = conn.public_send(method, path) do |req|
+        req.params.update(params) unless params.empty?
+      end
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise NetworkError, "Network error: #{e.message}"
+    end
+
+    # Parses and validates an HTTP response.
+    #
+    # @param response [Faraday::Response]
+    # @return [Hash] parsed JSON body
+    # @raise [RateLimitError, NotFoundError, AuthenticationError, APIError]
+    def handle_response(response)
+      case response.status
+      when 200..299
+        parse_body(response.body)
+      when 401, 403
+        raise AuthenticationError, "Authentication failed (HTTP #{response.status})"
+      when 404
+        raise NotFoundError, "Resource not found (HTTP 404)"
+      when 429
+        raise RateLimitError, "Rate limit exceeded (HTTP 429)"
+      else
+        raise APIError.new("API error (HTTP #{response.status}): #{response.body}", status: response.status)
+      end
+    end
+
+    # Safely parses a JSON response body.
+    #
+    # @param body [String] raw response body
+    # @return [Hash]
+    # @raise [APIError] if the body is not valid JSON
+    def parse_body(body)
+      return {} if body.nil? || body.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise APIError.new("Invalid JSON response: #{e.message}")
+    end
+  end
+end

data/lib/xposedornot/configuration.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  # Configuration for the XposedOrNot client.
+  #
+  # @example
+  #   config = XposedOrNot::Configuration.new(api_key: "my-key", timeout: 15)
+  class Configuration
+    # @return [String] base URL for the free API
+    attr_reader :base_url
+
+    # @return [String] base URL for the Plus (commercial) API
+    attr_reader :plus_base_url
+
+    # @return [String] base URL for the password check API
+    attr_reader :passwords_base_url
+
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] maximum number of retries on 429 responses
+    attr_accessor :max_retries
+
+    # @return [String, nil] API key for Plus API access
+    attr_accessor :api_key
+
+    # @return [Hash] custom headers to include in every request
+    attr_accessor :custom_headers
+
+    # @return [Boolean] whether to allow insecure (HTTP) base URLs
+    attr_reader :allow_insecure
+
+    DEFAULT_BASE_URL = "https://api.xposedornot.com"
+    DEFAULT_PLUS_BASE_URL = "https://plus-api.xposedornot.com"
+    DEFAULT_PASSWORDS_BASE_URL = "https://passwords.xposedornot.com/api"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    # @param base_url [String] base URL for the free API
+    # @param plus_base_url [String] base URL for the Plus API
+    # @param passwords_base_url [String] base URL for the password API
+    # @param timeout [Integer] request timeout in seconds
+    # @param max_retries [Integer] max retries on 429 responses
+    # @param api_key [String, nil] API key for Plus API
+    # @param custom_headers [Hash] additional headers
+    # @param allow_insecure [Boolean] allow HTTP URLs (default false, for testing only)
+    def initialize(
+      base_url: DEFAULT_BASE_URL,
+      plus_base_url: DEFAULT_PLUS_BASE_URL,
+      passwords_base_url: DEFAULT_PASSWORDS_BASE_URL,
+      timeout: DEFAULT_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      api_key: nil,
+      custom_headers: {},
+      allow_insecure: false
+    )
+      @allow_insecure = allow_insecure
+      @base_url = base_url
+      @plus_base_url = plus_base_url
+      @passwords_base_url = passwords_base_url
+      @timeout = timeout
+      @max_retries = max_retries
+      @api_key = api_key
+      @custom_headers = custom_headers
+
+      validate!
+    end
+
+    # Sets the base URL for the free API.
+    #
+    # @param url [String]
+    def base_url=(url)
+      validate_url!(:base_url, url)
+      @base_url = url
+    end
+
+    # Sets the base URL for the Plus API.
+    #
+    # @param url [String]
+    def plus_base_url=(url)
+      validate_url!(:plus_base_url, url)
+      @plus_base_url = url
+    end
+
+    # Sets the base URL for the password check API.
+    #
+    # @param url [String]
+    def passwords_base_url=(url)
+      validate_url!(:passwords_base_url, url)
+      @passwords_base_url = url
+    end
+
+    # Returns true if an API key is configured (Plus API access).
+    #
+    # @return [Boolean]
+    def plus_api?
+      !@api_key.nil? && !@api_key.empty?
+    end
+
+    # Redacts sensitive fields from the inspect output.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} api_key=#{@api_key ? '[REDACTED]' : 'nil'}>"
+    end
+
+    private
+
+    # Validates all URL fields use HTTPS unless allow_insecure is set.
+    #
+    # @raise [ValidationError] if any URL does not start with https://
+    def validate!
+      return if @allow_insecure
+
+      validate_url!(:base_url, @base_url)
+      validate_url!(:plus_base_url, @plus_base_url)
+      validate_url!(:passwords_base_url, @passwords_base_url)
+    end
+
+    # Validates a single URL uses HTTPS.
+    #
+    # @param name [Symbol] the field name (for error messages)
+    # @param url [String] the URL to validate
+    # @raise [ValidationError] if the URL does not start with https://
+    def validate_url!(name, url)
+      return if @allow_insecure
+      return if url.start_with?("https://")
+
+      raise ValidationError, "#{name} must use HTTPS (got: #{url})"
+    end
+  end
+end

data/lib/xposedornot/endpoints/breaches.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Endpoints
+    # Breaches listing endpoint.
+    module Breaches
+      # Get a list of all known breaches, optionally filtered by domain.
+      #
+      # @param domain [String, nil] optional domain to filter results
+      # @return [Array<Models::Breach>] list of breach records
+      def get_breaches(domain: nil)
+        params = {}
+        params[:domain] = domain if domain
+
+        response = request(:get, "/v1/breaches", base: :free, params: params)
+        raw = response["exposedBreaches"] || []
+        raw.map { |b| Models::Breach.new(b) }
+      end
+    end
+  end
+end

data/lib/xposedornot/endpoints/email.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module XposedOrNot
+  module Endpoints
+    # Email-related API endpoints.
+    module Email
+      # Check if an email has been exposed in data breaches.
+      #
+      # When an API key is configured, uses the Plus API for detailed results.
+      # Otherwise, uses the free API.
+      #
+      # @param email [String] the email address to check
+      # @return [Models::EmailBreachResponse, Models::EmailBreachDetailedResponse]
+      # @raise [ValidationError] if the email is invalid
+      # @raise [NotFoundError] if the email is not found in any breaches
+      def check_email(email)
+        Utils.validate_email(email)
+
+        if @config.plus_api?
+          check_email_detailed(email)
+        else
+          check_email_free(email)
+        end
+      end
+
+      # Get breach analytics for an email address.
+      #
+      # @param email [String] the email address to analyze
+      # @return [Models::BreachAnalyticsResponse]
+      # @raise [ValidationError] if the email is invalid
+      def breach_analytics(email)
+        Utils.validate_email(email)
+
+        response = request(:get, "/v1/breach-analytics", base: :free, params: { email: email })
+        Models::BreachAnalyticsResponse.new(response)
+      end
+
+      private
+
+      # @param email [String]
+      # @return [Models::EmailBreachResponse]
+      def check_email_free(email)
+        response = request(:get, "/v1/check-email/#{URI.encode_www_form_component(email)}", base: :free)
+        Models::EmailBreachResponse.new(response)
+      end
+
+      # @param email [String]
+      # @return [Models::EmailBreachDetailedResponse]
+      def check_email_detailed(email)
+        response = request(:get, "/v3/check-email/#{URI.encode_www_form_component(email)}", base: :plus, params: { detailed: true })
+        Models::EmailBreachDetailedResponse.new(response)
+      end
+    end
+  end
+end

data/lib/xposedornot/endpoints/password.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Endpoints
+    # Password exposure check endpoint.
+    module Password
+      # Check if a password has been exposed in data breaches.
+      #
+      # The password is hashed locally using Keccak-512 and only the first
+      # 10 hex characters of the digest are sent to the API for an anonymous
+      # lookup.
+      #
+      # @param password [String] the plaintext password to check
+      # @return [Models::PasswordCheckResponse]
+      # @raise [ValidationError] if the password is blank
+      def check_password(password)
+        Utils.validate_password(password)
+
+        hash_prefix = Utils.keccak_hash_prefix(password)
+        response = request(:get, "/v1/pass/anon/#{hash_prefix}", base: :passwords)
+        Models::PasswordCheckResponse.new(response)
+      end
+    end
+  end
+end

data/lib/xposedornot/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  # Base error class for all XposedOrNot errors.
+  class XposedOrNotError < StandardError; end
+
+  # Raised when the API returns a 429 Too Many Requests response.
+  class RateLimitError < XposedOrNotError; end
+
+  # Raised when the requested resource is not found (404).
+  class NotFoundError < XposedOrNotError; end
+
+  # Raised when authentication fails (401/403).
+  class AuthenticationError < XposedOrNotError; end
+
+  # Raised when input validation fails before making a request.
+  class ValidationError < XposedOrNotError; end
+
+  # Raised when a network-level error occurs (timeouts, connection refused, etc.).
+  class NetworkError < XposedOrNotError; end
+
+  # Raised when the API returns an unexpected error response.
+  class APIError < XposedOrNotError
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status
+
+    # @param message [String] the error message
+    # @param status [Integer, nil] the HTTP status code
+    def initialize(message = nil, status: nil)
+      @status = status
+      super(message)
+    end
+  end
+end

data/lib/xposedornot/models/breach.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # Represents a single data breach record.
+    class Breach
+      # @return [String] unique breach identifier
+      attr_reader :breach_id
+
+      # @return [String] date the breach occurred
+      attr_reader :breached_date
+
+      # @return [String] domain affected by the breach
+      attr_reader :domain
+
+      # @return [String] industry of the breached organization
+      attr_reader :industry
+
+      # @return [String] types of data exposed
+      attr_reader :exposed_data
+
+      # @return [Integer] number of records exposed
+      attr_reader :exposed_records
+
+      # @return [Boolean] whether the breach is verified
+      attr_reader :verified
+
+      # @return [String, nil] URL of the breach logo
+      attr_reader :logo
+
+      # @return [String, nil] risk level of password exposure
+      attr_reader :password_risk
+
+      # @return [Boolean, nil] whether the breach is searchable
+      attr_reader :searchable
+
+      # @return [String, nil] description of the exposure
+      attr_reader :xposure_desc
+
+      # @param data [Hash] raw breach data from the API
+      def initialize(data)
+        @breach_id = data["breachID"] || data["breach_id"]
+        @breached_date = data["breachedDate"] || data["breached_date"]
+        @domain = data["domain"]
+        @industry = data["industry"]
+        @exposed_data = data["exposedData"] || data["xposed_data"]
+        @exposed_records = data["exposedRecords"] || data["xposed_records"]
+        @verified = data["verified"]
+        @logo = data["logo"]
+        @password_risk = data["password_risk"]
+        @searchable = data["searchable"]
+        @xposure_desc = data["xposure_desc"]
+      end
+
+      # @return [Hash] hash representation of the breach
+      def to_h
+        {
+          breach_id: @breach_id,
+          breached_date: @breached_date,
+          domain: @domain,
+          industry: @industry,
+          exposed_data: @exposed_data,
+          exposed_records: @exposed_records,
+          verified: @verified,
+          logo: @logo,
+          password_risk: @password_risk,
+          searchable: @searchable,
+          xposure_desc: @xposure_desc
+        }.compact
+      end
+    end
+  end
+end

data/lib/xposedornot/models/breach_analytics_response.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # Response from the breach analytics endpoint.
+    class BreachAnalyticsResponse
+      # @return [Array<Breach>] detailed breach records
+      attr_reader :breaches_details
+
+      # @return [Hash] summary of breaches
+      attr_reader :breaches_summary
+
+      # @return [Hash] breach metrics
+      attr_reader :breach_metrics
+
+      # @return [Hash] pastes summary
+      attr_reader :pastes_summary
+
+      # @return [Array<Hash>] exposed pastes
+      attr_reader :exposed_pastes
+
+      # @param data [Hash] raw response data from the API
+      def initialize(data)
+        exposed = data["ExposedBreaches"] || {}
+        details = exposed["breaches_details"] || []
+        @breaches_details = details.map { |b| Breach.new(b) }
+        @breaches_summary = data["BreachesSummary"] || {}
+        @breach_metrics = data["BreachMetrics"] || {}
+        @pastes_summary = data["PastesSummary"] || {}
+        @exposed_pastes = data["ExposedPastes"] || []
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        {
+          breaches_details: @breaches_details.map(&:to_h),
+          breaches_summary: @breaches_summary,
+          breach_metrics: @breach_metrics,
+          pastes_summary: @pastes_summary,
+          exposed_pastes: @exposed_pastes
+        }
+      end
+    end
+  end
+end

data/lib/xposedornot/models/email_breach_detailed_response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # Response from the Plus API detailed email breach check endpoint.
+    class EmailBreachDetailedResponse
+      # @return [String] status from the API
+      attr_reader :status
+
+      # @return [String] the queried email address
+      attr_reader :email
+
+      # @return [Array<Breach>] detailed breach records
+      attr_reader :breaches
+
+      # @param data [Hash] raw response data from the Plus API
+      def initialize(data)
+        @status = data["status"]
+        @email = data["email"]
+        raw_breaches = data["breaches"] || []
+        @breaches = raw_breaches.map { |b| Breach.new(b) }
+      end
+
+      # @return [Boolean] true if the email was found in any breaches
+      def breached?
+        !@breaches.empty?
+      end
+
+      # @return [Integer] number of breaches found
+      def count
+        @breaches.length
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        {
+          status: @status,
+          email: @email,
+          breaches: @breaches.map(&:to_h),
+          breached: breached?,
+          count: count
+        }
+      end
+    end
+  end
+end

data/lib/xposedornot/models/email_breach_response.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # Response from the free email breach check endpoint.
+    class EmailBreachResponse
+      # @return [Array<String>] list of breach names
+      attr_reader :breaches
+
+      # @param data [Hash] raw response data from the API
+      def initialize(data)
+        raw = data["breaches"]
+        @breaches = if raw.is_a?(Array) && raw.first.is_a?(Array)
+                      raw.flatten
+                    elsif raw.is_a?(Array)
+                      raw
+                    else
+                      []
+                    end
+      end
+
+      # @return [Boolean] true if the email was found in any breaches
+      def breached?
+        !@breaches.empty?
+      end
+
+      # @return [Integer] number of breaches found
+      def count
+        @breaches.length
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        { breaches: @breaches, breached: breached?, count: count }
+      end
+    end
+  end
+end

data/lib/xposedornot/models/password_check_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # Response from the password exposure check endpoint.
+    class PasswordCheckResponse
+      # @return [String] the anonymous hash prefix used for the search
+      attr_reader :anon
+
+      # @return [String] character composition breakdown (e.g. "D:3;A:8;S:0;L:11")
+      attr_reader :char
+
+      # @return [Integer] number of times the password was seen in breaches
+      attr_reader :count
+
+      # @param data [Hash] raw response data from the API
+      def initialize(data)
+        search = data["SearchPassAnon"] || {}
+        @anon = search["anon"]
+        @char = search["char"]
+        @count = (search["count"] || "0").to_i
+      end
+
+      # @return [Boolean] true if the password has been exposed
+      def exposed?
+        @count.positive?
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        { anon: @anon, char: @char, count: @count, exposed: exposed? }
+      end
+    end
+  end
+end

data/lib/xposedornot/utils.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "digest/keccak"
+
+module XposedOrNot
+  # Utility methods for the XposedOrNot client.
+  module Utils
+    EMAIL_REGEX = /\A[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}\z/
+
+    module_function
+
+    # Validates that the given string is a plausible email address.
+    #
+    # @param email [String] the email address to validate
+    # @raise [ValidationError] if the email is invalid
+    # @return [void]
+    def validate_email(email)
+      raise ValidationError, "Email must be a non-empty string" if email.nil? || email.strip.empty?
+      raise ValidationError, "Invalid email format: #{email}" unless email.match?(EMAIL_REGEX)
+    end
+
+    # Validates that the given string is a non-empty password.
+    #
+    # @param password [String] the password to validate
+    # @raise [ValidationError] if the password is blank
+    # @return [void]
+    def validate_password(password)
+      raise ValidationError, "Password must be a non-empty string" if password.nil? || password.empty?
+    end
+
+    # Hashes a password with original Keccak-512 and returns the first 10 hex
+    # characters of the digest (the "anonymous prefix").
+    #
+    # @param password [String] the plaintext password
+    # @return [String] first 10 hex characters of the Keccak-512 digest
+    def keccak_hash_prefix(password)
+      digest = Digest::Keccak.new(512)
+      full_hash = digest.hexdigest(password)
+      full_hash[0, 10]
+    end
+  end
+end

data/lib/xposedornot/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  VERSION = "1.0.0"
+end

data/lib/xposedornot.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "xposedornot/version"
+require_relative "xposedornot/errors"
+require_relative "xposedornot/configuration"
+require_relative "xposedornot/utils"
+require_relative "xposedornot/models/breach"
+require_relative "xposedornot/models/email_breach_response"
+require_relative "xposedornot/models/email_breach_detailed_response"
+require_relative "xposedornot/models/breach_analytics_response"
+require_relative "xposedornot/models/password_check_response"
+require_relative "xposedornot/endpoints/email"
+require_relative "xposedornot/endpoints/breaches"
+require_relative "xposedornot/endpoints/password"
+require_relative "xposedornot/client"
+
+# XposedOrNot API client library for checking data breaches.
+#
+# @example
+#   client = XposedOrNot::Client.new
+#   result = client.check_email("test@example.com")
+module XposedOrNot
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: xposedornot
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- XposedOrNot
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  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'
+- !ruby/object:Gem::Dependency
+  name: digest-keccak
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: A Ruby gem for interacting with the XposedOrNot API to check email breaches,
+  password exposure, and breach analytics. Supports both the free and commercial Plus
+  API.
+email:
+- deva@xposedornot.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/xposedornot.rb
+- lib/xposedornot/client.rb
+- lib/xposedornot/configuration.rb
+- lib/xposedornot/endpoints/breaches.rb
+- lib/xposedornot/endpoints/email.rb
+- lib/xposedornot/endpoints/password.rb
+- lib/xposedornot/errors.rb
+- lib/xposedornot/models/breach.rb
+- lib/xposedornot/models/breach_analytics_response.rb
+- lib/xposedornot/models/email_breach_detailed_response.rb
+- lib/xposedornot/models/email_breach_response.rb
+- lib/xposedornot/models/password_check_response.rb
+- lib/xposedornot/utils.rb
+- lib/xposedornot/version.rb
+homepage: https://xposedornot.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://xposedornot.com
+  source_code_uri: https://github.com/XposedOrNot/XposedOrNot-Ruby
+  changelog_uri: https://github.com/XposedOrNot/XposedOrNot-Ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.4.20
+signing_key:
+specification_version: 4
+summary: Ruby client library for the XposedOrNot data breach API
+test_files: []