tricle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8ae60bb0e6e671d65f0c1901458bdb6a2a8ea730
+  data.tar.gz: 4714ec2150c42c605587d3cea5fd05382a60f4ab
+SHA512:
+  metadata.gz: b0b2c91ada726e91f976c1cb5ed6c421c9a8a8e4a8d6f633f599bd644e71aa80af59157835cbad37ad844952abe3d60a59e5fe272d1a92c672133d44d871e9c1
+  data.tar.gz: 365357668547fc809ace7212a7d2a9931850b8d69d97f0d85b7e0713b23c205cddcbee6ecb96596c92ae1caba151ba5786441594dc8492e26c279e41df122f5a

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+To set up, run
+
+```bash
+bundle
+```
+
+To run tests,
+
+```bash
+bundle exec rspec
+# or, to run continuously:
+bundle exec guard
+```
+
+To see a live preview with dummy data:
+
+```bash
+gem install shotgun
+shotgun
+open http://localhost:9393/test_mailer.html
+```

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tricle.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,8 @@
+notification :gntp
+
+guard :rspec, all_on_start: true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/}) { 'spec' }
+  watch('spec/spec_helper.rb') { 'spec' }
+  watch(%r{^spec/}) { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Aidan Feldman
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# Tricle [![Build Status](https://travis-ci.org/artsy/tricle.png?branch=master)](https://travis-ci.org/artsy/tricle) [![Code Climate](https://codeclimate.com/github/artsy/tricle.png)](https://codeclimate.com/github/artsy/tricle)
+
+Automated metrics reporting via email.  It's datastore-agnostic, so you can query SQL, MongoDB, external APIs, etc. to generate the stats you need.  See [here](https://github.com/afeld/tricle-afeld) for an example implementation ([live demo](http://tricle.afeld.me/weekly_metrics)).
+
+![screenshot](screenshot.png)
+
+## Installation
+
+### Gem
+
+This gem can be used within an existing project (e.g. a Rails app), or standalone.
+
+```ruby
+# Gemfile
+gem 'tricle', '~> 0.1.0'
+
+# Rakefile
+require 'tricle/tasks'
+
+# your/config/file.rb
+# unless you already have ActionMailer set up
+ActionMailer::Base.raise_delivery_errors = true
+ActionMailer::Base.smtp_settings = {
+  # ...
+}
+```
+
+See [the ActionMailer guide](http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration) for configuration details.  Finally, execute:
+
+```bash
+bundle
+```
+
+## Usage
+
+### Metrics
+
+For each metric you want to report, create a new subclass of `Tricle::Metric` that implements `#size_for_range` and `#total`:
+
+```ruby
+class MyMetric < Tricle::Metric
+
+  # Retrieve the value of this metric for the provided time period. Generally
+  # this will be the count/value added/removed. Not necessary if #items_for_range
+  # is defined.
+  #
+  # @param start_at [Time]
+  # @param end_at [Time] non-inclusive
+  # @return [Fixnum]
+  def size_for_range(start_at, end_at)
+    # ...
+  end
+
+  # Retrieve the cumulative value for this metric.
+  #
+  # @return [Fixnum] the grand total
+  def total
+    # ...
+  end
+
+  # Optional: only necessary if using `list` for this Metric within your Mailer.
+  #
+  # @param start_at [Time]
+  # @param end_at [Time] non-inclusive
+  # @return [Enumerator]
+  def items_for_range(start_at, end_at)
+    # ...
+  end
+
+end
+```
+
+ActiveRecord example:
+
+```ruby
+# metrics/new_users.rb
+class NewUsers < Tricle::Metric
+
+  def size_for_range(start_at, end_at)
+    self.size_for_range(start_at, end_at).size
+  end
+
+  def total
+    self.users.count
+  end
+
+  def items_for_range(start_at, end_at)
+    self.size_for_range(start_at, end_at)
+  end
+
+
+  private
+
+  def size_for_range(start_at, end_at)
+    self.users.where('created_at >= ? AND created_at < ?', start_at, end_at)
+  end
+
+  # You can add whatever helper methods in that class that you need.
+  def users
+    # non-deleted Users
+    User.where(deleted_at: nil)
+  end
+
+end
+```
+
+### Mailers
+
+Mailers specify how a particular set of Metrics should be sent.  You can define one or multiple, to send different metrics to different groups of people.
+
+```ruby
+class MyMailer < Tricle::Mailer
+
+  # accepts the same options as ActionMailer... see "Default Hash" at
+  # http://rubydoc.info/gems/actionmailer/ActionMailer/Base
+  default(
+    # ...
+  )
+
+  metric MyMetric1
+  metric MyMetric2
+  # ...
+
+  # optional: metrics can be grouped
+  group "Group 1 Name" do
+    metric MyMetric3
+    # ...
+  end
+  group "Group 2 Name" do
+    metric MyMetric4
+    # ...
+  end
+
+  # optional: list the items for the specified Metric
+  list MyMetric2 do |item|
+    # return the HTML string for each particular item
+  end
+  # ...
+
+end
+```
+
+e.g.
+
+```ruby
+# mailers/weekly_insights.rb
+class WeeklyInsights < Tricle::Mailer
+
+  default(
+    to: ['theteam@mycompany.com', 'theboss@mycompany.com'],
+    from: 'noreply@mycompany.com'
+  )
+
+  metric NewUsers
+
+  list NewUsers do |user|
+    <<-MARKUP
+      <h3>#{user.name}</h3>
+      <div>#{user.location}</div>
+      <a href="mailto:#{user.email}>#{user.email}</a>
+    MARKUP
+  end
+
+end
+```
+
+The subject line will be based on the Mailer class name.
+
+### Previewing
+
+Since you'd probably like to preview your mailers before sending them, set up the `Tricle::MailPreview` Rack app (which uses [MailView](https://github.com/37signals/mail_view)).
+
+#### Within a Rails app
+
+```ruby
+# config/initializers/tricle.rb
+require 'tricle/mail_preview'
+
+# config/routes.rb
+if Rails.env.development?
+  mount MailPreview => 'mail_view'
+end
+```
+
+and navigate to [localhost:3000/mail_view](http://localhost:3000/mail_view).
+
+#### Standalone
+
+```bash
+bundle exec rake tricle:preview
+open http://localhost:8080
+```
+
+## Deploying
+
+To send all Tricle emails, run
+
+```bash
+rake tricle:emails:send
+```
+
+### Cron Setup
+
+TODO

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+require_relative 'spec/config/timecop'
+
+reset_time
+
+# used for the preview
+require_relative 'lib/tricle'
+require_relative 'spec/app/group_test_mailer.rb'
+require_relative 'spec/app/list_test_mailer.rb'
+require_relative 'spec/app/test_mailer.rb'
+require_relative 'spec/app/uber_test_mailer.rb'
+
+require_relative 'lib/tricle/tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/tricle.rb

@@ -0,0 +1,4 @@
+# only the files needed publicly
+require_relative 'tricle/version'
+require_relative 'tricle/metric'
+require_relative 'tricle/mailer'

data/lib/tricle/abstract_method_error.rb

@@ -0,0 +1,8 @@
+module Tricle
+  class AbstractMethodError < RuntimeError
+    def to_s
+      name = self.backtrace.first[/`(\w+)'/, 1]
+      "##{name} not implemented"
+    end
+  end
+end

data/lib/tricle/email_helper.rb

@@ -0,0 +1,66 @@
+require 'active_support/core_ext/date/calculations'
+require 'active_support/core_ext/numeric/time'
+
+module Tricle
+  module EmailHelper
+    def weeks_ago(n)
+      Date.today.beginning_of_week.weeks_ago(n)
+    end
+
+    def format_date(date)
+      date.strftime('%-m/%-d/%y')
+    end
+
+    def number_with_delimiter(number)
+      # from http://stackoverflow.com/a/11466770/358804
+      number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+
+    def percent_change(new_val, old_val)
+      if old_val == 0
+        new_val >= 0 ? '+' : '-'
+      else
+        fraction = (new_val - old_val) / old_val.to_f
+        sprintf('%+.1f%', fraction * 100.0)
+      end
+    end
+
+    def percent_change_cell(new_val, old_val)
+      cls = (new_val >= old_val) ? 'positive' : 'negative'
+      pct_str = percent_change(new_val, old_val)
+      old_val_str = number_with_delimiter(old_val.round)
+      %[<td class="#{cls}"><div>#{pct_str}</div><div>#{old_val_str}</div></td>].html_safe
+    end
+
+    def dates_range_str(start_at, end_at)
+      "#{ self.format_date(start_at) } - #{ self.format_date(end_at) }"
+    end
+
+    def dates_cell(start_at, end_at)
+      range = dates_range_str(start_at, end_at)
+      %[<div class="date-range">(#{range})</div>].html_safe
+    end
+
+    def single_week_dates_cell(start_at)
+      dates_cell(start_at, start_at.end_of_week)
+    end
+
+    def last_week_dates_cell
+      single_week_dates_cell(weeks_ago(1))
+    end
+
+    def previous_week_dates_cell
+      single_week_dates_cell(weeks_ago(2))
+    end
+
+    def quarter_dates_cell
+      dates_cell(weeks_ago(13), weeks_ago(1).end_of_week)
+    end
+
+    def list_markup(list)
+      start_at = self.weeks_ago(1).to_time
+      end_at = start_at + 7.days
+      list.items_markup(start_at, end_at).html_safe
+    end
+  end
+end

data/lib/tricle/mail_preview.rb

@@ -0,0 +1,10 @@
+require 'mail_view'
+require_relative 'mailer'
+
+module Tricle
+  class MailPreview < MailView
+    Tricle::Mailer.descendants.each do |klass|
+      define_method(klass.name.underscore) { klass.email }
+    end
+  end
+end

data/lib/tricle/mailer.rb

@@ -0,0 +1,75 @@
+require 'action_mailer'
+require 'active_support/descendants_tracker'
+require 'premailer'
+
+require_relative 'email_helper'
+require_relative 'presenters/report'
+
+
+module Tricle
+  class Mailer < ActionMailer::Base
+    include ActiveSupport::DescendantsTracker
+
+    class_attribute :report
+    helper Tricle::EmailHelper
+    self.view_paths = File.dirname(__FILE__)
+
+    CSS = File.read(File.join(File.dirname(__FILE__), 'templates', 'email.css')).freeze
+
+
+    def subject
+      "Your #{self.class.name.titleize}"
+    end
+
+    def premailer(message)
+      # message.text_part.body = Premailer.new(message.text_part.body.to_s, with_html_string: true).to_plain_text
+      message.html_part.body = Premailer.new(message.html_part.body.to_s, css_string: CSS.dup, with_html_string: true).to_inline_css
+      message
+    end
+
+    def email(options = {})
+      options = {
+        subject: self.subject
+      }.merge(options)
+
+      @report = self.report
+
+      message = mail(options) do |format|
+        format.html { render 'templates/email' }
+        format.text { render 'templates/email' }
+      end
+
+      premailer(message)
+    end
+
+    class << self
+      def inherited(klass)
+        klass.report = Tricle::Presenters::Report.new
+        super(klass)
+      end
+
+      def group(title)
+        self.report.add_group(title)
+        yield if block_given?
+      end
+
+      def metric(klass)
+        self.report.add_metric(klass)
+      end
+
+      def list(klass, &block)
+        self.report.add_list(klass, &block)
+      end
+
+      def send_all
+        mailers = Tricle::Mailer.descendants
+        puts "Sending #{mailers.size} emails..."
+        mailers.each do |klass|
+          puts "Sending #{klass.name}..."
+          klass.email.deliver
+        end
+        puts "Done."
+      end
+    end
+  end
+end