hanami-mailer 0.0.0 → 0.2.0

data/hanami-mailer.gemspec

@@ -1,23 +1,29 @@
-# coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'hanami/mailer/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "hanami-mailer"
+  spec.name          = 'hanami-mailer'
   spec.version       = Hanami::Mailer::VERSION
-  spec.authors       = ["Luca Guidi"]
-  spec.email         = ["me@lucaguidi.com"]
+  spec.authors       = ['Luca Guidi', 'Ines Coelho', 'Rosa Faria']
+  spec.email         = ['me@lucaguidi.com', 'ines.opcoelho@gmail.com', 'rosa1853@live.com']
 
-  spec.summary       = %q{The web, with simplicity}
-  spec.description   = %q{Hanami is a web framework for Ruby}
-  spec.homepage      = "http://hanamirb.org"
+  spec.summary       = %q{Mail for Ruby applications.}
+  spec.description   = %q{Mail for Ruby applications and Hanami mailers}
+  spec.homepage      = 'http://hanamirb.org'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.files         = `git ls-files -- lib/* CHANGELOG.md LICENSE.md README.md hanami-mailer.gemspec`.split($/)
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.0.0'
 
-  spec.add_development_dependency "bundler", "~> 1.11"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_dependency 'hanami-utils', '~> 0.7'
+  spec.add_dependency 'tilt',         '~> 2.0', '>= 2.0.1'
+  spec.add_dependency 'mail',         '~> 2.5'
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake',    '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.7'
 end

data/lib/hanami-mailer.rb

@@ -0,0 +1 @@
+require 'hanami/mailer'

data/lib/hanami/mailer.rb

@@ -1,7 +1,316 @@
-require "hanami/mailer/version"
+require 'hanami/utils/class_attribute'
+require 'hanami/mailer/version'
+require 'hanami/mailer/configuration'
+require 'hanami/mailer/dsl'
+require 'mail'
 
 module Hanami
+  # Hanami::Mailer
+  #
+  # @since 0.1.0
   module Mailer
-    # Your code goes here...
+    # Base error for Hanami::Mailer
+    #
+    # @since 0.1.0
+    class Error < ::StandardError
+    end
+
+    # Missing delivery data error
+    #
+    # It's raised when a mailer doesn't specify <tt>from</tt> or <tt>to</tt>.
+    #
+    # @since 0.1.0
+    class MissingDeliveryDataError < Error
+      def initialize
+        super("Missing delivery data, please check 'from', or 'to'")
+      end
+    end
+
+    # Content types mapping
+    #
+    # @since 0.1.0
+    # @api private
+    CONTENT_TYPES = {
+      html: 'text/html',
+      txt:  'text/plain'
+    }.freeze
+
+    include Utils::ClassAttribute
+
+    # @since 0.1.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure the framework.
+    # It yields the given block in the context of the configuration
+    #
+    # @param blk [Proc] the configuration block
+    #
+    # @since 0.1.0
+    #
+    # @see Hanami::Mailer::Configuration
+    #
+    # @example
+    #   require 'hanami/mailer'
+    #
+    #   Hanami::Mailer.configure do
+    #     root '/path/to/root'
+    #   end
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+      self
+    end
+
+    # Override Ruby's hook for modules.
+    # It includes basic Hanami::Mailer modules to the given Class.
+    # It sets a copy of the framework configuration
+    #
+    # @param base [Class] the target mailer
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+    def self.included(base)
+      conf = self.configuration
+      conf.add_mailer(base)
+
+      base.class_eval do
+        extend Dsl
+        extend ClassMethods
+
+        include Utils::ClassAttribute
+        class_attribute :configuration
+
+        self.configuration = conf.duplicate
+      end
+
+      conf.copy!(base)
+    end
+
+    # Test deliveries
+    #
+    # This is a collection of delivered messages, used when <tt>delivery_method</tt>
+    # is set on <tt>:test</tt>
+    #
+    # @return [Array] a collection of delivered messages
+    #
+    # @since 0.1.0
+    #
+    # @see Hanami::Mailer::Configuration#delivery_mode
+    #
+    # @example
+    #   require 'hanami/mailer'
+    #
+    #   Hanami::Mailer.configure do
+    #     delivery_method :test
+    #   end.load!
+    #
+    #   # In testing code
+    #   Signup::Welcome.deliver
+    #   Hanami::Mailer.deliveries.count # => 1
+    def self.deliveries
+      Mail::TestMailer.deliveries
+    end
+
+    # Load the framework
+    #
+    # @since 0.1.0
+    # @api private
+    def self.load!
+      Mail.eager_autoload!
+      configuration.load!
+    end
+
+    # @since 0.1.0
+    module ClassMethods
+      # Delivers a multipart email message.
+      #
+      # When a mailer defines a <tt>html</tt> and <tt>txt</tt> template, they are
+      # both delivered.
+      #
+      # In order to selectively deliver only one of the two templates, use
+      # <tt>Signup::Welcome.deliver(format: :txt)</tt>
+      #
+      # All the given locals, excepted the reserved ones (<tt>:format</tt> and
+      # <tt>charset</tt>), are avaliable as rendering context for the templates.
+      #
+      # @param locals [Hash] a set of objects that acts as context for the rendering
+      # @option :format [Symbol] specify format to deliver
+      # @option :charset [String] charset
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Mailer::Configuration#default_charset
+      #
+      # @example
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configure do
+      #     delivery_method :smtp
+      #   end.load!
+      #
+      #   module Billing
+      #     class Invoice
+      #       include Hanami::Mailer
+      #
+      #       from    'noreply@example.com'
+      #       to      :recipient
+      #       subject :subject_line
+      #
+      #       def prepare
+      #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
+      #       end
+      #
+      #       private
+      #
+      #       def recipient
+      #         user.email
+      #       end
+      #
+      #       def subject_line
+      #         "Invoice - #{ invoice.number }"
+      #       end
+      #     end
+      #   end
+      #
+      #   invoice = Invoice.new
+      #   user    = User.new(name: 'L', email: 'user@example.com')
+      #
+      #   Billing::Invoice.deliver(invoice: invoice, user: user)                      # Deliver both text, HTML parts and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :txt)        # Deliver only the text part and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, format: :html)       # Deliver only the text part and the attachment
+      #   Billing::Invoice.deliver(invoice: invoice, user: user, charset: 'iso-8859') # Deliver both the parts with "iso-8859"
+      def deliver(locals = {})
+        new(locals).deliver
+      end
+    end
+
+    # Initialize a mailer
+    #
+    # @param locals [Hash] a set of objects that acts as context for the rendering
+    # @option :format [Symbol] specify format to deliver
+    # @option :charset [String] charset
+    #
+    # @since 0.1.0
+    def initialize(locals = {})
+      @locals  = locals
+      @format  = locals.fetch(:format, nil)
+      @charset = charset = locals.fetch(:charset, self.class.configuration.default_charset)
+      @mail    = Mail.new.tap do |m|
+        m.from    = __dsl(:from)
+        m.to      = __dsl(:to)
+        m.subject = __dsl(:subject)
+
+        m.charset   = charset
+        m.html_part = __part(:html)
+        m.text_part = __part(:txt)
+
+        m.delivery_method(*Hanami::Mailer.configuration.delivery_method)
+      end
+
+      prepare
+    end
+
+    # Render a single template with the specified format.
+    #
+    # @param format [Symbol] format
+    #
+    # @return [String] the output of the rendering process.
+    #
+    # @since 0.1.0
+    # @api private
+    def render(format)
+      self.class.templates(format).render(self, @locals)
+    end
+
+    # Delivers a multipart email, by looking at all the associated templates and render them.
+    #
+    # @since 0.1.0
+    # @api private
+    def deliver
+      mail.deliver
+    rescue ArgumentError
+      raise MissingDeliveryDataError
+    end
+
+    protected
+
+    # Prepare the email message when a new mailer is initialized.
+    #
+    # This is a hook that can be overwritten by mailers.
+    #
+    # @since 0.1.0
+    #
+    # @example
+    #   require 'hanami/mailer'
+    #
+    #   module Billing
+    #     class Invoice
+    #       include Hanami::Mailer
+    #
+    #       subject 'Invoice'
+    #       from    'noreply@example.com'
+    #       to      ''
+    #
+    #       def prepare
+    #         mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
+    #       end
+    #
+    #       private
+    #
+    #       def recipient
+    #         user.email
+    #       end
+    #     end
+    #   end
+    #
+    #   invoice = Invoice.new
+    #   user    = User.new(name: 'L', email: 'user@example.com')
+    def prepare
+    end
+
+    # @private
+    # @since 0.1.0
+    def method_missing(m)
+      @locals.fetch(m) { super }
+    end
+
+    # @since 0.1.0
+    attr_reader :mail
+
+    # @private
+    # @since 0.1.0
+    attr_reader :charset
+
+    private
+
+    # @private
+    # @since 0.1.0
+    def __dsl(method_name)
+      case result = self.class.__send__(method_name)
+      when Symbol
+        __send__(result)
+      else
+        result
+      end
+    end
+
+    # @private
+    # @since 0.1.0
+    def __part(format)
+      Mail::Part.new.tap do |part|
+        part.content_type = "#{ CONTENT_TYPES.fetch(format) }; charset=#{ charset }"
+        part.body         = render(format)
+      end if __part?(format)
+    end
+
+    # @private
+    # @since 0.1.0
+    def __part?(format)
+      @format == format ||
+        (!@format && !self.class.templates(format).nil?)
+    end
   end
 end

data/lib/hanami/mailer/configuration.rb

@@ -0,0 +1,307 @@
+require 'set'
+require 'hanami/utils/kernel'
+
+module Hanami
+  module Mailer
+    # Framework configuration
+    #
+    # @since 0.1.0
+    class Configuration
+      # Default root
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_ROOT = '.'.freeze
+
+      # Default delivery method
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_DELIVERY_METHOD = :smtp
+
+      # Default charset
+      #
+      # @since 0.1.0
+      # @api private
+      DEFAULT_CHARSET = 'UTF-8'.freeze
+
+      # @since 0.1.0
+      # @api private
+      attr_reader :mailers
+
+      # @since 0.1.0
+      # @api private
+      attr_reader :modules
+
+      # Initialize a configuration instance
+      #
+      # @return [Hanami::Mailer::Configuration] a new configuration's instance
+      #
+      # @since 0.1.0
+      def initialize
+        @namespace = Object
+        reset!
+      end
+
+      # Set the Ruby namespace where to lookup for mailers.
+      #
+      # When multiple instances of the framework are used, we want to make sure
+      # that if a `MyApp` wants a `Mailers::Signup` mailer, we are loading the
+      # right one.
+      #
+      # If not set, this value defaults to `Object`.
+      #
+      # This is part of a DSL, for this reason when this method is called with
+      # an argument, it will set the corresponding instance variable. When
+      # called without, it will return the already set value, or the default.
+      #
+      # @overload namespace(value)
+      #   Sets the given value
+      #   @param value [Class, Module, String] a valid Ruby namespace identifier
+      #
+      # @overload namespace
+      #   Gets the value
+      #   @return [Class, Module, String]
+      #
+      # @api private
+      # @since 0.1.0
+      #
+      # @example Getting the value
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configuration.namespace # => Object
+      #
+      # @example Setting the value
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configure do
+      #     namespace 'MyApp::Mailers'
+      #   end
+      def namespace(value = nil)
+        if value
+          @namespace = value
+        else
+          @namespace
+        end
+      end
+
+      # Set the root path where to search for templates
+      #
+      # If not set, this value defaults to the current directory.
+      #
+      # When this method is called with an argument, it will set the corresponding instance variable.
+      # When called without, it will return the already set value, or the default.
+      #
+      # @overload root(value)
+      #   Sets the given value
+      #   @param value [String, Pathname, #to_pathname] an object that can be
+      #     coerced to Pathname
+      #
+      # @overload root
+      #   Gets the value
+      #   @return [Pathname]
+      #
+      # @since 0.1.0
+      #
+      # @see http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html
+      # @see http://rdoc.info/gems/hanami-utils/Hanami/Utils/Kernel#Pathname-class_method
+      #
+      # @example Getting the value
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configuration.root # => #<Pathname:.>
+      #
+      # @example Setting the value
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configure do
+      #     root '/path/to/templates'
+      #   end
+      #
+      #   Hanami::Mailer.configuration.root # => #<Pathname:/path/to/templates>
+      def root(value = nil)
+        if value
+          @root = Utils::Kernel.Pathname(value).realpath
+        else
+          @root
+        end
+      end
+
+      # Prepare the mailers.
+      #
+      # The given block will be yielded when `Hanami::Mailer` will be included by
+      # a mailer.
+      #
+      # This method can be called multiple times.
+      #
+      # @param blk [Proc] the code block
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if called without passing a block
+      #
+      # @since 0.1.0
+      #
+      # @see Hanami::Mailer.configure
+      def prepare(&blk)
+        if block_given?
+          @modules.push(blk)
+        else
+          raise ArgumentError.new('Please provide a block')
+        end
+      end
+
+      # Add a mailer to the registry
+      #
+      # @since 0.1.0
+      # @api private
+      def add_mailer(mailer)
+        @mailers.add(mailer)
+      end
+
+      # Duplicate by copying the settings in a new instance.
+      #
+      # @return [Hanami::Mailer::Configuration] a copy of the configuration
+      #
+      # @since 0.1.0
+      # @api private
+      def duplicate
+        Configuration.new.tap do |c|
+          c.namespace  = namespace
+          c.root       = root.dup
+          c.modules    = modules.dup
+          c.delivery_method = delivery_method
+          c.default_charset = default_charset
+        end
+      end
+
+      # Load the configuration
+      def load!
+        mailers.each { |m| m.__send__(:load!) }
+        freeze
+      end
+
+      # Reset the configuration
+      def reset!
+        root(DEFAULT_ROOT)
+        delivery_method(DEFAULT_DELIVERY_METHOD)
+        default_charset(DEFAULT_CHARSET)
+
+        @mailers = Set.new
+        @modules = []
+      end
+
+      alias_method :unload!, :reset!
+
+      # Copy the configuration for the given mailer
+      #
+      # @param base [Class] the target mailer
+      #
+      # @return void
+      #
+      # @since 0.1.0
+      # @api private
+      def copy!(base)
+        modules.each do |mod|
+          base.class_eval(&mod)
+        end
+      end
+
+      # Specify a global delivery method for the mail gateway.
+      #
+      # It supports the following delivery methods:
+      #
+      #   * Exim (<tt>:exim</tt>)
+      #   * Sendmail (<tt>:sendmail</tt>)
+      #   * SMTP (<tt>:smtp</tt>, for local installations)
+      #   * SMTP Connection (<tt>:smtp_connection</tt>,
+      #     via <tt>Net::SMTP</tt> - for remote installations)
+      #   * Test (<tt>:test</tt>, for testing purposes)
+      #
+      # The default delivery method is SMTP (<tt>:smtp</tt>).
+      #
+      # Custom delivery methods can be specified by passing the class policy and
+      # a set of optional configurations. This class MUST respond to:
+      #
+      #   * <tt>initialize(options = {})</tt>
+      #   * <tt>deliver!(mail)<tt>
+      #
+      # @param method [Symbol, #initialize, deliver!] delivery method
+      # @param options [Hash] optional settings
+      #
+      # @return [Array] an array containing the delivery method and the optional settings as an Hash
+      #
+      # @since 0.1.0
+      #
+      # @example Setup delivery method with supported symbol
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configure do
+      #     delivery_method :sendmail
+      #   end
+      #
+      # @example Setup delivery method with supported symbol and options
+      #   require 'hanami/mailer'
+      #
+      #   Hanami::Mailer.configure do
+      #     delivery_method :smtp, address: "localhost", port: 1025
+      #   end
+      #
+      # @example Setup custom delivery method with options
+      #   require 'hanami/mailer'
+      #
+      #   class MandrillDeliveryMethod
+      #     def initialize(options)
+      #       @options = options
+      #     end
+      #
+      #     def deliver!(mail)
+      #       # ...
+      #     end
+      #   end
+      #
+      #   Hanami::Mailer.configure do
+      #     delivery_method MandrillDeliveryMethod,
+      #       username: ENV['MANDRILL_USERNAME'],
+      #       password: ENV['MANDRILL_API_KEY']
+      #   end
+      def delivery_method(method = nil, options = {})
+        if method.nil?
+          @delivery_method
+        else
+          @delivery_method = [method, options]
+        end
+      end
+
+      # @since 0.1.0
+      def default_charset(value = nil)
+        if value.nil?
+          @default_charset
+        else
+          @default_charset = value
+        end
+      end
+
+      protected
+      # @api private
+      # @since 0.1.0
+      attr_writer :root
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :delivery_method
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :default_charset
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :namespace
+
+      # @api private
+      # @since 0.1.0
+      attr_writer :modules
+    end
+  end
+end