@antelopejs/dms-mailing 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "E-mail templates for the AntelopeJS DMS: a block editor with drafts and versions, a send log, delivery metrics and a suppression list.",
   "keywords": [
     "antelopejs",
@@ -46,23 +46,23 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@antelopejs/interface-api": ">=0.3.0 <1.0.0",
-    "@antelopejs/interface-api-util": ">=0.3.0 <1.0.0",
-    "@antelopejs/interface-core": ">=0.4.0 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.6.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.3.0 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.2.0 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.12.0 <1.0.0",
-    "@antelopejs/interface-dms-mailing": ">=0.10.0 <0.11.0",
-    "@antelopejs/interface-email": ">=0.0.6 <1.0.0",
+    "@antelopejs/interface-api": ">=0.3.3 <0.4.0",
+    "@antelopejs/interface-api-util": ">=0.3.2 <0.4.0",
+    "@antelopejs/interface-core": ">=0.5.0 <0.6.0",
+    "@antelopejs/interface-data-api": ">=0.8.0 <0.9.0",
+    "@antelopejs/interface-database": ">=0.4.0 <0.5.0",
+    "@antelopejs/interface-database-decorators": ">=0.5.0 <0.6.0",
+    "@antelopejs/interface-dms": ">=0.14.0 <0.15.0",
+    "@antelopejs/interface-dms-mailing": ">=0.11.0 <0.12.0",
+    "@antelopejs/interface-email": ">=0.2.0 <0.3.0",
     "node-cron": "^4.2.1",
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.21.0",
-    "@antelopejs/dms": ">=0.19.0 <1.0.0",
-    "@antelopejs/mongodb": "^1.6.2",
-    "@antelopejs/tooling-configs": "^0.3.3",
+    "@antelopejs/core": "~1.23.2",
+    "@antelopejs/dms": ">=0.20.0 <0.21.0",
+    "@antelopejs/mongodb": "~1.8.1",
+    "@antelopejs/tooling-configs": ">=0.7.1 <0.8.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10",
     "@types/node": "^24.0.0",
@@ -77,7 +77,7 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "@antelopejs/interface-dms-automation": ">=0.6.0 <1.0.0"
+    "@antelopejs/interface-dms-automation": ">=0.6.0 <0.7.0"
   },
   "antelopeJs": {
     "baseUrl": "dist",
@@ -98,7 +98,7 @@
     "typecheck": "tsc --noEmit",
     "knip": "knip --dependencies",
     "knip:all": "knip",
-    "release": "pnpm --filter @antelopejs/interface-dms-mailing build && pnpm --dir ../.. install --frozen-lockfile && release-it",
+    "release": "pnpm --dir ../.. run typecheck && pnpm --filter @antelopejs/interface-dms-mailing build && pnpm --dir ../.. install --frozen-lockfile && release-it",
     "test": "pnpm run test:backend && pnpm run test:layer",
     "test:backend": "([ -n \"$DMS_PREBUILT\" ] || pnpm run build) && ajs module test .",
     "test:layer": "cd frontend-vue && pnpm test",

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

@@ -24,8 +24,28 @@ export type ImportedSendRow = Omit<
 
 const MAX_MUTATION_ATTEMPTS = 5;
 
-/** A send as the metrics read it: everything but the rendered variables. */
-export type SendSummary = Omit<MailingSend, "json_variables">;
+const SEND_SUMMARY_FIELDS = [
+  "_id",
+  "createdAt",
+  "templateSlug",
+  "recipientEmail",
+  "status",
+  "stage",
+  "latencyMs",
+  "opens",
+  "clicks",
+  "isTest",
+  "error",
+  "source",
+  "locale",
+  "requestedLocale",
+] as const;
+
+/** A send as the figures read it: only the fields they count. */
+export type SendSummary = Pick<
+  MailingSend,
+  (typeof SEND_SUMMARY_FIELDS)[number]
+>;
 
 type SendActivity = Pick<
   MailingSend,
@@ -122,7 +142,7 @@ export class SendModel extends BasicDataModel(
     return this.table
       .filter((row) => row.key("createdAt").ge(from))
       .filter((row) => row.key("createdAt").lt(to))
-      .without("json_variables")
+      .pluck(...SEND_SUMMARY_FIELDS)
       .run();
   }
 
@@ -259,7 +279,7 @@ export class SendModel extends BasicDataModel(
     return this.table
       .getAll(templateSlug, "templateSlug")
       .filter((row) => row.key("createdAt").ge(from))
-      .without("json_variables")
+      .pluck(...SEND_SUMMARY_FIELDS)
       .run();
   }
 
@@ -270,4 +290,14 @@ export class SendModel extends BasicDataModel(
       .count()
       .run();
   }
+
+  /** The slugs of the real sends made from `from` until `to`. */
+  listSentSlugs(from: Date, to: Date): Promise<string[]> {
+    return this.table
+      .filter((row) => row.key("createdAt").ge(from))
+      .filter((row) => row.key("createdAt").lt(to))
+      .filter((row) => row.key("isTest").ne(true))
+      .distinct("templateSlug")
+      .run();
+  }
 }

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

@@ -4,6 +4,10 @@ import {
   type MailingTemplate,
   MailingTemplateVersion,
 } from "../tables";
+import {
+  parseStored,
+  storedVersionRowSchema,
+} from "../../validation/stored.schema";
 import { TemplateModel } from "./templates.model";
 
 /** The latest committed history row, even before its separate insert completes. */
@@ -11,13 +15,11 @@ 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(
+  return parseStored(
     template.json_published_version,
-  ) as MailingTemplateVersion;
-  row.publishedAt = new Date(row.publishedAt);
-  return row;
+    storedVersionRowSchema,
+    "a version row",
+  );
 }
 
 export class TemplateVersionModel extends BasicDataModel(

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

@@ -35,7 +35,9 @@ export class TemplateModel extends BasicDataModel(
 ) {
   /** The row of `fields`, its name written in every language it holds. */
   static fromFields(fields: TemplateFields): MailingTemplate {
-    return TemplateModel.fromPlainData(fields).localize("*", ["name"]);
+    const row = TemplateModel.fromPlainData(fields);
+    row.localize("*", ["name"]);
+    return row;
   }
 
   /**
@@ -57,19 +59,30 @@ export class TemplateModel extends BasicDataModel(
     return this.insert(TemplateModel.fromFields(fields));
   }
 
+  /**
+   * The stored form of a patch. The row's modifier container (`_internal`,
+   * where the localized name lives) comes out empty when the patch has no
+   * name, and the database merges a row shallowly, so that empty container
+   * would wipe the stored name: it is left out then.
+   */
+  private static storedPatch(row: MailingTemplate, fields: TemplateFields) {
+    const stored = TemplateModel.toDatabase(row);
+    if (fields.name === undefined) delete stored[MODIFIER_CONTAINER];
+    return stored;
+  }
+
   /**
    * Updates a template, a name given holding every language. Every write of
-   * a template goes through here rather than `update`: an update event leaves
-   * the row's modifier container (`_internal`, where the localized name
-   * lives) empty when the patch has no name, and the database merges a row
-   * shallowly, so that empty container would wipe the stored name.
+   * a template goes through here rather than `update`, which would store the
+   * patch's empty modifier container over the name.
    */
   updateFields(id: string, fields: TemplateFields): Promise<number> {
     const row = TemplateModel.fromFields(fields);
     triggerEvent(row, "update");
-    const stored = TemplateModel.toDatabase(row);
-    if (fields.name === undefined) delete stored[MODIFIER_CONTAINER];
-    return this.table.get(id).update(stored).run();
+    return this.table
+      .get(id)
+      .update(TemplateModel.storedPatch(row, fields))
+      .run();
   }
 
   /** Publishes only over the exact semantic revision that was inspected. */
@@ -77,7 +90,10 @@ export class TemplateModel extends BasicDataModel(
     template: MailingTemplate,
     patch: TemplateFields,
   ): Promise<boolean> {
-    const stored = TemplateModel.toDatabase(TemplateModel.fromFields(patch));
+    const stored = TemplateModel.storedPatch(
+      TemplateModel.fromFields(patch),
+      patch,
+    );
     const outcome = await this.table
       .atomicMutation(template._id, {
         type: "update",

package/src/hooks/tenant-export.ts

@@ -102,8 +102,11 @@ async function loadPage<T extends object>(
 
 /** A template as exported: its name in every language. */
 const templateCodec: RowCodec<MailingTemplate> = {
-  fromDatabase: (row) =>
-    TemplateModel.fromDatabase(row)?.localize("*", ["name"]),
+  fromDatabase: (stored) => {
+    const row = TemplateModel.fromDatabase(stored);
+    row?.localize("*", ["name"]);
+    return row;
+  },
 };
 
 export function exportedCollections(tenantId: string): ExportedCollection[] {

package/src/pages/editor.ts

@@ -25,7 +25,7 @@ export class MailingEditorController extends PageController(
   },
   DefaultLayout({ fullWidth: true, hideHeader: true, fillHeight: true }),
 ) {
-  static editor = CustomComponent("MailingEditor").meta({
+  static editor = CustomComponent("MailingTemplateEditor").meta({
     name: "$dms_mailing.permissions.editor.name",
     description: "$dms_mailing.permissions.editor.description",
     icon: "i-ph-pencil-simple",

package/src/routes/metrics.ts

@@ -324,11 +324,10 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
       findSettings(this.tenantId),
     ]);
     const sends = forAudience(rows, this.audience);
-    const excluded = rows.filter((row) => !sends.includes(row));
     const items = buildAttentionItems({
       templates,
       sends,
-      excluded,
+      excludedCount: rows.length - sends.length,
       windowEnd: range.to,
       tracking,
       isSenderSet: Boolean(settings?.senderEmail),

package/src/routes/sends.ts

@@ -70,6 +70,7 @@ import {
 } from "../services/templates";
 import type { SendStatus, SuppressionSummary, TemplateStatus } from "../types";
 import type { JsonObject } from "../types/json";
+import { parseJsonObject } from "../validation/json";
 import {
   type previewVersionSchema,
   realSendSchema,
@@ -578,9 +579,7 @@ function requestedVersionOf(
 }
 
 function variablesOf(send: MailingSend): JsonObject {
-  // SAFETY: json_variables is written only as JSON.stringify(params.variables ?? {}) (services/send.ts) or
-  // JSON.stringify(send.variables) (services/send-import.ts), both a JsonObject.
-  return JSON.parse(send.json_variables || "{}") as JsonObject;
+  return parseJsonObject(send.json_variables || "{}");
 }
 
 function summarize(template: MailingTemplate): SendTemplateSummary {

package/src/routes/templates.ts

@@ -6,6 +6,7 @@ import {
   Parameter,
   Post,
   Put,
+  type QueryValue,
   type RequestContext,
 } from "@antelopejs/interface-api";
 import { assert, assertValidation } from "@antelopejs/interface-api-util";
@@ -32,7 +33,7 @@ import {
 } from "../db";
 import { INVALID_TEMPLATE, saveDetails } from "../data/templates-table";
 import { TemplatesPageController } from "../pages/templates";
-import { forAudience, statsWindowStart } from "../services/metrics";
+import { forAudience, groupBy, statsWindowStart } from "../services/metrics";
 import { refreshTemplateAttention } from "../services/template-attention";
 import { renderEmailHtml } from "../services/render";
 import { categoriesIn } from "../services/categories";
@@ -203,14 +204,14 @@ export class TemplatesController extends Controller(
   @Get("/starters/:id/preview")
   async starterPreview(
     @Parameter("id", "param") id: string,
-    @Parameter("locale", "query") requested?: string,
+    @Parameter("locale", "query") requested: QueryValue,
   ) {
     const starter = findStarter(id);
     assert(starter, HTTP_NOT_FOUND, STARTER_NOT_FOUND);
     const settings = await getSettings(this.tenantId);
     const locale = pickLocale(
       starter.content,
-      requested || undefined,
+      requested === true || requested === "" ? undefined : requested,
       settings.fallbackLocale,
     );
     const localeContent = localeContentOf(starter.content, locale);
@@ -234,14 +235,13 @@ export class TemplatesController extends Controller(
       this.templates.getAll(),
       this.sends.listBetween(statsWindowStart(), new Date()),
     ]);
-    const sends = forAudience(rows, BUSINESS_AUDIENCE);
+    const bySlug = groupBy(
+      forAudience(rows, BUSINESS_AUDIENCE),
+      (send) => send.templateSlug,
+    );
     return {
       items: templates.map((template) =>
-        statsOf(
-          template._id,
-          template.slug,
-          sends.filter((send) => send.templateSlug === template.slug),
-        ),
+        statsOf(template._id, template.slug, bySlug.get(template.slug) ?? []),
       ),
     };
   }

package/src/services/attention.ts

@@ -124,13 +124,13 @@ function unusedLiveItem(window: AttentionWindow): AttentionItem[] {
 
 /**
  * Every send the Overview window holds, split the way the business view counts
- * them: `sends` are the ones behind the figures, `excluded` the test sends the
- * business audience drops.
+ * them: `sends` are the ones behind the figures, `excludedCount` the test sends
+ * the business audience drops.
  */
 export interface AttentionWindow {
   templates: MailingTemplate[];
   sends: SendSummary[];
-  excluded: SendSummary[];
+  excludedCount: number;
   /** When the window closes. */
   windowEnd: Date;
   /** What the configured provider can report; `null` when it is unreachable. */
@@ -140,7 +140,7 @@ export interface AttentionWindow {
 }
 
 function testOnlyWindowItem(window: AttentionWindow): AttentionItem[] {
-  if (window.sends.length || !window.excluded.length) return [];
+  if (window.sends.length || !window.excludedCount) return [];
   return [
     {
       id: "test-only-window",
@@ -150,8 +150,8 @@ function testOnlyWindowItem(window: AttentionWindow): AttentionItem[] {
       description: "$dms_mailing.attention.test_only_window.description",
       action: "$dms_mailing.attention.test_only_window.action",
       to: SENDS_PAGE,
-      count: window.excluded.length,
-      params: { count: window.excluded.length },
+      count: window.excludedCount,
+      params: { count: window.excludedCount },
     },
   ];
 }

package/src/services/metrics.ts

@@ -276,7 +276,9 @@ export function groupBy<T>(
   const groups = new Map<string, T[]>();
   for (const item of items) {
     const id = key(item);
-    groups.set(id, [...(groups.get(id) ?? []), item]);
+    const group = groups.get(id);
+    if (group) group.push(item);
+    else groups.set(id, [item]);
   }
   return groups;
 }

package/src/services/settings.ts

@@ -10,6 +10,10 @@ import {
 } from "../types";
 import type { JsonObject } from "../types/json";
 import type { SettingsPatch } from "../validation/settings.schema";
+import {
+  parseStored,
+  storedCategoriesSchema,
+} from "../validation/stored.schema";
 
 export const WEBHOOK_SECRET_BYTES = 24;
 
@@ -48,9 +52,11 @@ function toValues(row: MailingSettings): MailingSettingsValues {
     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[],
+    categories: parseStored(
+      row.json_categories,
+      storedCategoriesSchema,
+      "template categories",
+    ),
   };
 }
 

package/src/services/template-attention.ts

@@ -5,13 +5,13 @@ import {
   type TemplateAttentionFields,
   TemplateModel,
 } from "../db";
-import { BUSINESS_AUDIENCE, type TemplateAttentionReason } from "../types";
+import type { TemplateAttentionReason } from "../types";
 import {
   knownLocalesOf,
   type TemplateAttentionContext,
   templateAttentionReasons,
 } from "./attention";
-import { forAudience, statsWindowStart } from "./metrics";
+import { statsWindowStart } from "./metrics";
 
 /** How the stored `attention` field separates its reasons. */
 const REASON_SEPARATOR = ",";
@@ -31,14 +31,13 @@ async function attentionContext(
   templates: MailingTemplate[],
 ): Promise<TemplateAttentionContext> {
   const now = Date.now();
-  const sends = await GetModel(SendModel, tenantId).listBetween(
+  const slugs = await GetModel(SendModel, tenantId).listSentSlugs(
     statsWindowStart(now),
     new Date(now),
   );
-  const real = forAudience(sends, BUSINESS_AUDIENCE);
   return {
     now,
-    sentSlugs: new Set(real.map((send) => send.templateSlug)),
+    sentSlugs: new Set(slugs),
     knownLocales: knownLocalesOf(templates),
   };
 }

package/src/services/templates.ts

@@ -28,6 +28,13 @@ import type {
 } from "../types";
 import { DEFAULT_FALLBACK_LOCALE } from "../types";
 import type { JsonObject } from "../types/json";
+import { parseJsonObject } from "../validation/json";
+import {
+  parseStored,
+  storedChangesSchema,
+  storedContentSchema,
+  storedVariablesSchema,
+} from "../validation/stored.schema";
 
 export interface TemplateAuthor {
   name?: string;
@@ -74,8 +81,11 @@ 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;
+  return parseStored(
+    template.json_content || EMPTY_CONTENT,
+    storedContentSchema,
+    "template content",
+  );
 }
 
 export function hasDraft(template: MailingTemplate): boolean {
@@ -85,8 +95,11 @@ 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;
+  return parseStored(
+    template.json_draft,
+    storedContentSchema,
+    "template content",
+  );
 }
 
 /** The version customers receive; 0 for a template never published. */
@@ -105,8 +118,11 @@ 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[];
+  return parseStored(
+    template.json_variables,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /**
@@ -118,8 +134,11 @@ 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[];
+  return parseStored(
+    template.json_variables_draft,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /** A template's working state: what a publish would ship. */
@@ -175,8 +194,7 @@ export function pendingChanges(template: MailingTemplate): TemplateChange[] {
 }
 
 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;
+  return parseJsonObject(template.json_test_data);
 }
 
 interface FooterLabels {
@@ -297,16 +315,18 @@ 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[];
+  return parseStored(row.json_changes, storedChangesSchema, "version changes");
 }
 
 /** The declarations a published version shipped with. */
 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[];
+  return parseStored(
+    row.json_variables,
+    storedVariablesSchema,
+    "variable declarations",
+  );
 }
 
 /**
@@ -461,8 +481,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;
+  return parseStored(row.json_content, storedContentSchema, "template content");
 }
 
 /**