@antelopejs/dms-mailing 0.8.0 → 0.9.1

package/src/routes/template-content.ts

@@ -0,0 +1,45 @@
+import type { MailingTemplate } from "../db";
+import type { TemplateChange } from "../engine";
+import type {
+  CategoryInLocale,
+  TemplateContent,
+  VariableDefinition,
+} from "../types";
+import type { JsonObject } from "../types/json";
+
+export interface TemplateSender {
+  name: string;
+  email: string;
+  replyTo: string;
+}
+
+export interface TemplateContentResponse {
+  /** The template, its name in the reader's language. */
+  template: MailingTemplate;
+  /** The content the editor works on: the draft, else the published one. */
+  content: TemplateContent;
+  /** What customers receive; `null` when the template was never published. */
+  publishedContent: TemplateContent | null;
+  hasDraft: boolean;
+  /** Version customers receive; 0 when never published. */
+  version: number;
+  /** The draft revision a save or a publish must carry back. */
+  revision: number;
+  changes: TemplateChange[];
+  /** The declarations the editor works on: the draft's, else the published. */
+  variables: VariableDefinition[];
+  /** Paths the working content references, across every locale. */
+  detectedVariables: string[];
+  /**
+   * The contract callers send against: the published declarations and the
+   * paths the published content references; `null` when never published.
+   */
+  publishedVariables: VariableDefinition[] | null;
+  publishedDetectedVariables: string[] | null;
+  testData: JsonObject;
+  fallbackLocale: string;
+  /** Whether a send missing a variable fails rather than goes out blank. */
+  blockOnMissingVariables: boolean;
+  categories: CategoryInLocale[];
+  sender: TemplateSender;
+}

package/src/routes/templates.ts

@@ -22,7 +22,6 @@ import {
 import {
   collectContentVariablePaths,
   resolveEmail,
-  type TemplateChange,
   valueFormatOf,
 } from "../engine";
 import {
@@ -31,7 +30,7 @@ import {
   type TemplateFields,
   TemplateModel,
 } from "../db";
-import { saveDetails } from "../data/templates-table";
+import { INVALID_TEMPLATE, saveDetails } from "../data/templates-table";
 import { TemplatesPageController } from "../pages/templates";
 import { forAudience, statsWindowStart } from "../services/metrics";
 import { refreshTemplateAttention } from "../services/template-attention";
@@ -75,18 +74,18 @@ import {
 import {
   BUSINESS_AUDIENCE,
   type CategoryInLocale,
-  type TemplateContent,
   type TemplateStatus,
-  type VariableDefinition,
 } from "../types";
 import {
   duplicateSchema,
   previewSchema,
   publishSchema,
   saveContentSchema,
+  templateDetailsSchema,
   testDataSchema,
   variablesSchema,
 } from "../validation/templates.schema";
+import type { TemplateContentResponse } from "./template-content";
 
 const STARTER_NOT_FOUND = "$dms_mailing.errors.starter_not_found";
 const INVALID_CONTENT = "$dms_mailing.errors.invalid_content";
@@ -125,43 +124,6 @@ export interface CategoriesResponse {
   categories: CategoryInLocale[];
 }
 
-export interface TemplateSender {
-  name: string;
-  email: string;
-  replyTo: string;
-}
-
-export interface TemplateContentResponse {
-  /** The template, its name in the reader's language. */
-  template: MailingTemplate;
-  /** The content the editor works on: the draft, else the published one. */
-  content: TemplateContent;
-  /** What customers receive; `null` when the template was never published. */
-  publishedContent: TemplateContent | null;
-  hasDraft: boolean;
-  /** Version customers receive; 0 when never published. */
-  version: number;
-  /** The draft revision a save or a publish must carry back. */
-  revision: number;
-  changes: TemplateChange[];
-  /** The declarations the editor works on: the draft's, else the published. */
-  variables: VariableDefinition[];
-  /** Paths the working content references, across every locale. */
-  detectedVariables: string[];
-  /**
-   * The contract callers send against: the published declarations and the
-   * paths the published content references; `null` when never published.
-   */
-  publishedVariables: VariableDefinition[] | null;
-  publishedDetectedVariables: string[] | null;
-  testData: Record<string, unknown>;
-  fallbackLocale: string;
-  /** Whether a send missing a variable fails rather than goes out blank. */
-  blockOnMissingVariables: boolean;
-  categories: CategoryInLocale[];
-  sender: TemplateSender;
-}
-
 export interface StarterSummary {
   id: string;
   name: string;
@@ -221,9 +183,9 @@ export class TemplatesController extends Controller(
   }
 
   @Get("/starters")
-  starters(): { starters: StarterSummary[] } {
+  starters() {
     return {
-      starters: STARTER_TEMPLATES.map((starter) => ({
+      starters: STARTER_TEMPLATES.map((starter): StarterSummary => ({
         id: starter.id,
         name: starter.name,
         slug: starter.slug,
@@ -559,7 +521,12 @@ export class TemplatesController extends Controller(
     @JSONBody() body: unknown,
   ) {
     const template = await requireTemplate(this.templates, id);
-    await saveDetails(this.ctx, template, body, this.author);
+    const details = assertValidation(
+      body,
+      (value) => templateDetailsSchema.parse(value),
+      () => INVALID_TEMPLATE,
+    );
+    await saveDetails(this.ctx, template, details, this.author);
     return { id };
   }
 

package/src/routes/zod-json.ts

@@ -0,0 +1,28 @@
+import type { HTTPBody } from "@antelopejs/interface-api";
+import type { ZodIssue } from "zod";
+
+function isJson(value: unknown): value is HTTPBody {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+  if (Array.isArray(value)) return value.every(isJson);
+  return typeof value === "object" && Object.values(value).every(isJson);
+}
+
+/**
+ * zod's issues as the JSON value `JSON.stringify` writes for them, so a body
+ * holding it serializes byte for byte as one holding the issues. A `ZodError`
+ * nested in an issue (`unionErrors`, `argumentsError`, `returnTypeError`)
+ * becomes its enumerable fields, `issues` and `name`.
+ */
+export function zodIssuesJson(issues: readonly ZodIssue[]): HTTPBody {
+  const json: unknown = JSON.parse(JSON.stringify(issues));
+  if (!isJson(json))
+    throw new TypeError("zod issues did not serialize to JSON");
+  return json;
+}

package/src/services/attention.ts

@@ -375,20 +375,21 @@ type TemplateAttentionRule = (
   context: TemplateAttentionContext,
 ) => boolean;
 
-const TEMPLATE_ATTENTION_RULES: Record<
+const TEMPLATE_ATTENTION_RULES = new Map<
   TemplateAttentionReason,
   TemplateAttentionRule
-> = {
-  stale_draft: (template, context) => isStaleDraft(template, context.now),
-  never_sent: (template, context) =>
-    template.status === "live" && !context.sentSlugs.has(template.slug),
-  missing_locale: (template, context) =>
-    isMissingLocale(template, context.knownLocales),
-};
-
-const TEMPLATE_ATTENTION_REASONS = Object.keys(
-  TEMPLATE_ATTENTION_RULES,
-) as TemplateAttentionReason[];
+>([
+  ["stale_draft", (template, context) => isStaleDraft(template, context.now)],
+  [
+    "never_sent",
+    (template, context) =>
+      template.status === "live" && !context.sentSlugs.has(template.slug),
+  ],
+  [
+    "missing_locale",
+    (template, context) => isMissingLocale(template, context.knownLocales),
+  ],
+]);
 
 /**
  * Why a template needs a look, in a stable order: a draft never published and
@@ -399,7 +400,7 @@ export function templateAttentionReasons(
   template: MailingTemplate,
   context: TemplateAttentionContext,
 ): TemplateAttentionReason[] {
-  return TEMPLATE_ATTENTION_REASONS.filter((reason) =>
-    TEMPLATE_ATTENTION_RULES[reason](template, context),
-  );
+  return [...TEMPLATE_ATTENTION_RULES]
+    .filter(([, applies]) => applies(template, context))
+    .map(([reason]) => reason);
 }

package/src/services/catalog.ts

@@ -1,21 +1,17 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import type { ModuleStatus } from "@antelopejs/interface-dms/page";
+import { isText } from "../validation/guards";
+import { parseJsonObject } from "../validation/json";
 import { readCapabilities } from "./provider";
 
 const PACKAGE_JSON_PATH = path.join(__dirname, "../../package.json");
 
-interface PackageManifest {
-  version?: string;
-}
-
 /** The module's published version, as the catalog tile and the sidebar show it. */
 export function moduleVersion(): string | undefined {
   try {
-    const manifest = JSON.parse(
-      readFileSync(PACKAGE_JSON_PATH, "utf8"),
-    ) as PackageManifest;
-    return manifest.version;
+    const manifest = parseJsonObject(readFileSync(PACKAGE_JSON_PATH, "utf8"));
+    return isText(manifest.version) ? manifest.version : undefined;
   } catch {
     return undefined;
   }

package/src/services/declaration-error.ts

@@ -26,7 +26,7 @@ function describeIssues(error: ZodError): string {
 /** `input` parsed by `schema`, or a `DeclarationError` under `code`. */
 export function parseDeclared<Output, Input>(
   schema: ZodType<Output, ZodTypeDef, Input>,
-  input: unknown,
+  input: Input,
   code: string,
   subject: string,
 ): Output {

package/src/services/declarations.ts

@@ -133,7 +133,10 @@ export async function declareTemplate(
   assertKnownCategory(settings.categories, declaration.category, slug);
   const created = await createDeclared(declaration);
   if (created) return resultOf(created, "created");
-  return resultOf((await model.getBySlug(slug)) as MailingTemplate, "kept");
+  const winner = await model.getBySlug(slug);
+  if (!winner)
+    throw new Error(`Template "${slug}" disappeared before it was read`);
+  return resultOf(winner, "kept");
 }
 
 /** Category declarations of one tenant run one after the other. */

package/src/services/events.ts

@@ -16,7 +16,8 @@ import { publishSendUpdated } from "../realtime";
 import type { SendEventType, SendStatus } from "../types";
 import { notifyProblems } from "./notify";
 import { suppressAddress, suppressionReasonOf } from "./suppressions";
-import { isObject, isText } from "../validation/guards";
+import { isText } from "../validation/guards";
+import { isJsonObject } from "../validation/json";
 
 export interface SendCounters {
   status: SendStatus;
@@ -169,7 +170,8 @@ export function isSameEvent(
   if (eventId) {
     const storedDetails: unknown = JSON.parse(stored.json_details || "{}");
     return (
-      eventIdOf(isObject(storedDetails) ? storedDetails : undefined) === eventId
+      eventIdOf(isJsonObject(storedDetails) ? storedDetails : undefined) ===
+      eventId
     );
   }
   if (!event.at || stored.type !== event.type) return false;

package/src/services/metrics.ts

@@ -11,14 +11,12 @@ const AUDIENCE_KEEPS: Record<SendAudience, (send: SendSummary) => boolean> = {
   [OPERATIONAL_AUDIENCE]: () => true,
 };
 
-const AUDIENCE_BY_NAME: Record<string, SendAudience> = {
-  [BUSINESS_AUDIENCE]: BUSINESS_AUDIENCE,
-  [OPERATIONAL_AUDIENCE]: OPERATIONAL_AUDIENCE,
-};
+const isAudience = (raw: string): raw is SendAudience =>
+  Object.hasOwn(AUDIENCE_KEEPS, raw);
 
 /** Named audience behind a query value; anything unknown is the business view. */
 export function readAudience(raw: string | null | undefined): SendAudience {
-  return AUDIENCE_BY_NAME[raw ?? ""] ?? BUSINESS_AUDIENCE;
+  return raw != null && isAudience(raw) ? raw : BUSINESS_AUDIENCE;
 }
 
 const STATS_WINDOW_DAYS = 30;

package/src/services/send-import.ts

@@ -172,10 +172,12 @@ interface EntryOutcome {
 }
 
 /**
- * Writes one send: its events first, under ids derived from the send's, then
- * the send itself. A run stopped half-way leaves events no send shows yet,
- * which the next run completes; each write skips the row an earlier run
- * wrote, and a send present means it was fully imported.
+ * Writes one send: the send itself first, then its events under ids derived
+ * from the send's. An event is written only after its send, so the
+ * retention's orphan-event pass never finds an import's events before their
+ * send. A run stopped half-way leaves a send with part of its history, which
+ * the next run completes: each write skips the row an earlier run wrote, and
+ * the events are written whether or not the send was already there.
  */
 async function importOne(
   tenantId: string,
@@ -184,8 +186,10 @@ async function importOne(
   fallbackLocale: string,
 ): Promise<EntryOutcome> {
   const id = importedSendIdOf(tenantId, send.importId);
-  const sends = GetModel(SendModel, tenantId);
   const timeline = timelineOf(send);
+  const locale = send.locale ?? fallbackLocale;
+  const row = sendRow(id, send, template, locale, foldEvents(send, timeline));
+  const isImported = await GetModel(SendModel, tenantId).insertImported(row);
   const events = GetModel(SendEventModel, tenantId);
   for (const [index, entry] of timeline.entries()) {
     await events.insertImported({
@@ -196,9 +200,7 @@ async function importOne(
       json_details: JSON.stringify(entry.details ?? {}),
     });
   }
-  const locale = send.locale ?? fallbackLocale;
-  const row = sendRow(id, send, template, locale, foldEvents(send, timeline));
-  return { id, isImported: await sends.insertImported(row) };
+  return { id, isImported };
 }
 
 /**

package/src/services/send.ts

@@ -159,9 +159,6 @@ const OUTCOME_SEVERITY: Record<SendStatus, number> = {
   failed: 9,
 };
 
-const describeError = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error);
-
 const addressOf = (to: EmailAddress): string => (isText(to) ? to : to.email);
 
 const nameOf = (to: EmailAddress): string | undefined =>
@@ -376,7 +373,7 @@ async function deliverOne(
       status: "failed",
       outcome: {
         latencyMs: Date.now() - startedAt,
-        error: describeError(error),
+        error: error instanceof Error ? error.message : String(error),
       },
     };
   }
@@ -423,7 +420,7 @@ export async function deliverBatch(
     return failAll(
       input.recipients,
       Date.now() - startedAt,
-      describeError(error),
+      error instanceof Error ? error.message : String(error),
     );
   }
 }
@@ -504,7 +501,7 @@ async function recordOne(
       sendId: UNRECORDED_SEND_ID,
       status: "failed",
       messageId: message.outcome.providerMessageId,
-      error: describeError(error),
+      error: error instanceof Error ? error.message : String(error),
     };
   }
 }

package/src/services/settings.ts

@@ -5,10 +5,17 @@ import {
   MODULE_DEFAULT_SETTINGS,
   type MailingSettingsValues,
   type TemplateCategory,
+  WEBHOOK_SECRET_SOURCES,
+  type WebhookSecretSource,
 } from "../types";
+import type { JsonObject } from "../types/json";
+import type { SettingsPatch } from "../validation/settings.schema";
 
 export const WEBHOOK_SECRET_BYTES = 24;
 
+const GENERATED_SECRET: WebhookSecretSource = "generated";
+const OPERATOR_SECRET: WebhookSecretSource = "operator";
+
 function defaults(): MailingSettingsValues {
   return {
     ...MODULE_DEFAULT_SETTINGS,
@@ -16,9 +23,21 @@ function defaults(): MailingSettingsValues {
     senderEmail: "",
     replyTo: "",
     webhookSecret: randomBytes(WEBHOOK_SECRET_BYTES).toString("hex"),
+    webhookSecretSource: GENERATED_SECRET,
   };
 }
 
+/**
+ * The stored source, or `operator` for a row written before the source was
+ * kept: a secret of unknown origin is the workspace's until proven otherwise.
+ */
+function storedSecretSource(stored: string | undefined): WebhookSecretSource {
+  return (
+    WEBHOOK_SECRET_SOURCES.find((source) => source === stored) ??
+    OPERATOR_SECRET
+  );
+}
+
 function toValues(row: MailingSettings): MailingSettingsValues {
   return {
     fallbackLocale: row.fallbackLocale,
@@ -28,6 +47,9 @@ function toValues(row: MailingSettings): MailingSettingsValues {
     senderEmail: row.senderEmail,
     replyTo: row.replyTo,
     webhookSecret: row.webhookSecret,
+    webhookSecretSource: storedSecretSource(row.webhookSecretSource),
+    // SAFETY: json_categories is written only by toRow as the JSON.stringify of categories that categoriesSchema
+    // validated (settingsPatchSchema, applyCategory) or that the module defaults supplied.
     categories: JSON.parse(row.json_categories) as TemplateCategory[],
   };
 }
@@ -71,7 +93,12 @@ export async function getSettings(
   if (existing) return existing;
   const created = defaults();
   if (await insertKeyedSettings(tenantId, created)) return created;
-  return (await findSettings(tenantId)) as MailingSettingsValues;
+  const winner = await findSettings(tenantId);
+  if (!winner)
+    throw new Error(
+      `The settings of tenant "${tenantId}" disappeared before they were read`,
+    );
+  return winner;
 }
 
 export async function saveSettings(
@@ -85,6 +112,22 @@ export async function saveSettings(
   return values;
 }
 
+/**
+ * Writes the webhook secret and its source alone, so a concurrent writer of
+ * the other settings keeps its fields. The tenant's row must exist: read it
+ * with `getSettings` first.
+ */
+export async function saveWebhookSecret(
+  tenantId: string,
+  webhookSecret: string,
+  webhookSecretSource: WebhookSecretSource,
+): Promise<void> {
+  await GetModel(SettingsModel, tenantId).update(tenantId, {
+    webhookSecret,
+    webhookSecretSource,
+  });
+}
+
 export function findCategory(
   categories: TemplateCategory[],
   id: string,
@@ -105,36 +148,32 @@ export function missingVariablesPolicy(
 }
 
 /** The form-only field folded back into `blockOnMissingVariables`. */
-const MISSING_VARIABLES_KEY = "missingVariables";
 const CLEARED_VALUE = "";
 /** The patch with each cleared field (`null`) as the empty value it stores. */
-export function clearedToEmpty(
-  patch: Record<string, unknown>,
-): Record<string, unknown> {
+export function clearedToEmpty(patch: JsonObject): JsonObject {
   return Object.fromEntries(
     Object.entries(patch).map(([key, value]) => [key, value ?? CLEARED_VALUE]),
   );
 }
 
 /**
- * The settings once `patch` (the fields a form changed, `null` for a cleared
- * one) is laid over the stored ones, the missing-variables choice folded back
- * into its boolean.
+ * The settings once `patch` (the fields a form changed, cleared ones already
+ * stored as empty) is laid over the stored ones, the missing-variables choice
+ * folded back into its boolean. A secret the patch changes becomes the
+ * workspace owner's.
  */
 export function mergeSettingsPatch(
   current: MailingSettingsValues,
-  patch: Record<string, unknown>,
+  patch: SettingsPatch,
 ): MailingSettingsValues {
-  const written = Object.fromEntries(
-    Object.entries(clearedToEmpty(patch)).filter(
-      ([key]) => key !== MISSING_VARIABLES_KEY,
-    ),
-  );
-  const policy = patch.missingVariables;
+  const { missingVariables: policy, ...written } = patch;
   const isChoice = policy === REFUSE_POLICY || policy === SEND_POLICY;
   const guard =
     isChoice && !("blockOnMissingVariables" in patch)
       ? { blockOnMissingVariables: policy === REFUSE_POLICY }
       : {};
-  return { ...current, ...written, ...guard } as MailingSettingsValues;
+  const merged = { ...current, ...written, ...guard };
+  return merged.webhookSecret === current.webhookSecret
+    ? merged
+    : { ...merged, webhookSecretSource: OPERATOR_SECRET };
 }

package/src/services/starters.ts

@@ -5,6 +5,7 @@ import type {
   TemplateContent,
   VariableDefinition,
 } from "../types";
+import type { JsonObject } from "../types/json";
 import { footerForCategory, formattingLocale } from "../engine";
 import { blankFields, footerBlock } from "./templates";
 
@@ -21,9 +22,9 @@ export interface StarterTemplate {
   content: TemplateContent;
   variables: VariableDefinition[];
   /** The test data as an English-speaking workspace gets it. */
-  testData: Record<string, unknown>;
+  testData: JsonObject;
   /** The test data with its amounts written the way `locale` writes them. */
-  testDataFor: (locale: string) => Record<string, unknown>;
+  testDataFor: (locale: string) => JsonObject;
 }
 
 type StarterSource = Omit<StarterTemplate, "testData">;
@@ -39,9 +40,12 @@ const ORDER_LINE_NAMES = new Map([
 const LOCALE_PARTS = /[-_]/;
 
 /** A test text in the language of `locale`, English when it has none. */
-function inLanguageOf(texts: ReadonlyMap<string, string>, locale: string) {
+function inLanguageOf(
+  texts: ReadonlyMap<string, string>,
+  locale: string,
+): string {
   const language = locale.toLowerCase().split(LOCALE_PARTS)[0] ?? "";
-  return texts.get(language) ?? texts.get(DEFAULT_TEST_DATA_LOCALE);
+  return texts.get(language) ?? texts.get(DEFAULT_TEST_DATA_LOCALE) ?? "";
 }
 
 /** An amount the way `locale` writes it: "€1,556.00", "1 556,00 €". */

package/src/services/templates.ts

@@ -27,6 +27,7 @@ import type {
   VariableDefinition,
 } from "../types";
 import { DEFAULT_FALLBACK_LOCALE } from "../types";
+import type { JsonObject } from "../types/json";
 
 export interface TemplateAuthor {
   name?: string;
@@ -73,6 +74,7 @@ export async function refuseTakenSlug<T>(write: Promise<T>): Promise<T> {
 
 /** The content customers receive: the last published version. */
 export function parseContent(template: MailingTemplate): TemplateContent {
+  // SAFETY: json_content is written only as JSON.stringify of a TemplateContent that saveContentSchema validated or the module built.
   return JSON.parse(template.json_content || EMPTY_CONTENT) as TemplateContent;
 }
 
@@ -83,6 +85,7 @@ export function hasDraft(template: MailingTemplate): boolean {
 /** The content the editor works on: the draft, or the published content. */
 export function workingContent(template: MailingTemplate): TemplateContent {
   if (!template.json_draft) return parseContent(template);
+  // SAFETY: json_draft is written only as JSON.stringify of a TemplateContent that saveContentSchema validated or the module built.
   return JSON.parse(template.json_draft) as TemplateContent;
 }
 
@@ -102,6 +105,7 @@ export function isPublished(template: MailingTemplate): boolean {
 export function parseVariables(
   template: MailingTemplate,
 ): VariableDefinition[] {
+  // SAFETY: json_variables is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
   return JSON.parse(template.json_variables) as VariableDefinition[];
 }
 
@@ -114,6 +118,7 @@ export function workingVariables(
 ): VariableDefinition[] {
   if (!hasDraft(template) || !template.json_variables_draft)
     return parseVariables(template);
+  // SAFETY: json_variables_draft is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
   return JSON.parse(template.json_variables_draft) as VariableDefinition[];
 }
 
@@ -169,10 +174,9 @@ export function pendingChanges(template: MailingTemplate): TemplateChange[] {
   });
 }
 
-export function parseTestData(
-  template: MailingTemplate,
-): Record<string, unknown> {
-  return JSON.parse(template.json_test_data) as Record<string, unknown>;
+export function parseTestData(template: MailingTemplate): JsonObject {
+  // SAFETY: json_test_data is written only as JSON.stringify of an object that its route or declaration schema validated, or the module built.
+  return JSON.parse(template.json_test_data) as JsonObject;
 }
 
 interface FooterLabels {
@@ -190,16 +194,16 @@ const ENGLISH_FOOTER_LABELS: FooterLabels = {
  * e-mail without an unsubscribe link is a legal problem, so a blank template
  * ships a footer — and nothing else: no invented subject, prose or address.
  */
-const FOOTER_LABELS: Record<string, FooterLabels> = {
-  en: ENGLISH_FOOTER_LABELS,
-  fr: { unsubscribe: "Se désinscrire", preferences: "Préférences" },
-};
+const FOOTER_LABELS = new Map<string, FooterLabels>([
+  ["en", ENGLISH_FOOTER_LABELS],
+  ["fr", { unsubscribe: "Se désinscrire", preferences: "Préférences" }],
+]);
 
 const FOOTER_BLOCK_ID = "footer";
 
 /** A footer in `locale`: its legal line and the labels of its two links. */
 export function footerBlock(locale: string, text = ""): Block {
-  const labels = FOOTER_LABELS[locale] ?? ENGLISH_FOOTER_LABELS;
+  const labels = FOOTER_LABELS.get(locale) ?? ENGLISH_FOOTER_LABELS;
   return {
     id: FOOTER_BLOCK_ID,
     type: "footer",
@@ -293,6 +297,7 @@ export async function discardDraft(
 export function parseVersionChanges(
   row: MailingTemplateVersion,
 ): TemplateChange[] {
+  // SAFETY: json_changes is written only as JSON.stringify of the TemplateChange[] from diffContents and diffVariables.
   return JSON.parse(row.json_changes) as TemplateChange[];
 }
 
@@ -300,6 +305,7 @@ export function parseVersionChanges(
 export function parseVersionVariables(
   row: MailingTemplateVersion,
 ): VariableDefinition[] {
+  // SAFETY: a version row's json_variables is written only as JSON.stringify of a VariableDefinition[] that variableListSchema validated or the module built.
   return JSON.parse(row.json_variables) as VariableDefinition[];
 }
 
@@ -455,6 +461,7 @@ export async function contentOfVersion(
 export function parseVersionContent(
   row: MailingTemplateVersion,
 ): TemplateContent {
+  // SAFETY: a version row's json_content is written only as JSON.stringify of a TemplateContent that saveContentSchema validated.
   return JSON.parse(row.json_content) as TemplateContent;
 }