apostle 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+Gemfile.lock
+InstalledFiles
+# YARD artifacts
+.yardoc
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in penpal.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Apostle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,164 @@
+# Apostle
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'apostle'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apostle
+
+## Domain Key
+
+You will need to provide your apostle domain key to send emails. Apostle looks in `ENV['APOSTLE_DOMAIN_KEY']`, or you can set it manually.
+
+```ruby
+Apostle.configure do |config|
+	config.domain_key = 'Your domain key'
+end
+```
+
+## Sending Email
+
+Sending an email is easy. A minimal email might look like this.
+
+```ruby
+Apostle::Mail.new('welcome_email', email: "mal@mal.co.nz").deliver!
+```
+The first param `Apostle::Mail` expects is the template slug, and the second is a hash of mail information.
+
+### Adding data
+
+You can assign any data you want, and it will be passed to the API for hydrating your template. If you had a template that required `{{username}}`, you could send them like this:
+
+```ruby
+mail = Apostle::Mail.new('welcome_email', email: 'mal@mal.co.nz', username: 'Snikch').deliver!
+```
+
+You can also set any data directly on the mail object.
+
+```ruby
+mail = Apostle::Mail.new('welcome_email')
+mail.email = 'mal@mal.co.nz'
+mail.username = 'Snikch'
+mail.deliver!
+```
+
+### Setting name
+
+In addition to the email, you can provide the name to be used in the `to` field of the email.
+
+```ruby
+Apostle::Mail.new('welcome_email', email: "mal@mal.co.nz", name: "Mal Curtis").deliver!
+# Sends email with "to: Mal Curtis <mal@mal.co.nz>"
+```
+
+### Setting from address
+
+Although the `from` address is set up in your template, you can override that for any individual email, or provide a reply to address.
+
+```ruby
+mail.from = 'support@example.com'
+mail.reply_to = 'noreply@example.com'
+```
+
+
+### Additional Headers
+
+You can provide custom headers to be sent with your email via `#header`.
+
+```ruby
+# Set
+mail.header 'X-Some-Header', 'my custom header'
+
+# Get
+mail.header 'X-Some-Header'
+=> "my custom header"
+```
+
+## Sending Multiple Emails
+
+To speed up processing, you can send more than one email at a time.
+
+```ruby
+queue = Apostle::Queue.new
+
+3.times do |count|
+	queue << Apostle::Mail.new("welcome_email", email: "user#{count}@example.com")
+end
+
+queue.deliver!
+```
+
+If any of the emails are invalid this will raise an exception and no emails will be sent; i.e. missing a template slug, or delivery address.
+
+You can either catch `Apostle::DeliveryError`, or call the safer `#deliver`, then access a hash of results on the queue via `#results`.
+
+```ruby
+queue = Apostle::Queue.new
+
+queue << Apostle::Mail.new("welcome_email", email: "mal@mal.co.nz")
+queue << Apostle::Mail.new("welcome_email")
+
+queue.deliver
+=> false
+
+queue.results
+=> {
+	:valid=>[#<Apostle::Mail:0x007fcee5ab2550>],
+	:invalid=>[#<Apostle::Mail:0x007fcee5ab23c0>]
+}
+queue.results[:invalid].first._exception
+=> #<Apostle::DeliveryError @message="No recipient provided">
+```
+
+### Helpers
+
+You have access to `#size` and `#clear` on the queue. You can use this to group requests.
+
+```ruby
+users.each do |user|
+	queue << Penpan::Mail.new('welcome', email: user.email)
+	if queue.size == 1000
+		queue.deliver
+		queue.clear
+	end
+end
+```
+
+Or use the helper method `#flush`, which does exactly this, calls `#deliver` then `#clear` if delivery succeeds.
+
+```ruby
+users.each do |user|
+	queue << Penpan::Mail.new('welcome', email: user.email)
+	if queue.size == 1000
+		queue.flush
+	end
+end
+```
+
+## Delivery Failure
+
+If delivery to Apostle fails, an exception will be raised. There are various events that could cause a failure:
+
+* `Apostle::Unauthorized`: The domain key was not provided, or valid
+* `Apostle::UnprocessableEntity`: The server returned a 422 response. Check the content of the message for more details, but this will likely be a validation / content error
+* `Apostle::ServerError`: Something went wrong at the Apostle API, you should try again with exponential backoff
+* `Apostle::Forbidden`: The server returned a 403 response. This should not occur on the delivery API
+* `Apostle::DeliveryError`: Anything which isn't covered by the above exceptions
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/apostle/mail.rb

@@ -0,0 +1,91 @@
+require 'net/http'
+require 'json'
+
+module Apostle
+
+  class Mail
+
+    attr_accessor :data,
+      :email,
+      :from,
+      :headers,
+      :layout_id,
+      :name,
+      :reply_to,
+      :template_id,
+      :_exception
+
+    def initialize(template_id, options = {})
+      @template_id = template_id
+      @data = {}
+
+      options.each do |k, v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    # Provide a getter and setters for headers
+    def header(name, value = nil)
+      if value
+        (@headers ||= {})[name] = value
+      else
+        (@headers || {})[name]
+      end
+    end
+
+    # Allow convenience setters for the data payload
+    # E.G. mail.potato= "Something" will set @data['potato']
+    def method_missing(method, *args)
+      return unless method.match /.*=/
+      @data[method.to_s.gsub(/=$/, '')] = args.first
+    end
+
+    def deliver
+      begin
+        deliver!
+        true
+      rescue DeliveryError => e
+        false
+      end
+    end
+
+    # Shortcut method to deliver a single message
+    def deliver!
+      return true unless Apostle.deliver
+
+      unless template_id && template_id != ""
+        raise DeliveryError,
+          "No email template_id provided"
+      end
+
+      queue = Apostle::Queue.new
+      queue.add self
+      queue.deliver!
+
+      # Return true or false depending on successful delivery
+      if queue.results[:valid].include?(self)
+        return true
+      else
+        raise _exception
+      end
+    end
+
+    def to_h
+      {
+        "#{self.email.to_s}" => {
+          "data" => @data,
+          "from" => from.to_s,
+          "headers" => headers,
+          "layout_id" => layout_id.to_s,
+          "name" => name.to_s,
+          "reply_to" => reply_to.to_s,
+          "template_id" => template_id.to_s
+        }.delete_if { |k, v| !v || v == '' }
+      }
+    end
+
+    def to_json
+      JSON.generate(to_h)
+    end
+  end
+end

data/lib/apostle/queue.rb

@@ -0,0 +1,150 @@
+require 'json'
+
+module Apostle
+
+  class Queue
+
+    attr_accessor :emails, :results
+
+    def initialize
+      @emails = []
+    end
+
+    def <<(email)
+      add(email)
+    end
+
+    def add(email)
+      @emails << email
+    end
+
+    def size
+      emails.size
+    end
+
+    def clear
+      emails = []
+      results = nil
+    end
+
+    def flush
+      deliver && clear
+    end
+
+    def deliver
+      deliver!
+    rescue DeliveryError
+      false
+    end
+
+    def deliver!
+      return true unless Apostle.deliver
+
+      # Validate the minimum requirement of a recipient and template
+      unless Apostle.domain_key
+        raise DeliveryError,
+          "No Apostle Domain Key has been defined. Preferably this should be in your environment, as ENV['APOSTLE_DOMAIN_KEY']. If you need to configure this manually, you can call Apostle.configure.
+
+      Apostle.configure do |config|
+        config.domain_key = 'Your domain key'
+      end"
+      end
+
+      raise DeliveryError, "Mail queue is empty" if emails.size == 0
+
+      payload, @results = process_emails
+
+      if @results[:invalid].size > 0
+        raise DeliveryError,
+          "Invalid emails: #{@results[:invalid].size}"
+      end
+
+      # Deliver the payload
+      response = deliver_payload(payload)
+
+      true
+    end
+
+    private
+
+    def process_emails
+      results = { valid: [], invalid: [] }
+
+      payload = {recipients: {}}
+
+      emails.each do |mail|
+        # Validate each mail
+        begin
+          unless mail.email && mail.email != ""
+            raise DeliveryError,
+              "No recipient provided"
+          end
+
+          unless mail.template_id && mail.template_id != ""
+            raise DeliveryError,
+              "No email template_id provided"
+          end
+
+          payload[:recipients].merge!(mail.to_h)
+          results[:valid] << mail
+        rescue => e
+          results[:invalid] << mail
+          mail._exception = e
+        end
+      end
+
+      [payload, results]
+    end
+
+    def deliver_payload(payload)
+      delivery_api = Apostle.delivery_host
+
+      req = Net::HTTP::Post.new(
+        "/",
+        'Content-Type' =>'application/json',
+        "Authorization" => "Bearer #{Apostle.domain_key}")
+      if delivery_api.user
+        req.basic_auth delivery_api.user, delivery_api.password
+      end
+      req.body = JSON.generate(payload)
+      response = Net::HTTP.
+        new(delivery_api.host, delivery_api.port).
+        start do |http|
+          http.request(req)
+        end
+
+      # Successful request
+      if [200, 201, 202].include?(response.code.to_i)
+        return true
+      end
+
+      begin
+        json = JSON.parse(response.body)
+      rescue JSON::ParserError
+        json = {}
+      end
+
+      if json["message"]
+        message = json["message"]
+      else
+        response.body
+      end
+
+      raise case response.code.to_i
+      when 401
+        Apostle::Unauthorized
+      when 403
+        Apostle::Forbidden
+      when 422
+        Apostle::UnprocessableEntity
+      when 500
+        Apostle::ServerError
+      else
+        Apostle::DeliveryError
+      end, message
+
+      response
+    end
+
+  end
+end

data/lib/apostle/version.rb

@@ -0,0 +1,3 @@
+module Apostle
+  VERSION = "0.0.1"
+end

data/lib/apostle.rb

@@ -0,0 +1,53 @@
+require "apostle/version"
+require 'apostle/mail'
+require 'apostle/queue'
+require 'uri'
+
+module Apostle
+  @@delivery_host = URI(ENV['APOSTLE_DELIVERY_HOST'] || 'http://deliver.apostle.io')
+  @@domain_key = ENV['APOSTLE_DOMAIN_KEY']
+  @@deliver = true
+
+  def self.delivery_host=(host)
+    @@delivery_host = host
+  end
+
+  # Lazily create a delivery_host URI
+  def self.delivery_host
+    if @@delivery_host.is_a?(URI)
+      @@delivery_host
+    else
+      URI(@@delivery_host)
+    end
+  end
+
+  def self.domain_key=(key)
+    @@domain_key = key
+  end
+
+  def self.domain_key
+    @@domain_key
+  end
+
+  def self.deliver=(bool)
+    @@deliver = !!bool
+  end
+
+  def self.deliver
+    @@deliver
+  end
+
+  class << self
+    def configure
+      yield self
+    end
+  end
+
+  Error = Class.new(StandardError)
+  DeliveryError = Class.new(Error)
+  Unauthorized = Class.new(DeliveryError)
+  Forbidden = Class.new(DeliveryError)
+  UnprocessableEntity = Class.new(DeliveryError)
+  ServerError = Class.new(DeliveryError)
+
+end

data/penpal.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/apostle/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Mal Curtis"]
+  gem.email         = ["mal@sitepoint.com"]
+  gem.description   = %q{: Write a gem description}
+  gem.summary       = %q{: Write a gem summary}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "apostle"
+  gem.require_paths = ["lib"]
+  gem.version       = Apostle::VERSION
+
+  gem.add_development_dependency "minitest"
+  gem.add_development_dependency "webmock"
+end

data/spec/mail_spec.rb

@@ -0,0 +1,65 @@
+require_relative 'spec_helper'
+require 'apostle'
+
+describe Apostle::Mail do
+  before do
+    Apostle.configure do |config|
+     config.domain_key = "abc"
+    end
+  end
+
+  describe "#initialize" do
+    it "assigns template and attributes" do
+      mail = Apostle::Mail.new "template_slug",
+        email: "email address",
+        unknown_key: "val"
+
+      mail.email.must_equal "email address"
+      mail.template_id.must_equal "template_slug"
+      mail.data.must_equal({ "unknown_key" => "val" })
+    end
+  end
+
+  describe "#deliver!" do
+    it "returns raises an exception without a template id" do
+      mail = Apostle::Mail.new nil
+      expect(mail.deliver!).to raise_error(Apostle::DeliveryError, "No template")
+    end
+
+    it "delegates to a queue" do
+    end
+
+    it "raises any error returned"
+  end
+
+  describe "to_json" do
+    it "returns a json representaion of the hash"
+  end
+
+  describe "to_h" do
+    it "returns a hash of attributes" do
+      mail = Apostle::Mail.new "template_slug"
+      mail.from = :f
+      mail.email = 123
+      mail.reply_to = "someone"
+      mail.name = "name"
+      mail.data = { "Hello" => "World" }
+      mail.foo = 'Bar'
+      mail.to_h.must_equal({"123" => {
+        "template_id" => "template_slug",
+        "from" => "f",
+        "reply_to" => "someone",
+        "name" => "name",
+        "data" => { "Hello" => "World", "foo" => "Bar"}
+      }})
+    end
+    it "removes nil entries" do
+      mail = Apostle::Mail.new "slug"
+      mail.email = "to"
+      mail.to_h.must_equal({"to" => {
+        "template_id" => "slug",
+        "data" => {}
+      }})
+    end
+  end
+end

data/spec/queue_spec.rb

@@ -0,0 +1,59 @@
+require_relative 'spec_helper'
+
+Apostle.domain_key = "abc123"
+
+describe Apostle::Queue do
+  it "sends the auth header" do
+    stub = stub_request(:any, Apostle.delivery_host.to_s).with(
+      headers: { "Authorization" => "Bearer abc123" }
+    )
+    queue = Apostle::Queue.new
+    queue.send :deliver_payload, {}
+    assert_requested(stub)
+  end
+
+  it "sends grouped requests" do
+    queue = Apostle::Queue.new
+    mail1 = Apostle::Mail.new "slug1", email: "recipient1"
+    mail2 = Apostle::Mail.new "slug2", email: "recipient2"
+
+    queue << mail1
+    queue << mail2
+
+    queue.emails.must_equal([mail1, mail2])
+
+    payload, results = queue.send :process_emails
+    results.must_equal({valid: [mail1, mail2], invalid: []})
+    payload.must_equal({
+      recipients: {
+        "recipient1" => {"template_id" => "slug1", "data" => {} },
+        "recipient2" => {"template_id" => "slug2", "data" => {} }
+      }
+    })
+  end
+
+  it "validates emails" do
+    queue = Apostle::Queue.new
+    mail1 = Apostle::Mail.new nil, email: "recipient1@example.com"
+    mail2 = Apostle::Mail.new "slug2"
+
+    queue << mail1
+    queue << mail2
+
+    queue.emails.must_equal([mail1, mail2])
+
+    payload, results = queue.send :process_emails
+    results.must_equal({invalid: [mail1, mail2], valid: []})
+
+    mail1._exception.message.must_equal("No email template_id provided")
+    mail2._exception.message.must_equal("No recipient provided")
+    payload[:recipients].must_equal({})
+  end
+
+  describe "#deliver" do
+    it "returns false if no delivery occurs" do
+      queue = Apostle::Queue.new
+      queue.deliver.must_equal(false)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require "minitest/autorun"
+require 'webmock/minitest'
+
+$LOAD_PATH.unshift "./lib"
+require "apostle"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: apostle
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mal Curtis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70173682453920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70173682453920
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: &70173682452780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70173682452780
+description: ': Write a gem description'
+email:
+- mal@sitepoint.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/apostle.rb
+- lib/apostle/mail.rb
+- lib/apostle/queue.rb
+- lib/apostle/version.rb
+- penpal.gemspec
+- spec/mail_spec.rb
+- spec/queue_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: ': Write a gem summary'
+test_files:
+- spec/mail_spec.rb
+- spec/queue_spec.rb
+- spec/spec_helper.rb
+has_rdoc: