kempo 4.6.2 → 4.8.0

package/server/utils/auth/verifyEmail.js

@@ -1,6 +1,7 @@
 import db from '../../db/index.js';
 import { verificationToken, user } from '../../db/schema.js';
 import { eq, and, gt } from 'drizzle-orm';
+import triggerHook from '../hooks/triggerHook.js';
 
 export default async ({ token }) => {
   if(!token){
@@ -36,7 +37,15 @@ export default async ({ token }) => {
       .delete(verificationToken)
       .where(eq(verificationToken.token, token));
 
-    return [null, { 
+    /*
+      Someone has just proved they own this address, which is what an extension needs before it hands
+      them something that was only ever tied to the address (guest orders, say). Fires
+      `user:email_verified` with `{ userId, email }`.
+    */
+    const [verified] = await db.select({ email: user.email }).from(user).where(eq(user.id, tokenRecord.userId)).limit(1);
+    await triggerHook('user:email_verified', { userId: tokenRecord.userId, email: verified?.email ?? null });
+
+    return [null, {
       success: true,
       userId: tokenRecord.userId
     }];

package/server/utils/dashboard/coreWidgets.js

@@ -4,6 +4,7 @@ const core = widget => ({
   owner: CORE_OWNER,
   description: null,
   icon: null,
+  iconSrc: null,
   defaultWidth: 2,
   defaultHeight: 1,
   minWidth: 1,

package/server/utils/dashboard/helpers.js

@@ -24,6 +24,7 @@ export const normalizeWidget = ({
   title,
   description = null,
   icon = null,
+  iconSrc = null,
   element,
   module,
   defaultWidth = 2,
@@ -57,6 +58,10 @@ export const normalizeWidget = ({
     return [{ code: 400, msg: 'Icon must be an icon name' }, null];
   }
 
+  if(iconSrc !== null && !(isLocalPath(iconSrc) && iconSrc.length <= 200)){
+    return [{ code: 400, msg: 'iconSrc must be the path to an icon file on this site, beginning with a single "/"' }, null];
+  }
+
   if(typeof element !== 'string' || !ELEMENT_PATTERN.test(element)){
     return [{ code: 400, msg: 'Element must be a custom element tag name such as "my-ext-widget"' }, null];
   }
@@ -128,6 +133,7 @@ export const normalizeWidget = ({
     title: title.trim(),
     description,
     icon,
+    iconSrc,
     element,
     module,
     defaultWidth,

package/server/utils/email/defaultSender.js

@@ -0,0 +1,2 @@
+/* The sender kempo uses until the site sets its own. Providers refuse it, so an email extension that knows a better one (the mailbox it signs in with) can use that instead, see `fromIsDefault`. */
+export default 'noreply@example.com';

package/server/utils/email/dispatchEmail.js

@@ -0,0 +1,56 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, eq, sql } from 'drizzle-orm';
+import triggerHook from '../hooks/triggerHook.js';
+import emailSettings from './emailSettings.js';
+import defaultSender from './defaultSender.js';
+
+export const SEND_HOOK = 'email:send';
+
+/*
+  One try at sending a queued email.
+
+  The email is taken (queued -> sending, one conditional UPDATE, so of several processes only one sends it) and the `email:send`
+  hook is fired with `{ email }`. Each email extension answers with what it did, and the first to say it sent it ends the chain, so
+  with several installed only one sends and a failed one hands the email to the next:
+
+    export default async ({ email }) => ({ sent: true, provider: 'my-sender', messageId: 'abc' });   // it went
+    export default async ({ email }) => ({ sent: false, error: 'Mailbox full' });                    // it tried and could not (throwing says the same)
+    export default async ({ email }) => ({ sent: false, skipped: true, error: 'No API key is saved' }); // it is not set up, so it did not try
+
+  `email` is `{ id, to, from, fromIsDefault, subject, html, type, attempt }`; `fromIsDefault` says the site has not set its own sender, so
+  `from` is only a placeholder and a sender that knows a better one (the mailbox it signs in with) can use that. A handler sends the email and returns; it never touches the log, which
+  kempo keeps. After the chain the email is `sent`, or goes back to `queued` for a retry, or is `failed` when it has no tries left
+  (the first try plus `email_max_retries`). Resolves like sendEmail.
+*/
+const finish = async (id, changes) => {
+  const [row] = await db.update(email).set({ ...changes, updatedAt: new Date() }).where(eq(email.id, id)).returning();
+  return row;
+};
+
+export default async id => {
+  const [claimed] = await db.update(email)
+    .set({ status: 'sending', attempts: sql`${email.attempts} + 1`, updatedAt: new Date() })
+    .where(and(eq(email.id, id), eq(email.status, 'queued')))
+    .returning();
+  if(!claimed) return [{ code: 409, msg: 'That email is not waiting to be sent', emailId: id }, null];
+
+  const [hookError, fired] = await triggerHook(SEND_HOOK, { email: { id: claimed.id, to: claimed.recipient, from: claimed.sender, fromIsDefault: claimed.sender === defaultSender, subject: claimed.subject, html: claimed.html, type: claimed.type, attempt: claimed.attempts } }, { stopWhen: result => result?.sent === true });
+  const results = fired?.results ?? [];
+  const sent = results.find(entry => entry.result?.sent === true);
+
+  if(sent){
+    await finish(id, { status: 'sent', sentAt: new Date(), lastError: null, provider: String(sent.result.provider ?? sent.owner).slice(0, 100), providerRef: sent.result.messageId ? String(sent.result.messageId).slice(0, 200) : null });
+    return [null, { id, status: 'sent', provider: sent.result.provider ?? sent.owner }];
+  }
+
+  /* An extension that is not set up says so and is not counted as having tried: its reason is only shown when nothing else did. */
+  const said = entry => `${entry.owner}: ${entry.error ?? entry.result?.error ?? 'did not send it'}`;
+  const tried = results.filter(entry => !entry.result?.skipped);
+  const reasons = hookError ? [hookError.msg] : (tried.length ? tried : results).map(said);
+  const message = (tried.length || hookError ? reasons.join('; ') : results.length ? `No email extension is set up yet. ${reasons.join('; ')}` : '') || 'No email extension is installed to send email (install kempo-resend or kempo-smtp)';
+  const { maxRetries } = await emailSettings();
+  const final = claimed.attempts >= 1 + maxRetries;
+  await finish(id, { status: final ? 'failed' : 'queued', lastError: message.slice(0, 1000) });
+  return [{ code: tried.length ? 502 : 503, msg: message, emailId: id }, null];
+};

package/server/utils/email/emailSettings.js

@@ -0,0 +1,21 @@
+import getSetting from '../settings/getSetting.js';
+
+const DEFAULT_RETRIES = 1;
+const DEFAULT_RETENTION_DAYS = 30;
+
+const whole = (value, fallback) => (Number.isInteger(Number(value)) && value !== '' && value !== null && Number(value) >= 0 ? Number(value) : fallback);
+
+/*
+  What the email settings say, with a safe value for anything unreadable: `maxRetries` (tries after the first), `retentionDays` (0 keeps
+  forever) and `retentionByType` ({ type: days }), which wins over `retentionDays` for that kind of email.
+*/
+export default async () => {
+  const [, retries] = await getSetting('system', 'email_max_retries', DEFAULT_RETRIES);
+  const [, days] = await getSetting('system', 'email_retention_days', DEFAULT_RETENTION_DAYS);
+  const [, byType] = await getSetting('system', 'email_retention_by_type', {});
+  const retentionByType = {};
+  if(byType && typeof byType === 'object' && !Array.isArray(byType)){
+    for(const [type, value] of Object.entries(byType)) if(whole(value, null) !== null) retentionByType[type] = Number(value);
+  }
+  return { maxRetries: whole(retries, DEFAULT_RETRIES), retentionDays: whole(days, DEFAULT_RETENTION_DAYS), retentionByType };
+};

package/server/utils/email/emailTemplatePaths.js

@@ -0,0 +1,36 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PART = '[a-z0-9][a-z0-9-]*';
+const NAME = new RegExp(`^(?:(${PART})/)?(${PART})$`);
+
+/*
+  Where an email template lives, the same places renderEmailTemplate looks:
+
+    "owner/name"  the extension's own `node_modules/owner/emails/name.page.html`, which the site overrides at
+                  `templates/emails/owner/name.page.html`
+    "name"        kempo's own `app-templates/emails/name.page.html`, which the site overrides at
+                  `templates/emails/name.page.html`
+*/
+export const parseTemplateName = template => {
+  const match = typeof template === 'string' ? NAME.exec(template) : null;
+  return match ? { owner: match[1] ?? null, name: match[2] } : null;
+};
+
+export const siteEmailsDir = owner => (owner ? join(process.cwd(), 'templates/emails', owner) : join(process.cwd(), 'templates/emails'));
+
+export const defaultEmailsDir = owner => (owner ? join(process.cwd(), 'node_modules', owner, 'emails') : join(here, '../../../app-templates/emails'));
+
+export const locateTemplate = template => {
+  const parsed = parseTemplateName(template);
+  if(!parsed) return null;
+  return { ...parsed, template, sitePath: join(siteEmailsDir(parsed.owner), `${parsed.name}.page.html`), defaultPath: join(defaultEmailsDir(parsed.owner), `${parsed.name}.page.html`) };
+};
+
+export const isOwnerName = owner => new RegExp(`^${PART}$`).test(owner);
+
+/* The page's `title`, which is what a list shows as the email's name. */
+export const titleOf = source => /<page\b[^>]*\stitle="([^"]*)"/.exec(source)?.[1] ?? '';
+
+export const sameSource = (a, b) => String(a).replace(/\r\n/g, '\n').trim() === String(b).replace(/\r\n/g, '\n').trim();

package/server/utils/email/getEmail.js

@@ -0,0 +1,14 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+
+/* One email of the log, with its whole body. Resolves to [error, email]. */
+export default async id => {
+  if(!id) return [{ code: 400, msg: 'An email id is required' }, null];
+  try {
+    const [row] = await db.select().from(email).where(eq(email.id, String(id))).limit(1);
+    return row ? [null, row] : [{ code: 404, msg: 'Email not found' }, null];
+  } catch {
+    return [{ code: 500, msg: 'Failed to read the email' }, null];
+  }
+};

package/server/utils/email/getSenderEmail.js

@@ -0,0 +1,11 @@
+import getSenderFrom from './getSenderFrom.js';
+
+/*
+  The bare address kempo sends its emails from (`shop@example.com`, out of `Shop <shop@example.com>`), for an extension that needs
+  one for the site, such as a shipping label's sender. It is the same address emails go out from (see getSenderFrom), so it is a
+  placeholder (noreply@example.com) until the site sets one. Resolves to the address, or null if there is none to find.
+*/
+export default async () => {
+  const from = (await getSenderFrom()).trim();
+  return (/<([^<>\s]+@[^<>\s]+)>/.exec(from) ?? /^([^<>\s]+@[^<>\s]+)$/.exec(from))?.[1] ?? null;
+};

package/server/utils/email/getSenderFrom.js

@@ -0,0 +1,18 @@
+import getSetting from '../settings/getSetting.js';
+import isValidSender from './isValidSender.js';
+import PLACEHOLDER from './defaultSender.js';
+
+/*
+  What kempo sends its emails from, as the email provider takes it. In order:
+
+    the `system:email_from` setting   edited on the admin Settings screen (it must be a valid address, or empty)
+    `EMAIL_FROM`                      the server environment; what the README and `kempo init` write
+    `SMTP_FROM`                       what the environment used to be called
+    a placeholder address (noreply@example.com), which most providers will refuse until the site sets its own
+
+  A value that is not an address is skipped rather than sent, so a bad environment value cannot stop every email.
+*/
+export default async () => {
+  const [, stored] = await getSetting('system', 'email_from', '');
+  return [stored, process.env.EMAIL_FROM, process.env.SMTP_FROM].map(value => String(value ?? '').trim()).find(isValidSender) ?? PLACEHOLDER;
+};

package/server/utils/email/isValidSender.js

@@ -0,0 +1,4 @@
+/* Whether text can be the address emails are sent from: `name@example.com` or `Shop Name <name@example.com>`, on one line. */
+export default value => typeof value === 'string'
+  && value.length <= 200
+  && /^(?:[^<>\r\n@]+<[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+>|[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+)$/.test(value.trim());

package/server/utils/email/listEmailTemplates.js

@@ -0,0 +1,23 @@
+import { readdir } from 'fs/promises';
+import { defaultEmailsDir, isOwnerName, siteEmailsDir } from './emailTemplatePaths.js';
+import readEmailTemplate from './readEmailTemplate.js';
+
+const SUFFIX = '.page.html';
+
+const namesIn = async dir => (await readdir(dir).catch(() => [])).filter(file => file.endsWith(SUFFIX)).map(file => file.slice(0, -SUFFIX.length));
+
+/*
+  The email templates of one extension (`owner`), or kempo's own and the site's (no owner): the packaged ones, and any the site has
+  added. Resolves to [error, [{ template, name, title, overridden, packaged }]] sorted by name.
+*/
+export default async ({ owner = null } = {}) => {
+  if(owner !== null && !isOwnerName(owner)) return [{ code: 400, msg: 'Invalid extension name' }, null];
+
+  const names = [...new Set([...await namesIn(defaultEmailsDir(owner)), ...await namesIn(siteEmailsDir(owner))])].sort();
+  const templates = [];
+  for(const name of names){
+    const [error, found] = await readEmailTemplate({ template: owner ? `${owner}/${name}` : name });
+    if(!error) templates.push({ template: found.template, name, title: found.title, overridden: found.overridden, packaged: found.defaultSource !== null });
+  }
+  return [null, templates];
+};

package/server/utils/email/listEmails.js

@@ -0,0 +1,35 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, desc, eq, ilike, or, sql } from 'drizzle-orm';
+
+const STATUSES = ['queued', 'sending', 'sent', 'failed'];
+
+/*
+  The log, newest first, without the bodies (read one with getEmail). `status`, `type` and `search` (a part of the recipient or the
+  subject) narrow it. Resolves to [error, { emails, total, limit, offset }].
+*/
+export default async ({ status, type, search, limit = 50, offset = 0 } = {}) => {
+  try {
+    const conditions = [];
+    if(status){
+      if(!STATUSES.includes(status)) return [{ code: 400, msg: `Status must be one of ${STATUSES.join(', ')}` }, null];
+      conditions.push(eq(email.status, status));
+    }
+    if(type) conditions.push(eq(email.type, String(type)));
+    if(search){
+      const like = `%${String(search).replace(/[\\%_]/g, '\\$&')}%`;
+      conditions.push(or(ilike(email.recipient, like), ilike(email.subject, like)));
+    }
+    const where = conditions.length ? and(...conditions) : undefined;
+    const take = Math.min(Math.max(Number(limit) || 50, 1), 200);
+    const skip = Math.max(Number(offset) || 0, 0);
+    const emails = await db.select({
+      id: email.id, type: email.type, recipient: email.recipient, sender: email.sender, subject: email.subject, status: email.status, attempts: email.attempts,
+      lastError: email.lastError, provider: email.provider, createdAt: email.createdAt, updatedAt: email.updatedAt, sentAt: email.sentAt,
+    }).from(email).where(where).orderBy(desc(email.createdAt)).limit(take).offset(skip);
+    const [{ total }] = await db.select({ total: sql`count(*)::int` }).from(email).where(where);
+    return [null, { emails, total, limit: take, offset: skip }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to read the email log' }, null];
+  }
+};

package/server/utils/email/maintainEmails.js

@@ -0,0 +1,46 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, asc, eq, lt, or, gt, sql } from 'drizzle-orm';
+import dispatchEmail from './dispatchEmail.js';
+import emailSettings from './emailSettings.js';
+import pruneEmails from './pruneEmails.js';
+
+const MINUTE_MS = 60 * 1000;
+const STUCK_MS = 5 * MINUTE_MS;
+const BACKOFF_MS = MINUTE_MS;
+const TOO_OLD_MS = 24 * 60 * MINUTE_MS;
+const BATCH = 50;
+
+/*
+  The email job, run every minute by the scheduler (kempo registers it itself):
+
+    - a `sending` email that has not finished in five minutes (the process died) goes back to `queued`;
+    - a `queued` email with tries left is sent again, a minute after its last try at the earliest, up to 50 at a time;
+    - a `queued` email older than a day is marked `failed` instead, so a password-reset link is never sent a day late;
+    - emails older than the retention settings are deleted.
+*/
+export default async () => {
+  const now = Date.now();
+  const { maxRetries } = await emailSettings();
+
+  await db.update(email)
+    .set({ status: 'queued', lastError: 'The send did not finish' })
+    .where(and(eq(email.status, 'sending'), lt(email.updatedAt, new Date(now - STUCK_MS))));
+
+  await db.update(email)
+    .set({ status: 'failed', lastError: sql`coalesce(${email.lastError}, 'Never sent') || ' (too old to send now)'`, updatedAt: new Date() })
+    .where(and(eq(email.status, 'queued'), lt(email.createdAt, new Date(now - TOO_OLD_MS))));
+
+  const due = await db.select({ id: email.id }).from(email)
+    .where(and(
+      eq(email.status, 'queued'),
+      gt(email.createdAt, new Date(now - TOO_OLD_MS)),
+      lt(email.attempts, 1 + maxRetries),
+      or(eq(email.attempts, 0), lt(email.updatedAt, new Date(now - BACKOFF_MS))),
+    ))
+    .orderBy(asc(email.createdAt))
+    .limit(BATCH);
+  for(const { id } of due) await dispatchEmail(id);
+
+  await pruneEmails();
+};

package/server/utils/email/pruneEmails.js

@@ -0,0 +1,29 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, lt, eq, notInArray } from 'drizzle-orm';
+import emailSettings from './emailSettings.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/*
+  Deletes the emails that are older than the settings keep them. A kind of email in `email_retention_by_type` is kept that many days,
+  every other kind `email_retention_days`; 0 keeps it forever. Resolves to [error, { deleted }].
+*/
+export default async ({ now = new Date() } = {}) => {
+  try {
+    const { retentionDays, retentionByType } = await emailSettings();
+    const specific = Object.keys(retentionByType);
+    let deleted = 0;
+    for(const [type, days] of Object.entries(retentionByType)){
+      if(days === 0) continue;
+      deleted += (await db.delete(email).where(and(eq(email.type, type), lt(email.createdAt, new Date(now.getTime() - days * DAY_MS)))).returning({ id: email.id })).length;
+    }
+    if(retentionDays > 0){
+      const older = lt(email.createdAt, new Date(now.getTime() - retentionDays * DAY_MS));
+      deleted += (await db.delete(email).where(specific.length ? and(notInArray(email.type, specific), older) : older).returning({ id: email.id })).length;
+    }
+    return [null, { deleted }];
+  } catch {
+    return [{ code: 500, msg: 'Failed to delete old emails' }, null];
+  }
+};

package/server/utils/email/readEmailTemplate.js

@@ -0,0 +1,28 @@
+import { readFile } from 'fs/promises';
+import { locateTemplate, sameSource, titleOf } from './emailTemplatePaths.js';
+
+const read = path => readFile(path, 'utf8').catch(() => null);
+
+/*
+  One email template as the site would send it: `source` is the site's own version when it has one and the packaged one
+  otherwise, `defaultSource` is the packaged one (null when there is none), and `overridden` says the site's differs from it.
+  Resolves to [error, { template, owner, name, title, source, defaultSource, overridden }].
+*/
+export default async ({ template } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+
+  const [site, packaged] = await Promise.all([read(located.sitePath), read(located.defaultPath)]);
+  if(site === null && packaged === null) return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+
+  const source = site ?? packaged;
+  return [null, {
+    template,
+    owner: located.owner,
+    name: located.name,
+    title: titleOf(source),
+    source,
+    defaultSource: packaged,
+    overridden: site !== null && packaged !== null && !sameSource(site, packaged),
+  }];
+};

package/server/utils/email/renderEmailTemplate.js

@@ -0,0 +1,63 @@
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { renderPage, renderExternalPage } from 'kempo-server/templating';
+import shake from 'kempo-css/shake';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/*
+  Renders an email template to HTML, without sending it.
+
+  A plain name ("verify-email") is looked up in the site's `templates/emails`, then in kempo's own.
+
+  A name with an owner ("my-extension/order-paid") is an extension's template. The site may override
+  it at `templates/emails/my-extension/order-paid.page.html`; otherwise it is the extension's own
+  `emails/order-paid.page.html`. Either way the layout (`<page template="email">`) is the site's
+  `templates/emails/email.template.html` when it has one, and kempo's otherwise, so every email a site
+  sends looks the same.
+
+  Returns [error, html].
+*/
+export default async ({ template, data = {} } = {}) => {
+  if(!template){
+    return [{ code: 400, msg: 'Template name is required' }, null];
+  }
+  if(!/^[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)?$/.test(template)){
+    return [{ code: 400, msg: `Invalid email template name: ${template}` }, null];
+  }
+
+  const consumerDir = join(process.cwd(), 'templates/emails');
+  const moduleDir = join(__dirname, '../../../app-templates/emails');
+  const [owner, name] = template.includes('/') ? template.split('/') : [null, template];
+
+  let pagePath;
+  let rootDir;
+  if(owner){
+    const override = join(consumerDir, owner, `${name}.page.html`);
+    pagePath = existsSync(override) ? override : join(process.cwd(), 'node_modules', owner, 'emails', `${name}.page.html`);
+    rootDir = existsSync(join(consumerDir, 'email.template.html')) ? consumerDir : moduleDir;
+  } else {
+    rootDir = existsSync(join(consumerDir, `${name}.page.html`)) ? consumerDir : moduleDir;
+    pagePath = join(rootDir, `${name}.page.html`);
+  }
+
+  if(!existsSync(pagePath)){
+    return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+  }
+
+  const themePath = join(process.cwd(), 'public/styles.css');
+  const themeOpts = existsSync(themePath) ? { theme: themePath } : {};
+
+  try {
+    let html = owner
+      ? await renderExternalPage(pagePath, rootDir, rootDir, {}, data)
+      : await renderPage(pagePath, rootDir, {}, data);
+    const css = shake(html, { ...themeOpts, colorMode: 'light' });
+    html = html.replace('</head>', `<style>${css}</style></head>`);
+    return [null, html];
+  } catch(error){
+    console.error('Email render error:', error);
+    return [{ code: 500, msg: 'Failed to render the email template' }, null];
+  }
+};

package/server/utils/email/resetEmailTemplate.js

@@ -0,0 +1,15 @@
+import { readFile, rm } from 'fs/promises';
+import { locateTemplate } from './emailTemplatePaths.js';
+
+/* Removes the site's version of an email template so the packaged one is used again. Resolves to [error, { template }]. */
+export default async ({ template } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+  if(await readFile(located.defaultPath, 'utf8').catch(() => null) === null) return [{ code: 409, msg: 'There is no packaged version to go back to' }, null];
+  try {
+    await rm(located.sitePath, { force: true });
+    return [null, { template }];
+  } catch {
+    return [{ code: 500, msg: 'The template could not be reset' }, null];
+  }
+};

package/server/utils/email/retryEmail.js

@@ -0,0 +1,21 @@
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import { and, eq, inArray } from 'drizzle-orm';
+import dispatchEmail from './dispatchEmail.js';
+
+/*
+  Tries an email that did not go again, as if it were new: it gets the full number of tries once more. Only a `queued` or `failed`
+  email can be tried again (one that is `sent` or being sent is left alone). Resolves like sendEmail.
+*/
+export default async id => {
+  try {
+    const [row] = await db.update(email)
+      .set({ status: 'queued', attempts: 0, lastError: null, updatedAt: new Date() })
+      .where(and(eq(email.id, String(id ?? '')), inArray(email.status, ['queued', 'failed'])))
+      .returning({ id: email.id });
+    if(!row) return [{ code: 409, msg: 'Only an email that is waiting or failed can be tried again' }, null];
+  } catch {
+    return [{ code: 500, msg: 'Failed to retry the email' }, null];
+  }
+  return dispatchEmail(String(id));
+};

package/server/utils/email/saveEmailTemplate.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, rm, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { locateTemplate } from './emailTemplatePaths.js';
+import renderEmailTemplate from './renderEmailTemplate.js';
+
+const MAX_SOURCE = 100000;
+
+/*
+  The site's own version of an email template, written to `templates/emails/` so it is used from the next email on (the packaged
+  one is never touched). Only a template that exists can be saved, so this cannot make up new names. The new version is rendered
+  once before it is kept, and the old one is put back when it does not render, so a typo cannot stop the site sending that email.
+  Resolves to [error, { template }].
+*/
+export default async ({ template, source } = {}) => {
+  const located = locateTemplate(template);
+  if(!located) return [{ code: 400, msg: 'Invalid email template name' }, null];
+  if(typeof source !== 'string' || !source.trim()) return [{ code: 400, msg: 'The template cannot be empty' }, null];
+  if(source.length > MAX_SOURCE) return [{ code: 400, msg: `The template can be at most ${MAX_SOURCE} characters` }, null];
+  if(source.includes('\u0000')) return [{ code: 400, msg: 'The template cannot contain null characters' }, null];
+
+  const [site, packaged] = await Promise.all([readFile(located.sitePath, 'utf8').catch(() => null), readFile(located.defaultPath, 'utf8').catch(() => null)]);
+  if(site === null && packaged === null) return [{ code: 404, msg: `Email template not found: ${template}` }, null];
+
+  try {
+    await mkdir(dirname(located.sitePath), { recursive: true });
+    await writeFile(located.sitePath, source);
+  } catch {
+    return [{ code: 500, msg: 'The template could not be saved' }, null];
+  }
+
+  const [renderError] = await renderEmailTemplate({ template, data: {} });
+  if(renderError){
+    if(site === null) await rm(located.sitePath, { force: true });
+    else await writeFile(located.sitePath, site);
+    return [{ code: 400, msg: `The template does not render, so it was not saved: ${renderError.msg}` }, null];
+  }
+  return [null, { template }];
+};

package/server/utils/email/sendEmail.js

@@ -1,48 +1,38 @@
-import { Resend } from 'resend';
+import crypto from 'crypto';
+import db from '../../db/index.js';
+import { email } from '../../db/schema.js';
+import getSenderFrom from './getSenderFrom.js';
+import dispatchEmail from './dispatchEmail.js';
 
 /*
-  Constructed on first send, not at import. The Resend constructor throws when the key is missing,
-  and this module is reachable from the server SDK, so building it at module scope made an unset
-  RESEND_API_KEY fail every route that transitively imports it rather than just disabling email.
-*/
-let resend = null;
-const client = () => (resend ??= new Resend(process.env.RESEND_API_KEY));
-
-export default async ({ to, subject, html }) => {
-  if(!process.env.RESEND_API_KEY){
-    return [{ code: 500, msg: 'RESEND_API_KEY not configured' }, null];
-  }
+  Asks for an email to be sent. Kempo does not send email itself: this saves the email in the log (the `email` table) and hands it to
+  whichever email extension is installed (kempo-resend, kempo-smtp...) through the `email:send` hook; see dispatchEmail.js.
 
+  `template` is the name of the template the email was made from, if any, and is its type in the log. It resolves to
+  `[null, { id, status: 'sent' }]` when a sender sent it, or `[{ code, msg, emailId }, null]` when none did: 503 when there is no email
+  extension installed, 502 when one tried and failed. Either way the email is in the log, and a failed one is tried again (see the
+  `email_max_retries` setting).
+*/
+export default async ({ to, subject, html, template = null } = {}) => {
   if(!to){
     return [{ code: 400, msg: 'Recipient email is required' }, null];
   }
-  
+
   if(!subject){
     return [{ code: 400, msg: 'Email subject is required' }, null];
   }
-  
+
   if(!html){
     return [{ code: 400, msg: 'Email content is required' }, null];
   }
 
-  const from = process.env.SMTP_FROM || 'onboarding@resend.dev';
-
+  const id = crypto.randomUUID();
+  const now = new Date();
   try {
-    const { data, error } = await client().emails.send({
-      from,
-      to,
-      subject,
-      html,
-    });
-
-    if(error){
-      console.error('Email send error:', error);
-      return [{ code: 500, msg: error.message || 'Failed to send email' }, null];
-    }
-
-    return [null, { success: true, messageId: data.id }];
-  } catch(error){
-    console.error('Email send error:', error);
-    return [{ code: 500, msg: 'Failed to send email' }, null];
+    await db.insert(email).values({ id, type: template || 'other', recipient: String(to), sender: await getSenderFrom(), subject: String(subject), html: String(html), status: 'queued', attempts: 0, createdAt: now, updatedAt: now });
+  } catch(error) {
+    return [{ code: 500, msg: 'The email could not be saved to send' }, null];
   }
+
+  return dispatchEmail(id);
 };