thousandmails 1.0.0

data/lib/thousandmails/utils/transport.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module ThousandMails
+  # The HTTP layer under ThousandMails::Http.
+  #
+  # Split out so the retry policy, the URL building and the error mapping can be
+  # tested — and swapped — independently of how bytes actually reach the network.
+  # Pass your own implementation as `ThousandMails::Client.new(transport:)` to route
+  # requests through an existing connection pool, a proxy, or a test double.
+  #
+  # The bundled NetHttpTransport uses nothing but the standard library, so the
+  # gem installs with no dependencies at all.
+  module Transports
+    # One outbound HTTP call, fully materialised.
+    class Request
+      attr_reader :http_method, :url, :headers, :body, :timeout_ms
+
+      def initialize(http_method, url, headers, body = nil, timeout_ms = 0)
+        @http_method = http_method
+        @url = url
+        @headers = headers
+        @body = body
+        # Milliseconds. 0 disables the timeout, which is what the SSE endpoint needs.
+        @timeout_ms = timeout_ms
+      end
+
+      def timeout_seconds
+        timeout_ms.positive? ? timeout_ms / 1000.0 : nil
+      end
+    end
+
+    # A completed response, body already read.
+    class Response
+      attr_reader :status, :headers, :body
+
+      def initialize(status, headers, body)
+        @status = status
+        # Header names are lower-cased, so lookups never have to guess the casing.
+        @headers = headers
+        @body = body
+      end
+
+      def ok?
+        status >= 200 && status < 300
+      end
+    end
+
+    # What Http needs from the network.
+    class Transport
+      # Perform the call and read the whole body.
+      #
+      # A non-2xx is a normal return, not an exception — Http decides what a
+      # status means. Only a failure to complete the exchange at all raises, and
+      # it must raise ThousandMails::ConnectionError (or ThousandMails::TimeoutError).
+      def send_request(_request)
+        raise NotImplementedError, "#{self.class}#send_request"
+      end
+
+      # Perform the call and hand each chunk of the body to the block as it
+      # arrives. Returning false from the block closes the connection.
+      #
+      # The Node SDK's `open()` hands back a readable body; Ruby's Net::HTTP is
+      # push-based, so the consumer arrives as a block instead. EventStream turns
+      # that back into a pull-based Enumerator with a Fiber.
+      def stream(_request)
+        raise NotImplementedError, "#{self.class}#stream"
+      end
+    end
+
+    # The default transport: Net::HTTP, no third-party gems.
+    class NetHttpTransport < Transport
+      # Net::HTTP needs a read timeout even on the event stream, which is idle by
+      # design between events. The server sends a `: ping` comment every 25s, so
+      # anything past this means the connection is genuinely gone rather than
+      # quiet, and reconnecting is the right answer.
+      STREAM_READ_TIMEOUT_SECONDS = 60
+
+      def send_request(request)
+        with_session(request) do |session, prepared|
+          response = session.request(prepared)
+          Response.new(response.code.to_i, headers_of(response), response.body.to_s)
+        end
+      end
+
+      def stream(request, &on_chunk)
+        with_session(request, read_timeout: STREAM_READ_TIMEOUT_SECONDS) do |session, prepared|
+          result = nil
+
+          begin
+            session.request(prepared) do |response|
+              status = response.code.to_i
+              headers = headers_of(response)
+
+              # A non-2xx on the stream endpoint carries a normal JSON body, so
+              # it is read whole and handed back for Http to turn into a typed
+              # error.
+              unless status >= 200 && status < 300
+                result = Response.new(status, headers, response.read_body.to_s)
+                next
+              end
+
+              # Set before reading, because stopping unwinds past this point.
+              result = Response.new(status, headers, "")
+              response.read_body { |chunk| raise StopStreaming unless on_chunk.call(chunk) }
+            end
+          rescue StopStreaming
+            # The consumer asked to stop.
+            #
+            # The rescue sits out here, outside `session.request`, on purpose. If
+            # the raise were caught inside the block, Net::HTTP would carry on to
+            # `HTTPResponse#reading_body`, whose next act is to drain whatever is
+            # left of the body so the connection can be reused. On a stream that
+            # stays open by design there is no "rest of the body", so it would
+            # block until the read timeout — leaving `close` looking like it did
+            # nothing and the reader thread parked. Letting the exception unwind
+            # past that point closes the socket instead.
+          end
+
+          result
+        end
+      end
+
+      private
+
+      # Raised to break out of Net::HTTP's chunk loop when the consumer is done.
+      class StopStreaming < StandardError; end
+
+      def with_session(request, read_timeout: nil)
+        uri = URI.parse(request.url)
+        timeout = read_timeout || request.timeout_seconds
+
+        session = Net::HTTP.new(uri.host, uri.port)
+        session.use_ssl = uri.scheme == "https"
+        if timeout
+          session.open_timeout = timeout
+          session.read_timeout = timeout
+          session.write_timeout = timeout if session.respond_to?(:write_timeout=)
+        end
+
+        session.start do |started|
+          yield(started, build_request(request, uri))
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+        raise TimeoutError.new("#{request.http_method} #{request.url} timed out", cause: e)
+      rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
+        raise ConnectionError.new("#{request.http_method} #{request.url} failed: #{e.message}", cause: e)
+      end
+
+      def build_request(request, uri)
+        klass = case request.http_method.to_s.upcase
+                when "GET" then Net::HTTP::Get
+                when "POST" then Net::HTTP::Post
+                when "PUT" then Net::HTTP::Put
+                when "PATCH" then Net::HTTP::Patch
+                when "DELETE" then Net::HTTP::Delete
+                else raise ConfigError, "Unsupported HTTP method: #{request.http_method}"
+                end
+
+        path = uri.request_uri
+        prepared = klass.new(path)
+        request.headers.each { |name, value| prepared[name] = value }
+        prepared.body = request.body if request.body
+        prepared
+      end
+
+      def headers_of(response)
+        headers = {}
+        response.each_header { |name, value| headers[name.to_s.downcase] = value }
+        headers
+      end
+    end
+  end
+end

data/lib/thousandmails/utils/validate.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module ThousandMails
+  # Local pre-flight checks that mirror src/backend/client/services/Sendpipeline.js.
+  #
+  # They run in the same order the server runs them, so a message rejected here
+  # would have been rejected there with the same complaint — the SDK just saves
+  # the round trip. Anything the server alone can know (does this sender exist,
+  # is the domain verified, is the recipient suppressed) is deliberately left to
+  # the API.
+  #
+  # Pass `validate_input: false` to the client to skip all of it.
+  #
+  # Message hashes may be keyed with symbols or strings; both are read, and the
+  # wire format is always the string keys the API documents.
+  module Validate
+    # Keys the API understands. Anything else is treated as a typo.
+    KNOWN_FIELDS = %w[
+      senderemail from to cc bcc subject text html
+      templateid templateId templaterequiredfields templateRequiredFields
+      attachments
+    ].freeze
+
+    module_function
+
+    # Validate one message and return it normalised. Attachments are checked
+    # separately (ThousandMails::Attachments) because only the multipart endpoints
+    # take them.
+    def message(input, validate_recipients: true)
+      raise InvalidInputError, "A message object is required" unless input.is_a?(Hash) && !input.empty?
+
+      payload = stringify_keys(input)
+
+      # `from`, `templateId` and `templateRequiredFields` are accepted as aliases
+      # so the SDK reads naturally to anyone coming from another mail library;
+      # the wire format stays exactly what the API documents.
+      sender = payload["senderemail"] || payload["from"]
+      template = payload["templateid"] || payload["templateId"]
+      fields = payload["templaterequiredfields"] || payload["templateRequiredFields"]
+
+      subject = payload["subject"]
+      text = payload["text"]
+      html = payload["html"]
+
+      if sender.nil? || sender.to_s.empty?
+        raise InvalidInputError.new("senderemail is required", { field: "senderemail" })
+      end
+
+      normalised_sender = sender.to_s.strip.downcase
+      unless Constants::EMAIL_PATTERN.match?(normalised_sender)
+        raise InvalidInputError.new(
+          "senderemail is not a valid email address",
+          { field: "senderemail", value: normalised_sender }
+        )
+      end
+
+      to = normalise_recipients(payload["to"], "to")
+      cc = normalise_recipients(payload["cc"], "cc")
+      bcc = normalise_recipients(payload["bcc"], "bcc")
+
+      raise InvalidInputError.new("to is required", { field: "to" }) if to[:value].nil?
+
+      if validate_recipients
+        assert_addresses(to, "to")
+        assert_addresses(cc, "cc")
+        assert_addresses(bcc, "bcc")
+      end
+
+      has_template = !template.nil? && !template.to_s.empty?
+      has_raw = present?(subject) || present?(text) || present?(html)
+
+      if has_template && has_raw
+        raise InvalidInputError, "Send either templateid or subject/text/html, not both"
+      end
+
+      unless has_template
+        raise InvalidInputError.new("subject is required", { field: "subject" }) unless present?(subject)
+
+        unless present?(text) || present?(html)
+          raise InvalidInputError.new("text or html is required", { field: "text" })
+        end
+
+        # The server resolves `{{placeholders}}` in raw bodies too, and 422s when
+        # a value is missing. It cannot see inside a stored template from here,
+        # so only the raw path is checked locally.
+        required = placeholders_in([subject, text, html])
+        unless required.empty?
+          provided = fields.is_a?(Hash) ? stringify_keys(fields) : {}
+          missing = required.reject { |name| present?(provided[name]) }
+
+          unless missing.empty?
+            raise InvalidInputError.new(
+              "templaterequiredfields is missing required values",
+              { requiredFields: required, missingFields: missing }
+            )
+          end
+        end
+      end
+
+      if !fields.nil? && !fields.is_a?(Hash)
+        raise InvalidInputError.new(
+          "templaterequiredfields must be an object",
+          { field: "templaterequiredfields" }
+        )
+      end
+
+      unknown = payload.keys - KNOWN_FIELDS
+      unless unknown.empty?
+        # The API ignores unknown keys, so a typo like `htlm` would silently send
+        # a message with no HTML body. Refusing here is the whole point of
+        # pre-flight.
+        raise InvalidInputError.new(
+          "Unknown field(s): #{unknown.join(', ')}. The API ignores unrecognised " \
+          "keys, so this is almost certainly a typo.",
+          { fields: unknown }
+        )
+      end
+
+      compact(
+        "senderemail" => normalised_sender,
+        "to" => to[:value],
+        "cc" => cc[:value],
+        "bcc" => bcc[:value],
+        "subject" => subject,
+        "text" => text,
+        "html" => html,
+        "templateid" => has_template ? template : nil,
+        "templaterequiredfields" => fields.nil? ? nil : stringify_keys(fields)
+      )
+    end
+
+    # Validate a batch and return the normalised messages.
+    def batch(messages, multipart: false, **options)
+      entries = list_of(messages)
+
+      raise InvalidInputError, "messages must be a non-empty array" if entries.nil? || entries.empty?
+
+      maximum = multipart ? Constants::MAX_ATTACHMENT_BATCH : Constants::MAX_BATCH
+      if entries.length > maximum
+        raise InvalidInputError.new(
+          "A #{multipart ? 'multipart ' : ''}batch may contain at most #{maximum} messages",
+          { received: entries.length, max: maximum }
+        )
+      end
+
+      entries.each_with_index.map do |entry, index|
+        begin
+          message(entry, **options)
+        rescue InvalidInputError => e
+          raise e.with_index(index)
+        end
+      end
+    end
+
+    # Unwrap `[a, b]` or `{ messages: [a, b] }` into a plain array.
+    def list_of(messages)
+      return messages if messages.is_a?(Array)
+
+      if messages.is_a?(Hash)
+        inner = messages[:messages] || messages["messages"]
+        return inner if inner.is_a?(Array)
+      end
+
+      nil
+    end
+
+    # Normalise a recipient field to the shape the API accepts.
+    #
+    # `:splittable` records whether the caller handed us a bare string. Only then
+    # may a comma be read as a separator — once a `{ name:, address: }` entry has
+    # been flattened to "Doe, John <j@x.com>" the commas inside it are data.
+    def normalise_recipients(value, field)
+      return { value: nil, splittable: false } if value.nil? || value == "" || value == []
+
+      was_list = value.is_a?(Array)
+      entries = was_list ? value : [value]
+
+      cleaned = entries.filter_map do |entry|
+        case entry
+        when String
+          trimmed = entry.strip
+          trimmed.empty? ? nil : trimmed
+        when Hash
+          # { name:, address: } — the shape most mail libraries use.
+          record = stringify_keys(entry)
+          address = record["address"]
+          raise recipient_shape_error(field) if address.nil? || address.to_s.empty?
+
+          name = record["name"]
+          present?(name) ? "#{name} <#{address}>" : address.to_s
+        else
+          raise recipient_shape_error(field)
+        end
+      end
+
+      return { value: nil, splittable: false } if cleaned.empty?
+
+      # A bare string stays a string on the wire, exactly as it arrived.
+      {
+        value: was_list ? cleaned : cleaned.first,
+        splittable: !was_list && value.is_a?(String)
+      }
+    end
+
+    # Strip display names: "Ada <ada@x.com>" => "ada@x.com".
+    def bare_address(entry)
+      match = /<([^>]+)>/.match(entry.to_s)
+      (match ? match[1] : entry.to_s).strip
+    end
+
+    # Placeholder names appearing in any of the given strings, in first-seen order.
+    def placeholders_in(parts)
+      parts.filter_map { |part| part if part.is_a?(String) && !part.empty? }
+           .flat_map { |part| part.scan(Constants::PLACEHOLDER_PATTERN).flatten }
+           .uniq
+    end
+
+    # Drop nil values so they never reach the wire.
+    def compact(hash)
+      hash.reject { |_, value| value.nil? }
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+    end
+
+    def present?(value)
+      !value.nil? && value != ""
+    end
+
+    def recipient_shape_error(field)
+      InvalidInputError.new(
+        "#{field} entries must be a string or { name:, address: }",
+        { field: field }
+      )
+    end
+
+    def assert_addresses(recipients, field)
+      value = recipients[:value]
+      return if value.nil?
+
+      parts = if value.is_a?(Array)
+                value
+              elsif recipients[:splittable]
+                value.to_s.split(",")
+              else
+                [value]
+              end
+
+      parts.each do |part|
+        address = bare_address(part)
+        next if address.empty?
+
+        unless Constants::EMAIL_PATTERN.match?(address)
+          raise InvalidInputError.new(
+            "\"#{address}\" in #{field} is not a valid email address",
+            { field: field, value: address }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/thousandmails/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ThousandMails
+  # The SDK version, sent on the User-Agent.
+  VERSION = "1.0.0"
+end

data/lib/thousandmails.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for the ThousandMails client API.
+#
+#   require "thousandmails"
+#
+#   thousandmails = ThousandMails.new(api_key: ENV["THOUSANDMAILS_API_KEY"])
+#   thousandmails.send_mail(
+#     senderemail: "noreply@yourdomain.com",
+#     to: "customer@example.com",
+#     subject: "Your receipt",
+#     html: "<p>Thanks for your order.</p>"
+#   )
+
+require_relative "thousandmails/version"
+require_relative "thousandmails/utils/constants"
+require_relative "thousandmails/utils/errors"
+require_relative "thousandmails/utils/options"
+require_relative "thousandmails/utils/transport"
+require_relative "thousandmails/utils/http"
+require_relative "thousandmails/utils/validate"
+require_relative "thousandmails/utils/attachments"
+require_relative "thousandmails/utils/stream"
+require_relative "thousandmails/resources/emails"
+require_relative "thousandmails/resources/stats"
+require_relative "thousandmails/resources/realtime"
+require_relative "thousandmails/resources/logs"
+require_relative "thousandmails/client"
+
+module ThousandMails
+  # `ThousandMails.new(...)` is `ThousandMails::Client.new(...)`, so the entry point
+  # reads the same as it does in the Node, PHP and Python SDKs.
+  def self.new(...)
+    Client.new(...)
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: thousandmails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Hariraghav.S
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Transactional email, attachments, statistics, delivery logs and a live
+  event stream, behind one client object.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/thousandmails.rb
+- lib/thousandmails/client.rb
+- lib/thousandmails/resources/emails.rb
+- lib/thousandmails/resources/logs.rb
+- lib/thousandmails/resources/realtime.rb
+- lib/thousandmails/resources/stats.rb
+- lib/thousandmails/utils/attachments.rb
+- lib/thousandmails/utils/constants.rb
+- lib/thousandmails/utils/errors.rb
+- lib/thousandmails/utils/http.rb
+- lib/thousandmails/utils/options.rb
+- lib/thousandmails/utils/stream.rb
+- lib/thousandmails/utils/transport.rb
+- lib/thousandmails/utils/validate.rb
+- lib/thousandmails/version.rb
+homepage: https://thousandmails.com
+licenses:
+- Nonstandard
+metadata:
+  homepage_uri: https://thousandmails.com
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Official Ruby SDK for the ThousandMails client API
+test_files: []