Relay transactional email through Salesforce instead of SMTP (#9)

Reviewed-on: #9
Co-authored-by: Patrick Müller <patrick@mueller-patrick.tech>
Co-committed-by: Patrick Müller <patrick@mueller-patrick.tech>

test/common/common.mail.test.ts

@@ -0,0 +1,115 @@
+// common.mail relays one email through the Salesforce org (see
+// src/common/common.mail.ts). These tests mock the shared Salesforce client so
+// no network is touched, and check: the payload shape, base64 attachment
+// encoding, the attachment size cap, the retry-once-on-transient-failure
+// behaviour, and that a delivery failure is swallowed (returns false, never
+// throws).
+
+jest.mock('../../src/common/salesforce.client');
+jest.mock('../../src/middleware/logger', () => ({
+	__esModule: true,
+	default: {info: jest.fn(), warn: jest.fn(), error: jest.fn()}
+}));
+
+import {MailService} from '../../src/common/common.mail';
+import {salesforceApexRestPost, salesforceEnabled} from '../../src/common/salesforce.client';
+
+const mockPost = salesforceApexRestPost as jest.Mock;
+const mockEnabled = salesforceEnabled as jest.Mock;
+
+const httpError = (status: number, body?: any): any => {
+	const err: any = new Error('request failed with ' + status);
+	err.response = {status, data: body};
+	return err;
+};
+
+beforeEach(() => {
+	jest.clearAllMocks();
+	mockEnabled.mockReturnValue(true);
+	mockPost.mockResolvedValue({status: 'SENT'});
+});
+
+describe('MailService.sendMail', () => {
+	it('returns false without a callout when Salesforce is disabled', async () => {
+		mockEnabled.mockReturnValue(false);
+
+		const result = await MailService.sendMail('guest@example.com', 'Hi', 'Hallo');
+
+		expect(result).toBe(false);
+		expect(mockPost).not.toHaveBeenCalled();
+	});
+
+	it('posts the email to the Apex REST endpoint and returns true on success', async () => {
+		const result = await MailService.sendMail('guest@example.com', 'Bestätigung', 'Hallo', {html: '<p>Hallo</p>'});
+
+		expect(result).toBe(true);
+		expect(mockPost).toHaveBeenCalledWith('/services/apexrest/email/send', {
+			to: 'guest@example.com',
+			subject: 'Bestätigung',
+			textBody: 'Hallo',
+			htmlBody: '<p>Hallo</p>',
+			attachments: []
+		});
+	});
+
+	it('sends htmlBody as null when no HTML is given', async () => {
+		await MailService.sendMail('guest@example.com', 'Hi', 'Hallo');
+
+		expect(mockPost).toHaveBeenCalledWith('/services/apexrest/email/send', expect.objectContaining({htmlBody: null}));
+	});
+
+	it('base64-encodes attachments', async () => {
+		await MailService.sendMail('guest@example.com', 'Hi', 'Hallo', {
+			attachments: [{filename: 'konzert.ics', content: 'BEGIN:VCALENDAR', contentType: 'text/calendar'}]
+		});
+
+		expect(mockPost).toHaveBeenCalledWith(
+			'/services/apexrest/email/send',
+			expect.objectContaining({
+				attachments: [{
+					filename: 'konzert.ics',
+					contentType: 'text/calendar',
+					contentBase64: Buffer.from('BEGIN:VCALENDAR', 'utf-8').toString('base64')
+				}]
+			})
+		);
+	});
+
+	it('rejects an attachment over the size cap without sending', async () => {
+		const huge = Buffer.alloc(3 * 1024 * 1024 + 1);
+
+		const result = await MailService.sendMail('guest@example.com', 'Hi', 'Hallo', {
+			attachments: [{filename: 'big.pdf', content: huge}]
+		});
+
+		expect(result).toBe(false);
+		expect(mockPost).not.toHaveBeenCalled();
+	});
+
+	it('retries once on a 5xx and returns false when the retry also fails', async () => {
+		mockPost.mockRejectedValue(httpError(503));
+
+		const result = await MailService.sendMail('guest@example.com', 'Hi', 'Hallo');
+
+		expect(result).toBe(false);
+		expect(mockPost).toHaveBeenCalledTimes(2);
+	});
+
+	it('retries once on a network error (no response) then succeeds', async () => {
+		mockPost.mockRejectedValueOnce(new Error('socket hang up')).mockResolvedValueOnce({status: 'SENT'});
+
+		const result = await MailService.sendMail('guest@example.com', 'Hi', 'Hallo');
+
+		expect(result).toBe(true);
+		expect(mockPost).toHaveBeenCalledTimes(2);
+	});
+
+	it('does not retry on a 4xx (e.g. the 429 limit response) and returns false', async () => {
+		mockPost.mockRejectedValue(httpError(429, {errorCode: 'LIMIT_REACHED'}));
+
+		const result = await MailService.sendMail('guest@example.com', 'Hi', 'Hallo');
+
+		expect(result).toBe(false);
+		expect(mockPost).toHaveBeenCalledTimes(1);
+	});
+});

test/common/salesforce.client.test.ts

@@ -0,0 +1,124 @@
+// salesforce.client caches the OAuth token at module scope, so every test
+// resets the module registry for a clean cache and re-requires axios + the
+// module under test after the reset (same approach as
+// test/feedback/salesforce.service.test.ts).
+
+export {}; // isolate module scope from other script-style test files
+
+jest.mock('axios');
+
+const freshImports = () => {
+	const axios = require('axios');
+	const {salesforceApexRestPost, salesforceEnabled} = require('../../src/common/salesforce.client');
+	return {axios, salesforceApexRestPost, salesforceEnabled};
+};
+
+const ORIGINAL_ENV = {...process.env};
+const ENABLED_ENV = {
+	...ORIGINAL_ENV,
+	SALESFORCE_ENABLED: 'true',
+	SALESFORCE_API_URL: 'https://example.my.salesforce.com',
+	SALESFORCE_CLIENT_ID: 'client-id',
+	SALESFORCE_CLIENT_SECRET: 'client-secret'
+};
+
+beforeEach(() => {
+	jest.resetModules();
+	process.env = {...ENABLED_ENV};
+});
+
+afterAll(() => {
+	process.env = {...ORIGINAL_ENV};
+});
+
+describe('salesforceEnabled', () => {
+	it('is true only when SALESFORCE_ENABLED === "true"', () => {
+		process.env.SALESFORCE_ENABLED = 'true';
+		expect(freshImports().salesforceEnabled()).toBe(true);
+
+		jest.resetModules();
+		process.env.SALESFORCE_ENABLED = 'false';
+		expect(freshImports().salesforceEnabled()).toBe(false);
+	});
+});
+
+describe('salesforceApexRestPost', () => {
+	it('fetches a token, posts to the given Apex REST path, and returns the response body', async () => {
+		const {axios, salesforceApexRestPost} = freshImports();
+		axios.post.mockImplementation((url: string) => {
+			if (url.endsWith('/services/oauth2/token')) return Promise.resolve({data: {access_token: 'tok-1'}});
+			return Promise.resolve({data: {ok: true}});
+		});
+
+		const result = await salesforceApexRestPost('/services/apexrest/email/send', {to: 'x@example.com'});
+
+		expect(result).toEqual({ok: true});
+		expect(axios.post).toHaveBeenCalledWith(
+			'https://example.my.salesforce.com/services/oauth2/token',
+			expect.any(String),
+			expect.objectContaining({headers: {'Content-Type': 'application/x-www-form-urlencoded'}})
+		);
+		expect(axios.post).toHaveBeenCalledWith(
+			'https://example.my.salesforce.com/services/apexrest/email/send',
+			{to: 'x@example.com'},
+			expect.objectContaining({headers: {Authorization: 'Bearer tok-1'}})
+		);
+	});
+
+	it('reuses the cached token across calls instead of fetching twice', async () => {
+		const {axios, salesforceApexRestPost} = freshImports();
+		axios.post.mockImplementation((url: string) => {
+			if (url.endsWith('/services/oauth2/token')) return Promise.resolve({data: {access_token: 'tok-1'}});
+			return Promise.resolve({data: {}});
+		});
+
+		await salesforceApexRestPost('/services/apexrest/email/send', {});
+		await salesforceApexRestPost('/services/apexrest/email/send', {});
+
+		const tokenCalls = axios.post.mock.calls.filter(([url]: [string]) => url.endsWith('/services/oauth2/token'));
+		expect(tokenCalls).toHaveLength(1);
+	});
+
+	it('retries once with a fresh token on a 401, then succeeds', async () => {
+		const {axios, salesforceApexRestPost} = freshImports();
+		let tokenFetches = 0;
+		axios.post.mockImplementation((url: string) => {
+			if (url.endsWith('/services/oauth2/token')) {
+				tokenFetches += 1;
+				return Promise.resolve({data: {access_token: `tok-${tokenFetches}`}});
+			}
+			if (tokenFetches === 1) {
+				const err: any = new Error('Unauthorized');
+				err.response = {status: 401};
+				return Promise.reject(err);
+			}
+			return Promise.resolve({data: {ok: true}});
+		});
+
+		const result = await salesforceApexRestPost('/services/apexrest/email/send', {});
+
+		expect(result).toEqual({ok: true});
+		expect(tokenFetches).toBe(2);
+	});
+
+	it('does not retry on a non-401 error and rethrows it', async () => {
+		const {axios, salesforceApexRestPost} = freshImports();
+		axios.post.mockImplementation((url: string) => {
+			if (url.endsWith('/services/oauth2/token')) return Promise.resolve({data: {access_token: 'tok-1'}});
+			const err: any = new Error('Server error');
+			err.response = {status: 500};
+			return Promise.reject(err);
+		});
+
+		await expect(salesforceApexRestPost('/services/apexrest/email/send', {})).rejects.toThrow('Server error');
+		const endpointCalls = axios.post.mock.calls.filter(([url]: [string]) => url.endsWith('/email/send'));
+		expect(endpointCalls).toHaveLength(1);
+	});
+
+	it('throws a clear error when client credentials are not configured', async () => {
+		process.env.SALESFORCE_CLIENT_ID = '';
+		const {salesforceApexRestPost} = freshImports();
+
+		await expect(salesforceApexRestPost('/services/apexrest/email/send', {})).rejects.toThrow('SALESFORCE_CLIENT_ID');
+	});
+});

test/tickets/confirmation-email.test.ts

@@ -0,0 +1,131 @@
+// tickets.confirmation-email builds and sends the redemption confirmation
+// email, shared by the public redeem path and the admin resend action.
+
+jest.mock('../../src/models/calendar/events/events.service', () => ({
+	getEventById: jest.fn()
+}));
+jest.mock('../../src/models/calendar/events/icalgenerator.service', () => ({
+	convertToIcal: jest.fn()
+}));
+jest.mock('../../src/common/common.mail', () => ({
+	MailService: {sendMail: jest.fn()}
+}));
+jest.mock('../../src/models/tickets/Tickets.db', () => ({
+	NachklangTicketsDB: {getConnection: jest.fn()}
+}));
+jest.mock('../../src/middleware/logger', () => ({
+	__esModule: true,
+	default: {info: jest.fn(), warn: jest.fn(), error: jest.fn()}
+}));
+
+import * as EventsService from '../../src/models/calendar/events/events.service';
+import * as IcalService from '../../src/models/calendar/events/icalgenerator.service';
+import {MailService} from '../../src/common/common.mail';
+import logger from '../../src/middleware/logger';
+import {NachklangTicketsDB} from '../../src/models/tickets/Tickets.db';
+import {recordConfirmationEmailResult, sendRedemptionConfirmation} from '../../src/models/tickets/tickets.confirmation-email';
+
+const mockGetEvent = EventsService.getEventById as jest.Mock;
+const mockToIcal = IcalService.convertToIcal as jest.Mock;
+const mockSendMail = MailService.sendMail as jest.Mock;
+const mockLogger = logger as unknown as {info: jest.Mock; warn: jest.Mock; error: jest.Mock};
+const mockGetConnection = NachklangTicketsDB.getConnection as jest.Mock;
+
+const EVENT = {
+	eventId: 42,
+	name: 'Sommerkonzert 2026',
+	startDateTime: new Date('2026-07-01T19:00:00Z'),
+	location: 'Christuskirche',
+	status: 'PUBLISHED'
+};
+
+const RECIPIENT = {
+	eventId: 42,
+	contactName: 'Erika Mustermann',
+	contactEmail: 'erika@example.com',
+	guestNames: ['Erika Mustermann', 'Hans Mustermann']
+};
+
+beforeEach(() => {
+	jest.clearAllMocks();
+	mockGetEvent.mockResolvedValue(EVENT);
+	mockToIcal.mockResolvedValue('BEGIN:VCALENDAR\nEND:VCALENDAR');
+	mockSendMail.mockResolvedValue(true);
+});
+
+describe('sendRedemptionConfirmation', () => {
+	it('sends the German confirmation with the event details, guest list and .ics attachment', async () => {
+		const result = await sendRedemptionConfirmation(RECIPIENT);
+
+		expect(result).toBe(true);
+		expect(mockSendMail).toHaveBeenCalledTimes(1);
+		const [to, subject, body, options] = mockSendMail.mock.calls[0];
+		expect(to).toBe('erika@example.com');
+		expect(subject).toBe('Bestätigung: Sommerkonzert 2026');
+		expect(body).toContain('Hallo Erika Mustermann,');
+		expect(body).toContain('"Sommerkonzert 2026"');
+		expect(body).toContain('- Hans Mustermann');
+		expect(options.attachments).toEqual([
+			{filename: 'konzert.ics', content: 'BEGIN:VCALENDAR\nEND:VCALENDAR', contentType: 'text/calendar'}
+		]);
+	});
+
+	it('still sends (without an attachment) and warns when the .ics build fails', async () => {
+		mockToIcal.mockRejectedValue(new Error('ical boom'));
+
+		await sendRedemptionConfirmation(RECIPIENT);
+
+		const options = mockSendMail.mock.calls[0][3];
+		expect(options.attachments).toBeUndefined();
+		expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('without .ics attachment'));
+	});
+
+	it('returns false and does not send when the event no longer exists', async () => {
+		mockGetEvent.mockResolvedValue(null);
+
+		const result = await sendRedemptionConfirmation(RECIPIENT);
+
+		expect(result).toBe(false);
+		expect(mockSendMail).not.toHaveBeenCalled();
+	});
+
+	it('propagates the relay result', async () => {
+		mockSendMail.mockResolvedValue(false);
+
+		expect(await sendRedemptionConfirmation(RECIPIENT)).toBe(false);
+	});
+});
+
+describe('recordConfirmationEmailResult', () => {
+	const makeConn = () => ({query: jest.fn().mockResolvedValue(undefined), end: jest.fn().mockResolvedValue(undefined)});
+
+	it('writes SENT when the mail was accepted', async () => {
+		const conn = makeConn();
+		mockGetConnection.mockResolvedValue(conn);
+
+		await recordConfirmationEmailResult(7, true);
+
+		expect(conn.query).toHaveBeenCalledWith(
+			'UPDATE redemptions SET confirmation_email_status = ? WHERE redemption_id = ?',
+			['SENT', 7]
+		);
+		expect(conn.end).toHaveBeenCalled();
+	});
+
+	it('writes FAILED when the mail was not accepted', async () => {
+		const conn = makeConn();
+		mockGetConnection.mockResolvedValue(conn);
+
+		await recordConfirmationEmailResult(7, false);
+
+		expect(conn.query).toHaveBeenCalledWith(expect.any(String), ['FAILED', 7]);
+	});
+
+	it('swallows a DB error rather than throwing', async () => {
+		const conn = {query: jest.fn().mockRejectedValue(new Error('db down')), end: jest.fn().mockResolvedValue(undefined)};
+		mockGetConnection.mockResolvedValue(conn);
+
+		await expect(recordConfirmationEmailResult(7, true)).resolves.toBeUndefined();
+		expect(conn.end).toHaveBeenCalled();
+	});
+});

test/tickets/redemptions.admin.resend.test.ts

@@ -0,0 +1,88 @@
+// resendRedemptionConfirmation rebuilds the confirmation email from stored
+// redemption data and records the new outcome. Only the resend path is
+// exercised here; the shared send/record logic is covered by
+// confirmation-email.test.ts.
+
+jest.mock('../../src/models/tickets/Tickets.db', () => ({
+	NachklangTicketsDB: {getConnection: jest.fn()}
+}));
+jest.mock('../../src/models/tickets/tickets.confirmation-email', () => ({
+	sendRedemptionConfirmation: jest.fn(),
+	recordConfirmationEmailResult: jest.fn()
+}));
+
+import {NachklangTicketsDB} from '../../src/models/tickets/Tickets.db';
+import {recordConfirmationEmailResult, sendRedemptionConfirmation} from '../../src/models/tickets/tickets.confirmation-email';
+import {resendRedemptionConfirmation} from '../../src/models/tickets/admin/redemptions.admin.service';
+
+const mockGetConnection = NachklangTicketsDB.getConnection as jest.Mock;
+const mockSend = sendRedemptionConfirmation as jest.Mock;
+const mockRecord = recordConfirmationEmailResult as jest.Mock;
+
+const ACTIVE_ROW = {
+	redemption_id: 5,
+	code: 'ABC123',
+	event_id: 42,
+	status: 'ACTIVE',
+	contact_name: 'Erika Mustermann',
+	contact_email: 'erika@example.com',
+	contact_address: null,
+	guest_count: 2,
+	redeemed_at: new Date('2026-06-01T10:00:00Z'),
+	confirmation_email_status: 'FAILED'
+};
+
+// getRedemption issues: 1) SELECT redemptions, 2) SELECT redemption_guests
+const connFor = (redemptionRows: any[], guestRows: any[] = []) => ({
+	query: jest
+		.fn()
+		.mockResolvedValueOnce(redemptionRows)
+		.mockResolvedValueOnce(guestRows),
+	end: jest.fn().mockResolvedValue(undefined)
+});
+
+beforeEach(() => {
+	jest.clearAllMocks();
+	mockSend.mockResolvedValue(true);
+});
+
+describe('resendRedemptionConfirmation', () => {
+	it('returns NOT_FOUND when the redemption does not exist', async () => {
+		mockGetConnection.mockResolvedValue(connFor([]));
+
+		expect(await resendRedemptionConfirmation(5)).toBe('NOT_FOUND');
+		expect(mockSend).not.toHaveBeenCalled();
+	});
+
+	it('returns NOT_ACTIVE for an undone redemption', async () => {
+		mockGetConnection.mockResolvedValue(connFor([{...ACTIVE_ROW, status: 'UNDONE'}]));
+
+		expect(await resendRedemptionConfirmation(5)).toBe('NOT_ACTIVE');
+		expect(mockSend).not.toHaveBeenCalled();
+	});
+
+	it('resends from the stored data and records SENT on success', async () => {
+		mockGetConnection.mockResolvedValue(connFor([ACTIVE_ROW], [{name: 'Erika Mustermann'}, {name: 'Hans Mustermann'}]));
+
+		const result = await resendRedemptionConfirmation(5);
+
+		expect(result).toBe('SENT');
+		expect(mockSend).toHaveBeenCalledWith({
+			eventId: 42,
+			contactName: 'Erika Mustermann',
+			contactEmail: 'erika@example.com',
+			guestNames: ['Erika Mustermann', 'Hans Mustermann']
+		});
+		expect(mockRecord).toHaveBeenCalledWith(5, true);
+	});
+
+	it('records FAILED and returns FAILED when the relay rejects the send', async () => {
+		mockGetConnection.mockResolvedValue(connFor([ACTIVE_ROW], [{name: 'Erika Mustermann'}]));
+		mockSend.mockResolvedValue(false);
+
+		const result = await resendRedemptionConfirmation(5);
+
+		expect(result).toBe('FAILED');
+		expect(mockRecord).toHaveBeenCalledWith(5, false);
+	});
+});