mailkube 1.0.0

data/sig/mailkube/errors.rbs

@@ -0,0 +1,78 @@
+module Mailkube
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class SignatureVerificationError < Error
+  end
+
+  class APIError < Error
+    attr_reader error_name: String
+    attr_reader status_code: Integer
+    attr_reader body: Hash[String, untyped]
+    attr_reader retry_after: Integer?
+    attr_reader request_id: String?
+
+    def initialize: (?String?, ?error_name: String, ?status_code: Integer, ?body: Hash[String, untyped],
+                     ?retry_after: Integer?, ?request_id: String?) -> void
+  end
+
+  class BadRequestError < APIError
+  end
+
+  class AuthenticationError < APIError
+  end
+
+  class NotFoundError < APIError
+  end
+
+  class ConflictError < APIError
+  end
+
+  class InvalidRequestError < APIError
+  end
+
+  class RateLimitError < APIError
+  end
+
+  class ServerError < APIError
+  end
+
+  module ErrorName
+    APPLICATION_ERROR: String
+    BODY_CONTENT_REJECTED: String
+    BROWSER_NOT_ALLOWED: String
+    CONCURRENT_IDEMPOTENT_REQUESTS: String
+    FROM_DOMAIN_NOT_ALLOWED: String
+    INVALID_API_KEY: String
+    INVALID_ATTACHMENT: String
+    INVALID_FROM_ADDRESS: String
+    INVALID_IDEMPOTENCY_KEY: String
+    INVALID_IDEMPOTENT_REQUEST: String
+    INVALID_REQUEST_BODY: String
+    LINK_REPUTATION_BLOCKED: String
+    MAX_MESSAGE_SIZE_EXCEEDED: String
+    MAX_RECIPIENTS_EXCEEDED: String
+    METHOD_NOT_ALLOWED: String
+    MISSING_REQUIRED_FIELD: String
+    MISSING_REQUIRED_VARIABLE: String
+    MISSING_USER_AGENT: String
+    NOT_ACCEPTABLE: String
+    QUOTA_EXCEEDED: String
+    RATE_LIMIT_EXCEEDED: String
+    SCHEDULED_EMAIL_NOT_FOUND: String
+    SCHEDULED_EMAIL_NOT_PENDING: String
+    SCHEDULING_NOT_INCLUDED: String
+    TEMPLATE_NOT_FOUND: String
+    TEMPLATE_NOT_PUBLISHED: String
+    TOPIC_DISABLED: String
+    TOPIC_NOT_FOUND: String
+    UNSUPPORTED_MEDIA_TYPE: String
+    VALIDATION_ERROR: String
+  end
+end

data/sig/mailkube/events/contexts.rbs

@@ -0,0 +1,60 @@
+module Mailkube
+  module Events
+    class MessageContext < Node
+      def email_id: () -> String
+      def created_at: () -> String
+      def domain: () -> String?
+      def subject: () -> String?
+      def to: () -> Array[String]?
+      def from: () -> String?
+      # Plain hashes, not `Mailkube::Tag`: a `Data` would drop an unknown key inside a tag.
+      def tags: () -> Array[Hash[String, untyped]]
+    end
+
+    class DeliveryContext < Node
+      def recipient: () -> String
+      def timestamp: () -> String
+    end
+
+    class FailureContext < DeliveryContext
+      def code: () -> Integer
+      def reason: () -> String
+    end
+
+    class EngagementContext < Node
+      def ip_address: () -> String
+      def user_agent: () -> String
+      def timestamp: () -> String
+    end
+
+    class ClickContext < EngagementContext
+      def link: () -> String
+    end
+
+    class SuppressionContext < Node
+      def recipients: () -> Array[String]
+      def timestamp: () -> String
+    end
+
+    class ScheduledContext < Node
+      def scheduled_at: () -> String
+      def batch_id: () -> String?
+    end
+
+    class SendFailureContext < Node
+      def reason: () -> String
+      def timestamp: () -> String
+    end
+
+    class DomainStatusPrevious < Node
+      def status: () -> String
+      def onboarding_state: () -> String
+    end
+
+    class WebhookStatusPrevious < Node
+      def active?: () -> bool
+      def deleted?: () -> bool
+      def disabled_reason: () -> String
+    end
+  end
+end

data/sig/mailkube/events/envelopes.rbs

@@ -0,0 +1,60 @@
+module Mailkube
+  module Events
+    # `data` is declared per concrete subclass rather than on `Event`, which is what lets
+    # `UnknownEvent#data` return a raw Hash without conflicting with a typed sibling.
+    #
+    # There is no `id`: the delivery id travels in the `X-Webhook-Id` header.
+    class Event < Node
+      def type: () -> String
+      def created_at: () -> String
+    end
+
+    class EmailSentEvent < Event
+      def data: () -> SentData
+    end
+
+    class EmailDeliveredEvent < Event
+      def data: () -> DeliveredData
+    end
+
+    class EmailBouncedEvent < Event
+      def data: () -> BouncedData
+    end
+
+    class EmailDeliveryDelayedEvent < Event
+      def data: () -> DelayedData
+    end
+
+    class EmailSuppressedEvent < Event
+      def data: () -> SuppressedData
+    end
+
+    class EmailScheduledEvent < Event
+      def data: () -> ScheduledData
+    end
+
+    class EmailFailedEvent < Event
+      def data: () -> FailedData
+    end
+
+    class EmailOpenedEvent < Event
+      def data: () -> OpenedData
+    end
+
+    class EmailClickedEvent < Event
+      def data: () -> ClickedData
+    end
+
+    class DomainStatusEvent < Event
+      def data: () -> DomainStatusData
+    end
+
+    class WebhookStatusEvent < Event
+      def data: () -> WebhookStatusData
+    end
+
+    class UnknownEvent < Event
+      def data: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/mailkube/events/node.rbs

@@ -0,0 +1,32 @@
+module Mailkube
+  module Events
+    # Event models are the one place this gem does **not** use `Data.define`.
+    #
+    # The contract inverts the response-model rule for webhooks: unknown fields are preserved, not
+    # dropped, at every depth. A `Data` has fixed members and drops them, so the decoded hash is
+    # the state instead, and each subclass declares one-line readers over it.
+    #
+    # Those readers are real `def`s, so they are declared here as `def` — `attr_reader` in these
+    # signatures is reserved for the readers `Data.define` actually generates (see
+    # `sig/mailkube/types.rbs`).
+    class Node
+      @raw: Hash[String, untyped]
+
+      attr_reader raw: Hash[String, untyped]
+
+      def initialize: (Hash[String, untyped]) -> void
+      def []: (String) -> untyped
+      def to_h: () -> Hash[String, untyped]
+      def ==: (untyped) -> bool
+      def eql?: (untyped) -> bool
+      def hash: () -> Integer
+
+      private
+
+      # Deliberately `untyped` rather than a bounded generic: Ruby has no generics, and every
+      # caller is a one-line reader that already declares its own concrete return type — which is
+      # where the type belongs.
+      def block: (untyped, String) -> untyped
+    end
+  end
+end

data/sig/mailkube/events/payloads.rbs

@@ -0,0 +1,54 @@
+module Mailkube
+  module Events
+    class SentData < MessageContext
+      def sent: () -> DeliveryContext
+    end
+
+    class DeliveredData < MessageContext
+      def delivery: () -> DeliveryContext
+    end
+
+    class BouncedData < MessageContext
+      def bounce: () -> FailureContext
+    end
+
+    class DelayedData < MessageContext
+      def delay: () -> FailureContext
+    end
+
+    class SuppressedData < MessageContext
+      def suppression: () -> SuppressionContext
+    end
+
+    class ScheduledData < MessageContext
+      def scheduled: () -> ScheduledContext
+    end
+
+    class FailedData < MessageContext
+      def failed: () -> SendFailureContext
+    end
+
+    class OpenedData < MessageContext
+      def open: () -> EngagementContext
+    end
+
+    class ClickedData < MessageContext
+      def click: () -> ClickContext
+    end
+
+    class DomainStatusData < Node
+      def domain: () -> String
+      def status: () -> String
+      def onboarding_state: () -> String
+      def previous: () -> DomainStatusPrevious
+    end
+
+    class WebhookStatusData < Node
+      def endpoint_url: () -> String
+      def active?: () -> bool
+      def deleted?: () -> bool
+      def disabled_reason: () -> String
+      def previous: () -> WebhookStatusPrevious
+    end
+  end
+end

data/sig/mailkube/events/registry.rbs

@@ -0,0 +1,6 @@
+module Mailkube
+  module Events
+    # The catalogue. The known-type set is `REGISTRY.keys`; there is no parallel list.
+    REGISTRY: Hash[String, singleton(Event)]
+  end
+end

data/sig/mailkube/logging.rbs

@@ -0,0 +1,26 @@
+module Mailkube
+  # Anything a caller may point SDK logging at. The seam is `#write` rather than a stdlib `Logger`
+  # because `logger` is a bundled gem from Ruby 4.0 and this gem has no runtime dependencies.
+  interface _LogDevice
+    def write: (String) -> untyped
+  end
+
+  module Logging
+    ENV_LEVEL: String
+    VERBOSE_LEVELS: Array[String]
+    SENSITIVE_HEADERS: Array[String]
+    REDACTION: String
+
+    self.@device: _LogDevice?
+
+    def self.device: () -> _LogDevice?
+    def self.enable!: (?device: _LogDevice) -> _LogDevice
+    def self.disable!: () -> nil
+    def self.enable_from_env: (?Hash[String, String]) -> _LogDevice?
+    def self.redact: (Hash[String, String]) -> Hash[String, String]
+    def self.request: (String, String, Hash[String, String]) -> void
+    def self.response: (Integer, String, ?String?) -> void
+  end
+
+  def self.enable_logging: (?device: _LogDevice) -> _LogDevice
+end

data/sig/mailkube/net_http_adapter.rbs

@@ -0,0 +1,15 @@
+module Mailkube
+  class NetHttpAdapter
+    METHODS: Hash[String, untyped]
+    TRANSPORT_ERRORS: Array[untyped]
+
+    def initialize: (?timeout: Numeric) -> void
+    def call: (method: String, url: String, headers: Hash[String, String], ?body: String?) -> HttpResponse
+
+    private
+
+    def parse_url: (String) -> URI::Generic
+    def build_request: (String, URI::Generic, Hash[String, String], String?) -> untyped
+    def to_response: (untyped) -> HttpResponse
+  end
+end

data/sig/mailkube/resources/emails.rbs

@@ -0,0 +1,18 @@
+module Mailkube
+  module Resources
+    class Emails
+      def initialize: (_SendTransport) -> void
+
+      def send: (from: String, to: (String | Array[String]), subject: String, ?html: String?, ?text: String?,
+                 ?cc: Array[String]?, ?bcc: Array[String]?, ?reply_to: (String | Array[String])?,
+                 ?headers: Hash[String, String]?, ?attachments: Array[Attachment]?, ?tags: Array[Tag]?,
+                 ?template_id: String?, ?template_version: String?, ?variables: Hash[String, untyped]?,
+                 ?topic: String?, ?idempotency_key: String?, ?scheduled_at: (Time | String)?,
+                 ?batch_id: String?) -> Email
+
+      private
+
+      def idempotency: (String?) -> Hash[String, String]
+    end
+  end
+end

data/sig/mailkube/resources/scheduled_email_requests.rbs

@@ -0,0 +1,19 @@
+module Mailkube
+  module Resources
+    module ScheduledEmailRequests
+      COLLECTION: String
+      BATCHES: String
+
+      def self.item: (String, String, String, ?Hash[String, untyped]?) -> RequestSpec
+      def self.list: (?status: (String | Array[String])?, ?batch_id: String?,
+                      ?scheduled_at_gte: (Time | String)?, ?scheduled_at_lte: (Time | String)?,
+                      ?page: Integer?) -> RequestSpec
+      def self.page: (String) -> RequestSpec
+      def self.get: (String) -> RequestSpec
+      def self.update: (String, Hash[String, untyped]) -> RequestSpec
+      def self.cancel: (String) -> RequestSpec
+      def self.batch_update: (String, Hash[String, untyped]) -> RequestSpec
+      def self.batch_cancel: (String) -> RequestSpec
+    end
+  end
+end

data/sig/mailkube/resources/scheduled_emails.rbs

@@ -0,0 +1,32 @@
+module Mailkube
+  module Resources
+    class ScheduledEmailBatches
+      def initialize: (_JsonTransport) -> void
+      def update: (String, scheduled_at: (Time | String)) -> ScheduledEmailBatchUpdate
+      def cancel: (String) -> ScheduledEmailBatchCancel
+    end
+
+    class ScheduledEmails
+      attr_reader batches: ScheduledEmailBatches
+
+      def initialize: (_JsonTransport) -> void
+
+      def list: (?status: (String | Array[String])?, ?batch_id: String?,
+                 ?scheduled_at_gte: (Time | String)?, ?scheduled_at_lte: (Time | String)?,
+                 ?page: Integer?) -> ScheduledEmailPage
+
+      # A lazy `Enumerator`, so abandoning the walk early costs nothing.
+      def iter_all: (?status: (String | Array[String])?, ?batch_id: String?,
+                     ?scheduled_at_gte: (Time | String)?, ?scheduled_at_lte: (Time | String)?,
+                     ?page: Integer?) -> Enumerator[ScheduledEmail, void]
+
+      def get: (String) -> ScheduledEmail
+      def update: (String, scheduled_at: (Time | String), ?batch_id: String?) -> ScheduledEmail
+      def cancel: (String) -> CanceledScheduledEmail
+
+      private
+
+      def fetch_page: (RequestSpec) -> ScheduledEmailPage
+    end
+  end
+end

data/sig/mailkube/serialization.rbs

@@ -0,0 +1,11 @@
+module Mailkube
+  module Serialization
+    def self.to_iso: ((Time | String)?) -> String?
+    def self.query_value: (untyped) -> String
+    def self.query_scalar: (untyped) -> String
+    def self.query: (Hash[Symbol, untyped]) -> Hash[String, String]
+    def self.escape_segment: (String) -> String
+    def self.encode_attachments: (Array[Attachment]?) -> Array[Hash[String, untyped]]?
+    def self.encode_tags: (Array[Tag]?) -> Array[Hash[String, untyped]]?
+  end
+end

data/sig/mailkube/transport.rbs

@@ -0,0 +1,34 @@
+module Mailkube
+  class RequestSpec
+    attr_reader path: String
+    attr_reader method: String
+    attr_reader body: Hash[String, untyped]?
+    attr_reader params: Hash[String, String]
+    attr_reader headers: Hash[String, String]
+
+    def initialize: (path: String, ?method: String, ?body: Hash[String, untyped]?,
+                     ?params: Hash[String, String], ?headers: Hash[String, String]) -> void
+  end
+
+  class HttpResponse
+    attr_reader status: Integer
+    attr_reader headers: Hash[String, String]
+    attr_reader body: String
+
+    def initialize: (status: Integer, ?headers: Hash[String, String], ?body: String) -> void
+    def header: (String) -> String?
+  end
+
+  class Transport
+    def initialize: (Config, _HttpAdapter) -> void
+    def send_email: (RequestSpec) -> Email
+    def request_json: (RequestSpec) -> Hash[String, untyped]
+
+    private
+
+    def perform: (RequestSpec) -> HttpResponse
+    def error_for: (HttpResponse) -> APIError
+    def decode_object: (String) -> Hash[String, untyped]?
+    def decode: (String) -> Hash[String, untyped]
+  end
+end

data/sig/mailkube/types/scheduled_acks.rbs

@@ -0,0 +1,30 @@
+module Mailkube
+  class CanceledScheduledEmail
+    attr_reader id: String
+    attr_reader object: String
+    attr_reader status: String
+
+    def initialize: (id: String, ?object: String, ?status: String) -> void
+    def self.from: (Hash[String, untyped]) -> CanceledScheduledEmail
+  end
+
+  class ScheduledEmailBatchCancel
+    attr_reader object: String
+    attr_reader batch_id: String
+    attr_reader canceled_count: Integer
+
+    def initialize: (?object: String, ?batch_id: String, ?canceled_count: Integer) -> void
+    def self.from: (Hash[String, untyped]) -> ScheduledEmailBatchCancel
+  end
+
+  class ScheduledEmailBatchUpdate
+    attr_reader object: String
+    attr_reader batch_id: String
+    attr_reader rescheduled_count: Integer
+    attr_reader scheduled_at: String?
+
+    def initialize: (?object: String, ?batch_id: String, ?rescheduled_count: Integer,
+                     ?scheduled_at: String?) -> void
+    def self.from: (Hash[String, untyped]) -> ScheduledEmailBatchUpdate
+  end
+end

data/sig/mailkube/types/scheduled_emails.rbs

@@ -0,0 +1,53 @@
+module Mailkube
+  # Declared the same way as every other model — see `sig/mailkube/types.rbs` for why these are
+  # plain classes that do not name `::Data` as a superclass.
+  class ScheduledEmail
+    attr_reader id: String
+    attr_reader message_id: String?
+    attr_reader object: String
+    attr_reader status: String
+    attr_reader scheduled_at: String?
+    attr_reader created_at: String?
+    attr_reader batch_id: String?
+    attr_reader subject: String?
+    attr_reader recipients: String?
+    attr_reader topic: String?
+    attr_reader tags: Array[Hash[String, untyped]]
+
+    def initialize: (id: String, ?message_id: String?, ?object: String, ?status: String,
+                     ?scheduled_at: String?, ?created_at: String?, ?batch_id: String?,
+                     ?subject: String?, ?recipients: String?, ?topic: String?,
+                     ?tags: Array[Hash[String, untyped]]) -> void
+    def self.from: (Hash[String, untyped]) -> ScheduledEmail
+  end
+
+  class PageSteps
+    # Declared as `def` rather than `attr_reader` only because `next` is a Ruby keyword: RBS's own
+    # core signatures spell this member `def next:` and use no keyword-named `attr_reader`
+    # anywhere. `previous` keeps the house form. Both are `Data.define` readers, and
+    # `MethodDefinitionMissing` is off in the Steepfile for exactly that reason.
+    def next: () -> String?
+    attr_reader previous: String?
+
+    def initialize: (?next: String?, ?previous: String?) -> void
+    def self.from: (Hash[String, untyped]?) -> PageSteps
+  end
+
+  class Pagination
+    attr_reader steps: PageSteps
+    attr_reader total_count: Integer
+    attr_reader current_page: Integer
+
+    def initialize: (?steps: PageSteps, ?total_count: Integer, ?current_page: Integer) -> void
+    def self.from: (Hash[String, untyped]?) -> Pagination
+  end
+
+  class ScheduledEmailPage
+    attr_reader pagination: Pagination
+    attr_reader data: Array[ScheduledEmail]
+
+    def initialize: (?pagination: Pagination, ?data: Array[ScheduledEmail]) -> void
+    def self.from: (Hash[String, untyped]) -> ScheduledEmailPage
+    def more?: () -> bool
+  end
+end

data/sig/mailkube/types.rbs

@@ -0,0 +1,44 @@
+module Mailkube
+  # Response and parameter models.
+  #
+  # Two shapes matter here, and both were arrived at by testing Steep 2.0.0 rather than guessing.
+  #
+  # In `lib/`, each model is `class X < Data.define(...)`, not `X = Data.define(...) do ... end`.
+  # Steep attributes the block form's methods to the enclosing module rather than to the constant,
+  # and then cannot resolve the generated readers from inside them.
+  #
+  # Here, each is declared as a plain `class X` and **does not name `::Data` as its superclass**.
+  # Inheriting `::Data` in the signature brings its own untyped `new` along, which shadows the
+  # keyword-argument `initialize` below, and every call site then fails with "unexpected keyword
+  # argument".
+  #
+  # The generated readers are declared as `attr_reader`; `Ruby::MethodDefinitionMissing` stays off
+  # in the Steepfile because Steep cannot see their implementations.
+  class Attachment
+    attr_reader filename: String
+    attr_reader content: String
+    attr_reader content_type: String?
+
+    def initialize: (filename: String, content: String, ?content_type: String?) -> void
+  end
+
+  class Tag
+    attr_reader name: String
+    attr_reader value: String
+
+    def initialize: (name: String, ?value: String) -> void
+  end
+
+  class Email
+    attr_reader id: String
+    attr_reader message_id: String?
+    attr_reader idempotent_replayed: bool
+    attr_reader status: String?
+    attr_reader scheduled_at: String?
+    attr_reader batch_id: String?
+
+    def initialize: (id: String, ?message_id: String?, ?idempotent_replayed: bool, ?status: String?,
+                     ?scheduled_at: String?, ?batch_id: String?) -> void
+    def scheduled?: () -> bool
+  end
+end

data/sig/mailkube/webhooks.rbs

@@ -0,0 +1,30 @@
+module Mailkube
+  module Webhooks
+    DEFAULT_TOLERANCE: Integer
+    SIGNATURE_PREFIX: String
+    PARSE_OPTIONS: Hash[Symbol, untyped]
+
+    # `headers` is any mapping that yields name/value pairs, not just a Hash:
+    # `ActionDispatch::Http::Headers` is Enumerable-only and yields CGI env names, and a Rails
+    # receiver passes it straight through from `request.headers`.
+    def self.verify_signature: (payload: String, headers: _HeaderMap, secret: String,
+                                ?tolerance: Integer) -> String
+    def self.parse_event: (String) -> Events::Event
+    def self.verify: (payload: String, headers: _HeaderMap, secret: String,
+                      ?tolerance: Integer) -> Events::Event
+    def self.check_freshness: (String, Integer) -> void
+    def self.check_signature: (String, String, String, String, String) -> void
+    def self.normalize_headers: (_HeaderMap) -> Hash[String, String]
+    def self.canonical_header: (untyped) -> String
+  end
+
+  # The narrowest thing a header mapping has to be: something that yields name/value pairs.
+  #
+  # The block takes a **pair**, matching how RBS declares `Hash#each`, so a plain Hash satisfies
+  # this. Ruby's block destructuring means `{ |name, value| ... }` reads a pair either way, which
+  # is also what lets a mapping that yields two arguments — `ActionDispatch::Http::Headers` — work
+  # at runtime.
+  interface _HeaderMap
+    def each: () { ([untyped, untyped]) -> void } -> void
+  end
+end

data/sig/mailkube.rbs

@@ -0,0 +1,36 @@
+# Signatures for the gem's public surface.
+#
+# These are checked two ways, and both are needed:
+#   `rbs validate` proves the signatures are internally coherent (every type they name exists).
+#   `steep check`  proves the implementation matches them.
+# `rbs validate` alone never loads `lib/`, so it would happily pass a `sig/` describing methods
+# that do not exist, which is the exact drift this directory is here to prevent.
+module Mailkube
+  VERSION: String
+  DEFAULT_BASE_URL: String
+
+  # What an HTTP adapter must respond to. `Client.new(http:)` accepts anything matching this.
+  interface _HttpAdapter
+    def call: (method: String, url: String, headers: Hash[String, String], ?body: String?) -> HttpResponse
+  end
+
+  # What a resource needs of its transport: the one verb it calls, and nothing else.
+  interface _SendTransport
+    def send_email: (RequestSpec) -> Email
+  end
+
+  # What a resource needs when the answer is a model rather than a send acknowledgement.
+  #
+  # As narrow as `_SendTransport`, and a separate interface rather than a widening of it, so the
+  # emails resource never acquires a dependency on a verb it does not call. It performs the request
+  # and hands back the decoded object; naming the model is the resource's job — which is also why
+  # this needs no generics, of which Ruby has none.
+  interface _JsonTransport
+    def request_json: (RequestSpec) -> Hash[String, untyped]
+  end
+
+  def self.new: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> Client
+  def self.error_class_for: (Integer) -> Class
+
+  STATUS_ERRORS: Hash[Integer, Class]
+end