bigshield 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38b2d82913a30fd6abedec5e0ab61866f92bbf8e33bf1d1fb788fd2af6f99eed
+  data.tar.gz: cdc34299a70002a370cf37400ddb59e03e595457633cccf592329219da195074
+SHA512:
+  metadata.gz: b53386268e60d5e56eef855c6c34db0505b752616c4e89e1f81ec2dc8ece100821938066402dfd167d22bca8ce172cead24a6889eeaa72acc3416819c8ef3986
+  data.tar.gz: c32e3f9c4e46b6222418cb632795ad0a5f48d29e49ae44230bf605a63afa278d644f970ccc2e2d9f1ad00f77f4cdd94833bfa59ef6d9a148d496aca0ff2709b6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BigShield
+
+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,162 @@
+# BigShield Ruby SDK
+
+Official Ruby SDK for the [BigShield](https://bigshield.app) email validation API. Detect fake signups, burner emails, and disposable domains with 30+ detection signals.
+
+## Requirements
+
+- Ruby 3.0+
+- net-http (stdlib)
+
+## Installation
+
+```bash
+gem install bigshield
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "bigshield"
+```
+
+## Quick Start
+
+```ruby
+require "bigshield"
+
+client = BigShield::Client.new("ev_live_...")
+result = client.validate("user@example.com")
+
+puts result.risk_score       # 0-100
+puts result.fraud_decision   # "allow" | "block" | "review" | "require_verification"
+puts result.recommendation   # "accept" | "review" | "reject"
+
+raise "Please use a valid email address" if result.fraud_decision == "block"
+```
+
+## Configuration
+
+```ruby
+# Simple
+client = BigShield::Client.new("ev_live_...")
+
+# Advanced options
+client = BigShield::Client.new(
+  "ev_live_...",
+  base_url: "https://bigshield.app",  # default
+  timeout: 30,                         # request timeout in seconds
+  retries: 2                           # retry on 5xx errors
+)
+```
+
+## Methods
+
+### `validate(email, **options) -> ValidationResult`
+
+Validate a single email address.
+
+```ruby
+result = client.validate(
+  "user@example.com",
+  ip: request.remote_ip,
+  user_agent: request.user_agent,
+  fingerprint: client_fingerprint,
+  wait: true,                                # long-poll for async signals
+  webhook_url: "https://myapp.com/webhook",
+  metadata: { source: "signup" }
+)
+
+puts result.fraud_decision
+puts result.fraud_flags   # e.g. ["proxy_ip", "burner_domain"]
+puts result.signals       # individual signal results
+```
+
+### `batch_validate(emails, **options) -> BatchValidateResponse`
+
+Validate multiple emails in a single request. Max batch size depends on your plan.
+
+```ruby
+batch = client.batch_validate(
+  ["user1@gmail.com", "fake@tempmail.com", "real@company.org"],
+  ip: request.remote_ip
+)
+
+blocked = batch.results.select { |r| r.fraud_decision == "block" }
+puts "Blocked #{blocked.size} of #{batch.total} emails"
+```
+
+### `get_validation(id) -> ValidationResult`
+
+Retrieve a previous validation result by ID.
+
+```ruby
+result = client.get_validation("val_a1b2c3d4")
+```
+
+### `wait_for_completion(id, interval:, max_attempts:) -> ValidationResult`
+
+Poll until async signals complete.
+
+```ruby
+initial = client.validate("user@example.com")
+
+if initial.status == "partial"
+  final = client.wait_for_completion(
+    initial.id,
+    interval: 1.0,      # poll every 1s
+    max_attempts: 30     # give up after 30s
+  )
+end
+```
+
+### `get_usage -> UsageStats`
+
+Get current usage statistics.
+
+```ruby
+usage = client.get_usage
+puts "#{usage.usage.total} / #{usage.usage.limit} validations used"
+```
+
+### `health -> HealthResponse`
+
+Check API health status.
+
+```ruby
+health = client.health
+puts health.status
+```
+
+### `register_webhook(url, events:) -> Hash`
+
+Register a webhook URL for validation events.
+
+```ruby
+client.register_webhook("https://myapp.com/webhook", events: ["validation.completed"])
+```
+
+## Error Handling
+
+```ruby
+require "bigshield"
+
+begin
+  result = client.validate("test@example.com")
+rescue BigShield::AuthError
+  # Invalid or missing API key (401)
+rescue BigShield::RateLimitError => e
+  # Rate limit exceeded (429)
+  puts "Retry after #{e.retry_after} seconds"
+rescue BigShield::Error => e
+  # Other API error
+  puts "#{e.code} #{e.status} #{e.message}"
+end
+```
+
+## Documentation
+
+Full API documentation is available at [bigshield.app/docs](https://bigshield.app/docs).
+
+## License
+
+MIT

data/lib/bigshield/client.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module BigShield
+  # Synchronous BigShield email validation client.
+  #
+  # @example Basic usage
+  #   client = BigShield::Client.new("ev_live_abc123")
+  #   result = client.validate("user@example.com")
+  #   puts result.risk_score
+  #   puts result.valid?
+  #
+  # @example Wait for all signals to complete
+  #   result = client.validate("user@example.com", wait: true)
+  #
+  # @example Poll for completion
+  #   result = client.validate("user@example.com")
+  #   if result.status == "partial"
+  #     result = client.wait_for_completion(result.id)
+  #   end
+  class Client
+    # @param api_key [String] your BigShield API key (e.g. "ev_live_...")
+    # @param base_url [String] API base URL
+    # @param timeout [Integer] request timeout in seconds
+    # @param retries [Integer] number of retry attempts for 5xx / network errors
+    # @raise [ArgumentError] if the API key is empty or nil
+    def initialize(api_key, base_url: "https://www.bigshield.app", timeout: 30, retries: 2)
+      raise ArgumentError, "API key is required" if api_key.nil? || api_key.empty?
+
+      @http = HttpClient.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        retries: retries
+      )
+    end
+
+    # Validate a single email address.
+    #
+    # @param email [String] the email address to validate
+    # @param wait [Boolean] if true, long-poll until Tier 2 signals complete
+    # @param webhook_url [String, nil] URL to receive a callback when validation completes
+    # @param metadata [Hash, nil] custom metadata to attach to the validation
+    # @param ip [String, nil] client IP address for contextual signals
+    # @param fingerprint [String, nil] device fingerprint for multi-account detection
+    # @param user_agent [String, nil] browser user agent string
+    # @return [ValidationResult] validation result with risk score, signals, and recommendation
+    def validate(email, wait: false, webhook_url: nil, metadata: nil, ip: nil, fingerprint: nil, user_agent: nil)
+      body = { "email" => email }
+      body["wait"] = true if wait
+      body["webhook_url"] = webhook_url unless webhook_url.nil?
+      body["metadata"] = metadata unless metadata.nil?
+      body["ip"] = ip unless ip.nil?
+      body["fingerprint"] = fingerprint unless fingerprint.nil?
+      body["user_agent"] = user_agent unless user_agent.nil?
+
+      data = @http.request(:post, "/api/v1/validate", body: body)
+      ValidationResult.from_hash(data)
+    end
+
+    # Retrieve a validation result by ID.
+    #
+    # Useful for polling Tier 2/3 signal completion after an initial
+    # {#validate} call returns with status +"partial"+.
+    #
+    # @param id [String] the validation ID
+    # @return [ValidationResult]
+    def get_validation(id)
+      data = @http.request(:get, "/api/v1/validate/#{id}")
+      ValidationResult.from_hash(data)
+    end
+
+    # Validate multiple email addresses in a single request.
+    #
+    # Maximum batch size depends on your plan (5-100 emails).
+    #
+    # @param emails [Array<String>] list of email addresses to validate
+    # @param webhook_url [String, nil] URL to receive a callback when validation completes
+    # @param ip [String, nil] client IP address for contextual signals
+    # @param fingerprint [String, nil] device fingerprint for multi-account detection
+    # @param user_agent [String, nil] browser user agent string
+    # @return [BatchValidateResponse]
+    def batch_validate(emails, webhook_url: nil, ip: nil, fingerprint: nil, user_agent: nil)
+      body = { "emails" => emails }
+      body["webhook_url"] = webhook_url unless webhook_url.nil?
+      body["ip"] = ip unless ip.nil?
+      body["fingerprint"] = fingerprint unless fingerprint.nil?
+      body["user_agent"] = user_agent unless user_agent.nil?
+
+      data = @http.request(:post, "/api/v1/validate/batch", body: body)
+      BatchValidateResponse.from_hash(data)
+    end
+
+    # Get usage statistics for the current API key.
+    #
+    # @return [UsageStats]
+    def get_usage
+      data = @http.request(:get, "/api/v1/usage")
+      UsageStats.from_hash(data)
+    end
+
+    # Check API health status.
+    #
+    # @return [HealthResponse]
+    def health
+      data = @http.request(:get, "/api/v1/health")
+      HealthResponse.from_hash(data)
+    end
+
+    # Register a webhook URL for validation completion events.
+    #
+    # @param url [String] the webhook endpoint URL
+    # @param events [Array<String>, nil] list of event types to subscribe to
+    # @return [Hash] registration confirmation from the API
+    def register_webhook(url, events: nil)
+      body = { "url" => url }
+      body["events"] = events unless events.nil?
+
+      @http.request(:post, "/api/v1/webhooks", body: body)
+    end
+
+    # Poll until a validation reaches "completed" or "failed" status.
+    #
+    # @param id [String] the validation ID to poll
+    # @param interval [Float] seconds between polling attempts
+    # @param max_attempts [Integer] maximum number of polling attempts
+    # @return [ValidationResult] the final validation result
+    def wait_for_completion(id, interval: 1.0, max_attempts: 30)
+      max_attempts.times do
+        result = get_validation(id)
+        return result if %w[completed failed].include?(result.status)
+
+        sleep(interval)
+      end
+
+      # Final attempt after exhausting retries
+      get_validation(id)
+    end
+  end
+end

data/lib/bigshield/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module BigShield
+  # Base exception for all BigShield API errors.
+  #
+  # @example Catching any BigShield error
+  #   begin
+  #     client.validate("user@example.com")
+  #   rescue BigShield::Error => e
+  #     puts "#{e.code}: #{e.message} (HTTP #{e.status})"
+  #   end
+  class Error < StandardError
+    # @return [String] machine-readable error code
+    attr_reader :code
+
+    # @return [Integer] HTTP status code (0 for network/timeout errors)
+    attr_reader :status
+
+    # @return [Hash] additional error details from the API
+    attr_reader :details
+
+    # @param message [String] human-readable error message
+    # @param code [String] machine-readable error code
+    # @param status [Integer] HTTP status code
+    # @param details [Hash, nil] additional error details
+    def initialize(message = "Unknown error", code: "UNKNOWN_ERROR", status: 0, details: nil)
+      super(message)
+      @code = code
+      @status = status
+      @details = details || {}
+    end
+  end
+
+  # Raised when the API key is invalid or missing (HTTP 401).
+  class AuthError < Error
+    # @param message [String] human-readable error message
+    def initialize(message = "Invalid or missing API key")
+      super(message, code: "UNAUTHORIZED", status: 401)
+    end
+  end
+
+  # Raised when the rate limit is exceeded (HTTP 429).
+  class RateLimitError < Error
+    # @return [Integer] seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @param message [String] human-readable error message
+    # @param retry_after [Integer] seconds to wait before retrying
+    def initialize(message = "Rate limit exceeded", retry_after: 60)
+      super(message, code: "RATE_LIMIT_EXCEEDED", status: 429)
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised for invalid request parameters (HTTP 400).
+  class ValidationError < Error
+    # @param message [String] human-readable error message
+    # @param details [Hash, nil] field-level validation errors
+    def initialize(message = "Validation error", details: nil)
+      super(message, code: "VALIDATION_ERROR", status: 400, details: details)
+    end
+  end
+end

data/lib/bigshield/http_client.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module BigShield
+  # Internal HTTP client with retry logic and error handling.
+  #
+  # Uses Ruby's built-in +net/http+ -- no external dependencies required.
+  #
+  # @api private
+  class HttpClient
+    # @param api_key [String] BigShield API key
+    # @param base_url [String] API base URL
+    # @param timeout [Integer] request timeout in seconds
+    # @param retries [Integer] number of retry attempts for 5xx / network errors
+    def initialize(api_key:, base_url:, timeout:, retries:)
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @retries = retries
+    end
+
+    # Perform an HTTP request with automatic retries and error handling.
+    #
+    # @param method [Symbol] HTTP method (+:get+, +:post+, etc.)
+    # @param path [String] API path (e.g. "/api/v1/validate")
+    # @param body [Hash, nil] request body (will be serialized to JSON)
+    # @return [Hash] parsed JSON response
+    # @raise [BigShield::Error] on API or network errors
+    def request(method, path, body: nil)
+      uri = URI("#{@base_url}#{path}")
+      last_error = nil
+
+      (@retries + 1).times do |attempt|
+        begin
+          response = execute_request(method, uri, body)
+          status = response.code.to_i
+
+          if status >= 200 && status < 300
+            return JSON.parse(response.body)
+          end
+
+          # Don't retry client errors (except potentially retryable ones handled below)
+          if !should_retry?(status) || attempt == @retries
+            handle_error(response)
+          end
+
+          last_error = Error.new("Server error (#{status})", code: "SERVER_ERROR", status: status)
+        rescue Error, AuthError, RateLimitError, ValidationError
+          raise
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          last_error = e
+          if attempt == @retries
+            raise Error.new("Request timed out", code: "TIMEOUT", status: 0)
+          end
+        rescue StandardError => e
+          last_error = e
+          if attempt == @retries
+            raise Error.new("Network error: #{e.message}", code: "NETWORK_ERROR", status: 0)
+          end
+        end
+
+        # Exponential backoff: 0.5s, 1s, 2s, ...
+        sleep(0.5 * (2**attempt))
+      end
+
+      raise last_error
+    end
+
+    private
+
+    # Build and send the HTTP request.
+    #
+    # @param method [Symbol]
+    # @param uri [URI]
+    # @param body [Hash, nil]
+    # @return [Net::HTTPResponse]
+    def execute_request(method, uri, body)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = build_request(method, uri, body)
+      http.request(request)
+    end
+
+    # Build the Net::HTTP request object.
+    #
+    # @param method [Symbol]
+    # @param uri [URI]
+    # @param body [Hash, nil]
+    # @return [Net::HTTPRequest]
+    def build_request(method, uri, body)
+      klass = case method
+              when :get  then Net::HTTP::Get
+              when :post then Net::HTTP::Post
+              when :put  then Net::HTTP::Put
+              when :delete then Net::HTTP::Delete
+              else raise ArgumentError, "Unsupported HTTP method: #{method}"
+              end
+
+      req = klass.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@api_key}"
+      req.body = JSON.generate(body) if body
+      req
+    end
+
+    # Determine whether a response status code is retryable.
+    #
+    # @param status [Integer]
+    # @return [Boolean]
+    def should_retry?(status)
+      status >= 500
+    end
+
+    # Parse an error response and raise the appropriate error class.
+    #
+    # @param response [Net::HTTPResponse]
+    # @raise [BigShield::AuthError] on 401
+    # @raise [BigShield::RateLimitError] on 429
+    # @raise [BigShield::ValidationError] on 400
+    # @raise [BigShield::Error] on all other error statuses
+    def handle_error(response)
+      status = response.code.to_i
+      body = begin
+               JSON.parse(response.body)
+             rescue StandardError
+               {}
+             end
+
+      message = body["error"] || body["message"] || response.body
+
+      case status
+      when 401
+        raise AuthError.new(message || "Invalid or missing API key")
+      when 429
+        retry_after = (response["Retry-After"] || "60").to_i
+        raise RateLimitError.new(message || "Rate limit exceeded", retry_after: retry_after)
+      when 400
+        raise ValidationError.new(message || "Validation error", details: body["details"])
+      else
+        raise Error.new(
+          message || "API error (#{status})",
+          code: body["code"] || "API_ERROR",
+          status: status,
+          details: body["details"]
+        )
+      end
+    end
+  end
+end

data/lib/bigshield/types.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module BigShield
+  # Result for a single validation signal.
+  #
+  # @example
+  #   signal = result.signals.first
+  #   puts "#{signal.name}: impact=#{signal.score_impact}, confidence=#{signal.confidence}"
+  class SignalResult
+    # @return [String] signal name
+    attr_reader :name
+
+    # @return [String] signal tier (e.g. "tier1", "tier2")
+    attr_reader :tier
+
+    # @return [Float] impact on the overall risk score
+    attr_reader :score_impact
+
+    # @return [Float] confidence level (0.0 to 1.0)
+    attr_reader :confidence
+
+    # @return [String] human-readable description
+    attr_reader :description
+
+    # @return [String] ISO 8601 timestamp when the signal was executed
+    attr_reader :executed_at
+
+    # @return [Float] execution time in milliseconds
+    attr_reader :duration_ms
+
+    # @return [Hash] additional signal-specific details
+    attr_reader :details
+
+    # @param name [String]
+    # @param tier [String]
+    # @param score_impact [Float]
+    # @param confidence [Float]
+    # @param description [String]
+    # @param executed_at [String]
+    # @param duration_ms [Float]
+    # @param details [Hash]
+    def initialize(name:, tier:, score_impact:, confidence:, description:, executed_at:, duration_ms:, details: {})
+      @name = name
+      @tier = tier
+      @score_impact = score_impact
+      @confidence = confidence
+      @description = description
+      @executed_at = executed_at
+      @duration_ms = duration_ms
+      @details = details
+    end
+
+    # Build a SignalResult from an API response hash.
+    #
+    # @param data [Hash] raw hash from the API
+    # @return [SignalResult]
+    def self.from_hash(data)
+      new(
+        name: data["name"] || "",
+        tier: data["tier"] || "",
+        score_impact: data["score_impact"] || 0,
+        confidence: data["confidence"] || 0,
+        description: data["description"] || "",
+        executed_at: data["executed_at"] || "",
+        duration_ms: data["duration_ms"] || 0,
+        details: data["details"] || {}
+      )
+    end
+  end
+
+  # The result of an email validation request.
+  #
+  # @example
+  #   result = client.validate("user@example.com")
+  #   if result.valid?
+  #     puts "Email looks good! Score: #{result.risk_score}"
+  #   end
+  class ValidationResult
+    # @return [String] unique validation ID
+    attr_reader :id
+
+    # @return [String] the validated email address
+    attr_reader :email
+
+    # @return [String] validation status: "pending", "partial", "completed", or "failed"
+    attr_reader :status
+
+    # @return [Float] overall risk score (0-100)
+    attr_reader :risk_score
+
+    # @return [String] risk level: "very_low", "low", "medium", "high", or "very_high"
+    attr_reader :risk_level
+
+    # @return [String] recommendation: "accept", "review", or "reject"
+    attr_reader :recommendation
+
+    # @return [Array<SignalResult>] individual signal results
+    attr_reader :signals
+
+    # @return [String] ISO 8601 creation timestamp
+    attr_reader :created_at
+
+    # @return [String] ISO 8601 last-updated timestamp
+    attr_reader :updated_at
+
+    # @return [String, nil] fraud decision: "allow", "block", "require_verification", or "review"
+    attr_reader :fraud_decision
+
+    # @return [Array<String>, nil] list of fraud flag identifiers
+    attr_reader :fraud_flags
+
+    # @return [String, nil] ISO 8601 timestamp when tier 1 signals completed
+    attr_reader :tier1_completed_at
+
+    # @return [String, nil] ISO 8601 timestamp when tier 2 signals completed
+    attr_reader :tier2_completed_at
+
+    # @return [String, nil] ISO 8601 timestamp when tier 3 signals completed
+    attr_reader :tier3_completed_at
+
+    # @param id [String]
+    # @param email [String]
+    # @param status [String]
+    # @param risk_score [Float]
+    # @param risk_level [String]
+    # @param recommendation [String]
+    # @param signals [Array<SignalResult>]
+    # @param created_at [String]
+    # @param updated_at [String]
+    # @param fraud_decision [String, nil]
+    # @param fraud_flags [Array<String>, nil]
+    # @param tier1_completed_at [String, nil]
+    # @param tier2_completed_at [String, nil]
+    # @param tier3_completed_at [String, nil]
+    def initialize(id:, email:, status:, risk_score:, risk_level:, recommendation:, signals:,
+                   created_at:, updated_at:, fraud_decision: nil, fraud_flags: nil,
+                   tier1_completed_at: nil, tier2_completed_at: nil, tier3_completed_at: nil)
+      @id = id
+      @email = email
+      @status = status
+      @risk_score = risk_score
+      @risk_level = risk_level
+      @recommendation = recommendation
+      @signals = signals
+      @created_at = created_at
+      @updated_at = updated_at
+      @fraud_decision = fraud_decision
+      @fraud_flags = fraud_flags
+      @tier1_completed_at = tier1_completed_at
+      @tier2_completed_at = tier2_completed_at
+      @tier3_completed_at = tier3_completed_at
+    end
+
+    # Returns true if the recommendation is "accept".
+    #
+    # @return [Boolean]
+    def valid?
+      recommendation == "accept"
+    end
+
+    # Build a ValidationResult from an API response hash.
+    #
+    # @param data [Hash] raw hash from the API
+    # @return [ValidationResult]
+    def self.from_hash(data)
+      new(
+        id: data["id"] || "",
+        email: data["email"] || "",
+        status: data["status"] || "pending",
+        risk_score: data["risk_score"] || 0,
+        risk_level: data["risk_level"] || "medium",
+        recommendation: data["recommendation"] || "review",
+        signals: (data["signals"] || []).map { |s| SignalResult.from_hash(s) },
+        created_at: data["created_at"] || "",
+        updated_at: data["updated_at"] || "",
+        fraud_decision: data["fraud_decision"],
+        fraud_flags: data["fraud_flags"],
+        tier1_completed_at: data["tier1_completed_at"],
+        tier2_completed_at: data["tier2_completed_at"],
+        tier3_completed_at: data["tier3_completed_at"]
+      )
+    end
+  end
+
+  # Response from a batch validation request.
+  #
+  # @example
+  #   batch = client.batch_validate(["a@b.com", "c@d.com"])
+  #   puts "#{batch.completed}/#{batch.total} completed"
+  class BatchValidateResponse
+    # @return [Array<ValidationResult>] individual validation results
+    attr_reader :results
+
+    # @return [Integer] total number of emails in the batch
+    attr_reader :total
+
+    # @return [Integer] number of validations that have completed
+    attr_reader :completed
+
+    # @param results [Array<ValidationResult>]
+    # @param total [Integer]
+    # @param completed [Integer]
+    def initialize(results:, total:, completed:)
+      @results = results
+      @total = total
+      @completed = completed
+    end
+
+    # Build a BatchValidateResponse from an API response hash.
+    #
+    # @param data [Hash] raw hash from the API
+    # @return [BatchValidateResponse]
+    def self.from_hash(data)
+      new(
+        results: (data["results"] || []).map { |r| ValidationResult.from_hash(r) },
+        total: data["total"] || 0,
+        completed: data["completed"] || 0
+      )
+    end
+  end
+
+  # Usage period boundaries.
+  class UsagePeriod
+    # @return [String] ISO 8601 period start date
+    attr_reader :start
+
+    # @return [String] ISO 8601 period end date
+    attr_reader :end_date
+
+    # @param start [String]
+    # @param end_date [String]
+    def initialize(start:, end_date:)
+      @start = start
+      @end_date = end_date
+    end
+  end
+
+  # Aggregate usage information.
+  class UsageInfo
+    # @return [Integer] total validations used in the current period
+    attr_reader :total
+
+    # @return [Integer] plan validation limit
+    attr_reader :limit
+
+    # @return [Integer] remaining validations
+    attr_reader :remaining
+
+    # @param total [Integer]
+    # @param limit [Integer]
+    # @param remaining [Integer]
+    def initialize(total:, limit:, remaining:)
+      @total = total
+      @limit = limit
+      @remaining = remaining
+    end
+  end
+
+  # Daily usage entry.
+  class DailyUsage
+    # @return [String] date string (YYYY-MM-DD)
+    attr_reader :date
+
+    # @return [Integer] number of validations on this day
+    attr_reader :count
+
+    # @param date [String]
+    # @param count [Integer]
+    def initialize(date:, count:)
+      @date = date
+      @count = count
+    end
+  end
+
+  # Usage statistics for the current API key.
+  #
+  # @example
+  #   usage = client.get_usage
+  #   puts "#{usage.usage.remaining} validations remaining on #{usage.plan} plan"
+  class UsageStats
+    # @return [String] first characters of the API key
+    attr_reader :api_key_prefix
+
+    # @return [String] plan name
+    attr_reader :plan
+
+    # @return [UsagePeriod] current billing period
+    attr_reader :period
+
+    # @return [UsageInfo] aggregate usage information
+    attr_reader :usage
+
+    # @return [Array<DailyUsage>] daily usage breakdown
+    attr_reader :daily
+
+    # @param api_key_prefix [String]
+    # @param plan [String]
+    # @param period [UsagePeriod]
+    # @param usage [UsageInfo]
+    # @param daily [Array<DailyUsage>]
+    def initialize(api_key_prefix:, plan:, period:, usage:, daily:)
+      @api_key_prefix = api_key_prefix
+      @plan = plan
+      @period = period
+      @usage = usage
+      @daily = daily
+    end
+
+    # Build a UsageStats from an API response hash.
+    #
+    # @param data [Hash] raw hash from the API
+    # @return [UsageStats]
+    def self.from_hash(data)
+      period_data = data["period"] || {}
+      usage_data = data["usage"] || {}
+
+      new(
+        api_key_prefix: data["api_key_prefix"] || "",
+        plan: data["plan"] || "",
+        period: UsagePeriod.new(
+          start: period_data["start"] || "",
+          end_date: period_data["end"] || ""
+        ),
+        usage: UsageInfo.new(
+          total: usage_data["total"] || 0,
+          limit: usage_data["limit"] || 0,
+          remaining: usage_data["remaining"] || 0
+        ),
+        daily: (data["daily"] || []).map do |d|
+          DailyUsage.new(date: d["date"] || "", count: d["count"] || 0)
+        end
+      )
+    end
+  end
+
+  # API health check response.
+  #
+  # @example
+  #   health = client.health
+  #   puts "API is #{health.status}, version #{health.version}"
+  class HealthResponse
+    # @return [String] health status: "ok", "degraded", or "down"
+    attr_reader :status
+
+    # @return [String] API version string
+    attr_reader :version
+
+    # @return [String] ISO 8601 timestamp
+    attr_reader :timestamp
+
+    # @return [Hash<String, String>] individual service statuses
+    attr_reader :services
+
+    # @param status [String]
+    # @param version [String]
+    # @param timestamp [String]
+    # @param services [Hash]
+    def initialize(status:, version:, timestamp:, services:)
+      @status = status
+      @version = version
+      @timestamp = timestamp
+      @services = services
+    end
+
+    # Build a HealthResponse from an API response hash.
+    #
+    # @param data [Hash] raw hash from the API
+    # @return [HealthResponse]
+    def self.from_hash(data)
+      new(
+        status: data["status"] || "down",
+        version: data["version"] || "",
+        timestamp: data["timestamp"] || "",
+        services: data["services"] || {}
+      )
+    end
+  end
+end

data/lib/bigshield/version.rb

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

data/lib/bigshield.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "bigshield/version"
+require_relative "bigshield/errors"
+require_relative "bigshield/types"
+require_relative "bigshield/http_client"
+require_relative "bigshield/client"
+
+# Multi-signal email validation SDK for BigShield.
+#
+# @example Quick start
+#   require "bigshield"
+#
+#   client = BigShield::Client.new("ev_live_abc123")
+#   result = client.validate("user@example.com")
+#
+#   if result.valid?
+#     puts "Email is safe (score: #{result.risk_score})"
+#   else
+#     puts "Risky email: #{result.recommendation} (score: #{result.risk_score})"
+#   end
+module BigShield
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: bigshield
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- BigShield
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby SDK for the BigShield email validation API. Provides multi-signal
+  risk scoring to detect fake signups, burner emails, disposable domains, and other
+  fraudulent email patterns.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/bigshield.rb
+- lib/bigshield/client.rb
+- lib/bigshield/errors.rb
+- lib/bigshield/http_client.rb
+- lib/bigshield/types.rb
+- lib/bigshield/version.rb
+homepage: https://www.bigshield.app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.bigshield.app
+  source_code_uri: https://github.com/bigshield/bigshield-ruby
+  documentation_uri: https://www.bigshield.app/docs
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Multi-signal email validation SDK. Detect fake signups, burner emails, and
+  disposable domains.
+test_files: []