mailcheckr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6961901669d98e1acf873bf68523f2a6701600ccac4cca46c69e4bc7870f5da3
+  data.tar.gz: 207b9219579311d9c782194964b63334845e49e6b5276a58c51fd1c41fac7a87
+SHA512:
+  metadata.gz: 47d996133599bad00402124c4935bbc02eb5bef7f741418e8cccaefeda62f14576c4960b22700470595190c74799ed1024d3f5aadcab37e36b40062f4f688c89
+  data.tar.gz: 1eda2d93b87fee25cc456d4212918084eeab23e49ed62a172235342383e31c760a5660ecd3a37c97438f1e7340573b8c9869cc6c3afa66560011f150dcf8f3e2

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "rake"
+gem "rubocop", "~> 1.0"

data/README.md

@@ -0,0 +1,134 @@
+# MailCheckr Ruby SDK
+
+[![Tests](https://github.com/Eazybright/mailcheckr/actions/workflows/test.yml/badge.svg)](https://github.com/Eazybright/mailcheckr/actions/workflows/test.yml)
+[![Gem Version](https://img.shields.io/gem/v/mailcheckr.svg)](https://rubygems.org/gems/mailcheckr)
+[![Gem](https://img.shields.io/gem/dt/mailcheckr.svg)](https://rubygems.org/gems/mailcheckr/)
+
+A minimal Ruby client for the [MailCheckr API](https://mailcheckr.app/docs). It uses Ruby's
+standard HTTP and JSON libraries.
+
+## Requirements
+
+Ruby 3.2 or newer.
+
+## Installation
+
+You can install the client library via RubyGems:
+
+```ruby
+gem install mailcheckr
+```
+
+or add it to your Gemfile:
+
+```ruby
+gem "mailcheckr"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+Create a client with an API key from your MailCheckr dashboard:
+
+```ruby
+require "mailcheckr"
+
+client = Mailcheckr::Client.new(api_key: ENV.fetch("MAILCHECKR_API_KEY"))
+```
+
+Create a verification. MailCheckr requires an `Idempotency-Key`; use a stable
+unique value when retrying the same operation. The result remains hash-like,
+and `http_status` distinguishes an immediately completed response from one to
+poll:
+
+```ruby
+result = client.create_verification(
+  email: "person@example.com",
+  idempotency_key: "signup-123"
+)
+
+case result.http_status
+when 200
+  puts result["status"]
+when 202
+  result = client.get_verification(id: result.fetch("id"))
+end
+```
+
+Creation returns the parsed `data` object as a hash-like
+`Mailcheckr::VerificationResponse`. Both `200 OK` and `202 Accepted` responses
+include `http_status`; poll the returned ID after `202` until the state is
+`completed` or `failed`.
+
+The client also accepts a custom base URL and HTTP timeouts:
+
+```ruby
+client = Mailcheckr::Client.new(
+  api_key: ENV.fetch("MAILCHECKR_API_KEY"),
+  base_url: "https://mailcheckr.app/api/v1",
+  open_timeout: 5,
+  read_timeout: 30
+)
+```
+
+## Webhook signatures
+
+Verify webhook deliveries using the exact raw request body, the
+`X-MailCheckr-Timestamp` header, the `X-MailCheckr-Signature` header, and the
+signing secret shown when configuring the webhook:
+
+```ruby
+valid = Mailcheckr::Webhook.verify_signature(
+  raw_body: request.raw_post,
+  timestamp: request.headers["X-MailCheckr-Timestamp"],
+  signature: request.headers["X-MailCheckr-Signature"],
+  secret: ENV.fetch("MAILCHECKR_WEBHOOK_SECRET")
+)
+
+halt 401 unless valid
+```
+
+MailCheckr signs `timestamp + "." + raw_body` with HMAC-SHA256 and sends the
+hex digest as `v1=<digest>`. Verification uses a constant-time comparison and
+rejects timestamps more than five minutes away from the current time. Set the
+`tolerance:` option in seconds to change that window.
+
+## Errors
+
+Non-2xx responses raise `Mailcheckr::APIError` (or a more specific subclass).
+Errors expose `status`/`status_code`, parsed `response`, raw `response_body`,
+API `code`, and `request_id` when the server supplies an `X-Request-Id` header.
+Their message includes the HTTP status and API message/code when present.
+
+```ruby
+begin
+  client.create_verification(email: email, idempotency_key: key)
+rescue Mailcheckr::InsufficientCreditsError => error
+  logger.error("MailCheckr #{error.status} #{error.code}: #{error.message}")
+rescue Mailcheckr::APIError => error
+  logger.error("MailCheckr request failed: #{error.status} #{error.response_body}")
+end
+```
+
+Documented error statuses map to `AuthenticationError` (401),
+`InsufficientCreditsError` (402), `EmailVerificationRequiredError` (403),
+`IdempotencyConflictError` (409), and `ValidationError` (422). All inherit
+from `APIError`. Invalid JSON or an unexpected response envelope on a
+successful status raises `Mailcheckr::ResponseError`. Network and timeout
+errors from `Net::HTTP` are propagated to the caller.
+
+## Development
+
+Run the test suite with:
+
+```sh
+bin/setup
+bundle exec rake test
+```
+
+Start an interactive Ruby console with:
+
+```sh
+bin/console
+```

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake"
+require "rake/testtask"
+
+Rake::TestTask.new do |task|
+  task.libs << "lib"
+  task.pattern = "spec/**/*_spec.rb"
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "mailcheckr"
+
+# Add fixtures or initialization code here to make experimenting with the gem easier.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Add any other automated development setup here.

data/lib/mailcheckr/client.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "errors"
+
+module Mailcheckr
+  class VerificationResponse < Hash
+    attr_reader :http_status
+
+    def initialize(http_status:, data:)
+      super()
+      update(data)
+      @http_status = http_status
+    end
+  end
+
+  class Client
+    DEFAULT_BASE_URL = "https://mailcheckr.app/api/v1"
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, open_timeout: 5, read_timeout: 30)
+      raise ArgumentError, "api_key must not be empty" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = normalize_base_url(base_url)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def create_verification(email:, idempotency_key:)
+      raise ArgumentError, "idempotency_key must not be empty" if idempotency_key.nil? || idempotency_key.empty?
+
+      request(
+        Net::HTTP::Post,
+        "verifications",
+        body: { email: email },
+        idempotency_key: idempotency_key
+      )
+    end
+
+    def get_verification(id:)
+      raise ArgumentError, "id must not be empty" if id.nil? || id.to_s.empty?
+
+      encoded_id = URI.encode_www_form_component(id.to_s).gsub("+", "%20")
+      request(Net::HTTP::Get, "verifications/#{encoded_id}")
+    end
+
+    private
+
+    def normalize_base_url(base_url)
+      uri = URI.parse(base_url)
+      unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+        raise ArgumentError, "base_url must be an HTTP(S) URL without credentials, query, or fragment"
+      end
+
+      uri.to_s.sub(%r{/+\z}, "")
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url must be a valid HTTP(S) URL"
+    end
+
+    def request(http_method, path, body: nil, idempotency_key: nil)
+      uri = URI.join("#{@base_url}/", path)
+      request = http_method.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"] = "application/json"
+
+      unless body.nil?
+        request["Content-Type"] = "application/json"
+        request["Idempotency-Key"] = idempotency_key if idempotency_key
+        request.body = JSON.generate(body)
+      end
+
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) { |http| http.request(request) }
+
+      status = response.code.to_i
+      response_body = response.body.to_s
+      request_id = response["X-Request-Id"]
+      unless (200..299).cover?(status)
+        raise APIError.for_response(status: status, response_body: response_body, request_id: request_id)
+      end
+
+      parsed_body = JSON.parse(response_body)
+      data = parsed_body.is_a?(Hash) ? parsed_body["data"] : nil
+      raise ResponseError.new(status: status, response_body: response_body) unless data.is_a?(Hash)
+
+      VerificationResponse.new(http_status: status, data: data)
+    rescue JSON::ParserError
+      raise ResponseError.new(status: status, response_body: response_body)
+    end
+  end
+end

data/lib/mailcheckr/errors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mailcheckr
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :response_body, :response, :code, :request_id
+    alias status_code status
+
+    def self.for_response(status:, response_body:, request_id: nil)
+      error_class = {
+        401 => AuthenticationError,
+        402 => InsufficientCreditsError,
+        403 => EmailVerificationRequiredError,
+        409 => IdempotencyConflictError,
+        422 => ValidationError
+      }[status] || self
+      error_class.new(status: status, response_body: response_body, request_id: request_id)
+    end
+
+    def initialize(status:, response_body:, request_id: nil)
+      @status = status
+      @response_body = response_body
+      @request_id = request_id
+      @response = parse_response(response_body)
+      error_details = response.is_a?(Hash) ? response["error"] : nil
+      @code = response.is_a?(Hash) ? response["code"] : nil
+      @code ||= error_details["code"] if error_details.is_a?(Hash)
+      @code ||= error_details if error_details.is_a?(String)
+      message_detail = response.is_a?(Hash) ? response["message"] : nil
+      message_detail ||= error_details["message"] if error_details.is_a?(Hash)
+
+      message = "MailCheckr API request failed with HTTP #{status}"
+      detail = [message_detail, code].find { |value| value.is_a?(String) && !value.empty? }
+      message = "#{message}: #{detail}" if detail
+      message = "#{message} (request ID: #{request_id})" if request_id && !request_id.empty?
+      super(message)
+    end
+
+    private
+
+    def parse_response(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  class AuthenticationError < APIError; end
+  class InsufficientCreditsError < APIError; end
+  class EmailVerificationRequiredError < APIError; end
+  class IdempotencyConflictError < APIError; end
+  class ValidationError < APIError; end
+
+  class ResponseError < Error
+    attr_reader :status, :response_body
+
+    def initialize(status:, response_body:)
+      @status = status
+      @response_body = response_body
+      super("MailCheckr API returned invalid JSON with HTTP #{status}")
+    end
+  end
+end

data/lib/mailcheckr/version.rb

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

data/lib/mailcheckr/webhook.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Mailcheckr
+  module Webhook
+    DEFAULT_TOLERANCE = 300
+
+    def self.verify_signature(raw_body:, timestamp:, signature:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+      tolerance = Integer(tolerance)
+      raise ArgumentError, "tolerance must not be negative" if tolerance.negative?
+
+      return false unless raw_body.is_a?(String) && secret.is_a?(String) && !secret.empty?
+      return false unless timestamp.is_a?(String) && timestamp.match?(/\A\d+\z/)
+      return false unless signature.is_a?(String) && signature.match?(/\Av1=[a-fA-F0-9]{64}\z/)
+
+      timestamp_value = Integer(timestamp, 10)
+      return false if (now.to_i - timestamp_value).abs > tolerance
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
+      OpenSSL.fixed_length_secure_compare(expected, signature.delete_prefix("v1=").downcase)
+    end
+  end
+end

data/lib/mailcheckr.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "mailcheckr/version"
+require_relative "mailcheckr/errors"
+require_relative "mailcheckr/client"
+require_relative "mailcheckr/webhook"

data/spec/client_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "minitest/mock"
+require "mailcheckr"
+
+class MailcheckrClientTest < Minitest::Test
+  Response = Struct.new(:code, :body, :headers) do
+    def [](name)
+      headers[name]
+    end
+  end
+
+  class FakeHTTP
+    attr_reader :last_request
+
+    def initialize(response)
+      @response = response
+    end
+
+    def request(request)
+      @last_request = request
+      @response
+    end
+  end
+
+  def with_response(code: "200", body: '{"data":{"id":"verification-123","state":"completed"}}', request_id: nil)
+    headers = request_id ? { "X-Request-Id" => request_id } : {}
+    http = FakeHTTP.new(Response.new(code, body, headers))
+    start = lambda do |_host, _port, **_options, &block|
+      block.call(http)
+    end
+
+    Net::HTTP.stub(:start, start) { yield http }
+  end
+
+  def test_create_verification_sends_bearer_auth_idempotency_key_and_email
+    with_response do |http|
+      result = Mailcheckr::Client.new(api_key: "secret").create_verification(
+        email: "person@example.com",
+        idempotency_key: "verify-person-123"
+      )
+
+      assert_equal "verification-123", result["id"]
+      assert_equal 200, result.http_status
+      assert_equal "Bearer secret", http.last_request["Authorization"]
+      assert_equal "verify-person-123", http.last_request["Idempotency-Key"]
+      assert_equal "application/json", http.last_request["Content-Type"]
+      assert_equal({ "email" => "person@example.com" }, JSON.parse(http.last_request.body))
+      assert_equal "/api/v1/verifications", http.last_request.path
+    end
+  end
+
+  def test_get_verification_quotes_id_as_a_path_segment
+    with_response do |http|
+      Mailcheckr::Client.new(api_key: "secret").get_verification(id: "verify/123")
+
+      assert_equal "/api/v1/verifications/verify%2F123", http.last_request.path
+      assert_nil http.last_request["Idempotency-Key"]
+      assert_equal "Bearer secret", http.last_request["Authorization"]
+    end
+  end
+
+  def test_accepts_a_202_response_for_async_verification
+    with_response(code: "202", body: '{"data":{"id":"verification-123","state":"processing"}}') do
+      result = Mailcheckr::Client.new(api_key: "secret").create_verification(
+        email: "person@example.com",
+        idempotency_key: "verify-person-123"
+      )
+
+      assert_equal "processing", result["state"]
+      assert_equal 202, result.http_status
+    end
+  end
+
+  def test_raises_api_error_for_non_success_responses
+    with_response(
+      code: "409",
+      body: '{"error":"idempotency_conflict"}',
+      request_id: "req_123"
+    ) do
+      error = assert_raises(Mailcheckr::APIError) do
+        Mailcheckr::Client.new(api_key: "secret").create_verification(
+          email: "person@example.com",
+          idempotency_key: "verify-person-123"
+        )
+      end
+
+      assert_equal 409, error.status
+      assert_equal 409, error.status_code
+      assert_equal "idempotency_conflict", error.code
+      assert_equal "req_123", error.request_id
+      assert_equal '{"error":"idempotency_conflict"}', error.response_body
+    end
+  end
+
+  def test_maps_documented_error_statuses_to_specific_error_classes
+    cases = {
+      "401" => Mailcheckr::AuthenticationError,
+      "402" => Mailcheckr::InsufficientCreditsError,
+      "403" => Mailcheckr::EmailVerificationRequiredError,
+      "409" => Mailcheckr::IdempotencyConflictError,
+      "422" => Mailcheckr::ValidationError
+    }
+
+    cases.each do |status, error_class|
+      with_response(code: status, body: '{"code":"api_error","message":"Request rejected"}') do
+        error = assert_raises(error_class) do
+          Mailcheckr::Client.new(api_key: "secret").get_verification(id: "verification-123")
+        end
+
+        assert_equal status.to_i, error.status
+        assert_equal "api_error", error.code
+        assert_equal "Request rejected", error.response["message"]
+        assert_includes error.message, "Request rejected"
+      end
+    end
+  end
+
+  def test_extracts_error_details_from_nested_error_object
+    with_response(code: "402", body: '{"error":{"code":"insufficient_credits","message":"No credits left"}}') do
+      error = assert_raises(Mailcheckr::InsufficientCreditsError) do
+        Mailcheckr::Client.new(api_key: "secret").get_verification(id: "verification-123")
+      end
+
+      assert_equal "insufficient_credits", error.code
+      assert_includes error.message, "No credits left"
+    end
+  end
+
+  def test_raises_response_error_for_invalid_json
+    with_response(body: "not json") do
+      error = assert_raises(Mailcheckr::ResponseError) do
+        Mailcheckr::Client.new(api_key: "secret").get_verification(id: "verification-123")
+      end
+
+      assert_equal 200, error.status
+      assert_equal "not json", error.response_body
+    end
+  end
+
+  def test_raises_response_error_when_data_envelope_is_missing
+    with_response(body: '{"id":"verification-123","state":"completed"}') do
+      error = assert_raises(Mailcheckr::ResponseError) do
+        Mailcheckr::Client.new(api_key: "secret").get_verification(id: "verification-123")
+      end
+
+      assert_equal 200, error.status
+    end
+  end
+
+  def test_requires_an_api_key_and_idempotency_key
+    assert_raises(ArgumentError) { Mailcheckr::Client.new(api_key: "") }
+    client = Mailcheckr::Client.new(api_key: "secret")
+    assert_raises(ArgumentError) do
+      client.create_verification(email: "person@example.com", idempotency_key: "")
+    end
+  end
+end

data/spec/webhook_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "openssl"
+require "mailcheckr/webhook"
+
+class MailcheckrWebhookSpec < Minitest::Test
+  SECRET = "webhook-secret"
+  RAW_BODY = '{"id":"event_123","type":"verification.completed"}'
+  NOW = Time.at(1_800_000_000)
+
+  def signed_headers(timestamp: NOW.to_i.to_s, raw_body: RAW_BODY)
+    signed_payload = "#{timestamp}.#{raw_body}"
+    signature = OpenSSL::HMAC.hexdigest("SHA256", SECRET, signed_payload)
+    { timestamp: timestamp, signature: "v1=#{signature}" }
+  end
+
+  def verify(raw_body: RAW_BODY, timestamp: NOW.to_i.to_s, signature: signed_headers[:signature], secret: SECRET,
+             **)
+    Mailcheckr::Webhook.verify_signature(
+      raw_body: raw_body,
+      timestamp: timestamp,
+      signature: signature,
+      secret: secret,
+      now: NOW,
+      **
+    )
+  end
+
+  def test_accepts_a_valid_signature
+    headers = signed_headers
+
+    assert Mailcheckr::Webhook.verify_signature(
+      raw_body: RAW_BODY,
+      timestamp: headers[:timestamp],
+      signature: headers[:signature],
+      secret: SECRET,
+      now: NOW
+    )
+  end
+
+  def test_rejects_a_modified_body_or_signature
+    refute verify(raw_body: "#{RAW_BODY} ")
+    refute verify(signature: "v1=#{"0" * 64}")
+  end
+
+  def test_rejects_timestamps_outside_tolerance
+    stale = (NOW.to_i - Mailcheckr::Webhook::DEFAULT_TOLERANCE - 1).to_s
+    future = (NOW.to_i + Mailcheckr::Webhook::DEFAULT_TOLERANCE + 1).to_s
+
+    refute verify(timestamp: stale, signature: signed_headers(timestamp: stale)[:signature])
+    refute verify(timestamp: future, signature: signed_headers(timestamp: future)[:signature])
+  end
+
+  def test_accepts_timestamp_inside_custom_tolerance
+    timestamp = (NOW.to_i - 600).to_s
+    signature = signed_headers(timestamp: timestamp)[:signature]
+
+    assert verify(timestamp: timestamp, signature: signature, tolerance: 600)
+  end
+
+  def test_rejects_malformed_headers_and_empty_secret
+    refute verify(timestamp: "not-a-timestamp")
+    refute verify(signature: "sha256=invalid")
+    refute verify(secret: "")
+  end
+
+  def test_rejects_negative_tolerance
+    assert_raises(ArgumentError) { verify(tolerance: -1) }
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: mailcheckr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kolawole Ezekiel
+- Ridwan Kasim
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-31 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby SDK for creating and retrieving MailCheckr verifications.
+email:
+- doneazy911@gmail.com
+- kasimsheyi20@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/mailcheckr.rb
+- lib/mailcheckr/client.rb
+- lib/mailcheckr/errors.rb
+- lib/mailcheckr/version.rb
+- lib/mailcheckr/webhook.rb
+- spec/client_spec.rb
+- spec/webhook_spec.rb
+homepage: https://mailcheckr.app/docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mailcheckr.app/docs
+  source_code_uri: https://github.com/Eazybright/mailcheckr
+  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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Ruby client for the MailCheckr API
+test_files: []