mailclerk 0.1.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0746f6e459e89ebf5c23c33c940f10f4639d7b92e9bffbb7bb0f0c217608d8e9
-  data.tar.gz: 12c12b1846326a577d6423dd7b20ecf77156c50d4e3ab084327b72224a4b8023
+  metadata.gz: 97393aafed17d2eb1ca2d9c8242154c116e3bbb58e60596efd5f03b8697fb7df
+  data.tar.gz: 65cf703eede9e9213f0a7cb439dbed5e908cb127184634002a7618d0b7cfff8d
 SHA512:
-  metadata.gz: 1867bff480e230a049d3ec3f14221ca83ace81ed745cbefd1b3b7ef7ec6d6d561f7b8f9fe37b9d0d83d178f50ed28061bf6f35768f806dd4e9d27997a7f6c289
-  data.tar.gz: 5aa6071e289c6194fe43abfba94ed141200b1c385c42ac897e4c09dd0b0bf722f079f7e69b0d96d767deac7273a47a5475b31d60aac3160575dfb431e0006ffa
+  metadata.gz: 0f6fac55f44d59eb8fbd49709117543d666a26f53b9f650c89b14c04705b62d82df88c7ff5ea447dcddba692bd73c6d5d381725e54956de130a8a2c1949d0bdd
+  data.tar.gz: 81906cfdb4a73edbad522ef11fc75354d3dc97d9c03b26ed693c398fdaa5646b74ab113d3cb66e7188887c108a037e0b2b6c93d0762481468e1a7ede6a1afafc

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="mailcerk.png" alt="Mailclerk Logo"/>
+  <img src="https://github.com/mailclerk/mailclerk-ruby/blob/main/mailclerk.png?raw=true" alt="Mailclerk Logo"/>
 </p>
 
 # Mailclerk
@@ -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)
+  - [Testing](#testing)
   - [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,16 +51,16 @@ 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:
 
-```
-# config/initializers/mailcerk.rb
-Mailclerk.api_key = "mc_yourprivatekey"
+```ruby
+# config/initializers/mailclerk.rb
+Mailclerk.api_key = "mc_live_yourprivatekey"
 ```
 
 _If you are using version control like git, we strongly recommend storing your
 production API keys in environmental variables_.
 
-The default API endpoint is `https://api.mailcerk.app`. To change this, you
-can provide a `MAILCLERK_API_URL` ENV variable or set `Mailclerk.mailcerk_url`.
+The default API endpoint is `https://api.mailclerk.app`. To change this, you
+can provide a `MAILCLERK_API_URL` ENV variable or set `Mailclerk.mailclerk_url`.
 
 ## Usage
 
@@ -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.
 
+## Testing
+
+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 current 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
-      "0.1.1"
+      "1.1.1"
     end
 
     def self.version_label
@@ -30,47 +34,19 @@ module Mailclerk
     end
   end
 
-  class MailclerkError < StandardError
-  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, '')
-      
-      resp = conn.post('deliver', {
-        'template' => template,
-        'recipient' => recipient,
-        'data' => data,
-        'options' => options
-      }.to_json, {
-        'Content-Type' => 'application/json',
-        'X-Client-Version' => Identity.version_label
-      })
-
-      return resp
-    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,91 @@
+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)
+      self.select do |email|
+        query.all? do |key, value|
+          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: 0.1.1
+  version: 1.1.1
 platform: ruby
 authors:
 - Noah Litvin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-28 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
@@ -133,7 +150,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="