mailkube 1.0.0

data/lib/mailkube/transport.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mailkube
+  # A fully-built request, ready to send.
+  #
+  # @api private This is internal plumbing, not part of the supported surface. Build requests by
+  #   calling a resource verb; the shape here may change in a minor release.
+  #
+  # `path` is relative to the base URL, or an absolute URL the API itself issued (a pagination
+  # link). {Config#build_url} refuses an absolute URL off the configured origin.
+  class RequestSpec < Data.define(:path, :method, :body, :params, :headers)
+    # @param path [String] the path or absolute URL to request.
+    # @param method [String] the HTTP method.
+    # @param body [Hash, nil] the JSON request body, or nil for a body-less request.
+    # @param params [Hash{String => String}] query parameters, already rendered to strings by
+    #   {Serialization.query}. Empty means no query string at all, not an empty one.
+    # @param headers [Hash{String => String}] per-request headers, merged over the defaults.
+    def initialize(path:, method: "POST", body: nil, params: {}, headers: {}) = super
+  end
+
+  # One HTTP response, in the shape every adapter returns.
+  #
+  # `headers` are stored exactly as the adapter supplied them, and read through {#header}, which
+  # matches case-insensitively as HTTP requires.
+  #
+  # Unlike the rest of this file, this class **is** public: it is the return type of the `http:`
+  # adapter contract, so any adapter you write has to construct one.
+  class HttpResponse < Data.define(:status, :headers, :body)
+    # @param status [Integer] the HTTP status code.
+    # @param headers [Hash{String => String}] response headers, in any casing.
+    # @param body [String] the raw response body.
+    def initialize(status:, headers: {}, body: "") = super
+
+    # Look a header up, case-insensitively.
+    #
+    # Both sides are downcased, rather than downcasing the argument and indexing a map assumed to
+    # be lowercase already. That assumption used to be this class's documented contract, and since
+    # the class is **public** — the `http:` seam means third-party adapters construct it — it was
+    # an invariant the SDK asked for and could not enforce. An adapter that passed `X-Request-Id`
+    # through in the server's own casing produced a silent nil for every header the SDK reads,
+    # which is exactly how the request id could have stayed empty even after the gateway started
+    # sending it. A scan over a handful of pairs costs nothing and cannot be got wrong from
+    # outside.
+    #
+    # @param name [String] a header name in any casing.
+    # @return [String, nil] the header value, or nil when absent.
+    def header(name)
+      wanted = name.downcase
+      headers.each { |key, value| return value if key.downcase == wanted }
+      nil
+    end
+  end
+
+  # Performs one HTTP round trip and turns the result into a model or a mapped error.
+  #
+  # @api private This is internal plumbing, not part of the supported surface. To swap out the HTTP
+  #   layer, pass an adapter to `Client.new(http:)` — that seam **is** public, and it is documented
+  #   in the README. Depending on this class directly is not supported.
+  #
+  # This is the layer that knows the API's error envelope and nothing about `Net::HTTP`: the
+  # actual socket work lives behind the injected adapter (see {NetHttpAdapter}), which is what
+  # lets the whole suite run without network access.
+  #
+  # A resource depends on the narrowest thing it needs, which in Ruby means an object responding
+  # to the one verb it calls. `Resources::Emails` needs only `#send_email`. A new capability adds
+  # a method here; it never widens an existing one.
+  class Transport
+    # @param config [Config] the resolved configuration.
+    # @param adapter [#call] the HTTP adapter performing the round trip.
+    def initialize(config, adapter)
+      @config = config
+      @adapter = adapter
+      freeze
+    end
+
+    # Perform a send request and build the accepted-send result.
+    #
+    # @param spec [RequestSpec] the request to perform.
+    # @return [Email] the accepted-send result.
+    # @raise [APIError] on any non-2xx response.
+    # @raise [ConnectionError] on a transport failure or timeout.
+    def send_email(spec)
+      response = perform(spec)
+      payload = decode(response.body)
+      id = payload["id"]
+      raise APIError.new("expected a JSON body with an 'id'", status_code: response.status) unless id.is_a?(String)
+
+      Email.new(
+        id: id,
+        message_id: payload["message_id"],
+        idempotent_replayed: response.header("Idempotent-Replayed")&.downcase == "true",
+        status: payload["status"],
+        scheduled_at: payload["scheduled_at"],
+        batch_id: payload["batch_id"]
+      )
+    end
+
+    # Perform a request and return its decoded JSON object body.
+    #
+    # The second transport verb, and deliberately **not** a widening of the first: {#send_email}
+    # builds one specific model out of a body plus a response header, which is a send concern.
+    # This one hands back the decoded object and lets the resource name its model, which is what
+    # keeps {Resources::Emails} depending on `#send_email` alone.
+    #
+    # It takes no model argument on purpose. Ruby has no generics and RBS cannot tie a class
+    # argument to a return type, so a `request(spec, model)` form would make Steep prove generic
+    # structural conformance for something the resource already knows statically. Naming the model
+    # is a resource decision; decoding is this layer's.
+    #
+    # @param spec [RequestSpec] the request to perform.
+    # @return [Hash{String => Object}] the decoded 2xx body.
+    # @raise [APIError] on any non-2xx response, or a 2xx body that is not a JSON object.
+    # @raise [ConnectionError] on a transport failure or timeout.
+    def request_json(spec)
+      response = perform(spec)
+      payload = decode_object(response.body)
+      raise APIError.new("expected a JSON object body", status_code: response.status) if payload.nil?
+
+      payload
+    end
+
+    private
+
+    # Perform the round trip, raising the mapped error for any non-2xx status.
+    #
+    # This is the single place a status becomes an exception, so every verb, present and future,
+    # reports failures identically.
+    #
+    # @param spec [RequestSpec] the request to perform.
+    # @return [HttpResponse] the 2xx response.
+    def perform(spec)
+      url = @config.build_url(spec.path, spec.params)
+      headers = @config.default_headers.merge(spec.headers)
+      Logging.request(spec.method, url, headers)
+      response = @adapter.call(
+        method: spec.method,
+        url: url,
+        headers: headers,
+        body: spec.body.nil? ? nil : JSON.generate(spec.body)
+      )
+      Logging.response(response.status, url, response.header("X-Request-Id"))
+      return response if (200..299).cover?(response.status)
+
+      raise error_for(response)
+    end
+
+    # Build the exception for a non-2xx response.
+    #
+    # @param response [HttpResponse] the failed response.
+    # @return [APIError] the exception to raise.
+    def error_for(response)
+      payload = decode(response.body)
+      Mailkube.error_class_for(response.status).new(
+        payload["message"],
+        error_name: payload["name"].is_a?(String) ? payload["name"] : "",
+        status_code: response.status,
+        body: payload,
+        retry_after: response.header("Retry-After")&.to_i,
+        request_id: response.header("X-Request-Id")
+      )
+    end
+
+    # Decode a body strictly: nil when it is empty, undecodable, or not a JSON *object*.
+    #
+    # Split out of {#decode} rather than inlined, because the two callers need opposite things
+    # from the same parse: {#error_for} must stay lenient, so a malformed error body still maps by
+    # status, and {#request_json} must not, so a 2xx that is not an object is reported rather than
+    # silently becoming an empty model. One parse, two contracts.
+    #
+    # @param raw [String] the raw response body.
+    # @return [Hash{String => Object}, nil] the decoded object, or nil.
+    def decode_object(raw)
+      return nil if raw.empty?
+
+      decoded = JSON.parse(raw)
+      decoded.is_a?(Hash) ? decoded : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Best-effort JSON decode: an empty or undecodable body becomes an empty hash, so a
+    # malformed error response still maps by status.
+    #
+    # @param raw [String] the raw response body.
+    # @return [Hash] the decoded object, or an empty hash.
+    def decode(raw) = decode_object(raw) || {}
+  end
+end

data/lib/mailkube/types/scheduled_acks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # What a cancellation reports back.
+  #
+  # A separate model from {ScheduledEmail} rather than a widened one: the server answers a
+  # cancellation with a three-field acknowledgement, not with the record, and a model mirrors the
+  # wire and nothing else.
+  class CanceledScheduledEmail < Data.define(:id, :object, :status)
+    # @param id [String] the canceled scheduled email's UUID.
+    # @param object [String] the resource discriminator, always `scheduled_email`.
+    # @param status [String] the resulting status, always `canceled`.
+    def initialize(id:, object: "scheduled_email", status: "canceled") = super
+
+    # @param payload [Hash{String => Object}] the decoded acknowledgement.
+    # @return [CanceledScheduledEmail] the model.
+    def self.from(payload)
+      new(id: payload["id"], object: payload["object"] || "scheduled_email",
+          status: payload["status"] || "canceled")
+    end
+  end
+
+  # What cancelling a whole batch reports back.
+  class ScheduledEmailBatchCancel < Data.define(:object, :batch_id, :canceled_count)
+    # @param object [String] the resource discriminator, always `scheduled_email.batch`.
+    # @param batch_id [String] the batch that was targeted.
+    # @param canceled_count [Integer] how many pending emails the cancellation affected. An
+    #   unknown batch is a no-op reporting 0, **not** an error, so do not treat 0 as a failure.
+    def initialize(object: "scheduled_email.batch", batch_id: "", canceled_count: 0) = super
+
+    # @param payload [Hash{String => Object}] the decoded acknowledgement.
+    # @return [ScheduledEmailBatchCancel] the model.
+    def self.from(payload)
+      new(object: payload["object"] || "scheduled_email.batch", batch_id: payload["batch_id"] || "",
+          canceled_count: payload["canceled_count"] || 0)
+    end
+  end
+
+  # What rescheduling a whole batch reports back.
+  class ScheduledEmailBatchUpdate < Data.define(:object, :batch_id, :rescheduled_count, :scheduled_at)
+    # @param object [String] the resource discriminator, always `scheduled_email.batch`.
+    # @param batch_id [String] the batch that was targeted.
+    # @param rescheduled_count [Integer] how many pending emails moved. An unknown batch is a
+    #   no-op reporting 0, **not** an error.
+    # @param scheduled_at [String, nil] the new due time applied to every moved email.
+    def initialize(object: "scheduled_email.batch", batch_id: "", rescheduled_count: 0, scheduled_at: nil)
+      super
+    end
+
+    # @param payload [Hash{String => Object}] the decoded acknowledgement.
+    # @return [ScheduledEmailBatchUpdate] the model.
+    def self.from(payload)
+      new(object: payload["object"] || "scheduled_email.batch", batch_id: payload["batch_id"] || "",
+          rescheduled_count: payload["rescheduled_count"] || 0, scheduled_at: payload["scheduled_at"])
+    end
+  end
+end

data/lib/mailkube/types/scheduled_emails.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # One scheduled email, as the `scheduled-emails` collection reports it.
+  #
+  # Richer than the {Email} acknowledgement a scheduled send returns: that ack is lean by design,
+  # and these are the fields you get by asking the collection for the email afterwards.
+  #
+  # Timestamps stay the verbatim ISO-8601 strings the server sent; call `Time.iso8601` yourself if
+  # you want objects. `tags` are plain hashes rather than {Tag} values — see {Events::Node} for the
+  # rule: {Tag} is what you construct, a hash is what you read.
+  class ScheduledEmail < Data.define(:id, :message_id, :object, :status, :scheduled_at, :created_at,
+                                     :batch_id, :subject, :recipients, :topic, :tags)
+    # @param id [String] the scheduled email's UUID.
+    # @param message_id [String, nil] the RFC Message-ID.
+    # @param object [String] the resource discriminator, always `scheduled_email`.
+    # @param status [String] one of `scheduled`, `canceled`, `sent`, `failed`. A server-controlled
+    #   string, deliberately not an enum: a value added later must not break a released client.
+    # @param scheduled_at [String, nil] when the send is due.
+    # @param created_at [String, nil] when the send was accepted.
+    # @param batch_id [String, nil] the batch label this send was grouped under.
+    # @param subject [String, nil] the subject line.
+    # @param recipients [String, nil] a recipient **summary**, not a list: `"a@b.com +2"` when
+    #   there are more, the bare address when there is one, `""` when there are none. The full
+    #   list stays server-side.
+    # @param topic [String, nil] the mailing-list topic slug.
+    # @param tags [Array<Hash{String => Object}>] the tags attached at send time, verbatim.
+    def initialize(id:, message_id: nil, object: "scheduled_email", status: "", scheduled_at: nil,
+                   created_at: nil, batch_id: nil, subject: nil, recipients: nil, topic: nil, tags: [])
+      super
+    end
+
+    # @param payload [Hash{String => Object}] one decoded `scheduled_email` object.
+    # @return [ScheduledEmail] the model.
+    def self.from(payload)
+      new(id: payload["id"], message_id: payload["message_id"],
+          object: payload["object"] || "scheduled_email", status: payload["status"] || "",
+          scheduled_at: payload["scheduled_at"], created_at: payload["created_at"],
+          batch_id: payload["batch_id"], subject: payload["subject"],
+          recipients: payload["recipients"], topic: payload["topic"], tags: payload["tags"] || [])
+    end
+  end
+
+  # Links to the pages adjacent to the one in hand.
+  #
+  # The server **omits** a step at either end of the range rather than sending null, so an absent
+  # link and a nil value mean the same thing: there is no such page.
+  class PageSteps < Data.define(:next, :previous)
+    # @param next [String, nil] absolute URL of the following page, nil on the last page.
+    # @param previous [String, nil] absolute URL of the preceding page, nil on the first page.
+    def initialize(next: nil, previous: nil) = super
+
+    # @param payload [Hash{String => Object}, nil] the decoded `steps` block, which may be absent.
+    # @return [PageSteps] the model.
+    def self.from(payload) = new(next: (payload || {})["next"], previous: (payload || {})["previous"])
+  end
+
+  # The pagination block that accompanies every listing.
+  #
+  # Every member has a default because the server adds `total_count` and `current_page`
+  # conditionally, exactly as it does the step links.
+  class Pagination < Data.define(:steps, :total_count, :current_page)
+    # @param steps [PageSteps] links to the adjacent pages.
+    # @param total_count [Integer] matching records across every page.
+    # @param current_page [Integer] the 1-based number of the page in hand.
+    def initialize(steps: PageSteps.new, total_count: 0, current_page: 1) = super
+
+    # @param payload [Hash{String => Object}, nil] the decoded `pagination` block.
+    # @return [Pagination] the model.
+    def self.from(payload)
+      block = payload || {}
+      new(steps: PageSteps.from(block["steps"]), total_count: block["total_count"] || 0,
+          current_page: block["current_page"] || 1)
+    end
+  end
+
+  # One page of scheduled emails: the records, plus how to reach the neighbouring pages.
+  class ScheduledEmailPage < Data.define(:pagination, :data)
+    # @param pagination [Pagination] page metadata, including the adjacent-page links.
+    # @param data [Array<ScheduledEmail>] the scheduled emails on this page.
+    def initialize(pagination: Pagination.new, data: []) = super
+
+    # @param payload [Hash{String => Object}] the decoded listing body.
+    # @return [ScheduledEmailPage] the model.
+    def self.from(payload)
+      new(pagination: Pagination.from(payload["pagination"]),
+          data: (payload["data"] || []).map { |item| ScheduledEmail.from(item) })
+    end
+
+    # Spelled `more?` rather than `has_more`: Ruby's predicate convention, and the same call this
+    # gem already makes for `Email#scheduled?` where the other SDKs say `is_scheduled`.
+    #
+    # @return [Boolean] true when the server issued a link to a following page.
+    def more? = !pagination.steps.next.nil?
+  end
+end

data/lib/mailkube/types.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # A file attached to an email.
+  #
+  # `content` is the raw bytes; the SDK base64-encodes them for the wire. `content_type` is
+  # inferred from the filename when omitted.
+  class Attachment < Data.define(:filename, :content, :content_type)
+    # @param filename [String] the name of the attached file.
+    # @param content [String] the raw file content.
+    # @param content_type [String, nil] the MIME type, inferred from the filename when nil.
+    def initialize(filename:, content:, content_type: nil) = super
+  end
+
+  # A free-form name/value tag attached to an outgoing email.
+  #
+  # Tags are forwarded to the server, which denormalizes them onto the sending log so you can
+  # filter, export and dashboard sends by tag, and so they ride along on delivery webhooks. Tag
+  # values are not encrypted, so do not put personal data in them.
+  class Tag < Data.define(:name, :value)
+    # @param name [String] the tag name.
+    # @param value [String] the tag value; it may be empty.
+    def initialize(name:, value: "") = super
+  end
+
+  # The result of a successful send.
+  #
+  # A **scheduled** send (one carrying `scheduled_at`) is acknowledged with 202 and a richer
+  # body; `status`, `scheduled_at` and `batch_id` are populated only then, and `#scheduled?` is
+  # the discriminator. An immediate send leaves all three nil.
+  #
+  # This is the worked example of the contract's **widen, never union** rule: one call can return
+  # two shapes, and adding optional fields plus a predicate keeps every existing caller valid,
+  # where returning one of two classes would not.
+  #
+  # Timestamps stay the verbatim ISO-8601 strings the server sent. The SDK does not validate or
+  # reinterpret server data; call `Time.iso8601` yourself if you want an object. Transport
+  # metadata (response headers, the request id) belongs on the exception, not here.
+  class Email < Data.define(:id, :message_id, :idempotent_replayed, :status, :scheduled_at, :batch_id)
+    # @param id [String] the accepted message's UUID.
+    # @param message_id [String, nil] the RFC Message-ID, when the deployment returns one.
+    # @param idempotent_replayed [Boolean] true when this replays an earlier identical request.
+    # @param status [String, nil] the scheduled email's status, on a scheduled ack only.
+    # @param scheduled_at [String, nil] when the send is due, on a scheduled ack only.
+    # @param batch_id [String, nil] the batch label the send was grouped under.
+    def initialize(id:, message_id: nil, idempotent_replayed: false, status: nil, scheduled_at: nil,
+                   batch_id: nil)
+      super
+    end
+
+    # @return [Boolean] true when the send was accepted for later delivery rather than sent now.
+    def scheduled? = !scheduled_at.nil?
+  end
+end

data/lib/mailkube/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # The released version of this gem.
+  #
+  # This constant is the **single source of truth** the contract requires: the gemspec reads it
+  # (`spec.version = Mailkube::VERSION`) and the User-Agent reads it, so the version on the wire
+  # and the version on rubygems.org cannot disagree.
+  #
+  # The value committed here is a permanent `0.0.0` placeholder and is never updated. On release,
+  # semantic-release rewrites this line **in the release runner** just before the gem is built, and
+  # commits nothing back to `main` (see `.rules/RELEASE.md`). So a checkout reports `0.0.0` and an
+  # installed gem reports the real version: that is intended, not a bug to fix by hardcoding one.
+  VERSION = "1.0.0"
+end

data/lib/mailkube/webhooks.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+require "json"
+
+module Mailkube
+  # Webhook signature verification.
+  #
+  # Verification is pure and dependency-free: no client instance, no configuration, so you call
+  # it directly inside your webhook handler.
+  module Webhooks
+    # How stale a webhook timestamp may be, in seconds, before it is rejected.
+    DEFAULT_TOLERANCE = 300
+    # The prefix the server puts before the hex digest in `X-Webhook-Sig`.
+    SIGNATURE_PREFIX = "sha256="
+    # Decode webhook payloads deep-frozen, so a receiver cannot mutate an event it is about to
+    # forward or log. Passed **positionally** because that is the shape `JSON.parse` declares
+    # (`(source, opts)`); as keywords Steep reports an unexpected keyword.
+    PARSE_OPTIONS = { freeze: true }.freeze
+
+    # Verify a webhook's signature and timestamp freshness over the raw body.
+    #
+    # The signed input is `"{id}.{timestamp}."` followed by the **raw** body, HMAC-SHA256 keyed
+    # by the endpoint's signing secret, hex-encoded, and sent as `X-Webhook-Sig: sha256=<hex>`.
+    # `X-Webhook-Ts` is an ISO-8601 timestamp checked for freshness; `X-Webhook-Id` is stable
+    # across retries, so use it to deduplicate.
+    #
+    # Verify against the bytes you received. Never parse the body and re-encode it first: JSON
+    # round-tripping reorders keys and normalizes whitespace, and the signature will not match.
+    # In Rails that means `request.raw_post`, not `params`.
+    #
+    # @param payload [String] the raw request body.
+    # @param headers [Hash{String => String}] the request headers, in any casing.
+    # @param secret [String] the endpoint's signing secret.
+    # @param tolerance [Integer] the freshness window in seconds.
+    # @return [String] the verified payload, so a caller can parse it in one expression.
+    # @raise [SignatureVerificationError] when a header is missing, the timestamp is stale, or
+    #   the signature does not match.
+    def self.verify_signature(payload:, headers:, secret:, tolerance: DEFAULT_TOLERANCE)
+      lookup = normalize_headers(headers)
+      id = lookup["x-webhook-id"]
+      timestamp = lookup["x-webhook-ts"]
+      signature = lookup["x-webhook-sig"]
+      if id.nil? || timestamp.nil? || signature.nil?
+        raise SignatureVerificationError, "missing required webhook signature headers"
+      end
+
+      check_freshness(timestamp, tolerance)
+      check_signature(payload, id, timestamp, signature, secret)
+      payload
+    end
+
+    # Parse a raw webhook body into a typed event.
+    #
+    # An event type this release has never heard of comes back as {Events::UnknownEvent} rather
+    # than raising: a receiver keeps working when the platform adds a type, with no SDK upgrade.
+    # That is the contract's deliberate inversion of the response-model rules, and it is why the
+    # dispatch is a `fetch` with a default rather than a conditional — an unknown type is the last
+    # row of the table, not an error path.
+    #
+    # Unknown *fields* survive too, at every depth: see {Events::Node}.
+    #
+    # @param payload [String] the raw request body.
+    # @return [Events::Event] the parsed event; narrow it with `case` or `is_a?`.
+    # @raise [Error] when the body is not a JSON object.
+    def self.parse_event(payload)
+      body = JSON.parse(payload, PARSE_OPTIONS)
+      raise Error, "webhook payload is not a JSON object" unless body.is_a?(Hash)
+
+      Events::REGISTRY.fetch(body["type"], Events::UnknownEvent).new(body)
+    rescue JSON::ParserError => e
+      raise Error, "webhook payload is not valid JSON: #{e.message}"
+    end
+
+    # Verify a webhook's signature and return the parsed event.
+    #
+    # The combinator most handlers actually want. It composes cleanly only because
+    # {verify_signature} returns the verified payload rather than true.
+    #
+    # @param payload [String] the raw request body.
+    # @param headers [Hash{String => String}, Enumerable] the request headers, in any casing.
+    # @param secret [String] the endpoint's signing secret.
+    # @param tolerance [Integer] the freshness window in seconds.
+    # @return [Events::Event] the verified, parsed event.
+    # @raise [SignatureVerificationError] when verification fails.
+    # @raise [Error] when the verified body is not valid JSON.
+    def self.verify(payload:, headers:, secret:, tolerance: DEFAULT_TOLERANCE)
+      parse_event(verify_signature(payload: payload, headers: headers, secret: secret, tolerance: tolerance))
+    end
+
+    # Normalize a header mapping to lowercase, dashed names.
+    #
+    # This accepts more than a Hash on purpose. `ActionDispatch::Http::Headers` is `Enumerable`
+    # but **not** a Hash, so the obvious `headers.transform_keys` raises `NoMethodError` on
+    # `request.headers` — which is exactly what a Rails receiver passes. Nor is `to_h` a fix:
+    # Rails' `#each` yields raw CGI env names, so a `to_h`-based lookup sees `HTTP_X_WEBHOOK_SIG`
+    # and never matches `x-webhook-sig`.
+    #
+    # Stripping the `http_` prefix and swapping underscores for dashes maps both spellings onto
+    # one, so a plain Hash, a Rack env and `request.headers` all work.
+    #
+    # @param headers [Hash{String => String}, Enumerable] the request headers, in any casing.
+    # @return [Hash{String => String}] the headers keyed by lowercase dashed name.
+    def self.normalize_headers(headers)
+      # Iterated with a block rather than collected through `each.to_h`, because a mapping is only
+      # required to yield — it is not required to hand back an Enumerator when called bare.
+      normalized = {} #: Hash[String, String]
+      headers.each { |name, value| normalized[canonical_header(name)] = value.to_s }
+      normalized
+    end
+    private_class_method :normalize_headers
+
+    # @param name [Object] a header name in any casing, dashed or in CGI env form.
+    # @return [String] the lowercase, dashed form.
+    def self.canonical_header(name) = name.to_s.downcase.delete_prefix("http_").tr("_", "-")
+    private_class_method :canonical_header
+
+    # @param timestamp [String] the ISO-8601 `X-Webhook-Ts` value.
+    # @param tolerance [Integer] the freshness window in seconds.
+    # @raise [SignatureVerificationError] when malformed or outside the window.
+    def self.check_freshness(timestamp, tolerance)
+      begin
+        parsed = Time.iso8601(timestamp)
+      rescue ArgumentError
+        raise SignatureVerificationError, "malformed X-Webhook-Ts timestamp"
+      end
+
+      return if (Time.now - parsed).abs <= tolerance
+
+      raise SignatureVerificationError, "timestamp is outside the freshness window"
+    end
+    private_class_method :check_freshness
+
+    # @param payload [String] the raw body.
+    # @param id [String] the `X-Webhook-Id` value.
+    # @param timestamp [String] the `X-Webhook-Ts` value.
+    # @param signature [String] the `X-Webhook-Sig` value.
+    # @param secret [String] the signing secret.
+    # @raise [SignatureVerificationError] when the digests differ.
+    def self.check_signature(payload, id, timestamp, signature, secret)
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{id}.#{timestamp}.#{payload}")
+      provided = signature.delete_prefix(SIGNATURE_PREFIX)
+      # Length is compared first because `fixed_length_secure_compare` raises on a mismatch, and
+      # the length of a hex digest is not a secret.
+      return if provided.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(provided, expected)
+
+      raise SignatureVerificationError, "signature mismatch"
+    end
+    private_class_method :check_signature
+  end
+end

data/lib/mailkube.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "mailkube/version"
+require_relative "mailkube/errors"
+require_relative "mailkube/logging"
+require_relative "mailkube/types"
+require_relative "mailkube/types/scheduled_emails"
+require_relative "mailkube/types/scheduled_acks"
+require_relative "mailkube/serialization"
+require_relative "mailkube/config"
+require_relative "mailkube/transport"
+require_relative "mailkube/net_http_adapter"
+require_relative "mailkube/resources/emails"
+require_relative "mailkube/resources/scheduled_email_requests"
+require_relative "mailkube/resources/scheduled_emails"
+require_relative "mailkube/client"
+require_relative "mailkube/events/node"
+require_relative "mailkube/events/contexts"
+require_relative "mailkube/events/payloads"
+require_relative "mailkube/events/envelopes"
+require_relative "mailkube/events/registry"
+require_relative "mailkube/webhooks"
+
+# mailkube-ruby: The official Ruby SDK for mailkube
+#
+#     client = Mailkube.new                      # reads MAILKUBE_API_KEY
+#     email = client.emails.send(
+#       from: "Acme <hello@yourdomain.com>",
+#       to: "customer@example.com",
+#       subject: "Hello world",
+#       html: "<p>It works!</p>"
+#     )
+#     email.id
+#
+# Errors form a hierarchy under {Error}, so rescue the category you care about:
+#
+#     begin
+#       client.emails.send(...)
+#     rescue Mailkube::RateLimitError => e
+#       sleep(e.retry_after || 1)
+#     end
+#
+# The conventions every mailkube SDK shares are in `.rules/SDK_CONTRACT.md`; how they are
+# realized in Ruby is in `.rules/SDK_DESIGN.md`.
+module Mailkube
+  # The API base URL used when nothing else is configured.
+  DEFAULT_BASE_URL = "https://api.mailkube.com/mta/v1/"
+
+  # Create a {Client}. Sugar for `Mailkube::Client.new`, which is what most callers want.
+  #
+  # @param options [Hash] forwarded verbatim to {Client#initialize}.
+  # @return [Client] the new client.
+  def self.new(**options) = Client.new(**options)
+
+  # Turn SDK request logging on. Sugar for {Logging.enable!}.
+  #
+  # The device is anything responding to `#write(String)`, so an application passes its own
+  # logger rather than being handed one:
+  #
+  #     Mailkube.enable_logging(device: Rails.logger)
+  #
+  # @param device [#write] where to write; defaults to `$stderr`.
+  # @return [#write] the device now in use.
+  def self.enable_logging(device: $stderr) = Logging.enable!(device: device)
+end
+
+# Honour `MAILKUBE_LOG` at load, so a deployment can turn logging on without a code change.
+Mailkube::Logging.enable_from_env

data/sig/mailkube/client.rbs

@@ -0,0 +1,9 @@
+module Mailkube
+  class Client
+    attr_reader emails: Resources::Emails
+    attr_reader scheduled_emails: Resources::ScheduledEmails
+
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> void
+    def base_url: () -> String
+  end
+end

data/sig/mailkube/config.rbs

@@ -0,0 +1,14 @@
+module Mailkube
+  class Config
+    ENV_API_KEY: String
+    ENV_BASE_URL: String
+    DEFAULT_TIMEOUT: Integer
+
+    attr_reader base_url: String
+    attr_reader timeout: Numeric
+
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric) -> void
+    def default_headers: () -> Hash[String, String]
+    def build_url: (String, ?Hash[String, String]) -> String
+  end
+end