totalizer 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 325cabe6e33e0ec8d6ff8f104b20cb50194f8ac0
-  data.tar.gz: 19e48c1f6977e45f048cfa9e4a6b9456b5d30ede
+  metadata.gz: 64378db2593e41ea508fbd469dd20f36bb010652
+  data.tar.gz: aa0ea7c47ed3bed604157154b31bca1f21fcd1d3
 SHA512:
-  metadata.gz: 543b8a101ff5fcacdb94703e9372b5a3f51ea0546934b677e5ff7a940ed83600e3027fa3c257a92cacefa9d4e1407c897ae3a519b1adb3e49263815738650cba
-  data.tar.gz: 7a6495f66fc42afe02c187347a5b228959e0e5e38945ed6db666f18567a52233904937b69201be7441a0b79f10a0610c840f85c886852487643bf57d14eb44e5
+  metadata.gz: ee4d5424e72d83a47e1ea9fa91de4d5b144072d90ece8c5e69aebfa1c10b5aec40ce10b6277181c2e889de34721e2fc629cf392e1ccac0fc44bbb512b53ea880
+  data.tar.gz: 91462bfd5e919eedf7291b8bb4d9359df1816c7fa9fbba7b19ec87a90dd6f82d5e8c15621ddee4fc8b013c3a49531214308914cf5c874a2c495b603adda8f60c

data/README.md

@@ -1,6 +1,10 @@
-# Totalizer - Calculate important metrics in your Rails application.
+# Totalizer - Calculate and share important metrics in your Rails application.
 
-Provides tools to Ruby on Rails developers to create calculations for Acquisition, Activation, Engagement, Retention and Churn.
+Totalizer makes it easy for Ruby on Rails developers to report on Acquisition, Activation, Activity, Engagement, Retention and Churn.
+
+By defining two key metrics, Growth and Key Activity, all five reports can be generated.
+
+Metrics are only worthwhile if your team sees them so Totalizer includes notifiers for Slack and email.
 
 ### Installation
 
@@ -16,13 +20,172 @@ Or install it yourself as:
 
     $ gem install totalizer
 
-  
+### Configuration
+
+You need to define your Growth Metric and Key Activity Metric in order to use Totalizer. You can do this by creating a Totalizer initializer file in your Rails application:
+
+```ruby
+# config/initializers/totalizer.rb
+
+Totalizer.growth_metric = Totalizer::Metric.new model: User
+Totalizer.activity_metric = Totalizer::Metric.new model: Post, map: 'user_id'
+```
+
+The Growth Metric and the Key Activity Metric need to map to the same id to allow comparison.
+
+#### Metrics
+
+A Metric is a calculation based on one of your models for a duration of time.
+
+```ruby
+metric = Totalizer::Metric.new(model: User)
+
+metric.value
+#=> 10 (the number of records for the period)
+
+metric.start
+#=> 20 (the number of records before the period)
+
+metric.finish
+#=> 30 (the number of records at the end of the period)
+
+metric.rate
+#=> 0.5 (how much the number changed over the period)
+```
+
+##### Parameters
+
+You can pass the following parameters into the Metric:
++ `model` (required): The Rails model class that Totalizer will query.
++ `date`: When to start measuring your records. Default is `now`.
++ `duration`: Duration (in days) to measure your records from. Must be an integer. Default is `7`.
++ `filter`: Write a custom query to determine which records to use in calculation. For example to find all users who created a public response you could pass in: `filter: "is_public = true"`.
++ `map`: Which field to map records on. For example, to find unique users who did a response you could pass in: `map: 'user_id'`. Default is `id`.
+
+#### Notifiers
+
+By default, running the Totalizer rake tasks will output the metrics to your logs
+
+##### Action Mailer
+
+You can configure Totalizer to email metrics using ActionMailer, just ensure you have ActionMailer configured.
+
+To do this add the following lines to your initializer:
+
+```ruby
+Totalizer.notifiers = {
+	action_mailer: {
+		from:  %{"notifier" <notifier@example.com>},
+		to: %w{team@example.com}
+	}
+}
+```
+
+You can also optionally include: `subject`.
+
+##### Mandrill Mailer
+
+If you are using [mandrill_mailer gem](https://github.com/renz45/mandrill_mailer) in your application then you can configure Totalizer to email metrics using MandrillMailer, just ensure you have MandrillMailer configured.
+
+To do this add the following lines to your initializer:
+
+```ruby
+Totalizer.notifiers = {
+	mandrill_mailer: {
+		from:  %{"notifier" <notifier@example.com>},
+		to: %w{team@example.com}
+	}
+}
+```
+
+You can also optionally include: `subject`.
 
-*** 
+##### Slack Notifier
 
-## Factory
+You can configure Totalizer to post to Slack by including the [slack-notifier gem](https://github.com/stevenosloan/slack-notifier) in your Gemfile.
 
-The Totalizer Factory makes it easy to report on Acquisition, Activation, Engagement, Retention and Churn.
+```ruby
+gem 'slack-notifier'
+```
+
+Then add the following lines to your initializer:
+
+```ruby
+Totalizer.notifiers = {
+	slack: {
+		webhook_url: ENV['SLACK_WEBHOOK_URL'],
+		channel: ENV['SLACK_CHANNEL']
+	}
+}
+```
+
+You can also optionally include: `username`, `icon_emoji` and `color`.
+
+### Usage
+
+Totalizer comes with two rake tasks you can run.
+
+### Daily
+
+You don’t need to review every metric every day, but it’s good practice to monitor growth and activity on a daily basis so you can respond to any spikes or dips.
+
+Totalizer generates your Acquisition and Activity metrics for the previous day and the previous week.
+
+```
+$ rake totalizer:daily
+```
+
+This will generate the following report:
+
+```
+Acquisition
+  Yesterday: 20 (∆ 10%)
+  Last 7 days: 100 (∆ 7%)
+  Signed up this period (with rate of change)
+Activity
+  Yesterday: 60 (∆ 9%)
+  Last 7 days: 120 (∆ 8%)
+  Key activities this period (with rate of change)
+```
+
+### Weekly
+
+Every week it’s important to review your important metrics to ensure you are trending in the right direction.
+
+Totalizer generates your Activation, Engagement, Retention and Churn for the previous week and previous month.
+
+```
+$ rake totalizer:weekly
+```
+
+This will generate the following report:
+
+```
+Activation
+  Created this period and did key activity
+  Last 7 days: 77 → 58 (75.32%)
+  Last 30 days: 444 → 355 (79.95%)
+Engagement
+  Created before this period and did key activity this period
+  Last 7 days: 56.18% (150/267)
+  Last 30 days: 34.14% (210/615)
+Retention
+  Did key activity the previous period and again this period
+  Last 7 days: 61.19% (134/219)
+  Last 30 days: 69.42% (722/1040)
+Churn
+  Did key activity last period but not this period over the total who did key activity last period plus new users
+  Last 7 days: 6.21% (9/145)
+  Last 30 days: 3.29% (34/1032)
+```
+
+***
+
+In addition to Metric, you can also use the following underlying objects.
+
+### Factory
+
+The Totalizer Factory is what generates the Acquisition, Activation, Engagement, Retention and Churn reports.
 
 By defining one growth metric, like new user creation, and one key activity metric, like creating a post, you can generate all five reports.
 
@@ -36,20 +199,16 @@ factory = Totalizer::Factory.new(growth_metric: growth_metric, activity_metric:
 
 This will return a message object for each calculation.
 
-#### Parameters
+##### Parameters
 
 You can pass the following parameters into the Factory:
 
 + `growth_metric`: (required) a Totalizer metric representing growth, usually a User model.
 + `activity_metric`: (required) a Totalizer metric representing the key activity a user should do within your application.
 + `date`: When to start measuring your records from. Must be a DateTime. Default is `now`.
-+ `acquisition_duration`: Duration (in days) to measure your records. Must be an integer. Default is `7`.
-+ `activation_duration`: Duration (in days) to measure your activation. Must be an integer. Default is `7`.
-+ `engagement_duration`: Duration (in days) to measure your engagement. Must be an integer. Default is `7`.
-+ `retention_duration`: Duration (in days) to measure your retention. Must be an integer. Default is `30`.
-+ `churn_duration`: Duration (in days) to measure your churn. Must be an integer. Default is `30`.
++ `duration`: Duration (in days) to measure your records. Must be an integer. Default is `7`.
 
-### Acquisition
+#### Acquisition
 
 ```ruby
 growth_metric = Totalizer::Metric.new(model: User)
@@ -67,7 +226,7 @@ acquisition.text
 #=> "74 (Growth rate: 10%)"
 ```
 
-### Activation
+#### Activation
 
 ```ruby
 growth_metric = Totalizer::Metric.new(model: User)
@@ -85,7 +244,7 @@ activation.text
 #=> "63/90  (Conversion rate: 70%)"
 ```
 
-### Engagement
+#### Engagement
 
 ```ruby
 growth_metric = Totalizer::Metric.new(model: User)
@@ -103,7 +262,7 @@ engagement.text
 #=> "42/350 (Engagement rate: 12%)"
 ```
 
-### Retention
+#### Retention
 
 ```ruby
 growth_metric = Totalizer::Metric.new(model: User)
@@ -121,7 +280,7 @@ retention.text
 #=> "42/75  56%"
 ```
 
-### Churn
+#### Churn
 
 ```ruby
 growth_metric = Totalizer::Metric.new(model: User)
@@ -139,57 +298,15 @@ churn.text
 #=> "33/75  44%"
 ```
 
-## Make your metrics visible
-
-Metrics are only worthwhile if the team actually sees them.
-
-With the results of your Factory you can:
-+ Post them to Slack
-+ Send them via email
-+ Create a dashboard view
-
-***
-
-You can also access the underlying objects directly.
-
-### Metric
-
-A Metric is a calculation based on one of your models for a duration of time. To create a Metric just use this in your Rails application:
-
-```ruby
-metric = Totalizer::Metric.new(model: User)
-
-metric.value
-#=> 10 (the number of records for the period)
-
-metric.start
-#=> 20 (the number of records before the period)
-
-metric.finish
-#=> 30 (the number of records at the end of the period)
-
-metric.rate
-#=> 0.5 (how much the number changed over the period)
-```
-
-##### Parameters
-
-You can pass the following parameters into the Metric:
-+ `model` (required): The Rails model class that Totalizer will query.
-+ `date`: When to start measuring your records. Default is `now`.
-+ `duration`: Duration (in days) to measure your records from. Must be an integer. Default is `7`.
-+ `filter`: Write a custom query to determine which records to use in calculation. For example to find all users who created a public response you could pass in: `filter: "is_public = true"`.
-+ `map`: Which field to map records on. For example, to find unique users who did a response you could pass in: `map: 'user_id'`. Default is `id`.
-
 ### Step
 
 A step allows you to easily compare two sets of ids to see who converted.
 
-To create a Funnel just use this in your Rails application:
+To create a Step just use this in your Rails application:
 
 ```ruby
 first_metric = Totalizer::Metric.new(model: User)
-second_metric = Totalizer::Metric.new(model: User, filter: "actions > 0")
+second_metric = Totalizer::Metric.new(model: Post, map: 'user_id')
 step = Totalizer::Step.new first_step_metric.ids, second_step_metric.ids
 
 step.start
@@ -208,15 +325,13 @@ step.ids
 You can use the result of one step to feed into another step. Continuing on the example above, you could do the following:
 
 ```ruby
-third_metric = Totalizer::Metric.new(model: User, filter: "actions > 5")
+third_metric = Totalizer::Metric.new(model: Comment, map: 'user_id')
 next_step = Totalizer::Step.new step.ids, third_metric.ids
 ```
 
-***
-
 ## Manual Calculations
 
-You can also report on Acquisition, Activation, Retention, Engagement and Churn yourself without using a Factory.
+You can also report on Acquisition, Activity, Activation, Retention, Engagement and Churn yourself without using a Factory.
 
 ### Acquisition
 
@@ -230,11 +345,23 @@ acquisition.rate
 #=> 10
 ```
 
+### Activity
+
+```ruby
+activity = Totalizer::Metric.new(model: Post, map: 'user_id')
+
+acquisition.value
+#=> 20
+
+acquisition.rate
+#=> 5
+```
+
 ### Activation
 
 ```ruby
 sign_up = Totalizer::Metric.new(model: User, duration: 7)
-do_action = Totalizer::Metric.new(model: User, filter: "actions > 0")
+do_action = Totalizer::Metric.new(model: Post, map: 'user_id')
 activation = Totalizer::Step.new sign_up.ids, do_action.ids
 
 activation.start
@@ -251,7 +378,7 @@ activation.rate
 
 ```ruby
 sign_up = Totalizer::Metric.new(model: User, duration: 7)
-do_action = Totalizer::Metric.new(model: User, filter: "actions > 0")
+do_action = Totalizer::Metric.new(model: Post, map: 'user_id')
 
 existing_active = (sign_up.start_ids & do_action.ids).size
 #=> 14
@@ -315,7 +442,7 @@ lost_existing_customers.to_f / (new_and_existing_customers - lost_existing_custo
 
 The MIT License (MIT)
 
-Copyright (c) 2014 Michael Dijkstra
+Copyright (c) 2016 Michael Dijkstra
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/tasks/totalizer.rake

@@ -0,0 +1,26 @@
+namespace :totalizer do
+  task validate: :environment do
+    abort '! Growth metric not defined. Please define your growth metric before running this task. See https://github.com/micdijkstra/totalizer' unless Totalizer.growth_metric
+    abort '! Activity metric not defined. Please define your growth metric before running this task. See https://github.com/micdijkstra/totalizer' unless Totalizer.activity_metric
+  end
+
+  task daily: :validate do
+    Totalizer.logger.info "Totalizer: Daily"
+    messages = {
+      acquisition: [Totalizer.generate(:acquisition, 1), Totalizer.generate(:acquisition, 7)],
+      activity: [Totalizer.generate(:activity, 1), Totalizer.generate(:activity, 7)],
+    }
+    Totalizer.notify messages
+  end
+
+  task weekly: :validate do
+    Totalizer.logger.info "Totalizer: Daily"
+    messages = {
+      activation: [Totalizer.generate(:activation, 7), Totalizer.generate(:activation, 30)],
+      engagement: [Totalizer.generate(:engagement, 7), Totalizer.generate(:engagement, 30)],
+      retention: [Totalizer.generate(:retention, 7), Totalizer.generate(:retention, 30)],
+      churn: [Totalizer.generate(:churn, 7), Totalizer.generate(:churn, 30)],
+    }
+    Totalizer.notify messages
+  end
+end

data/lib/totalizer/base.rb

@@ -0,0 +1,48 @@
+module Totalizer
+  extend self
+  NOTIFIERS = { log: Totalizer::LogNotifier, action_mailer: Totalizer::ActionMailerNotifier, mandrill_mailer: Totalizer::MandrillMailerNotifier, slack: Totalizer::SlackNotifier }
+  attr_reader :growth_metric, :activity_metric
+
+  def growth_metric= metric
+    @growth_metric = validate_metric(metric)
+  end
+
+  def activity_metric= metric
+    @activity_metric = validate_metric(metric)
+  end
+
+  def validate_metric metric
+    raise Errors::InvalidMetric unless metric.kind_of?(Totalizer::Metric)
+    metric
+  end
+
+  def factory
+    @factory ||= Totalizer::Factory.new growth_metric, activity_metric
+  end
+
+  def date= date
+    factory.date = date
+  end
+
+  def generate build, duration=nil
+    factory.duration = duration
+    factory.send(build)
+  end
+
+  def notifiers
+    @notifiers ||= {}
+  end
+
+  def notifiers= notifiers
+    @notifiers = notifiers
+  end
+
+  def notify message_groups
+    notifiers.merge({ log: {} }).each { |notifier| fire_notification(notifier, message_groups) }
+  end
+
+  def fire_notification notifier_options, message_groups
+    notifier = NOTIFIERS[notifier_options.first]
+    notifier.call(message_groups, notifier_options.last)
+  end
+end

data/lib/totalizer/errors.rb

@@ -3,6 +3,9 @@ module Totalizer
     class InvalidData < StandardError
     end
 
+    class InvalidMetric < InvalidData
+    end
+
     class InvalidModel < InvalidData
     end
 

data/lib/totalizer/factory.rb

@@ -1,81 +1,59 @@
 module Totalizer
   class Factory
-    attr_accessor :growth_metric, :activity_metric, :date, :acquisition_duration, :activation_duration, :engagement_duration, :retention_duration, :churn_duration
+    attr_accessor :growth_metric, :activity_metric, :date, :duration
 
-    def initialize params
-      self.growth_metric = params[:growth_metric]
-      self.activity_metric = params[:activity_metric]
+    def initialize growth_metric, activity_metric, params={}
+      self.growth_metric = growth_metric
+      self.activity_metric = activity_metric
       self.date = params[:date] || DateTime.now
-      self.acquisition_duration = params[:acquisition_duration] || 7
-      self.activation_duration = params[:activation_duration] || 7
-      self.engagement_duration = params[:engagement_duration] || 7
-      self.retention_duration = params[:retention_duration] || 30
-      self.churn_duration = params[:churn_duration] || 30
+      self.duration = params[:duration] || 7
       validate_attributes!
     end
 
     def acquisition
-      @acquisition ||= calculate_acquisition
+      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: duration)
+      AcqusitionMessage.new(growth_metric, duration)
     end
 
     def activation
-      @activation ||= calculate_activation
+      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: duration)
+      activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: duration)
+      step = Totalizer::Step.new growth_metric.ids, activity_metric.ids
+      ActivationMessage.new(step, duration)
+    end
+
+    def activity
+      activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: duration, map: 'id')
+      ActivityMessage.new(activity_metric, duration)
     end
 
     def engagement
-      @engagement ||= calculate_engagement
+      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: duration)
+      activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: duration)
+      EngagementMessage.new(growth_metric, activity_metric, duration)
     end
 
     def retention
-      @retention || calculate_retention
+      previous_period = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date - duration.days, duration: duration)
+      this_period = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: duration)
+      step = Totalizer::Step.new previous_period.ids, this_period.ids
+      RetentionMessage.new(step, duration)
     end
 
     def churn
-      @churn || calculate_churn
+      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: duration)
+      previous_activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date - duration.days, duration: duration)
+      this_activity_metc = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: duration)
+      ChurnMessage.new(growth_metric, previous_activity_metric, this_activity_metc, duration)
     end
 
     private
 
-    def calculate_acquisition
-      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: acquisition_duration)
-      AcqusitionMessage.new(growth_metric, acquisition_duration)
-    end
-
-    def calculate_activation
-      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: activation_duration)
-      activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: activation_duration)
-      step = Totalizer::Step.new growth_metric.ids, activity_metric.ids
-      ActivationMessage.new(step, activation_duration)
-    end
-
-    def calculate_engagement
-      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: engagement_duration)
-      activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: engagement_duration)
-      EngagementMessage.new(growth_metric, activity_metric, engagement_duration)
-    end
-
-    def calculate_retention
-      previous_period = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date - retention_duration.days, duration: retention_duration)
-      this_period = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: retention_duration)
-      step = Totalizer::Step.new previous_period.ids, this_period.ids
-      RetentionMessage.new(step, retention_duration)
-    end
-
-    def calculate_churn
-      growth_metric = Totalizer::Metric.new self.growth_metric.attributes.merge(date: date, duration: churn_duration)
-      previous_activity_metric = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date - churn_duration.days, duration: churn_duration)
-      this_activity_metc = Totalizer::Metric.new self.activity_metric.attributes.merge(date: date, duration: churn_duration)
-      ChurnMessage.new(growth_metric, previous_activity_metric, this_activity_metc, churn_duration)
-    end
-
     def validate_attributes!
-      raise Errors::InvalidData unless growth_metric.kind_of?(Totalizer::Metric)
-      raise Errors::InvalidData unless activity_metric.kind_of?(Totalizer::Metric)
+      raise Errors::InvalidMetric unless growth_metric.kind_of?(Totalizer::Metric)
+      raise Errors::InvalidMetric unless activity_metric.kind_of?(Totalizer::Metric)
       raise Errors::InvalidDate unless date.kind_of?(DateTime)
-      raise Errors::InvalidDuration unless acquisition_duration.kind_of?(Integer)
-      raise Errors::InvalidDuration unless activation_duration.kind_of?(Integer)
-      raise Errors::InvalidDuration unless retention_duration.kind_of?(Integer)
-      raise Errors::InvalidDuration unless churn_duration.kind_of?(Integer)
+      raise Errors::InvalidDuration unless duration.kind_of?(Integer)
     end
   end
 end

data/lib/totalizer/logger.rb

@@ -0,0 +1,9 @@
+module Totalizer
+  def self.logger
+    @@logger ||= defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+  end
+
+  def self.logger=(logger)
+    @@logger = logger
+  end
+end

data/lib/totalizer/message.rb

@@ -1,67 +1,76 @@
 module Totalizer
   class Message
-    attr_accessor :title, :pretext, :text, :duration
+    attr_accessor :description, :text, :duration
 
-    def days_string
-      "#{duration if duration != 1} #{'day'.pluralize(duration)}"
+    def period_string
+      if duration > 1
+        "Last #{duration} #{'day'.pluralize(duration)}"
+      else
+        duration == 0 ? 'Today' : 'Yesterday'
+      end
+    end
+
+    def percentage_string value
+      "#{(value.to_f * 100).round(2).to_s.gsub(/.0$/, '')}%"
     end
   end
 
-  class AcqusitionMessage < Message
-    def initialize growth_metric, duration
+  class MetricMessage < Message
+    def initialize metric, duration
       self.duration = duration
-      self.title = 'Acqusition'
-      self.pretext = "Signed up in the last #{days_string}"
-      self.text = "#{growth_metric.value} (Growth rate: #{(growth_metric.rate * 100).round(0)}%)"
+      self.text = "#{period_string}: #{metric.value} (∆ #{percentage_string(metric.rate)})"
+    end
+  end
+
+  class AcqusitionMessage < MetricMessage
+    def initialize metric, duration
+      super
+      self.description = "Signed up this period (with rate of change)"
+    end
+  end
+
+  class ActivityMessage < MetricMessage
+    def initialize metric, duration
+      super
+      self.description = "Key activities this period (with rate of change)"
     end
   end
 
-  class StepMessage < Message
+  class ActivationMessage < Message
     def initialize step, duration
       self.duration = duration
-      self.text = "#{step.finish}/#{step.start} (Conversion rate: #{(step.rate * 100).round(0)}%)"
+      self.text = "#{period_string}: #{step.start} → #{step.finish} (#{percentage_string(step.rate)})"
+      self.description = "Created this period and did key activity"
     end
   end
 
   class EngagementMessage < Message
     def initialize growth_metric, activity_metric, duration
       self.duration = duration
-      self.title = 'Engagement'
 
       existing_active = (growth_metric.start_ids & activity_metric.ids).size
-
-      self.pretext = "Signed up more than #{days_string} ago and did key activity in the last #{days_string}"
-      self.text = "#{existing_active}/#{growth_metric.start} (Engagement rate: #{(existing_active.to_f / growth_metric.start.to_f * 100).round(0)}%)"
+      self.text = "#{period_string}: #{percentage_string existing_active.to_f / growth_metric.start.to_f} (#{existing_active}/#{growth_metric.start})"
+      self.description = "Created before this period and did key activity this period"
     end
   end
 
-  class ActivationMessage < StepMessage
+  class RetentionMessage < Message
     def initialize step, duration
-      super
-      self.title = 'Activation'
-      self.pretext = "Signed up in the last #{days_string} and did key activity"
-    end
-  end
-
-  class RetentionMessage < StepMessage
-    def initialize step, duration
-      super
-      self.title = 'Retention'
-      self.pretext = "Did key activity more than #{days_string} ago and again in the last #{days_string}"
+      self.duration = duration
+      self.text = "#{period_string}: #{percentage_string(step.rate)} (#{step.finish}/#{step.start})"
+      self.description = "Did key activity the previous period and again this period"
     end
   end
 
   class ChurnMessage < Message
     def initialize growth_metric, previous_activity_metric, this_activity_metc, duration
       self.duration = duration
-      self.title = 'Churn'
-      self.pretext = "Acquired more than #{days_string} ago and did not do key activity in last #{days_string} over total acquired"
 
-      new_and_existing = growth_metric.finish
+      new_and_existing = previous_activity_metric.value + growth_metric.value
       lost_existing = (previous_activity_metric.ids - this_activity_metc.ids).size
       final = new_and_existing - lost_existing
-
-      self.text = "#{lost_existing}/#{new_and_existing} (Churn rate: #{(lost_existing.to_f / new_and_existing.to_f * 100).round(0)}%)"
+      self.text = "#{period_string}: #{percentage_string lost_existing.to_f / new_and_existing.to_f} (#{lost_existing}/#{new_and_existing})"
+      self.description = "Did key activity last period but not this period over the total who did key activity last period plus new users"
     end
   end
 end

data/lib/totalizer/metric.rb

@@ -48,7 +48,7 @@ module Totalizer
     end
 
     def rate
-      (finish - start).to_f / start.to_f
+      start == 0 ? 0 : (finish - start).to_f / start.to_f
     end
 
     private

data/lib/totalizer/notifier/action_mailer_notifier.rb

@@ -0,0 +1,9 @@
+require 'action_mailer'
+
+module Totalizer
+  class ActionMailerNotifier < EmailNotifier
+    def self.send body, options
+      ActionMailer::Base.mail(from: options[:from], to: options[:to], subject: options[:subject], body: body).deliver_now
+    end
+  end
+end

data/lib/totalizer/notifier/base_notifier.rb

@@ -0,0 +1,4 @@
+module Totalizer
+  class BaseNotifier
+  end
+end

data/lib/totalizer/notifier/email_notifier.rb

@@ -0,0 +1,23 @@
+require 'action_mailer'
+
+module Totalizer
+  class EmailNotifier < BaseNotifier
+    DEFAULT_OPTIONS = { subject: '[Totalizer] Your important metrics', from: 'totalizer@totalizer.io' }
+
+    def self.call(message_groups, options)
+      body = ""
+      message_groups.each do |message_type, messages|
+        body += "\n#{message_type.to_s.capitalize}\n"
+        description = messages.map{ |message| message.description }.uniq.join("\n")
+        body += "#{description}\n"
+
+        text = messages.map{ |message| message.text }.join("\n")
+        body += "#{text}\n"
+      end
+
+      body += "\n— Totalizer"
+
+      self.send body, DEFAULT_OPTIONS.merge(options)
+    end
+  end
+end

data/lib/totalizer/notifier/log_notifier.rb

@@ -0,0 +1,14 @@
+module Totalizer
+  class LogNotifier < BaseNotifier
+    def self.call(message_groups, options)
+      message_groups.each do |message_type, messages|
+        Totalizer.logger.info message_type.to_s.capitalize
+
+        description = messages.map{ |message| message.description }.uniq.join(", ")
+        Totalizer.logger.info "  #{description}"
+
+        messages.each { |message| Totalizer.logger.info "  #{message.text}" }
+      end
+    end
+  end
+end

data/lib/totalizer/notifier/mandrill_mailer_notifier.rb

@@ -0,0 +1,9 @@
+require 'mandrill_mailer'
+
+module Totalizer
+  class MandrillMailerNotifier< EmailNotifier
+    def self.send body, options
+      MandrillMailer::MessageMailer.mandrill_mail(from: options[:from], to: options[:to], subject: options[:subject], text: body).deliver_now
+    end
+  end
+end

data/lib/totalizer/notifier/slack_notifier.rb

@@ -0,0 +1,16 @@
+require 'slack-notifier'
+
+module Totalizer
+  class SlackNotifier < BaseNotifier
+    DEFAULT_OPTIONS = { username: 'Totalizer', icon_emoji: ":nerd_face:", color: '#5767ff' }
+
+    def self.call(message_groups, options)
+      notifier = Slack::Notifier.new options[:webhook_url], DEFAULT_OPTIONS.merge(options)
+      message_groups.each do |message_type, messages|
+        text = messages.map{ |message| message.text }.join("\n")
+        description = messages.map{ |message| message.description }.uniq.join("\n")
+        notifier.ping message_type.to_s.capitalize, attachments: [{ fallback: text, color: options[:color], text: text, footer: description }]
+      end
+    end
+  end
+end

data/lib/totalizer/notifier.rb

@@ -0,0 +1,6 @@
+require "totalizer/notifier/base_notifier"
+require "totalizer/notifier/log_notifier"
+require 'totalizer/notifier/email_notifier'
+require 'totalizer/notifier/action_mailer_notifier'
+require 'totalizer/notifier/mandrill_mailer_notifier'
+require 'totalizer/notifier/slack_notifier'

data/lib/totalizer/railtie.rb

@@ -0,0 +1,12 @@
+require 'totalizer'
+require 'rails'
+
+module Totalizer
+  class Railtie < Rails::Railtie
+    railtie_name :totalizer
+
+    rake_tasks do
+      load "tasks/totalizer.rake"
+    end
+  end
+end

data/lib/totalizer/version.rb

@@ -1,3 +1,3 @@
 module Totalizer
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/lib/totalizer.rb

@@ -1,6 +1,10 @@
 require "totalizer/version"
+require 'totalizer/logger'
 require 'totalizer/errors'
 require 'totalizer/metric'
 require 'totalizer/step'
 require 'totalizer/factory'
 require 'totalizer/message'
+require 'totalizer/notifier'
+require 'totalizer/railtie' if defined?(Rails)
+require "totalizer/base"

data/spec/lib/totalizer/factory_spec.rb

@@ -5,39 +5,27 @@ describe Totalizer::Factory do
   let(:activity_metric) { Totalizer::Metric.new model: Post, map: 'user_id' }
   let(:duration) { nil }
   let(:date) { nil }
-  let(:factory) { Totalizer::Factory.new growth_metric: growth_metric, activity_metric: activity_metric, date: date, retention_duration: 7, churn_duration: 7 }
+  let(:factory) { Totalizer::Factory.new growth_metric, activity_metric, date: date }
 
   describe "Validate" do
     it "requires metrics" do
-      expect{ Totalizer::Factory.new(growth_metric: 'fake', activity_metric: 'metric') }.to raise_exception(Totalizer::Errors::InvalidData)
+      expect{ Totalizer::Factory.new('fake', 'metric') }.to raise_exception(Totalizer::Errors::InvalidMetric)
     end
 
     it "requires activity metric" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: 'metric') }.to raise_exception(Totalizer::Errors::InvalidData)
+      expect{ Totalizer::Factory.new(growth_metric, 'metric') }.to raise_exception(Totalizer::Errors::InvalidMetric)
     end
 
     it "requires growth metric" do
-      expect{ Totalizer::Factory.new(growth_metric: 'fake', activity_metric: activity_metric) }.to raise_exception(Totalizer::Errors::InvalidData)
+      expect{ Totalizer::Factory.new('fake', activity_metric) }.to raise_exception(Totalizer::Errors::InvalidMetric)
     end
 
     it "requires a valid datetime" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: activity_metric, date: 'Whenever') }.to raise_exception(Totalizer::Errors::InvalidDate)
+      expect{ Totalizer::Factory.new(growth_metric, activity_metric, date: 'Whenever') }.to raise_exception(Totalizer::Errors::InvalidDate)
     end
 
-    it "requires a acquisition duration" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: activity_metric, acquisition_duration: 'Whatever') }.to raise_exception(Totalizer::Errors::InvalidDuration)
-    end
-
-    it "requires a activation duration" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: activity_metric, activation_duration: 'Whatever') }.to raise_exception(Totalizer::Errors::InvalidDuration)
-    end
-
-    it "requires a retention duration" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: activity_metric, retention_duration: 'Whatever') }.to raise_exception(Totalizer::Errors::InvalidDuration)
-    end
-
-    it "requires a churn duration" do
-      expect{ Totalizer::Factory.new(growth_metric: growth_metric, activity_metric: activity_metric, churn_duration: 'Whatever') }.to raise_exception(Totalizer::Errors::InvalidDuration)
+    it "requires a duration" do
+      expect{ Totalizer::Factory.new(growth_metric, activity_metric, duration: 'Whatever') }.to raise_exception(Totalizer::Errors::InvalidDuration)
     end
   end
 
@@ -47,7 +35,7 @@ describe Totalizer::Factory do
     end
 
     it "defaults to 7 day acquisition duration" do
-      expect(factory.acquisition_duration).to eq 7
+      expect(factory.duration).to eq 7
     end
   end
 
@@ -69,72 +57,43 @@ describe Totalizer::Factory do
     end
 
     describe "Acquisition" do
-      it "returns title" do
-        expect(factory.acquisition.title).to eq 'Acqusition'
-      end
-
-      it "returns pretext" do
-        expect(factory.acquisition.pretext).to eq 'Signed up in the last 7 days'
+      it "returns text" do
+        expect(factory.acquisition.text).to eq "Last 7 days: 2 (∆ 50%)"
       end
+    end
 
+    describe "Activity" do
       it "returns text" do
-        expect(factory.acquisition.text).to eq "2 (Growth rate: 50%)"
+        expect(factory.activity.text).to eq "Last 7 days: 2 (∆ 50%)"
       end
     end
 
     describe "Activation" do
-      it "returns title" do
-        expect(factory.activation.title).to eq 'Activation'
-      end
-
-      it "returns pretext" do
-        expect(factory.activation.pretext).to eq 'Signed up in the last 7 days and did key activity'
-      end
-
       it "returns text" do
-        expect(factory.activation.text).to eq "1/2 (Conversion rate: 50%)"
+        expect(factory.activation.text).to eq "Last 7 days: 2 → 1 (50%)"
       end
     end
 
     describe "Engagement" do
-      it "returns title" do
-        expect(factory.engagement.title).to eq 'Engagement'
-      end
-
-      it "returns pretext" do
-        expect(factory.engagement.pretext).to eq 'Signed up more than 7 days ago and did key activity in the last 7 days'
-      end
-
       it "returns text" do
-        expect(factory.engagement.text).to eq "1/4 (Engagement rate: 25%)"
+        expect(factory.engagement.text).to eq "Last 7 days: 25% (1/4)"
       end
     end
 
     describe "Retention" do
-      it "returns title" do
-        expect(factory.retention.title).to eq 'Retention'
-      end
-
-      it "returns pretext" do
-        expect(factory.retention.pretext).to eq 'Did key activity more than 7 days ago and again in the last 7 days'
-      end
-
       it "returns text" do
-        expect(factory.retention.text).to eq "1/4 (Conversion rate: 25%)"
+        expect(factory.retention.text).to eq "Last 7 days: 25% (1/4)"
       end
     end
 
     describe "Churn" do
-      it "returns title" do
-        expect(factory.churn.title).to eq 'Churn'
-      end
-
-      it "returns pretext" do
-        expect(factory.churn.pretext).to eq 'Acquired more than 7 days ago and did not do key activity in last 7 days over total acquired'
+      let(:user_7) { FactoryGirl.create :user, created_at: 13.days.ago }
+      before do
+        FactoryGirl.create :post, user_id: user_7.id, created_at: 13.days.ago
       end
 
       it "returns text" do
-        expect(factory.churn.text).to eq "3/6 (Churn rate: 50%)"
+        expect(factory.churn.text).to eq "Last 7 days: 57.14% (4/7)"
       end
     end
   end

data/spec/lib/totalizer/metric_spec.rb

@@ -66,7 +66,7 @@ describe Totalizer::Metric do
       expect(metric.finish).to eq 3
     end
 
-    it "calculates the rate of rate" do
+    it "calculates the rate of change" do
       expect(metric.rate).to eq 2
     end
 
@@ -77,6 +77,14 @@ describe Totalizer::Metric do
         expect{ metric.value }.to raise_exception(ActiveRecord::StatementInvalid)
       end
     end
+
+    describe 'with 0 records' do
+      let(:metric) { Totalizer::Metric.new(model: User, filter: ['created_at > ?', DateTime.now] ) }
+
+      it "calculates the rate of change" do
+        expect(metric.rate).to eq 0
+      end
+    end
   end
 
   describe "Filter" do
@@ -109,7 +117,7 @@ describe Totalizer::Metric do
       expect(metric.finish).to eq 2
     end
 
-    it "calculates the rate of rate" do
+    it "calculates the rate of change" do
       expect(metric.rate).to eq 1
     end
   end

data/spec/lib/totalizer_spec.rb

@@ -0,0 +1,91 @@
+require 'spec_helper'
+
+describe Totalizer do
+  describe "Validate" do
+    it "require a growth metrics" do
+      expect{ Totalizer.growth_metric = 'fake' }.to raise_exception(Totalizer::Errors::InvalidMetric)
+    end
+
+    it "require an activity metric" do
+      expect{ Totalizer.activity_metric = 'fake' }.to raise_exception(Totalizer::Errors::InvalidMetric)
+    end
+  end
+
+  describe "Initialize" do
+    let(:growth_metric) { Totalizer::Metric.new model: User }
+    let(:activity_metric) { Totalizer::Metric.new model: Post, map: 'user_id' }
+
+    before do
+      Totalizer.growth_metric = growth_metric
+      Totalizer.activity_metric = activity_metric
+    end
+
+    it "creates a factory" do
+      expect(Totalizer.factory).not_to eq nil
+      expect(Totalizer.factory.kind_of?(Totalizer::Factory)).to eq true
+    end
+  end
+
+  describe ".notify" do
+    let(:growth_metric) { Totalizer::Metric.new model: User }
+    let(:message) { Totalizer::AcqusitionMessage.new(growth_metric, 1) }
+    let(:messages) { { activation: [message] } }
+    before do
+      allow(Totalizer::ActionMailerNotifier).to receive(:send)
+      allow(Totalizer::MandrillMailerNotifier).to receive(:send)
+      allow( Slack::Notifier::DefaultHTTPClient).to receive(:post)
+    end
+
+    it "does not send to Slack by default" do
+      Totalizer.notify messages
+      expect(Totalizer::SlackNotifier).not_to receive(:call)
+    end
+
+    describe "with action mailer notifier configured" do
+      before do
+        Totalizer.notifiers = {
+          action_mailer: {
+            to: 'admin@example.com'
+          }
+        }
+      end
+
+      it "sends Email" do
+        Totalizer.notify messages
+        expect(Totalizer::ActionMailerNotifier).to respond_to(:send).with(2).arguments
+      end
+    end
+
+    describe "with mandrill mailer notifier configured" do
+      before do
+        Totalizer.notifiers = {
+          mandrill_mailer: {
+            to: 'admin@example.com'
+          }
+        }
+      end
+
+      it "sends Email" do
+        Totalizer.notify messages
+        expect(Totalizer::MandrillMailerNotifier).to respond_to(:send).with(2).arguments
+      end
+    end
+
+
+    describe "with Slack notifier configured" do
+      before do
+        Totalizer.notifiers = {
+          slack: {
+            webhook_url: 'http://slack.webhook.url',
+            channel: '#general'
+          }
+        }
+      end
+
+      it "sends to Slack" do
+        Totalizer.notify messages
+        expect(Totalizer::SlackNotifier).to respond_to(:call).with(2).arguments
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -11,6 +11,7 @@ require 'active_record'
 require 'factory_girl'
 require 'database_cleaner'
 require 'timecop'
+require 'mandrill_mailer/offline'
 
 ActiveRecord::Base.establish_connection adapter: "sqlite3", database: ":memory:"
 load File.dirname(__FILE__) + '/support/schema.rb'

data/totalizer.gemspec

@@ -26,4 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "factory_girl_rails"
   spec.add_development_dependency "database_cleaner"
   spec.add_development_dependency "timecop"
+  spec.add_development_dependency "actionmailer"
+  spec.add_development_dependency "mandrill_mailer"
+  spec.add_development_dependency "slack-notifier"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: totalizer
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Michael Dijkstra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-01 00:00:00.000000000 Z
+date: 2016-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  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'
+- !ruby/object:Gem::Dependency
+  name: mandrill_mailer
+  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'
+- !ruby/object:Gem::Dependency
+  name: slack-notifier
+  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: Provides tools to Ruby on Rails developers to create calculations for
   acquisiton, activation, engagement, retention and churn.
 email:
@@ -135,16 +177,28 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/tasks/totalizer.rake
 - lib/totalizer.rb
+- lib/totalizer/base.rb
 - lib/totalizer/errors.rb
 - lib/totalizer/factory.rb
+- lib/totalizer/logger.rb
 - lib/totalizer/message.rb
 - lib/totalizer/metric.rb
+- lib/totalizer/notifier.rb
+- lib/totalizer/notifier/action_mailer_notifier.rb
+- lib/totalizer/notifier/base_notifier.rb
+- lib/totalizer/notifier/email_notifier.rb
+- lib/totalizer/notifier/log_notifier.rb
+- lib/totalizer/notifier/mandrill_mailer_notifier.rb
+- lib/totalizer/notifier/slack_notifier.rb
+- lib/totalizer/railtie.rb
 - lib/totalizer/step.rb
 - lib/totalizer/version.rb
 - spec/lib/totalizer/factory_spec.rb
 - spec/lib/totalizer/metric_spec.rb
 - spec/lib/totalizer/step_spec.rb
+- spec/lib/totalizer_spec.rb
 - spec/spec_helper.rb
 - spec/support/factories.rb
 - spec/support/models.rb
@@ -178,6 +232,7 @@ test_files:
 - spec/lib/totalizer/factory_spec.rb
 - spec/lib/totalizer/metric_spec.rb
 - spec/lib/totalizer/step_spec.rb
+- spec/lib/totalizer_spec.rb
 - spec/spec_helper.rb
 - spec/support/factories.rb
 - spec/support/models.rb