heya 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125b5f898dd3d7841fd0e50ae05d424ec56d2818bb011a43a083f224d15aa3ea
-  data.tar.gz: 23a1fd76278729817ab0317dff81ab816cabd9f09b323e8f723cb5c8f9186eff
+  metadata.gz: 91788b17940c18fd1196e0cc20f2892fb91233c714a5dc7c876833459ae867d3
+  data.tar.gz: 6f8694d2562802ff9102fd62e04349beaf464dee5043fd928e0403fd4deb6bab
 SHA512:
-  metadata.gz: 22b4d72ffa9e69068ce5a77008b76047cf3f1379d330f233b0a4f174a6a89d3a91ab3353e1941b4b1262a4898316cdc1b14e3842468e4fd9bbffa301234c3e62
-  data.tar.gz: bc5c5604c1e1d95adb14fe4435817431c4af2f471a5df7d6bfd4ec100d6a5607cbd4121a31d66660cde7e9a892b84126bf6b6e2d15676afbd36af2fad958910e
+  metadata.gz: 7315798099a708fa8bc0477e229672377634a29a97097139c2055ef09edd748edaf4a40a8685cfa015b87e766463ade73c3e10ea71ee41893184bea0ab7867ec
+  data.tar.gz: 3a437c995a6aaed616b75cce220c80bf28baf7d64364ac1956d11ce1e38c8bbf40d9a71bed97258e84d19d410970ae7ed48d07a6aaed92b92ebc3610ef9b654f

data/CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2020-04-23
+### Fixed
+- Update the install and campaign generators.
+
 ## [0.2.0] - 2020-04-14
 ### Added
 - Added licensing.

data/README.md

@@ -27,11 +27,12 @@ Getting started with Heya is easy:
   rails db:migrate
   ```
 
-  This will do 3 things:
+  This will:
 
   1. Copy Heya's migration files to *db/migrate*
-  2. Copy Heya's default initializer to *config/initializers/heya.rb*
-  3. Run local migrations
+  1. Copy Heya's default initializer to *config/initializers/heya.rb*
+  1. Create the file *app/campaigns/application_campaign.rb*
+  1. Run local migrations
 
 <details><summary>Note: Heya doesn't store a copy of your user data; instead, it reads from your existing <code>User</code> model (it never writes). If you have a different user model, change the <code>user_type</code> configuration option in <em>config/initializers/heya.rb</em>.</summary>
 
@@ -47,7 +48,7 @@ end
 1. Create a campaign:
 
   ```bash
-  rails generate heya:campaign Onboarding welcome
+  rails generate heya:campaign Onboarding welcome:0
   ```
 
 2. Add a user to your campaign:
@@ -55,14 +56,99 @@ end
   ```ruby
   OnboardingCampaign.add(user)
   ```
+  
+  Add the following to your `User` model to send them the campaign
+  when they first signup:
+  
+  ```ruby
+  after_create_commit do
+    OnboardingCampaign.add(self)
+  end
+  ```
 
 ### Running the scheduler
-To start sending emails, run the scheduler periodically:
+To start queuing emails, run the scheduler task periodically:
 
 ```bash
 rails heya:scheduler
 ```
 
+Heya uses ActiveJob to send emails in the background. Make sure your
+ActiveJob backend is configured to process the `heya` queue. For example,
+here's how you might start Sidekiq:
+
+```sh
+bundle exec sidekiq -q default -q heya
+```
+
+You can change Heya's default queue using the `queue` option:
+
+```ruby
+# app/campaigns/application_campaign.rb
+class ApplicationCampaign < Heya::Campaigns::Base
+  default queue: "custom"
+end
+```
+
+### Bonus: tips for working with email in Rails
+
+<details><summary>Use <a href="http://mailcatcher.me">MailCatcher</a> to see emails sent from your dev environment</summary>
+
+```ruby
+# config/environments/development.rb
+Rails.application.configure do
+  # ..
+
+  # Use MailCatcher to inspect emails
+  # http://mailcatcher.me
+  # Usage:
+  #   gem install mailcatcher
+  #   mailcatcher
+  #   # => Starting MailCatcher
+  #   # => ==> smtp://127.0.0.1:1025
+  #   # => ==> http://127.0.0.1:1080
+  config.action_mailer.delivery_method = :smtp
+  config.action_mailer.smtp_settings = {host: "localhost", port: 1025}
+end
+```
+</details>
+<details><summary>Use <a href="https://github.com/codetriage/maildown">Maildown</a> to write your emails in Markdown</summary>
+
+```sh
+$ bundle add maildown
+$ rails generate heya:campaign Onboarding welcome
+      create  app/campaigns/application_campaign.rb
+      create  app/campaigns/onboarding_campaign.rb
+      create  app/views/heya/campaign_mailer/onboarding_campaign/welcome.md.erb
+```
+
+☝️ Notice how only one template was generated; Maildown automatically builds
+the HTML and text variants from the markdown file.
+</details>
+<details><summary>Use <a href="https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails">ActionMailer::Preview</a> to preview emails as you write them</summary>
+
+Heya's campaign generator generates previews for campaigns at
+`(test|spec)/mailers/previews/*_campaign_preview.rb`. To see them, open
+http://localhost:3000/rails/mailers/. If you didn't use the generator, you
+can still build your own preview:
+
+```ruby
+# test/mailers/previews/onboarding_campaign_preview.rb
+class OnboardingCampaignPreview < ActionMailer::Preview
+  def welcome
+    OnboardingCampaign.welcome(user)
+  end
+
+  private
+
+  def user
+    User.where(id: params[:user_id]).first || User.first
+  end
+end
+
+```
+</details>
+
 ## Configuration
 
 You can use the following options to configure Heya (find this file in
@@ -96,11 +182,12 @@ Heya stores campaigns in *app/campaigns/*, similar to how Rails stores mailers i
 rails generate heya:campaign Onboarding first second third
 ```
 
-This will do three things:
+This will:
 
-- Create the file *app/campaigns/onboarding_campaign.rb*
-- Create the directory *app/views/heya/campaign_mailer/onboarding_campaign/*
-- Create email templates inside of *app/views/heya/campaign_mailer/onboarding_campaign/*
+1. Create the file *app/campaigns/onboarding_campaign.rb*
+1. Create the directory *app/views/heya/campaign_mailer/onboarding_campaign/*
+1. Create email templates inside of *app/views/heya/campaign_mailer/onboarding_campaign/*
+1. Create an ActionMailer preview at *(test|spec)/mailers/previews/onboarding_campaign_preview.rb*
 
 Here's the campaign that the above command generates:
 
@@ -316,6 +403,27 @@ class ApplicationCampaign < Heya::Campaigns::Base
 end
 ```
 
+### Handling exceptions
+
+Heya campaigns are [rescuable](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html).
+Use the `rescue_from` method to handle exceptions in campaigns:
+
+```ruby
+class OnboardingCampaign < ApplicationCampaign
+  rescue_from Postmark::InactiveRecipientError, with: :log_error
+
+  private
+
+  def log_error(error)
+    Rails.logger.error("Got Heya error: #{error}")
+  end
+end
+```
+
+See the
+[Rails documentation](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from)
+for additional details.
+
 ### Campaigns FAQ
 **What happens when:**
 <details><summary>I reorder messages in an active campaign?</summary>

data/lib/generators/heya/campaign/USAGE

@@ -2,7 +2,7 @@ Description:
     Generate a new campaign
 
 Example:
-    rails generate heya:campaign Onboarding first second third
+    rails generate heya:campaign Onboarding first:0 second:2.days third
 
     This will create:
         app/campaigns/onboarding_campaign.rb

data/lib/generators/heya/campaign/campaign_generator.rb

@@ -6,7 +6,10 @@ class Heya::CampaignGenerator < Rails::Generators::NamedBase
   argument :steps, type: :array, default: []
 
   def copy_campaign_template
-    template "application_campaign.rb", "app/campaigns/application_campaign.rb"
+    application_campaign = "app/campaigns/application_campaign.rb"
+    unless File.exist?(application_campaign)
+      template File.expand_path("../install/templates/application_campaign.rb", __dir__), application_campaign
+    end
     template "campaign.rb", "app/campaigns/#{file_name.underscore}_campaign.rb"
   end
 
@@ -35,11 +38,18 @@ class Heya::CampaignGenerator < Rails::Generators::NamedBase
       end
 
     steps.each do |step|
+      step, _wait = step.split(":")
       @step = step
       template_method.call(step)
     end
   end
 
+  def copy_test_templates
+    if preview_path
+      template "preview.rb", preview_path.join("#{file_name.underscore}_campaign_preview.rb")
+    end
+  end
+
   private
 
   def action_mailer_template(step)
@@ -50,4 +60,10 @@ class Heya::CampaignGenerator < Rails::Generators::NamedBase
   def maildown_template(step)
     template "message.md.erb", "app/views/heya/campaign_mailer/#{file_name.underscore}_campaign/#{step.underscore.to_sym}.md.erb"
   end
+
+  def preview_path
+    @preview_path ||= if ActionMailer::Base.preview_path.present?
+      Pathname(ActionMailer::Base.preview_path).sub(Rails.root.to_s, ".")
+    end
+  end
 end

data/lib/generators/heya/campaign/templates/campaign.rb.tt

@@ -1,7 +1,4 @@
-class <%= file_name.camelcase %>Campaign < ApplicationCampaign
-<% steps.each do |step| %>
-  step :<%= step.underscore.to_sym %>,
-    subject: "<%= step.humanize %> Message"
-
-<% end -%>
-end
+class <%= file_name.camelcase %>Campaign < ApplicationCampaign<% steps.each do |step| %><% step, wait = step.split(":") %>
+  step :<%= step.underscore.to_sym %>,<%= wait.presence ? "\n    wait: #{wait}," : "" %>
+    subject: "<%= step.humanize %>"
+<% end %>end

data/lib/generators/heya/campaign/templates/preview.rb.tt

@@ -0,0 +1,12 @@
+# Preview all emails at http://localhost:3000/rails/mailers/
+class <%= file_name.camelcase %>CampaignPreview < ActionMailer::Preview<% steps.each do |step| %><% step, wait = step.split(":") %>
+  def <%= step %>
+    <%= file_name.camelcase %>Campaign.<%= step %>(user)
+  end
+<% end %>
+  private
+
+  def user
+    <%= Heya.config.user_type %>.where(id: params[:user_id]).first || <%= Heya.config.user_type %>.first || <%= Heya.config.user_type %>.new(email: "user@example.com").freeze
+  end
+end

data/lib/generators/heya/install/install_generator.rb

@@ -13,6 +13,10 @@ class Heya::InstallGenerator < Rails::Generators::Base
     copy_file "initializer.rb", "config/initializers/heya.rb"
   end
 
+  def copy_application_campaign_template
+    template "application_campaign.rb", "app/campaigns/application_campaign.rb"
+  end
+
   def self.next_migration_number(dirname)
     next_migration_number = current_migration_number(dirname) + 1
     ActiveRecord::Migration.next_migration_number(next_migration_number)

data/lib/heya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Heya
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: heya
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Joshua Wood
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-14 00:00:00.000000000 Z
+date: 2020-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -88,13 +88,14 @@ files:
 - config/routes.rb
 - lib/generators/heya/campaign/USAGE
 - lib/generators/heya/campaign/campaign_generator.rb
-- lib/generators/heya/campaign/templates/application_campaign.rb.tt
 - lib/generators/heya/campaign/templates/campaign.rb.tt
 - lib/generators/heya/campaign/templates/message.html.erb.tt
 - lib/generators/heya/campaign/templates/message.md.erb.tt
 - lib/generators/heya/campaign/templates/message.text.erb.tt
+- lib/generators/heya/campaign/templates/preview.rb.tt
 - lib/generators/heya/install/USAGE
 - lib/generators/heya/install/install_generator.rb
+- lib/generators/heya/install/templates/application_campaign.rb.tt
 - lib/generators/heya/install/templates/initializer.rb.tt
 - lib/generators/heya/install/templates/migration.rb.tt
 - lib/heya.rb