capistrano-mailgun 0.1.1 → 1.0.0

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.8.7
+  - ree
+script: bundle exec rspec spec

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in capistrano-mailgun.gemspec
 gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'awesome_print'

data/README.md

@@ -1,4 +1,4 @@
-# Capistrano-Mailgun
+# Capistrano-Mailgun  [![Build Status](https://travis-ci.org/spikegrobstein/capistrano-mailgun.png)](https://travis-ci.org/spikegrobstein/capistrano-mailgun)
 
 *Bust a cap in your deployment notifications*
 
@@ -29,17 +29,17 @@ In your `Capfile`, add:
 
 To send a notification after deploy, add the following to your `deploy.rb` file:
 
-    require 'capistrano-mailgun'
-
     set :mailgun_api_key, 'key-12345678901234567890123456789012' # your mailgun API key
     set :mailgun_domain, 'example.com' # your mailgun email domain
     set :mailgun_from, 'deployment@example.com' # who the email will appear to come from
     set :mailgun_recipients, [ 'you@example.com', 'otherguy@example.com' ] # who will receive the email
 
-    # create an after:deploy hook
-    # pass it the path to an erb template.
     # The erb template will have visibility into all your capistrano variables.
-    after(:deploy) { mailgun.notify_of_deploy File.join(File.dirname(__FILE__), 'mail.erb') }
+    # this template will be the text body of the notification email
+    set :mailgun_text_template, File.join(File.dirname(__FILE__), 'mail.erb')
+
+    # create an after deploy hook
+    after(:deploy) { mailgun.notify_of_deploy }
 
 You should then create a `mail.erb` file in the same directory as `deploy.rb`:
 
@@ -47,6 +47,55 @@ You should then create a `mail.erb` file in the same directory as `deploy.rb`:
 
 That's it. When you do a deploy, it should automatically send an email.
 
+## Example using mailgun.send_email
+
+If you need a little more control over the message being sent or you want to bcc or be a little
+more conditional over what you're sending, see the following example, which should be placed
+in your `deploy.rb` file:
+
+    # when using send_email, the following 2 settings are REQUIRED
+    set :mailgun_api_key, 'key-12345678901234567890123456789012' # your mailgun API key
+    set :mailgun_domain, 'example.com' # your mailgun email domain
+
+    set(:email_body) { abort "Please set email_body using `-s email_body='this is the body of the email'" }
+
+    # some variables that we'll use when calling mailgun.send_email
+    set :ops_emails, [ 'alice', 'bob' ]
+    set :dev_emails, [ 'carl@contractors.com', 'dave' ]
+
+    # some basic tasks
+    namespace :email do
+      task :ops do
+        mailgun.send_email(
+          :to => mailgun.build_recipients(ops_emails, 'example.com'),
+          :from => 'some_dude@example.com',
+          :subject => 'you have just been mailgunned',
+          :text => email_body
+        )
+      end
+
+      task :devs do
+        mailgun.send_email(
+          :to => 'no-reply@example.com',
+          :from => 'no-reply@example.com',
+          :bcc => mailgun.build_recipients(dev_emails, 'example.com'),
+          :subject => 'You guys are just developers',
+          :text => email_body
+        )
+      end
+    end
+
+This defines 2 tasks that can be used to send emails to ops or devs. The `email:ops` task is using
+an Capistrano variable `email_body` which should be set on the commandline. With this example, you could
+send an email to ops guys like the following:
+
+    cap email:ops -s email_body="You guys are awesome. Keep up the good work"
+
+You could also take advantage of `:text_template` and/or `:html_template` for more complex messages. The
+above is just an example.
+
+Also, notice the use of `mailgun.build_recipients`. See documentation below for more information.
+
 ## Capistrano Variables
 
 `capistrano-mailgun` leverages variables defined in Capistrano to reduce the amount of configuration
@@ -71,6 +120,19 @@ An array of email addresses who should recieve a notification when a deployment
 You can optionally only specify just the part of the email address before the @ and `capistrano-mailgun` will
 automatically append the `mailgun_recipient_domain` to it. See `mailgun_recipient_domain`.
 
+### mailgun_text_template (required for notify_of_deploy)
+
+This is the path to the ERB template that `Capistrano::Mailgun` will use to create the text body of
+your email. This is only required if you do not use the `mailgun_html_template` variable. You can
+specify both text and html templates and the emails will contain the proper bodies where the client
+supports it.
+
+### mailgun_html_template (required for notify_of_deploy)
+
+This is the path to the ERB template that will be used to generate the HTML body of the email. It is only
+required if you do not specify the `mailgun_text_template` variable. You can specify both text and html
+templates and emails will contain the proper bodies where the client supports it.
+
 ### mailgun_recipient_domain
 
 The domain that will be automatically appended to incomplete email addresses in the `mailgun_recipients`.
@@ -87,23 +149,41 @@ Setting this will override the default.
 
 `capistrano-mailgun` has a couple of methods to enable you to send emails easily. The following are the functions:
 
-### mailgun.notify_of_deploy(erb_path)
+### mailgun.build_recipients( recipients, default_domain=nil )
+
+Given an array of email addresses, this will join them with a comma so any recipients field with more than 1 recipient
+will be formatted properly. Typically, you will only use this function in the event that you're using `mailgun.send_email`.
+
+You can also pass an alternate `default_domain`. This is useful if you're not using the global `mailgun_recipient_domain`
+Capistrano variable of if you want to override the behavior in this one use-case. `mailgun.build_recipients` will always
+choose the specified `default_domain` over `mailgun_recipient_domain`.
 
-Given a path to an erb template file, it will send an email to recipients specified using the above
-Capistrano variables.
+### mailgun.notify_of_deploy
+
+This is a convenience function to send an email via the Mailgun api using your Capistrano variables for
+basic configuration. It will use either/or `mailgun_html_template` and `mailgun_text_template` to generate the
+email body, `mailgun_recipients` for who to address the email to, `mailgun_from` for the reply-to field
+of the email and `mailgun_subject` for the subject of the email.
 
 See Quickstart, above, for an example.
 
-### mailgun.send_email( template, subject, recipients, from_address )
+### mailgun.send_email( options )
+
+This is the base function for operating the Mailgun API. It uses the `mailgun_api_key` and `mailgun_domain`
+Capistrano variables for interacting with the service. If you need additional control over headers and options
+when sending the emails, call this function directly. For a full list of options, see the Mailgun REST API
+documentation:
+
+http://documentation.mailgun.net/api-sending.html
+
+This function also takes the following additional options:
 
-Given a path to a template, subject, recipients and a from\_address, send an email via the Mailgun API.
+ * `:text_template` -- a path to an ERB template for the text body of the email.
+ * `:html_template` -- a path to an ERB template for the HTML body of the email.
 
-This function exists for convenience if you want to change the default behavior or notify during other events
-triggered by Capistrano. `mailgun.send_email` adheres to the same behavior for recipients (automatically adding
-the domain to the email addresses) as the regular `mailgun.notify_of_deploy` function.
+The templates will have access to all of your Capistrano variables.
 
-The template will also be executed in the context of the recipe and will have access to everything that
-capistrano has access to.
+Of course, you can also pass `:text` and `:html` options for the exact text/html bodies of the sent emails.
 
 ### deployer_username
 
@@ -113,10 +193,8 @@ actually did the deployment.
 
 ## Limitations
 
- * Only supports plain-text emails. This should be fixed in the next release.
  * Only supports ERB for templates. This should be changed in a future release.
- * Simpler support for specifying templates? Should not need to pass absolute path, hopefully.
- * Extremely limited access to Mailgun parameters. Eventually I'd like to add support for better customization of this.
+ * Currently requires that ERB templates are on the filesystem. Future releases may allow for inline templates.
 
 ## Contributing
 

data/capistrano-mailgun.gemspec

@@ -14,4 +14,7 @@ Gem::Specification.new do |gem|
   gem.name          = "capistrano-mailgun"
   gem.require_paths = ["lib"]
   gem.version       = Capistrano::Mailgun::VERSION
+
+  gem.add_dependency "capistrano"
+  gem.add_dependency "rest-client"
 end

data/lib/capistrano-mailgun/version.rb

@@ -1,5 +1,5 @@
 module Capistrano
   module Mailgun
-    VERSION = "0.1.1"
+    VERSION = "1.0.0"
   end
 end

data/lib/capistrano-mailgun.rb

@@ -6,18 +6,54 @@ require 'erb'
 module Capistrano
   module Mailgun
 
+    def self.load_into(config)
+      config.load do
+
+        Capistrano.plugin :mailgun, Capistrano::Mailgun
+
+        set(:mailgun_subject) { "[Deployment] #{ application.capitalize } completed" }
+
+        set(:mailgun_api_key)           { abort "Please set mailgun_api_key accordingly" }
+        set(:mailgun_domain)            { abort "Please set mailgun_domain accordingly" }
+        set(:mailgun_from)              { abort "Please set mailgun_from to your desired From field" }
+        set(:mailgun_recipients)        { abort "Please specify mailgun_recipients" }
+        set(:mailgun_recipient_domain)  { abort "Please set mailgun_recipient_domain accordingly" }
+
+        set(:deployer_username) do
+          if fetch(:scm, nil).to_sym == :git
+            `git config user.name`.chomp
+          else
+            `whoami`.chomp
+          end
+        end
+
+
+      end # config.load
+    end
+
     # simple wrapper for sending an email with a given template
-    def send_email(template, subject, recipients, from_address)
-      RestClient.post "https://api:#{ mailgun_api_key }@api.mailgun.net/v2/#{ mailgun_domain }/messages",
-        :from => from_address,
-        :to => build_recipients( recipients ).join(','),
-        :subject => subject,
-        :text => ERB.new( File.open( find_template(template), 'r' ).read ).result(self.binding)
+    def send_email(options)
+      options = process_send_email_options(options)
+
+      RestClient.post build_mailgun_uri( mailgun_api_key, mailgun_domain ), options
     end
 
     # does a deploy notification leveraging variables defined in capistrano.
-    def notify_of_deploy(template_name)
-      send_email( template_name, mailgun_subject, build_recipients( mailgun_recipients ), mailgun_from )
+    def notify_of_deploy
+      options = {
+        :to => build_recipients( fetch(:mailgun_recipients) ),
+        :from => fetch(:mailgun_from),
+        :subject => fetch(:mailgun_subject)
+      }
+
+      if fetch(:mailgun_text_template, nil).nil? && fetch(:mailgun_html_template, nil).nil?
+        abort "You must specify one (or both) of mailgun_text_template and mailgun_html_template to use notify_of_deploy"
+      end
+
+      options[:text_template] = fetch(:mailgun_text_template) if fetch(:mailgun_text_template, nil)
+      options[:html_template] = fetch(:mailgun_html_template) if fetch(:mailgun_html_template, nil)
+
+      send_email options
     end
 
     # kinda unused function for locating a provided template
@@ -26,42 +62,37 @@ module Capistrano
       File.join( File.dirname(__FILE__), t )
     end
 
-    private
-
-    # regenerates the recipients list using hte mailgun_domain for any reciients without domains
-    def build_recipients(recipients)
-      recipients.map do |r|
-        if r.match /.+?@.+?$/
+    # regenerates the recipients list using the mailgun_domain for any reciients without domains
+    def build_recipients(recipients, default_domain=nil)
+      [*recipients].map do |r|
+        if r.match /.+?@.+?$/ # the email contains an @ so it's fully-qualified.
           r
         else
-          "#{ r }@#{ mailgun_recipient_domain }"
+          "#{ r }@#{ default_domain || fetch(:mailgun_recipient_domain) }"
         end
-      end
+      end.uniq
     end
 
-  end
-end
+    private
 
-if Capistrano::Configuration.instance
-  Capistrano::Configuration.instance.load do
-    Capistrano.plugin :mailgun, Capistrano::Mailgun
-
-    set(:mailgun_subject) { "[Deployment] #{ application.capitalize } completed" }
-
-    set(:mailgun_api_key) { abort "Please set mailgun_api_key accordingly" }
-    set(:mailgun_domain) { abort "Please set mailgun_domain accordingly" }
-    set(:mailgun_from) { abort "Please set mailgun_from to your desired From field" }
-    set(:mailgun_recipients) { abort "Please specify mailgun_recipients" }
-    set(:mailgun_recipient_domain) { abort "Please set mailgun_recipient_domain accordingly" }
-
-    set(:deployer_username) do
-      if fetch(:scm, nil).to_sym == :git
-        `git config user.name`.chomp
-      else
-        `whoami`.chomp
-      end
+    # apply templates and all that jazz
+    def process_send_email_options(options)
+      text_template = options.delete(:text_template)
+      html_template = options.delete(:html_template)
+
+      options[:text] = ERB.new( File.open( find_template(text_template) ).read ).result(self.binding) if text_template
+      options[:html] = ERB.new( File.open( find_template(html_template) ).read ).result(self.binding) if html_template
+
+      options
+    end
+
+    def build_mailgun_uri(mailgun_api_key, mailgun_domain)
+      "https://api:#{ mailgun_api_key }@api.mailgun.net/v2/#{ mailgun_domain }/messages"
     end
 
   end
+end
 
+if Capistrano::Configuration.instance
+  Capistrano::Mailgun.load_into(Capistrano::Configuration.instance)
 end

data/spec/capistrano-mailgun_spec.rb

@@ -0,0 +1,174 @@
+require 'spec_helper'
+
+describe Capistrano::Mailgun do
+
+  let(:config) do
+    Capistrano::Configuration.new
+  end
+
+  before do
+    Capistrano::Mailgun.load_into(config)
+  end
+
+  let!(:mailgun) { config.mailgun }
+
+  context '#buid_recipients' do
+    let(:email_1) { 'spike@example.com' }
+    let(:email_2) { 'bob@example.com' }
+
+    def build_recipients(recipients, default_domain=nil)
+      mailgun.send(:build_recipients, recipients, default_domain)
+    end
+
+    it "should accept a single recipient (not an array)" do
+      build_recipients(email_1).should == [email_1]
+    end
+
+    it "should accept an array of recipeints" do
+      build_recipients( [email_1, email_2] ).should == [email_1, email_2]
+    end
+
+    it "should deduplicate emails in the recipients" do
+      build_recipients( [email_1, email_2, email_1] ).should == [email_1, email_2]
+    end
+
+    context "when working with unqualified email addresses" do
+      before do
+        config.load do
+          set :mailgun_recipient_domain, 'another.com'
+        end
+      end
+
+      it "should add the mailgun_recipient_domain to any unqualified email addresses" do
+        build_recipients( %w( spike ) ).should == ['spike@another.com']
+      end
+
+      it "should accept a mix of qualified and unqualified email addresses" do
+        build_recipients( [email_1, 'spike']).should == [email_1, 'spike@another.com']
+      end
+
+    end
+
+    context "when working with custom default domains" do
+
+      it "should not raise an error if mailgun_recipient_domain is not defined, but default_domain is" do
+        lambda { build_recipients( ['spike'], 'example.com' ) }.should_not raise_error
+      end
+
+      it "should use the passed default_domain over the mailgun_recipient_domain if it's passed" do
+        config.load { set :mailgun_recipient_domain, 'example.com' }
+        build_recipients( ['spike'], 'awesome.com' ).should == ['spike@awesome.com']
+      end
+    end
+
+
+  end
+
+  context "#find_template" do
+
+    # future behavior might be different
+    it "should return the path passed to it" do
+      mailgun.find_template('asdf').should == 'asdf'
+    end
+
+  end
+
+
+  context "when ensuring cap variables are defined" do
+
+    def should_require(var)
+      lambda do
+        config.load { fetch var }
+      end.should raise_error
+    end
+
+    it "should require mailgun_api_key" do
+      should_require :mailgun_api_key
+    end
+
+    it "should require mailgun_domain" do
+      should_require :mailgun_domain
+    end
+
+  end
+
+  context "#send_email" do
+
+    before do
+      config.load do
+        set :mailgun_api_key, 'asdfasdf'
+        set :mailgun_domain, 'example.com'
+      end
+    end
+
+  end
+
+  context "#notify_of_deploy" do
+
+    before do
+      config.load do
+        set :mailgun_recipients, 'people@example.com'
+        set :mailgun_from, 'me@example.com'
+
+        set :mailgun_subject, 'new subject'
+      end
+    end
+
+    it "should raise an error if neither mailgun_text_template nor mailgun_html_template are defined" do
+      lambda { mailgun.send(:notify_of_deploy) }.should raise_error
+    end
+
+    it "should not raise an error if mailgun_text_template is defined" do
+      config.load { set :mailgun_text_template, 'template' }
+      mailgun.should_receive(:send_email)
+
+      lambda { mailgun.notify_of_deploy }.should_not raise_error
+    end
+
+    it "should not raise an error if mailgun_html_template is defined" do
+      config.load { set :mailgun_html_template, 'template' }
+      mailgun.should_receive(:send_email)
+
+      lambda { mailgun.notify_of_deploy }.should_not raise_error
+    end
+
+  end
+
+  context "#process_send_email_options" do
+    let(:test_mailgun_domain) { 'example.com' }
+
+    before do
+      config.load { set :mailgun_domain, 'example.com' }
+    end
+
+    it "should set text to the rendered text template if text_template is passed" do
+      result = mailgun.send(:process_send_email_options, :text_template => fixture_path('text_body.erb'))
+
+      result[:text].should include(test_mailgun_domain)
+      result[:text].should_not include('<%=')
+    end
+
+    it "should not change text if no text_template is passed" do
+      ERB.should_not_receive(:new)
+      File.should_not_receive(:open)
+
+      mailgun.send(:process_send_email_options, :text => 'normal text')[:text].should == 'normal text'
+    end
+
+    it "should set html to the rendered html template if html_template is passed" do
+      result = mailgun.send(:process_send_email_options, :html_template => fixture_path('html_body.erb'))
+
+      result[:html].should include(test_mailgun_domain)
+      result[:html].should_not include('<%=')
+    end
+
+    it "should not change html if no html_template is passed" do
+      ERB.should_not_receive(:new)
+      File.should_not_receive(:open)
+
+      mailgun.send(:process_send_email_options, :html => 'normal html')[:html].should == 'normal html'
+    end
+
+  end
+
+end

data/spec/fixtures/html_body.erb

@@ -0,0 +1 @@
+This is an html template. <%= mailgun_domain %>

data/spec/fixtures/text_body.erb

@@ -0,0 +1 @@
+This is a text template. <%= mailgun_domain %>

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'awesome_print'
+
+$: << File.dirname(__FILE__) + '/../lib'
+
+require 'capistrano'
+require 'capistrano-mailgun'
+
+Rspec.configure do |config|
+  # config
+end
+
+def fixture_path(filename)
+  File.join( File.dirname(__FILE__), 'fixtures', filename )
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-mailgun
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,40 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-11 00:00:00.000000000 Z
-dependencies: []
+date: 2012-10-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Notify of deploys and other actions using mailgun
 email:
 - spike@ticketevolution.com
@@ -19,6 +51,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -26,6 +60,10 @@ files:
 - capistrano-mailgun.gemspec
 - lib/capistrano-mailgun.rb
 - lib/capistrano-mailgun/version.rb
+- spec/capistrano-mailgun_spec.rb
+- spec/fixtures/html_body.erb
+- spec/fixtures/text_body.erb
+- spec/spec_helper.rb
 homepage: ''
 licenses: []
 post_install_message: 
@@ -38,17 +76,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 224140973397268413
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 224140973397268413
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Notify of deploys and other actions using mailgun
-test_files: []
-has_rdoc: 
+test_files:
+- spec/capistrano-mailgun_spec.rb
+- spec/fixtures/html_body.erb
+- spec/fixtures/text_body.erb
+- spec/spec_helper.rb