mailhive 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be565bac6c57f6bc2292b802192122794dfc98d9ac4060423b0ed51faa08510c
+  data.tar.gz: fb4e61ecfa08f93e3f553673947f3d930cb8f61ad632155cbb4fa2e3a5466746
+SHA512:
+  metadata.gz: abe61a7f497e628a1031476ccb99d1dbc76df57054341f742cb7905f268fabba0a2590204c46e8b4819d806899b4f37138da482c743ed1a69e4f938cd0ac846b
+  data.tar.gz: 19171faa17039b7778eb150fc09938191a830cfb4c53dde81533265e9c945c3f81235f0d1c43131d405c8c0b416c2bd96400c9eae037cb49d2ddf0118ae8df81

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- `Mailhive::Client`, with `emails.send`, `emails.send_batch` and `emails.get`.
+- Idempotency keys reused across retries, and `Retry-After` honoured.
+- Typed errors that carry the request id.
+- `Mailhive::Webhook.verify`, with secret rotation.
+- The ActionMailer delivery method (`:mailhive`), registered by a Railtie.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naszat
+
+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,172 @@
+# mailhive
+
+The official Ruby SDK for [Mailhive Send](https://mailhive.africa/docs/send/overview). It supports Ruby 3.0+, has no runtime dependencies, and includes an **ActionMailer** delivery method for Rails.
+
+```sh
+bundle add mailhive
+# or: gem install mailhive
+```
+
+## Send an email
+
+```ruby
+require "mailhive"
+
+client = Mailhive::Client.new # reads MAILHIVE_API_KEY
+
+email = client.emails.send(
+  from: "Acme <hello@acme.com>",
+  to: "ada@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>"
+)
+puts email[:id]
+```
+
+Pass the fields as keyword arguments or as a Hash (symbol or string keys). They match the [API reference](https://mailhive.africa/docs/api/send-email) exactly: `from`, `to`, `cc`, `bcc`, `subject`, `html`, `text`, `template_id`, `variables`, `reply_to`, `headers`, `tags` and `attachments`.
+
+Responses are Hashes with **symbol keys**, parsed from the API's JSON: `email[:id]`, `email[:status]`.
+
+An attachment's `content` is the raw file, which is encoded for you. Use `content_base64` if your data is already base64:
+
+```ruby
+client.emails.send(
+  from: "hello@acme.com",
+  to: "ada@example.com",
+  subject: "Your invoice",
+  text: "Attached.",
+  attachments: [
+    { filename: "invoice.pdf", content: File.binread("invoice.pdf"), content_type: "application/pdf" }
+  ]
+)
+```
+
+```ruby
+client.emails.send_batch([email1, email2]) # up to 100; all accepted or none. Returns the accepted emails.
+client.emails.get(email_id)                # {status: "delivered", …}
+```
+
+`emails.send` sends an email: on that object, use `__send__` or `public_send` for Ruby's dynamic dispatch.
+
+## Rails (ActionMailer)
+
+The gem's Railtie registers a `:mailhive` delivery method:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :mailhive
+config.action_mailer.mailhive_settings = { api_key: ENV["MAILHIVE_API_KEY"] } # or leave the key in the environment
+```
+
+Every mailer then sends through Mailhive: HTML and text parts, attachments, cc, bcc, Reply-To, and your own `X-` headers (plus `In-Reply-To`, `References` and `List-Unsubscribe`). Two headers control Mailhive features and aren't sent on:
+
+```ruby
+class ReceiptMailer < ApplicationMailer
+  def receipt(order)
+    headers["X-Mailhive-Idempotency-Key"] = "order-#{order.id}-receipt" # safe to repeat
+    headers["X-Mailhive-Tags"] = { type: "receipt" }.to_json             # tags, returned in webhook events
+    mail(to: order.email, subject: "Your receipt")
+  end
+end
+```
+
+After delivery, the message's `X-Mailhive-Email-Id` header holds the email's id. `mailhive_settings` also takes `base_url`, `timeout` and `max_retries`.
+
+Outside Rails, use it with the [mail](https://github.com/mikel/mail) gem:
+
+```ruby
+mail.delivery_method Mailhive::ActionMailer::DeliveryMethod, api_key: "mhs_…"
+```
+
+## Retries and idempotency
+
+Every send carries an `Idempotency-Key`. Retries reuse it, so **a retry never sends twice**.
+
+- **Retried** (up to 2 times, then configurable): network errors, timeouts, 5xx responses, and `429 rate_limited` after the `Retry-After` delay.
+- **Not retried:** a used-up allowance (`monthly_quota_reached`, `daily_cap_reached`) and invalid requests.
+
+To stay safe across restarts, pass your own key:
+
+```ruby
+client.emails.send(email, idempotency_key: "order-#{order.id}-receipt")
+```
+
+## Errors
+
+```ruby
+begin
+  client.emails.send(email)
+rescue Mailhive::ValidationError => e
+  puts e.code, e.message, e.details, e.request_id
+rescue Mailhive::RateLimitError => e
+  # e.code == "monthly_quota_reached", or wait e.retry_after seconds
+end
+```
+
+| Error | Status |
+|---|---|
+| `Mailhive::AuthenticationError` | 401 |
+| `Mailhive::BillingError` | 402 |
+| `Mailhive::PermissionError` | 403 |
+| `Mailhive::NotFoundError` | 404 |
+| `Mailhive::ConflictError` | 409 (e.g. `idempotency_conflict`) |
+| `Mailhive::ValidationError` | 400, 422 |
+| `Mailhive::RateLimitError` | 429 (`retry_after` in seconds) |
+| `Mailhive::APIError` | other statuses, and the base class of all of the above |
+| `Mailhive::ConnectionError` | no response |
+
+API errors carry `status`, `code`, `message`, `details`, `request_id` and `headers`. Everything the SDK raises is a `Mailhive::Error`.
+
+## Webhooks
+
+Pass the **raw** body, exactly as received. `verify` returns the event as a Hash with symbol keys:
+
+```ruby
+class MailhiveWebhooksController < ActionController::API
+  def create
+    event = Mailhive::Webhook.verify(
+      request.raw_post,
+      request.headers["Mailhive-Signature"],
+      ENV.fetch("MAILHIVE_WEBHOOK_SECRET")
+    )
+    case event[:type]
+    when "email.bounced" then # …
+    end
+    head :ok
+  rescue Mailhive::WebhookVerificationError => e
+    head :bad_request # e.reason is "header", "timestamp" or "signature"
+  end
+end
+```
+
+Signatures older than 300 seconds are refused (`tolerance:` changes that). Several `v1=` values are accepted, so secrets can be rotated.
+
+## Options
+
+```ruby
+Mailhive::Client.new(
+  api_key: "mhs_…",                                 # default: MAILHIVE_API_KEY
+  base_url: "https://api-beta.mailhive.africa/v1",  # default: MAILHIVE_BASE_URL, then production
+  timeout: 30,                                      # seconds
+  max_retries: 2
+)
+```
+
+The key is never included in `inspect` or logs.
+
+**Test keys** (`mhs_test_…`) work unchanged: delivery is simulated and nothing is billed. [More about test keys](https://mailhive.africa/docs/send/api-keys#test-keys).
+
+## Development
+
+```sh
+bundle config set --local path vendor/bundle
+bundle install
+bundle exec rake test # needs node on PATH for the shared mock server
+```
+
+This gem lives in the [mailhive-sdks](https://github.com/Naszat/mailhive-sdks) monorepo. Please open issues and pull requests there.
+
+## Releasing (maintainers)
+
+1. Bump `Mailhive::VERSION` and the changelog, then merge to `main`.
+2. Push the tag `ruby-vX.Y.Z`. The `release-ruby` workflow publishes the gem to RubyGems through trusted publishing.

data/lib/mailhive/action_mailer.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # Sending ActionMailer (and plain Mail gem) messages through Mailhive Send.
+  #
+  #   # config/environments/production.rb
+  #   config.action_mailer.delivery_method = :mailhive
+  #   config.action_mailer.mailhive_settings = { api_key: ENV["MAILHIVE_API_KEY"] }
+  #
+  # The Railtie registers the :mailhive delivery method. Outside Rails, call
+  # Mailhive::ActionMailer.install, or use the class directly with the Mail
+  # gem: +mail.delivery_method Mailhive::ActionMailer::DeliveryMethod, api_key: "mhs_…"+.
+  #
+  # This file never loads the mail gem: it works on whatever Mail::Message
+  # it's handed.
+  module ActionMailer
+    IDEMPOTENCY_HEADER = "X-Mailhive-Idempotency-Key"
+    TAGS_HEADER = "X-Mailhive-Tags"
+    EMAIL_ID_HEADER = "X-Mailhive-Email-Id"
+
+    # Non-X- headers the API accepts.
+    PASSED_HEADERS = %w[in-reply-to references list-unsubscribe list-unsubscribe-post].freeze
+
+    # Registers :mailhive on ActionMailer::Base. Safe to call twice.
+    def self.install(base = ::ActionMailer::Base)
+      base.add_delivery_method(:mailhive, DeliveryMethod) unless base.delivery_methods.key?(:mailhive)
+    end
+
+    # The API request for one Mail::Message.
+    def self.params(mail)
+      params = {
+        "from" => addresses(mail, :from).first,
+        "to" => recipients(mail),
+        "subject" => mail.subject.to_s
+      }
+      { "cc" => :cc, "bcc" => :bcc, "reply_to" => :reply_to }.each do |key, field|
+        list = addresses(mail, field)
+        params[key] = list unless list.empty?
+      end
+      params.merge!(bodies(mail))
+
+      headers = {}
+      mail.header.fields.each do |field|
+        name = field.name.to_s
+        lower = name.downcase
+        next if lower.start_with?("x-mailhive-")
+        next unless lower.start_with?("x-") || PASSED_HEADERS.include?(lower)
+
+        headers[name] = field.decoded.to_s
+      end
+      params["headers"] = headers unless headers.empty?
+
+      tags = tags(mail)
+      params["tags"] = tags if tags
+
+      attachments = mail.attachments.map do |part|
+        {
+          "filename" => part.filename || "attachment",
+          "content" => part.decoded,
+          "content_type" => part.mime_type || "application/octet-stream"
+        }
+      end
+      params["attachments"] = attachments unless attachments.empty?
+      params
+    end
+
+    def self.header_value(mail, name)
+      field = mail.header[name]
+      field = field.last if field.is_a?(Array)
+      value = field&.decoded.to_s.strip
+      value.nil? || value.empty? ? nil : value
+    end
+
+    def self.addresses(mail, name)
+      field = mail[name]
+      return [] if field.nil?
+
+      Array(field.respond_to?(:formatted) ? field.formatted : field.decoded).compact.map(&:to_s)
+    rescue StandardError
+      Array(mail.public_send(name)).compact.map(&:to_s)
+    end
+
+    # To, or the envelope's recipients (less cc and bcc) when there's no To.
+    def self.recipients(mail)
+      to = addresses(mail, :to)
+      return to unless to.empty?
+
+      envelope = Array(mail.smtp_envelope_to)
+      rest = envelope - Array(mail.cc) - Array(mail.bcc)
+      rest.empty? ? envelope : rest
+    end
+
+    def self.bodies(mail)
+      if mail.multipart?
+        result = {}
+        result["html"] = mail.html_part.decoded if mail.html_part
+        result["text"] = mail.text_part.decoded if mail.text_part
+        result
+      elsif mail.body.to_s.empty?
+        {}
+      elsif mail.mime_type == "text/html"
+        { "html" => mail.decoded }
+      else
+        { "text" => mail.decoded }
+      end
+    end
+
+    def self.tags(mail)
+      raw = header_value(mail, TAGS_HEADER)
+      return nil if raw.nil?
+
+      tags = begin
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+      raise Error, "#{TAGS_HEADER} must be a JSON object, like {\"type\":\"receipt\"}." unless tags.is_a?(Hash)
+
+      tags.to_h { |key, value| [key.to_s, value.to_s] }
+    end
+    private_class_method :addresses, :recipients, :bodies, :tags
+
+    # An ActionMailer / Mail delivery method. ActionMailer builds one per
+    # message, from config.action_mailer.mailhive_settings: api_key,
+    # base_url, timeout, max_retries (or client: a Mailhive::Client).
+    # Without an api_key, MAILHIVE_API_KEY is used.
+    class DeliveryMethod
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = (settings || {}).to_h.transform_keys(&:to_sym)
+      end
+
+      # Sends the message, sets its X-Mailhive-Email-Id header to the
+      # email's id, and returns the accepted email.
+      def deliver!(mail)
+        accepted = client.emails.send(
+          ActionMailer.params(mail),
+          idempotency_key: ActionMailer.header_value(mail, IDEMPOTENCY_HEADER)
+        )
+        mail[EMAIL_ID_HEADER] = accepted[:id]
+        accepted
+      end
+
+      def client
+        @client ||= settings[:client] || Client.new(
+          **settings.slice(:api_key, :base_url, :timeout, :max_retries, :transport, :sleeper)
+        )
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+    end
+  end
+end

data/lib/mailhive/client.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # The Mailhive Send API client.
+  #
+  #   client = Mailhive::Client.new # reads MAILHIVE_API_KEY
+  #   client.emails.send(from: "Acme <hello@acme.com>", to: "ada@example.com", subject: "Hi", text: "Hello")
+  #
+  # Responses are Hashes with symbol keys, parsed from the API's JSON.
+  class Client
+    DEFAULT_BASE_URL = "https://api.mailhive.africa/v1"
+    MAX_RETRY_AFTER = 60.0
+
+    # Errors that mean no response came back: retried, then raised as
+    # Mailhive::ConnectionError.
+    NETWORK_ERRORS = [
+      Timeout::Error, # includes Net::OpenTimeout and Net::ReadTimeout
+      Net::WriteTimeout,
+      IOError, # includes EOFError
+      SocketError,
+      SystemCallError, # Errno::ECONNREFUSED, ECONNRESET, EPIPE, ETIMEDOUT, …
+      OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse
+    ].freeze
+
+    TIMEOUT_ERRORS = [Timeout::Error, Net::WriteTimeout, Errno::ETIMEDOUT].freeze
+    private_constant :TIMEOUT_ERRORS
+
+    attr_reader :base_url, :timeout, :max_retries, :emails
+
+    # Options:
+    # - api_key: a secret key (mhs_…); default MAILHIVE_API_KEY
+    # - base_url: default MAILHIVE_BASE_URL, then production
+    # - timeout: seconds per request (connect, write and read)
+    # - max_retries: retries after the first attempt
+    # - transport, sleeper: for tests (see NetHTTPTransport; sleeper gets seconds)
+    def initialize(api_key: nil, base_url: nil, timeout: 30, max_retries: 2, transport: nil, sleeper: nil)
+      key = present(api_key) || present(ENV.fetch("MAILHIVE_API_KEY", nil))
+      if key.nil?
+        raise Error, "No API key. Pass one to Mailhive::Client.new(api_key: …) or set MAILHIVE_API_KEY. " \
+                     "Create keys under Mailhive Send → API keys."
+      end
+      if key.start_with?("mhp_")
+        raise Error, "That's a form's publishable key (mhp_…). The server SDK needs a secret API key (mhs_…) " \
+                     "from Mailhive Send → API keys."
+      end
+
+      @api_key = key
+      @base_url = (present(base_url) || present(ENV.fetch("MAILHIVE_BASE_URL", nil)) || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = [max_retries.to_i, 0].max
+      @transport = transport || NetHTTPTransport.new
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @emails = Emails.new(self)
+    end
+
+    # Never shows the key.
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+    alias to_s inspect
+
+    # @api private Used by the resources.
+    def request(method, path, body = nil, idempotency_key: nil)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "mailhive-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
+      }
+      payload = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        payload = JSON.generate(body)
+      end
+      # One key per call, reused on every retry: a retry never sends twice.
+      headers["Idempotency-Key"] = present(idempotency_key&.to_s) || SecureRandom.uuid if method == "POST"
+      url = "#{base_url}#{path}"
+
+      attempt = 0
+      loop do
+        begin
+          response = @transport.call(method, url, headers, payload, timeout)
+        rescue *NETWORK_ERRORS => e
+          if attempt < max_retries
+            @sleeper.call(self.class.backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise ConnectionError, connection_message(e)
+        end
+
+        return parse(response.body) if response.status.between?(200, 299)
+
+        error = build_error(response)
+        wait = wait_before_retry(error, attempt)
+        raise error if wait.nil?
+
+        @sleeper.call(wait)
+        attempt += 1
+      end
+    end
+
+    # About 0.5s, 1s, 2s … up to 8s, with jitter.
+    def self.backoff(attempt)
+      ceiling = [8.0, 0.5 * (2**attempt)].min
+      (ceiling / 2) + (rand * ceiling / 2)
+    end
+
+    private
+
+    def present(value)
+      value.nil? || value.empty? ? nil : value
+    end
+
+    def parse(body)
+      body.nil? || body.strip.empty? ? {} : JSON.parse(body, symbolize_names: true)
+    end
+
+    # Seconds to wait before retrying, or nil to give up. Only a rate limit
+    # and server errors are worth retrying: a used-up allowance or a bad
+    # request fails the same way again.
+    def wait_before_retry(error, attempt)
+      return nil if attempt >= max_retries
+      return nil unless error.status >= 500 || (error.status == 429 && error.code == "rate_limited")
+
+      wait = Mailhive.parse_seconds(error.headers["retry-after"])
+      return nil if wait && wait > MAX_RETRY_AFTER
+
+      wait || self.class.backoff(attempt)
+    end
+
+    def build_error(response)
+      headers = response.headers || {}
+      error = begin
+        decoded = JSON.parse(response.body.to_s, symbolize_names: true)
+        decoded.is_a?(Hash) && decoded[:error].is_a?(Hash) ? decoded[:error] : {}
+      rescue JSON::ParserError
+        {}
+      end
+      Mailhive.error_for(
+        response.status,
+        error[:message].is_a?(String) ? error[:message] : "HTTP #{response.status}",
+        code: error[:code].is_a?(String) ? error[:code] : "http_error",
+        details: error[:details],
+        request_id: error[:request_id] || headers["x-request-id"],
+        headers: headers
+      )
+    end
+
+    def connection_message(error)
+      if TIMEOUT_ERRORS.any? { |klass| error.is_a?(klass) }
+        seconds = timeout.to_f == timeout.to_i ? timeout.to_i : timeout.to_f
+        "The Mailhive API didn't answer within #{seconds} seconds."
+      else
+        "Couldn't reach the Mailhive API at #{base_url}."
+      end
+    end
+  end
+end

data/lib/mailhive/emails.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # client.emails. Note that #send here sends an email: use #__send__ or
+  # #public_send for Ruby's dynamic dispatch on this object.
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    # Sends one email and returns the accepted email: {id:, status:, suppressed:, test:}.
+    #
+    # Keys match the API reference exactly (symbols or strings): from, to,
+    # cc, bcc, subject, html, text, template_id, variables, reply_to,
+    # headers, tags, attachments. An attachment's +content+ is the raw file
+    # (encoded for you); use +content_base64+ for data that's already base64.
+    #
+    #   client.emails.send({ from: "hello@acme.com", to: "ada@example.com", subject: "Hi", text: "Hello" })
+    #   client.emails.send(from: "hello@acme.com", to: "ada@example.com", subject: "Hi", text: "Hello")
+    def send(params = nil, idempotency_key: nil, **fields)
+      @client.request("POST", "/send/emails", self.class.encode((params || {}).merge(fields)), idempotency_key: idempotency_key)
+    end
+
+    # Up to 100 independent emails; all are accepted, or none. Returns the
+    # list of accepted emails.
+    def send_batch(emails, idempotency_key: nil)
+      body = { emails: emails.map { |email| self.class.encode(email) } }
+      @client.request("POST", "/send/emails/batch", body, idempotency_key: idempotency_key)[:data]
+    end
+
+    # One email, with its status ("delivered", "bounced", …).
+    def get(id)
+      @client.request("GET", "/send/emails/#{self.class.escape(id)}")
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    # @api private The JSON body for one email.
+    def self.encode(params)
+      raise ArgumentError, "An email must be a Hash, got #{params.class}" unless params.respond_to?(:to_hash)
+
+      email = {}
+      params.to_hash.each { |key, value| email[key.to_s] = value unless value.nil? }
+      attachments = email["attachments"]
+      email["attachments"] = attachments.map { |attachment| encode_attachment(attachment) } if attachments
+      email
+    end
+
+    # @api private
+    def self.encode_attachment(attachment)
+      encoded = {}
+      attachment.to_hash.each { |key, value| encoded[key.to_s] = value }
+      if encoded.key?("content_base64")
+        encoded["content"] = encoded.delete("content_base64").to_s
+      else
+        encoded["content"] = [encoded["content"].to_s].pack("m0")
+      end
+      encoded
+    end
+
+    # @api private Percent-encodes a path segment.
+    def self.escape(value)
+      value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |char| format("%%%02X", char.ord) }
+    end
+  end
+end

data/lib/mailhive/errors.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # Base class for everything this SDK raises.
+  class Error < StandardError; end
+
+  # An error response from the API. Check #code, not #message: codes are
+  # stable, messages may change.
+  class APIError < Error
+    attr_reader :status, :code, :details, :request_id, :headers
+
+    def initialize(message = nil, status: nil, code: nil, details: nil, request_id: nil, headers: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+      @request_id = request_id
+      @headers = headers || {}
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status.inspect} code=#{code.inspect} request_id=#{request_id.inspect}>"
+    end
+  end
+
+  # 401: missing, unknown or revoked API key.
+  class AuthenticationError < APIError; end
+
+  # 402: Mailhive Send is paused over an unpaid invoice.
+  class BillingError < APIError; end
+
+  # 403: Send isn't activated, or the stream is paused.
+  class PermissionError < APIError; end
+
+  # 404
+  class NotFoundError < APIError; end
+
+  # 409: e.g. an Idempotency-Key reused for a different request.
+  class ConflictError < APIError; end
+
+  # 400 or 422: the request is invalid; #details lists every problem.
+  class ValidationError < APIError; end
+
+  # 429: rate_limited (retried for you), or monthly_quota_reached /
+  # daily_cap_reached (not retried: waiting won't help).
+  class RateLimitError < APIError
+    # Seconds from the Retry-After header, or nil.
+    def retry_after
+      Mailhive.parse_seconds(headers["retry-after"])
+    end
+  end
+
+  # The API couldn't be reached, or didn't answer in time.
+  class ConnectionError < Error; end
+
+  # A webhook's signature didn't check out. #reason is "header", "timestamp"
+  # or "signature".
+  class WebhookVerificationError < Error
+    attr_reader :reason
+
+    def initialize(message, reason)
+      super(message)
+      @reason = reason
+    end
+  end
+
+  ERRORS_BY_STATUS = {
+    400 => ValidationError,
+    401 => AuthenticationError,
+    402 => BillingError,
+    403 => PermissionError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => ValidationError,
+    429 => RateLimitError
+  }.freeze
+  private_constant :ERRORS_BY_STATUS
+
+  # @api private
+  def self.error_for(status, message, **fields)
+    ERRORS_BY_STATUS.fetch(status, APIError).new(message, status: status, **fields)
+  end
+
+  # @api private A non-negative number of seconds, or nil.
+  def self.parse_seconds(value)
+    return nil if value.nil? || value.to_s.strip.empty?
+
+    seconds = Float(value.to_s.strip, exception: false)
+    seconds if seconds&.finite? && seconds >= 0
+  end
+end

data/lib/mailhive/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # Registers the :mailhive ActionMailer delivery method. Settings come from
+  # config.action_mailer.mailhive_settings = { api_key: …, base_url: … },
+  # falling back to MAILHIVE_API_KEY and MAILHIVE_BASE_URL.
+  class Railtie < ::Rails::Railtie
+    # Before ActionMailer applies config.action_mailer.*, so that
+    # mailhive_settings= exists by then.
+    initializer "mailhive.action_mailer", before: "action_mailer.set_configs" do
+      ActiveSupport.on_load(:action_mailer) { Mailhive::ActionMailer.install(self) }
+    end
+  end
+end

data/lib/mailhive/transport.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # What a transport returns. +headers+ has lowercase names.
+  Response = Struct.new(:status, :headers, :body)
+
+  # The default transport, on Net::HTTP. A transport is anything with
+  # +call(method, url, headers, body, timeout)+ returning a Mailhive::Response,
+  # and raising the usual Net::HTTP / socket errors when there's no response.
+  class NetHTTPTransport
+    def call(method, url, headers, body, timeout)
+      uri = URI.parse(url)
+      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
+      # The client does its own retries, reusing the idempotency key.
+      http.max_retries = 0
+
+      request = request_class(method).new(uri.request_uri, headers)
+      request.body = body if body
+      response = http.start { |connection| connection.request(request) }
+
+      response_headers = {}
+      response.each_header { |name, value| response_headers[name.downcase] = value }
+      Response.new(response.code.to_i, response_headers, response.body.to_s.dup.force_encoding(Encoding::UTF_8))
+    end
+
+    private
+
+    def request_class(method)
+      case method
+      when "GET" then Net::HTTP::Get
+      when "POST" then Net::HTTP::Post
+      when "DELETE" then Net::HTTP::Delete
+      when "PATCH" then Net::HTTP::Patch
+      when "PUT" then Net::HTTP::Put
+      else raise ArgumentError, "Unsupported HTTP method #{method}"
+      end
+    end
+  end
+end

data/lib/mailhive/version.rb

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

data/lib/mailhive/webhook.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mailhive
+  # Checking Mailhive-Signature on webhooks.
+  module Webhook
+    V1 = /\A[0-9a-fA-F]{64}\z/.freeze
+    private_constant :V1
+
+    # Checks a webhook's Mailhive-Signature header (HMAC-SHA256 of
+    # "<t>.<raw body>" with the endpoint's secret) and returns the event, a
+    # Hash with symbol keys. +payload+ must be the raw body exactly as
+    # received (in Rails, request.raw_post): parsing and re-serializing it
+    # changes the bytes. Several v1= values are accepted, so secrets can be
+    # rotated. Raises Mailhive::WebhookVerificationError.
+    def self.verify(payload, signature_header, secret, tolerance: 300, now: nil)
+      unless payload.is_a?(String)
+        raise TypeError, "Mailhive::Webhook.verify needs the raw request body (a String), not #{payload.class}: " \
+                         "re-serializing changes the bytes, so the signature can't match."
+      end
+
+      timestamp, candidates = parse(signature_header)
+      raise WebhookVerificationError.new("Missing or malformed Mailhive-Signature header.", "header") if timestamp.nil?
+
+      current = now.nil? ? Time.now.to_f : now.to_f
+      if (current - timestamp).abs > tolerance
+        raise WebhookVerificationError.new(
+          "The webhook's timestamp is more than #{tolerance} seconds from now; it may be a replay.", "timestamp"
+        )
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp}.".b + payload.b)
+      unless candidates.any? { |candidate| OpenSSL.fixed_length_secure_compare(expected, candidate) }
+        raise WebhookVerificationError.new(
+          "The webhook's signature doesn't match. Check the endpoint's signing secret.", "signature"
+        )
+      end
+
+      JSON.parse(payload, symbolize_names: true)
+    end
+
+    # [timestamp, [v1, …]], or nil when either is missing.
+    def self.parse(header)
+      return nil if header.nil?
+
+      timestamp = nil
+      candidates = []
+      header.to_s.split(",").each do |part|
+        key, separator, value = part.partition("=")
+        next if separator.empty?
+
+        key = key.strip
+        value = value.strip
+        if key == "t" && value.match?(/\A\d+\z/)
+          timestamp = value.to_i
+        elsif key == "v1" && value.match?(V1)
+          candidates << value.downcase
+        end
+      end
+      return nil if timestamp.nil? || candidates.empty?
+
+      [timestamp, candidates]
+    end
+    private_class_method :parse
+  end
+end

data/lib/mailhive.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+require_relative "mailhive/version"
+require_relative "mailhive/errors"
+require_relative "mailhive/transport"
+require_relative "mailhive/emails"
+require_relative "mailhive/client"
+require_relative "mailhive/webhook"
+require_relative "mailhive/action_mailer"
+require_relative "mailhive/railtie" if defined?(Rails::Railtie)
+
+# The official Ruby SDK for Mailhive Send: Mailhive::Client, Mailhive::Webhook
+# and an ActionMailer delivery method.
+module Mailhive
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: mailhive
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Naszat
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Send transactional email through the Mailhive Send API from Ruby and
+  Rails: safe retries with idempotency keys, typed errors, webhook verification and
+  an ActionMailer delivery method. No runtime dependencies.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailhive.rb
+- lib/mailhive/action_mailer.rb
+- lib/mailhive/client.rb
+- lib/mailhive/emails.rb
+- lib/mailhive/errors.rb
+- lib/mailhive/railtie.rb
+- lib/mailhive/transport.rb
+- lib/mailhive/version.rb
+- lib/mailhive/webhook.rb
+homepage: https://mailhive.africa/docs/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mailhive.africa/docs/sdks/ruby
+  source_code_uri: https://github.com/Naszat/mailhive-sdks/tree/main/ruby
+  changelog_uri: https://github.com/Naszat/mailhive-sdks/blob/main/ruby/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Naszat/mailhive-sdks/issues
+  rubygems_mfa_required: 'true'
+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.6.9
+specification_version: 4
+summary: The official Ruby SDK for Mailhive Send, with an ActionMailer delivery method.
+test_files: []