@antelopejs/dms-mailing 0.8.0 → 0.9.0

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.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

@@ -6,6 +6,8 @@ import {
   type MailingSettingsValues,
   type TemplateCategory,
 } from "../types";
+import type { JsonObject } from "../types/json";
+import type { SettingsPatch } from "../validation/settings.schema";
 
 export const WEBHOOK_SECRET_BYTES = 24;
 
@@ -28,6 +30,8 @@ function toValues(row: MailingSettings): MailingSettingsValues {
     senderEmail: row.senderEmail,
     replyTo: row.replyTo,
     webhookSecret: row.webhookSecret,
+    // 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 +75,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(
@@ -105,36 +114,28 @@ 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.
  */
 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;
+  return { ...current, ...written, ...guard };
 }

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;
 }
 

package/src/services/webhook-status.ts

@@ -7,6 +7,7 @@ import type {
   WebhookRefusal,
   WebhookStatus,
 } from "../types";
+import { isObject, isText } from "../validation/guards";
 import { webhookSecretMatches } from "./events";
 import { WEBHOOK_SECRET_HEADER } from "../constants";
 
@@ -28,11 +29,11 @@ export const WEBHOOK_REFUSAL_MESSAGES: Record<WebhookRefusal, string> = {
 };
 
 /** The body of a refused webhook call. */
-export interface WebhookRefusalBody {
+export type WebhookRefusalBody = {
   error: "webhook_refused";
   reason: WebhookRefusal;
   message: string;
-}
+};
 
 /** What "Send a test event" found when it called the webhook URL. */
 export interface WebhookTestOutcome {
@@ -143,15 +144,13 @@ export async function readWebhookStatus(
   );
 }
 
-const describeError = (error: unknown): string =>
-  error instanceof Error
-    ? String((error.cause as Error | undefined)?.message ?? error.message)
-    : String(error);
-
 async function refusalOf(
   response: Response,
 ): Promise<WebhookRefusal | undefined> {
   try {
+    // SAFETY: Response.json() answers any, and the URL under test is this module's own webhook route, which refuses
+    // with refusalBody(reason); another endpoint can answer any JSON, which is read the same way, and a non-object
+    // reads as no refusal (only null throws, into the catch below).
     const body = (await response.json()) as Partial<WebhookRefusalBody>;
     return body.reason;
   } catch {
@@ -192,11 +191,17 @@ export async function sendWebhookTest(
       refusal: response.ok ? undefined : await refusalOf(response),
     };
   } catch (error) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const causeMessage =
+      isObject(cause) && isText(cause.message) ? cause.message : undefined;
     return {
       isReceived: false,
       url,
       durationMs: elapsed(),
-      networkError: describeError(error),
+      networkError:
+        error instanceof Error
+          ? (causeMessage ?? error.message)
+          : String(error),
     };
   }
 }

package/src/types/json.ts

@@ -0,0 +1 @@
+export type { JsonObject, JsonValue } from "@antelopejs/interface-dms-mailing";

package/src/types/settings.ts

@@ -1,11 +1,11 @@
 import type { LocalizedText } from "@antelopejs/interface-dms-mailing";
 
 /** A template category as stored: its label written once per language. */
-export interface TemplateCategory {
+export type TemplateCategory = {
   id: string;
   label: LocalizedText;
   icon: string;
-}
+};
 
 /** A template category as one reader sees it: the label in their language. */
 export interface CategoryInLocale {

package/src/validation/declarations.schema.ts

@@ -8,6 +8,7 @@ import {
   templateContentSchema,
   variableListSchema,
 } from "./templates.schema";
+import { jsonObjectSchema } from "./json.schema";
 
 const MAX_AUTHOR_LENGTH = MAX_NAME_LENGTH;
 const MAX_IMPORT_ID_LENGTH = 200;
@@ -36,7 +37,7 @@ export const templateDeclarationSchema = z.object({
   category: z.string().trim().default(""),
   content: templateContentSchema,
   variables: variableListSchema.default([]),
-  testData: z.record(z.unknown()).default({}),
+  testData: jsonObjectSchema.default({}),
   author: z.string().trim().min(1).max(MAX_AUTHOR_LENGTH).optional(),
 });
 
@@ -78,7 +79,7 @@ const recipientSchema = z.union([
 const importedEventSchema = z.object({
   type: sendEventTypeSchema,
   at: z.coerce.date(),
-  details: z.record(z.unknown()).optional(),
+  details: jsonObjectSchema.optional(),
 });
 
 const importedSendSchema = z.object({
@@ -87,7 +88,7 @@ const importedSendSchema = z.object({
   to: recipientSchema,
   sentAt: z.coerce.date(),
   locale: z.string().trim().min(1).optional(),
-  variables: z.record(z.unknown()).default({}),
+  variables: jsonObjectSchema.default({}),
   provider: z.string().optional(),
   providerMessageId: z.string().optional(),
   source: z.string().optional(),

package/src/validation/guards.ts

@@ -3,14 +3,6 @@ export function isText(value: unknown): value is string {
   return typeof value === "string";
 }
 
-/**
- * Whether `value` is a JSON object as a parsed body holds one: an object,
- * neither `null` nor an array. Its values are not checked.
- */
-export function isJsonObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Whether `value` is an object, arrays included, and not `null`: reading any
  * key of it yields a value of unknown type.

package/src/validation/json.schema.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { isJsonObject } from "./json";
+
+/** A JSON object whose every value is JSON data, such as a request body carries. */
+export const jsonObjectSchema = z
+  .unknown()
+  .refine(isJsonObject, "expected a JSON object");

package/src/validation/json.ts

@@ -0,0 +1,66 @@
+import type { JsonObject, JsonValue } from "../types/json";
+import { isNumber, isObject, isText } from "./guards";
+
+/** A step of the walk in {@link isJsonValue}: visit a node, or leave one. */
+type JsonWalkStep = { visit: unknown } | { leave: object };
+
+/**
+ * Whether `value` is wholly JSON data: strings, numbers, booleans, null, and
+ * arrays and plain objects of the same, none of them reached through itself.
+ * Walked with a stack, so a deeply nested value cannot overflow it.
+ */
+export function isJsonValue(value: unknown): value is JsonValue {
+  const stack: JsonWalkStep[] = [{ visit: value }];
+  const ancestors = new Set<object>();
+  for (let step = stack.pop(); step; step = stack.pop()) {
+    if ("leave" in step) {
+      ancestors.delete(step.leave);
+      continue;
+    }
+    const item = step.visit;
+    if (
+      item === null ||
+      isText(item) ||
+      isNumber(item) ||
+      typeof item === "boolean"
+    )
+      continue;
+    if (typeof item !== "object" || ancestors.has(item)) return false;
+    const prototype: unknown = Object.getPrototypeOf(item);
+    if (
+      !Array.isArray(item) &&
+      prototype !== Object.prototype &&
+      prototype !== null
+    )
+      return false;
+    ancestors.add(item);
+    stack.push({ leave: item });
+    for (const child of Object.values(item)) stack.push({ visit: child });
+  }
+  return true;
+}
+
+/** Whether `value` is wholly JSON data and an object: neither `null` nor an array. */
+export function isJsonObject(value: unknown): value is JsonObject {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    isJsonValue(value)
+  );
+}
+
+/** `text` parsed as JSON; a `SyntaxError` when it is not. */
+export function parseJson(text: string): JsonValue {
+  const parsed: unknown = JSON.parse(text);
+  if (!isJsonValue(parsed)) throw new TypeError("expected JSON data");
+  return parsed;
+}
+
+/** `text` parsed as a JSON object. */
+export function parseJsonObject(text: string): JsonObject {
+  const parsed = parseJson(text);
+  if (!isObject(parsed) || Array.isArray(parsed))
+    throw new TypeError("expected a JSON object");
+  return parsed;
+}

package/src/validation/templates.schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { MAX_NAME_LENGTH, MAX_SLUG_LENGTH, SLUG_PATTERN } from "../constants";
 import type { Block } from "../types";
+import { jsonObjectSchema } from "./json.schema";
 
 const MIN_HEADING_SIZE = 12;
 const MAX_HEADING_SIZE = 48;
@@ -149,7 +150,7 @@ export const saveContentSchema = z.object({
   revision: draftRevisionSchema,
 });
 
-export const testDataSchema = z.object({ data: z.record(z.unknown()) });
+export const testDataSchema = z.object({ data: jsonObjectSchema });
 
 /**
  * Which content a preview renders when it carries none: the working draft
@@ -166,7 +167,7 @@ export const previewSchema = z.object({
   locale: z.string().min(1).optional(),
   version: previewVersionSchema.optional(),
   content: templateContentSchema.optional(),
-  data: z.record(z.unknown()).optional(),
+  data: jsonObjectSchema.optional(),
 });
 
 /**
@@ -176,7 +177,7 @@ export const previewSchema = z.object({
 export const realSendSchema = z.object({
   to: z.array(z.string().email()).min(1).max(MAX_TEST_RECIPIENT_COUNT),
   locale: z.string().min(1).optional(),
-  data: z.record(z.unknown()).optional(),
+  data: jsonObjectSchema.optional(),
 });
 
 export const testSendSchema = previewSchema.extend({
@@ -193,6 +194,9 @@ export const templateDetailsSchema = z.object({
   category: z.string().nullable().optional(),
 });
 
+/** The details a template's drawer or the editor saves, validated. */
+export type TemplateDetails = z.infer<typeof templateDetailsSchema>;
+
 export const duplicateSchema = z.object({
   slug: slugSchema,
   name: z.string().trim().min(1).max(MAX_NAME_LENGTH),