xposedornot 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f9cdb8cf4574407c468bb74827549048bf41754f4278c8987546b374b3a708c
-  data.tar.gz: fe1dd67cd895457cb38191ecde0c7a4c6eb350598137ef3c69c1aaca44304472
+  metadata.gz: d5e29be49035702970f6e4420c5461f54fd862530298e3e1ab99d77cdfaccc86
+  data.tar.gz: 315dcc82cbcc4de0f3e9ad8715f960fe5f4eadcee8a0df1050b7058036f90164
 SHA512:
-  metadata.gz: ed2b79e6fb0b032718c143c988ecb788c3718f1ce0f6b60f5fb9a38635ec3f019cb0d78e898f5020b9d8b18db3c64a4cf0ef874e82c3aae475ab1aa36d42ed02
-  data.tar.gz: 589c001faa755f628a0c02c4b47120ec33eb7fa1082a7d69c63f42f23c57c51fbb25f012fb994e49a96cded660a955da678d789d17ca72cefb3834c306ee915d
+  metadata.gz: 728126a8268521381cb7a2deed69dd54b7864fbfb6da0ce943919805779050d913aea1725af04fde5c2c172d6936e18510a6058a01f5ffa685e040992d4a5efb
+  data.tar.gz: 5b946852623b383499b3934cab2db55d40cc02a21c2d8559136ae7695a38b84edd9c8168f7b35fe54e581b87d17ee08761b28e39daf99cd7f397dae107794566

data/README.md

@@ -30,9 +30,10 @@
 - [Requirements](#requirements)
 - [Quick Start](#quick-start)
 - [API Reference](#api-reference)
-  - [check_email](#check_emailemail)
-  - [get_breaches](#get_breachesdomain)
-  - [breach_analytics](#breach_analyticsemail)
+  - [check_email](#check_emailemail-include_details-false)
+  - [get_breaches](#get_breachesdomain-breach_id)
+  - [get_domain_breaches](#get_domain_breaches)
+  - [breach_analytics](#breach_analyticsemail-token-nil)
   - [check_password](#check_passwordpassword)
 - [Error Handling](#error-handling)
 - [Rate Limits](#rate-limits)
@@ -104,9 +105,12 @@ See [Configuration](#configuration) for all available options.
 
 ### Methods
 
-#### `check_email(email)`
+#### `check_email(email, include_details: false)`
 
-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.
+Check if an email address has been exposed in any data breaches.
+
+- **Without API key**: Uses the free API, returns `EmailBreachResponse` with breach names only. Pass `include_details: true` to request detailed breach information.
+- **With API key**: Uses the Plus API (`plus-api.xposedornot.com`), returns `EmailBreachDetailedResponse` with full breach details (`include_details` is ignored - the Plus API is always queried with detailed results).
 
 ```ruby
 # Free API
@@ -122,9 +126,9 @@ puts result.breaches.first.breach_id
 puts result.breaches.first.password_risk
 ```
 
-#### `get_breaches(domain:)`
+#### `get_breaches(domain:, breach_id:)`
 
-Get a list of all known data breaches, optionally filtered by domain.
+Get a list of all known data breaches, optionally filtered by domain or breach ID.
 
 ```ruby
 # Get all breaches
@@ -133,6 +137,9 @@ breaches = client.get_breaches
 # Filter by domain
 adobe_breaches = client.get_breaches(domain: 'adobe.com')
 
+# Fetch a specific breach by ID
+adobe = client.get_breaches(breach_id: 'Adobe')
+
 breaches.each do |breach|
   puts "#{breach.breach_id} - #{breach.domain} (#{breach.exposed_records} records)"
 end
@@ -143,18 +150,37 @@ end
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `domain` | `String` | Optional. Filter breaches by domain |
+| `breach_id` | `String` | Optional. Fetch a specific breach by ID |
 
 **Returns:** `Array<Models::Breach>` with properties such as `breach_id`, `breached_date`, `domain`, `industry`, `exposed_data`, `exposed_records`, and `verified`.
 
-#### `breach_analytics(email)`
+#### `get_domain_breaches`
+
+Get breach information for domains verified against your API key (requires an API key with verified domains configured at [console.xposedornot.com](https://console.xposedornot.com)).
+
+```ruby
+client = XposedOrNot::Client.new(api_key: 'your-api-key')
+report = client.get_domain_breaches
+
+puts report.domain_summary   # Breach counts per domain
+puts report.yearly_metrics   # Breach counts by year
+puts report.top10_breaches   # Top 10 largest breaches
+
+report.breaches_details.each do |record|
+  puts "#{record.email} #{record.domain} #{record.breach}"
+end
+```
+
+#### `breach_analytics(email, token: nil)`
 
-Get detailed breach analytics for an email address, including breach summaries, metrics, and paste exposures.
+Get detailed breach analytics for an email address, including breach summaries, metrics, and paste exposures. Pass `token` to access sensitive breach data.
 
 ```ruby
 analytics = client.breach_analytics('user@example.com')
 
+puts analytics.breaches_count     # Number of breaches
+puts analytics.breach_names       # Names of breaches the email was found in
 puts analytics.breaches_details.length
-puts analytics.breaches_summary
 puts analytics.breach_metrics
 puts analytics.exposed_pastes
 ```

data/lib/xposedornot/endpoints/breaches.rb

@@ -4,18 +4,38 @@ module XposedOrNot
   module Endpoints
     # Breaches listing endpoint.
     module Breaches
-      # Get a list of all known breaches, optionally filtered by domain.
+      # Get a list of all known breaches, optionally filtered by domain or breach ID.
       #
       # @param domain [String, nil] optional domain to filter results
+      # @param breach_id [String, nil] optional breach ID to fetch a specific breach
       # @return [Array<Models::Breach>] list of breach records
-      def get_breaches(domain: nil)
+      def get_breaches(domain: nil, breach_id: nil)
         params = {}
         params[:domain] = domain if domain
+        params[:breach_id] = breach_id if breach_id
 
         response = request(:get, "/v1/breaches", base: :free, params: params)
         raw = response["exposedBreaches"] || []
         raw.map { |b| Models::Breach.new(b) }
       end
+
+      # Get breach information for domains verified against the API key.
+      #
+      # Requires an API key with verified domains configured at
+      # console.xposedornot.com.
+      #
+      # @return [Models::DomainBreachesResponse] metrics and exposed email records
+      # @raise [AuthenticationError] if no API key is configured or the key is invalid
+      def get_domain_breaches
+        unless @config.plus_api?
+          raise AuthenticationError,
+                "An API key is required for domain breach monitoring. " \
+                "Get one at console.xposedornot.com"
+        end
+
+        response = request(:post, "/v1/domain-breaches", base: :free)
+        Models::DomainBreachesResponse.new(response)
+      end
     end
   end
 end

data/lib/xposedornot/endpoints/email.rb

@@ -12,37 +12,47 @@ module XposedOrNot
       # Otherwise, uses the free API.
       #
       # @param email [String] the email address to check
+      # @param include_details [Boolean] request detailed breach information from the
+      #   free API; ignored when an API key is set (the Plus API is always queried
+      #   with detailed results)
       # @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)
+      # @raise [NotFoundError] if the Plus API reports the email as not found
+      def check_email(email, include_details: false)
         Utils.validate_email(email)
 
         if @config.plus_api?
           check_email_detailed(email)
         else
-          check_email_free(email)
+          check_email_free(email, include_details: include_details)
         end
       end
 
       # Get breach analytics for an email address.
       #
       # @param email [String] the email address to analyze
+      # @param token [String, nil] optional token for accessing sensitive breach data
       # @return [Models::BreachAnalyticsResponse]
       # @raise [ValidationError] if the email is invalid
-      def breach_analytics(email)
+      def breach_analytics(email, token: nil)
         Utils.validate_email(email)
 
-        response = request(:get, "/v1/breach-analytics", base: :free, params: { email: email })
+        params = { email: email }
+        params[:token] = token if token
+
+        response = request(:get, "/v1/breach-analytics", base: :free, params: params)
         Models::BreachAnalyticsResponse.new(response)
       end
 
       private
 
       # @param email [String]
+      # @param include_details [Boolean]
       # @return [Models::EmailBreachResponse]
-      def check_email_free(email)
-        response = request(:get, "/v1/check-email/#{URI.encode_www_form_component(email)}", base: :free)
+      def check_email_free(email, include_details: false)
+        params = include_details ? { include_details: "true" } : {}
+        response = request(:get, "/v1/check-email/#{URI.encode_www_form_component(email)}", base: :free,
+                                                                                            params: params)
         Models::EmailBreachResponse.new(response)
       rescue NotFoundError
         # 404 means email not found in any breaches — valid result

data/lib/xposedornot/models/breach_analytics_response.rb

@@ -19,6 +19,21 @@ module XposedOrNot
       # @return [Array<Hash>] exposed pastes
       attr_reader :exposed_pastes
 
+      # @return [Array<String>] names of breaches the email was found in
+      attr_reader :breach_names
+
+      # @return [Integer] number of breaches the email was found in
+      attr_reader :breaches_count
+
+      # @return [Integer] total number of exposures
+      attr_reader :exposures_count
+
+      # @return [String] date of first breach
+      attr_reader :first_breach
+
+      # @return [Integer] number of pastes the email was found in
+      attr_reader :pastes_count
+
       # @param data [Hash] raw response data from the API
       def initialize(data)
         exposed = data["ExposedBreaches"] || {}
@@ -28,6 +43,19 @@ module XposedOrNot
         @breach_metrics = data["BreachMetrics"] || {}
         @pastes_summary = data["PastesSummary"] || {}
         @exposed_pastes = data["ExposedPastes"] || []
+
+        site = @breaches_summary["site"]
+        if site.is_a?(String)
+          @breach_names = site.split(";").reject(&:empty?)
+          @breaches_count = @breach_names.length
+        else
+          @breach_names = []
+          @breaches_count = site || 0
+        end
+
+        @exposures_count = @breaches_summary["exposures"] || @breaches_details.length
+        @first_breach = @breaches_summary["first_breach"] || ""
+        @pastes_count = @pastes_summary["cnt"] || 0
       end
 
       # @return [Hash] hash representation
@@ -37,7 +65,12 @@ module XposedOrNot
           breaches_summary: @breaches_summary,
           breach_metrics: @breach_metrics,
           pastes_summary: @pastes_summary,
-          exposed_pastes: @exposed_pastes
+          exposed_pastes: @exposed_pastes,
+          breach_names: @breach_names,
+          breaches_count: @breaches_count,
+          exposures_count: @exposures_count,
+          first_breach: @first_breach,
+          pastes_count: @pastes_count
         }
       end
     end

data/lib/xposedornot/models/domain_breaches_response.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module XposedOrNot
+  module Models
+    # A single exposed email record from the domain-breaches endpoint.
+    class DomainBreachDetail
+      # @return [String] email address exposed in the breach
+      attr_reader :email
+
+      # @return [String] verified domain the email belongs to
+      attr_reader :domain
+
+      # @return [String] name of the breach the email was found in
+      attr_reader :breach
+
+      # @param data [Hash] raw record data from the API
+      def initialize(data)
+        @email = data["email"] || ""
+        @domain = data["domain"] || ""
+        @breach = data["breach"] || ""
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        { email: @email, domain: @domain, breach: @breach }
+      end
+    end
+
+    # Response from the domain-breaches endpoint.
+    #
+    # Contains breach metrics and statistics for domains verified
+    # against the API key.
+    class DomainBreachesResponse
+      # @return [String] response status ("success" or "error")
+      attr_reader :status
+
+      # @return [Array<DomainBreachDetail>] exposed email records across the verified domains
+      attr_reader :breaches_details
+
+      # @return [Hash] breach counts by year
+      attr_reader :yearly_metrics
+
+      # @return [Hash] summary of breaches by domain
+      attr_reader :domain_summary
+
+      # @return [Hash] summary of all breaches
+      attr_reader :breach_summary
+
+      # @return [Hash] top 10 largest breaches affecting the domains
+      attr_reader :top10_breaches
+
+      # @return [Hash] detailed information about each breach
+      attr_reader :detailed_breach_info
+
+      # @param data [Hash] raw response data from the API
+      def initialize(data)
+        metrics = data["metrics"] || {}
+        @status = data["status"] || ""
+        @breaches_details = (metrics["Breaches_Details"] || []).map { |b| DomainBreachDetail.new(b) }
+        @yearly_metrics = metrics["Yearly_Metrics"] || {}
+        @domain_summary = metrics["Domain_Summary"] || {}
+        @breach_summary = metrics["Breach_Summary"] || {}
+        @top10_breaches = metrics["Top10_Breaches"] || {}
+        @detailed_breach_info = metrics["Detailed_Breach_Info"] || {}
+      end
+
+      # @return [Hash] hash representation
+      def to_h
+        {
+          status: @status,
+          breaches_details: @breaches_details.map(&:to_h),
+          yearly_metrics: @yearly_metrics,
+          domain_summary: @domain_summary,
+          breach_summary: @breach_summary,
+          top10_breaches: @top10_breaches,
+          detailed_breach_info: @detailed_breach_info
+        }
+      end
+    end
+  end
+end

data/lib/xposedornot/models/email_breach_response.rb

@@ -7,6 +7,12 @@ module XposedOrNot
       # @return [Array<String>] list of breach names
       attr_reader :breaches
 
+      # @return [String] the email address that was checked
+      attr_reader :email
+
+      # @return [String] response status ("success" or "error")
+      attr_reader :status
+
       # @param data [Hash] raw response data from the API
       def initialize(data)
         raw = data["breaches"]
@@ -17,6 +23,8 @@ module XposedOrNot
                     else
                       []
                     end
+        @email = data["email"] || ""
+        @status = data["status"] || ""
       end
 
       # @return [Boolean] true if the email was found in any breaches
@@ -31,7 +39,7 @@ module XposedOrNot
 
       # @return [Hash] hash representation
       def to_h
-        { breaches: @breaches, breached: breached?, count: count }
+        { breaches: @breaches, breached: breached?, count: count, email: @email, status: @status }
       end
     end
   end

data/lib/xposedornot/version.rb

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

data/lib/xposedornot.rb

@@ -8,6 +8,7 @@ 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/domain_breaches_response"
 require_relative "xposedornot/models/password_check_response"
 require_relative "xposedornot/endpoints/email"
 require_relative "xposedornot/endpoints/breaches"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xposedornot
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - XposedOrNot
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -72,6 +72,7 @@ files:
 - lib/xposedornot/errors.rb
 - lib/xposedornot/models/breach.rb
 - lib/xposedornot/models/breach_analytics_response.rb
+- lib/xposedornot/models/domain_breaches_response.rb
 - lib/xposedornot/models/email_breach_detailed_response.rb
 - lib/xposedornot/models/email_breach_response.rb
 - lib/xposedornot/models/password_check_response.rb