@antelopejs/dms-mailing 0.8.0 → 0.9.1

package/src/automation/send-template-action.ts

@@ -3,7 +3,10 @@ import type {
   JsonSchema,
 } from "@antelopejs/interface-dms-automation";
 import type { EmailAddress } from "@antelopejs/interface-email";
-import type { SendTemplateResult } from "@antelopejs/interface-dms-mailing";
+import type {
+  SendTemplateResult,
+  TemplateVariables,
+} from "@antelopejs/interface-dms-mailing";
 import { sendUnlessSuppressed } from "../services/checked-send";
 import { SEND_STATUSES } from "../types";
 
@@ -12,7 +15,7 @@ export interface SendTemplateActionInput {
   slug: string;
   to: EmailAddress | EmailAddress[];
   locale?: string;
-  variables?: Record<string, unknown>;
+  variables?: TemplateVariables;
   source?: string;
 }
 
@@ -42,12 +45,12 @@ const INPUT_SCHEMA: JsonSchema = {
   required: ["tenantId", "slug", "to"],
 };
 
-const RESULT_PROPERTIES: JsonSchema = {
+const RESULT_PROPERTIES = {
   sendId: { type: "string" },
   status: { type: "string", enum: SEND_STATUSES },
   messageId: { type: "string" },
   error: { type: "string" },
-};
+} satisfies { [name: string]: JsonSchema };
 
 const OUTPUT_SCHEMA: JsonSchema = {
   type: "object",
@@ -61,12 +64,21 @@ const OUTPUT_SCHEMA: JsonSchema = {
   },
 };
 
-const failedRecipients = (result: SendTemplateResult): SendTemplateResult[] =>
+/** What the action hands the graph: the send's result, as JSON. */
+type SendTemplateOutput = {
+  sendId: string;
+  status: SendTemplateResult["status"];
+  messageId?: string;
+  error?: string;
+  results?: SendTemplateOutput[];
+};
+
+const failedRecipients = (result: SendTemplateOutput): SendTemplateOutput[] =>
   (result.results ?? [result]).filter((entry) => entry.status === "failed");
 
 export const sendTemplateAction: ActionType<
   SendTemplateActionInput,
-  SendTemplateResult
+  SendTemplateOutput
 > = {
   id: SEND_TEMPLATE_ACTION_ID,
   name: "Send e-mail template",
@@ -78,13 +90,16 @@ export const sendTemplateAction: ActionType<
     const source =
       input.source ?? `${AUTOMATION_SOURCE_PREFIX}${ctx.procedureId}`;
     try {
-      const result = await sendUnlessSuppressed(input.slug, {
-        tenantId: input.tenantId,
-        to: input.to,
-        locale: input.locale,
-        variables: input.variables,
-        source,
-      });
+      const result: SendTemplateOutput = await sendUnlessSuppressed(
+        input.slug,
+        {
+          tenantId: input.tenantId,
+          to: input.to,
+          locale: input.locale,
+          variables: input.variables,
+          source,
+        },
+      );
       const failures = failedRecipients(result);
       if (failures.length > 0) {
         ctx.log(
@@ -95,7 +110,11 @@ export const sendTemplateAction: ActionType<
       }
       return result;
     } catch (error) {
-      ctx.log("error", `Template "${input.slug}" could not be sent`, error);
+      ctx.log(
+        "error",
+        `Template "${input.slug}" could not be sent`,
+        error instanceof Error ? error.message : String(error),
+      );
       throw error;
     }
   },

package/src/data/body.ts

@@ -1,14 +1,17 @@
 import { HTTPResult } from "@antelopejs/interface-api";
 import { HTTP_BAD_REQUEST } from "../constants";
+import type { JsonValue } from "../types/json";
 import { isText } from "../validation/guards";
+import { parseJson } from "../validation/json";
 
 const INVALID_BODY = "$dms_mailing.errors.invalid_body";
 
-export function parseBody(body: Buffer | string): Record<string, unknown> {
+/** The JSON a request body carries, `{}` for an empty one; 400 when it is not JSON. */
+export function parseBody(body: Buffer | string): JsonValue {
   const raw = isText(body) ? body : body.toString("utf8");
   if (!raw) return {};
   try {
-    return JSON.parse(raw) as Record<string, unknown>;
+    return parseJson(raw);
   } catch {
     throw new HTTPResult(HTTP_BAD_REQUEST, INVALID_BODY);
   }

package/src/data/templates-table.ts

@@ -4,13 +4,17 @@ import {
   Parameter,
   type RequestContext,
 } from "@antelopejs/interface-api";
-import { assertValidation } from "@antelopejs/interface-api-util";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import { z } from "zod";
 import {
   DataController,
   type DataControllerCallback,
   RegisterDataController,
 } from "@antelopejs/interface-data-api";
-import type { Validation } from "@antelopejs/interface-data-api/components";
+import type {
+  Parameters,
+  Validation,
+} from "@antelopejs/interface-data-api/components";
 import {
   Access,
   AccessMode,
@@ -79,19 +83,23 @@ import {
   refuseTakenSlug,
 } from "../services/templates";
 import type { TemplateCategory } from "../types";
+import type { JsonObject } from "../types/json";
 
 import {
   createTemplateSchema,
-  templateDetailsSchema,
+  type TemplateDetails,
 } from "../validation/templates.schema";
 import { isObject, isText } from "../validation/guards";
+import { isJsonObject } from "../validation/json";
 import { parseBody } from "./body";
 import { CategoryDisplay, LocaleChipsDisplay } from "./displays";
 
 const SLUG_IMMUTABLE = "$dms_mailing.errors.slug_immutable";
 const SOURCE_NOT_FOUND = "$dms_mailing.errors.template_not_found";
 const STARTER_NOT_FOUND = "$dms_mailing.errors.starter_not_found";
-const INVALID_TEMPLATE = "$dms_mailing.errors.invalid_template";
+export type { TemplateDetails };
+
+export const INVALID_TEMPLATE = "$dms_mailing.errors.invalid_template";
 const UNKNOWN_CATEGORY = "$dms_mailing.errors.unknown_category";
 const TEMPLATE_IN_USE = "$dms_mailing.errors.template_in_use";
 const TEMPLATE_WAS_SENT = "$dms_mailing.errors.template_was_sent";
@@ -147,25 +155,23 @@ async function seedFields(
   return starterFields(starter, fallbackLocale);
 }
 
-const isBlank = (value: unknown) =>
-  value === undefined || value === null || value === "";
-
 /** A category is left empty or picked among the ones the settings declare. */
 function assertKnownCategory(
   categories: TemplateCategory[],
-  category: unknown,
+  category: string | undefined,
 ): void {
-  if (isBlank(category)) return;
-  if (isText(category) && findCategory(categories, category)) {
-    return;
-  }
+  if (!category || findCategory(categories, category)) return;
   throw new HTTPResult(HTTP_UNPROCESSABLE, UNKNOWN_CATEGORY);
 }
 
-/** The row `new` answers since interface-data-api 0.3: its key and fields. */
-interface CreatedRow {
-  _id: string;
-  [field: string]: unknown;
+/** The key of the row `new` answers since interface-data-api 0.3. */
+const createdRowSchema = z.object({ _id: z.string() });
+
+/** The JSON object a creation sends; 400 for any other JSON. */
+function parseCreationBody(body: Buffer): JsonObject {
+  const parsed = parseBody(body);
+  assert(isJsonObject(parsed), HTTP_BAD_REQUEST, INVALID_TEMPLATE);
+  return parsed;
 }
 
 /**
@@ -176,7 +182,7 @@ interface CreatedRow {
  * object: interface-data-api 0.3 refuses a JSON string.
  */
 function parseCreation(body: Validation.WrittenBody, locale: string) {
-  const raw = Buffer.isBuffer(body) ? parseBody(body) : body;
+  const raw = Buffer.isBuffer(body) ? parseCreationBody(body) : body;
   const seed = assertValidation(
     raw,
     (value) => createTemplateSchema.parse(value),
@@ -191,11 +197,6 @@ function parseCreation(body: Validation.WrittenBody, locale: string) {
   return { seed, normalized };
 }
 
-/** What the data API locks a localized field with: the controller's key. */
-interface LocalizedController {
-  language: string;
-}
-
 /** The key that writes every language of a localized field at once. */
 const ALL_LANGUAGES = "*";
 
@@ -209,9 +210,9 @@ function withSeeding(base: DataControllerCallback): DataControllerCallback {
   return {
     ...base,
     func: async function (
-      this: unknown,
+      this: TemplatesTableAPI,
       ctx: RequestContext,
-      params: unknown,
+      params: Parameters.NewParameters,
       body: Validation.WrittenBody,
       ...rest: unknown[]
     ) {
@@ -220,11 +221,11 @@ function withSeeding(base: DataControllerCallback): DataControllerCallback {
       const settings = await getSettings(tenantId);
       assertKnownCategory(settings.categories, seed.category);
       const fields = await seedFields(tenantId, seed, settings.fallbackLocale);
-      (this as LocalizedController).language = ALL_LANGUAGES;
-      const created = (await refuseTakenSlug(
-        base.func.call(this, ctx, params, normalized, ...rest),
-      )) as CreatedRow;
-      const templateId = created._id;
+      this.language = ALL_LANGUAGES;
+      const created: unknown = await refuseTakenSlug(
+        Promise.resolve(base.func.call(this, ctx, params, normalized, ...rest)),
+      );
+      const templateId = createdRowSchema.parse(created)._id;
       const user = await authenticateTenantRequest(ctx);
       await initializeTemplate(tenantId, templateId, displayName(user), fields);
       return created;
@@ -301,10 +302,17 @@ export async function assertEditable(
 ): Promise<void> {
   if (body.slug !== undefined && body.slug !== current.slug)
     throw new HTTPResult(HTTP_CONFLICT, SLUG_IMMUTABLE);
-  if (body.name !== undefined && isBlankName(body.name))
-    throw new HTTPResult(HTTP_BAD_REQUEST, BLANK_NAME);
+  if (body.name !== undefined) {
+    const texts = isObject(body.name) ? Object.values(body.name) : [body.name];
+    if (!texts.some((text) => isText(text) && text.trim()))
+      throw new HTTPResult(HTTP_BAD_REQUEST, BLANK_NAME);
+  }
   const { categories } = await getSettings(tenantId);
-  assertKnownCategory(categories, body.category);
+  const { category } = body;
+  if (category === undefined || category === null || category === "") return;
+  if (!isText(category))
+    throw new HTTPResult(HTTP_UNPROCESSABLE, UNKNOWN_CATEGORY);
+  assertKnownCategory(categories, category);
 }
 
 /**
@@ -314,14 +322,9 @@ export async function assertEditable(
 export async function saveDetails(
   ctx: RequestContext,
   template: MailingTemplate,
-  body: unknown,
+  details: TemplateDetails,
   author: string,
 ): Promise<void> {
-  const details = assertValidation(
-    body,
-    (value) => templateDetailsSchema.parse(value),
-    () => INVALID_TEMPLATE,
-  );
   const tenantId = getRequestTenantId(ctx);
   await assertEditable(tenantId, details, template);
   const names = TemplateModel.namesOf(template);
@@ -334,15 +337,6 @@ export async function saveDetails(
   });
 }
 
-/**
- * Whether an edited name holds no text: the text of the reader's language,
- * or, from a form editing every language, all of them.
- */
-function isBlankName(name: unknown): boolean {
-  const texts = isObject(name) ? Object.values(name) : [name];
-  return !texts.some((text) => isText(text) && text.trim());
-}
-
 /** The names trimmed, blank ones left out, the fallback language filled. */
 function tidyNames(names: LocalizedText, locale: string): LocalizedText {
   const tidy = Object.fromEntries(
@@ -362,10 +356,8 @@ function tidyNames(names: LocalizedText, locale: string): LocalizedText {
 export function afterEdit(
   model: TemplateModel,
   id: string,
-  name: unknown,
   locale: string,
-): AfterWrite | undefined {
-  if (name === undefined) return undefined;
+): AfterWrite {
   return async () => {
     const template = await model.get(id);
     if (!template) return;
@@ -377,8 +369,10 @@ export function afterEdit(
 }
 
 /** The templates the attention refresh flagged. */
-const isFlagged: FilterFunction<Record<string, unknown>> = (_context, proxy) =>
-  proxy.default(false).eq(true);
+const isFlagged: FilterFunction<TemplatesTableAPI, TemplatesTableAPI> = (
+  _context,
+  proxy,
+) => proxy.default(false).eq(true);
 
 const templateRoutes = {
   ...TableViewRoutes.All,

package/src/data-types/categories-type.ts

@@ -12,8 +12,8 @@ import { categoriesSchema } from "../validation/settings.schema";
  */
 @RegisterDataType(TEMPLATE_CATEGORIES_TYPE_ID)
 export class TemplateCategoriesType extends DataType {
-  constructor(public readonly options: Record<string, unknown> = {}) {
-    super([], undefined, options);
+  constructor() {
+    super([], undefined, {});
   }
 
   protected defaultInputComponent() {

package/src/data-types/category-type.ts

@@ -19,7 +19,7 @@ import { TEMPLATE_CATEGORY_TYPE_ID } from "../constants";
  */
 @RegisterDataType(TEMPLATE_CATEGORY_TYPE_ID)
 export class TemplateCategoryType extends DataType {
-  constructor(public readonly options: Record<string, unknown> = {}) {
+  constructor() {
     super(
       [
         DefaultDataCompareTypes.Is,
@@ -28,7 +28,7 @@ export class TemplateCategoryType extends DataType {
         DefaultDataCompareTypes.IsNotEmpty,
       ],
       DefaultDataCompareTypes.Is,
-      options,
+      {},
     );
   }
 

package/src/db/models/sends.model.ts

@@ -123,7 +123,7 @@ export class SendModel extends BasicDataModel(
       .filter((row) => row.key("createdAt").ge(from))
       .filter((row) => row.key("createdAt").lt(to))
       .without("json_variables")
-      .run() as Promise<SendSummary[]>;
+      .run();
   }
 
   listOlderThan(limit: Date, pageSize: number): Promise<MailingSend[]> {
@@ -260,7 +260,7 @@ export class SendModel extends BasicDataModel(
       .getAll(templateSlug, "templateSlug")
       .filter((row) => row.key("createdAt").ge(from))
       .without("json_variables")
-      .run() as Promise<SendSummary[]>;
+      .run();
   }
 
   /** How many sends the retention would delete with this cutoff. */

package/src/db/models/template-versions.model.ts

@@ -11,6 +11,8 @@ export function committedVersionOf(
   template: Pick<MailingTemplate, "json_published_version">,
 ): MailingTemplateVersion | undefined {
   if (!template.json_published_version) return undefined;
+  // SAFETY: json_published_version is written only by publishSnapshot and publishedAtCreation as the
+  // JSON.stringify of the version row they insert; its publishedAt reads back as a string, and the next line restores the Date.
   const row = JSON.parse(
     template.json_published_version,
   ) as MailingTemplateVersion;
@@ -33,12 +35,12 @@ export class TemplateVersionModel extends BasicDataModel(
       await this.insert(version);
     } catch (error) {
       const stored = await this.get(version._id);
+      if (!stored) throw error;
+      const storedFields = new Map(Object.entries(stored));
       if (
-        !stored ||
         Object.entries(version).some(
           ([key, value]) =>
-            JSON.stringify(stored[key as keyof MailingTemplateVersion]) !==
-            JSON.stringify(value),
+            JSON.stringify(storedFields.get(key)) !== JSON.stringify(value),
         )
       )
         throw error;

package/src/db/tables/settings.table.ts

@@ -46,4 +46,8 @@ export class MailingSettings extends Table {
 
   @Field("string")
   declare webhookSecret: string;
+
+  /** Who set `webhookSecret`; absent on rows written before it was kept. */
+  @Field("string")
+  declare webhookSecretSource?: string;
 }

package/src/db/tables/templates.table.ts

@@ -156,7 +156,7 @@ export class MailingTemplate extends Table.with(LocalizationModifier) {
 
 /** Covers model updates and generated data-api edits in the same database write. */
 class TemplateRevisionModifier extends Modifier {
-  update(object: Record<string, unknown>, field: string): void {
+  update(object: Pick<MailingTemplate, "revision">, field: "revision"): void {
     object[field] = randomUUID();
   }
 }

package/src/engine/changes.ts

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import type {
   Block,
   BlockType,
@@ -6,7 +7,6 @@ import type {
   VariableDefinition,
 } from "../types";
 import { walkBlocks } from "./walk";
-import { isObject } from "../validation/guards";
 
 export type TemplateChangeKind =
   | "locale_added"
@@ -41,36 +41,21 @@ export const CONTRACT_LOCALE = "";
 
 interface BlockSnapshot {
   type: BlockType;
-  signature: string;
+  fields: object;
 }
 
 const NESTED_KEYS = new Set(["children", "elseChildren"]);
 
-/**
- * A value with its object keys sorted at every depth, so two blocks equal but
- * for the order their fields were written in read the same.
- */
-function canonical(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(canonical);
-  if (!isObject(value)) return value;
+function ownFields(block: Block): object {
   return Object.fromEntries(
-    Object.keys(value)
-      .sort()
-      .map((key) => [key, canonical(value[key])]),
-  );
-}
-
-function ownFields(block: Block): string {
-  const entries = Object.entries(block).filter(
-    ([key]) => !NESTED_KEYS.has(key),
+    Object.entries(block).filter(([key]) => !NESTED_KEYS.has(key)),
   );
-  return JSON.stringify(canonical(Object.fromEntries(entries)));
 }
 
 function snapshotBlocks(blocks: Block[]): Map<string, BlockSnapshot> {
   const snapshots = new Map<string, BlockSnapshot>();
   walkBlocks(blocks, (block) => {
-    snapshots.set(block.id, { type: block.type, signature: ownFields(block) });
+    snapshots.set(block.id, { type: block.type, fields: ownFields(block) });
   });
   return snapshots;
 }
@@ -94,7 +79,7 @@ function blockChanges(
   const touched = [...after].flatMap(([id, snapshot]) => {
     const previous = before.get(id);
     if (!previous) return [blockChange(locale, "block_added", id, snapshot)];
-    if (previous.signature === snapshot.signature) return [];
+    if (isDeepStrictEqual(previous.fields, snapshot.fields)) return [];
     return [blockChange(locale, "block_changed", id, snapshot)];
   });
   return [...touched, ...removed];
@@ -162,13 +147,8 @@ export function diffContents(
 
 function declarationsByPath(
   variables: VariableDefinition[],
-): Map<string, string> {
-  return new Map(
-    variables.map((variable) => [
-      variable.path,
-      JSON.stringify(canonical(variable)),
-    ]),
-  );
+): Map<string, VariableDefinition> {
+  return new Map(variables.map((variable) => [variable.path, variable]));
 }
 
 function variableChange(
@@ -194,6 +174,8 @@ export function diffVariables(
     const next = after.get(path);
     if (previous === undefined) return [variableChange("variable_added", path)];
     if (next === undefined) return [variableChange("variable_removed", path)];
-    return previous === next ? [] : [variableChange("variable_changed", path)];
+    return isDeepStrictEqual(previous, next)
+      ? []
+      : [variableChange("variable_changed", path)];
   });
 }

package/src/engine/conditions.ts

@@ -1,13 +1,21 @@
+import type {
+  TemplateVariables,
+  TemplateVariableValue,
+} from "@antelopejs/interface-dms-mailing";
 import type { Condition, ConditionOperator } from "../types";
+import { plainText } from "./formats";
 import { getPath } from "./paths";
 
-type Evaluator = (actual: unknown, expected: string) => boolean;
+type Evaluator = (
+  actual: TemplateVariableValue | undefined,
+  expected: string,
+) => boolean;
 
 const EVALUATORS: Record<ConditionOperator, Evaluator> = {
   truthy: (actual) => Boolean(actual),
   falsy: (actual) => !actual,
-  eq: (actual, expected) => String(actual) === expected,
-  ne: (actual, expected) => String(actual) !== expected,
+  eq: (actual, expected) => plainText(actual) === expected,
+  ne: (actual, expected) => plainText(actual) !== expected,
   gt: (actual, expected) => Number(actual) > Number(expected),
   lt: (actual, expected) => Number(actual) < Number(expected),
 };
@@ -15,7 +23,7 @@ const EVALUATORS: Record<ConditionOperator, Evaluator> = {
 /** Whether `data` passes the condition a block is shown under. */
 export function evaluateCondition(
   condition: Condition,
-  data: Record<string, unknown>,
+  data: TemplateVariables,
 ): boolean {
   const evaluate = EVALUATORS[condition.operator];
   return evaluate(getPath(data, condition.path), condition.value);

package/src/engine/coverage.ts

@@ -1,3 +1,4 @@
+import type { TemplateVariables } from "@antelopejs/interface-dms-mailing";
 import { SYSTEM_VARIABLE_PATHS } from "../constants";
 import type {
   Block,
@@ -63,7 +64,7 @@ export function collectContentVariablePaths(
 
 export function missingRequiredVariables(
   declared: VariableDefinition[],
-  data: Record<string, unknown>,
+  data: TemplateVariables,
 ): string[] {
   return declared
     .filter((variable) => variable.required)

package/src/engine/formats.ts

@@ -1,16 +1,10 @@
+import type {
+  MoneyValue,
+  TemplateVariableValue,
+} from "@antelopejs/interface-dms-mailing";
 import type { VariableDefinition } from "../types";
-import { isObject, isText } from "../validation/guards";
-
-/**
- * An amount in the minor unit of its currency (cents for `EUR`), like the
- * DMS's composed-text `money` parameter: `{ value: 987420, currency: "EUR" }`
- * reads "€9,874.20" in English, "9 874,20 €" in French.
- */
-export interface MoneyValue {
-  value: number;
-  /** ISO 4217 code. An unknown code writes the amount as a plain number. */
-  currency: string;
-}
+import { isText } from "../validation/guards";
+import { isPresent, isRecord } from "./paths";
 
 /** How a send writes its typed values: its locale, and the paths typed `date`. */
 export interface ValueFormat {
@@ -55,8 +49,10 @@ export function valueFormatOf(
   };
 }
 
-export function isMoneyValue(value: unknown): value is MoneyValue {
-  if (!isObject(value)) return false;
+export function isMoneyValue(
+  value: TemplateVariableValue | undefined,
+): value is MoneyValue {
+  if (!isRecord(value)) return false;
   return (
     typeof value.value === "number" &&
     Number.isFinite(value.value) &&
@@ -101,6 +97,24 @@ function formatIsoDate(value: string, locale: string): string | null {
     : formatDate(date, options, locale);
 }
 
+/** What `String()` writes for a record, which has no text of its own. */
+const RECORD_TEXT = "[object Object]";
+
+/**
+ * `String(value)` spelled out for each kind a variable can be: a list joins
+ * its items with commas, a missing item writing nothing, and a record writes
+ * {@link RECORD_TEXT}.
+ */
+export function plainText(value: TemplateVariableValue | undefined): string {
+  if (Array.isArray(value))
+    return value
+      .map((item) => (isPresent(item) ? plainText(item) : ""))
+      .join(",");
+  if (value instanceof Date) return value.toString();
+  if (isRecord(value)) return RECORD_TEXT;
+  return String(value);
+}
+
 /**
  * A value as a recipient reads it. A money value and a `Date` format
  * themselves in the send's locale wherever they appear; an ISO string is
@@ -108,7 +122,7 @@ function formatIsoDate(value: string, locale: string): string | null {
  * else, a string already formatted by the caller among them, as given.
  */
 export function formatValue(
-  value: unknown,
+  value: TemplateVariableValue | undefined,
   path = "",
   format?: ValueFormat,
 ): string {
@@ -116,9 +130,9 @@ export function formatValue(
   if (isMoneyValue(value)) return formatMoney(value, locale);
   if (value instanceof Date)
     return Number.isNaN(value.getTime())
-      ? String(value)
+      ? value.toString()
       : formatDate(value, DATE_STYLE, locale);
   if (isText(value) && format?.datePaths.has(path))
     return formatIsoDate(value, locale) ?? value;
-  return String(value);
+  return plainText(value);
 }