haskimail-rails 1.0.0

data/lib/haskimail/util.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "erb"
+
+module Haskimail
+  # Small, dependency-free helpers shared across the library.
+  module Util
+    MOSCOW_OFFSET = "+03:00" # Moscow has no DST since 2014; the API works in MSK.
+
+    module_function
+
+    # "8f3e0c7a-5b2d-..." -> "8f3e…2a94". Never prints a full secret.
+    def redact(secret)
+      return nil if secret.nil?
+
+      str = secret.to_s
+      return "[REDACTED]" if str.length < 12
+
+      "#{str[0, 4]}…#{str[-4, 4]}"
+    end
+
+    # Encodes a single path segment so that IDs and template aliases cannot
+    # change the request path ("/", "?", "#", "..", spaces, Cyrillic, ...).
+    def escape_path_segment(value)
+      segment = value.to_s
+      raise ArgumentError, "Path parameter must not be blank" if segment.strip.empty?
+      raise ArgumentError, "Invalid path parameter: #{segment.inspect}" if %w[. ..].include?(segment)
+
+      ERB::Util.url_encode(segment)
+    end
+
+    # Header values must not contain CR/LF (header injection) or be blank.
+    def validate_token!(token, name)
+      str = token.to_s
+      raise ConfigurationError, "#{name} is not set" if str.strip.empty?
+      raise ConfigurationError, "#{name} contains illegal characters" if str.match?(/[\r\n\0]/)
+
+      str
+    end
+
+    # Date-only API filter: "2026-10-01" (Moscow date).
+    def format_date(value)
+      case value
+      when nil then nil
+      when String then validate_date_string!(value, date_only: true)
+      when DateTime, Time then to_moscow(value).strftime("%Y-%m-%d")
+      when Date then value.strftime("%Y-%m-%d")
+      else
+        return format_date(value.to_time) if value.respond_to?(:to_time)
+
+        raise ArgumentError, "Expected a Date, Time or String, got #{value.class}"
+      end
+    end
+
+    # Date-time API filter: "2026-10-01 12:00:00" (or with "T" for inbound search).
+    def format_datetime(value, separator: " ")
+      case value
+      when nil then nil
+      when String then validate_date_string!(value)
+      when DateTime, Time then to_moscow(value).strftime("%Y-%m-%d#{separator}%H:%M:%S")
+      when Date then value.strftime("%Y-%m-%d")
+      else
+        return format_datetime(value.to_time, separator: separator) if value.respond_to?(:to_time)
+
+        raise ArgumentError, "Expected a Date, Time or String, got #{value.class}"
+      end
+    end
+
+    def to_moscow(value)
+      value.to_time.getlocal(MOSCOW_OFFSET)
+    end
+
+    DATE_STRING = /\A(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?\z/
+
+    # Accepts "YYYY-MM-DD" and, unless date_only, "YYYY-MM-DD HH:MM[:SS]" (or with "T").
+    def validate_date_string!(value, date_only: false)
+      match = DATE_STRING.match(value)
+      valid = match && Date.valid_date?(match[1].to_i, match[2].to_i, match[3].to_i) &&
+              (match[4].nil? || (!date_only && match[4].to_i < 24 && match[5].to_i < 60 && match[6].to_i < 60))
+      return value if valid
+
+      raise ArgumentError,
+            "Invalid date #{value.inspect}, expected #{date_only ? 'YYYY-MM-DD' : 'YYYY-MM-DD[ HH:MM:SS]'}"
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) || (value.is_a?(String) && value.strip.empty?)
+    end
+
+    # Drops nil values from a flat hash.
+    def compact(hash)
+      hash.compact
+    end
+
+    def assert_known_keys!(given, allowed, context)
+      unknown = given.map(&:to_sym) - allowed
+      return if unknown.empty?
+
+      raise ArgumentError, "Unknown #{context} option(s): #{unknown.join(', ')}. Allowed: #{allowed.join(', ')}"
+    end
+
+    def assert_range!(name, value, range)
+      return if value.nil?
+      raise ArgumentError, "#{name} must be an Integer" unless value.is_a?(Integer)
+      raise ArgumentError, "#{name} must be within #{range}, got #{value}" unless range.cover?(value)
+    end
+  end
+end

data/lib/haskimail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Haskimail
+  VERSION = "1.0.0"
+end

data/lib/haskimail/webhooks/endpoint.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Haskimail
+  module Webhooks
+    # A Rack app that receives Haskimail webhooks, authenticates them and hands
+    # parsed events to your code. Mount it in config/routes.rb:
+    #
+    #   mount Haskimail::Webhooks::Endpoint.new(
+    #     signature_key: Rails.application.credentials.dig(:haskimail, :webhook_key),
+    #     username: "haskimail", password: Rails.application.credentials.dig(:haskimail, :webhook_password)
+    #   ) { |event| HaskimailWebhookJob.perform_later(event.to_h) }, at: "/haskimail/webhooks"
+    #
+    # Configure the webhook URL in Haskimail as https://haskimail:PASSWORD@your.app/haskimail/webhooks.
+    #
+    # Every payload is also published via ActiveSupport::Notifications as
+    # "webhook.haskimail" with payload { type:, event: }.
+    #
+    # Security:
+    # * Basic auth is required (it is checked before the body is read).
+    # * signature_key adds a per-event check. Haskimail signs only recipient and
+    #   message_id, so a captured signature can be replayed with another event
+    #   type; that is why signature-only mode needs allow_signature_only: true.
+    # * Inbound emails are not signed, so they are accepted only with Basic auth.
+    #
+    # Responses: 200 handled; 401 bad credentials; 403 bad or missing signature;
+    # 500 when your handler raises. Haskimail retries 5xx for every webhook; for
+    # inbound emails it also retries other non-2xx responses except 403.
+    class Endpoint
+      DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024 # inbound email up to 10 MB, Base64-encoded
+      JSON_HEADERS = { "content-type" => "application/json" }.freeze
+
+      # @param signature_key [String, nil] account webhook key; when set, events without a
+      #   valid `secret` are rejected
+      # @param username [String, nil] Basic auth user; when set, Basic auth is required
+      # @param password [String, nil] Basic auth password
+      # @param logger [#error, nil]
+      # @param allow_signature_only [Boolean] accept events authenticated only by signature_key
+      #   (inbound emails are then rejected)
+      # @param allow_unauthenticated [Boolean] explicitly accept requests without any
+      #   authentication (only for local development)
+      def initialize(signature_key: nil, username: nil, password: nil, max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+                     logger: nil, allow_signature_only: false, allow_unauthenticated: false, &handler)
+        @signature_key = signature_key.to_s.empty? ? nil : Secret.new(signature_key)
+        @username = username.to_s.empty? ? nil : Secret.new(username)
+        @password = password.to_s.empty? ? nil : Secret.new(password)
+        @max_body_bytes = max_body_bytes
+        @logger = logger
+        @allow_signature_only = allow_signature_only
+        @allow_unauthenticated = allow_unauthenticated
+        @handler = handler
+        validate_settings!
+      end
+
+      def call(env)
+        return respond(405, "Method Not Allowed", "allow" => "POST") unless env["REQUEST_METHOD"] == "POST"
+        return unauthorized unless authenticated?(env)
+
+        body = read_body(env)
+        return respond(413, "Payload Too Large") unless body
+
+        payload = Webhooks.parse(body)
+        return respond(403, "Forbidden") unless trusted?(payload)
+
+        dispatch(payload)
+        respond(200, "OK")
+      rescue ParseError
+        respond(400, "Bad Request")
+      rescue StandardError => e
+        @logger&.error("[Haskimail] webhook handler failed: #{e.class}: #{e.message}")
+        respond(500, "Internal Server Error")
+      end
+
+      def inspect
+        "#<#{self.class.name} signed=#{!@signature_key.nil?} basic_auth=#{basic_auth?}>"
+      end
+
+      private
+
+      def validate_settings!
+        if @username.nil? != @password.nil?
+          raise ConfigurationError, "Set both username and password for webhook Basic auth"
+        end
+        unless @max_body_bytes.is_a?(Integer) && @max_body_bytes.positive?
+          raise ConfigurationError, "max_body_bytes must be a positive Integer"
+        end
+        return if basic_auth? || @allow_unauthenticated
+        return if @signature_key && @allow_signature_only
+
+        raise ConfigurationError, "Configure Basic auth (username/password) for the webhook endpoint. " \
+                                  "Signature-only mode needs allow_signature_only: true; " \
+                                  "allow_unauthenticated: true is for local development only"
+      end
+
+      def basic_auth?
+        !@username.nil?
+      end
+
+      def authenticated?(env)
+        return true unless basic_auth?
+
+        Webhooks.valid_basic_auth?(env["HTTP_AUTHORIZATION"], username: @username.reveal, password: @password.reveal)
+      end
+
+      # Events must carry a valid signature when a key is configured. Inbound
+      # emails are unsigned, so they require Basic auth.
+      # A configured signature key is always enforced, even with allow_unauthenticated.
+      def trusted?(payload)
+        if payload.is_a?(Event)
+          @signature_key.nil? || Webhooks.valid_signature?(payload, key: @signature_key.reveal)
+        else
+          basic_auth? || @allow_unauthenticated
+        end
+      end
+
+      def read_body(env)
+        input = env["rack.input"]
+        return "" unless input
+
+        input.rewind if input.respond_to?(:rewind)
+        body = String.new(input.read(@max_body_bytes + 1).to_s)
+        input.rewind if input.respond_to?(:rewind)
+        body.bytesize > @max_body_bytes ? nil : body.force_encoding(Encoding::UTF_8)
+      end
+
+      def dispatch(payload)
+        if defined?(ActiveSupport::Notifications)
+          ActiveSupport::Notifications.instrument("webhook.haskimail", type: payload.type, event: payload) do
+            @handler&.call(payload)
+          end
+        else
+          @handler&.call(payload)
+        end
+      end
+
+      def unauthorized
+        respond(401, "Unauthorized", "www-authenticate" => 'Basic realm="Haskimail webhooks"')
+      end
+
+      def respond(status, message, extra_headers = {})
+        [status, JSON_HEADERS.merge(extra_headers), [JSON.generate(status: message)]]
+      end
+    end
+  end
+end

data/lib/haskimail/webhooks/event.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Haskimail
+  module Webhooks
+    # A delivery, bounce, spam complaint, open, click or subscription change event.
+    class Event
+      TYPES = %i[delivered bounced complained opened clicked subscription_change].freeze
+      BOUNCE_CATEGORIES = { "hrd" => :hard, "sft" => :soft, "blk" => :blocked, "spm" => :spam }.freeze
+      MOSCOW_OFFSET = "+03:00"
+
+      attr_reader :raw
+
+      def initialize(data)
+        @raw = data.transform_keys(&:to_s).freeze
+      end
+
+      # @return [Symbol] :delivered, :bounced, :complained, :opened, :clicked,
+      #   :subscription_change (or the raw value, downcased, for unknown events)
+      def type
+        @type ||= begin
+          value = raw["event"].to_s.downcase
+          value == "subscriptionchange" ? :subscription_change : value.to_sym
+        end
+      end
+
+      TYPES.each do |event_type|
+        define_method(:"#{event_type}?") { type == event_type }
+      end
+
+      def recipient = string("recipient") || string("email")
+      def message_id = raw["message_id"].to_s
+      def tag = string("campaign_id")
+      def server_id = raw["server_id"]&.to_i
+      def stream_id = raw["stream_id"]&.to_s
+      def secret = string("secret")
+
+      # Metadata sent with the message. Haskimail delivers it as a JSON string
+      # (or an object in some events); always returns a Hash.
+      def metadata
+        @metadata ||= begin
+          value = raw["custom_vars"]
+          parsed = value.is_a?(String) && !value.strip.empty? ? JSON.parse(value) : value
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      # @return [Time, nil] event time in UTC
+      def occurred_at
+        @occurred_at ||= if string("event_time_utc")
+                           parse_time(raw["event_time_utc"], "+00:00")
+                         elsif string("event_time")
+                           parse_time(raw["event_time"], MOSCOW_OFFSET)
+                         end
+      end
+
+      # ---- bounced ----
+      def bounce_category = BOUNCE_CATEGORIES[raw["bounce_category"].to_s]
+      def hard_bounce? = bounced? && bounce_category == :hard
+      def soft_bounce? = bounced? && bounce_category == :soft
+      def bounce_code = string("code")
+      def bounce_description = string("description") || string("error")
+
+      # ---- clicked ----
+      def original_url = string("url_original")
+      def clicked_url = string("url_pers")
+
+      # ---- subscription_change ----
+      def suppress_sending? = raw["SuppressSending"].to_s == "true"
+      def suppression_reason = string("SuppressionReason")
+
+      # Haskimail may deliver an event more than once; use this to deduplicate.
+      def idempotency_key
+        [type, message_id, recipient, raw["event_time_utc"] || raw["event_time"], clicked_url || original_url].join(":")
+      end
+
+      def [](key) = raw[key.to_s]
+
+      def to_h = raw.dup
+
+      def inspect
+        "#<#{self.class.name} type=#{type.inspect} message_id=#{message_id.inspect}>"
+      end
+
+      private
+
+      def string(key)
+        value = raw[key]
+        value.nil? || value.to_s.empty? ? nil : value.to_s
+      end
+
+      def parse_time(value, offset)
+        Time.strptime("#{value} #{offset}", "%Y-%m-%d %H:%M:%S %z").utc
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/haskimail/webhooks/inbound_message.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Haskimail
+  module Webhooks
+    # An inbound email posted to the server's InboundHookUrl
+    # (https://haskimail.ru/developer/webhooks/inbound-webhook).
+    class InboundMessage
+      Address = Struct.new(:email, :name, :mailbox_hash, keyword_init: true)
+
+      # Inbound attachment; content is decoded lazily.
+      class Attachment
+        attr_reader :name, :content_type, :content_length, :content_id
+
+        def initialize(data)
+          @name = data["Name"].to_s
+          @content_type = data["ContentType"]
+          @content_length = data["ContentLength"]
+          @content_id = data["ContentID"].to_s
+          @encoded = data["Content"].to_s
+        end
+
+        def inline? = !content_id.empty?
+
+        # @return [String] raw bytes (binary)
+        def read
+          Base64.decode64(@encoded)
+        end
+
+        def inspect
+          "#<#{self.class.name} name=#{name.inspect} content_type=#{content_type.inspect}>"
+        end
+      end
+
+      attr_reader :raw
+
+      def initialize(data)
+        @raw = data.transform_keys(&:to_s).freeze
+      end
+
+      def type = :inbound
+      def message_id = raw["MessageID"]
+      def message_stream = raw["MessageStream"]&.to_s
+      def subject = raw["Subject"]
+      def date = raw["Date"]
+      def tag = raw["Tag"]
+      def mailbox_hash = raw["MailboxHash"]
+      def original_recipient = raw["OriginalRecipient"]
+      def reply_to = raw["ReplyTo"]
+      def text_body = raw["TextBody"]
+      def html_body = raw["HtmlBody"]
+      def stripped_text_reply = raw["StrippedTextReply"]
+      def raw_email = raw["RawEmail"]
+
+      def from
+        full = raw["FromFull"]
+        full.is_a?(Hash) ? address(full) : Address.new(email: raw["From"], name: raw["FromName"], mailbox_hash: nil)
+      end
+
+      def to = addresses("ToFull")
+      def cc = addresses("CcFull")
+      def bcc = addresses("BccFull")
+
+      # @return [Array<Hash>] [{ "Name" => ..., "Value" => ... }]
+      def headers = Array(raw["Headers"])
+
+      # Case-insensitive lookup of the first header with this name.
+      def header(name)
+        headers.find { |header| header["Name"].to_s.casecmp?(name.to_s) }&.fetch("Value", nil)
+      end
+
+      def spam_score
+        value = header("X-Spam-Score")
+        value && Float(value, exception: false)
+      end
+
+      def attachments
+        @attachments ||= Array(raw["Attachments"]).map { |data| Attachment.new(data) }
+      end
+
+      def [](key) = raw[key.to_s]
+      def to_h = raw.dup
+
+      def inspect
+        "#<#{self.class.name} message_id=#{message_id.inspect} attachments=#{attachments.size}>"
+      end
+
+      private
+
+      def addresses(key)
+        Array(raw[key]).map { |data| address(data) }
+      end
+
+      def address(data)
+        Address.new(email: data["Email"], name: data["Name"], mailbox_hash: data["MailboxHash"])
+      end
+    end
+  end
+end

data/lib/haskimail/webhooks.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "digest"
+
+require_relative "webhooks/event"
+require_relative "webhooks/inbound_message"
+require_relative "webhooks/endpoint"
+
+module Haskimail
+  # Parsing and verification of incoming webhook requests
+  # (https://haskimail.ru/developer/webhooks/webhooks-overview).
+  #
+  #   event = Haskimail::Webhooks.parse(request.raw_post)
+  #   Haskimail::Webhooks.verify_signature!(event, key: ENV["HASKIMAIL_WEBHOOK_KEY"])
+  #   case event
+  #   when Haskimail::Webhooks::Event          then event.bounced? ...
+  #   when Haskimail::Webhooks::InboundMessage then event.stripped_text_reply ...
+  #   end
+  module Webhooks
+    class ParseError < Error; end
+
+    module_function
+
+    # @param payload [String, Hash] raw JSON body or an already parsed Hash
+    # @return [Event, InboundMessage]
+    def parse(payload)
+      data = payload.is_a?(String) ? JSON.parse(payload) : payload
+      raise ParseError, "Webhook payload must be a JSON object" unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      return Event.new(data) if data.key?("event")
+      return InboundMessage.new(data) if data.key?("MessageID") || data.key?("FromFull")
+
+      raise ParseError, "Unrecognized Haskimail webhook payload"
+    rescue JSON::ParserError => e
+      raise ParseError, "Invalid JSON in webhook payload: #{e.message}"
+    end
+
+    # MD5(recipient + message_id + key), as documented by Haskimail. Compared in
+    # constant time. Inbound webhooks are not signed — protect them with Basic auth.
+    #
+    # Note: the upstream scheme signs only recipient and message_id, so a captured
+    # secret can be replayed with another event type. Use Basic auth as well.
+    def valid_signature?(event, key:)
+      event = parse(event) unless event.is_a?(Event) || event.is_a?(InboundMessage)
+      return false unless event.is_a?(Event)
+
+      secret = event.secret.to_s.downcase
+      return false if key.to_s.empty? || secret.empty?
+
+      expected = Digest::MD5.hexdigest("#{event.recipient}#{event.message_id}#{key}")
+      secure_compare(expected, secret)
+    end
+
+    # @return [Event] the parsed, verified event
+    # @raise [WebhookVerificationError]
+    def verify_signature!(event, key:)
+      event = parse(event) unless event.is_a?(Event) || event.is_a?(InboundMessage)
+      raise WebhookVerificationError, "Invalid Haskimail webhook signature" unless valid_signature?(event, key: key)
+
+      event
+    end
+
+    # Checks an "Authorization: Basic ..." header against expected credentials.
+    def valid_basic_auth?(authorization, username:, password:)
+      scheme, encoded = authorization.to_s.split(" ", 2)
+      return false unless scheme&.casecmp?("basic") && encoded
+
+      given_user, given_password = encoded.unpack1("m").split(":", 2)
+      # Evaluate both comparisons so timing does not reveal which part was wrong.
+      user_ok = secure_compare(Digest::SHA256.hexdigest(given_user.to_s), Digest::SHA256.hexdigest(username.to_s))
+      password_ok = secure_compare(Digest::SHA256.hexdigest(given_password.to_s),
+                                   Digest::SHA256.hexdigest(password.to_s))
+      user_ok & password_ok
+    end
+
+    def secure_compare(left, right)
+      left = left.to_s
+      right = right.to_s
+      return false unless left.bytesize == right.bytesize
+
+      OpenSSL.fixed_length_secure_compare(left, right)
+    end
+  end
+end

data/lib/haskimail-rails.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "haskimail"
+require "mail"
+require "active_support"
+require "active_support/lazy_load_hooks"
+require_relative "haskimail/rails/message_options"
+require_relative "haskimail/rails/mail_converter"
+require_relative "haskimail/rails/delivery_method"
+require_relative "haskimail/rails/mailer_helpers"
+
+Mail::Message.include(Haskimail::Rails::MailExtension)
+
+ActiveSupport.on_load(:action_mailer) do
+  add_delivery_method :haskimail, Haskimail::Rails::DeliveryMethod
+  include Haskimail::Rails::MailerHelpers
+end
+
+require_relative "haskimail/rails/railtie" if defined?(Rails::Railtie)

data/lib/haskimail.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "haskimail/version"
+require_relative "haskimail/errors"
+require_relative "haskimail/util"
+require_relative "haskimail/secret"
+require_relative "haskimail/configuration"
+require_relative "haskimail/serializer"
+require_relative "haskimail/response_handler"
+require_relative "haskimail/connection"
+require_relative "haskimail/paginator"
+require_relative "haskimail/attachment"
+require_relative "haskimail/resources/base"
+require_relative "haskimail/resources/emails"
+require_relative "haskimail/resources/templates"
+require_relative "haskimail/resources/messages"
+require_relative "haskimail/resources/bounces"
+require_relative "haskimail/resources/message_streams"
+require_relative "haskimail/resources/stats"
+require_relative "haskimail/resources/webhooks"
+require_relative "haskimail/resources/inbound_rules"
+require_relative "haskimail/resources/suppressions"
+require_relative "haskimail/resources/servers"
+require_relative "haskimail/resources/domains"
+require_relative "haskimail/resources/account_templates"
+require_relative "haskimail/clients"
+require_relative "haskimail/webhooks"
+
+# Ruby SDK for the Haskimail transactional email API (https://haskimail.ru/developer).
+module Haskimail
+  # Send-only test token: the API validates the request but sends nothing.
+  TEST_TOKEN = "HASKIMAIL_API_TEST"
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # @return [Haskimail::ServerClient] built from the global configuration
+    def server_client(token = nil, **options)
+      ServerClient.new(token, **options)
+    end
+
+    # @return [Haskimail::AccountClient] built from the global configuration
+    def account_client(token = nil, **options)
+      AccountClient.new(token, **options)
+    end
+  end
+end