feat(invitations): add InvitationLogger service

- Service for logging invitation batch operations
- Tracks success/failure/skip counts per batch
- Provides convenience methods for starting/finishing/failing batches

Co-Authored-By: opencode <noreply@opencode.ai>

Author: mroderick

app/services/invitation_logger.rb

@@ -0,0 +1,78 @@
+class InvitationLogger
+  def initialize(loggable, initiator, audience, action)
+    @loggable = loggable
+    @initiator = initiator
+    @audience = audience
+    @action = action
+    @log = nil
+  end
+
+  def start_batch
+    @log = InvitationLog.create!(
+      loggable: @loggable,
+      initiator: @initiator,
+      chapter_id: @loggable.try(:chapter_id),
+      audience: @audience,
+      action: @action,
+      started_at: Time.current,
+      status: :running
+    )
+  end
+
+  def log_success(member, invitation = nil)
+    return unless @log
+
+    @log.entries.create!(
+      member: member,
+      invitation: invitation,
+      status: :success,
+      processed_at: Time.current
+    ).tap { @log.increment!(:success_count) }
+  end
+
+  def log_failure(member, invitation, error)
+    return unless @log
+
+    @log.entries.create!(
+      member: member,
+      invitation: invitation,
+      status: :failed,
+      failure_reason: error.message,
+      processed_at: Time.current
+    ).tap { @log.increment!(:failure_count) }
+  end
+
+  def log_skipped(member, invitation, reason)
+    return unless @log
+
+    @log.entries.create!(
+      member: member,
+      invitation: invitation,
+      status: :skipped,
+      failure_reason: reason,
+      processed_at: Time.current
+    ).tap { @log.increment!(:skipped_count) }
+  end
+
+  def finish_batch(total_invitees)
+    return unless @log
+
+    @log.update!(
+      total_invitees: total_invitees,
+      completed_at: Time.current,
+      status: :completed
+    )
+  end
+
+  def fail_batch(error)
+    return unless @log
+
+    @log.update!(
+      status: :failed,
+      error_message: error.message,
+      completed_at: Time.current
+    )
+  end
+
+  attr_reader :log
+end

spec/services/invitation_logger_spec.rb

@@ -0,0 +1,107 @@
+require 'rails_helper'
+
+RSpec.describe InvitationLogger do
+  let(:workshop) { Fabricate(:workshop) }
+  let(:initiator) { Fabricate(:member) }
+  let(:member) { Fabricate(:member) }
+  let(:invitation) { Fabricate(:workshop_invitation, workshop: workshop, member: member) }
+
+  describe '#start_batch' do
+    it 'creates an InvitationLog record' do
+      logger = described_class.new(workshop, initiator, 'students', :invite)
+      log = logger.start_batch
+
+      expect(log).to be_persisted
+      expect(log.loggable).to eq workshop
+      expect(log.initiator).to eq initiator
+      expect(log.audience).to eq 'students'
+      expect(log.action).to eq 'invite'
+      expect(log.status).to eq 'running'
+    end
+
+    it 'raises error if a running batch already exists' do
+      Fabricate(:invitation_log, loggable: workshop, audience: 'students', action: 'invite', status: :running)
+      logger = described_class.new(workshop, initiator, 'students', :invite)
+
+      expect { logger.start_batch }.to raise_error(ActiveRecord::RecordNotUnique)
+    end
+
+    it 'sets chapter_id from loggable' do
+      logger = described_class.new(workshop, initiator, 'students', :invite)
+      log = logger.start_batch
+
+      expect(log.chapter_id).to eq workshop.chapter_id
+    end
+  end
+
+  describe '#log_success' do
+    let(:logger) { described_class.new(workshop, initiator, 'students', :invite) }
+    let!(:log) { logger.start_batch }
+
+    it 'creates entry with success status and increments count' do
+      entry = logger.log_success(member, invitation)
+
+      expect(entry.status).to eq 'success'
+      expect(entry.member).to eq member
+      expect(entry.invitation).to eq invitation
+      expect(log.reload.success_count).to eq 1
+    end
+  end
+
+  describe '#log_failure' do
+    let(:logger) { described_class.new(workshop, initiator, 'students', :invite) }
+    let!(:log) { logger.start_batch }
+
+    it 'creates entry with failure status and increments count' do
+      error = StandardError.new('SMTP error')
+      entry = logger.log_failure(member, invitation, error)
+
+      expect(entry.status).to eq 'failed'
+      expect(entry.failure_reason).to eq 'SMTP error'
+      expect(log.reload.failure_count).to eq 1
+    end
+  end
+
+  describe '#log_skipped' do
+    let(:logger) { described_class.new(workshop, initiator, 'students', :invite) }
+    let!(:log) { logger.start_batch }
+
+    it 'creates entry with skipped status and increments count' do
+      entry = logger.log_skipped(member, invitation, 'Already invited')
+
+      expect(entry.status).to eq 'skipped'
+      expect(entry.failure_reason).to eq 'Already invited'
+      expect(log.reload.skipped_count).to eq 1
+    end
+  end
+
+  describe '#finish_batch' do
+    let(:logger) { described_class.new(workshop, initiator, 'students', :invite) }
+    let!(:log) { logger.start_batch }
+
+    it 'updates status to completed with counts' do
+      2.times { logger.log_success(Fabricate(:member), Fabricate(:workshop_invitation, workshop: workshop)) }
+      logger.log_failure(Fabricate(:member), Fabricate(:workshop_invitation, workshop: workshop), StandardError.new('err'))
+
+      logger.finish_batch(5)
+
+      expect(log.reload.status).to eq 'completed'
+      expect(log.total_invitees).to eq 5
+      expect(log.completed_at).to be_present
+    end
+  end
+
+  describe '#fail_batch' do
+    let(:logger) { described_class.new(workshop, initiator, 'students', :invite) }
+    let!(:log) { logger.start_batch }
+
+    it 'updates status to failed with error message' do
+      error = StandardError.new('Something went wrong')
+      logger.fail_batch(error)
+
+      expect(log.reload.status).to eq 'failed'
+      expect(log.error_message).to eq 'Something went wrong'
+      expect(log.completed_at).to be_present
+    end
+  end
+end