trueform 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8c1befd1e0c8f22c56730d0b668a30df78f406bc43dbdde1512a439bf961c10
+  data.tar.gz: 6ee4f568e35bf1d11630c31fb3629287c8d78984bbffb419fa4c9a126b9e7bbc
+SHA512:
+  metadata.gz: 40bbe46e945ab6d664cc2fe9f6d4acd277bbed27cecdf7dc2d7f3394537ca2b09a67152fa385abe89ed6e75ea5b2b38575ab49ec1a5a8be74fa3185119f44c54
+  data.tar.gz: e97329fe0109144397e5a223d4c1f60ff0b0cb79168be59a5027dd0d8f9262ac95e09a4080f41b6e720c7cec0b92ae4990b30172021479c9e4149105a834eaa1

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to the Trueform Ruby SDK are documented here.
+
+## [0.1.0] - 2026-08-13
+
+- Added the `Trueform::Client` and `validations.create` resource interface.
+- Added immutable validation results with idiomatic predicate methods.
+- Added configurable retries, timeouts, and namespaced errors.
+- Added validation of successful API response shapes.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trueform
+
+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,116 @@
+# Trueform Ruby SDK
+
+The official Ruby client for the [Trueform email validation API](https://trueform.cloud/docs/).
+
+[Ruby SDK documentation](https://trueform.cloud/docs/ruby/) | [API reference](https://trueform.cloud/docs/api-reference/)
+
+## Install
+
+Add the gem to your bundle:
+
+```ruby
+gem "trueform"
+```
+
+Then run `bundle install`. You can also install it directly with `gem install trueform`.
+
+The SDK supports Ruby 3.1 and newer. It has no runtime dependencies and does not require an API key.
+
+## Quickstart
+
+```ruby
+require "trueform"
+
+trueform = Trueform::Client.new
+validation = trueform.validations.create(email: "user@example.com")
+
+puts "Email looks good" if validation.deliverable?
+```
+
+## Handle validation results
+
+Validation results are immutable Ruby objects with predicate methods:
+
+```ruby
+if validation.did_you_mean
+  puts "Did you mean #{validation.did_you_mean}?"
+end
+
+puts "Ask for a permanent email address" if validation.disposable?
+```
+
+Available values and predicates:
+
+- `email`
+- `valid_format?`
+- `freemail?`
+- `disposable?`
+- `mx_records?`
+- `did_you_mean`
+- `deliverable?`
+- `to_h`
+
+`deliverable?` is a domain-level verdict. It does not prove that a specific mailbox exists.
+
+## Configure the client
+
+Timeout values and retry delays use seconds:
+
+```ruby
+trueform = Trueform::Client.new(
+  timeout: 5,
+  max_retries: 2
+)
+```
+
+Override options for one request:
+
+```ruby
+validation = trueform.validations.create(
+  email: "user@example.com",
+  timeout: 2,
+  max_retries: 0
+)
+```
+
+The client retries connection failures, timeouts, rate limits, and server errors. A `Retry-After`
+response header controls the delay when present.
+
+Use `base_url:` to point the client at a different Trueform-compatible endpoint.
+
+## Errors
+
+```ruby
+begin
+  validation = trueform.validations.create(email: "user@example.com")
+rescue Trueform::RateLimitError => error
+  warn "Retry after #{error.retry_after} seconds"
+rescue Trueform::InvalidRequestError => error
+  warn error.message
+end
+```
+
+Exported errors:
+
+- `Trueform::Error`
+- `Trueform::APIError`
+- `Trueform::InvalidRequestError`
+- `Trueform::RateLimitError`
+- `Trueform::ConnectionError`
+- `Trueform::TimeoutError`
+
+Errors expose `code`, `status`, `request_id`, and `retry_after` when available.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake
+```
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Report vulnerabilities
+through the process in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/trueform/client.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "time"
+require "timeout"
+require "uri"
+
+module Trueform
+  class Client
+    DEFAULT_BASE_URL = "https://api.trueform.cloud"
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_MAX_RETRIES = 2
+    MAX_RETRY_DELAY = 60
+
+    attr_reader :validations
+
+    def initialize(
+      base_url: DEFAULT_BASE_URL,
+      timeout: DEFAULT_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      transport: Transport::NetHTTP.new
+    )
+      @base_url = normalize_base_url(base_url)
+      @timeout = positive_number(timeout, :timeout)
+      @max_retries = non_negative_integer(max_retries, :max_retries)
+      @transport = transport
+      @validations = Resources::Validations.new do |email, timeout: nil, max_retries: nil|
+        request(
+          method: :post,
+          path: "/v1/validations",
+          body: {email: email},
+          timeout: timeout,
+          max_retries: max_retries
+        )
+      end
+    end
+
+    private
+
+    def request(method:, path:, body:, timeout:, max_retries:)
+      request_timeout = positive_number(timeout.nil? ? @timeout : timeout, :timeout)
+      retries = non_negative_integer(max_retries.nil? ? @max_retries : max_retries, :max_retries)
+      attempt = 0
+
+      begin
+        response = perform_request(
+          method: method,
+          path: path,
+          body: body,
+          timeout: request_timeout
+        )
+        parse_response(response)
+      rescue Error => error
+        raise unless retryable?(error) && attempt < retries
+
+        sleep(retry_delay(error, attempt))
+        attempt += 1
+        retry
+      end
+    end
+
+    def perform_request(method:, path:, body:, timeout:)
+      @transport.call(
+        method: method,
+        uri: URI.parse("#{@base_url}#{path}"),
+        headers: {
+          "Accept" => "application/json",
+          "Content-Type" => "application/json",
+          "User-Agent" => "trueform-ruby/#{VERSION}"
+        },
+        body: JSON.generate(body),
+        timeout: timeout
+      )
+    rescue Timeout::Error => timeout_error
+      raise TimeoutError.new(
+        "Request timed out after #{timeout} seconds.",
+        code: "request_timeout"
+      ), cause: timeout_error
+    rescue OpenSSL::SSL::SSLError, Net::ProtocolError, SocketError, IOError, SystemCallError => connection_error
+      raise ConnectionError.new(
+        "Unable to connect to the Trueform API.",
+        code: "connection_error"
+      ), cause: connection_error
+    end
+
+    def parse_response(response)
+      status = Integer(response.code)
+      request_id = response["x-request-id"] || response["cf-ray"]
+      body = parse_body(response.body, status: status, request_id: request_id)
+
+      if status.between?(200, 299)
+        unless body.is_a?(Hash)
+          raise APIError.new(
+            "The API returned an invalid JSON response.",
+            code: "invalid_response",
+            status: status,
+            request_id: request_id
+          )
+        end
+
+        return body
+      end
+
+      raise error_from_response(status, body, response, request_id)
+    end
+
+    def parse_body(value, status:, request_id:)
+      return nil if value.nil? || value.empty?
+
+      JSON.parse(value)
+    rescue JSON::ParserError => error
+      return nil unless status.between?(200, 299)
+
+      raise APIError.new(
+        "The API returned an invalid JSON response.",
+        code: "invalid_response",
+        status: status,
+        request_id: request_id
+      ), cause: error
+    end
+
+    def error_from_response(status, body, response, request_id)
+      message = if body.is_a?(Hash) && body["error"].is_a?(String)
+        body["error"]
+      else
+        "Request failed with status #{status}."
+      end
+
+      case status
+      when 400
+        InvalidRequestError.new(
+          message,
+          code: "invalid_request",
+          status: status,
+          request_id: request_id
+        )
+      when 429
+        RateLimitError.new(
+          message,
+          code: "rate_limit",
+          status: status,
+          request_id: request_id,
+          retry_after: parse_retry_after(response["retry-after"])
+        )
+      else
+        APIError.new(
+          message,
+          code: "api_error",
+          status: status,
+          request_id: request_id
+        )
+      end
+    end
+
+    def parse_retry_after(value)
+      return if value.nil? || value.empty?
+
+      seconds = Float(value, exception: false)
+      return [seconds, 0].max if seconds&.finite?
+
+      [Time.httpdate(value) - Time.now, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    def retryable?(error)
+      return true if error.is_a?(RateLimitError)
+      return true if error.is_a?(TimeoutError)
+      return true if error.is_a?(ConnectionError) && error.code == "connection_error"
+
+      error.is_a?(APIError) && (error.status == 408 || error.status.to_i >= 500)
+    end
+
+    def retry_delay(error, attempt)
+      return [error.retry_after, MAX_RETRY_DELAY].min if error.retry_after
+
+      [0.25 * (2**attempt), 2].min
+    end
+
+    def normalize_base_url(value)
+      unless value.is_a?(String)
+        raise ArgumentError, "base_url must be an HTTP or HTTPS URL"
+      end
+
+      uri = URI.parse(value)
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.query && !uri.fragment
+        raise ArgumentError, "base_url must be an HTTP or HTTPS URL"
+      end
+
+      value.sub(%r{/+\z}, "")
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url must be an HTTP or HTTPS URL"
+    end
+
+    def positive_number(value, name)
+      valid = value.is_a?(Numeric) && value.positive? && (!value.respond_to?(:finite?) || value.finite?)
+      raise ArgumentError, "#{name} must be a positive number" unless valid
+
+      value
+    end
+
+    def non_negative_integer(value, name)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "#{name} must be a non-negative integer"
+      end
+
+      value
+    end
+  end
+end

data/lib/trueform/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Trueform
+  class Error < StandardError
+    attr_reader :code, :status, :request_id, :retry_after
+
+    def initialize(message, code:, status: nil, request_id: nil, retry_after: nil)
+      super(message)
+      @code = code
+      @status = status
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+  end
+
+  class APIError < Error; end
+  class InvalidRequestError < APIError; end
+  class RateLimitError < APIError; end
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+end

data/lib/trueform/resources/validations.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Trueform
+  module Resources
+    class Validations
+      def initialize(&request)
+        @request = request
+      end
+
+      def create(email:, **options)
+        unless email.is_a?(String) && !email.strip.empty?
+          raise InvalidRequestError.new(
+            "The email parameter must be a non-empty string.",
+            code: "invalid_email"
+          )
+        end
+
+        response = @request.call(email, **options)
+        Validation.from_api_response(response)
+      end
+    end
+  end
+end

data/lib/trueform/transport/net_http.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Trueform
+  module Transport
+    class NetHTTP
+      def call(method:, uri:, headers:, body:, timeout:)
+        request = request_class(method).new(uri)
+        headers.each { |name, value| request[name] = value }
+        request.body = body
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+        http.request(request)
+      end
+
+      private
+
+      def request_class(method)
+        return Net::HTTP::Post if method == :post
+
+        raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+      end
+    end
+  end
+end

data/lib/trueform/validation.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Trueform
+  class Validation
+    BOOLEAN_FIELDS = %w[
+      is_valid_format
+      is_freemail
+      is_disposable
+      has_mx_records
+      is_deliverable
+    ].freeze
+
+    attr_reader :email, :did_you_mean
+
+    def self.from_api_response(value)
+      valid = value.is_a?(Hash) &&
+        value["email"].is_a?(String) &&
+        BOOLEAN_FIELDS.all? { |field| value[field] == true || value[field] == false } &&
+        (value["did_you_mean"].nil? || value["did_you_mean"].is_a?(String))
+
+      unless valid
+        raise APIError.new(
+          "The API returned an invalid validation response.",
+          code: "invalid_response"
+        )
+      end
+
+      new(
+        email: value["email"],
+        valid_format: value["is_valid_format"],
+        freemail: value["is_freemail"],
+        disposable: value["is_disposable"],
+        mx_records: value["has_mx_records"],
+        did_you_mean: value["did_you_mean"],
+        deliverable: value["is_deliverable"]
+      )
+    end
+
+    def initialize(email:, valid_format:, freemail:, disposable:, mx_records:, did_you_mean:, deliverable:)
+      @email = email.dup.freeze
+      @valid_format = valid_format
+      @freemail = freemail
+      @disposable = disposable
+      @mx_records = mx_records
+      @did_you_mean = did_you_mean&.dup&.freeze
+      @deliverable = deliverable
+      freeze
+    end
+
+    def valid_format?
+      @valid_format
+    end
+
+    def freemail?
+      @freemail
+    end
+
+    def disposable?
+      @disposable
+    end
+
+    def mx_records?
+      @mx_records
+    end
+
+    def deliverable?
+      @deliverable
+    end
+
+    def to_h
+      {
+        email: @email,
+        is_valid_format: @valid_format,
+        is_freemail: @freemail,
+        is_disposable: @disposable,
+        has_mx_records: @mx_records,
+        did_you_mean: @did_you_mean,
+        is_deliverable: @deliverable
+      }
+    end
+
+    def ==(other)
+      other.is_a?(Validation) && to_h == other.to_h
+    end
+    alias_method :eql?, :==
+
+    def hash
+      to_h.hash
+    end
+  end
+end

data/lib/trueform/version.rb

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

data/lib/trueform.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "trueform/version"
+require_relative "trueform/error"
+require_relative "trueform/validation"
+require_relative "trueform/resources/validations"
+require_relative "trueform/transport/net_http"
+require_relative "trueform/client"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: trueform
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Trueform
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free Ruby client for validating email addresses with Trueform.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/trueform.rb
+- lib/trueform/client.rb
+- lib/trueform/error.rb
+- lib/trueform/resources/validations.rb
+- lib/trueform/transport/net_http.rb
+- lib/trueform/validation.rb
+- lib/trueform/version.rb
+homepage: https://trueform.cloud/docs/ruby/
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/True-Form-Cloud/trueform-ruby-sdk/issues
+  changelog_uri: https://github.com/True-Form-Cloud/trueform-ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://trueform.cloud/docs/ruby/
+  homepage_uri: https://trueform.cloud/docs/ruby/
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/True-Form-Cloud/trueform-ruby-sdk
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Official Ruby SDK for the Trueform email validation API
+test_files: []