ahoy_email 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bd419ac1420c0d404b6137e3804545193969ecd8aab0444c919e9f7b5e5fae4
-  data.tar.gz: 3cce5d71d203a287992fc6560910f596f3cf74b0ef24861df8f5ed27ad9bd3b1
+  metadata.gz: acb3c3744cff970d75c695f1c79edec32e7dd7a9bea7342576b7fc87be2d3e4a
+  data.tar.gz: 1cd08f10de1fa686aa09312cdee054694debe9f7835bb97fd9eb35aa9fc09c01
 SHA512:
-  metadata.gz: b163a83c5a2f78e7a2576940f1d7d0bb25bb38fec0203571adf387ffa2e380c5ed164fff92ba12c00f81a30d7b43b39e41d7a68a1d94b86f2dfc27c48139eb16
-  data.tar.gz: 816a961760e8fedf55efa9b5b59f38decdf0fdd12531dc5a52f83c09178bddf820e93eb375c47100e10bd4e9f2aba7b4c2efabde952ebfc589cf20d2d0418537
+  metadata.gz: 3eb7a246d87edfec081d873c8a464c90a682b81acd5d38877c8551770ba911f0c222bf778b03c2abf390fadf5bf48edabe863187627740c673b86718e082a9e4
+  data.tar.gz: 15c5a59995db66c0d76bfa5273e8a7f4404b11d80078fbf73765fcfb157d8ed3ff744b7bc694e75c8eb8fc2b4afc5494727fa68fb2f60769f91cf2d1f86e7dec

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 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-2018 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 UserMailer < 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.first)` 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
+  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
 
-UTM parameters are added to links if they don’t already exist.
+Record extra attributes on the `Ahoy::Message` model.
 
-The defaults are:
+Create a migration to add extra attributes to the `ahoy_messages` table. For example:
 
-- utm_medium - `email`
-- utm_source - the mailer name like `user_mailer`
-- utm_campaign - the mailer action like `welcome_email`
+```ruby
+class AddCouponIdToAhoyMessages < ActiveRecord::Migration[5.2]
+  def change
+    add_column :ahoy_messages, :coupon_id, :integer
+  end
+end
+```
 
-Use `track utm_params: false` to skip tagging, or skip specific links with:
+Then use:
 
+```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:
 
+```erb
+<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
 ```
-https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
-```
-
-A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
-Use `track click: false` to skip tracking, or skip specific links with:
+### Opens & Clicks
 
-```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
-track extra: {campaign_id: 1}
+AhoyEmail.api = true
 ```
 
-## Customize
+And add to mailers you want to track:
 
-### Tracking
+```ruby
+class UserMailer < ApplicationMailer
+  track open: true, click: true # use only/except to limit actions
+end
+```
 
-Skip tracking of attributes by removing them from your model.  You can safely remove:
+#### How It Works
 
-- to
-- mailer
-- subject
-- content
+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.
 
-### Configuration
+For clicks, a redirect is added to links to track clicks in HTML emails.
 
-There are 3 places to set options. Here’s the order of precedence.
+```
+https://chartkick.com
+```
 
-#### Action
+becomes
 
-``` ruby
-class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    # ...
-    track user: user
-    mail to: user.email
-  end
-end
 ```
+https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
+```
+
+A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
-#### Mailer
+Skip specific links with:
+
+```erb
+<%= link_to "Go", some_url, data: {skip_click: true} %>
+```
+
+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
 
@@ -211,54 +245,56 @@ AhoyEmail.subscribers << EmailSubscriber.new
 
 ## Reference
 
-You can use a `Proc` for any option.
+Set global options
 
 ```ruby
-track utm_campaign: ->(message, mailer) { mailer.action_name + Time.now.year }
+AhoyEmail.default_options[:user] = -> { params[:admin] }
 ```
 
-Disable tracking for an email
+Use a different model
 
 ```ruby
-track message: false
+AhoyEmail.message_model = -> { UserMessage }
 ```
 
-Or specific actions
+Or fully customize how messages are tracked
 
 ```ruby
-track only: [:welcome_email]
-track except: [:welcome_email]
+AhoyEmail.track_method = lambda do |data|
+  # your code
+end
 ```
 
-Or by default
+## Upgrading
 
-```ruby
-AhoyEmail.track message: false
-```
+### 1.0
 
-Customize domain
+Breaking changes
 
-```ruby
-track url_options: {host: "mydomain.com"}
-```
+- UTM tagging, open tracking, and click tracking are no longer enabled by default. To enable, create an initializer with:
 
-By default, unsubscribe links are excluded from tracking. To change this, use:
+  ```ruby
+  AhoyEmail.api = true
 
-```ruby
-track unsubscribe_links: true
-```
+  AhoyEmail.default_options[:open] = true
+  AhoyEmail.default_options[:click] = true
+  AhoyEmail.default_options[:utm_params] = true
+  ```
 
-Use a different model
+- Only sent emails are recorded
+- Proc options are now executed in the context of the mailer and take no arguments
 
-```ruby
-AhoyEmail.message_model = -> { UserMessage }
-```
-
-## Upgrading
+  ```ruby
+  # old
+  user: ->(mailer, message) { User.find_by(email: message.to.first) }
 
-### 0.2.3
+  # new
+  user: -> { User.find_by(email: message.to.first) }
+  ```
 
-Optionally, you can store UTM parameters by adding `utm_source`, `utm_medium`, and `utm_campaign` columns to your message model.
+- 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
 

data/app/controllers/ahoy/messages_controller.rb

@@ -1,17 +1,24 @@
 module Ahoy
-  class MessagesController < ActionController::Base
-    if respond_to? :before_action
-      before_action :set_message
+  class MessagesController < ApplicationController
+    filters = _process_action_callbacks.map(&:filter) - AhoyEmail.preserve_callbacks
+    if Rails::VERSION::MAJOR >= 5
+      skip_before_action(*filters, raise: false)
+      skip_after_action(*filters, raise: false)
+      skip_around_action(*filters, raise: false)
     else
-      before_filter :set_message
+      skip_action_callback *filters
     end
 
+    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
 
@@ -21,10 +28,17 @@ module Ahoy
         @message.opened_at ||= @message.clicked_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 +60,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