feat(dunning): Add BCC emails addresses (#3354)

## Description

When creating a dunning campaign, you can now add a list of email
addresses to pass in the `bcc` field. This can help accounting team
keeping track of payment requests.

In GraphQL, the field is an array of string, each string is a valid
email address. It's NOT a single string containing comma-separated email
addresses (like we might do in other places).

```rb
["[email protected]", "[email protected]"] 
🆚 
"[email protected],[email protected]"
```

The dunning campaign is attached to the payment request so I only had to
check it in the Mailer. The rest is basically model + gql boilerplate.

Author: julienbourdeau

app/graphql/types/dunning_campaigns/create_input.rb

@@ -6,6 +6,7 @@ class CreateInput < Types::BaseInputObject
       graphql_name "CreateDunningCampaignInput"
 
       argument :applied_to_organization, Boolean, required: true
+      argument :bcc_emails, [String], required: false
       argument :code, String, required: true
       argument :days_between_attempts, Integer, required: true
       argument :max_attempts, Integer, required: true

app/graphql/types/dunning_campaigns/object.rb

@@ -8,6 +8,7 @@ class Object < Types::BaseObject
       field :id, ID, null: false
 
       field :applied_to_organization, Boolean, null: false
+      field :bcc_emails, [String], null: true
       field :code, String, null: false
       field :customers_count, Integer, null: false
       field :days_between_attempts, Integer, null: false

app/graphql/types/dunning_campaigns/update_input.rb

@@ -8,6 +8,7 @@ class UpdateInput < Types::BaseInputObject
       argument :id, ID, required: true
 
       argument :applied_to_organization, Boolean, required: false
+      argument :bcc_emails, [String], required: false
       argument :code, String, required: false
       argument :days_between_attempts, Integer, required: false
       argument :description, String, required: false

app/mailers/payment_request_mailer.rb

@@ -15,10 +15,13 @@ def requested
     @invoices = @payment_request.invoices
     @payment_url = ::PaymentRequests::Payments::GeneratePaymentUrlService.call(payable: @payment_request).payment_url
 
+    bcc_emails = @payment_request.dunning_campaign&.bcc_emails
+
     I18n.with_locale(@customer.preferred_document_locale) do
       mail(
         to: @payment_request.email,
         from: email_address_with_name(@organization.from_email_address, @organization.name),
+        bcc: bcc_emails,
         reply_to: email_address_with_name(@organization.email, @organization.name),
         subject: I18n.t(
           "email.payment_request.requested.subject",

app/models/dunning_campaign.rb

@@ -16,6 +16,7 @@ class DunningCampaign < ApplicationRecord
   accepts_nested_attributes_for :thresholds
 
   validates :name, presence: true
+  validates :bcc_emails, email_array: true
   validates :days_between_attempts, numericality: {greater_than: 0}
   validates :max_attempts, numericality: {greater_than: 0}
   validates :code,
@@ -52,6 +53,7 @@ def reset_customers_last_attempt
 #
 #  id                      :uuid             not null, primary key
 #  applied_to_organization :boolean          default(FALSE), not null
+#  bcc_emails              :string           default([]), is an Array
 #  code                    :string           not null
 #  days_between_attempts   :integer          default(1), not null
 #  deleted_at              :datetime

app/services/dunning_campaigns/create_service.rb

@@ -24,6 +24,7 @@ def call
         dunning_campaign = organization.dunning_campaigns.create!(
           applied_to_organization: params[:applied_to_organization],
           code: params[:code],
+          bcc_emails: Array.wrap(params[:bcc_emails]),
           days_between_attempts: params[:days_between_attempts],
           max_attempts: params[:max_attempts],
           name: params[:name],

app/services/dunning_campaigns/update_service.rb

@@ -33,7 +33,7 @@ def call
     attr_reader :dunning_campaign, :organization, :params
 
     def permitted_attributes
-      params.slice(:name, :code, :description, :days_between_attempts, :max_attempts)
+      params.slice(:name, :bcc_emails, :code, :description, :days_between_attempts, :max_attempts)
     end
 
     def handle_thresholds

app/validators/email_array_validator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class EmailArrayValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    unless value.is_a? Array
+      record.errors.add(attribute, "must_be_an_array")
+      return
+    end
+
+    value.each_with_index do |email, index|
+      unless valid? email
+        record.errors.add(attribute, "invalid_email_format[#{index},#{email}]")
+      end
+    end
+  end
+
+  protected
+
+  def valid?(value)
+    value&.match(Regex::EMAIL)
+  end
+end

db/migrate/20250324122757_add_email_bcc_to_dunning_campaign.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddEmailBccToDunningCampaign < ActiveRecord::Migration[7.2]
+  def change
+    add_column :dunning_campaigns, :bcc_emails, :string, array: true, default: []
+  end
+end

db/schema.rb

@@ -11,6 +11,7 @@
       name: "Dunning campaign name",
       code: "dunning-campaign-code",
       description: "Dunning campaign description",
+      bccEmails: ["[email protected]"],
       maxAttempts: 3,
       daysBetweenAttempts: 1,
       appliedToOrganization: false,
@@ -31,6 +32,7 @@
           name
           code
           description
+          bccEmails
           maxAttempts
           daysBetweenAttempts
           appliedToOrganization
@@ -63,6 +65,7 @@
       "name" => "Dunning campaign name",
       "code" => "dunning-campaign-code",
       "description" => "Dunning campaign description",
+      "bccEmails" => ["[email protected]"],
       "maxAttempts" => 3,
       "daysBetweenAttempts" => 1,
       "appliedToOrganization" => false,

schema.graphql

@@ -21,6 +21,7 @@
           id
           customersCount
           appliedToOrganization
+          bccEmails
           code
           daysBetweenAttempts
           description
@@ -37,7 +38,7 @@
 
   let(:membership) { create(:membership) }
   let(:organization) { membership.organization }
-  let(:dunning_campaign) { create(:dunning_campaign, organization:) }
+  let(:dunning_campaign) { create(:dunning_campaign, organization:, bcc_emails: %w[[email protected]]) }
   let(:dunning_campaign_threshold) { create(:dunning_campaign_threshold, dunning_campaign:) }
 
   before do
@@ -57,6 +58,7 @@
         "id" => dunning_campaign.id,
         "customersCount" => 0,
         "appliedToOrganization" => dunning_campaign.applied_to_organization,
+        "bccEmails" => dunning_campaign.bcc_emails,
         "code" => dunning_campaign.code,
         "daysBetweenAttempts" => dunning_campaign.days_between_attempts,
         "description" => dunning_campaign.description,

schema.json

@@ -7,6 +7,7 @@
 
   it do
     expect(subject).to accept_argument(:applied_to_organization).of_type("Boolean!")
+    expect(subject).to accept_argument(:bcc_emails).of_type("[String!]")
     expect(subject).to accept_argument(:code).of_type("String!")
     expect(subject).to accept_argument(:days_between_attempts).of_type("Int!")
     expect(subject).to accept_argument(:max_attempts).of_type("Int!")

spec/graphql/mutations/dunning_campaigns/create_spec.rb

@@ -10,6 +10,7 @@
 
     expect(subject).to have_field(:customers_count).of_type("Int!")
     expect(subject).to have_field(:applied_to_organization).of_type("Boolean!")
+    expect(subject).to have_field(:bcc_emails).of_type("[String!]")
     expect(subject).to have_field(:code).of_type("String!")
     expect(subject).to have_field(:days_between_attempts).of_type("Int!")
     expect(subject).to have_field(:max_attempts).of_type("Int!")

spec/graphql/resolvers/dunning_campaign_resolver_spec.rb

@@ -9,6 +9,7 @@
     expect(subject).to accept_argument(:id).of_type("ID!")
 
     expect(subject).to accept_argument(:applied_to_organization).of_type("Boolean")
+    expect(subject).to accept_argument(:bcc_emails).of_type("[String!]")
     expect(subject).to accept_argument(:code).of_type("String")
     expect(subject).to accept_argument(:days_between_attempts).of_type("Int")
     expect(subject).to accept_argument(:description).of_type("String")

spec/graphql/types/dunning_campaigns/create_input_spec.rb

@@ -3,7 +3,7 @@
 require "rails_helper"
 
 RSpec.describe PaymentRequestMailer, type: :mailer do
-  subject(:payment_request_mailer) { described_class }
+  subject(:mailer) { described_class.with(payment_request:).requested }
 
   let(:organization) { create(:organization, document_number_prefix: "ORG-123B") }
   let(:first_invoice) { create(:invoice, total_amount_cents: 1000, total_paid_amount_cents: 1, organization:) }
@@ -38,18 +38,16 @@
     end
 
     specify do
-      mailer = payment_request_mailer.with(payment_request:).requested
-
       expect(mailer.to).to eq([payment_request.email])
       expect(mailer.reply_to).to eq([payment_request.organization.email])
+      expect(mailer.bcc).to be_nil
       expect(mailer.body.encoded).to include(CGI.escapeHTML(first_invoice.number))
       expect(mailer.body.encoded).to include(CGI.escapeHTML(second_invoice.number))
       expect(mailer.body.encoded).to include(CGI.escapeHTML(MoneyHelper.format(first_invoice.total_due_amount)))
       expect(mailer.body.encoded).to include(CGI.escapeHTML(MoneyHelper.format(second_invoice.total_due_amount)))
     end
 
     it "calls the generate payment url service" do
-      mailer = payment_request_mailer.with(payment_request:).requested
       parsed_body = Nokogiri::HTML(mailer.body.encoded)
 
       expect(parsed_body.at_css("a#payment_link")["href"]).to eq(payment_url)
@@ -59,11 +57,23 @@
         .with(payable: payment_request)
     end
 
+    context "when payment request has dunning campaign attached and there are 2 addresses in bcc_emails" do
+      let(:bcc_emails) { %w[[email protected] [email protected]] }
+      let(:dunning_campaign) { create(:dunning_campaign, organization:, bcc_emails:) }
+
+      before do
+        payment_request.update(dunning_campaign:)
+      end
+
+      it "includes the BCC email addresses in the mailer" do
+        expect(mailer.bcc).to match_array(bcc_emails)
+      end
+    end
+
     context "when payment request email is nil" do
       before { payment_request.update(email: nil) }
 
       it "returns a mailer with nil values" do
-        mailer = payment_request_mailer.with(payment_request:).requested
         expect(mailer.to).to be_nil
       end
     end
@@ -72,7 +82,6 @@
       before { organization.update(email: nil) }
 
       it "returns a mailer with nil values" do
-        mailer = payment_request_mailer.with(payment_request:).requested
         expect(mailer.to).to be_nil
       end
     end
@@ -85,7 +94,6 @@
       end
 
       it "does not include the payment link" do
-        mailer = payment_request_mailer.with(payment_request:).requested
         parsed_body = Nokogiri::HTML(mailer.body.encoded)
 
         expect(parsed_body.css("a#payment_link")).not_to be_present