LG-9564: Notify users when verify by mail codes expire 📣

app/jobs/send_gpo_code_expiration_notices_job.rb

@@ -0,0 +1,77 @@
+class SendGpoCodeExpirationNoticesJob < ApplicationJob
+  queue_as :low
+
+  def initialize(analytics: nil)
+    @analytics = analytics
+  end
+
+  def perform
+    codes_to_send_notifications_for.find_each do |code|
+      user = code.profile.user
+
+      user.send_email_to_all_addresses(:gpo_code_expired, code_sent_at: code.code_sent_at)
+      code.update(expiration_notice_sent_at: Time.zone.now)
+
+      analytics.idv_gpo_expiration_email_sent(user_id: user.uuid)
+    end
+  end
+
+  def codes_to_send_notifications_for
+    # We are looking at a 48 hr window in which all codes will _definitely_ be expired.
+    from, to = calculate_notification_window_bounds
+    expired_codes_needing_notification_sent_between(
+      from: from,
+      to: to,
+    )
+  end
+
+  def calculate_notification_window_bounds(as_of: Time.zone.now)
+    to = as_of.beginning_of_day - IdentityConfig.store.usps_confirmation_max_days.days
+    from = to - 2.days
+    [from, to]
+  end
+
+  private
+
+  def analytics
+    @analytics ||= Analytics.new(user: AnonymousUser.new, request: nil, session: {}, sp: nil)
+  end
+
+  def expired_codes_needing_notification_sent_between(
+    from:,
+    to:
+  )
+    GpoConfirmationCode.joins(:profile).
+      # 1. Exclude codes that we've already sent an expiration notice for
+      where(expiration_notice_sent_at: nil).
+
+      # 2. Exclude codes not sent in the window we're looking at
+      where(code_sent_at: from...to).
+
+      # 3. Exclude codes where the associated profile does not have the GPO pending timestamp set
+      #    (meaning they either completed GPO or reset their password).
+      where.not(profile: { gpo_verification_pending_at: nil }).
+
+      # 4. Exclude codes where the associated profile has been deactivated for some reason
+      where(profile: { deactivation_reason: nil }).
+
+      # 5. Exclude codes where the user has since gotten an active profile (no point in notifying)
+      where.not(
+        profile: {
+          user_id: User.joins(:profiles).where(
+            profiles: {
+              active: true,
+            },
+          ),
+        },
+      ).
+
+      # 6. Only include codes that are the most recent code sent for the profile
+      where(
+        code_sent_at: GpoConfirmationCode.
+          select('max(code_sent_at)').
+          from('usps_confirmation_codes child').
+          where('child.profile_id = usps_confirmation_codes.profile_id'),
+      )
+  end
+end

app/mailers/user_mailer.rb

@@ -401,6 +401,16 @@ def gpo_reminder
     end
   end
 
+  def gpo_code_expired(code_sent_at:)
+    with_user_locale(user) do
+      @code_sent_at = I18n.l(
+        code_sent_at,
+        format: :event_date,
+      )
+      mail(to: email_address.email, subject: t('user_mailer.gpo_code_expired.subject'))
+    end
+  end
+
   private
 
   def email_should_receive_nonessential_notifications?(email)

app/models/user.rb

@@ -460,12 +460,12 @@ def analytics
     @analytics ||= Analytics.new(user: self, request: nil, session: {}, sp: nil)
   end
 
-  def send_email_to_all_addresses(user_mailer_template)
+  def send_email_to_all_addresses(user_mailer_template, **args)
     confirmed_email_addresses.each do |email_address|
       UserMailer.with(
         user: self,
         email_address: email_address,
-      ).send(user_mailer_template).
+      ).send(user_mailer_template, **args).
         deliver_now_or_later
     end
   end

app/services/analytics_events.rb

@@ -1118,6 +1118,12 @@ def idv_gpo_confirm_start_over_visited(**extra)
     track_event('IdV: gpo confirm start over visited', **extra) # rubocop:disable IdentityIdp/AnalyticsEventNameLinter
   end
 
+  # A GPO expiration email was sent to the user
+  # @param [String] user_id UUID of user we sent an email to
+  def idv_gpo_expiration_email_sent(user_id:, **extra)
+    track_event(:idv_gpo_expiration_email_sent, user_id: user_id, **extra)
+  end
+
   # A GPO reminder email was sent to the user
   # @param [String] user_id UUID of user who we sent a reminder to
   def idv_gpo_reminder_email_sent(user_id:, **extra)

app/views/user_mailer/gpo_code_expired.erb

@@ -0,0 +1,41 @@
+
+<%= t(
+      'user_mailer.gpo_code_expired.body.intro',
+      code_sent_at: @code_sent_at,
+      app_name: APP_NAME,
+    ) %>
+
+<%= link_to(
+      t('user_mailer.gpo_code_expired.body.learn_more_link'),
+      help_center_redirect_url(
+        category: 'verify-your-identity',
+        article: 'verify-your-address-by-mail',
+        flow: :idv,
+        step: :gpo_send_letter,
+      ),
+      { style: "text-decoration: 'underline'" },
+    ) %>
+
+<table class="button expanded large radius">
+  <tbody>
+    <tr>
+      <td>
+        <table style="margin-bottom: 1em; margin-top: 1em">
+          <tbody>
+            <tr>
+              <td style="text-align: center">
+                <%= link_to t('user_mailer.gpo_code_expired.body.cta'),
+                            idv_url,
+                            target: '_blank',
+                            class: 'float-center',
+                            align: 'center',
+                            rel: 'noopener' %>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </td>
+      <td class="expander"></td>
+    </tr>
+  </tbody>
+</table>

config/initializers/job_configurations.rb

@@ -188,6 +188,12 @@
         cron: cron_24h,
         args: -> { [14.days.ago] },
       },
+      # Send emails when unused GPO verification codes have expired
+      send_gpo_code_expiration_notices: {
+        class: 'SendGpoCodeExpirationNoticesJob',
+        cron: cron_24h,
+        args: -> { [] },
+      },
       # Monthly report checking in on key metrics
       monthly_key_metrics_report: {
         class: 'Reports::MonthlyKeyMetricsReport',

config/locales/user_mailer/en.yml

@@ -87,6 +87,14 @@ en:
       help_html: If you did not want to delete this email address, please visit the
         %{app_name_html} %{help_link_html} or %{contact_link_html}.
       subject: Email address deleted
+    gpo_code_expired:
+      body:
+        cta: Start verifying your identity
+        intro: You requested a letter with a verification code on %{code_sent_at}. This
+          verification code has now expired. Sign back into %{app_name} to start
+          verifying your identity again.
+        learn_more_link: Learn more about verifying your address by mail.
+      subject: Your verification code has expired
     help_link_text: Help Center
     in_person_completion_survey:
       body:

config/locales/user_mailer/es.yml

@@ -94,6 +94,15 @@ es:
       help_html: Si no desea eliminar esta dirección de correo electrónico, visite el
         %{app_name_html} %{help_link_html} o el %{contact_link_html}.
       subject: Dirección de correo electrónico eliminada
+    gpo_code_expired:
+      body:
+        cta: Comenzar a verificar su identidad
+        intro: Solicitó una carta con un código de verificación el %{code_sent_at}. Este
+          código de verificación ya expiró. Vuelva a iniciar sesión en
+          %{app_name} para comenzar a verificar su identidad nuevamente.
+        learn_more_link: Obtenga más información sobre la verificación de su dirección
+          por correo.
+      subject: Su código de verificación ha caducado
     help_link_text: Centro de Ayuda
     in_person_completion_survey:
       body:

config/locales/user_mailer/fr.yml

@@ -98,6 +98,14 @@ fr:
         veuillez visiter le %{help_link_html} de %{app_name_html} ou
         %{contact_link_html}.
       subject: Adresse email supprimée
+    gpo_code_expired:
+      body:
+        cta: Commencez à vérifier votre identité
+        intro: Vous avez demandé une lettre avec un code de vérification le
+          %{code_sent_at}. Ce code de vérification a expiré. Reconnectez-vous à
+          %{app_name} pour reprendre la vérification de votre identité.
+        learn_more_link: En savoir plus sur la vérification de votre adresse par courrier.
+      subject: Votre code de vérification a expiré
     help_link_text: Centre d’aide
     in_person_completion_survey:
       body:

db/primary_migrate/20231018230656_add_expiration_notice_sent_at_to_usps_confirmation_codes.rb

@@ -0,0 +1,8 @@
+class AddExpirationNoticeSentAtToUspsConfirmationCodes < ActiveRecord::Migration[7.0]
+  disable_ddl_transaction!
+
+  def change
+    add_column :usps_confirmation_codes, :expiration_notice_sent_at, :datetime, precision: nil
+    add_index :usps_confirmation_codes, :expiration_notice_sent_at, algorithm: :concurrently
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.0].define(version: 2023_08_31_124437) do
+ActiveRecord::Schema[7.0].define(version: 2023_10_18_230656) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pgcrypto"
@@ -621,6 +621,9 @@
     t.datetime "updated_at", precision: nil, null: false
     t.datetime "bounced_at", precision: nil
     t.datetime "reminder_sent_at", precision: nil
+    t.datetime "expiration_notice_sent_at", precision: nil
+    t.index ["code_sent_at"], name: "ix_code_sent_at"
+    t.index ["expiration_notice_sent_at"], name: "index_usps_confirmation_codes_on_expiration_notice_sent_at"
     t.index ["otp_fingerprint"], name: "index_usps_confirmation_codes_on_otp_fingerprint"
     t.index ["profile_id"], name: "index_usps_confirmation_codes_on_profile_id"
     t.index ["reminder_sent_at"], name: "index_usps_confirmation_codes_on_reminder_sent_at"

spec/factories/gpo_confirmation_codes.rb

@@ -4,5 +4,6 @@
   factory :gpo_confirmation_code do
     profile
     otp_fingerprint { Pii::Fingerprinter.fingerprint('ABCDE12345') }
+    code_sent_at { 1.day.ago }
   end
 end

spec/factories/users.rb

@@ -205,12 +205,28 @@
     end
 
     trait :with_pending_gpo_profile do
-      after :build do |user|
-        profile = create(:profile, :with_pii, gpo_verification_pending_at: 1.day.ago, user: user)
-        gpo_code = create(:gpo_confirmation_code)
-        profile.gpo_confirmation_codes << gpo_code
-        device = create(:device, user: user)
-        create(:event, user: user, device: device, event_type: :gpo_mail_sent)
+      transient do
+        code_sent_at { 1.day.ago }
+      end
+
+      after :create do |user, context|
+        profile = create(
+          :profile,
+          :with_pii,
+          gpo_verification_pending_at: context.code_sent_at,
+          user: user,
+        )
+        create(
+          :gpo_confirmation_code,
+          profile: profile,
+          code_sent_at: context.code_sent_at,
+        )
+        create(
+          :event,
+          user: user,
+          device: create(:device, user: user),
+          event_type: :gpo_mail_sent,
+        )
       end
     end