mailgazelle 1.0.0

data/lib/mailgazelle/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "mailgazelle/error"
+require "mailgazelle/http/http_client"
+require "mailgazelle/http/net_http_transport"
+require "mailgazelle/version"
+require "mailgazelle/emails_resource"
+require "mailgazelle/domains_resource"
+
+module MailGazelle
+  # Entry point for the Mail Gazelle API.
+  #
+  # Construct one client per API token and reuse it.
+  class Client
+    DEFAULT_BASE_URL = "https://mailgazelle.com/api/v1"
+
+    def initialize(api_token:, base_url: nil, transport: nil, timeout: 30, connect_timeout: 10,
+                   user_agent_suffix: nil)
+      token = api_token.to_s.strip
+      raise ArgumentError, "A Mail Gazelle API token is required." if token.empty?
+
+      timeout = Float(timeout)
+      connect_timeout = Float(connect_timeout)
+      raise ArgumentError, "Timeouts must be greater than zero." if timeout <= 0 || connect_timeout <= 0
+
+      @http = Http::HttpClient.new(
+        transport: transport || Http::NetHttpTransport.new,
+        base_url: normalize_base_url(base_url),
+        default_headers: {
+          "Authorization" => "Bearer #{token}",
+          "Accept" => "application/json",
+          "User-Agent" => user_agent(user_agent_suffix)
+        },
+        timeout: timeout,
+        connect_timeout: connect_timeout
+      )
+    end
+
+    def emails
+      @emails ||= EmailsResource.new(@http)
+    end
+
+    def domains
+      @domains ||= DomainsResource.new(@http)
+    end
+
+    private
+
+    def normalize_base_url(base_url)
+      normalized = base_url.to_s.strip
+      normalized = DEFAULT_BASE_URL if normalized.empty?
+      normalized.sub(%r{/+\z}, "")
+    end
+
+    def user_agent(suffix)
+      agent = "mailgazelle-ruby/#{VERSION}"
+      extra = suffix.to_s.strip
+      extra.empty? ? agent : "#{agent} #{extra}"
+    end
+  end
+end

data/lib/mailgazelle/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  # Process-wide defaults used by {MailGazelle.client} and ActionMailer.
+  class Configuration
+    attr_accessor :api_token, :api_base, :timeout, :connect_timeout, :user_agent_suffix
+
+    def initialize
+      @api_token = nil
+      @api_base = nil
+      @timeout = 30
+      @connect_timeout = 10
+      @user_agent_suffix = nil
+    end
+  end
+end

data/lib/mailgazelle/domain.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  # A product domain and its verification statuses from +GET /domains+.
+  #
+  # Unknown JSON keys stay on {#to_h}.
+  class Domain
+    attr_reader :name, :type, :verification_statuses
+
+    def self.from_h(payload)
+      data = string_keyed(payload)
+      raw_name = data["name"] || data["domain"] || data["host"] || ""
+      raw_type = data["type"] || data["kind"]
+
+      new(
+        name: raw_name.is_a?(String) ? raw_name : "",
+        type: raw_type.is_a?(String) && !raw_type.empty? ? raw_type : nil,
+        verification_statuses: statuses(data).freeze,
+        raw: data
+      )
+    end
+
+    def initialize(name:, type:, verification_statuses:, raw:)
+      @name = name
+      @type = type
+      @verification_statuses = verification_statuses
+      @raw = raw
+      freeze
+    end
+
+    def to_h
+      @raw
+    end
+
+    def self.string_keyed(payload)
+      return {} unless payload.is_a?(Hash)
+
+      payload.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value
+      end
+    end
+    private_class_method :string_keyed
+
+    def self.statuses(data)
+      candidates = data["verification"] || data["verification_statuses"] || data["statuses"]
+      return direct_statuses(data) unless candidates.is_a?(Hash)
+
+      candidates.each_with_object({}) do |(key, value), result|
+        if value.is_a?(String)
+          result[key.to_s] = value
+        elsif value.is_a?(Hash) && value["status"].is_a?(String)
+          name = value["name"].is_a?(String) ? value["name"] : key.to_s
+          result[name] = value["status"]
+        end
+      end
+    end
+    private_class_method :statuses
+
+    def self.direct_statuses(data)
+      %w[dkim mail_from spf dmarc].each_with_object({}) do |key, result|
+        result[key] = data[key] if data[key].is_a?(String)
+      end
+    end
+    private_class_method :direct_statuses
+  end
+end

data/lib/mailgazelle/domains_resource.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "mailgazelle/domain"
+
+module MailGazelle
+  # List the product domains associated with the current API token.
+  class DomainsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list
+      items(@http.request("GET", "/domains")).filter_map do |item|
+        Domain.from_h(item) if item.is_a?(Hash)
+      end
+    end
+
+    private
+
+    def items(payload)
+      return payload if payload.is_a?(Array)
+      return [] unless payload.is_a?(Hash)
+
+      %w[data domains].each do |key|
+        value = payload[key] || payload[key.to_sym]
+        return Array(value) if value.is_a?(Array)
+      end
+
+      [payload]
+    end
+  end
+end

data/lib/mailgazelle/email.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "mailgazelle/address"
+require "mailgazelle/attachment"
+require "mailgazelle/error"
+
+module MailGazelle
+  # Immutable builder for a +POST /emails+ payload.
+  #
+  # Either HTML or plain text is required. Optional fields are omitted from the
+  # JSON body so Mail Gazelle can apply product defaults.
+  class Email
+    MAX_HTML_BYTES = 512 * 1024
+    MAX_ATTACHMENT_BYTES = 7 * 1024 * 1024
+    MAX_RECIPIENTS = 50
+    MAX_TAGS = 48
+    MAX_TAG_NAME_LENGTH = 64
+    MAX_TAG_VALUE_LENGTH = 256
+    MAX_HEADERS = 50
+    MAX_HEADER_VALUE_LENGTH = 8192
+    RESERVED_TAGS = %w[team_id product_id].freeze
+    TAG_PATTERN = /\A[A-Za-z0-9_-]+\z/
+    HEADER_NAME_PATTERN = /\A[A-Za-z0-9-]+\z/
+
+    def self.to(email, name = nil)
+      new(to: [Address.new(email, name)])
+    end
+
+    def add_to(email, name = nil)
+      append_recipient(:to, Address.new(email, name))
+    end
+
+    def cc(email, name = nil)
+      append_recipient(:cc, Address.new(email, name))
+    end
+
+    def bcc(email, name = nil)
+      append_recipient(:bcc, Address.new(email, name))
+    end
+
+    def subject(value)
+      copy(subject: value)
+    end
+
+    def text(value)
+      copy(text: value)
+    end
+
+    def html(value)
+      copy(html: value)
+    end
+
+    def from(email, name = nil)
+      copy(from: Address.new(email, name))
+    end
+
+    def reply_to(email, name = nil)
+      addresses = @reply_to.dup
+      addresses << Address.new(email, name)
+      copy(reply_to: addresses.freeze, omit_reply_to: false)
+    end
+
+    def without_reply_to
+      copy(reply_to: [].freeze, omit_reply_to: true)
+    end
+
+    def header(name, value)
+      self.class.assert_header(name, value)
+      headers = @headers.dup
+      if !headers.key?(name) && headers.size >= MAX_HEADERS
+        raise ValidationError.new(
+          "A message can include at most #{MAX_HEADERS} headers.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      headers[name] = value
+      copy(headers: headers.freeze)
+    end
+
+    def headers(values)
+      updated = copy(headers: {}.freeze)
+      values.each { |name, value| updated = updated.header(name.to_s, value.to_s) }
+      updated
+    end
+
+    def tag(key, value)
+      self.class.assert_tag_part(key, MAX_TAG_NAME_LENGTH)
+      self.class.assert_tag_part(value, MAX_TAG_VALUE_LENGTH)
+      if RESERVED_TAGS.include?(key)
+        raise ValidationError.new(
+          "The tag names team_id and product_id are reserved.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      tags = @tags.dup
+      if !tags.key?(key) && tags.size >= MAX_TAGS
+        raise ValidationError.new(
+          "A message can include at most #{MAX_TAGS} tags.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      tags[key] = value
+      copy(tags: tags.freeze)
+    end
+
+    def tags(values)
+      updated = copy(tags: {}.freeze)
+      values.each { |key, value| updated = updated.tag(key.to_s, value.to_s) }
+      updated
+    end
+
+    def idempotency_key(key)
+      copy(idempotency_key: key)
+    end
+
+    def attach(attachment)
+      raise ArgumentError, "Expected a MailGazelle::Attachment" unless attachment.is_a?(Attachment)
+
+      if attachment.content_id
+        @attachments.each do |existing|
+          next unless existing.content_id == attachment.content_id
+
+          raise AttachmentError.new(
+            "Attachment content ids must be unique.",
+            code: "attachment_invalid",
+            http_status: 422
+          )
+        end
+      end
+
+      attachments = @attachments.dup
+      attachments << attachment
+      copy(attachments: attachments.freeze)
+    end
+
+    # Validate documented limits and return the JSON body for +POST /emails+.
+    def to_payload
+      assert_ready
+
+      payload = {
+        to: @to.map(&:to_h),
+        subject: @subject
+      }
+      payload[:html] = @html unless @html.nil?
+      payload[:text] = @text unless @text.nil?
+      payload[:from] = @from.to_h unless @from.nil?
+      payload[:cc] = @cc.map(&:to_h) unless @cc.empty?
+      payload[:bcc] = @bcc.map(&:to_h) unless @bcc.empty?
+
+      if @omit_reply_to
+        payload[:reply_to] = []
+      elsif !@reply_to.empty?
+        payload[:reply_to] = @reply_to.map(&:to_h)
+      end
+
+      payload[:headers] = @headers unless @headers.empty?
+      payload[:tags] = @tags unless @tags.empty?
+      payload[:idempotency_key] = @idempotency_key if @idempotency_key.is_a?(String) && !@idempotency_key.empty?
+      payload[:attachments] = @attachments.map(&:to_h) unless @attachments.empty?
+      payload
+    end
+
+    def self.assert_header(name, value)
+      unless HEADER_NAME_PATTERN.match?(name)
+        raise ValidationError.new(
+          "Header names must contain only letters, numbers, and hyphens.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      if value.match?(/[\r\n]/)
+        raise ValidationError.new(
+          "Header values cannot contain line breaks.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      return if value.length <= MAX_HEADER_VALUE_LENGTH
+
+      raise ValidationError.new(
+        "Header values must be at most #{MAX_HEADER_VALUE_LENGTH} characters.",
+        code: "validation_error",
+        http_status: 422
+      )
+    end
+
+    def self.assert_tag_part(value, max_length)
+      return if TAG_PATTERN.match?(value) && value.length <= max_length
+
+      raise ValidationError.new(
+        "Tag names and values may only contain letters, numbers, underscores, and hyphens.",
+        code: "validation_error",
+        http_status: 422
+      )
+    end
+
+    def initialize(to:, subject: nil, text: nil, html: nil, from: nil, cc: [].freeze, bcc: [].freeze,
+                   reply_to: [].freeze, omit_reply_to: false, headers: {}.freeze, tags: {}.freeze,
+                   idempotency_key: nil, attachments: [].freeze)
+      @to = to.freeze
+      @subject = subject
+      @text = text
+      @html = html
+      @from = from
+      @cc = cc.freeze
+      @bcc = bcc.freeze
+      @reply_to = reply_to.freeze
+      @omit_reply_to = omit_reply_to
+      @headers = headers.freeze
+      @tags = tags.freeze
+      @idempotency_key = idempotency_key
+      @attachments = attachments.freeze
+      freeze
+    end
+
+    private
+
+    def copy(**changes)
+      self.class.new(
+        to: changes.fetch(:to, @to),
+        subject: changes.fetch(:subject, @subject),
+        text: changes.fetch(:text, @text),
+        html: changes.fetch(:html, @html),
+        from: changes.fetch(:from, @from),
+        cc: changes.fetch(:cc, @cc),
+        bcc: changes.fetch(:bcc, @bcc),
+        reply_to: changes.fetch(:reply_to, @reply_to),
+        omit_reply_to: changes.fetch(:omit_reply_to, @omit_reply_to),
+        headers: changes.fetch(:headers, @headers),
+        tags: changes.fetch(:tags, @tags),
+        idempotency_key: changes.fetch(:idempotency_key, @idempotency_key),
+        attachments: changes.fetch(:attachments, @attachments)
+      )
+    end
+
+    def append_recipient(field, address)
+      if @to.size + @cc.size + @bcc.size >= MAX_RECIPIENTS
+        raise ValidationError.new(
+          "A message can include at most #{MAX_RECIPIENTS} recipients.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      list = instance_variable_get(:"@#{field}").dup
+      list << address
+      copy(field => list.freeze)
+    end
+
+    def assert_ready
+      if @subject.nil? || @subject.strip.empty?
+        raise ValidationError.new("A subject is required.", code: "validation_error", http_status: 422)
+      end
+
+      has_html = !@html.nil? && !@html.empty?
+      has_text = !@text.nil? && !@text.empty?
+      unless has_html || has_text
+        raise ValidationError.new(
+          "Either html or text is required.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      if has_html && @html.bytesize > MAX_HTML_BYTES
+        raise HtmlTooLargeError.new(
+          "HTML must be at most #{MAX_HTML_BYTES} bytes.",
+          code: "html_too_large",
+          http_status: 422
+        )
+      end
+
+      total = @attachments.sum(&:decoded_size)
+      return if total <= MAX_ATTACHMENT_BYTES
+
+      raise AttachmentTooLargeError.new(
+        "Decoded attachments must total at most #{MAX_ATTACHMENT_BYTES} bytes.",
+        code: "attachment_too_large",
+        http_status: 422
+      )
+    end
+  end
+end

data/lib/mailgazelle/emails/attachment_meta.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  # Attachment metadata returned by +GET /emails/{id}+.
+  #
+  # File bytes are never included.
+  class AttachmentMeta
+    attr_reader :filename, :content_type, :size
+
+    def self.from_h(payload)
+      data = string_keyed(payload)
+      new(
+        filename: data["filename"].is_a?(String) ? data["filename"] : "",
+        content_type: data["content_type"].is_a?(String) ? data["content_type"] : nil,
+        size: integer_or_nil(data["size"]),
+        raw: data
+      )
+    end
+
+    def initialize(filename:, content_type:, size:, raw:)
+      @filename = filename
+      @content_type = content_type
+      @size = size
+      @raw = raw
+      freeze
+    end
+
+    def to_h
+      @raw
+    end
+
+    def self.string_keyed(payload)
+      return {} unless payload.is_a?(Hash)
+
+      payload.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value
+      end
+    end
+    private_class_method :string_keyed
+
+    def self.integer_or_nil(value)
+      return value if value.is_a?(Integer)
+      return Integer(value) if value.is_a?(String) && value.match?(/\A-?\d+\z/)
+      return value.to_i if value.is_a?(Numeric)
+
+      nil
+    end
+    private_class_method :integer_or_nil
+  end
+end

data/lib/mailgazelle/emails/email_record.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "time"
+require "mailgazelle/emails/attachment_meta"
+require "mailgazelle/emails/email_status"
+
+module MailGazelle
+  # Status record returned by +GET /emails/{id}+.
+  #
+  # HTML, text, and attachment bytes are not included. Unknown JSON keys stay
+  # on {#to_h} so later API fields do not break older clients.
+  class EmailRecord
+    attr_reader :id, :status, :message_id, :last_event_type, :created_at, :updated_at, :sent_at, :attachments
+
+    def self.from_h(payload)
+      data = unwrap(payload)
+      attachments = Array(data["attachments"]).filter_map do |item|
+        AttachmentMeta.from_h(item) if item.is_a?(Hash)
+      end
+
+      new(
+        id: string_value(data, "id") || "",
+        status: string_value(data, "status") || "",
+        message_id: string_value(data, "message_id") ||
+          string_value(data, "provider_message_id") ||
+          string_value(data, "ses_message_id"),
+        last_event_type: string_value(data, "last_event_type") || string_value(data, "last_event"),
+        created_at: timestamp(data, "created_at"),
+        updated_at: timestamp(data, "updated_at"),
+        sent_at: timestamp(data, "sent_at"),
+        attachments: attachments.freeze,
+        raw: data
+      )
+    end
+
+    def initialize(id:, status:, message_id:, last_event_type:, created_at:, updated_at:, sent_at:, attachments:, raw:)
+      @id = id
+      @status = status
+      @message_id = message_id
+      @last_event_type = last_event_type
+      @created_at = created_at
+      @updated_at = updated_at
+      @sent_at = sent_at
+      @attachments = attachments
+      @raw = raw
+      freeze
+    end
+
+    # The documented status when this SDK version knows it, otherwise +nil+.
+    def known_status
+      EmailStatus.known?(status) ? status : nil
+    end
+
+    def to_h
+      @raw
+    end
+
+    def self.unwrap(payload)
+      data = string_keyed(payload)
+      nested = data["data"]
+      data = string_keyed(nested) if nested.is_a?(Hash)
+      data
+    end
+    private_class_method :unwrap
+
+    def self.string_keyed(payload)
+      return {} unless payload.is_a?(Hash)
+
+      payload.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value
+      end
+    end
+    private_class_method :string_keyed
+
+    def self.string_value(data, key)
+      value = data[key]
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+    private_class_method :string_value
+
+    def self.timestamp(data, key)
+      value = data[key]
+      return nil unless value.is_a?(String) && !value.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :timestamp
+  end
+end

data/lib/mailgazelle/emails/email_status.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  # Message statuses documented by the send path.
+  #
+  # Additional statuses may appear on {EmailRecord#status} as raw strings when
+  # the API adds new values.
+  module EmailStatus
+    QUEUED = "queued"
+    REJECTED = "rejected"
+    KNOWN = [QUEUED, REJECTED].freeze
+
+    module_function
+
+    def known?(value)
+      KNOWN.include?(value)
+    end
+  end
+end

data/lib/mailgazelle/emails/queued_email.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mailgazelle/emails/email_status"
+
+module MailGazelle
+  # Immediate 202 result of +POST /emails+.
+  #
+  # The message is persisted and queued. Delivery happens asynchronously.
+  class QueuedEmail
+    attr_reader :id, :status
+
+    def self.from_h(payload)
+      data = string_keyed(payload)
+      new(
+        id: data["id"].is_a?(String) ? data["id"] : "",
+        status: data["status"].is_a?(String) ? data["status"] : EmailStatus::QUEUED,
+        raw: data
+      )
+    end
+
+    def initialize(id:, status:, raw:)
+      @id = id
+      @status = status
+      @raw = raw
+      freeze
+    end
+
+    def to_h
+      @raw
+    end
+
+    def self.string_keyed(payload)
+      return {} unless payload.is_a?(Hash)
+
+      payload.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value
+      end
+    end
+    private_class_method :string_keyed
+  end
+end

data/lib/mailgazelle/emails_resource.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+require "mailgazelle/email"
+require "mailgazelle/emails/email_record"
+require "mailgazelle/emails/queued_email"
+require "mailgazelle/error"
+
+module MailGazelle
+  # Send and inspect transactional emails.
+  class EmailsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # Persist a message and queue a send. Returns immediately on HTTP 202.
+    #
+    # The same idempotency key returns the original message and does not send again.
+    def send(email)
+      raise ArgumentError, "Expected a MailGazelle::Email" unless email.is_a?(Email)
+
+      QueuedEmail.from_h(@http.request("POST", "/emails", json: email.to_payload))
+    end
+
+    # Fetch status, timestamps, provider message id, last event, and attachment metadata.
+    def get(id)
+      trimmed = id.to_s.strip
+      if trimmed.empty?
+        raise ValidationError.new("An email id is required.", code: "validation_error", http_status: 422)
+      end
+
+      EmailRecord.from_h(@http.request("GET", "/emails/#{URI.encode_uri_component(trimmed)}"))
+    end
+  end
+end