mailkube 1.0.0

data/lib/mailkube/config.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Mailkube
+  # Resolved client configuration: the key, the origin, the timeout and the default headers.
+  #
+  # @api private This is internal plumbing, not part of the supported surface. Configure the client
+  #   through `Client.new` or the environment; both are documented in the README.
+  #
+  # This is the only place configuration is read, and the only place a URL is built. Keeping the
+  # origin guard here rather than in a resource protects every future link-following feature for
+  # free. Instances are frozen: a client that cannot be reconfigured after construction is a
+  # client that cannot develop a concurrency bug.
+  class Config
+    # Environment variable holding the API key.
+    ENV_API_KEY = "MAILKUBE_API_KEY"
+    # Environment variable overriding the API base URL.
+    ENV_BASE_URL = "MAILKUBE_BASE_URL"
+    # Per-request timeout in seconds when the caller does not set one.
+    DEFAULT_TIMEOUT = 30
+
+    # @return [String] the resolved API base URL, always ending in a slash.
+    attr_reader :base_url
+    # @return [Integer, Float] the per-request timeout in seconds.
+    attr_reader :timeout
+
+    # Resolve configuration from the arguments, then the environment, then the defaults.
+    #
+    # @param api_key [String, nil] the API key; falls back to `MAILKUBE_API_KEY`.
+    # @param base_url [String, nil] the API base URL; falls back to `MAILKUBE_BASE_URL`.
+    # @param timeout [Integer, Float] the per-request timeout in seconds.
+    # @raise [ConfigurationError] when no API key is available.
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT)
+      key = api_key || ENV.fetch(ENV_API_KEY, nil)
+      raise ConfigurationError, "no API key provided: pass api_key: or set #{ENV_API_KEY}" if key.nil? || key.empty?
+
+      @api_key = key
+      @base_url = base_url || ENV.fetch(ENV_BASE_URL, nil) || Mailkube::DEFAULT_BASE_URL
+      @timeout = timeout
+      freeze
+    end
+
+    # The auth and non-browser identification headers sent on every request.
+    #
+    # The User-Agent is required: the API rejects a request without one. It reports
+    # Mailkube::VERSION, which the gemspec also reads, so it cannot drift from the released
+    # version.
+    #
+    # @return [Hash{String => String}] the default headers.
+    def default_headers
+      {
+        "Authorization" => "Bearer #{@api_key}",
+        "User-Agent" => "mailkube-ruby/#{VERSION}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json"
+      }
+    end
+
+    # Join a relative path onto the base URL, attach the query, and refuse any absolute URL off
+    # the base URL's origin.
+    #
+    # Every request carries the Authorization header, so following a link that names a foreign
+    # host would hand that host the API key.
+    #
+    # The query is attached **after** the origin check and only when there is one, so an absolute
+    # page link the API issued keeps its own query untouched and an unfiltered listing produces no
+    # `?` at all. `URI.encode_www_form` — not {Serialization.escape_segment} — is correct here: a
+    # space in a query value is `+`, and a space in a path segment is `%20`.
+    #
+    # @param path [String] a relative path, or an absolute URL the API itself issued.
+    # @param params [Hash{String => String}] query parameters, already rendered to strings by
+    #   {Serialization.query}.
+    # @return [String] the absolute URL to request.
+    # @raise [ConfigurationError] when the result is not on the configured origin.
+    def build_url(path, params = {})
+      base = URI.parse(@base_url)
+      resolved = base.merge(path)
+      unless resolved.scheme == base.scheme && resolved.host == base.host && resolved.port == base.port
+        raise ConfigurationError, "refusing to follow #{resolved}: it is not on the configured API origin"
+      end
+
+      resolved.query = URI.encode_www_form(params) unless params.empty?
+      resolved.to_s
+    rescue URI::InvalidURIError, URI::InvalidComponentError => e
+      raise ConfigurationError, "invalid URL #{path.inspect}: #{e.message}"
+    end
+  end
+end

data/lib/mailkube/errors.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# The error taxonomy: one base class, one class per category, and the table that selects them.
+module Mailkube
+  # Base class for every error this gem raises.
+  #
+  # Rescue this to catch anything the SDK can raise, or a subclass to branch on the category.
+  # Ruby's idiom is an exception hierarchy rather than Go's sentinel values, so this mirrors the
+  # python, node and PHP SDKs one-for-one; the categories, and the status that selects each, are
+  # identical across all of them.
+  class Error < StandardError; end
+
+  # Raised when no API key is available, or configuration is otherwise unusable.
+  class ConfigurationError < Error; end
+
+  # Raised on a transport-level failure with no HTTP response: DNS, TCP, TLS or timeout.
+  class ConnectionError < Error; end
+
+  # Raised when a webhook signature or its timestamp cannot be verified.
+  class SignatureVerificationError < Error; end
+
+  # Raised for any non-2xx response, carrying the API's error envelope.
+  #
+  # Rescue a subclass to branch on the category, and read the attributes for the detail. The
+  # envelope's `name` stays a plain string, so a value this release has never heard of is
+  # reported verbatim rather than coerced.
+  class APIError < Error
+    # @return [String] the machine-readable name from the envelope, e.g. `quota_exceeded`.
+    attr_reader :error_name
+    # @return [Integer] the HTTP status code.
+    attr_reader :status_code
+    # @return [Hash] the decoded response body, or an empty hash.
+    attr_reader :body
+    # @return [Integer, nil] the Retry-After header in seconds, when the server sent one.
+    attr_reader :retry_after
+    # @return [String, nil] the server's request id, to quote to support.
+    attr_reader :request_id
+
+    # There is deliberately one base constructor taking the whole envelope, and no subclass
+    # overrides it. Eight subclasses each repeating an argument list is how a duplication gate
+    # starts failing and how two categories start reporting different fields.
+    def initialize(message = nil, error_name: "", status_code: 0, body: {}, retry_after: nil, request_id: nil)
+      super(message || (error_name.empty? ? "HTTP #{status_code}" : error_name))
+      @error_name = error_name
+      @status_code = status_code
+      @body = body
+      @retry_after = retry_after
+      @request_id = request_id
+    end
+  end
+
+  # HTTP 400: the request envelope was invalid.
+  class BadRequestError < APIError; end
+
+  # HTTP 403: authentication failed, or the key is forbidden from this action.
+  class AuthenticationError < APIError; end
+
+  # HTTP 404: a referenced resource was not found.
+  class NotFoundError < APIError; end
+
+  # HTTP 409: an idempotency conflict. The same key was reused with a different payload.
+  class ConflictError < APIError; end
+
+  # HTTP 422: the request was rejected by a send-policy check.
+  class InvalidRequestError < APIError; end
+
+  # HTTP 429: the rate limit was exceeded. Read {APIError#retry_after} before retrying.
+  class RateLimitError < APIError; end
+
+  # HTTP 5xx: an unexpected server error. Safe to retry with backoff.
+  class ServerError < APIError; end
+
+  # The documented values of the error envelope's `name` field.
+  #
+  # These are constants for discoverability, **not** a closed set: {APIError#error_name} stays a
+  # plain String, so a name this release has never heard of is reported verbatim instead of
+  # crashing an older client. The list tracks the public error reference and the other SDKs; add a
+  # constant when the API adds a name.
+  module ErrorName
+    APPLICATION_ERROR = "application_error"
+    BODY_CONTENT_REJECTED = "body_content_rejected"
+    BROWSER_NOT_ALLOWED = "browser_not_allowed"
+    CONCURRENT_IDEMPOTENT_REQUESTS = "concurrent_idempotent_requests"
+    FROM_DOMAIN_NOT_ALLOWED = "from_domain_not_allowed"
+    INVALID_API_KEY = "invalid_api_key"
+    INVALID_ATTACHMENT = "invalid_attachment"
+    INVALID_FROM_ADDRESS = "invalid_from_address"
+    INVALID_IDEMPOTENCY_KEY = "invalid_idempotency_key"
+    INVALID_IDEMPOTENT_REQUEST = "invalid_idempotent_request"
+    INVALID_REQUEST_BODY = "invalid_request_body"
+    LINK_REPUTATION_BLOCKED = "link_reputation_blocked"
+    MAX_MESSAGE_SIZE_EXCEEDED = "max_message_size_exceeded"
+    MAX_RECIPIENTS_EXCEEDED = "max_recipients_exceeded"
+    METHOD_NOT_ALLOWED = "method_not_allowed"
+    MISSING_REQUIRED_FIELD = "missing_required_field"
+    MISSING_REQUIRED_VARIABLE = "missing_required_variable"
+    MISSING_USER_AGENT = "missing_user_agent"
+    NOT_ACCEPTABLE = "not_acceptable"
+    QUOTA_EXCEEDED = "quota_exceeded"
+    RATE_LIMIT_EXCEEDED = "rate_limit_exceeded"
+    SCHEDULED_EMAIL_NOT_FOUND = "scheduled_email_not_found"
+    SCHEDULED_EMAIL_NOT_PENDING = "scheduled_email_not_pending"
+    SCHEDULING_NOT_INCLUDED = "scheduling_not_included"
+    TEMPLATE_NOT_FOUND = "template_not_found"
+    TEMPLATE_NOT_PUBLISHED = "template_not_published"
+    TOPIC_DISABLED = "topic_disabled"
+    TOPIC_NOT_FOUND = "topic_not_found"
+    UNSUPPORTED_MEDIA_TYPE = "unsupported_media_type"
+    VALIDATION_ERROR = "validation_error"
+  end
+
+  # Maps an HTTP status to its error class. Any other 5xx is {ServerError}; the rest {APIError}.
+  STATUS_ERRORS = {
+    400 => BadRequestError,
+    403 => AuthenticationError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => InvalidRequestError,
+    429 => RateLimitError
+  }.freeze
+
+  # Returns the error class for an HTTP status.
+  #
+  # @param status [Integer] the HTTP status code.
+  # @return [Class] the {APIError} subclass to raise.
+  def self.error_class_for(status)
+    return STATUS_ERRORS.fetch(status) if STATUS_ERRORS.key?(status)
+    return ServerError if status >= 500
+
+    APIError
+  end
+end

data/lib/mailkube/events/contexts.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Events
+    # The message an event is about: the fields every `email.*` event carries.
+    #
+    # The shared base of all nine `email.*` payloads, mirroring the server, where one serializer
+    # supplies this block to every message event.
+    #
+    # Every field except the id and timestamp is nullable: they are denormalized from the send
+    # transaction, and there is a window in which an event can be emitted before that row exists.
+    class MessageContext < Node
+      # @return [String] the message's UUID.
+      def email_id = self["email_id"]
+      # @return [String] when the message was accepted.
+      def created_at = self["created_at"]
+      # @return [String, nil] the sending domain.
+      def domain = self["domain"]
+      # @return [String, nil] the subject line.
+      def subject = self["subject"]
+      # @return [Array<String>, nil] the recipients.
+      def to = self["to"]
+      # `from` is the wire key and is neither a Ruby keyword nor an Object method, so it needs no
+      # renaming — unlike Python, where `from_` is forced.
+      # @return [String, nil] the sender address.
+      def from = self["from"]
+
+      # Tags stay plain hashes, and {Mailkube::Tag} stays the one **send-side** type.
+      #
+      # `Tag` is a `Data` with fixed members, so building one here would silently drop an unknown
+      # key *inside* a tag — the preservation rule violated three levels down, where nothing on the
+      # send side would notice. A second inbound tag class would preserve the keys but cost the SDK
+      # family its one-tag-type story. A hash costs neither. The rule: `Tag` is what you construct,
+      # a hash is what you read.
+      #
+      # @return [Array<Hash{String => Object}>] the tags attached at send time, verbatim.
+      def tags = self["tags"] || []
+    end
+
+    # A single-recipient delivery outcome (`email.delivered`, `email.sent`).
+    class DeliveryContext < Node
+      # @return [String] the recipient this outcome is about.
+      def recipient = self["recipient"]
+      # @return [String] when the outcome was recorded.
+      def timestamp = self["timestamp"]
+    end
+
+    # A delivery failure, carrying the receiving server's verdict.
+    #
+    # Subclasses {DeliveryContext} because it mirrors the server's own serializer inheritance: a
+    # failure *is* a delivery outcome plus a reason.
+    class FailureContext < DeliveryContext
+      # @return [Integer] the SMTP status code the receiving server returned.
+      def code = self["code"]
+      # Server-controlled, and deliberately a plain String: a closed set would turn a reason added
+      # later into a parse error on an already-released client.
+      # @return [String] the failure reason.
+      def reason = self["reason"]
+    end
+
+    # An open interaction (`email.opened`).
+    #
+    # These nested keys are camelCase on the wire, unlike every other block here. The SDK mirrors
+    # the server rather than normalizing it.
+    class EngagementContext < Node
+      # @return [String] the opening client's IP address (wire key `ipAddress`).
+      def ip_address = self["ipAddress"]
+      # @return [String] the opening client's user agent (wire key `userAgent`).
+      def user_agent = self["userAgent"]
+      # @return [String] when the interaction was recorded.
+      def timestamp = self["timestamp"]
+    end
+
+    # A click interaction (`email.clicked`): an open, plus the link that was clicked.
+    class ClickContext < EngagementContext
+      # @return [String] the clicked URL.
+      def link = self["link"]
+    end
+
+    # Recipients suppressed for a message (`email.suppressed`).
+    class SuppressionContext < Node
+      # @return [Array<String>] the suppressed recipients.
+      def recipients = self["recipients"]
+      # @return [String] when the suppression was applied.
+      def timestamp = self["timestamp"]
+    end
+
+    # When a scheduled send is due (`email.scheduled`).
+    #
+    # Unlike the engagement blocks, these keys are snake_case on the wire.
+    class ScheduledContext < Node
+      # @return [String] when the send is due.
+      def scheduled_at = self["scheduled_at"]
+      # @return [String, nil] the batch label the send was grouped under.
+      def batch_id = self["batch_id"]
+    end
+
+    # Why a scheduled send never went out (`email.failed`).
+    #
+    # Deliberately **not** a {FailureContext}: this is message-level, so there is no recipient and
+    # no SMTP code. `reason` stays a plain String for the same reason as everywhere else.
+    class SendFailureContext < Node
+      # @return [String] why the send failed, e.g. `mta_unreachable`.
+      def reason = self["reason"]
+      # @return [String] when the failure was recorded.
+      def timestamp = self["timestamp"]
+    end
+
+    # A sending domain's state before a `domain.status` change.
+    class DomainStatusPrevious < Node
+      # @return [String] the previous status.
+      def status = self["status"]
+      # @return [String] the previous onboarding state.
+      def onboarding_state = self["onboarding_state"]
+    end
+
+    # A webhook endpoint's state before a `webhook.status` change.
+    class WebhookStatusPrevious < Node
+      # Spelled `active?` rather than `is_active`: Ruby's predicate convention. The wire key stays
+      # `is_active`, and {Node#[]} reaches it under that name.
+      # @return [Boolean] whether the endpoint was active.
+      def active? = self["is_active"]
+      # @return [Boolean] whether the endpoint was deleted.
+      def deleted? = self["is_deleted"]
+      # @return [String] why the endpoint was disabled, e.g. `none`, `user`, `low_quality`.
+      def disabled_reason = self["disabled_reason"]
+    end
+  end
+end

data/lib/mailkube/events/envelopes.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Events
+    # The envelope every webhook payload arrives in: a type, a timestamp, and a `data` block.
+    #
+    # There is deliberately **no `id`** here. The delivery id travels in the `X-Webhook-Id` header,
+    # is stable across retries, and is what you deduplicate on — so it belongs to the request, not
+    # to the parsed body.
+    #
+    # `data` is declared on each concrete subclass rather than here, which is what lets
+    # {UnknownEvent} hand back a raw Hash without conflicting with a typed sibling.
+    class Event < Node
+      # @return [String] the event type, e.g. `email.delivered`.
+      def type = self["type"]
+      # @return [String] when the event occurred.
+      def created_at = self["created_at"]
+    end
+
+    # A message left the platform for its recipient's server.
+    class EmailSentEvent < Event
+      # @return [SentData] the event payload.
+      def data = block(SentData, "data")
+    end
+
+    # A recipient's server accepted the message.
+    class EmailDeliveredEvent < Event
+      # @return [DeliveredData] the event payload.
+      def data = block(DeliveredData, "data")
+    end
+
+    # A recipient's server rejected the message permanently.
+    class EmailBouncedEvent < Event
+      # @return [BouncedData] the event payload.
+      def data = block(BouncedData, "data")
+    end
+
+    # A recipient's server deferred the message; delivery will be retried.
+    class EmailDeliveryDelayedEvent < Event
+      # @return [DelayedData] the event payload.
+      def data = block(DelayedData, "data")
+    end
+
+    # Recipients were suppressed rather than sent to.
+    class EmailSuppressedEvent < Event
+      # @return [SuppressedData] the event payload.
+      def data = block(SuppressedData, "data")
+    end
+
+    # A send was accepted for later delivery.
+    class EmailScheduledEvent < Event
+      # @return [ScheduledData] the event payload.
+      def data = block(ScheduledData, "data")
+    end
+
+    # A scheduled send never went out.
+    class EmailFailedEvent < Event
+      # @return [FailedData] the event payload.
+      def data = block(FailedData, "data")
+    end
+
+    # A recipient opened the message.
+    class EmailOpenedEvent < Event
+      # @return [OpenedData] the event payload.
+      def data = block(OpenedData, "data")
+    end
+
+    # A recipient clicked a link in the message.
+    class EmailClickedEvent < Event
+      # @return [ClickedData] the event payload.
+      def data = block(ClickedData, "data")
+    end
+
+    # A sending domain's status or onboarding state changed.
+    class DomainStatusEvent < Event
+      # @return [DomainStatusData] the event payload.
+      def data = block(DomainStatusData, "data")
+    end
+
+    # A webhook endpoint was enabled, disabled or deleted.
+    class WebhookStatusEvent < Event
+      # @return [WebhookStatusData] the event payload.
+      def data = block(WebhookStatusData, "data")
+    end
+
+    # An event type this release has never heard of.
+    #
+    # Not an error: the contract requires an unknown type to degrade to untyped access so that a
+    # receiver keeps working when the platform adds a type, with no SDK upgrade. {#data} is the raw
+    # hash, and {Node#[]} reaches anything inside it.
+    class UnknownEvent < Event
+      # @return [Hash{String => Object}] the payload, undecoded.
+      def data = self["data"] || {}
+    end
+  end
+end

data/lib/mailkube/events/node.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # Typed models for inbound webhook payloads.
+  module Events
+    # A typed lens over one decoded JSON object from a webhook payload.
+    #
+    # Every other model in this gem is a `Data.define`, whose members are fixed — which is exactly
+    # why none of them can be used here. The contract **inverts** the response-model rule for
+    # events: unknown fields are *preserved*, not dropped, at every nesting depth, so a receiver
+    # that logs or forwards an event keeps fields this release predates. A `Data` drops them at
+    # parse time and offers no way to ask it not to.
+    #
+    # So the storage is inverted rather than fought. The decoded hash **is** this object's state,
+    # and a subclass adds one-line readers naming the fields this release knows. Nothing is copied,
+    # so nothing can be lost, and {#raw} round-trips to exactly what the server sent. Nested blocks
+    # are built on read, so a receiver that only touches `data.email_id` never allocates the rest.
+    #
+    # Readers are written out as plain `def`s rather than generated by a macro: Steep's
+    # `UndeclaredMethodDefinition` gate reads what is in `lib/`, and a generated reader is a method
+    # no signature can be matched against.
+    class Node
+      # @return [Hash{String => Object}] the verbatim decoded object, unknown fields included.
+      attr_reader :raw
+
+      # @param raw [Hash{String => Object}] the decoded JSON object for this block.
+      def initialize(raw)
+        @raw = raw
+        freeze
+      end
+
+      # Read any field by its wire name, whether or not this release models it.
+      #
+      # This is the forward-compatibility escape hatch the contract asks for: a field the platform
+      # adds after this gem ships is reachable here on the day it appears.
+      #
+      # @param key [String] the wire field name.
+      # @return [Object, nil] the value, or nil when the server did not send it.
+      def [](key) = @raw[key]
+
+      # @return [Hash{String => Object}] the verbatim decoded object, for logging or forwarding.
+      def to_h = @raw
+
+      # @param other [Object] the object to compare with.
+      # @return [Boolean] true when both are the same class over the same payload.
+      def ==(other) = other.instance_of?(self.class) && other.raw == @raw
+      alias eql? ==
+
+      # @return [Integer] a hash consistent with {#==}.
+      def hash = [self.class, @raw].hash
+
+      private
+
+      # Build a nested block, tolerating a server that omitted the key entirely.
+      #
+      # @param type [Class] the {Node} subclass modelling the nested object.
+      # @param key [String] the wire field holding it.
+      # @return [Node] the nested block.
+      def block(type, key) = type.new(self[key] || {})
+    end
+  end
+end

data/lib/mailkube/events/payloads.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Events
+    # The `data` of `email.sent`: the message, plus the delivery attempt that left the platform.
+    class SentData < MessageContext
+      # @return [DeliveryContext] the send outcome.
+      def sent = block(DeliveryContext, "sent")
+    end
+
+    # The `data` of `email.delivered`: the message, plus the accepted delivery.
+    class DeliveredData < MessageContext
+      # @return [DeliveryContext] the delivery outcome.
+      def delivery = block(DeliveryContext, "delivery")
+    end
+
+    # The `data` of `email.bounced`: the message, plus the receiving server's rejection.
+    class BouncedData < MessageContext
+      # @return [FailureContext] the bounce, with its SMTP code and reason.
+      def bounce = block(FailureContext, "bounce")
+    end
+
+    # The `data` of `email.delivery_delayed`: the message, plus the deferral.
+    class DelayedData < MessageContext
+      # @return [FailureContext] the deferral, with its SMTP code and reason.
+      def delay = block(FailureContext, "delay")
+    end
+
+    # The `data` of `email.suppressed`: the message, plus who was suppressed.
+    class SuppressedData < MessageContext
+      # @return [SuppressionContext] the suppressed recipients.
+      def suppression = block(SuppressionContext, "suppression")
+    end
+
+    # The `data` of `email.scheduled`: the message, plus when it is due.
+    class ScheduledData < MessageContext
+      # @return [ScheduledContext] the due time and batch.
+      def scheduled = block(ScheduledContext, "scheduled")
+    end
+
+    # The `data` of `email.failed`: the message, plus why it never went out.
+    class FailedData < MessageContext
+      # @return [SendFailureContext] the message-level failure.
+      def failed = block(SendFailureContext, "failed")
+    end
+
+    # The `data` of `email.opened`: the message, plus the open.
+    class OpenedData < MessageContext
+      # @return [EngagementContext] the open.
+      def open = block(EngagementContext, "open")
+    end
+
+    # The `data` of `email.clicked`: the message, plus the click.
+    class ClickedData < MessageContext
+      # @return [ClickContext] the click, including the link.
+      def click = block(ClickContext, "click")
+    end
+
+    # The `data` of `domain.status`: a sending domain's new state, and its previous one.
+    #
+    # Not a {MessageContext}: a domain lifecycle event is about the domain, not about a message.
+    # `status` and `onboarding_state` are server-controlled strings, not enums.
+    class DomainStatusData < Node
+      # @return [String] the domain.
+      def domain = self["domain"]
+      # @return [String] the new status.
+      def status = self["status"]
+      # @return [String] the new onboarding state.
+      def onboarding_state = self["onboarding_state"]
+      # @return [DomainStatusPrevious] the state before this change.
+      def previous = block(DomainStatusPrevious, "previous")
+    end
+
+    # The `data` of `webhook.status`: an endpoint's new state, and its previous one.
+    class WebhookStatusData < Node
+      # @return [String] the endpoint's URL.
+      def endpoint_url = self["endpoint_url"]
+      # @return [Boolean] whether the endpoint is now active.
+      def active? = self["is_active"]
+      # @return [Boolean] whether the endpoint is now deleted.
+      def deleted? = self["is_deleted"]
+      # @return [String] why the endpoint was disabled.
+      def disabled_reason = self["disabled_reason"]
+      # @return [WebhookStatusPrevious] the state before this change.
+      def previous = block(WebhookStatusPrevious, "previous")
+    end
+  end
+end

data/lib/mailkube/events/registry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Events
+    # Every event type this release knows, mapped to the envelope that models it.
+    #
+    # **This constant is the catalogue.** The known-type set is derived from it (`REGISTRY.keys`)
+    # and never written out beside it: a hand-maintained parallel list that missed an entry would
+    # route a wired-up event to {UnknownEvent} at runtime, silently, with no test failing.
+    #
+    # Registering an event is adding one row here. There is no second place to update.
+    REGISTRY = {
+      "email.sent" => EmailSentEvent,
+      "email.delivered" => EmailDeliveredEvent,
+      "email.bounced" => EmailBouncedEvent,
+      "email.delivery_delayed" => EmailDeliveryDelayedEvent,
+      "email.suppressed" => EmailSuppressedEvent,
+      "email.scheduled" => EmailScheduledEvent,
+      "email.failed" => EmailFailedEvent,
+      "email.opened" => EmailOpenedEvent,
+      "email.clicked" => EmailClickedEvent,
+      "domain.status" => DomainStatusEvent,
+      "webhook.status" => WebhookStatusEvent
+    }.freeze
+  end
+end