html-griddler 0.1.2

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Caleb Thompson, Joel Oliveira and thoughtbot, inc.
+
+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,154 @@
+Griddler
+========
+
+### Receive emails in your Rails app
+
+Griddler is a Rails engine (full plugin) that provides an endpoint for the
+[SendGrid parse api](http://sendgrid.com/docs/API%20Reference/Webhooks/parse.html)
+that hands off a built email object to a class implemented by you.
+
+Tutorials
+---------
+
+* SendGrid has done a
+  [great tutorial](http://blog.sendgrid.com/receiving-email-in-your-rails-app-with-griddler/)
+  on integrating Griddler with your application.
+* And of course, view our own blog post on the subject over at
+  [Giant Robots](http://robots.thoughtbot.com/post/42286882447/handle-incoming-email-with-griddler).
+
+Installation
+------------
+
+Add griddler to your application's Gemfile and run `bundle install`:
+
+```ruby
+gem 'griddler'
+```
+
+Griddler comes with a default endpoint that will be displayed at the bottom
+of the output of `rake routes`. If there is a previously defined route that
+matches `/email_processor` -- or you would like to rename the matched path -- you
+may add the route to the desired position in routes.rb with the following:
+
+```ruby
+post '/email_processor' => 'griddler/emails#create'
+```
+
+Defaults
+--------
+
+By default Griddler will look for a class to be created in your application
+called EmailProcessor with a class method implemented, named process, taking
+in one argument (presumably `email`). For example, in `./lib/email_processor.rb`:
+
+```ruby
+class EmailProcessor
+  def self.process(email)
+    # all of your application-specific code here - creating models,
+    # processing reports, etc
+  end
+end
+```
+
+The contents of the `email` object passed into your process method is an object
+that responds to:
+
+* `.to`
+* `.from`
+* `.subject`
+* `.body`
+* `.raw_body`
+
+Each of those has some sensible defaults.
+
+`.from`, `.raw_body` and `.subject` will contain the obvious values found in the email, the raw values from those fields.
+
+`.body` will contain the full contents of the email body **unless** there is a
+line in the email containing the string `-- Reply ABOVE THIS LINE --`. In that
+case `.body` will contain everything before that line.
+
+`.to` will contain all of the text before the email's "@" character. We've found
+that this is the most often used portion of the email address and consider it to
+be the token we'll key off of for interaction with our application.
+
+Configuration Options
+---------------------
+
+An initializer can be created to control some of the options in Griddler. Defaults
+are shown below with sample overrides following. In `config/initializer/griddler.rb`:
+
+```ruby
+Griddler.configure do |config|
+  config.processor_class = EmailProcessor # MyEmailProcessor
+  config.to = :token # :raw, :email, :hash
+  # :raw    => 'AppName <s13.6b2d13dc6a1d33db7644@mail.myapp.com>'
+  # :email  => 's13.6b2d13dc6a1d33db7644@mail.myapp.com'
+  # :token  => 's13.6b2d13dc6a1d33db7644'
+  # :hash   => { raw: '', email: '', token: '', host: '' }
+  config.reply_delimiter = '-- REPLY ABOVE THIS LINE --'
+end
+```
+
+* `config.processor_class` is the class Griddler will use to handle your incoming emails.
+* `config.reply_delimiter` is the string searched for that will split your body.
+* `config.to` is the format of the returned value for the `:to` key in
+the email object. `:hash` will return all options within a -- (surprise!) -- hash.
+
+Testing In Your App
+-------------------
+
+You may want to create a factory for when testing the integration of Griddler into
+your application. If you're using factory_girl this can be accomplished with the
+following sample factory.
+
+```ruby
+factory :email, class: OpenStruct do
+  to 'email-token'
+  from 'user@email.com'
+  subject 'email subject'
+  body 'Hello!'
+  attachments {[]}
+
+  trait :with_attachment do
+    attachments {[
+      ActionDispatch::Http::UploadedFile.new({
+        filename: 'img.png',
+        type: 'image/png',
+        tempfile: File.new("#{File.expand_path File.dirname(__FILE__)}/fixtures/img.png")
+      })
+    ]}
+  end
+end
+```
+
+Bear in mind, if you plan on using the `:with_attachment` trait, that this
+example assumes your factories are in `spec/factories.rb` and you have
+an image file in `spec/fixtures/`.
+
+To use it in your test(s) just build with `email = build(:email)`
+or `email = build(:email, :with_attachment)`
+
+More Information
+----------------
+
+* [SendGrid](http://www.sendgrid.com)
+* [SendGrid Parse API](http://www.sendgrid.com/docs/API Reference/Webhooks/parse.html)
+
+Credits
+-------
+
+Griddler was written by Caleb Thompson and Joel Oliveira.
+
+Large portions of the codebase were extracted from thoughtbot's
+[Trajectory](http://www.apptrajectory.com).
+
+![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
+
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+License
+-------
+
+Griddler is Copyright © 2012 Caleb Thompson, Joel Oliveira and thoughtbot. It is
+free software, and may be redistributed under the terms specified in the LICENSE
+file.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/app/controllers/griddler/emails_controller.rb

@@ -0,0 +1,6 @@
+class Griddler::EmailsController < ActionController::Base
+  def create
+    Griddler::Email.new(params).process
+    head :ok
+  end
+end

data/config/initializers/griddler.rb

@@ -0,0 +1 @@
+require 'griddler'

data/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  post '/email_processor' => 'griddler/emails#create', as: :email_processor
+end

data/lib/html-griddler/configuration.rb

@@ -0,0 +1,33 @@
+module Griddler
+  @@configuration = nil
+
+  def self.configure
+    @@configuration = Configuration.new
+
+    if block_given?
+      yield configuration
+    end
+
+    configuration
+  end
+
+  def self.configuration
+    @@configuration || configure
+  end
+
+  class Configuration
+    attr_accessor :processor_class, :reply_delimiter, :to
+
+    def to
+      @to ||= :token
+    end
+
+    def processor_class
+      @processor_class ||= EmailProcessor
+    end
+
+    def reply_delimiter
+      @reply_delimiter ||= 'Reply ABOVE THIS LINE'
+    end
+  end
+end

data/lib/html-griddler/email.rb

@@ -0,0 +1,97 @@
+require 'htmlentities'
+
+class Griddler::Email
+  include ActionView::Helpers::SanitizeHelper
+  attr_reader :to, :from, :body, :raw_body, :subject, :attachments, :spam_score, :spam_report, :spf, :dkim
+
+  def initialize(params)
+    @params = params
+    @to = extract_address(params[:to], config.to)
+    @from = extract_address(params[:from], :email)
+    @subject = params[:subject]
+    @body = extract_body
+    @raw_body = params[:html] || params[:text]
+    @attachments = extract_attachments
+    @spam_score = params[:spam_score]
+    @spam_report = params[:spam_report]
+    @spf = params[:SPF]
+    @dkim = params[:dkim]
+  end
+
+  def process
+    processor_class = config.processor_class
+    processor_class.process(self)
+  end
+
+  private
+
+  attr_reader :params
+
+  def config
+    Griddler.configuration
+  end
+
+  def extract_address(address, type)
+    parsed = EmailParser.parse_address(address)
+
+    if type == :hash
+      parsed
+    else
+      parsed[type]
+    end
+  end
+
+  def extract_attachments
+    attachment_count = params[:attachments].to_i
+
+    attachment_count.times.map do |index|
+      params["attachment#{index + 1}".to_sym]
+    end
+  end
+
+  def extract_body
+    body_text = text_or_sanitized_html
+
+    if params[:charsets].present?
+      body_text = body_text.encode(
+        'UTF-8',
+        invalid: :replace,
+        undef: :replace,
+        replace: ''
+      ).force_encoding('UTF-8')
+    end
+
+    EmailParser.extract_reply_body(body_text)
+  end
+
+  def text_or_sanitized_html
+    if params.key? :html
+      clean_html(params[:html])
+    elsif params.key? :text
+      clean_html(params[:text])
+    else
+      raise Griddler::Errors::EmailBodyNotFound
+    end
+  end
+
+  def clean_text(text)
+    clean_invalid_utf8_bytes(text)
+  end
+
+  def clean_html(html)
+    cleaned_html = clean_invalid_utf8_bytes(html)
+    cleaned_html = strip_tags(cleaned_html)
+    cleaned_html = HTMLEntities.new.decode(cleaned_html)
+    cleaned_html
+  end
+
+  def clean_invalid_utf8_bytes(text)
+    text.encode(
+      'UTF-8',
+      'binary',
+      invalid: :replace,
+      undef: :replace,
+      replace: ''
+    )
+  end
+end

data/lib/html-griddler/email_parser.rb

@@ -0,0 +1,49 @@
+# Parse emails from their full format into a hash containing full email, host,
+# local token, and the raw argument.
+#
+# Some Body <somebody@example.com>
+# # => {
+#   token: 'somebody',
+#   host: 'example.com',
+#   email: 'somebody@example.com',
+#   full: 'Some Body <somebody@example.com>',
+# }
+module EmailParser
+  def self.parse_address(full_address)
+    email_address = extract_email_address(full_address)
+    token, host = split_address(email_address)
+    {
+      token: token,
+      host: host,
+      email: email_address,
+      full: full_address,
+    }
+  end
+
+  def self.extract_reply_body(body)
+    if body
+      delimeter = Griddler.configuration.reply_delimiter
+      body.split(delimeter).first.
+        split(/^\s*[-]+\s*Original Message\s*[-]+\s*$/).first.
+        split(/^\s*--\s*$/).first.
+        gsub(/On.*wrote:/, '').
+        split(/[\r]*\n/).reject do |line|
+          line =~ /^\s*>/ ||
+            line =~ /^\s*Sent from my /
+        end.
+        join("\n").
+        gsub(/^\s*On.*\r?\n?\s*.*\s*wrote:$/,'').
+        strip
+    end
+  end
+
+  private
+
+  def self.extract_email_address(full_address)
+    full_address.split('<').last.delete('>').strip
+  end
+
+  def self.split_address(email_address)
+    email_address.try :split, '@'
+  end
+end

data/lib/html-griddler/engine.rb

@@ -0,0 +1,4 @@
+module Griddler
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/html-griddler/errors.rb

@@ -0,0 +1,9 @@
+module Griddler
+  class Error < StandardError
+  end
+
+  module Errors
+    class EmailBodyNotFound < Griddler::Error
+    end
+  end
+end

data/lib/html-griddler/version.rb

@@ -0,0 +1,3 @@
+module HtmlGriddler
+  VERSION = "0.1.2"
+end

data/lib/html-griddler.rb

@@ -0,0 +1,8 @@
+require 'html-griddler/errors'
+require 'html-griddler/engine'
+require 'html-griddler/email'
+require 'html-griddler/email_parser'
+require 'html-griddler/configuration'
+
+module Griddler
+end

data/lib/tasks/griddler_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :griddler do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification 
+name: html-griddler
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.2
+platform: ruby
+authors: 
+- Sean Powell - forker :)
+- Original Authors
+- Caleb Thompson
+- Joel Oliveira
+- thoughtbot
+- Swift
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-02-20 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.2.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: htmlentities
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec-rails
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: jquery-rails
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: 
+email: 
+- sean@engageyourcause.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- app/controllers/griddler/emails_controller.rb
+- config/initializers/griddler.rb
+- config/routes.rb
+- lib/html-griddler/configuration.rb
+- lib/html-griddler/email.rb
+- lib/html-griddler/email_parser.rb
+- lib/html-griddler/engine.rb
+- lib/html-griddler/errors.rb
+- lib/html-griddler/version.rb
+- lib/html-griddler.rb
+- lib/tasks/griddler_tasks.rake
+- LICENSE
+- Rakefile
+- README.md
+homepage: http://htmlemailboilerplate.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- app
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Fork of Thoughtbot's SendGrid Parse API client Rails Engine for HTML Email Specific Applications
+test_files: []
+