feat(admin): make the token lifetimes, cart hold and greeting configurable (#136)

Giving the customer emails a tab of their own (#135) made a family of related holes visible: an admin could edit the wording of every customer email, but not the facts that wording asserted, and two templates could not address the customer at all.

Both token lifetimes were hardcoded twice. VERIFY_TOKEN_TTL_MS sat in routes/customers.ts while the verification body separately said "This link expires in 24 hours", and RESET_TOKEN_TTL_MS sat beside a body separately saying "one hour". The prose was not derived from the constant, it was a second hand-written copy of the same fact — so making the constants configurable without addressing that would have made things worse, not better: the setting moves to two hours and the email keeps confidently promising one. Both are now settings, and both templates state their lifetime through an {{expiresIn}} placeholder rendered from the setting.

The cart reminder gains {{holdDuration}} for the same reason. Per-item deadlines were already inside {{itemList}}, but there was no way to write a sentence about the hold itself without hardcoding a number the cart expiry setting could change underneath the author.

All three durations render through one formatDuration(), so the reset email and the cart reminder say "one hour" the same way rather than in two authors' phrasing. A fractional hour drops to minutes, because "0.5 hours" reads badly and "1.5 hours" reads worse in a sentence a customer is meant to act on.

Every template now offers greeting, firstName and lastName. favoriteSold and favoriteWithdrawn previously offered only itemName and siteUrl and could not address anyone — the query behind them never selected a name, so it does now.

The greeting itself is two settings, a format and a fallback, rather than the wording baked into greeting(). The fallback is separate rather than the format with the name edited out: that editing is guesswork that has to be right every time, and getting it wrong ships "Hi ," to everyone who registered while first names were still optional (#106). Those customers exist, which is why greeting() guarded the case in the first place.

The admin preview renders the durations and the greeting from the live settings rather than from a static sample. The preview exists so an admin sees the email that will be sent, and a sample reading "one hour" while the setting says two is the precise failure these placeholders were added to remove.

Settings are read through a new adminSettings accessor. cart_expiry_hours was previously read by an inline query in two places, each with its own `|| '24'`; with five settings and read sites across three routes and the cron job, a default written twice is a default that will eventually disagree with itself. Values are stored as text, so each definition declares how to read it back — numbers were the only kind until the greeting format arrived.

The new placeholders are available but never required, so every template an admin has already saved keeps rendering and keeps sending.

Also fixes updateAdminSettings announcing success for a save the server refused: it returned the 400 body as though it were the saved settings, so the form reported "Settings saved" either way.

Closes #136

backend/tests/integration/adminSettings.integration.test.ts

@@ -0,0 +1,103 @@
+import request from 'supertest';
+import app from '../../src/app';
+import { pool } from '../../src/db';
+import { resetDb, closeDb } from './setup/testDb';
+import { getSettings } from '../../src/adminSettings';
+
+// resetDb only clears the stored email templates out of admin_settings — it
+// matches `email\_%`. The settings themselves survive it, so without this a
+// value written by one test is the baseline the next one reads. Cleared after
+// the file too, so nothing leaks into the suites that run behind it.
+beforeEach(async () => {
+  await resetDb();
+  await pool.query(`DELETE FROM admin_settings`);
+});
+
+afterAll(async () => {
+  await pool.query(`DELETE FROM admin_settings`);
+  await pool.end();
+  await closeDb();
+});
+
+describe('GET /api/admin/settings', () => {
+  it('answers with every setting, falling back for the ones never written', async () => {
+    const res = await request(app).get('/api/admin/settings');
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      cartExpiryHours: 24,
+      verifyTokenHours: 24,
+      passwordResetHours: 1,
+      greetingFormat: 'Hi {{firstName}},',
+      greetingFallback: 'Hi,'
+    });
+  });
+});
+
+describe('PUT /api/admin/settings', () => {
+  it('stores the lifetimes and reads them back', async () => {
+    const res = await request(app)
+      .put('/api/admin/settings')
+      .send({ verifyTokenHours: 2, passwordResetHours: 0.5 });
+
+    expect(res.status).toBe(200);
+    expect(res.body.verifyTokenHours).toBe(2);
+    expect(res.body.passwordResetHours).toBe(0.5);
+    // Read back through the accessor the senders use, not just the response.
+    expect((await getSettings()).verifyTokenHours).toBe(2);
+  });
+
+  // Partial rather than whole-object: a caller updating one field should not
+  // have to echo the others back to avoid clobbering them.
+  it('leaves settings it was not sent alone', async () => {
+    await request(app).put('/api/admin/settings').send({ cartExpiryHours: 6 });
+    await request(app).put('/api/admin/settings').send({ verifyTokenHours: 3 });
+
+    const { cartExpiryHours, verifyTokenHours } = await getSettings();
+    expect(cartExpiryHours).toBe(6);
+    expect(verifyTokenHours).toBe(3);
+  });
+
+  it('stores the greeting format and its fallback', async () => {
+    const res = await request(app)
+      .put('/api/admin/settings')
+      .send({ greetingFormat: 'Dear {{firstName}} {{lastName}}:', greetingFallback: 'Hello there,' });
+
+    expect(res.status).toBe(200);
+    expect(res.body.greetingFormat).toBe('Dear {{firstName}} {{lastName}}:');
+    expect(res.body.greetingFallback).toBe('Hello there,');
+  });
+
+  it.each([
+    ['cartExpiryHours', 0],
+    ['verifyTokenHours', -1],
+    ['passwordResetHours', 'soon']
+  ])('refuses %s of %p, naming the field', async (name, value) => {
+    const res = await request(app).put('/api/admin/settings').send({ [name]: value });
+
+    expect(res.status).toBe(400);
+    expect(res.body.error).toContain(name);
+  });
+
+  // An empty format would render every greeting as nothing at all, which reads
+  // as a broken email rather than a setting someone cleared.
+  it.each(['greetingFormat', 'greetingFallback'])('refuses an empty %s', async (name) => {
+    const res = await request(app).put('/api/admin/settings').send({ [name]: '   ' });
+
+    expect(res.status).toBe(400);
+    expect(res.body.error).toContain(name);
+  });
+
+  // Every field is validated before any is written, so a request that is part
+  // nonsense does not half-apply.
+  it('does not write anything when one field in the request is invalid', async () => {
+    await request(app).put('/api/admin/settings').send({ cartExpiryHours: 6 });
+
+    const res = await request(app)
+      .put('/api/admin/settings')
+      .send({ cartExpiryHours: 8, verifyTokenHours: -3 });
+
+    expect(res.status).toBe(400);
+    expect((await getSettings()).cartExpiryHours).toBe(6);
+  });
+});

backend/tests/unit/emailTemplates.test.ts

@@ -3,6 +3,8 @@ import {
   TemplateKey,
   missingPlaceholders,
   renderTemplate,
+  formatDuration,
+  greeting,
   SAMPLE_VALUES
 } from '../../src/emailTemplates';
 
@@ -142,7 +144,12 @@ describe('renderTemplate', () => {
     const { html, subject } = renderTemplate(
       'cartReminder',
       {},
-      { greeting: 'Hi Thom,', itemList: '- One thing', cartUrl: 'https://shop.test/cart' }
+      {
+        greeting: 'Hi Thom,',
+        itemList: '- One thing',
+        cartUrl: 'https://shop.test/cart',
+        holdDuration: '24 hours'
+      }
     );
     expect(html).not.toMatch(/\{\{\s*\w+\s*\}\}/);
     expect(subject).not.toMatch(/\{\{\s*\w+\s*\}\}/);
@@ -164,3 +171,106 @@ describe('SAMPLE_VALUES, which the admin preview renders with', () => {
     expect(subject).not.toMatch(/\{\{\s*\w+\s*\}\}/);
   });
 });
+
+describe('formatDuration, which puts a configured lifetime into email copy', () => {
+  // The three templates that mention a duration all render it through this, so
+  // "one hour" in the reset email and "one hour" in the cart reminder are the
+  // same string produced the same way rather than two authors' phrasing.
+  it('spells a single hour rather than printing a numeral', () => {
+    expect(formatDuration(1)).toBe('one hour');
+  });
+
+  it('counts whole hours', () => {
+    expect(formatDuration(2)).toBe('2 hours');
+    expect(formatDuration(24)).toBe('24 hours');
+  });
+
+  // A fractional hour reads badly as "0.5 hours", and worse as "1.5 hours" in a
+  // sentence a customer is meant to act on.
+  it('drops to minutes for anything that is not a whole number of hours', () => {
+    expect(formatDuration(0.5)).toBe('30 minutes');
+    expect(formatDuration(0.25)).toBe('15 minutes');
+    expect(formatDuration(1.5)).toBe('90 minutes');
+  });
+});
+
+describe('the duration placeholders', () => {
+  it('offers expiresIn on the two templates that carry a link with a lifetime', () => {
+    expect(TEMPLATES.verification.available).toContain('expiresIn');
+    expect(TEMPLATES.passwordReset.available).toContain('expiresIn');
+  });
+
+  it('offers holdDuration on the cart reminder', () => {
+    expect(TEMPLATES.cartReminder.available).toContain('holdDuration');
+  });
+
+  // Required would reject every template an admin saved before this existed,
+  // and the whole point is that their copy keeps sending.
+  it.each([
+    ['verification', 'expiresIn'],
+    ['passwordReset', 'expiresIn'],
+    ['cartReminder', 'holdDuration']
+  ] as const)('does not make %s require %s', (key, name) => {
+    expect(TEMPLATES[key].required).not.toContain(name);
+  });
+
+  it('renders a body saved before the placeholder existed, unchanged', () => {
+    const { html } = renderTemplate(
+      'passwordReset',
+      { subject: 'Reset it', body: 'Go [here]({{resetUrl}}). This link expires in one hour.' },
+      { resetUrl: 'https://shop.test/r', expiresIn: 'two hours' }
+    );
+    expect(html).toContain('one hour');
+    expect(html).not.toMatch(/\{\{\s*\w+\s*\}\}/);
+  });
+
+  it('substitutes the duration when a body does use the placeholder', () => {
+    const { html } = renderTemplate(
+      'passwordReset',
+      { subject: 'Reset it', body: 'Go [here]({{resetUrl}}). Expires in {{expiresIn}}.' },
+      { resetUrl: 'https://shop.test/r', expiresIn: 'two hours' }
+    );
+    expect(html).toContain('two hours');
+  });
+});
+
+describe('greeting, built from the configured format', () => {
+  const FORMAT = 'Hi {{firstName}},';
+  const FALLBACK = 'Hi,';
+
+  it('substitutes the first name into the format', () => {
+    expect(greeting('Ada', FORMAT, FALLBACK)).toBe('Hi Ada,');
+  });
+
+  it('honours a format an admin has rewritten', () => {
+    expect(greeting('Ada', 'Dear {{firstName}} {{lastName}}:', FALLBACK, 'Lovelace'))
+      .toBe('Dear Ada Lovelace:');
+  });
+
+  it('tolerates whitespace inside the braces, as the renderer does', () => {
+    expect(greeting('Ada', 'Hi {{ firstName }},', FALLBACK)).toBe('Hi Ada,');
+  });
+
+  // The case #106 was about. Customers who registered while first names were
+  // optional genuinely have none, and substituting an empty string into the
+  // format would send them "Hi ,".
+  it.each([null, undefined, '', '   '])(
+    'uses the fallback whole rather than a format with a hole in it (%p)',
+    (name) => {
+      expect(greeting(name, FORMAT, FALLBACK)).toBe('Hi,');
+    }
+  );
+
+  it('does not leave a lastName placeholder behind when there is no last name', () => {
+    expect(greeting('Ada', 'Hi {{firstName}} {{lastName}},', FALLBACK, null))
+      .not.toMatch(/\{\{/);
+  });
+});
+
+describe('every template can address the customer', () => {
+  it.each(KEYS)('%s offers greeting, firstName and lastName', (key) => {
+    expect(TEMPLATES[key].available).toEqual(
+      expect.arrayContaining(['greeting', 'firstName', 'lastName'])
+    );
+  });
+});