apiddress 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 659eb249d983cd4c87e29610a1a83d659d3487fb3d49f69859553585c4ec5a65
+  data.tar.gz: 9b7ff658b157ff64f474d377732c92dedbc259cb663df0949580816925bf4168
+SHA512:
+  metadata.gz: b35284431baef688f6588a9b93d5fd14a62b85bff8e401700d1efc93815e9dc76b39a9aa5d27284f4415a5bac5b2c1c2df713c5403d5c83d5b70dcb82d482619
+  data.tar.gz: 868c82a52672a1f6ef90f65520a76ea7360f43b4fcc4c20f313b9a817574b7ca74339fe40bb3291ffd48e5398f8c97e855138fa74e6d95b5b46b57a33fc8592d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 APIddress
+
+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,142 @@
+# apiddress
+
+Official Ruby SDK for the [APIddress](https://api.apiddress.com) email validation API.
+
+- Zero runtime gem dependencies (stdlib `net/http` only)
+- Ruby 3.0+, immutable `Data` value objects, fully type-documented
+- Automatic retry with backoff on `429` and `5xx` (batch creation is never retried)
+
+## Install
+
+```bash
+gem install apiddress
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "apiddress"
+```
+
+## Quickstart
+
+```ruby
+require "apiddress"
+
+client = Apiddress::Client.new(ENV["APIDDRESS_API_KEY"])
+
+result = client.validate_email("ada@stripe.com")
+puts result.status # => "valid"
+puts result.score  # => 0.98
+```
+
+## Configuration
+
+```ruby
+client = Apiddress::Client.new(
+  "YOUR_API_KEY",
+  base_url:    "https://api.apiddress.com", # default
+  timeout:     10,                          # per-request timeout (seconds), default 10
+  max_retries: 2,                           # retries on 429/5xx, default 2
+)
+```
+
+## Usage
+
+### Validate one email
+
+```ruby
+result = client.validate_email(
+  "john@company.com",
+  check_smtp:       false, # default
+  allow_role_based: true,  # server default
+)
+# result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
+# result.suggestion: "john@gmail.com" for typo-like addresses, else nil
+# result.checks: Apiddress::ValidationChecks (syntax, domain_exists, mx, smtp, ...)
+```
+
+A malformed value (e.g. `"not-an-email"`) is a verdict, not an error: you get
+`status == "invalid"` with `reason == "invalid_syntax"`.
+
+### Validate up to 100 emails synchronously
+
+```ruby
+response = client.validate_emails(["a@example.com", "b@example.com"])
+puts response.count
+response.results.each { |r| puts "#{r.email} #{r.status}" }
+```
+
+### Batch jobs (up to 5000 emails)
+
+```ruby
+batch = client.create_batch(
+  emails,
+  callback_url: "https://yourapp.com/webhooks/apiddress", # optional
+)
+
+done = client.wait_for_batch(
+  batch.batch_id,
+  poll_interval: 1.0,  # default
+  timeout:       60.0, # default
+)
+puts "#{done.status} #{done.results.length}"
+
+# Or poll yourself:
+status = client.get_batch(batch.batch_id)
+```
+
+`wait_for_batch` returns the terminal state (`"completed"` or `"failed"`) —
+check `status` before using `results`.
+
+### Account
+
+```ruby
+profile = client.me                  # plan, limits, usage
+usage   = client.usage               # current month
+may     = client.usage("2026-05")    # specific month
+health  = client.health              # no auth required
+```
+
+## Error handling
+
+Every failed request raises an `Apiddress::Error`:
+
+```ruby
+require "apiddress"
+
+begin
+  client.validate_email("john@company.com")
+rescue Apiddress::Error => err
+  puts err.status  # 429
+  puts err.code    # "quota_exceeded"
+  puts err.message # "Monthly request limit exceeded."
+  p err.details    # {"requests_used"=>..., "requests_limit"=>...}
+end
+```
+
+| `status` | `code` |
+| -------- | ------------------- |
+| 400 | `invalid_request` |
+| 401 | `unauthorized` |
+| 404 | `not_found` |
+| 429 | `quota_exceeded` |
+| 500 | `internal_error` |
+| 0 | `timeout` (request or `wait_for_batch` timeout) |
+
+## Development
+
+```bash
+bundle install
+
+# Unit tests (no network required):
+ruby test/test_client.rb
+
+# Integration tests need a live backend:
+APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev \
+  ruby test/test_client.rb
+```
+
+## License
+
+MIT

data/lib/apiddress/client.rb

@@ -0,0 +1,208 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Apiddress
+  # Official APIddress client (stdlib net/http, Ruby 3.0+).
+  #
+  #   client = Apiddress::Client.new(ENV["APIDDRESS_API_KEY"])
+  #   result = client.validate_email("ada@stripe.com")
+  #   puts result.status # => "valid"
+  class Client
+    DEFAULT_BASE_URL    = "https://api.apiddress.com"
+    DEFAULT_TIMEOUT     = 10      # seconds
+    DEFAULT_MAX_RETRIES = 2
+
+    # @param api_key    [String]  Your APIddress API key (sent as x-api-key).
+    # @param base_url   [String]  API origin. Defaults to production.
+    # @param timeout    [Integer] Per-request timeout in seconds. Default 10.
+    # @param max_retries [Integer] Retries on 429/5xx. Default 2.
+    #                              Batch creation is never retried.
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      raise ArgumentError, "Apiddress::Client: api_key must not be empty" if api_key.nil? || api_key.empty?
+
+      @api_key     = api_key
+      @base_url    = base_url.chomp("/")
+      @timeout     = timeout
+      @max_retries = max_retries
+    end
+
+    # -------------------------------------------------------------------------
+    # Validation
+    # -------------------------------------------------------------------------
+
+    # Validate a single email address. Costs 1 request.
+    #
+    # @param email           [String]
+    # @param check_smtp      [Boolean] Attempt an SMTP-level probe. Default false.
+    # @param allow_role_based [Boolean, nil] Treat role-based addresses as acceptable. Default nil (use server default).
+    # @return [ValidateEmailResponse]
+    def validate_email(email, check_smtp: false, allow_role_based: nil)
+      body = { email: email, check_smtp: check_smtp }
+      body[:allow_role_based] = allow_role_based unless allow_role_based.nil?
+      ValidateEmailResponse.from_hash(request(:post, "/api/v1/validate-email", body:))
+    end
+
+    # Validate 1-100 email addresses synchronously. Costs one request per email.
+    #
+    # @param emails     [Array<String>]
+    # @param check_smtp [Boolean]
+    # @return [BulkValidateResponse]
+    def validate_emails(emails, check_smtp: false)
+      BulkValidateResponse.from_hash(
+        request(:post, "/api/v1/validate-emails", body: { emails:, check_smtp: }),
+      )
+    end
+
+    # -------------------------------------------------------------------------
+    # Batch jobs
+    # -------------------------------------------------------------------------
+
+    # Create an asynchronous batch job for 1-5000 email addresses.
+    # Never retried automatically (to avoid duplicate jobs).
+    #
+    # @param emails       [Array<String>]
+    # @param callback_url [String, nil] Webhook URL invoked when the batch completes.
+    # @param check_smtp   [Boolean]
+    # @return [BatchAcceptedResponse]
+    def create_batch(emails, callback_url: nil, check_smtp: false)
+      body = { emails:, check_smtp: }
+      body[:callback_url] = callback_url unless callback_url.nil?
+      BatchAcceptedResponse.from_hash(
+        request(:post, "/api/v1/batches", body:, retryable: false),
+      )
+    end
+
+    # Get the current state (and results, when completed) of a batch job.
+    #
+    # @param batch_id [String]
+    # @return [BatchStatusResponse]
+    def get_batch(batch_id)
+      BatchStatusResponse.from_hash(
+        request(:get, "/api/v1/batches/#{URI.encode_www_form_component(batch_id)}"),
+      )
+    end
+
+    # Poll a batch job until it reaches a terminal state ("completed" or "failed").
+    #
+    # Returns the final state. Raises {Error} with code +"timeout"+ if the job
+    # is still running after +timeout+ seconds.
+    #
+    # @param batch_id      [String]
+    # @param poll_interval [Float] Delay between polls in seconds. Default 1.0.
+    # @param timeout       [Float] Give up after this many seconds. Default 60.0.
+    # @return [BatchStatusResponse]
+    def wait_for_batch(batch_id, poll_interval: 1.0, timeout: 60.0)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+      loop do
+        batch = get_batch(batch_id)
+        return batch if %w[completed failed].include?(batch.status)
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) + poll_interval > deadline
+          raise Error.new(0, "timeout",
+            "Batch #{batch_id} did not complete within #{timeout}s (last status: #{batch.status})")
+        end
+        sleep(poll_interval)
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Account
+    # -------------------------------------------------------------------------
+
+    # Get the profile (plan, limits, usage) of the authenticated API key.
+    # @return [ApiKeyProfileResponse]
+    def me
+      ApiKeyProfileResponse.from_hash(request(:get, "/api/v1/me"))
+    end
+
+    # Get usage for a month ("YYYY-MM"). Defaults to the current month.
+    # @param month [String, nil]
+    # @return [UsageResponse]
+    def usage(month = nil)
+      query = month ? { month: } : nil
+      UsageResponse.from_hash(request(:get, "/api/v1/usage", query:))
+    end
+
+    # Service health check. Does not require authentication.
+    # @return [HealthResponse]
+    def health
+      HealthResponse.from_hash(request(:get, "/api/v1/health", auth: false))
+    end
+
+    # -------------------------------------------------------------------------
+    # Transport
+    # -------------------------------------------------------------------------
+
+    private
+
+    def request(method, path, body: nil, query: nil, auth: true, retryable: true)
+      url = URI.parse(@base_url + path)
+      url.query = URI.encode_www_form(query.transform_keys(&:to_s)) if query
+
+      max_attempts = retryable ? @max_retries + 1 : 1
+
+      attempt = 0
+      loop do
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl     = url.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        req_class = method == :get ? Net::HTTP::Get : Net::HTTP::Post
+        req = req_class.new(url.request_uri)
+        req["Accept"] = "application/json"
+        req["x-api-key"] = @api_key if auth
+
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        begin
+          response = http.request(req)
+        rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+          raise Error.new(0, "timeout", "Request to #{path} timed out after #{@timeout}s")
+        end
+
+        http_status = response.code.to_i
+
+        if http_status >= 200 && http_status < 300
+          return JSON.parse(response.body)
+        end
+
+        api_error = parse_error_envelope(response.body, http_status)
+        should_retry = attempt + 1 < max_attempts && (http_status == 429 || http_status >= 500)
+
+        raise api_error unless should_retry
+
+        sleep(backoff_seconds(attempt))
+        attempt += 1
+      end
+    end
+
+    # Exponential backoff with a little jitter: ~0.25s, ~0.5s, ~1s, capped at 4s.
+    def backoff_seconds(attempt)
+      [0.25 * (2**attempt), 4.0].min + rand * 0.1
+    end
+
+    def parse_error_envelope(body, http_status)
+      code    = "unknown_error"
+      message = "HTTP #{http_status}"
+      details = nil
+
+      begin
+        payload  = JSON.parse(body)
+        envelope = payload["error"] || {}
+        code     = envelope["code"]    || code
+        message  = envelope["message"] || message
+        details  = envelope["details"]
+      rescue JSON::ParserError
+        # Non-JSON error body; keep defaults.
+      end
+
+      Error.new(http_status, code, message, details)
+    end
+  end
+end

data/lib/apiddress/error.rb

@@ -0,0 +1,38 @@
+module Apiddress
+  # Raised for any failed APIddress request.
+  #
+  # For HTTP errors, +status+ is the response status code and +code+ / +message+ /
+  # +details+ come from the API error envelope +{"error": {"code", "message", "details"}}+.
+  #
+  # For client-side failures (request timeout, wait_for_batch timeout), +status+
+  # is 0 and +code+ is +"timeout"+.
+  class Error < StandardError
+    # @return [Integer] HTTP status code, or 0 for client-side failures.
+    attr_reader :status
+
+    # @return [String] Machine-readable error code, e.g. "quota_exceeded".
+    attr_reader :code
+
+    # @return [String] Human-readable description (also the exception message).
+    attr_reader :message
+
+    # @return [Hash, nil] Extra context from the API, or nil.
+    attr_reader :details
+
+    # @param status  [Integer]
+    # @param code    [String]
+    # @param message [String]
+    # @param details [Hash, nil]
+    def initialize(status, code, message, details = nil)
+      super(message)
+      @status  = status
+      @code    = code
+      @message = message
+      @details = details
+    end
+
+    def inspect
+      "#<Apiddress::Error status=#{status.inspect} code=#{code.inspect} message=#{message.inspect} details=#{details.inspect}>"
+    end
+  end
+end

data/lib/apiddress/models.rb

@@ -0,0 +1,180 @@
+module Apiddress
+  # Response models for the APIddress API.
+  #
+  # Hand-mapped 1:1 from the OpenAPI 3.1 contract (backend/openapi.yaml).
+  # Attribute names match the wire format exactly (snake_case).
+
+  # Individual checks performed on an email address.
+  ValidationChecks = Data.define(
+    :syntax,
+    :domain_exists,
+    :mx,
+    # nil when the SMTP probe was skipped or inconclusive.
+    :smtp,
+    :disposable,
+    :role_based,
+    :free_provider,
+    # nil when not determined.
+    :catch_all,
+    :typo,
+    # "low" | "medium" | "high" | nil
+    :spam_trap_risk,
+  ) do
+    # @param data [Hash]
+    # @return [ValidationChecks]
+    def self.from_hash(data)
+      new(
+        syntax:        data["syntax"],
+        domain_exists: data["domain_exists"],
+        mx:            data["mx"],
+        smtp:          data["smtp"],
+        disposable:    data["disposable"],
+        role_based:    data["role_based"],
+        free_provider: data["free_provider"],
+        catch_all:     data["catch_all"],
+        typo:          data["typo"],
+        spam_trap_risk: data["spam_trap_risk"],
+      )
+    end
+  end
+
+  # Result of validating a single email address.
+  ValidateEmailResponse = Data.define(
+    :email,
+    :normalized_email,
+    # "valid" | "invalid" | "risky" | "disposable" | "unknown"
+    :status,
+    :valid,
+    # Confidence score between 0 and 1.
+    :score,
+    # Machine-readable reason, e.g. "accepted_email", "invalid_syntax".
+    :reason,
+    # Suggested correction for typo-like addresses, or nil.
+    :suggestion,
+    :checks,
+    :provider,
+    :created_at,
+  ) do
+    def self.from_hash(data)
+      new(
+        email:            data["email"],
+        normalized_email: data["normalized_email"],
+        status:           data["status"],
+        valid:            data["valid"],
+        score:            data["score"].to_f,
+        reason:           data["reason"],
+        suggestion:       data["suggestion"],
+        checks:           ValidationChecks.from_hash(data["checks"]),
+        provider:         data["provider"],
+        created_at:       data["created_at"],
+      )
+    end
+  end
+
+  # Result of a synchronous bulk validation.
+  BulkValidateResponse = Data.define(:count, :results) do
+    def self.from_hash(data)
+      new(
+        count:   data["count"].to_i,
+        results: data["results"].map { |item| ValidateEmailResponse.from_hash(item) },
+      )
+    end
+  end
+
+  # Returned when an asynchronous batch job is accepted (HTTP 202).
+  BatchAcceptedResponse = Data.define(
+    :batch_id,
+    # Always "pending" on acceptance.
+    :status,
+    :submitted_count,
+    :created_at,
+  ) do
+    def self.from_hash(data)
+      new(
+        batch_id:        data["batch_id"],
+        status:          data["status"],
+        submitted_count: data["submitted_count"].to_i,
+        created_at:      data["created_at"],
+      )
+    end
+  end
+
+  # Current state of an asynchronous batch job.
+  BatchStatusResponse = Data.define(
+    :batch_id,
+    # "pending" | "processing" | "completed" | "failed"
+    :status,
+    :submitted_count,
+    :processed_count,
+    :created_at,
+    :completed_at,
+    # Per-email results once the batch is completed, otherwise nil.
+    :results,
+  ) do
+    def self.from_hash(data)
+      raw_results = data["results"]
+      new(
+        batch_id:        data["batch_id"],
+        status:          data["status"],
+        submitted_count: data["submitted_count"].to_i,
+        processed_count: data["processed_count"].to_i,
+        created_at:      data["created_at"],
+        completed_at:    data["completed_at"],
+        results:         raw_results.nil? ? nil : raw_results.map { |item| ValidateEmailResponse.from_hash(item) },
+      )
+    end
+  end
+
+  # Profile of the authenticated API key.
+  ApiKeyProfileResponse = Data.define(
+    :id,
+    :email,
+    # "free" | "paid" | "enterprise"
+    :plan,
+    :is_active,
+    :requests_limit,
+    :requests_used,
+    :created_at,
+  ) do
+    def self.from_hash(data)
+      new(
+        id:             data["id"],
+        email:          data["email"],
+        plan:           data["plan"],
+        is_active:      data["is_active"],
+        requests_limit: data["requests_limit"].to_i,
+        requests_used:  data["requests_used"].to_i,
+        created_at:     data["created_at"],
+      )
+    end
+  end
+
+  # Monthly usage for the authenticated API key.
+  UsageResponse = Data.define(
+    # Month in YYYY-MM format.
+    :month,
+    :requests_used,
+    :requests_limit,
+    :remaining,
+  ) do
+    def self.from_hash(data)
+      new(
+        month:          data["month"],
+        requests_used:  data["requests_used"].to_i,
+        requests_limit: data["requests_limit"].to_i,
+        remaining:      data["remaining"].to_i,
+      )
+    end
+  end
+
+  # Service health payload.
+  HealthResponse = Data.define(:status, :timestamp, :version) do
+    def self.from_hash(data)
+      new(
+        status:    data["status"],
+        timestamp: data["timestamp"],
+        version:   data["version"],
+      )
+    end
+  end
+end

data/lib/apiddress.rb

@@ -0,0 +1,8 @@
+# Official Ruby SDK for the APIddress email validation API.
+require_relative "apiddress/error"
+require_relative "apiddress/models"
+require_relative "apiddress/client"
+
+module Apiddress
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: apiddress
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- APIddress
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Validate email addresses with the APIddress API. Stdlib net/http only,
+  Ruby 3.0+, automatic retries.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/apiddress.rb
+- lib/apiddress/client.rb
+- lib/apiddress/error.rb
+- lib/apiddress/models.rb
+homepage: https://api.apiddress.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://api.apiddress.com
+  source_code_uri: https://github.com/apiddress/sdk-ruby
+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: 4.0.11
+specification_version: 4
+summary: Official Ruby SDK for the APIddress email validation API
+test_files: []