mailclerk 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e38216e89dcd97a31456876ff58694230dfc67b2285c3540ff0677092d5db47
-  data.tar.gz: 90fc4a982810cc11a85adc7276d69bffbc168d034bdda9e6147ac546e50c6dd5
+  metadata.gz: a0411122cd662e0f7e37bfeb21853e818ecc8ec6e91fa54ad21ead1fad9ac998
+  data.tar.gz: 4b62af5e3f1b1e4e252c31f97d488cec0ee2e59d2023761c2b69fb83c7afa8d1
 SHA512:
-  metadata.gz: 6fe8289fad0d470fc1a664a5ec30d8e4c4de8ec6bd6500aa9e0c6fa87a96ad5279b3f7f842a1897e04f3c734f0c7ed38ba1592b58acfe4871152339ead2272e7
-  data.tar.gz: eb9d243468bc8205fdde9f62f460355595eddd9bebc66b80ebab8e7435c3197ee4939c05531219d08c18ad59c2e28880b5a4b140ff9ecda8a47e54d0a0261169
+  metadata.gz: 47d25d797fd25b415c8c251e464539df9544dd9863716ad37cc2b6bae843fe61f49c39f6853ff74d994239e920895db290282b84f64016672e590129bf443d37
+  data.tar.gz: 4eeea9f9278a145646f3fad23e0672c191c7b6b53ce148cf561dd7a76f268bfa729feec32bf5a0871270bf10c4f39d7aaac5896d237e0c202fb89aed24499186

data/README.md

@@ -16,8 +16,9 @@ Mailclerk helps anyone on your team design great emails, improve their performan
   - [Setup](#setup)
   - [API Key & URL](#api-key--url)
   - [Usage](#usage)
+  - [Usage in Test Environments](#usage-in-test-environments)
   - [Varying API Keys](#varying-api-keys)
-  - [Tests](#tests)
+  - [Gem Tests](#gem-tests)
   - [Versioning](#versioning)
   - [Code of Conduct](#code-of-conduct)
   - [Contributions](#contributions)
@@ -28,7 +29,7 @@ Mailclerk helps anyone on your team design great emails, improve their performan
 
 ## Requirements
 
-1. [Ruby 2.7.0](https://www.ruby-lang.org)
+1. [Ruby 2.4.0](https://www.ruby-lang.org)
 
 ## Setup
 
@@ -50,9 +51,9 @@ To set the Mailclerk API Key (begins with `mc_`), you can provide it as an
 environmental variable: `MAILCLERK_API_KEY`. Alternatively, you can
 set it directly on the Mailclerk module:
 
-```
+```ruby
 # config/initializers/mailclerk.rb
-Mailclerk.api_key = "mc_yourprivatekey"
+Mailclerk.api_key = "mc_live_yourprivatekey"
 ```
 
 _If you are using version control like git, we strongly recommend storing your
@@ -67,44 +68,114 @@ You'll need an active account and at least one template (in the example `welcome
 
 To send an email to "alice@example.com":
 
-```
+```ruby
 Mailclerk.deliver("welcome-email", "alice@example.com")
+Mailclerk.deliver("welcome-email", "Alice Adams <alice@example.com>")
+Mailclerk.deliver("welcome-email", { name: "Alice Adams", address: "<alice@example.com>" })
 ```
 
 If the template has any dynamic data, you can include it in the third parameter
 as a hash:
 
-```
+```ruby
 Mailclerk.deliver("welcome-email", "alice@example.com", { name: "Alice" })
 ```
 
 See [Mailclerk documentation](https://dashboard.mailclerk.app/docs) for more details.
 
+## Usage in Test Environments
+
+Your Mailclerk environment has two API keys: a production key (beginning with `mc_live`)
+and a test key (beginning with `mc_test`). If you use the test key, emails will
+not be delivered, but will show up in the logs on your Mailclerk account and can be
+previewed there. This replaces tools like [Letter Opener](https://github.com/ryanb/letter_opener) for previewing emails in development.
+
+To avoid cluttering up your Mailclerk test logs with sends triggered by your
+automated test suite, call `Mailclerk.outbox.enable` in the file that
+configures your tests. For example, in Rspec with Rails, add:
+
+```ruby
+# spec/rails_helper.rb
+Mailclerk.outbox.enable
+```
+
+This will also enable utility methods which you can use to write tests that check
+emails are sent with the correct data:
+
+```ruby
+# Number of emails "sent"
+Mailclerk.outbox.length
+
+# Returns all emails of matching a template or email recipient. See method
+Mailclerk.outbox.filter(template: "welcome-email")
+Mailclerk.outbox.filter(recipient_email: "felix@example.com")
+
+# Returns the most recent email (instance of Mailclerk::TestEmail):
+email = Mailclerk.outbox.last
+email.template        # "welcome-email"
+email.recipient_email # "felix@example.com"
+email.subject         # "Welcome to Acme Felix"
+email.html            # "<html><body>..."
+```
+
+In between test cases, you should clear the stored emails by calling `Mailclerk.outbox.reset`.
+
+For example, in Rspec with Rails:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    Mailclerk.outbox.reset
+  end
+end
+```
+
+`Mailclerk::OutboxEmail` has the following attributes:
+
+| Attribute         | Description                                                                |
+| ----------------- | -------------------------------------------------------------------------- |
+| `template`        | Slug of the template sent (1st argument to `Mailclerk.deliver`)            |
+| `recipient`       | Hash representing the send recipient (2nd argument to `Mailclerk.deliver`) |
+| `recipient_email` | Email of the send recipient                                                |
+| `recipient_name`  | Name of the send recipient (nil if not specified)                          |
+| `data`            | Dynamic data for the send (3rd argument to `Mailclerk.deliver`)            |
+| `options`         | Options specified for the send (4th argument to `Mailclerk.deliver`)       |
+| `from`            | From Mailclerk: Hash with `name` and `address` of the sender               |
+| `subject`         | From Mailclerk: Text of the send's subject line                            |
+| `preheader`       | From Mailclerk: Text of the send's preheader                               |
+| `html`            | From Mailclerk: Rendered body HTML for the send                            |
+| `text`            | From Mailclerk: Rendered plaintext version of the send                     |
+| `headers`         | From Mailclerk: Extra email headers (e.g. `reply-to`)                      |
+
+See the [Mailclerk testing documentation](https://dashboard.mailclerk.app/docs#testing)
+for more details.
+
 ## Varying API Keys
 
 If you need to use multiple API keys, you can also initialize `Mailclerk::Client`
 instances with different keys. This:
 
-```
-mc_client = Mailclerk.new("mc_yourprivatekey")
+```ruby
+mc_client = Mailclerk.new("mc_live_yourprivatekey")
 mc_client.deliver("welcome-email", "bob@example.com")
 ```
 
 Is equivalent to this:
 
-```
-Mailclerk.api_key = "mc_yourprivatekey"
+```ruby
+Mailclerk.api_key = "mc_live_yourprivatekey"
 Mailclerk.deliver("welcome-email", "bob@example.com")
 ```
 
-## Tests
-
-Tests aren't currently implemented. When they are, to test, run:
+## Gem Tests
 
 ```
-bundle exec rake
+bundle exec rspec
 ```
 
+Requires values in .env file as well
+
 ## Versioning
 
 Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:

data/lib/client.rb

@@ -0,0 +1,62 @@
+module Mailclerk
+  class Client
+    def initialize(api_key, api_url=nil)
+      @api_key = api_key
+      @api_url = api_url || ENV['MAILCLERK_API_URL'] || DEFAULT_API_URL
+      
+      if @api_key.nil?
+        raise MailclerkError.new(
+          "No Mailclerk API Key provided. Set `Mailclerk.api_key`"
+        )
+      end
+
+      if @api_url.nil? || @api_url.empty?
+        raise MailclerkError.new("Mailclerk API URL empty")
+      end
+    end
+    
+    def deliver(template, recipient, data={}, options={})
+      conn = Faraday.new(url: @api_url)
+      conn.basic_auth(@api_key, '')
+            
+      if Mailclerk.outbox_enabled?
+        options = options.merge(
+          "local_outbox" => true
+        )
+        options.delete(:local_outbox)
+      end
+      
+      params = {
+        'template' => template,
+        'recipient' => recipient,
+        'data' => data,
+        'options' => options
+      }
+
+      response = conn.post('deliver', params.to_json, {
+        'Content-Type' => 'application/json',
+        'X-Client-Version' => Identity.version_label
+      })
+      
+      if response.status >= 400
+        begin
+          message = JSON.parse(response.body)["message"] || "Unknown"
+          description = "Mailclerk API Error: #{ message }"
+        rescue JSON::ParserError
+          description = "Mailclerk API Unknown Error"
+        end
+        
+        raise MailclerkAPIError.new(
+          description, response.status, response
+        )
+      end
+      
+      if Mailclerk.outbox_enabled?
+        params["options"].delete("local_outbox")
+        Mailclerk.outbox.add_send(params, JSON.parse(response.body)["delivery"])
+      end
+      
+      return response
+    end
+  end
+end

data/lib/errors.rb

@@ -0,0 +1,15 @@
+module Mailclerk
+  class MailclerkError < StandardError
+  end
+
+  class MailclerkAPIError < MailclerkError
+    attr_accessor :http_status
+    attr_accessor :http_response
+    
+    def initialize(description, http_status=nil, http_response=nil)
+      super(description)
+      self.http_status = http_status
+      self.http_response = http_response
+    end
+  end
+end

data/lib/mailclerk.rb

@@ -3,6 +3,10 @@
 require 'faraday'
 require 'json'
 
+require "client"
+require "errors"
+require "outbox"
+
 module Mailclerk
   DEFAULT_API_URL = "https://api.mailclerk.app"
   
@@ -22,7 +26,7 @@ module Mailclerk
     end
 
     def self.version
-      "1.0.2"
+      "1.1.0"
     end
 
     def self.version_label
@@ -30,75 +34,19 @@ module Mailclerk
     end
   end
 
-  class MailclerkError < StandardError
-  end
-  
-  class MailclerkAPIError < MailclerkError
-    attr_accessor :http_status
-    attr_accessor :http_response
-    
-    def initialize(description, http_status=nil, http_response=nil)
-      super(description)
-      self.http_status = http_status
-      self.http_response = http_response
-    end
-
-  end
-
-  class Client
-    def initialize(api_key, api_url=nil)
-      @api_key = api_key
-      @api_url = api_url || ENV['MAILCLERK_API_URL'] || DEFAULT_API_URL
-      
-      if @api_key.nil?
-        raise MailclerkError.new(
-          "No Mailclerk API Key provided. Set `Mailclerk.api_key`"
-        )
-      end
-
-      if @api_url.nil? || @api_url.empty?
-        raise MailclerkError.new("Mailclerk API URL empty")
-      end
-    end
-    
-    def deliver(template, recipient, data={}, options={})
-      conn = Faraday.new(url: @api_url)
-      conn.basic_auth(@api_key, '')
-      
-      response = conn.post('deliver', {
-        'template' => template,
-        'recipient' => recipient,
-        'data' => data,
-        'options' => options
-      }.to_json, {
-        'Content-Type' => 'application/json',
-        'X-Client-Version' => Identity.version_label
-      })
-      
-      if response.status >= 400
-        begin
-          message = JSON.parse(response.body)["message"] || "Unknown"
-          description = "Mailclerk API Error: #{ message }"
-        rescue JSON::ParserError
-          description = "Mailclerk API Unknown Error"
-        end
-        
-        raise MailclerkAPIError.new(
-          description, response.status, response
-        )
-
-      end
-      
-      return response
-    end
-  end
-
   # Syntax intended to emulate ActionMailer
   def self.deliver(*args)
     api_key = self.api_key || ENV['MAILCLERK_API_KEY']
     
-    client = Client.new(api_key, self.api_url)
+    client = Mailclerk::Client.new(api_key, self.api_url)
     return client.deliver(*args)
   end
+  
+  def self.outbox
+    @outbox ||= Mailclerk::Outbox.new
+  end
 
-end
+  def self.outbox_enabled?
+    !!(@outbox && @outbox.enabled)
+  end
+end

data/lib/outbox.rb

@@ -0,0 +1,93 @@
+module Mailclerk
+  class Outbox < Array
+    attr_accessor :enabled
+
+    def initialize
+      self.enabled = false
+    end
+    
+    def enable
+      self.enabled = true
+    end
+    
+    def reset
+      self.clear
+    end
+    
+    # Not just an alias for 'select'
+    def filter(query)
+      puts query
+      self.select do |email|
+        query.all? do |key, value|
+          puts email[key]
+          email[key] == value
+        end
+      end
+    end
+    
+    def add_send(request, response)
+      email = OutboxEmail.new(
+        OutboxEmail.recursive_init(
+          response.merge(request)
+        )
+      )
+      self << email
+    end
+  end
+  
+  class OutboxEmail < OpenStruct
+    
+    def self.recursive_init(data)
+
+      data.each do |key, val|
+        if val.is_a?(Hash)
+          data[key] = self.recursive_init(val)
+        else
+          data[key] = val
+        end
+      end
+      
+      return OpenStruct.new(data)
+    end
+    
+    # Custom getters
+
+    def recipient_email
+      return parse_recipient[:address]
+    end
+    
+    def recipient_name
+      return parse_recipient[:name]
+    end
+    
+    private
+    
+    def parse_recipient
+      return {} unless self.recipient
+      
+      if self.recipient.is_a?(OpenStruct)
+        return self.recipient
+      end
+      
+      text = self.recipient.strip
+
+      if text =~ /^[^<]+<[^<]+>$/
+        parts = text.split("<", 2);
+
+        name = parts[0].strip.gsub('"', "")
+
+        address = parts[1].strip.gsub(">", "")
+
+        return {
+          name: name,
+          address: address
+        }
+      else
+        return {
+          name: nil,
+          address: text
+        }
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailclerk
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Noah Litvin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-16 00:00:00.000000000 Z
+date: 2021-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -109,6 +109,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - developers@mailclerk.app
@@ -120,7 +134,10 @@ extra_rdoc_files:
 files:
 - LICENSE.md
 - README.md
+- lib/client.rb
+- lib/errors.rb
 - lib/mailclerk.rb
+- lib/outbox.rb
 homepage: https://github.com/mailclerk/mailclerk-ruby
 licenses:
 - MIT