thousandmails 1.0.0

data/lib/thousandmails/utils/attachments.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "securerandom"
+
+module ThousandMails
+  # Turns whatever a caller hands us into the multipart body the attachment
+  # endpoints expect, applying the same ceilings the server does
+  # (src/backend/client/middleware/Attachment.js) so an oversized or unsupported
+  # file fails here rather than after the upload.
+  #
+  # Accepted forms:
+  #
+  #   "/path/to/invoice.pdf"                              a path on disk
+  #   { path: "/tmp/x.pdf", filename: "invoice.pdf" }     a path with a chosen name
+  #   { filename: "report.csv", content: "a,b\n1,2" }     bytes or text in memory
+  #   { filename: "x.png", content: "<base64>", encoding: "base64" }
+  module Attachments
+    # One attachment, read and checked.
+    ResolvedFile = Struct.new(:filename, :content, :content_type)
+
+    module_function
+
+    # The server refuses control characters and path separators outright, because
+    # the name is echoed into a Content-Disposition header.
+    def assert_safe_filename(filename, label)
+      if filename.nil? || filename.strip.empty?
+        raise InvalidInputError.new("Each attachment must have a filename", { field: label })
+      end
+
+      if filename.length > Constants::MAX_FILENAME_LENGTH
+        raise InvalidInputError.new(
+          "Attachment filenames may be at most #{Constants::MAX_FILENAME_LENGTH} characters",
+          { field: label, filename: filename }
+        )
+      end
+
+      filename.each_char do |char|
+        code = char.ord
+        next unless code < 0x20 || code == 0x7F || code == 0x2F || code == 0x5C
+
+        raise InvalidInputError.new(
+          "\"#{filename}\" is not a valid file name: no path separators or control characters",
+          { field: label, filename: filename }
+        )
+      end
+    end
+
+    def extension_of(filename)
+      dot = filename.rindex(".")
+      dot && dot.positive? ? filename[(dot + 1)..].downcase : ""
+    end
+
+    # Read and check one attachment.
+    def resolve_one(entry, label)
+      filename, content = read_entry(entry, label)
+
+      assert_safe_filename(filename, label)
+
+      extension = extension_of(filename)
+      content_type = Constants::ATTACHMENT_TYPES[extension]
+      if content_type.nil?
+        raise InvalidInputError.new(
+          "\"#{filename}\" has an unsupported file type. " \
+          "Allowed: #{Constants::ALLOWED_EXTENSIONS.join(', ')}",
+          { field: label, allowed: Constants::ALLOWED_EXTENSIONS, filename: filename }
+        )
+      end
+
+      size = content.bytesize
+      if size.zero?
+        raise InvalidInputError.new("\"#{filename}\" is empty", { field: label, filename: filename })
+      end
+
+      if size > Constants::MAX_FILE_BYTES
+        raise InvalidInputError.new(
+          "\"#{filename}\" is #{size} bytes; the per-file limit is #{Constants::MAX_FILE_BYTES}",
+          { field: label, filename: filename, size: size, max: Constants::MAX_FILE_BYTES }
+        )
+      end
+
+      ResolvedFile.new(filename, content, content_type)
+    end
+
+    # Resolve one message's attachments, enforcing the per-message count, the
+    # per-request byte ceiling and the duplicate-name rule the server applies.
+    def resolve_group(attachments, label = "attachments")
+      entries = attachments.is_a?(Array) ? attachments : [attachments]
+
+      if entries.empty? || (entries.length == 1 && blank?(entries.first))
+        raise InvalidInputError.new(
+          "#{label} is required — the attachment endpoints need at least one file " \
+          "(use send_mail for a message without files)",
+          { field: label }
+        )
+      end
+
+      if entries.length > Constants::MAX_ATTACHMENTS_PER_MESSAGE
+        raise InvalidInputError.new(
+          "A message may carry at most #{Constants::MAX_ATTACHMENTS_PER_MESSAGE} attachments",
+          { field: label, received: entries.length }
+        )
+      end
+
+      resolved = []
+      seen = {}
+      total = 0
+
+      entries.each do |entry|
+        file = resolve_one(entry, label)
+
+        key = file.filename.downcase
+        if seen.key?(key)
+          raise InvalidInputError.new(
+            "Duplicate attachment filename \"#{file.filename}\"",
+            { field: label, filename: file.filename }
+          )
+        end
+        seen[key] = true
+
+        total += file.content.bytesize
+        if total > Constants::MAX_REQUEST_BYTES
+          raise InvalidInputError.new(
+            "Attachments exceed the #{Constants::MAX_REQUEST_BYTES} byte per-request limit",
+            { field: label, size: total, max: Constants::MAX_REQUEST_BYTES }
+          )
+        end
+
+        resolved << file
+      end
+
+      resolved
+    end
+
+    # Body for POST /client/sendmail/attachment.
+    # @return [Array] `[[body, content_type], files]`
+    def single_form(message, attachments)
+      files = resolve_group(attachments)
+
+      parts = message.filter_map { |name, value| field(name.to_s, value) }
+      files.each { |file| parts << ["attachments", file] }
+
+      [encode(parts), files]
+    end
+
+    # Body for POST /client/send/attachment/batch. Files bind to their message by
+    # index through the field name `attachments[<index>]`, and every message in
+    # the batch must carry at least one.
+    # @return [Array] `[[body, content_type], groups]`
+    def batch_form(messages, attachments_by_index)
+      groups = []
+      total_files = 0
+
+      messages.each_index do |index|
+        files = resolve_group(attachments_by_index[index], "attachments[#{index}]")
+        total_files += files.length
+        groups << files
+      end
+
+      if total_files > Constants::MAX_FILES_PER_BATCH_REQUEST
+        raise InvalidInputError.new(
+          "A multipart batch may carry at most #{Constants::MAX_FILES_PER_BATCH_REQUEST} files in total",
+          { received: total_files, max: Constants::MAX_FILES_PER_BATCH_REQUEST }
+        )
+      end
+
+      parts = [["messages", JSON.generate(messages)]]
+      groups.each_with_index do |files, index|
+        files.each { |file| parts << ["attachments[#{index}]", file] }
+      end
+
+      [encode(parts), groups]
+    end
+
+    # Encode parts as multipart/form-data.
+    #
+    # Built by hand rather than through a MIME library so in-memory content needs
+    # no temp file, and so the test suite can read back exactly what would have
+    # gone over the wire.
+    #
+    # Each part is `[name, value]` where value is either a String (a plain field)
+    # or a ResolvedFile (a file part).
+    #
+    # @return [Array] `[body, content_type]`
+    def encode(parts)
+      boundary = "----ThousandMailsFormBoundary#{SecureRandom.hex(16)}"
+
+      # Built in binary throughout. File content read off disk is ASCII-8BIT and
+      # a filename or field value may be UTF-8; appending one to the other in a
+      # single-encoding buffer raises Encoding::CompatibilityError, so every
+      # piece is converted before it goes in.
+      body = +"".b
+
+      parts.each do |name, value|
+        body << "--#{boundary}\r\n".b
+
+        if value.is_a?(ResolvedFile)
+          body << "Content-Disposition: form-data; name=\"#{name}\"; " \
+                  "filename=\"#{escape_header_value(value.filename)}\"\r\n".b
+          body << "Content-Type: #{value.content_type}\r\n\r\n".b
+          body << value.content.b
+        else
+          body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n".b
+          body << value.to_s.b
+        end
+
+        body << "\r\n".b
+      end
+
+      body << "--#{boundary}--\r\n".b
+
+      [body, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    # Multipart carries every non-file part as a string, so structured values are
+    # JSON-encoded exactly the way the server's coerceMessage expects them.
+    def field(name, value)
+      return nil if value.nil? || value == "" || value == []
+      return [name, value ? "true" : "false"] if value == true || value == false
+      return [name, JSON.generate(value)] if value.is_a?(Hash) || value.is_a?(Array)
+
+      [name, value.to_s]
+    end
+
+    def read_entry(entry, label)
+      case entry
+      when String
+        [File.basename(entry), read_file(entry, label)]
+      when Hash
+        record = entry.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+
+        if record["path"] && !record["path"].to_s.empty?
+          path = record["path"].to_s
+          filename = blank?(record["filename"]) ? File.basename(path) : record["filename"].to_s
+          [filename, read_file(path, label)]
+        else
+          filename = record["filename"].to_s
+          content = to_bytes(record["content"], record["encoding"])
+          if content.nil?
+            shown = filename.empty? ? "(unnamed)" : filename
+            raise InvalidInputError.new(
+              "Attachment \"#{shown}\" needs `content` (a String of bytes) or `path`",
+              { field: label }
+            )
+          end
+          [filename, content]
+        end
+      else
+        raise InvalidInputError.new(
+          "An attachment must be a file path or a hash with { filename:, content: }",
+          { field: label }
+        )
+      end
+    end
+
+    def to_bytes(content, encoding)
+      return nil unless content.is_a?(String)
+
+      if encoding.to_s == "base64"
+        begin
+          return content.unpack1("m0")
+        rescue ArgumentError
+          return nil
+        end
+      end
+
+      content
+    end
+
+    def read_file(target, label)
+      File.binread(target)
+    rescue SystemCallError, IOError => e
+      raise InvalidInputError.new(
+        "Could not read attachment \"#{target}\": #{e.message}",
+        { field: label },
+        cause: e
+      )
+    end
+
+    # assert_safe_filename has already refused control characters and separators,
+    # so a quote is the only thing left that could break out of the header.
+    def escape_header_value(value)
+      value.gsub('"', "%22")
+    end
+
+    def blank?(value)
+      value.nil? || value == "" || value == [] || value == {}
+    end
+  end
+end

data/lib/thousandmails/utils/constants.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ThousandMails
+  # Values mirrored from the server so the SDK can reject a bad request locally
+  # instead of spending a round trip on it.
+  #
+  # Every constant here has a counterpart in src/backend/client. When the server
+  # changes a limit, change it here too — the pairs are called out per entry.
+  module Constants
+    # Every client endpoint hangs off this prefix (backend/client/routes/sendmail.routes.js).
+    CLIENT_PREFIX = "/client"
+
+    # Milliseconds, not seconds, so the Node, PHP, Python and Ruby SDKs
+    # configure identically.
+    DEFAULT_TIMEOUT_MS = 30_000
+    DEFAULT_MAX_RETRIES = 2
+
+    # The host used when nothing overrides it.
+    FALLBACK_BASE_URL = "https://beta.thousandmails.com/mailerapi"
+
+    # --- send limits ---------------------------------------------------------
+
+    # Sendpipeline.MAX_BATCH
+    MAX_BATCH = 100
+    # middleware/Attachment.MAX_ATTACHMENT_BATCH
+    MAX_ATTACHMENT_BATCH = 20
+    # middleware/Attachment.MAX_ATTACHMENTS_PER_MESSAGE
+    MAX_ATTACHMENTS_PER_MESSAGE = 5
+    # middleware/Attachment.MAX_FILE_BYTES
+    MAX_FILE_BYTES = 5 * 1024 * 1024
+    # middleware/Attachment.MAX_REQUEST_BYTES
+    MAX_REQUEST_BYTES = 20 * 1024 * 1024
+    # middleware/Attachment.MAX_FILES_PER_BATCH_REQUEST
+    MAX_FILES_PER_BATCH_REQUEST = 20
+    # middleware/Attachment.MAX_FILENAME_LENGTH
+    MAX_FILENAME_LENGTH = 200
+
+    # middleware/Attachment.ALLOWED_TYPES — extension => Content-Type. The server
+    # re-derives the type from the extension and sniffs the bytes, so the type we
+    # put on the multipart part is a courtesy, not a claim it trusts.
+    ATTACHMENT_TYPES = {
+      "csv" => "text/csv",
+      "xls" => "application/vnd.ms-excel",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "doc" => "application/msword",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "pdf" => "application/pdf",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "png" => "image/png"
+    }.freeze
+
+    ALLOWED_EXTENSIONS = ATTACHMENT_TYPES.keys.freeze
+
+    # --- analytics -----------------------------------------------------------
+
+    # client/utils/Analytics.METRIC_FIELDS
+    METRIC_FIELDS = %w[
+      sent delivered deferred bounced opened clicked spam unsubscribed failed
+    ].freeze
+
+    # client/utils/Analytics.METRIC_BY_TYPE keys — the `type` on a log event.
+    EVENT_TYPES = %w[
+      queued delivered deferred bounced opened clicked spam unsubscribed failed
+    ].freeze
+
+    INTERVALS = %w[day week month].freeze
+
+    # Query-param ceilings enforced by the controllers. The server clamps rather
+    # than rejects, so these are used for documentation and local clamping only.
+    LIMITS = {
+      "realtimeMinutes" => { min: 1, max: 120, default: 60 },
+      "realtimeSeconds" => { min: 1, max: 600, default: 120 },
+      "activityLimit" => { min: 1, max: 100, default: 20 },
+      "logPageSize" => { min: 1, max: 200, default: 50 }
+    }.freeze
+
+    # The row ceiling on GET /client/logs/export.
+    LOG_EXPORT_ROWS = 5000
+
+    # Sendpipeline.EMAIL_PATTERN, character for character. \A and \z rather than
+    # ^ and $, because Ruby's anchors match at a line break and JavaScript's do
+    # not — the server would refuse "a@b.com\n", so this has to as well.
+    EMAIL_PATTERN = /\A[^\s@]+@(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+\z/i
+
+    # Sendpipeline.PLACEHOLDER_PATTERN.
+    PLACEHOLDER_PATTERN = /\{\{\s*([\w.-]+)\s*\}\}/
+
+    # Where the API lives. Callers configure nothing but their API key, so this
+    # has to be the real host — override it only to point at a different
+    # deployment, with `ThousandMails::Client.new(base_url:)` or THOUSANDMAILS_BASE_URL.
+    #
+    # Read on each call rather than captured at load, so setting the variable
+    # after the gem has been required still takes effect.
+    def self.default_base_url
+      from_env = ENV["THOUSANDMAILS_BASE_URL"]
+      from_env.nil? || from_env.empty? ? FALLBACK_BASE_URL : from_env
+    end
+  end
+end

data/lib/thousandmails/utils/errors.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ThousandMails
+  # Every failure the SDK raises is a ThousandMails::Error, so a caller can rescue
+  # one type and branch on the specific subclass.
+  #
+  # The API answers with two body shapes — `{ "message": ... }` for validation
+  # and lookup failures, `{ "error": ... }` for authentication and rate limiting
+  # — so the message is pulled from whichever is present rather than assuming one.
+  class Error < StandardError
+    # The underlying failure, when this one wraps something lower down.
+    attr_reader :cause_error
+
+    def initialize(message, cause: nil)
+      super(message)
+      @cause_error = cause
+    end
+  end
+
+  # Bad or missing SDK configuration (no API key, unusable base_url).
+  class ConfigError < Error; end
+
+  # A request rejected locally, before any bytes went out — a missing sender, an
+  # oversized attachment, a batch over the limit. Mirrors the server's own checks
+  # so the failure arrives in microseconds instead of after a round trip.
+  class InvalidInputError < Error
+    # Everything the failure carried, including the keys promoted below.
+    attr_reader :details
+    # The offending field, when one field is to blame.
+    attr_reader :field
+    # Placeholders the body referenced, and those left without a value.
+    attr_reader :required_fields, :missing_fields
+    # Position in the batch, set when a batch entry is at fault.
+    attr_reader :index
+
+    def initialize(message, details = {}, cause: nil)
+      super(message, cause: cause)
+      @details = details || {}
+      @field = @details[:field] || @details["field"]
+      @required_fields = @details[:requiredFields] || @details["requiredFields"]
+      @missing_fields = @details[:missingFields] || @details["missingFields"]
+      @index = @details[:index] || @details["index"]
+    end
+
+    # Any other detail the failure carried (`value`, `filename`, `max`, …).
+    def detail(key)
+      @details[key] || @details[key.to_s] || @details[key.to_sym]
+    end
+
+    # Re-label the message and record the batch position. Used by
+    # Validate.batch so a rejected entry says which one it was.
+    def with_index(index)
+      self.class.new(
+        "messages[#{index}]: #{message}",
+        @details.merge(index: index),
+        cause: @cause_error
+      )
+    end
+  end
+
+  # The request never completed: DNS, TCP, TLS, or a dropped socket.
+  class ConnectionError < Error; end
+
+  # The request exceeded the configured timeout and was aborted.
+  class TimeoutError < ConnectionError; end
+
+  # The caller stopped the work in progress — closing a live event stream.
+  class AbortError < Error; end
+
+  # The API answered with a non-2xx status.
+  class APIError < Error
+    attr_reader :status, :body, :headers, :http_method, :url
+
+    def initialize(message, status: 0, body: nil, headers: {}, http_method: "", url: "")
+      super(message)
+      @status = status
+      @body = body
+      @headers = headers || {}
+      @http_method = http_method
+      @url = url
+    end
+  end
+
+  # 401 — header missing, malformed, or the key is unknown.
+  class AuthenticationError < APIError; end
+
+  # 403 — the key is inactive, its owner is gone, the sender is pinned to a
+  # different IP, or every recipient is suppressed. When suppression is the
+  # cause the response carries the offending addresses, exposed as `suppressed`.
+  class PermissionError < APIError
+    attr_reader :suppressed
+
+    def initialize(message, **options)
+      super
+      @suppressed = body["suppressed"] if body.is_a?(Hash) && body["suppressed"].is_a?(Array)
+    end
+  end
+
+  # 400 — a reference that does not resolve: unknown template, unknown sender,
+  # unknown message or event id. The API uses 400 rather than 404 for these.
+  class BadRequestError < APIError; end
+
+  # 404 — no such route.
+  class NotFoundError < APIError; end
+
+  # 422 — the request was understood and rejected. Placeholder failures carry
+  # `required_fields`/`missing_fields`; attachment failures carry `field`.
+  class ValidationError < APIError
+    attr_reader :required_fields, :missing_fields, :field, :allowed
+
+    def initialize(message, **options)
+      super
+      payload = body.is_a?(Hash) ? body : {}
+      @required_fields = payload["requiredFields"]
+      @missing_fields = payload["missingFields"]
+      @field = payload["field"]
+      @allowed = payload["allowed"]
+    end
+  end
+
+  # 413 — an attachment or form field exceeded the size ceiling.
+  class PayloadTooLargeError < APIError; end
+
+  # 415 — an attachment endpoint was called without multipart/form-data.
+  class UnsupportedMediaTypeError < APIError; end
+
+  # 429 — the per-key limiter tripped. `retry_after` is in seconds.
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message, **options)
+      super
+      @retry_after = Errors.parse_retry_after(headers)
+    end
+  end
+
+  # 5xx — the API or the transport behind it failed.
+  class ServerError < APIError; end
+
+  # 503 — too many attachment uploads are already in flight. The request was
+  # refused before any bytes were buffered, so retrying it is always safe.
+  class ServiceUnavailableError < ServerError; end
+
+  # Builds the right APIError subclass for a response.
+  module Errors
+    BY_STATUS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionError,
+      404 => NotFoundError,
+      413 => PayloadTooLargeError,
+      415 => UnsupportedMediaTypeError,
+      422 => ValidationError,
+      429 => RateLimitError,
+      503 => ServiceUnavailableError
+    }.freeze
+
+    def self.from_response(status, body, headers, http_method, url)
+      klass = BY_STATUS[status] || (status >= 500 ? ServerError : APIError)
+      klass.new(
+        message_of(body, status),
+        status: status,
+        body: body,
+        headers: headers,
+        http_method: http_method,
+        url: url
+      )
+    end
+
+    def self.message_of(body, status)
+      return body.strip[0, 500] if body.is_a?(String) && !body.strip.empty?
+
+      if body.is_a?(Hash)
+        return body["message"] if body["message"].is_a?(String)
+        return body["error"] if body["error"].is_a?(String)
+      end
+
+      "ThousandMails API request failed with status #{status}"
+    end
+
+    # Retry-After is either a delay in seconds or an HTTP date; normalise to seconds.
+    def self.parse_retry_after(headers)
+      raw = headers["retry-after"] if headers.respond_to?(:[])
+      return nil if raw.nil? || raw.to_s.empty?
+
+      return Float(raw) if raw.to_s.match?(/\A\s*-?\d+(\.\d+)?\s*\z/)
+
+      begin
+        [0.0, Time.httpdate(raw.to_s).to_f - Time.now.to_f].max
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end