ahoy_email 0.5.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bd419ac1420c0d404b6137e3804545193969ecd8aab0444c919e9f7b5e5fae4
-  data.tar.gz: 3cce5d71d203a287992fc6560910f596f3cf74b0ef24861df8f5ed27ad9bd3b1
+  metadata.gz: c056fb39ad0a8774c23582f8a37fbea9f460d903f4f05565e31b5670b0ce615d
+  data.tar.gz: 5b489942efd5cb224f068d06d06fdd9e9e68f65d256ded15be359ccdfc4190ec
 SHA512:
-  metadata.gz: b163a83c5a2f78e7a2576940f1d7d0bb25bb38fec0203571adf387ffa2e380c5ed164fff92ba12c00f81a30d7b43b39e41d7a68a1d94b86f2dfc27c48139eb16
-  data.tar.gz: 816a961760e8fedf55efa9b5b59f38decdf0fdd12531dc5a52f83c09178bddf820e93eb375c47100e10bd4e9f2aba7b4c2efabde952ebfc589cf20d2d0418537
+  metadata.gz: 55a1a58246738297be5e07198ef58014a13596fa372cf8127a4b4670ddfb7465c09371250ff269306cfc03ef7704ec28bc716669857eb6bc40fbe3132c94564a
+  data.tar.gz: b58a064519fb0ef57a255db8a57c4b0101f0fbf029e3110f1ece205e927bb13a8e4c3d5f95888e36be41f25eed6f0dc73ee995ff546d27771604c6b4058fd392

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## 1.1.0
+
+- Made `opened_at` optional with click tracking
+- Fixed secret token for environment variables
+- Removed support for Rails 4.2
+
+## 1.0.3
+
+- Fixed custom message model
+- Fixed `message` option with proc
+
+## 1.0.2
+
+- Fixed error with Ruby < 2.5
+- Fixed UTM parameters storage on model
+
+## 1.0.1
+
+- Use observer instead of interceptor
+
+## 1.0.0
+
+- Removed support for Rails < 4.2
+
+Breaking changes
+
+- UTM tagging, open tracking, and click tracking are no longer enabled by default
+- Only sent emails are recorded
+- Proc options are now executed in the context of the mailer and take no arguments
+- Invalid options now throw an `ArgumentError`
+- `AhoyEmail.track` was removed in favor of `AhoyEmail.default_options`
+- The `heuristic_parse` option was removed and is now the default
+
 ## 0.5.2
 
 - Fixed secret token for Rails 5.2

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+First, thanks for wanting to contribute. You’re awesome! :heart:
+
+## Help
+
+We’re not able to provide support through GitHub Issues. If you’re looking for help with your code, try posting on [Stack Overflow](https://stackoverflow.com/).
+
+All features should be documented. If you don’t see a feature in the docs, assume it doesn’t exist.
+
+## Bugs
+
+Think you’ve discovered a bug?
+
+1. Search existing issues to see if it’s been reported.
+2. Try the `master` branch to make sure it hasn’t been fixed.
+
+```rb
+gem "ahoy_email", github: "ankane/ahoy_email"
+```
+
+If the above steps don’t help, create an issue. Include:
+
+- Detailed steps to reproduce
+- Complete backtraces for exceptions
+
+## New Features
+
+If you’d like to discuss a new feature, create an issue and start the title with `[Idea]`.
+
+## Pull Requests
+
+Fork the project and create a pull request. A few tips:
+
+- Keep changes to a minimum. If you have multiple features or fixes, submit multiple pull requests.
+- Follow the existing style. The code should read like it’s written by a single person.
+- Add one or more tests if possible. Make sure existing tests pass with:
+
+```sh
+bundle exec rake test
+```
+
+Feel free to open an issue to get feedback on your idea before spending too much time on it.
+
+---
+
+This contributing guide is released under [CCO](https://creativecommons.org/publicdomain/zero/1.0/) (public domain). Use it for your own project without attribution.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Andrew Kane
+Copyright (c) 2014-2019 Andrew Kane
 
 MIT License
 

data/README.md

@@ -1,14 +1,14 @@
 # Ahoy Email
 
-:postbox: Simple, powerful email tracking for Rails
+:postbox: Email analytics for Rails
 
 You get:
 
 - A history of emails sent to each user
 - Easy UTM tagging
-- Open and click tracking
+- Optional open and click tracking
 
-Works with any email service.
+**Ahoy Email 1.0 was recently released!** See [how to upgrade](#upgrading)
 
 :bullettrain_side: To manage unsubscribes, check out [Mailkick](https://github.com/ankane/mailkick)
 
@@ -33,27 +33,37 @@ rails db:migrate
 
 ## How It Works
 
-Ahoy creates an `Ahoy::Message` every time an email is sent by default.
+### Message History
+
+Ahoy creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+
+```ruby
+class CouponMailer < ApplicationMailer
+  track message: false # use only/except to limit actions
+end
+```
+
+Or by default:
+
+```ruby
+AhoyEmail.default_options[:message] = false
+```
 
 ### Users
 
-Ahoy tracks the user a message is sent to - not just the email address.  This gives you a full history of messages for each user, even if he or she changes addresses.
+Ahoy records the user a message is sent to - not just the email address. This gives you a full history of messages for each user, even if he or she changes addresses.
 
-By default, Ahoy tries `User.where(email: message.to.first).first` to find the user.
+By default, Ahoy tries `@user` then `params[:user]` then `User.find_by(email: message.to)` to find the user.
 
 You can pass a specific user with:
 
 ```ruby
-class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    # ...
-    track user: user
-    mail to: user.email
-  end
+class CouponMailer < ApplicationMailer
+  track user: -> { params[:some_user] }
 end
 ```
 
-The user association is [polymorphic](http://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
+The user association is [polymorphic](https://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
 
 To get all messages sent to a user, add an association:
 
@@ -69,124 +79,148 @@ And run:
 user.messages
 ```
 
-### UTM Parameters
+### Extra Attributes
+
+Record extra attributes on the `Ahoy::Message` model.
 
-UTM parameters are added to links if they don’t already exist.
+Create a migration to add extra attributes to the `ahoy_messages` table. For example:
 
-The defaults are:
+```ruby
+class AddCouponIdToAhoyMessages < ActiveRecord::Migration[5.2]
+  def change
+    add_column :ahoy_messages, :coupon_id, :integer
+  end
+end
+```
 
-- utm_medium - `email`
-- utm_source - the mailer name like `user_mailer`
-- utm_campaign - the mailer action like `welcome_email`
+Then use:
 
-Use `track utm_params: false` to skip tagging, or skip specific links with:
+```ruby
+class CouponMailer < ApplicationMailer
+  track extra: {coupon_id: 1}
+end
+```
 
+You can use a proc as well.
 
-```html
-<a data-skip-utm-params="true" href="...">Break it down</a>
+```ruby
+class CouponMailer < ApplicationMailer
+  track extra: -> { {coupon_id: params[:coupon].id} }
+end
 ```
 
-### Opens
+### UTM Tagging
 
-An invisible pixel is added right before the `</body>` tag in HTML emails.
+Automatically add UTM parameters to links.
 
-If the recipient has images enabled in his or her email client, the pixel is loaded and the open time recorded.
+```ruby
+class CouponMailer < ApplicationMailer
+  track utm_params: true # use only/except to limit actions
+end
+```
 
-Use `track open: false` to skip this.
+The defaults are:
 
-### Clicks
+- `utm_medium` - `email`
+- `utm_source` - the mailer name like `coupon_mailer`
+- `utm_campaign` - the mailer action like `offer`
 
-A redirect is added to links to track clicks in HTML emails.
+You can customize them with:
 
-```
-https://chartkick.com
+```ruby
+class CouponMailer < ApplicationMailer
+  track utm_params: true, utm_campaign: -> { "coupon#{params[:coupon].id}" }
+end
 ```
 
-becomes
+Skip specific links with:
 
-```
-https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
+```erb
+<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
 ```
 
-A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
+### Opens & Clicks
 
-Use `track click: false` to skip tracking, or skip specific links with:
-
-```html
-<a data-skip-click="true" href="...">Can't touch this</a>
-```
+#### Setup
 
-### Extra Attributes
+Additional setup is required to track opens and clicks.
 
-Create a migration to add extra attributes to the `ahoy_messages` table, for example:
+Create a migration with:
 
 ```ruby
-class AddCampaignIdToAhoyMessages < ActiveRecord::Migration
+class AddTokenToAhoyMessages < ActiveRecord::Migration[5.2]
   def change
-    add_column :ahoy_messages, :campaign_id, :integer
+    add_column :ahoy_messages, :token, :string
+    add_column :ahoy_messages, :opened_at, :timestamp
+    add_column :ahoy_messages, :clicked_at, :timestamp
+
+    add_index :ahoy_messages, :token
   end
 end
 ```
 
-Then use:
+Create an initializer `config/initializers/ahoy_email.rb` with:
+
+```ruby
+AhoyEmail.api = true
+```
+
+And add to mailers you want to track:
 
 ```ruby
-track extra: {campaign_id: 1}
+class CouponMailer < ApplicationMailer
+  track open: true, click: true # use only/except to limit actions
+end
 ```
 
-## Customize
+#### How It Works
 
-### Tracking
+For opens, an invisible pixel is added right before the `</body>` tag in HTML emails. If the recipient has images enabled in their email client, the pixel is loaded and the open time recorded.
 
-Skip tracking of attributes by removing them from your model.  You can safely remove:
+For clicks, a redirect is added to links to track clicks in HTML emails.
 
-- to
-- mailer
-- subject
-- content
+```
+https://chartkick.com
+```
 
-### Configuration
+becomes
+
+```
+https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
+```
 
-There are 3 places to set options. Here’s the order of precedence.
+A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
-#### Action
+Skip specific links with:
 
-``` ruby
-class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    # ...
-    track user: user
-    mail to: user.email
-  end
-end
+```erb
+<%= link_to "Go", some_url, data: {skip_click: true} %>
 ```
 
-#### Mailer
+By default, unsubscribe links are excluded. To change this, use:
 
 ```ruby
-class UserMailer < ApplicationMailer
-  track utm_campaign: "boom"
-end
+AhoyEmail.default_options[:unsubscribe_links] = true
 ```
 
-#### Global
+You can specify the domain to use with:
 
 ```ruby
-AhoyEmail.track open: false
+AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
 ```
 
-## Events
+#### Events
 
-Subscribe to open and click events. Create an initializer `config/initializers/ahoy_email.rb` with:
+Subscribe to open and click events by adding to the initializer:
 
 ```ruby
 class EmailSubscriber
   def open(event)
-    # any code you want
+    # your code
   end
 
   def click(event)
-    # any code you want
+    # your code
   end
 end
 
@@ -209,56 +243,91 @@ end
 AhoyEmail.subscribers << EmailSubscriber.new
 ```
 
-## Reference
+## Data Protection
 
-You can use a `Proc` for any option.
+Protect the privacy of your users by encrypting the `to` field. [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted) is great for this. Use [blind_index](https://github.com/ankane/blind_index) if you need to query by the `to` field.
 
-```ruby
-track utm_campaign: ->(message, mailer) { mailer.action_name + Time.now.year }
-```
-
-Disable tracking for an email
+Create `app/models/ahoy/message.rb` with:
 
 ```ruby
-track message: false
+class Ahoy::Message < ApplicationRecord
+  self.table_name = "ahoy_messages"
+  belongs_to :user, polymorphic: true, optional: true
+
+  attr_encrypted :to, key: ...
+  blind_index :to, key: ...
+end
 ```
 
-Or specific actions
+## Reference
+
+Set global options
 
 ```ruby
-track only: [:welcome_email]
-track except: [:welcome_email]
+AhoyEmail.default_options[:user] = -> { params[:admin] }
 ```
 
-Or by default
+Use a different model
 
 ```ruby
-AhoyEmail.track message: false
+AhoyEmail.message_model = -> { UserMessage }
 ```
 
-Customize domain
+Or fully customize how messages are tracked
 
 ```ruby
-track url_options: {host: "mydomain.com"}
+AhoyEmail.track_method = lambda do |data|
+  # your code
+end
 ```
 
-By default, unsubscribe links are excluded from tracking. To change this, use:
+## Mongoid
+
+If you prefer to use Mongoid instead of ActiveRecord, create `app/models/ahoy/message.rb` with:
 
 ```ruby
-track unsubscribe_links: true
-```
+class Ahoy::Message
+  include Mongoid::Document
 
-Use a different model
+  belongs_to :user, polymorphic: true, optional: true, index: true
 
-```ruby
-AhoyEmail.message_model = -> { UserMessage }
+  field :to, type: String
+  field :mailer, type: String
+  field :subject, type: String
+  field :sent_at, type: Time
+end
 ```
 
 ## Upgrading
 
-### 0.2.3
+### 1.0
+
+Breaking changes
 
-Optionally, you can store UTM parameters by adding `utm_source`, `utm_medium`, and `utm_campaign` columns to your message model.
+- UTM tagging, open tracking, and click tracking are no longer enabled by default. To enable, create an initializer with:
+
+  ```ruby
+  AhoyEmail.api = true
+
+  AhoyEmail.default_options[:open] = true
+  AhoyEmail.default_options[:click] = true
+  AhoyEmail.default_options[:utm_params] = true
+  ```
+
+- Only sent emails are recorded
+- Proc options are now executed in the context of the mailer and take no arguments
+
+  ```ruby
+  # old
+  user: ->(mailer, message) { User.find_by(email: message.to) }
+
+  # new
+  user: -> { User.find_by(email: message.to) }
+  ```
+
+- Invalid options now throw an `ArgumentError`
+- `AhoyEmail.track` was removed in favor of `AhoyEmail.default_options`
+- The `heuristic_parse` option was removed and is now the default
 
 ## History
 
@@ -272,3 +341,12 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - Fix bugs and [submit pull requests](https://github.com/ankane/ahoy_email/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
+
+To get started with development and testing:
+
+```sh
+git clone https://github.com/ankane/ahoy_email.git
+cd ahoy_email
+bundle install
+rake test
+```

data/app/controllers/ahoy/messages_controller.rb

@@ -1,30 +1,40 @@
 module Ahoy
-  class MessagesController < ActionController::Base
-    if respond_to? :before_action
-      before_action :set_message
-    else
-      before_filter :set_message
-    end
+  class MessagesController < ApplicationController
+    filters = _process_action_callbacks.map(&:filter) - AhoyEmail.preserve_callbacks
+    skip_before_action(*filters, raise: false)
+    skip_after_action(*filters, raise: false)
+    skip_around_action(*filters, raise: false)
+
+    before_action :set_message
 
     def open
       if @message && !@message.opened_at
         @message.opened_at = Time.now
         @message.save!
       end
+
       publish :open
+
       send_data Base64.decode64("R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="), type: "image/gif", disposition: "inline"
     end
 
     def click
       if @message && !@message.clicked_at
         @message.clicked_at = Time.now
-        @message.opened_at ||= @message.clicked_at
+        @message.opened_at ||= @message.clicked_at if @message.respond_to?(:opened_at=)
         @message.save!
       end
+
+      user_signature = params[:signature].to_s
       url = params[:url].to_s
-      signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha1"), AhoyEmail.secret_token, url)
-      publish :click, url: params[:url]
-      if secure_compare(params[:signature].to_s, signature)
+
+      # TODO sign more than just url and transition to HMAC-SHA256
+      digest = "SHA1"
+      signature = OpenSSL::HMAC.hexdigest(digest, AhoyEmail.secret_token, url)
+
+      if ActiveSupport::SecurityUtils.secure_compare(user_signature, signature)
+        publish :click, url: params[:url]
+
         redirect_to url
       else
         redirect_to AhoyEmail.invalid_redirect_url || main_app.root_url
@@ -46,17 +56,5 @@ module Ahoy
         end
       end
     end
-
-    # from https://github.com/rails/rails/blob/master/activesupport/lib/active_support/message_verifier.rb
-    # constant-time comparison algorithm to prevent timing attacks
-    def secure_compare(a, b)
-      return false unless a.bytesize == b.bytesize
-
-      l = a.unpack "C#{a.bytesize}"
-
-      res = 0
-      b.each_byte { |byte| res |= byte ^ l.shift }
-      res == 0
-    end
   end
 end

data/app/models/ahoy/message.rb

@@ -2,6 +2,6 @@ module Ahoy
   class Message < ActiveRecord::Base
     self.table_name = "ahoy_messages"
 
-    belongs_to :user, AhoyEmail.belongs_to.merge(polymorphic: true)
+    belongs_to :user, polymorphic: true, optional: true
   end
 end

data/config/routes.rb

@@ -1,7 +1,5 @@
 Rails.application.routes.draw do
-  unless respond_to?(:has_named_route?) && has_named_route?("ahoy_email_engine")
-    mount AhoyEmail::Engine => "/ahoy"
-  end
+  mount AhoyEmail::Engine => "/ahoy" if AhoyEmail.api
 end
 
 AhoyEmail::Engine.routes.draw do

data/lib/ahoy_email/engine.rb

@@ -13,10 +13,10 @@ module AhoyEmail
             app.config
           end
 
-        creds.respond_to?(:secret_key_base) ? creds.secret_key_base : creds.secret_token
+        token = creds.respond_to?(:secret_key_base) ? creds.secret_key_base : creds.secret_token
+        token ||= app.secret_key_base # should come first, but need to maintain backward compatibility
+        token
       end
-
-      AhoyEmail.belongs_to = {optional: true} if Rails::VERSION::MAJOR >= 5
     end
   end
 end

data/lib/ahoy_email/mailer.rb

@@ -1,33 +1,43 @@
 module AhoyEmail
   module Mailer
-    def self.included(base)
-      base.extend ClassMethods
-      base.prepend InstanceMethods
-      base.class_eval do
-        attr_accessor :ahoy_options
-        class_attribute :ahoy_options
-        self.ahoy_options = {}
-      end
+    extend ActiveSupport::Concern
+
+    included do
+      attr_writer :ahoy_options
+      after_action :save_ahoy_options
     end
 
-    module ClassMethods
-      def track(options = {})
-        self.ahoy_options = ahoy_options.merge(message: true).merge(options)
+    class_methods do
+      def track(**options)
+        before_action(options.slice(:only, :except)) do
+          self.ahoy_options = ahoy_options.merge(message: true).merge(options.except(:only, :except))
+        end
       end
     end
 
-    module InstanceMethods
-      def track(options = {})
-        self.ahoy_options = (ahoy_options || {}).merge(message: true).merge(options)
-      end
+    def track(**options)
+      self.ahoy_options = ahoy_options.merge(message: true).merge(options)
+    end
+
+    def ahoy_options
+      @ahoy_options ||= AhoyEmail.default_options
+    end
+
+    def save_ahoy_options
+      Safely.safely do
+        # do message first for performance
+        message = ahoy_options[:message]
+        message = message.respond_to?(:call) ? instance_exec(&message) : message
 
-      def mail(headers = {}, &block)
-        # this mimics what original method does
-        return message if @_mail_was_called && headers.blank? && !block
+        if message
+          options = {}
+          ahoy_options.except(:message).each do |k, v|
+            # execute options in mailer content
+            options[k] = v.respond_to?(:call) ? instance_exec(&v) : v
+          end
 
-        message = super
-        AhoyEmail::Processor.new(message, self).process
-        message
+          AhoyEmail::Processor.new(self, options).perform
+        end
       end
     end
   end

data/lib/ahoy_email/observer.rb

@@ -0,0 +1,7 @@
+module AhoyEmail
+  class Observer
+    def self.delivered_email(message)
+      AhoyEmail::Tracker.new(message).perform
+    end
+  end
+end