heya 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 586da260567f71076b1e9820815e2508a74ac42104a1b099296f05c2a07cdb1a
-  data.tar.gz: 354d3c9c0e7254063088b32edc0b5b4f877457121bf8f681b3e8c0fb1fbf91ee
+  metadata.gz: 897c67c77ab4b26f47d21ddde192e5957239cdb319c662fd72dd806de3c552d2
+  data.tar.gz: e34438a886e4c1598b0bca34bab406b84b83561310857f2c8730c669961e5a9a
 SHA512:
-  metadata.gz: 386d12c2aca08df55c2ca1e65f9691e120e3fa187ce3d5ba2e1168ddad3f2442b74e96763a430750a0f9c06270dac8a19bcf0413de5d2ae5833b7dd722632251
-  data.tar.gz: e5286d6b20aab8f58a74eb6592ca4f99efbd0f8bdf8c17bd957f7f3fd33bc02d2023eeae4b37847614794ac91a29a8bbe972d7a38452da5834a474955cafc5d2
+  metadata.gz: 6efc0529915073f5e3e2abb9a878e1f2e290cf66b66913989555325ac29f508988378e48637efaa36a345f3bc6ebd6978c110879c52d1999cea7bb3ec35e67a4
+  data.tar.gz: 02e88ebd7dea87ba644b380be61ffc41788c24045f8e103df302e44b1a8f82a37850ed56beb12b763b183061abf2526a5cd2affb6a175e155f7096d22a8dde7d

data/CHANGELOG.md

@@ -5,6 +5,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [0.7.0] - 2022-02-03
+### Fixed
+- Automatically include Rails url helpers from application in campaign mailer templates (#158, @feliperaul)
+
+### Added
+- Allow the customization of the to field (#155, @feliperaul)
+
+## [0.6.1] - 2022-01-05
+### Fixed
+- Support Rails 7 (#151, @800a7b32)
+
+## [0.6.0] - 2021-11-02
+### Added
+- Optional `layout` parameter for steps; allowing override from default `heya/campaign_mailer`
+
+## [0.5.3] - 2021-08-18
+### Added
+- Create `bcc:` optional parameter for steps; use case is quality control
+
+## [0.5.2] - 2021-08-11
 ### Fixed
 - Fix typo in initializer (#139, @800a7b32)
 

data/README.md

@@ -247,12 +247,54 @@ The `wait` option tells Heya how long to wait before sending each message (the d
 Heya uses the following additional options to build the message itself:
 
 | Option Name | Default      | Description                |
-| :---------- | :----------- | :------------------------- |
+|-------------|--------------|----------------------------|
 | `subject`   | **required** | The email's subject        |
 | `from`      | Heya default | The sender's email address |
+| `layout`    | Heya default | The email's layout file    |
+| `to`        | See below    | See below                  |
 
 You can change the default options using the `default` method at the top of the campaign. Heya applies default options to each step which doesn't supply its own:
 
+```ruby
+class OnboardingCampaign < ApplicationCampaign
+  default wait: 1.day,
+    queue: "onboarding",
+    from: "support@example.com",
+    layout: "onboarding"
+
+  # Will still be sent after one day from the
+  # email address support@example.com
+  step :welcome,
+    subject: "Welcome to my app!"
+end
+```
+
+#### Customizing the `to` field
+
+You can customize the `to` field by passing a callable object, which Heya will invoke with the user. For instance:
+
+```ruby
+class OnboardingCampaign < ApplicationCampaign
+  step :welcome,
+    subject: "Welcome to my app!",
+    to: -> (user) { ActionMailer::Base.email_address_with_name(user.email, user.nickname) }
+end
+```
+
+It is recommended to rely on `ActionMailer::Base.email_address_with_name` so that sanitization is correctly applied.
+
+If the `to` param is not provided, Heya will default to:
+
+1. `user#first_name`
+1. `user#name`
+
+If the `user` object doesn't respond to these methods, it will fallback to a simple `user.email` in the `to` field.
+
+#### Quality control option
+
+You may wish to apply quality control to individual steps of a campaign. For example, when adding a new step to an existing campaign it is
+a good idea to inspect real-time results in production. You can do this by using the `bcc:` step option, which would look like this:
+
 ```ruby
 class OnboardingCampaign < ApplicationCampaign
   default wait: 1.day,
@@ -263,6 +305,10 @@ class OnboardingCampaign < ApplicationCampaign
   # email address support@example.com
   step :welcome,
     subject: "Welcome to my app!"
+
+  step :added_two_months_later,
+    subject: "We now have something new to say!",
+    bcc: 'quality_control@example.com'
 end
 ```
 

data/app/mailers/heya/campaign_mailer.rb

@@ -1,6 +1,8 @@
 module Heya
   class CampaignMailer < ApplicationMailer
-    layout "heya/campaign_mailer"
+    DEFAULT_LAYOUT = "heya/campaign_mailer"
+    layout -> { params.fetch(:step).params.fetch("layout", DEFAULT_LAYOUT) }
+    include Rails.application.routes.url_helpers
 
     def build
       user = params.fetch(:user)
@@ -10,6 +12,7 @@ module Heya
       step_name = step.name.underscore
 
       from = step.params.fetch("from")
+      bcc = step.params.fetch("bcc", nil)
       reply_to = step.params.fetch("reply_to", nil)
 
       subject = step.params.fetch("subject") {
@@ -22,8 +25,9 @@ module Heya
 
       mail(
         from: from,
+        bcc: bcc,
         reply_to: reply_to,
-        to: user.email,
+        to: to_address(user, step),
         subject: subject,
         template_path: "heya/campaign_mailer/#{campaign_name}",
         template_name: step_name
@@ -49,5 +53,27 @@ module Heya
         end
       end
     end
+
+    def to_address(user, step)
+      return step.params["to"].call(user) if step.params["to"].respond_to?(:call)
+
+      if user.respond_to?(:first_name)
+        self.class.email_address_with_name(user.email, user.first_name)
+      elsif user.respond_to?(:name)
+        self.class.email_address_with_name(user.email, user.name)
+      else
+        user.email
+      end
+    end
+
+    # This method is a backport and can be removed when we drop support of
+    # Rails 6.0; As of Rails 6.1, ActionMailer::Base, which we inherit from,
+    # already includes it.
+    def self.email_address_with_name(address, name)
+      Mail::Address.new.tap do |builder|
+        builder.address = address
+        builder.display_name = name
+      end.to_s
+    end
   end
 end

data/lib/heya/campaigns/actions/email.rb

@@ -4,7 +4,7 @@ module Heya
   module Campaigns
     module Actions
       class Email < Action
-        VALID_PARAMS = %w[subject from reply_to]
+        VALID_PARAMS = %w[subject from reply_to bcc layout to]
 
         def self.validate_step(step)
           step.params.assert_valid_keys(VALID_PARAMS)

data/lib/heya/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: heya
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Joshua Wood
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-11 00:00:00.000000000 Z
+date: 2022-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -19,7 +19,7 @@ dependencies:
         version: 5.2.3
     - - "<"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: 7.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: 5.2.3
     - - "<"
       - !ruby/object:Gem::Version
-        version: 6.2.0
+        version: 7.1.0
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: "Heya \U0001F44B"