thousandmails 1.0.0

data/lib/thousandmails/resources/emails.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "uri"
+
+module ThousandMails
+  module Resources
+    # Email sending — the four send endpoints plus the message lookup.
+    #
+    #   POST /client/sendmail
+    #   POST /client/send/batch
+    #   POST /client/sendmail/attachment
+    #   POST /client/send/attachment/batch
+    #   GET  /client/messages/:id
+    class Emails
+      @warned_about_batch_idempotency = false
+
+      class << self
+        attr_accessor :warned_about_batch_idempotency
+      end
+
+      def initialize(client)
+        @client = client
+      end
+
+      def http
+        @client.http
+      end
+
+      # Send one email — raw (`subject` plus `text`/`html`) or from a saved
+      # template (`templateid` plus `templaterequiredfields`), never both.
+      #
+      # When the message carries `attachments` this routes to the multipart
+      # endpoint automatically, so callers have one method to remember.
+      #
+      # `send` shadows Ruby's Object#send on this object; `deliver` is an alias
+      # for anyone who would rather not.
+      #
+      # @param idempotency_key [String, false, nil] your own key, or false for none
+      # @param timeout [Integer, nil] overrides the client timeout, in milliseconds
+      def send(message = nil, idempotency_key: nil, timeout: nil, **fields)
+        message = Options.merge(message, fields)
+
+        if message.is_a?(Hash) && (message.key?(:attachments) || message.key?("attachments"))
+          return send_with_attachments(message, idempotency_key: idempotency_key, timeout: timeout)
+        end
+
+        body = @client.validate_input ? Validate.message(message, **@client.validate_options) : message
+
+        http.request_object(
+          "POST", "/sendmail",
+          json: body,
+          idempotency_key: idempotency_key_for(idempotency_key),
+          timeout: timeout
+        )
+      end
+      alias deliver send
+
+      # Send up to 100 emails in one request. Each entry is validated and sent
+      # independently — a failure on one never rejects the batch, so always read
+      # the per-entry `outcome` in the response.
+      #
+      # The API ignores `Idempotency-Key` on batches, so a batch is never retried
+      # automatically after a 5xx.
+      def send_batch(messages = nil, idempotency_key: nil, timeout: nil, **fields)
+        # Folds `send_batch(messages: [...])` — the documented wrapper form —
+        # back into the payload; a plain array positional passes through.
+        messages = Options.merge(messages, fields)
+
+        if idempotency_key && !self.class.warned_about_batch_idempotency
+          self.class.warned_about_batch_idempotency = true
+          warn "ThousandMails: the API ignores Idempotency-Key on batch sends; " \
+               "the header will not be sent."
+        end
+
+        entries = if @client.validate_input
+                    Validate.batch(messages, **@client.validate_options)
+                  else
+                    Validate.list_of(messages) || []
+                  end
+
+        http.request_object("POST", "/send/batch", json: { "messages" => entries }, timeout: timeout)
+      end
+
+      # Send one email with 1–5 attachments (multipart/form-data). Files may be
+      # paths on disk or bytes in memory — see ThousandMails::Attachments for the
+      # accepted forms. At least one file is required; without one, use `send`.
+      def send_with_attachments(message = nil, idempotency_key: nil, timeout: nil, **fields)
+        message = Options.merge(message, fields)
+
+        raise InvalidInputError, "A message object is required" unless message.is_a?(Hash)
+
+        unless message.key?(:attachments) || message.key?("attachments")
+          raise InvalidInputError.new(
+            "attachments is required — use send for a message without files",
+            { field: "attachments" }
+          )
+        end
+
+        attachments = message[:attachments] || message["attachments"]
+        rest = message.reject { |key, _| key.to_s == "attachments" }
+
+        body = @client.validate_input ? Validate.message(rest, **@client.validate_options) : rest
+        form, = Attachments.single_form(body, attachments)
+
+        http.request_object(
+          "POST", "/sendmail/attachment",
+          form: form,
+          idempotency_key: idempotency_key_for(idempotency_key),
+          timeout: timeout
+        )
+      end
+
+      # Send up to 20 emails, each with its own files, in one multipart request.
+      # Every message must carry at least one attachment — the API rejects the
+      # entry otherwise. Files bind to their message by position.
+      def send_batch_with_attachments(messages = nil, timeout: nil, **fields)
+        messages = Options.merge(messages, fields)
+
+        entries = Validate.list_of(messages)
+        raise InvalidInputError, "messages must be a non-empty array" if entries.nil? || entries.empty?
+
+        bodies = []
+        files = []
+
+        entries.each do |entry|
+          record = entry.is_a?(Hash) ? entry : {}
+          files << (record[:attachments] || record["attachments"])
+          bodies << record.reject { |key, _| key.to_s == "attachments" }
+        end
+
+        validated = if @client.validate_input
+                      Validate.batch(bodies, multipart: true, **@client.validate_options)
+                    else
+                      bodies
+                    end
+
+        form, = Attachments.batch_form(validated, files)
+
+        http.request_object("POST", "/send/attachment/batch", form: form, timeout: timeout)
+      end
+
+      # Look up a send by the id returned from a send call, or by its SMTP
+      # message id (`<uuid@domain>` — encoded for you).
+      def get(message_id, timeout: nil)
+        if !message_id.is_a?(String) || message_id.strip.empty?
+          raise InvalidInputError, "A message id is required"
+        end
+
+        http.request_object(
+          "GET",
+          "/messages/#{Http.encode_path_segment(message_id)}",
+          timeout: timeout
+        )
+      end
+
+      private
+
+      # A single send is only replayable when it carries a key, so one is minted
+      # per call unless the caller supplies their own or opts out with false. The
+      # key scopes one logical send: a transport retry inside this call re-uses
+      # it and is de-duplicated server-side, while a later call gets a fresh one.
+      def idempotency_key_for(supplied)
+        return nil if supplied == false
+        return supplied.strip if supplied.is_a?(String) && !supplied.strip.empty?
+        return nil if !@client.auto_idempotency || http.max_retries.zero?
+
+        "sdk-#{SecureRandom.uuid}"
+      end
+    end
+  end
+end

data/lib/thousandmails/resources/logs.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "csv"
+require "date"
+require "time"
+
+module ThousandMails
+  module Resources
+    # The delivery event log.
+    #
+    #   GET /client/logs
+    #   GET /client/logs/export   (CSV)
+    #   GET /client/logs/:id
+    class Logs
+      DAY_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
+
+      def initialize(client)
+        @client = client
+      end
+
+      def http
+        @client.http
+      end
+
+      # One page of events, newest first.
+      #
+      # Recognised keys: `to` (alias `recipient`), `search`, `event` (alias
+      # `type`), `from`, `until`, `page`, `pageSize` (alias `limit`, 1–200,
+      # default 50).
+      def list(query = nil, timeout: nil, **fields)
+        query = Options.merge(query, fields)
+
+        query = self.class.stringify(query)
+        page_size = query["pageSize"] || query["limit"]
+        bounds = Constants::LIMITS["logPageSize"]
+
+        unless page_size.nil?
+          valid = begin
+            number = Integer(page_size)
+            number >= bounds[:min] && number <= bounds[:max]
+          rescue ArgumentError, TypeError
+            false
+          end
+
+          unless valid
+            raise InvalidInputError.new(
+              "pageSize must be between #{bounds[:min]} and #{bounds[:max]}",
+              { field: "pageSize", value: page_size }
+            )
+          end
+        end
+
+        params = self.class.filters(query).merge(
+          "page" => query["page"],
+          "pageSize" => page_size
+        )
+
+        http.request_object("GET", "/logs", query: params, timeout: timeout)
+      end
+
+      # Walk every page of a filtered log, yielding one event at a time.
+      #
+      # Deep paging is bounded server-side: past ~10,000 rows the response comes
+      # back with `truncated: true` and iteration stops rather than looping on a
+      # page that can never advance. Narrow with filters instead of paging that
+      # far.
+      #
+      #   client.logs.iterate({ event: "bounced" }).each { |event| ... }
+      def iterate(query = nil, timeout: nil, **fields)
+        query = Options.merge(query, fields)
+        return enum_for(:iterate, query, timeout: timeout) unless block_given?
+
+        query = self.class.stringify(query)
+        page_size = query["pageSize"] || query["limit"] || Constants::LIMITS["logPageSize"][:max]
+        page = (query["page"] || 1).to_i
+
+        loop do
+          # The loop's page/pageSize must win over whatever the caller passed, or
+          # a `page` in the query would pin every iteration to the same page.
+          result = list(query.merge("pageSize" => page_size, "page" => page), timeout: timeout)
+
+          events = result["events"] || []
+          events.each { |event| yield event }
+
+          break if !result["hasMore"] || result["truncated"] || events.empty?
+
+          page += 1
+        end
+      end
+
+      # Fetch one event by its `eventId`.
+      def get(event_id, timeout: nil)
+        if !event_id.is_a?(String) || event_id.strip.empty?
+          raise InvalidInputError, "An eventId is required"
+        end
+
+        data = http.request_object(
+          "GET",
+          "/logs/#{Http.encode_path_segment(event_id)}",
+          timeout: timeout
+        )
+
+        # The endpoint wraps its payload; unwrap so it matches every other event shape.
+        data["event"].is_a?(Hash) ? data["event"] : data
+      end
+
+      # The same filtered log as CSV (up to 5000 rows), returned as a string.
+      # Paging params do not apply. Columns: eventId, occurredAt, type,
+      # recipient, senderEmail, subject, messageId, queueId, dsn, ip.
+      def export(query = nil, timeout: nil, **fields)
+        query = Options.merge(query, fields)
+
+        http.request(
+          "GET", "/logs/export",
+          query: self.class.filters(self.class.stringify(query)),
+          parse: :text,
+          timeout: timeout
+        )[:data]
+      end
+
+      # Convenience: export straight to a file on disk. Returns the row count.
+      def export_to_file(file_path, query = nil, timeout: nil, **fields)
+        content = export(Options.merge(query, fields), timeout: timeout)
+        File.write(file_path, content, mode: "wb")
+        self.class.count_rows(content)
+      end
+
+      class << self
+        # Data rows in a CSV export, excluding the header.
+        #
+        # Counting line breaks would overcount: the server quotes any cell
+        # holding a newline (a subject can), so the CSV is parsed rather than
+        # split.
+        def count_rows(content)
+          return 0 if content.nil? || content.strip.empty?
+
+          rows = CSV.parse(content).reject { |row| row.nil? || row.empty? || row == [nil] }
+          [0, rows.length - 1].max
+        rescue CSV::MalformedCSVError
+          0
+        end
+
+        # `from`/`until` accept a YYYY-MM-DD day (widened to cover it), an ISO
+        # timestamp, or a Date/Time. The API ignores an unparsable value rather
+        # than rejecting it, which silently widens the window — so it is checked
+        # here.
+        def to_bound(value, field)
+          return nil if value.nil? || value == ""
+          # A wall-clock instant is pinned to UTC, which is the timezone the API
+          # reads the window in. Taking it as-is would shift the boundary by the
+          # caller's offset.
+          return value.getutc.iso8601 if value.is_a?(Time)
+          return value.to_time.getutc.iso8601 if value.is_a?(DateTime)
+          return value.strftime("%Y-%m-%d") if value.is_a?(Date)
+
+          text = value.to_s.strip
+          # Shape and calendar both — "2026-13-45" is the right shape and not a
+          # real day, and the API would ignore it and widen the window silently.
+          return text if DAY_PATTERN.match?(text) && Resources::Stats.calendar_day?(text)
+
+          begin
+            # Time.iso8601, not DateTime.parse. Ruby's general parser is lenient
+            # enough to read "last-tuesday" as a real date and "2026-13-45" as a
+            # valid one, which would defeat the whole point of this check: the
+            # API ignores what it cannot parse and silently widens the window, so
+            # anything it would not accept has to be refused here.
+            Time.iso8601(text)
+          rescue ArgumentError, TypeError
+            raise InvalidInputError.new(
+              "#{field} must be YYYY-MM-DD, an ISO-8601 timestamp, or a Date/Time — " \
+              "the API ignores anything it cannot parse",
+              { field: field, value: text }
+            )
+          end
+
+          text
+        end
+
+        def filters(query)
+          event = query["event"] || query["type"]
+
+          if !event.nil? && !Constants::EVENT_TYPES.include?(event.to_s)
+            raise InvalidInputError.new(
+              "event must be one of: #{Constants::EVENT_TYPES.join(', ')}",
+              { field: "event", value: event }
+            )
+          end
+
+          {
+            "to" => query["to"] || query["recipient"],
+            "search" => query["search"],
+            "event" => event,
+            "from" => to_bound(query["from"], "from"),
+            "until" => to_bound(query["until"], "until")
+          }
+        end
+
+        def stringify(query)
+          (query || {}).each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        end
+      end
+    end
+  end
+end

data/lib/thousandmails/resources/realtime.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ThousandMails
+  module Resources
+    # Live counters, feeds and the event stream.
+    #
+    #   GET /client/realtime/stats
+    #   GET /client/realtime/per-minute
+    #   GET /client/realtime/per-second
+    #   GET /client/realtime/activity
+    #   GET /client/realtime/stream   (Server-Sent Events)
+    class Realtime
+      def initialize(client)
+        @client = client
+      end
+
+      def http
+        @client.http
+      end
+
+      # Every metric summed over the last N minutes (1–120, default 60).
+      def stats(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        http.request_object(
+          "GET", "/realtime/stats",
+          query: { "minutes" => self.class.bounded(params["minutes"], "minutes", "realtimeMinutes") },
+          timeout: timeout
+        )
+      end
+
+      # The last N per-minute buckets, oldest first (1–120, default 60).
+      def per_minute(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        http.request_object(
+          "GET", "/realtime/per-minute",
+          query: { "minutes" => self.class.bounded(params["minutes"], "minutes", "realtimeMinutes") },
+          timeout: timeout
+        )
+      end
+
+      # Per-second buckets over the last N seconds (1–600, default 120),
+      # zero-filled so the series is continuous.
+      #
+      # The API derives these from at most 1000 raw events, newest first, so an
+      # account busier than that in the window will see the oldest seconds
+      # reported as idle. Narrow the window when volume is high.
+      def per_second(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        http.request_object(
+          "GET", "/realtime/per-second",
+          query: { "seconds" => self.class.bounded(params["seconds"], "seconds", "realtimeSeconds") },
+          timeout: timeout
+        )
+      end
+
+      # The most recent events, newest first (1–100, default 20).
+      def activity(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        http.request_object(
+          "GET", "/realtime/activity",
+          query: { "limit" => self.class.bounded(params["limit"], "limit", "activityLimit") },
+          timeout: timeout
+        )
+      end
+
+      # Open the live event stream.
+      #
+      # Returns an EventStream that dispatches to handlers through `listen`, or
+      # yields email events through `events`. Reconnects with backoff unless
+      # `reconnect: false` or the failure is an auth error, which will never
+      # resolve itself.
+      #
+      # Always call `close` (or `break` out of the loop) — the connection is held
+      # open by design and blocks the process otherwise.
+      def stream(**options)
+        EventStream.new(http, **options)
+      end
+
+      class << self
+        # The API clamps out-of-range values silently, which makes a typo look
+        # like data. Rejecting locally keeps the window a caller asked for and
+        # the one they get the same thing.
+        def bounded(value, name, limit_key)
+          return nil if value.nil? || value == ""
+
+          bounds = Constants::LIMITS[limit_key]
+          number = Integer(value)
+          raise ArgumentError if number < bounds[:min] || number > bounds[:max]
+
+          number
+        rescue ArgumentError, TypeError
+          raise InvalidInputError.new(
+            "#{name} must be a number between #{bounds[:min]} and #{bounds[:max]}",
+            { field: name, value: value }
+          )
+        end
+
+        def stringify(params)
+          (params || {}).each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        end
+      end
+    end
+  end
+end

data/lib/thousandmails/resources/stats.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "date"
+
+module ThousandMails
+  module Resources
+    # Aggregate statistics.
+    #
+    #   GET /client/stats/summary
+    #   GET /client/stats/timeseries
+    #   GET /client/stats/by-sender
+    #   GET /client/stats/by-tag
+    #
+    # `from`/`to` are YYYY-MM-DD in UTC and default server-side to the last 30
+    # days. A Date or Time is accepted here and converted, because passing one to
+    # a query string otherwise yields a form the API silently ignores.
+    class Stats
+      DAY_PATTERN = /\A\d{4}-\d{2}-\d{2}\z/
+
+      def initialize(client)
+        @client = client
+      end
+
+      def http
+        @client.http
+      end
+
+      # Totals for the window, the preceding window of equal length (for
+      # period-over-period deltas), and the derived rates.
+      def summary(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        http.request_object("GET", "/stats/summary", query: self.class.range(params), timeout: timeout)
+      end
+
+      # Per-interval buckets across the window.
+      # `interval`: day (default), week or month.
+      def timeseries(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        interval = params["interval"]
+
+        if !interval.nil? && !Constants::INTERVALS.include?(interval.to_s)
+          raise InvalidInputError.new(
+            "interval must be one of: #{Constants::INTERVALS.join(', ')}",
+            { field: "interval", value: interval }
+          )
+        end
+
+        query = self.class.range(params).merge("interval" => interval)
+        http.request_object("GET", "/stats/timeseries", query: query, timeout: timeout)
+      end
+
+      # Totals grouped by sender address.
+      def by_sender(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        http.request_object("GET", "/stats/by-sender", query: self.class.range(params), timeout: timeout)
+      end
+
+      # Send outcomes grouped by the record's `tag`, optionally narrowed to a list.
+      #
+      # Note: no send endpoint accepts a tag yet, so in practice every send is
+      # untagged and the whole window collapses into a single `tag: nil` row.
+      def by_tag(params = nil, timeout: nil, **fields)
+        params = Options.merge(params, fields)
+
+        params = self.class.stringify(params)
+        tags = params["tags"]
+        tags = tags.join(",") if tags.is_a?(Array)
+
+        query = self.class.range(params).merge("tags" => tags)
+        http.request_object("GET", "/stats/by-tag", query: query, timeout: timeout)
+      end
+
+      class << self
+        # Normalise one end of a date range to YYYY-MM-DD.
+        def to_day(value, field)
+          return nil if value.nil? || value == ""
+          # `from`/`to` are days in UTC, so a wall-clock instant is converted
+          # rather than read off as-is: 05:00 in +05:30 is the previous day to
+          # the API, and taking the local day would silently shift the window.
+          return value.getutc.strftime("%Y-%m-%d") if value.is_a?(Time)
+          return value.to_time.getutc.strftime("%Y-%m-%d") if value.is_a?(DateTime)
+          return value.strftime("%Y-%m-%d") if value.is_a?(Date)
+
+          text = value.to_s.strip
+          # Shape and calendar both: "2026-13-45" is the right shape and not a
+          # real day, and the API would ignore it and quietly fall back to its
+          # default window rather than say so.
+          unless DAY_PATTERN.match?(text) && calendar_day?(text)
+            raise InvalidInputError.new(
+              "#{field} must be a real YYYY-MM-DD date or a Date object — the API " \
+              "silently ignores anything else and falls back to its default window",
+              { field: field, value: text }
+            )
+          end
+
+          text
+        end
+
+        # True when the text names a day that exists.
+        def calendar_day?(text)
+          Date.strptime(text, "%Y-%m-%d")
+          true
+        rescue ArgumentError, TypeError
+          false
+        end
+
+        def range(params)
+          params = stringify(params)
+          { "from" => to_day(params["from"], "from"), "to" => to_day(params["to"], "to") }
+        end
+
+        def stringify(params)
+          (params || {}).each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        end
+      end
+    end
+  end
+end