RubyGems - sendgrid-ruby - Versions diffs - 1.0.5 → 1.1.5 - Mend

sendgrid-ruby 1.0.5 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

checksums.yaml +4 -4
data/.gitignore +0 -1
data/CHANGELOG.md +10 -3
data/README.md +62 -3
data/lib/sendgrid-ruby.rb +3 -0
data/lib/sendgrid/client.rb +5 -5
data/lib/sendgrid/mail.rb +16 -7
data/lib/sendgrid/recipient.rb +29 -0
data/lib/sendgrid/template.rb +26 -0
data/lib/sendgrid/template_mailer.rb +59 -0
data/lib/sendgrid/version.rb +1 -1
data/spec/lib/sendgrid/client_spec.rb +4 -0
data/spec/lib/sendgrid/mail_spec.rb +28 -0
data/spec/lib/sendgrid/recipient_spec.rb +91 -0
data/spec/lib/sendgrid/template_mailer_spec.rb +86 -0
data/spec/lib/sendgrid/template_spec.rb +61 -0
data/spec/lib/sendgrid_spec.rb +1 -1
metadata +11 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18a3e008f6b56eaf8822431e7b8ca475a82919aa
-  data.tar.gz: 376b2dae4fd84d6db306b3a30ea87350e549a79f
+  metadata.gz: 3c556cc58a72b04d8db231eb81396415aa3d5007
+  data.tar.gz: b86fde7d2356ecf19acc374aac5f429f0b425ea2
 SHA512:
-  metadata.gz: edbc9740e858675a0f030d8034b5a2ead47d27cd533528faab52f111f68b12a3093b872176746e9a1f9213234cfd69c2dc682188aa6df87459be2246b0d84aae
-  data.tar.gz: 7afef6adf85b26dc6e61786cb308e096c36a899aafc6e48b76f4f03cf5e7eff4c6250bc75c0759dd6a42a59d2370525d83d5507e5ec14dd0ca44b568ecf82c72
+  metadata.gz: b3138df821abe297098687b31936d15d50d49e712abae0fe2a34701e3a450f6526dacccc95166c8538bc3350a08f4f9a7894e809da2f4ab2da771576d98a3f84
+  data.tar.gz: 2127a04422ddd3a3c4061977c7b9f0ff394c150e4154c862a81d7d649cbd96e706d9fc6e741434d46760e6ff4ec518a04d0c87d44b2d1fb522696db1577ce2e9

data/.gitignore CHANGED Viewed

@@ -38,4 +38,3 @@ Gemfile.lock
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc

data/CHANGELOG.md CHANGED Viewed

@@ -1,14 +1,21 @@
 # Change Log
 All notable changes to this project will be documented in this file.
-## [1.0.5] - 2015-10-21
+## [1.1.5] - 2015-10-28 ##
+## Added
+Support for [Templates](https://github.com/sendgrid/sendgrid-ruby#working-with-templates) via [#28](https://github.com/sendgrid/sendgrid-ruby/pull/28)
+Thanks [Jake](https://github.com/yez)!
+## [1.0.5] - 2015-10-21 ##
 ### Fixed
 Remove puts from mail.rb [#29](https://github.com/sendgrid/sendgrid-ruby/pull/29)
-## [1.0.4] - 2015-10-06
+## [1.0.4] - 2015-10-06 ##
 ### Added
 Inline content support
-## [1.0.3] - 2015-10-01
+## [1.0.3] - 2015-10-01 ##
 ### Fixed
 Payload 'to' attribute fix for smtpapi

data/README.md CHANGED Viewed

@@ -106,11 +106,11 @@ params = {
 	:reply_to,
 	:date,
 	:smtpapi,
-	:attachments
+	:attachments,
+	:template
 }
 ```
 #### Setting Params
 Params can be set in the usual Ruby ways, including a block or a hash.
@@ -187,9 +187,67 @@ mail = SendGrid::Mail.new
 mail.html = '<html><body>Stuff in here, yo!</body></html>'
 ```
+#### :template
-## Using SendGrid's X-SMTPAPI Header
+The **:template** param allows us to specify a template object for this email to use. The initialized `Template` will automatically be included in the `smtpapi` header and passed to SendGrid.
+```ruby
+template = SendGrid::Template.new('MY_TEMPLATE_ID')
+mail.template = template
+```
+## Working with Templates
+Another easy way to use the [SendGrid Templating](https://sendgrid.com/docs/API_Reference/Web_API_v3/Template_Engine/index.html) system is with the `Recipient`, `Mail`, `Template`, and `TemplateMailer` objects.
+Create some `Recipients`
+```ruby
+users = User.where(email: ['first@gmail.com', 'second@gmail.com'])
+recipients = []
+users.each do |user|
+  recipient = SendGrid::Recipient.new(user.email)
+  recipient.add_substitution('first_name', user.first_name)
+  recipient.add_substitution('city', user.city)
+  recipients << recipient
+end
+```
+Create a `Template`
+```ruby
+template = SendGrid::Template.new('MY_TEMPLATE_ID')
+```
+Create a `Client`
+```ruby
+client = SendGrid::Client.new(api_user: my_user, api_key: my_key)
+```
+Initialize mail defaults and create the `TemplateMailer`
+```ruby
+mail_defaults = {
+  from: 'admin@email.com',
+  html: '<h1>I like email</h1>',
+  text: 'I like email',
+  subject: 'Email is great',
+}
+mailer = SendGrid::TemplateMailer.new(client, template, recipients)
+```
+Mail it!
+```ruby
+mailer.mail(mail_defaults)
+```
+## Using SendGrid's X-SMTPAPI Header
 <blockquote>
 To utilize the X-SMTPAPI header, we have directly integrated the <a href="https://github.com/SendGridJP/smtpapi-ruby">SendGridJP/smtpapi-ruby</a> gem.
@@ -233,3 +291,4 @@ mail.smtpapi = header
 5. Create a new Pull Request
 ***Hit up [@rbin](http://twitter.com/rbin) or [@sendgrid](http://twitter.com/sendgrid) on Twitter with any issues.***

data/lib/sendgrid-ruby.rb CHANGED Viewed

@@ -1,5 +1,8 @@
 require_relative 'sendgrid/client'
 require_relative 'sendgrid/exceptions'
+require_relative 'sendgrid/recipient'
+require_relative 'sendgrid/template'
+require_relative 'sendgrid/template_mailer'
 require_relative 'sendgrid/mail'
 require_relative 'sendgrid/response'
 require_relative 'sendgrid/version'

data/lib/sendgrid/client.rb CHANGED Viewed

@@ -3,7 +3,7 @@ require 'faraday'
 module SendGrid
   class Client
     attr_accessor :api_user, :api_key, :protocol, :host, :port, :url, :endpoint,
-                  :user_agent
+                  :user_agent, :template
     attr_writer :adapter, :conn, :raise_exceptions
     def initialize(params = {})
@@ -25,7 +25,7 @@ module SendGrid
       res = conn.post do |req|
         payload = mail.to_h
         req.url(endpoint)
         # Check if using username + password or API key
         if api_user
           # Username + password
@@ -34,12 +34,12 @@ module SendGrid
           # API key
           req.headers['Authorization'] = "Bearer #{api_key}"
         end
         req.body = payload
       end
       fail SendGrid::Exception, res.body if raise_exceptions? && res.status != 200
       SendGrid::Response.new(code: res.status, headers: res.headers, body: res.body)
     end

data/lib/sendgrid/mail.rb CHANGED Viewed

@@ -5,12 +5,13 @@ require 'mimemagic'
 module SendGrid
   class Mail
     attr_accessor :to, :to_name, :from, :from_name, :subject, :text, :html, :cc,
-                  :bcc, :reply_to, :date, :smtpapi, :attachments, :content
+                  :bcc, :reply_to, :date, :smtpapi, :attachments, :content, :template
     def initialize(params = {})
       params.each do |k, v|
         send(:"#{k}=", v) unless v.nil?
       end
       yield self if block_given?
     end
@@ -103,11 +104,11 @@ module SendGrid
     def attachments
       @attachments ||= []
     end
     def contents
       @contents ||= []
     end
     def add_content(path, cid)
       mime_type = MimeMagic.by_path(path)
       file = Faraday::UploadIO.new(path, mime_type)
@@ -119,6 +120,14 @@ module SendGrid
       @smtpapi ||= Smtpapi::Header.new
     end
+    def smtpapi_json
+      if !template.nil? && template.is_a?(Template)
+        template.add_to_smtpapi(smtpapi)
+      end
+      smtpapi.to_json
+    end
     # rubocop:disable Style/HashSyntax
     def to_h
       payload = {
@@ -133,7 +142,7 @@ module SendGrid
         :bcc => bcc,
         :text => text,
         :html => html,
-        :'x-smtpapi' => smtpapi.to_json,
+        :'x-smtpapi' => smtpapi_json,
         :content => ({":default"=>"0"} unless contents.empty?),
         :files => ({":default"=>"0"} unless attachments.empty? and contents.empty?)
         # If I don't define a default value, I get a Nil error when
@@ -144,7 +153,7 @@ module SendGrid
       payload.delete(:'x-smtpapi') if payload[:'x-smtpapi'] == '{}'
       payload[:to] = payload[:from] if payload[:to].nil? and not smtpapi.to.empty?
       unless attachments.empty?
         attachments.each do |file|
           payload[:files][file[:name]] = file[:file]
@@ -153,7 +162,7 @@ module SendGrid
           payload[:files].delete(":default")
         end
       end
       unless contents.empty?
         contents.each do |content|
           payload[:content][content[:name]] = content[:cid]
@@ -163,7 +172,7 @@ module SendGrid
           payload[:content].delete(":default")
         end
       end
       payload
     end
     # rubocop:enable Style/HashSyntax

data/lib/sendgrid/recipient.rb ADDED Viewed

@@ -0,0 +1,29 @@
+require 'smtpapi'
+module SendGrid
+  class Recipient
+    class NoAddress < StandardError; end
+    attr_reader :address, :substitutions
+    def initialize(address)
+      @address = address
+      @substitutions = {}
+      raise NoAddress, 'Recipient address cannot be nil' if @address.nil?
+    end
+    def add_substitution(key, value)
+      substitutions[key] = value
+    end
+    def add_to_smtpapi(smtpapi)
+      smtpapi.add_to(@address)
+      @substitutions.each do |key, value|
+        existing = smtpapi.sub[key] || []
+        smtpapi.add_substitution(key, existing + [value])
+      end
+    end
+  end
+end

data/lib/sendgrid/template.rb ADDED Viewed

@@ -0,0 +1,26 @@
+require 'smtpapi'
+module SendGrid
+  class Template
+    attr_reader :id, :recipients
+    def initialize(id)
+      @id = id
+      @recipients = []
+    end
+    def add_recipient(recipient)
+      recipients << recipient
+    end
+    def add_to_smtpapi(smtpapi)
+      return if smtpapi.nil?
+      smtpapi.tap do |api|
+        api.add_filter(:templates, :enable, 1)
+        api.add_filter(:templates, :template_id, id)
+        recipients.each { |r| r.add_to_smtpapi(smtpapi) }
+      end
+    end
+  end
+end

data/lib/sendgrid/template_mailer.rb ADDED Viewed

@@ -0,0 +1,59 @@
+module SendGrid
+  class InvalidClient < StandardError; end
+  class InvalidTemplate < StandardError; end
+  class InvalidRecipients < StandardError; end
+  class TemplateMailer
+    # This class is responsible for coordinating the responsibilities
+    #  of various models in the gem.
+    # It makes use of the Recipient, Template and Mail models to create
+    #  a single work flow, an example might look like:
+    #
+    # users = User.where(email: ['first@gmail.com', 'second@gmail.com'])
+    #
+    # recipients = []
+    #
+    # users.each do |user|
+    #   recipient = SendGrid::Recipient.new(user.email)
+    #   recipient.add_substitution('first_name', user.first_name)
+    #   recipient.add_substitution('city', user.city)
+    #
+    #   recipients << recipient
+    # end
+    #
+    # template = SendGrid::Template.new('MY_TEMPLATE_ID')
+    #
+    # client = SendGrid::Client.new(api_user: my_user, api_key: my_key)
+    #
+    # mail_defaults = {
+    #   from: 'admin@email.com',
+    #   html: '<h1>I like email</h1>',
+    #   text: 'I like email',
+    #   subject: 'Email is great',
+    # }
+    #
+    # mailer = SendGrid::TemplateMailer.new(client, template, recipients)
+    # mailer.mail(mail_defaults)
+    def initialize(client, template, recipients = [])
+      @client = client
+      @template = template
+      @recipients = recipients
+      raise InvalidClient, 'Client must be present' if @client.nil?
+      raise InvalidTemplate, 'Template must be present' if @template.nil?
+      raise InvalidRecipients, 'Recipients may not be empty' if @recipients.empty?
+      @recipients.each do |recipient|
+        @template.add_recipient(recipient)
+      end
+    end
+    def mail(params = {})
+      mail = Mail.new(params)
+      mail.template = @template
+      @client.send(mail.to_h)
+    end
+  end
+end

data/lib/sendgrid/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module SendGrid
-  VERSION = '1.0.5'
+  VERSION = '1.1.5'
 end

data/spec/lib/sendgrid/client_spec.rb CHANGED Viewed

@@ -23,6 +23,10 @@ describe 'SendGrid::Client' do
     expect(SendGrid::Client.new.endpoint).to eq('/api/mail.send.json')
   end
+  it 'accepts a block' do
+    expect { |b| SendGrid::Client.new(&b) }.to yield_control
+  end
   describe ':send' do
     it 'should make a request to sendgrid' do
       stub_request(:any, 'https://api.sendgrid.com/api/mail.send.json')

data/spec/lib/sendgrid/mail_spec.rb CHANGED Viewed

@@ -120,4 +120,32 @@ describe 'SendGrid::Mail' do
       expect(@mail.reply_to).to eq('foo@example.com')
     end
   end
+  describe 'smtpapi_json' do
+    before do
+      @mail.template = template
+    end
+    context 'a template has been set' do
+      let(:template) { SendGrid::Template.new(anything) }
+      it 'adds the template to the smtpapi header' do
+        expect(@mail.template).to receive(:add_to_smtpapi).with(@mail.smtpapi)
+        expect(@mail.smtpapi).to receive(:to_json)
+        @mail.to_h
+      end
+    end
+    context 'no template has been set' do
+      let(:template) { nil }
+      it 'does not add anything to the smtpapi header' do
+        expect_any_instance_of(SendGrid::Template).to_not receive(:add_to_smtpapi)
+        expect(@mail.smtpapi).to receive(:to_json)
+        @mail.to_h
+      end
+    end
+  end
 end

data/spec/lib/sendgrid/recipient_spec.rb ADDED Viewed

@@ -0,0 +1,91 @@
+require_relative '../../../lib/sendgrid/recipient'
+module SendGrid
+  describe Recipient do
+    subject { described_class.new(anything) }
+    describe '#initialize' do
+      it 'sets the address instance var' do
+        expect(subject.instance_variable_get(:@address)).to_not be_nil
+      end
+      it 'sets substitutions to an empty hash' do
+        expect(subject.instance_variable_get(:@substitutions)).to eq({})
+      end
+      context 'initialized with nil' do
+        it 'raises an error' do
+          expect do
+            described_class.new(nil)
+          end.to raise_error(Recipient::NoAddress, 'Recipient address cannot be nil')
+        end
+      end
+    end
+    describe '#add_substitution' do
+      it 'adds the key and value to the substitutions hash' do
+        subject.add_substitution(:foo, :bar)
+        expect(subject.substitutions).to have_key(:foo)
+        expect(subject.substitutions[:foo]).to eq(:bar)
+      end
+      context 'the same substiution key already exists' do
+        before do
+          subject.add_substitution(:foo, :bar)
+        end
+        it 'replaces the value' do
+          subject.add_substitution(:foo, :baz)
+          expect(subject.substitutions).to have_key(:foo)
+          expect(subject.substitutions[:foo]).to eq(:baz)
+        end
+      end
+    end
+    describe '#add_to_smtpapi' do
+      let(:substitutions) { { foo: :bar, baz: :qux } }
+      let(:smtp_api) { Smtpapi::Header.new }
+      before do
+        substitutions.each do |key, value|
+          subject.add_substitution(key, value)
+        end
+      end
+      it 'adds the address' do
+        expect(smtp_api).to receive(:add_to)
+        subject.add_to_smtpapi(smtp_api)
+      end
+      it 'calls add_substitution as many times as there are substitution keys' do
+        substitutions.each do |key, value|
+          expect(smtp_api).to receive(:add_substitution).with(key, [value])
+        end
+        subject.add_to_smtpapi(smtp_api)
+      end
+      context 'a substitution for the same key already exists' do
+        let(:substitutions) { { foo: :bar } }
+        let(:added_value) { [:bar, :rab] }
+        before do
+          smtp_api.add_substitution(:foo, [:rab])
+        end
+        it 'adds to it' do
+          expect(smtp_api).to receive(:add_substitution).with(:foo, array_including(added_value))
+          subject.add_to_smtpapi(smtp_api)
+        end
+      end
+      context 'substitutions is empty' do
+        let(:substitutions) { {} }
+        it 'does nothing' do
+          expect(smtp_api).to_not receive(:add_substitution)
+          subject.add_to_smtpapi(smtp_api)
+        end
+      end
+    end
+  end
+end

data/spec/lib/sendgrid/template_mailer_spec.rb ADDED Viewed

@@ -0,0 +1,86 @@
+require_relative '../../../lib/sendgrid/template_mailer'
+module SendGrid
+  describe TemplateMailer do
+    let(:client) { anything }
+    let(:template) { Template.new(anything) }
+    let(:recipients) { [Recipient.new(anything)] }
+    describe '#initialize' do
+      let(:client) { anything }
+      let(:template) { Template.new(anything) }
+      let(:recipients) { [anything] }
+      subject { described_class.new(client, template, recipients) }
+      it 'sets the instance variables' do
+        expect(subject.instance_variable_get(:@client)).to_not be_nil
+        expect(subject.instance_variable_get(:@template)).to_not be_nil
+        expect(subject.instance_variable_get(:@recipients)).to_not be_nil
+      end
+      context 'nil variables' do
+        context 'template is nil' do
+          let(:template) { nil }
+          it 'raises error' do
+            expect do
+              subject
+            end.to raise_error(InvalidTemplate, 'Template must be present')
+          end
+        end
+        context 'client is nil' do
+          let(:client) { nil }
+          it 'raises error' do
+            expect do
+              subject
+            end.to raise_error(InvalidClient, 'Client must be present')
+          end
+        end
+      end
+      context 'recipients' do
+        let(:first_recipient) { Recipient.new('someone@anything.com') }
+        let(:second_recipient) { Recipient.new('test@test.com') }
+        let(:recipients) { [first_recipient, second_recipient] }
+        it 'adds them to the template' do
+          expect(template).to receive(:add_recipient).with(first_recipient)
+          expect(template).to receive(:add_recipient).with(second_recipient)
+          subject
+        end
+      end
+    end
+    describe '#mail' do
+      subject { described_class.new(client, template, recipients) }
+      let(:mail_params) { {} }
+      let(:mail_to_h) { '' }
+      before do
+        allow(subject).to receive(:mail_params) { mail_params }
+        allow_any_instance_of(Mail).to receive(:to_h) { mail_to_h }
+        allow(client).to receive(:send)
+      end
+      it 'creates a new mail object' do
+        expect(Mail).to receive(:new).with(mail_params).and_call_original
+        subject.mail
+      end
+      it 'adds the template to the mail object' do
+        expect_any_instance_of(Mail).to receive(:template=).with(template)
+        subject.mail
+      end
+      it 'calls send on the client with the mail object' do
+        expect(client).to receive(:send).with(mail_to_h)
+        subject.mail
+      end
+    end
+  end
+end

data/spec/lib/sendgrid/template_spec.rb ADDED Viewed

@@ -0,0 +1,61 @@
+require_relative '../../../lib/sendgrid/template'
+module SendGrid
+  describe Template do
+    let(:id) { anything }
+    subject { described_class.new(id) }
+    describe '#initialize' do
+      it 'sets the id instance var' do
+        expect(subject.instance_variable_get(:@id)).to_not be_nil
+      end
+    end
+    describe '#add_to_smtpapi' do
+      let(:id) { rand(8999) }
+      let(:smtpapi) { Smtpapi::Header.new }
+      it 'adds enabled and the templates id' do
+        expect(smtpapi).to receive(:add_filter).with(:templates, :enable, 1)
+        expect(smtpapi).to receive(:add_filter).with(:templates, :template_id, id)
+        subject.add_to_smtpapi(smtpapi)
+      end
+      context 'smtpapi is nil' do
+        it 'does not error' do
+          expect do
+            subject.add_to_smtpapi(nil)
+          end.to_not raise_error
+        end
+      end
+      context 'with recipients' do
+        let(:substitution_key) { :foo }
+        let(:substitution_value) { :bar }
+        let(:recipients) do
+          [].tap do |recipients|
+            3.times.each do
+              r = Recipient.new("test+#{ rand(100) }@example.com")
+              r.add_substitution(substitution_key, substitution_value)
+              recipients << r
+            end
+          end
+        end
+        before do
+          recipients.each do |r|
+            subject.add_recipient(r)
+          end
+        end
+        it 'calls the recipients call to add to smtpapi' do
+          recipients.each do |recipient|
+            expect(recipient).to receive(:add_to_smtpapi).with(smtpapi)
+          end
+          subject.add_to_smtpapi(smtpapi)
+        end
+      end
+    end
+  end
+end

data/spec/lib/sendgrid_spec.rb CHANGED Viewed

@@ -2,6 +2,6 @@ require 'spec_helper'
 describe 'SendGrid' do
   it 'should have a version' do
-    expect(SendGrid::VERSION).to eq('1.0.5')
+    expect(SendGrid::VERSION).to eq('1.1.5')
   end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sendgrid-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.1.5
 platform: ruby
 authors:
 - Robin Johnson
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2015-10-21 00:00:00.000000000 Z
+date: 2015-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: smtpapi
@@ -215,11 +215,17 @@ files:
 - lib/sendgrid/client.rb
 - lib/sendgrid/exceptions.rb
 - lib/sendgrid/mail.rb
+- lib/sendgrid/recipient.rb
 - lib/sendgrid/response.rb
+- lib/sendgrid/template.rb
+- lib/sendgrid/template_mailer.rb
 - lib/sendgrid/version.rb
 - sendgrid-ruby.gemspec
 - spec/lib/sendgrid/client_spec.rb
 - spec/lib/sendgrid/mail_spec.rb
+- spec/lib/sendgrid/recipient_spec.rb
+- spec/lib/sendgrid/template_mailer_spec.rb
+- spec/lib/sendgrid/template_spec.rb
 - spec/lib/sendgrid_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/sendgrid/sendgrid-ruby
@@ -249,5 +255,8 @@ summary: Official SendGrid Gem
 test_files:
 - spec/lib/sendgrid/client_spec.rb
 - spec/lib/sendgrid/mail_spec.rb
+- spec/lib/sendgrid/recipient_spec.rb
+- spec/lib/sendgrid/template_mailer_spec.rb
+- spec/lib/sendgrid/template_spec.rb
 - spec/lib/sendgrid_spec.rb
 - spec/spec_helper.rb