escalated 0.4.0

data/lib/escalated/mail/adapters/imap_adapter.rb

@@ -0,0 +1,209 @@
+require "net/imap"
+
+module Escalated
+  module Mail
+    module Adapters
+      class ImapAdapter < BaseAdapter
+        # The IMAP adapter does not parse HTTP requests.
+        # Instead, it provides methods to poll an IMAP mailbox.
+        #
+        # @param request [ActionDispatch::Request] unused for IMAP
+        # @return [nil]
+        def parse_request(request)
+          raise NotImplementedError,
+            "ImapAdapter does not support webhook parsing. Use #fetch_messages instead."
+        end
+
+        # IMAP does not use webhook verification.
+        def verify_request(request)
+          false
+        end
+
+        # Connect to the configured IMAP server and fetch unread messages.
+        #
+        # @return [Array<Escalated::Mail::InboundMessage>]
+        def fetch_messages
+          messages = []
+          config = imap_config
+
+          imap = connect(config)
+          return messages unless imap
+
+          begin
+            imap.login(config[:username], config[:password])
+            imap.select(config[:mailbox])
+
+            # Search for unseen (unread) messages
+            uids = imap.uid_search(["UNSEEN"])
+
+            uids.each do |uid|
+              message = fetch_message(imap, uid)
+              messages << message if message
+            end
+          rescue Net::IMAP::Error => e
+            Rails.logger.error("[Escalated::ImapAdapter] IMAP error: #{e.message}")
+          ensure
+            begin
+              imap.logout
+              imap.disconnect
+            rescue StandardError
+              # Ignore disconnect errors
+            end
+          end
+
+          messages
+        end
+
+        # Mark a message as seen/read on the IMAP server.
+        #
+        # @param uid [Integer] the UID of the message to mark
+        def mark_as_read(uid)
+          config = imap_config
+          imap = connect(config)
+          return unless imap
+
+          begin
+            imap.login(config[:username], config[:password])
+            imap.select(config[:mailbox])
+            imap.uid_store(uid, "+FLAGS", [:Seen])
+          rescue Net::IMAP::Error => e
+            Rails.logger.error("[Escalated::ImapAdapter] Failed to mark message #{uid} as read: #{e.message}")
+          ensure
+            begin
+              imap.logout
+              imap.disconnect
+            rescue StandardError
+              # Ignore disconnect errors
+            end
+          end
+        end
+
+        private
+
+        def imap_config
+          config = Escalated.configuration
+          {
+            host: config.imap_host,
+            port: config.imap_port || 993,
+            encryption: config.imap_encryption || :ssl,
+            username: config.imap_username,
+            password: config.imap_password,
+            mailbox: config.imap_mailbox || "INBOX"
+          }
+        end
+
+        def connect(config)
+          return nil if config[:host].blank? || config[:username].blank? || config[:password].blank?
+
+          ssl = config[:encryption] == :ssl || config[:encryption] == :tls
+          Net::IMAP.new(config[:host], port: config[:port], ssl: ssl)
+        rescue SocketError, Errno::ECONNREFUSED, Net::IMAP::Error => e
+          Rails.logger.error("[Escalated::ImapAdapter] Connection failed: #{e.message}")
+          nil
+        end
+
+        def fetch_message(imap, uid)
+          fetch_data = imap.uid_fetch(uid, ["ENVELOPE", "BODY[TEXT]", "BODY[HEADER]", "RFC822"])
+          return nil unless fetch_data&.first
+
+          data = fetch_data.first
+          envelope = data.attr["ENVELOPE"]
+          raw_body = data.attr["BODY[TEXT]"] || ""
+          raw_headers = data.attr["BODY[HEADER]"] || ""
+          rfc822 = data.attr["RFC822"] || ""
+
+          from = envelope.from&.first
+          to = envelope.to&.first
+
+          from_email = from ? "#{from.mailbox}@#{from.host}" : nil
+          from_name = from&.name
+          to_email = to ? "#{to.mailbox}@#{to.host}" : nil
+
+          # Parse headers for In-Reply-To and References
+          headers = parse_raw_headers(raw_headers)
+
+          # Extract plain text body
+          body_text, body_html = extract_body_parts(rfc822)
+
+          message = InboundMessage.new(
+            from_email: from_email,
+            from_name: from_name,
+            to_email: to_email,
+            subject: envelope.subject || "(no subject)",
+            body_text: body_text.presence || raw_body,
+            body_html: body_html,
+            message_id: envelope.message_id,
+            in_reply_to: envelope.in_reply_to,
+            references: parse_references(headers["References"]),
+            headers: headers,
+            attachments: []
+          )
+
+          # Mark the message as seen after successful fetch
+          imap.uid_store(uid, "+FLAGS", [:Seen])
+
+          message
+        rescue StandardError => e
+          Rails.logger.error("[Escalated::ImapAdapter] Failed to fetch message #{uid}: #{e.message}")
+          nil
+        end
+
+        def parse_raw_headers(raw_headers)
+          return {} if raw_headers.blank?
+
+          headers = {}
+          current_key = nil
+          current_value = nil
+
+          raw_headers.each_line do |line|
+            if line =~ /\A(\S+):\s*(.*)/
+              headers[current_key] = current_value.strip if current_key
+              current_key = $1
+              current_value = $2
+            elsif line =~ /\A\s+(.*)/
+              # Continuation of previous header
+              current_value = "#{current_value} #{$1}" if current_key
+            end
+          end
+
+          headers[current_key] = current_value.strip if current_key
+          headers
+        end
+
+        def extract_body_parts(rfc822)
+          return ["", nil] if rfc822.blank?
+
+          # Simple MIME extraction — for production, use the `mail` gem
+          # This handles the common case of plain text emails
+          body_text = ""
+          body_html = nil
+
+          # Check for multipart boundary
+          if rfc822 =~ /Content-Type:.*?boundary="?([^";\s]+)"?/mi
+            boundary = $1
+            parts = rfc822.split("--#{boundary}")
+
+            parts.each do |part|
+              if part =~ /Content-Type:\s*text\/plain/i
+                body_text = extract_part_body(part)
+              elsif part =~ /Content-Type:\s*text\/html/i
+                body_html = extract_part_body(part)
+              end
+            end
+          else
+            # No multipart — treat the whole body as text
+            body_text = rfc822.sub(/\A.*?\r?\n\r?\n/m, "")
+          end
+
+          [body_text, body_html]
+        end
+
+        def extract_part_body(part)
+          # Skip headers, extract body after blank line
+          body = part.sub(/\A.*?\r?\n\r?\n/m, "")
+          body&.strip || ""
+        end
+      end
+    end
+  end
+end

data/lib/escalated/mail/adapters/mailgun_adapter.rb

@@ -0,0 +1,93 @@
+require "openssl"
+
+module Escalated
+  module Mail
+    module Adapters
+      class MailgunAdapter < BaseAdapter
+        # Parse a Mailgun inbound webhook into an InboundMessage.
+        #
+        # Mailgun POSTs multipart form data with fields:
+        #   sender, from, recipient, subject, body-plain, body-html,
+        #   Message-Id, In-Reply-To, References, message-headers, etc.
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Escalated::Mail::InboundMessage]
+        def parse_request(request)
+          params = request.params
+
+          from_name, from_email = parse_from(params)
+
+          InboundMessage.new(
+            from_email: from_email,
+            from_name: from_name,
+            to_email: safe_param(params, "recipient"),
+            subject: safe_param(params, "subject", "(no subject)"),
+            body_text: safe_param(params, "body-plain"),
+            body_html: safe_param(params, "body-html"),
+            message_id: safe_param(params, "Message-Id"),
+            in_reply_to: safe_param(params, "In-Reply-To"),
+            references: parse_references(safe_param(params, "References")),
+            headers: parse_headers(safe_param(params, "message-headers")),
+            attachments: []
+          )
+        end
+
+        # Verify the Mailgun webhook signature.
+        #
+        # Mailgun sends: timestamp, token, signature
+        # Signature = HMAC-SHA256(timestamp + token, signing_key)
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Boolean]
+        def verify_request(request)
+          signing_key = Escalated.configuration.mailgun_signing_key
+          return true if signing_key.blank? # Skip verification if no key configured
+
+          params = request.params
+          timestamp = params["timestamp"].to_s
+          token = params["token"].to_s
+          signature = params["signature"].to_s
+
+          return false if timestamp.blank? || token.blank? || signature.blank?
+
+          # Reject timestamps older than 5 minutes
+          if (Time.current.to_i - timestamp.to_i).abs > 300
+            Rails.logger.warn("[Escalated::MailgunAdapter] Webhook timestamp too old: #{timestamp}")
+            return false
+          end
+
+          expected = OpenSSL::HMAC.hexdigest("SHA256", signing_key, "#{timestamp}#{token}")
+          ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+        end
+
+        private
+
+        def parse_from(params)
+          from_field = safe_param(params, "from")
+          if from_field
+            parse_email_address(from_field)
+          else
+            [nil, safe_param(params, "sender")]
+          end
+        end
+
+        def parse_headers(headers_json)
+          return {} if headers_json.blank?
+
+          parsed = begin
+            JSON.parse(headers_json)
+          rescue JSON::ParserError
+            []
+          end
+
+          # Mailgun sends headers as [[key, value], [key, value], ...]
+          if parsed.is_a?(Array)
+            parsed.each_with_object({}) { |pair, hash| hash[pair[0]] = pair[1] if pair.is_a?(Array) && pair.size >= 2 }
+          else
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/escalated/mail/adapters/postmark_adapter.rb

@@ -0,0 +1,94 @@
+module Escalated
+  module Mail
+    module Adapters
+      class PostmarkAdapter < BaseAdapter
+        # Parse a Postmark inbound webhook into an InboundMessage.
+        #
+        # Postmark POSTs JSON with fields:
+        #   From, FromName, FromFull, To, ToFull, Subject, TextBody, HtmlBody,
+        #   MessageID, Headers, Attachments, etc.
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Escalated::Mail::InboundMessage]
+        def parse_request(request)
+          params = request.params
+
+          from_email = extract_from_email(params)
+          from_name = extract_from_name(params)
+          to_email = extract_to_email(params)
+          headers = extract_headers(params)
+
+          InboundMessage.new(
+            from_email: from_email,
+            from_name: from_name,
+            to_email: to_email,
+            subject: safe_param(params, "Subject", "(no subject)"),
+            body_text: safe_param(params, "TextBody"),
+            body_html: safe_param(params, "HtmlBody"),
+            message_id: safe_param(params, "MessageID"),
+            in_reply_to: headers["In-Reply-To"],
+            references: parse_references(headers["References"]),
+            headers: headers,
+            attachments: []
+          )
+        end
+
+        # Verify the Postmark inbound webhook.
+        #
+        # Postmark doesn't send a signature by default, but you can verify
+        # the inbound token matches the configured one.
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Boolean]
+        def verify_request(request)
+          token = Escalated.configuration.postmark_inbound_token.presence || Escalated::EscalatedSetting.get('postmark_inbound_token')
+          if token.blank?
+            Rails.logger.warn('Escalated: Postmark inbound token not configured — rejecting request.')
+            return false
+          end
+
+          request_token = request.headers['X-Postmark-Token'].to_s
+          ActiveSupport::SecurityUtils.secure_compare(request_token, token)
+        end
+
+        private
+
+        def extract_from_email(params)
+          from_full = params["FromFull"]
+          if from_full.is_a?(Hash)
+            from_full["Email"]
+          else
+            safe_param(params, "From")&.then { |f| parse_email_address(f).last }
+          end
+        end
+
+        def extract_from_name(params)
+          from_full = params["FromFull"]
+          if from_full.is_a?(Hash)
+            from_full["Name"].presence
+          else
+            safe_param(params, "FromName")
+          end
+        end
+
+        def extract_to_email(params)
+          to_full = params["ToFull"]
+          if to_full.is_a?(Array) && to_full.first.is_a?(Hash)
+            to_full.first["Email"]
+          else
+            safe_param(params, "To")&.then { |t| parse_email_address(t).last }
+          end
+        end
+
+        def extract_headers(params)
+          raw_headers = params["Headers"]
+          return {} unless raw_headers.is_a?(Array)
+
+          raw_headers.each_with_object({}) do |header, hash|
+            hash[header["Name"]] = header["Value"] if header.is_a?(Hash)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/escalated/mail/adapters/ses_adapter.rb

@@ -0,0 +1,179 @@
+require "json"
+require "base64"
+
+module Escalated
+  module Mail
+    module Adapters
+      class SesAdapter < BaseAdapter
+        # Parse an AWS SES/SNS inbound notification into an InboundMessage.
+        #
+        # SES sends notifications via SNS. The SNS message contains either:
+        # 1. A SubscriptionConfirmation (must be confirmed)
+        # 2. A Notification with the email content in the "Message" field
+        #
+        # The SES notification message contains:
+        #   mail.source, mail.destination, mail.headers, mail.subject,
+        #   content (base64 or S3 reference)
+        #
+        # For simplicity, this adapter handles the SNS notification format
+        # where SES includes parsed email data.
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Escalated::Mail::InboundMessage, nil]
+        def parse_request(request)
+          body = parse_sns_body(request)
+          return nil unless body
+
+          sns_type = body["Type"]
+
+          # Handle SNS subscription confirmation
+          if sns_type == "SubscriptionConfirmation"
+            confirm_subscription(body)
+            return nil
+          end
+
+          # Handle notification
+          return nil unless sns_type == "Notification"
+
+          ses_message = parse_ses_message(body["Message"])
+          return nil unless ses_message
+
+          build_inbound_message(ses_message)
+        end
+
+        # Verify the SNS message signature.
+        #
+        # @param request [ActionDispatch::Request]
+        # @return [Boolean]
+        def verify_request(request)
+          topic_arn = Escalated.configuration.ses_topic_arn
+          if topic_arn.blank?
+            Rails.logger.warn('Escalated: SES Topic ARN not configured — rejecting request.')
+            return false
+          end
+
+          body = parse_sns_body(request)
+          return false unless body
+
+          # Verify the TopicArn matches
+          message_topic_arn = body["TopicArn"]
+          return false unless message_topic_arn == topic_arn
+
+          # SNS signature verification can be implemented here.
+          # For production, you should verify the SigningCertURL, download
+          # the certificate, and verify the Signature field.
+          # For now, we verify the TopicArn match.
+          true
+        end
+
+        private
+
+        def parse_sns_body(request)
+          raw_body = request.raw_post
+          JSON.parse(raw_body)
+        rescue JSON::ParserError => e
+          Rails.logger.error("[Escalated::SesAdapter] Failed to parse SNS body: #{e.message}")
+          nil
+        end
+
+        def confirm_subscription(body)
+          subscribe_url = body["SubscribeURL"]
+
+          unless subscribe_url.present? && valid_sns_url?(subscribe_url)
+            Rails.logger.warn("Escalated: Rejected SNS SubscribeURL — not a valid Amazon SNS URL. url=#{subscribe_url}")
+            return
+          end
+
+          Rails.logger.info("[Escalated::SesAdapter] Confirming SNS subscription: #{subscribe_url}")
+          Thread.new do
+            begin
+              uri = URI.parse(subscribe_url)
+              Net::HTTP.get(uri)
+            rescue StandardError => e
+              Rails.logger.error("[Escalated::SesAdapter] Failed to confirm subscription: #{e.message}")
+            end
+          end
+        end
+
+        def valid_sns_url?(url)
+          return false if url.blank?
+
+          uri = URI.parse(url)
+          uri.scheme == 'https' && uri.host.match?(/\Asns\.[a-z0-9-]+\.amazonaws\.com\z/)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def parse_ses_message(message_string)
+          return nil if message_string.blank?
+
+          JSON.parse(message_string)
+        rescue JSON::ParserError => e
+          Rails.logger.error("[Escalated::SesAdapter] Failed to parse SES message: #{e.message}")
+          nil
+        end
+
+        def build_inbound_message(ses_message)
+          mail_data = ses_message["mail"] || {}
+          receipt_data = ses_message["receipt"] || {}
+          content = ses_message["content"]
+
+          headers = extract_headers(mail_data)
+          from_email = mail_data.dig("source") || headers["From"]
+          from_name = nil
+
+          # Parse the From header for a display name
+          if headers["From"].present?
+            from_name, parsed_email = parse_email_address(headers["From"])
+            from_email = parsed_email if parsed_email.present?
+          end
+
+          to_email = Array(mail_data["destination"]).first || headers["To"]
+          if to_email.present?
+            _, to_email = parse_email_address(to_email)
+          end
+
+          # Extract body from content (if raw email is provided)
+          body_text, body_html = extract_body(content)
+
+          InboundMessage.new(
+            from_email: from_email,
+            from_name: from_name,
+            to_email: to_email,
+            subject: headers["Subject"] || mail_data.dig("commonHeaders", "subject") || "(no subject)",
+            body_text: body_text,
+            body_html: body_html,
+            message_id: mail_data["messageId"] || headers["Message-ID"],
+            in_reply_to: headers["In-Reply-To"],
+            references: parse_references(headers["References"]),
+            headers: headers,
+            attachments: []
+          )
+        end
+
+        def extract_headers(mail_data)
+          raw_headers = mail_data["headers"]
+          return {} unless raw_headers.is_a?(Array)
+
+          raw_headers.each_with_object({}) do |header, hash|
+            hash[header["name"]] = header["value"] if header.is_a?(Hash)
+          end
+        end
+
+        def extract_body(content)
+          return ["", nil] if content.blank?
+
+          # If content is a raw MIME message (base64 encoded), do basic extraction
+          # For production, consider using the `mail` gem for robust MIME parsing
+          if content.is_a?(String)
+            # Try to find text/plain and text/html parts from a raw email
+            # This is a simplified parser; production should use the `mail` gem
+            [content, nil]
+          else
+            ["", nil]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/escalated/mail/inbound_message.rb

@@ -0,0 +1,78 @@
+module Escalated
+  module Mail
+    class InboundMessage
+      attr_accessor :from_email, :from_name, :to_email, :subject,
+                    :body_text, :body_html, :message_id, :in_reply_to,
+                    :references, :headers, :attachments
+
+      def initialize(**attrs)
+        @from_email = attrs[:from_email]
+        @from_name = attrs[:from_name]
+        @to_email = attrs[:to_email]
+        @subject = attrs[:subject]
+        @body_text = attrs[:body_text]
+        @body_html = attrs[:body_html]
+        @message_id = attrs[:message_id]
+        @in_reply_to = attrs[:in_reply_to]
+        @references = attrs[:references] || []
+        @headers = attrs[:headers] || {}
+        @attachments = attrs[:attachments] || []
+      end
+
+      # Extract ticket reference from subject line (e.g., "Re: [ESC-2602-ABC123] Original subject")
+      def ticket_reference
+        match = subject&.match(/\[([A-Z0-9]+-\d{4}-[A-Z0-9]+)\]/)
+        match ? match[1] : nil
+      end
+
+      # Strip the ticket reference tag from the subject for display
+      def clean_subject
+        return subject unless subject
+
+        subject.gsub(/\s*\[[A-Z0-9]+-\d{4}-[A-Z0-9]+\]\s*/, "")
+          .gsub(/\A\s*(Re|Fwd|Fw):\s*/i, "")
+          .strip
+      end
+
+      # Determine the best body content to use as reply/description text
+      def body
+        if body_text.present?
+          body_text.strip
+        elsif body_html.present?
+          strip_html(body_html).strip
+        else
+          ""
+        end
+      end
+
+      def valid?
+        from_email.present? && to_email.present? && subject.present?
+      end
+
+      def reply?
+        in_reply_to.present? || ticket_reference.present?
+      end
+
+      def raw_headers_string
+        return "" if headers.blank?
+
+        headers.map { |k, v| "#{k}: #{v}" }.join("\n")
+      end
+
+      private
+
+      def strip_html(html)
+        # Basic HTML tag stripping — production systems may want a proper sanitizer
+        text = html.gsub(/<br\s*\/?>|<\/p>|<\/div>|<\/li>/i, "\n")
+        text = text.gsub(/<[^>]+>/, "")
+        text = text.gsub(/&nbsp;/i, " ")
+        text = text.gsub(/&amp;/i, "&")
+        text = text.gsub(/&lt;/i, "<")
+        text = text.gsub(/&gt;/i, ">")
+        text = text.gsub(/&quot;/i, '"')
+        text = text.gsub(/&#39;/i, "'")
+        text.gsub(/\n{3,}/, "\n\n")
+      end
+    end
+  end
+end

data/lib/escalated/manager.rb

@@ -0,0 +1,33 @@
+require "escalated/drivers/local_driver"
+require "escalated/drivers/synced_driver"
+require "escalated/drivers/cloud_driver"
+
+module Escalated
+  class Manager
+    class << self
+      def driver
+        @driver ||= resolve_driver
+      end
+
+      def reset_driver!
+        @driver = nil
+      end
+
+      private
+
+      def resolve_driver
+        case Escalated.configuration.mode
+        when :self_hosted
+          Drivers::LocalDriver.new
+        when :synced
+          Drivers::SyncedDriver.new
+        when :cloud
+          Drivers::CloudDriver.new
+        else
+          raise ArgumentError, "Unknown Escalated mode: #{Escalated.configuration.mode}. " \
+                               "Valid modes are :self_hosted, :synced, :cloud"
+        end
+      end
+    end
+  end
+end