emailfuse 0.1.3 → 0.2.0

data/lib/email_fuse/mailer.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "email_fuse"
+
+module EmailFuse
+  # Mailer class used by railtie
+  class Mailer
+    attr_accessor :config, :settings
+
+    # These are set as `headers` by the Rails API, but these will be filtered out
+    # when constructing the EmailFuse API payload, since they're are sent as post params.
+    # https://resend.com/docs/api-reference/emails/send-email
+    IGNORED_HEADERS = %w[
+      cc bcc
+      from reply-to to subject mime-version
+      html text
+      content-type tags scheduled_at
+      headers options
+    ].freeze
+
+    SUPPORTED_OPTIONS = %w[idempotency_key].freeze
+
+    def initialize(config)
+      @config = config
+      @settings = config.is_a?(Hash) ? config : {}
+
+      # Check for API key in settings first, then fall back to global config
+      raise EmailFuse::Error.new("Make sure your API Key is set", @config) unless api_key
+    end
+
+    # Returns the API key from settings or global config
+    def api_key
+      @settings[:api_key] || EmailFuse.api_key
+    end
+
+    # Returns the base URL from settings or global config
+    def base_url
+      @settings[:host] || @settings[:base_url] || EmailFuse.base_url
+    end
+
+    #
+    # Overwritten deliver! method
+    #
+    # @param Mail mail
+    #
+    # @return Object resend response
+    #
+    def deliver!(mail)
+      params = build_resend_params(mail)
+      options = get_options(mail) if mail[:options].present?
+      options ||= {}
+
+      # Pass api_key and base_url from settings to the request
+      options[:api_key] = api_key
+      options[:base_url] = base_url
+
+      resp = EmailFuse::Emails.send(params, options: options)
+      mail.message_id = resp[:id] if resp[:error].nil?
+      resp
+    end
+
+    #
+    # Builds the payload for sending
+    #
+    # @param Mail mail rails mail object
+    #
+    # @return Hash hash with all EmailFuse params
+    #
+    def build_resend_params(mail)
+      params = {
+        from: get_from(mail),
+        to: mail.to,
+        subject: mail.subject
+      }
+      params.merge!(get_addons(mail))
+      params.merge!(get_headers(mail))
+      params.merge!(get_tags(mail))
+      params[:attachments] = get_attachments(mail) if mail.attachments.present?
+      params.merge!(get_contents(mail))
+      params
+    end
+
+    #
+    # Add custom headers fields.
+    #
+    # Both ways are supported:
+    #
+    #   1. Through the `#mail()` method ie:
+    #     mail(headers: { "X-Custom-Header" => "value" })
+    #
+    #   2. Through the Rails `#headers` method ie:
+    #     headers["X-Custom-Header"] = "value"
+    #
+    #
+    # setting the header values through the `#mail` method will overwrite values set
+    # through the `#headers` method using the same key.
+    #
+    # @param Mail mail Rails Mail object
+    #
+    # @return Hash hash with headers param
+    #
+    def get_headers(mail)
+      params = {}
+
+      if mail[:headers].present? || unignored_headers(mail).present?
+        params[:headers] = {}
+        params[:headers].merge!(headers_values(mail)) if unignored_headers(mail).present?
+        params[:headers].merge!(mail_headers_values(mail)) if mail[:headers].present?
+      end
+
+      params
+    end
+
+    #
+    # Adds additional options fields.
+    # Currently supports only :idempotency_key
+    #
+    # @param Mail mail Rails Mail object
+    # @return Hash hash with headers param
+    #
+    def get_options(mail)
+      opts = {}
+      if mail[:options].present?
+        opts.merge!(mail[:options].unparsed_value)
+        opts.delete_if { |k, _v| !SUPPORTED_OPTIONS.include?(k.to_s) }
+      end
+      opts
+    end
+
+    # Remove nils from header values
+    def cleanup_headers(headers)
+      headers.delete_if { |_k, v| v.nil? }
+    end
+
+    # Gets the values of the headers that are set through the `#mail` method
+    #
+    # @param Mail mail Rails Mail object
+    # @return Hash hash with mail headers values
+    def mail_headers_values(mail)
+      params = {}
+      mail[:headers].unparsed_value.each do |k, v|
+        params[k.to_s] = v
+      end
+      cleanup_headers(params)
+      params
+    end
+
+    # Gets the values of the headers that are set through the `#headers` method
+    #
+    # @param Mail mail Rails Mail object
+    # @return Hash hash with headers values
+    def headers_values(mail)
+      params = {}
+      unignored_headers(mail).each do |h|
+        params[h.name.to_s] = h.unparsed_value
+      end
+      cleanup_headers(params)
+      params
+    end
+
+    #
+    # Add tags fields
+    #
+    # @param Mail mail Rails Mail object
+    #
+    # @return Hash hash with tags param
+    #
+    def get_tags(mail)
+      params = {}
+      params[:tags] = mail[:tags].unparsed_value if mail[:tags].present?
+      params
+    end
+
+    #
+    # Add cc, bcc, reply_to fields
+    #
+    # @param Mail mail Rails Mail Object
+    #
+    # @return Hash hash containing cc/bcc/reply_to attrs
+    #
+    def get_addons(mail)
+      params = {}
+      params[:cc] = mail.cc if mail.cc.present?
+      params[:bcc] = mail.bcc if mail.bcc.present?
+      params[:reply_to] = mail.reply_to if mail.reply_to.present?
+      params
+    end
+
+    #
+    # Gets the body of the email
+    #
+    # @param Mail mail Rails Mail Object
+    #
+    # @return Hash hash containing html/text or both attrs
+    #
+    def get_contents(mail)
+      params = {}
+      case mail.mime_type
+      when "text/plain"
+        params[:text] = mail.body.decoded
+      when "text/html"
+        params[:html] = mail.body.decoded
+      when "multipart/alternative", "multipart/mixed", "multipart/related"
+        params[:text] = mail.text_part.decoded if mail.text_part
+        params[:html] = mail.html_part.decoded if mail.html_part
+      end
+      params
+    end
+
+    #
+    # Properly gets the `from` attr
+    #
+    # @param Mail input object
+    #
+    # @return String `from` string
+    #
+    def get_from(input)
+      return input.from.first if input[:from].nil?
+
+      from = input[:from].formatted
+      return from.first if from.is_a? Array
+
+      from.to_s
+    end
+
+    #
+    # Handle attachments when present
+    #
+    # @return Array attachments array
+    #
+    def get_attachments(mail)
+      attachments = []
+      mail.attachments.each do |part|
+        attachment = {
+          filename: part.filename,
+          content: part.body.decoded.bytes
+        }
+
+        # Rails uses the auto generated cid for inline attachments
+        attachment[:content_id] = part.cid if part.inline?
+        attachments.append(attachment)
+      end
+      attachments
+    end
+
+    #
+    # Get all headers that are not ignored
+    #
+    # @param Mail mail
+    #
+    # @return Array headers
+    #
+    def unignored_headers(mail)
+      @unignored_headers ||= mail.header_fields.reject { |h| IGNORED_HEADERS.include?(h.name.downcase) }
+    end
+  end
+end

data/lib/email_fuse/pagination_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # Helper class for building paginated query strings
+  class PaginationHelper
+    class << self
+      # Builds a paginated path with query parameters
+      #
+      # @param base_path [String] the base API path
+      # @param query_params [Hash] optional pagination parameters
+      # @option query_params [Integer] :limit Number of items to retrieve (max 100)
+      # @option query_params [String] :after ID after which to retrieve more items
+      # @option query_params [String] :before ID before which to retrieve more items
+      # @return [String] the path with query parameters
+      def build_paginated_path(base_path, query_params = nil)
+        return base_path if query_params.nil? || query_params.empty?
+
+        # Filter out nil values and convert to string keys
+        filtered_params = query_params.compact.transform_keys(&:to_s)
+
+        # Build query string
+        query_string = filtered_params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+
+        return base_path if query_string.empty?
+
+        "#{base_path}?#{query_string}"
+      end
+    end
+  end
+end

data/lib/email_fuse/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "email_fuse"
+require "email_fuse/mailer"
+
+module EmailFuse
+  # Main railtime class
+  class Railtie < ::Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :emailfuse, EmailFuse::Mailer
+      ActiveSupport.run_load_hooks(:emailfuse_mailer, EmailFuse::Mailer)
+    end
+  end
+end

data/lib/email_fuse/request.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # This class is responsible for making the appropriate HTTP calls
+  # and raising the specific errors based on the response.
+  class Request
+    attr_accessor :body, :verb, :options
+
+    def initialize(path = "", body = {}, verb = "POST", options: {})
+      # Allow api_key override via options, fall back to global config
+      api_key = options[:api_key] || EmailFuse.api_key
+      raise if api_key.nil?
+
+      api_key = api_key.call if api_key.is_a?(Proc)
+
+      # Allow base_url override via options, fall back to global config
+      @base_url = options[:base_url] || EmailFuse.base_url
+
+      @path = path
+      @body = body
+      @verb = verb
+      @options = options
+      @headers = {
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "emailfuse-ruby:#{EmailFuse::VERSION}",
+        "Authorization" => "Bearer #{api_key}"
+      }
+
+      set_idempotency_key
+      set_batch_validation
+    end
+
+    # Performs the HTTP call
+    def perform
+      options = build_request_options
+      resp = HTTParty.send(@verb.to_sym, URI.join(@base_url, @path).to_s, options)
+
+      check_json!(resp)
+      data = process_response(resp)
+      headers = extract_headers(resp)
+
+      EmailFuse::Response.new(data, headers)
+    end
+
+    def handle_error!(data, resp = nil)
+      code = data[:statusCode]
+      body = data[:message]
+      headers = resp.respond_to?(:headers) ? resp.headers : (data[:headers] || {})
+
+      # get error from the known list of errors
+      error_class = EmailFuse::Error::ERRORS[code] || EmailFuse::Error
+      raise error_class.new(body, code, headers)
+    end
+
+    private
+
+    def build_request_options
+      options = { headers: @headers }
+
+      if get_request_with_query?
+        options[:query] = @body
+      elsif !@body.empty?
+        options[:body] = @body.to_json
+      end
+
+      options
+    end
+
+    def get_request_with_query?
+      @verb.downcase == "get" && !@body.empty?
+    end
+
+    def process_response(resp)
+      # Extract the parsed data from HTTParty response or use the hash directly (for tests/mocks)
+      data = resp.respond_to?(:parsed_response) ? resp.parsed_response : resp
+      data ||= {}
+      data.transform_keys!(&:to_sym) unless resp.body.empty?
+      handle_error!(data, resp) if error_response?(data)
+      data
+    end
+
+    def error_response?(resp)
+      resp[:statusCode] && resp[:statusCode] != 200 && resp[:statusCode] != 201
+    end
+
+    def set_idempotency_key
+      # Only set idempotency key if the verb is POST for now.
+      #
+      # Does not set it if the idempotency_key is nil or empty
+      if @verb.downcase == "post" && !@options[:idempotency_key].nil? && !@options[:idempotency_key].empty?
+        @headers["Idempotency-Key"] = @options[:idempotency_key]
+      end
+    end
+
+    def set_batch_validation
+      # Set x-batch-validation header for batch emails
+      # Supported values: 'strict' (default) or 'permissive'
+      if @path == "emails/batch" && @options[:batch_validation]
+        @headers["x-batch-validation"] = @options[:batch_validation]
+      end
+    end
+
+    def check_json!(resp)
+      if resp.body.is_a?(Hash)
+        JSON.parse(resp.body.to_json)
+      else
+        JSON.parse(resp.body)
+      end
+    rescue JSON::ParserError, TypeError
+      raise EmailFuse::Error::InternalServerError.new("EmailFuse API returned an unexpected response", nil)
+    end
+
+    # Extract and normalize headers from the HTTParty response
+    def extract_headers(resp)
+      return {} unless resp.respond_to?(:headers)
+
+      resp.headers.to_h.transform_keys { |k| k.to_s.downcase }
+    end
+  end
+end

data/lib/email_fuse/response.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module EmailFuse
+  # Response wrapper that maintains backwards compatibility while exposing headers
+  #
+  # This class wraps API responses and behaves like a Hash for backwards compatibility,
+  # while also providing access to response headers via the #headers method.
+  #
+  # @example Backwards compatible hash access
+  #   response = EmailFuse::Emails.send(params)
+  #   response[:id]  # => "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
+  #
+  # @example Accessing response headers
+  #   response = EmailFuse::Emails.send(params)
+  #   response.headers  # => {"content-type" => "application/json", ...}
+  #   response.headers['x-ratelimit-remaining']  # => "50"
+  class Response
+    include Enumerable
+
+    # @param data [Hash] The response data
+    # @param headers [Hash, HTTParty::Response] The response headers
+    def initialize(data, headers)
+      @data = data.is_a?(Hash) ? data : {}
+      @headers = normalize_headers(headers)
+    end
+
+    # Access response headers
+    # @return [Hash] Response headers as a hash with lowercase string keys
+    attr_reader :headers
+
+    # Hash-like access via []
+    # @param key [Symbol, String] The key to access
+    # @return [Object] The value at the key
+    def [](key)
+      @data[key]
+    end
+
+    # Hash-like assignment via []=
+    # @param key [Symbol, String] The key to set
+    # @param value [Object] The value to set
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    # Dig into nested hash structure
+    # @param keys [Array<Symbol, String>] Keys to dig through
+    # @return [Object] The value at the nested key path
+    def dig(*keys)
+      @data.dig(*keys)
+    end
+
+    # Convert to plain hash
+    # @return [Hash] The underlying data hash
+    def to_h
+      @data
+    end
+
+    alias to_hash to_h
+
+    # Get all keys from the data
+    # @return [Array] Array of keys
+    def keys
+      @data.keys
+    end
+
+    # Get all values from the data
+    # @return [Array] Array of values
+    def values
+      @data.values
+    end
+
+    # Check if key exists
+    # @param key [Symbol, String] The key to check
+    # @return [Boolean] True if key exists
+    def key?(key)
+      @data.key?(key)
+    end
+
+    alias has_key? key?
+
+    # Enable enumeration over the data
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Transform keys in the underlying data
+    # @return [EmailFuse::Response] Self for chaining
+    def transform_keys!(&block)
+      @data.transform_keys!(&block)
+      self
+    end
+
+    # Check if response is empty
+    # @return [Boolean] True if data is empty
+    def empty?
+      @data.empty?
+    end
+
+    # Respond to hash-like methods
+    def respond_to_missing?(method_name, include_private = false)
+      @data.respond_to?(method_name) || super
+    end
+
+    # Delegate unknown methods to the underlying data hash
+    def method_missing(method_name, *args, &block)
+      if @data.respond_to?(method_name)
+        result = @data.send(method_name, *args, &block)
+        # If the method returns the hash itself, return self to maintain wrapper
+        result.equal?(@data) ? self : result
+      else
+        super
+      end
+    end
+
+    # String representation for debugging
+    # @return [String] String representation of the response
+    def inspect
+      "#<EmailFuse::Response data=#{@data.inspect} headers=#{@headers.keys.inspect}>"
+    end
+
+    private
+
+    # Normalize headers to a simple hash with lowercase string keys
+    # @param headers [Hash, HTTParty::Response, nil] The headers to normalize
+    # @return [Hash] Normalized headers hash
+    def normalize_headers(headers)
+      return {} if headers.nil?
+
+      # Handle HTTParty::Response object
+      headers = headers.headers if headers.respond_to?(:headers)
+
+      # Convert to hash and normalize keys to lowercase strings
+      case headers
+      when Hash
+        headers.to_h.transform_keys { |k| k.to_s.downcase }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/email_fuse/version.rb

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