haskimail-rails 1.0.0

data/lib/haskimail/rails/message_options.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Rails
+    # Haskimail-specific settings attached to a Mail::Message (`message.haskimail`).
+    class MessageOptions
+      ATTRIBUTES = %i[tag metadata message_stream track_opens track_links template template_model].freeze
+
+      attr_reader(*ATTRIBUTES)
+      # Response of the last successful delivery ({ message_id:, submitted_at:, ... }).
+      attr_accessor :response
+
+      def assign(options)
+        Util.assert_known_keys!(options.keys, ATTRIBUTES, "haskimail")
+        options.each { |key, value| public_send(:"#{key}=", value) }
+        self
+      end
+
+      def tag=(value)
+        @tag = value&.to_s
+      end
+
+      def metadata=(value)
+        raise ArgumentError, "metadata must be a Hash" unless value.nil? || value.is_a?(Hash)
+
+        @metadata = value
+      end
+
+      def message_stream=(value)
+        @message_stream = value&.to_s
+      end
+
+      def track_opens=(value)
+        raise ArgumentError, "track_opens must be true, false or nil" unless [true, false, nil].include?(value)
+
+        @track_opens = value
+      end
+
+      def track_links=(value)
+        raise ArgumentError, "track_links must be true, false or nil" unless [true, false, nil].include?(value)
+
+        @track_links = value
+      end
+
+      # @param value [Integer, String] template ID (Integer) or alias/name (String)
+      def template=(value)
+        unless value.nil? || value.is_a?(Integer) || (value.is_a?(String) && !value.strip.empty?)
+          raise ArgumentError, "template must be an Integer ID or a String alias"
+        end
+
+        @template = value
+      end
+
+      def template_model=(value)
+        raise ArgumentError, "template_model must be a Hash" unless value.nil? || value.is_a?(Hash)
+
+        @template_model = value
+      end
+
+      def template?
+        !template.nil?
+      end
+
+      def message_id
+        response && response[:message_id]
+      end
+
+      def to_api
+        payload = {
+          "Tag" => tag, "Metadata" => metadata, "MessageStream" => message_stream,
+          "TrackOpens" => track_opens, "TrackLinks" => track_links
+        }
+        if template?
+          payload[template.is_a?(Integer) ? "TemplateId" : "TemplateAlias"] = template
+          payload["TemplateModel"] = template_model || {}
+        end
+        payload.compact
+      end
+    end
+
+    # Adds `message.haskimail` to Mail::Message.
+    module MailExtension
+      def haskimail
+        @haskimail ||= MessageOptions.new
+      end
+    end
+  end
+end

data/lib/haskimail/rails/railtie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Rails
+    # Wires Haskimail into a Rails application.
+    #
+    #   # config/application.rb (optional; credentials/ENV work too)
+    #   config.haskimail.server_token = Rails.application.credentials.dig(:haskimail, :server_token)
+    #   config.haskimail.default_message_stream = "2081"
+    class Railtie < ::Rails::Railtie
+      config.haskimail = ActiveSupport::OrderedOptions.new
+
+      initializer "haskimail.configure" do |app|
+        settings = app.config.haskimail.to_h
+        unknown = settings.keys.map(&:to_sym) - Configuration::SETTINGS
+        raise ConfigurationError, "Unknown config.haskimail option(s): #{unknown.join(', ')}" if unknown.any?
+
+        Haskimail.configure do |config|
+          settings.each { |key, value| config.public_send(:"#{key}=", value) }
+        end
+      end
+
+      generators do
+        require_relative "../../generators/haskimail/install/install_generator"
+      end
+    end
+  end
+end

data/lib/haskimail/resources/account_templates.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Account-level template operations (account token).
+    class AccountTemplates < Base
+      # Moves (not copies!) all templates from one server to another.
+      # Call with perform_changes: false first to preview what would be moved.
+      # @return [Hash] { total_count:, templates: [{ template_id:, name: }] }
+      def push(source_server_id:, destination_server_id:, perform_changes:)
+        require_boolean!(:perform_changes, perform_changes)
+        require_value!(:source_server_id, source_server_id)
+        require_value!(:destination_server_id, destination_server_id)
+        if source_server_id.to_s == destination_server_id.to_s
+          raise ArgumentError, "source and destination servers must differ"
+        end
+
+        api_put(path(:templates, :push), {
+                  "SourceServerID" => source_server_id,
+                  "DestinationServerID" => destination_server_id,
+                  "PerformChanges" => perform_changes
+                })
+      end
+
+      # Creates a template on any server of the account.
+      def create(associated_server_id:, name:, subject: nil, html_body: nil, text_body: nil)
+        server_templates.create(name: name, subject: subject, html_body: html_body,
+                                text_body: text_body, associated_server_id: associated_server_id)
+      end
+
+      # Templates of all servers in the account.
+      # @return [Hash] { total_count:, templates: [{ template_id:, name: }] }
+      def list(count: Templates::DEFAULT_PAGE_SIZE, offset: 0)
+        server_templates.list(count: count, offset: offset)
+      end
+
+      def each(page_size: Templates::DEFAULT_PAGE_SIZE, &)
+        server_templates.each(page_size: page_size, &)
+      end
+
+      # Renders a template without saving or sending anything (see Templates#validate).
+      def validate(**options)
+        server_templates.validate(**options)
+      end
+
+      private
+
+      def server_templates
+        @server_templates ||= Templates.new(connection)
+      end
+    end
+  end
+end

data/lib/haskimail/resources/base.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Common plumbing for API resources: path building, serialization, validation.
+    class Base
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      attr_reader :connection
+
+      def path(*segments)
+        segments.map do |segment|
+          segment.is_a?(Symbol) ? segment.to_s : Util.escape_path_segment(segment)
+        end.unshift("").join("/")
+      end
+
+      def api_get(api_path, query = nil)
+        Serializer.from_api(connection.get(api_path, query: query))
+      end
+
+      def api_post(api_path, body = nil, idempotent: false)
+        Serializer.from_api(connection.post(api_path, body && Serializer.to_api(body), idempotent: idempotent))
+      end
+
+      def api_put(api_path, body = nil, idempotent: true)
+        Serializer.from_api(connection.put(api_path, body && Serializer.to_api(body), idempotent: idempotent))
+      end
+
+      def api_patch(api_path, body = nil)
+        Serializer.from_api(connection.patch(api_path, body && Serializer.to_api(body)))
+      end
+
+      def api_delete(api_path)
+        Serializer.from_api(connection.delete(api_path))
+      end
+
+      # Returns an Enumerator, or iterates right away when a block is given.
+      def iterate(items_key, page_size, max_window, consumer, max_page_size: nil, &)
+        Util.assert_range!(:page_size, page_size, 1..(max_page_size || Float::INFINITY))
+        paginator = Paginator.new(items_key: items_key, page_size: page_size, max_window: max_window, &)
+        consumer ? paginator.each(&consumer) : paginator.each
+      end
+
+      def pagination_query(count, offset, max_count: nil, max_window: nil)
+        Util.assert_range!(:count, count, 1..(max_count || Float::INFINITY))
+        Util.assert_range!(:offset, offset, 0..Float::INFINITY)
+        if max_window && count + offset > max_window
+          raise ArgumentError, "count + offset must not exceed #{max_window} (API limit)"
+        end
+
+        { "count" => count, "offset" => offset }
+      end
+
+      def require_value!(name, value)
+        raise ArgumentError, "#{name} is required" if Util.blank?(value)
+
+        value
+      end
+
+      def require_boolean!(name, value)
+        raise ArgumentError, "#{name} must be true or false" unless [true, false].include?(value)
+
+        value
+      end
+    end
+  end
+end

data/lib/haskimail/resources/bounces.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Bounces: https://haskimail.ru/developer/api/bounce-api
+    class Bounces < Base
+      DEFAULT_PAGE_SIZE = 500
+      # List names and their delivery-stats aliases (both are accepted by the API).
+      TYPES = %w[HardBounce SoftBounce BlkBounce SpmBounce BulkBounce SpamBlock].freeze
+
+      FILTERS = {
+        type: "type", email_filter: "emailFilter", tag: "tag", message_id: "messageID",
+        message_stream: "messagestream", from_date: "fromdate", to_date: "todate"
+      }.freeze
+
+      # Bounce counts by type for the last 45 days.
+      # @return [Hash] { bounces: [{ name: "All", count: 253 }, { type: "HardBounce", ... }] }
+      def delivery_stats
+        api_get(path(:deliverystats))
+      end
+
+      # @return [Hash] { total_count:, bounces: [...] }
+      def list(count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        Util.assert_known_keys!(filters.keys, FILTERS.keys, "bounce filter")
+        if filters[:type] && !TYPES.include?(filters[:type].to_s)
+          raise ArgumentError, "type must be one of: #{TYPES.join(', ')}"
+        end
+
+        query = pagination_query(count, offset)
+        filters.each do |key, value|
+          next if value.nil?
+
+          query[FILTERS.fetch(key)] = %i[from_date to_date].include?(key) ? Util.format_date(value) : value.to_s
+        end
+        api_get(path(:bounces), query)
+      end
+
+      def each(page_size: DEFAULT_PAGE_SIZE, **filters, &block)
+        iterate(:bounces, page_size, nil, block) { |count, offset| list(count: count, offset: offset, **filters) }
+      end
+    end
+  end
+end

data/lib/haskimail/resources/domains.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Sender domains (account token): https://haskimail.ru/developer/api/domains-api
+    class Domains < Base
+      DEFAULT_PAGE_SIZE = 500
+
+      # @return [Hash] { total_count:, domains: [{ id:, name:, dkim_verified:, spf_verified:, ... }] }
+      def list(count: DEFAULT_PAGE_SIZE, offset: 0)
+        api_get(path(:domains), pagination_query(count, offset))
+      end
+
+      def each(page_size: DEFAULT_PAGE_SIZE, &block)
+        iterate(:domains, page_size, nil, block) { |count, offset| list(count: count, offset: offset) }
+      end
+
+      # @return [Hash] domain with :spf_text_value and :dkim_text_value DNS records
+      def get(domain_id)
+        api_get(path(:domains, domain_id))
+      end
+
+      def create(name)
+        require_value!(:name, name)
+        api_post(path(:domains), { "Name" => name.to_s.strip })
+      end
+
+      # Deletes the domain and its confirmed sender addresses. Irreversible.
+      def delete(domain_id)
+        api_delete(path(:domains, domain_id))
+      end
+
+      def verify_dkim(domain_id)
+        api_put(path(:domains, domain_id, :verifyDkim))
+      end
+
+      def verify_spf(domain_id)
+        api_put(path(:domains, domain_id, :verifyspf))
+      end
+    end
+  end
+end

data/lib/haskimail/resources/emails.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Sending email: https://haskimail.ru/developer/api/email-api
+    # and template sending: https://haskimail.ru/developer/api/templates-api
+    class Emails < Base
+      MAX_BATCH_SIZE = 500
+      ADDRESS_FIELDS = %w[To Cc Bcc ReplyTo].freeze
+
+      # @example
+      #   client.emails.deliver(
+      #     from: "Магазин <shop@example.com>", to: "ivan@example.com",
+      #     subject: "Заказ №1042", html_body: "<p>Спасибо!</p>",
+      #     tag: "orders", metadata: { order_id: "1042" }, message_stream: "2081"
+      #   )
+      # @return [Hash] { to:, submitted_at:, message_id:, error_code: 0, message: "OK" }
+      def deliver(message)
+        send_one("/email", build_message(message, template: false))
+      end
+
+      # @param messages [Array<Hash>] 1..500 messages; may mix plain and template messages
+      # @return [Array<Hash>] one result per message, in order. Check :error_code of each item:
+      #   the API returns HTTP 200 even when some messages are rejected.
+      def deliver_batch(messages)
+        payload = build_batch(messages) { |message| build_message(message, template: nil) }
+        Serializer.from_api(connection.post("/email/batch", payload))
+      end
+
+      # @example
+      #   client.emails.deliver_with_template(
+      #     template_alias: "order-created", template_model: { "{{name}}" => "Иван" },
+      #     from: "shop@example.com", to: "ivan@example.com"
+      #   )
+      def deliver_with_template(message)
+        send_one("/email/withTemplate", build_message(message, template: true))
+      end
+
+      # @return [Array<Hash>] one result per message, in order (check :error_code of each)
+      def deliver_batch_with_templates(messages)
+        payload = build_batch(messages) { |message| build_message(message, template: true) }
+        Serializer.from_api(connection.post("/email/batchWithTemplates", { "Messages" => payload }))
+      end
+
+      private
+
+      def send_one(api_path, payload)
+        Serializer.from_api(connection.post(api_path, payload))
+      end
+
+      def build_batch(messages, &)
+        list = messages.respond_to?(:to_ary) ? messages.to_ary : nil
+        raise ArgumentError, "messages must be an Array" unless list
+        raise ArgumentError, "messages must not be empty" if list.empty?
+        if list.size > MAX_BATCH_SIZE
+          raise ArgumentError, "A batch may contain at most #{MAX_BATCH_SIZE} messages, got #{list.size}"
+        end
+
+        list.map(&)
+      end
+
+      # @param template [Boolean, nil] true: template required, false: body required, nil: either
+      def build_message(message, template:)
+        raise ArgumentError, "message must be a Hash, got #{message.class}" unless message.is_a?(Hash)
+
+        header_keys = message.keys.select { |key| Serializer.api_key(key) == "Headers" }
+        raise ArgumentError, "Duplicate field Headers (given as #{header_keys.inspect})" if header_keys.size > 1
+
+        # Header names are literal ("X-Order-Id"), so they bypass key transformation.
+        payload = Serializer.to_api(message.except(*header_keys))
+        payload["Headers"] = normalize_headers(message[header_keys.first]) if header_keys.any?
+        normalize!(payload)
+        default_stream = connection.config.default_message_stream
+        payload["MessageStream"] = default_stream.to_s if default_stream && Util.blank?(payload["MessageStream"])
+        validate_message!(payload, template)
+        payload.compact
+      end
+
+      def normalize!(payload)
+        payload["Attachments"] = normalize_attachments(payload["Attachments"]) if payload.key?("Attachments")
+        ADDRESS_FIELDS.each do |field|
+          payload[field] = payload[field].join(", ") if payload[field].is_a?(Array)
+        end
+      end
+
+      def validate_message!(payload, template)
+        %w[From To].each do |field|
+          raise ArgumentError, "#{field} is required" if Util.blank?(payload[field])
+        end
+
+        uses_template = !Util.blank?(payload["TemplateId"]) || !Util.blank?(payload["TemplateAlias"])
+        if template == true && !uses_template
+          raise ArgumentError, "template_id or template_alias is required"
+        elsif template == false && uses_template
+          raise ArgumentError, "Use deliver_with_template to send a template"
+        elsif !uses_template && Util.blank?(payload["HtmlBody"]) && Util.blank?(payload["TextBody"])
+          raise ArgumentError, "html_body or text_body is required"
+        end
+      end
+
+      # Accepts [{name:, value:}] or a plain Hash {"X-Order-Id" => "1042"}.
+      def normalize_headers(headers)
+        list = if headers.is_a?(Hash)
+                 headers.map do |name, value|
+                   { "Name" => name.to_s, "Value" => value.to_s }
+                 end
+               else
+                 headers
+               end
+        Array(list).map do |header|
+          raise ArgumentError, "Each header must be a Hash with name and value" unless header.is_a?(Hash)
+
+          header = Serializer.to_api(header)
+          name = header["Name"].to_s
+          value = header["Value"].to_s
+          if name.match?(/[\r\n:\0]/) || name.strip.empty? || value.match?(/[\r\n\0]/)
+            raise ArgumentError, "Invalid header #{name.inspect}"
+          end
+
+          { "Name" => name, "Value" => value }
+        end
+      end
+
+      # Hash attachments must already carry Base64 content; use Haskimail::Attachment for raw bytes.
+      def normalize_attachments(attachments)
+        Array(attachments).map do |attachment|
+          next attachment.to_h if attachment.is_a?(Attachment)
+          raise ArgumentError, "Each attachment must be a Hash or Haskimail::Attachment" unless attachment.is_a?(Hash)
+
+          if Util.blank?(attachment["Name"]) || Util.blank?(attachment["Content"])
+            raise ArgumentError, "Each attachment needs name and content"
+          end
+
+          Attachment.assert_allowed!(attachment["Name"])
+          assert_base64!(attachment)
+          content_id = Attachment.normalize_content_id(attachment["ContentID"])
+          content_id ? attachment.merge("ContentID" => content_id) : attachment.except("ContentID")
+        end
+      end
+
+      def assert_base64!(attachment)
+        Base64.strict_decode64(attachment["Content"].to_s)
+      rescue ArgumentError
+        raise ArgumentError, "Attachment #{attachment['Name'].inspect}: Content must be strict Base64 " \
+                             "(use Haskimail::Attachment to pass raw bytes)"
+      end
+    end
+  end
+end

data/lib/haskimail/resources/inbound_rules.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Inbound block rules: https://haskimail.ru/developer/api/inbound-rules-triggers-api
+    class InboundRules < Base
+      DEFAULT_PAGE_SIZE = 100
+      MAX_PAGE_SIZE = 500
+
+      # @return [Hash] { total_count:, inbound_rules: [{ id:, rule: }] }
+      def list(count: DEFAULT_PAGE_SIZE, offset: 0)
+        api_get(path(:triggers, :inboundrules), pagination_query(count, offset, max_count: MAX_PAGE_SIZE))
+      end
+
+      def each(page_size: DEFAULT_PAGE_SIZE, &block)
+        iterate(:inbound_rules, page_size, nil, block, max_page_size: MAX_PAGE_SIZE) do |count, offset|
+          list(count: count, offset: offset)
+        end
+      end
+
+      # @param rule [String] an email address ("spam@example.com") or a domain ("example.org")
+      # @return [Hash] { id:, rule: }
+      def create(rule)
+        require_value!(:rule, rule)
+        api_post(path(:triggers, :inboundrules), { "Rule" => rule.to_s.strip })
+      end
+
+      def delete(rule_id)
+        api_delete(path(:triggers, :inboundrules, rule_id))
+      end
+    end
+  end
+end

data/lib/haskimail/resources/message_streams.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Message streams (channels): https://haskimail.ru/developer/api/message-streams-api
+    class MessageStreams < Base
+      CREATABLE_TYPES = %w[Transactional Broadcasts].freeze
+
+      # @return [Hash] { total_count:, message_streams: [...] } (archived streams included)
+      def list
+        api_get(path(:"message-streams"))
+      end
+
+      def get(stream_id)
+        api_get(path(:"message-streams", stream_id))
+      end
+
+      # @param message_stream_type ["Transactional", "Broadcasts"] (case-insensitive)
+      # @param server_id [Integer, nil] required only when called with an account token
+      def create(name:, message_stream_type:, server_id: nil)
+        require_value!(:name, name)
+        type = CREATABLE_TYPES.find { |candidate| candidate.casecmp?(message_stream_type.to_s) }
+        raise ArgumentError, "message_stream_type must be one of: #{CREATABLE_TYPES.join(', ')}" unless type
+
+        api_post(path(:"message-streams"),
+                 Util.compact("ServerID" => server_id, "Name" => name, "MessageStreamType" => type))
+      end
+
+      # Only the name can be changed.
+      def update(stream_id, name:)
+        require_value!(:name, name)
+        api_patch(path(:"message-streams", stream_id), { "Name" => name })
+      end
+
+      # Stops sending through the stream. It is purged 45 days later unless unarchived.
+      # @return [Hash] { id:, server_id:, archived_at:, expected_purge_date: }
+      def archive(stream_id)
+        Serializer.from_api(connection.post(path(:"message-streams", stream_id, :archive), nil, idempotent: true))
+      end
+
+      def unarchive(stream_id)
+        Serializer.from_api(connection.post(path(:"message-streams", stream_id, :unarchive), nil, idempotent: true))
+      end
+    end
+  end
+end