@antelopejs/dms-mailing 0.9.2 → 0.10.0

package/frontend-vue/tests/backend-boundary.test.ts

@@ -7,8 +7,8 @@ import {
 	writeFileSync,
 } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { build as viteBuild, type Plugin } from 'vite'
+import { dirname, join } from 'node:path/posix'
+import { normalizePath, build as viteBuild, type Plugin } from 'vite'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { backendBoundary } from '../build/backend-boundary'
 
@@ -22,8 +22,8 @@ function write(file: string, text: string): void {
 }
 
 beforeAll(() => {
-	repository = realpathSync(
-		mkdtempSync(join(tmpdir(), 'dms-mailing-boundary-')),
+	repository = normalizePath(
+		realpathSync(mkdtempSync(`${tmpdir()}/dms-mailing-boundary-`)),
 	)
 	const backend = join(repository, 'packages/dms-mailing')
 	frontend = join(backend, 'frontend-vue')

package/frontend-vue/tests/column-displays.test.ts

@@ -1,6 +1,11 @@
 // @vitest-environment node
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { VNode } from 'vue'
+import CategoryLabel from '../app/components/CategoryLabel.vue'
+import setup, {
+	renderCategory,
+	renderLocaleChips,
+} from '../app/plugins/column-displays'
 
 interface RegisteredType {
 	id: string
@@ -11,9 +16,12 @@ type PluginSetup = () => void
 
 const registered: RegisteredType[] = []
 
+vi.hoisted(() => {
+	vi.stubGlobal('defineDmsPlugin', (pluginSetup: PluginSetup) => pluginSetup)
+})
+
 beforeEach(() => {
 	registered.length = 0
-	vi.stubGlobal('defineDmsPlugin', (setup: PluginSetup) => setup)
 	vi.stubGlobal('useDataTypes', () => ({
 		registerDataType: (type: RegisteredType) => registered.push(type),
 	}))
@@ -24,7 +32,6 @@ beforeEach(() => {
 
 afterEach(() => {
 	vi.unstubAllGlobals()
-	vi.resetModules()
 })
 
 function texts(node: VNode): string[] {
@@ -36,8 +43,7 @@ function texts(node: VNode): string[] {
 }
 
 describe('column displays plugin', () => {
-	it('registers the locale chips and category displays without a DOM', async () => {
-		const { default: setup } = await import('../app/plugins/column-displays')
+	it('registers the locale chips and category displays without a DOM', () => {
 		;(setup as unknown as PluginSetup)()
 		expect(registered.map((type) => type.id)).toEqual([
 			'mailing:locale-chips',
@@ -45,18 +51,14 @@ describe('column displays plugin', () => {
 		])
 	})
 
-	it('draws a category through its label component', async () => {
-		const { renderCategory } = await import('../app/plugins/column-displays')
-		const { default: CategoryLabel } =
-			await import('../app/components/CategoryLabel.vue')
+	it('draws a category through its label component', () => {
 		const cell = renderCategory('orders')
 		expect(cell.type).toBe(CategoryLabel)
 		expect(cell.props).toEqual({ value: 'orders' })
 		expect(renderCategory(undefined).props).toEqual({ value: null })
 	})
 
-	it('draws the locale chips with the missing workspace ones dashed', async () => {
-		const { default: setup } = await import('../app/plugins/column-displays')
+	it('draws the locale chips with the missing workspace ones dashed', () => {
 		;(setup as unknown as PluginSetup)()
 		const cell = registered[0]!.formatter.default('en,fr', 'en')
 		const chips = cell.children as VNode[]
@@ -65,8 +67,7 @@ describe('column displays plugin', () => {
 		expect(String(chips[0]!.props?.class)).not.toContain('border-dashed')
 	})
 
-	it('draws a dash for a row without locale information', async () => {
-		const { renderLocaleChips } = await import('../app/plugins/column-displays')
+	it('draws a dash for a row without locale information', () => {
 		expect(texts(renderLocaleChips('', ['en']))).toEqual(['—'])
 		expect(texts(renderLocaleChips(undefined, ['en']))).toEqual(['—'])
 	})

package/frontend-vue/tests/footer-block.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { defineComponent, h, provide, ref } from 'vue'
-import FooterBlockView from '../app/components/blocks/Footer.vue'
+import FooterBlockView from '../app/components/blocks/BlockFooter.vue'
 import type { FooterBlock } from '../app/types/mailing'
 import { TOKEN_DATA_KEY } from '../app/utils/tokens'
 import type { TokenData } from '../app/utils/tokens'

package/frontend-vue/tests/template-gallery-display.test.ts

@@ -1,6 +1,7 @@
 // @vitest-environment node
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { Component } from 'vue'
+import setup from '../app/plugins/template-gallery-display'
 
 interface DisplayRegistration {
 	id: string
@@ -9,21 +10,21 @@ interface DisplayRegistration {
 
 type PluginSetup = () => void
 
+vi.hoisted(() => {
+	vi.stubGlobal('defineDmsPlugin', (pluginSetup: PluginSetup) => pluginSetup)
+})
+
 afterEach(() => {
 	vi.unstubAllGlobals()
-	vi.resetModules()
 })
 
 describe('template gallery display plugin', () => {
-	it('registers the gallery under the mailing namespace without a DOM', async () => {
+	it('registers the gallery under the mailing namespace without a DOM', () => {
 		const registrations: DisplayRegistration[] = []
-		vi.stubGlobal('defineDmsPlugin', (setup: PluginSetup) => setup)
 		vi.stubGlobal(
 			'registerTableViewDisplay',
 			(registration: DisplayRegistration) => registrations.push(registration),
 		)
-		const { default: setup } =
-			await import('../app/plugins/template-gallery-display')
 		setup()
 		expect(registrations.map((registration) => registration.id)).toEqual([
 			'mailing:gallery',

package/frontend-vue/tests/template-overlays.test.ts

@@ -1,5 +1,6 @@
 // @vitest-environment node
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useTemplateDrawer } from '../app/composables/useTemplateDrawer'
 import type { TemplateRow } from '../app/types/mailing'
 
 interface OpenCall {
@@ -53,7 +54,6 @@ beforeEach(() => {
 
 afterEach(() => {
 	vi.unstubAllGlobals()
-	vi.resetModules()
 })
 
 function row(id: string): TemplateRow {
@@ -68,9 +68,7 @@ function row(id: string): TemplateRow {
 }
 
 describe('useTemplateDrawer', () => {
-	it('opens the test send with the editor draft and locale', async () => {
-		const { useTemplateDrawer } =
-			await import('../app/composables/useTemplateDrawer')
+	it('opens the test send with the editor draft and locale', () => {
 		const content = { locales: {} }
 		useTemplateDrawer().openTestSend('t1', { locale: 'fr', content })
 		expect(modalCalls[0]?.component).toEqual({ name: 'MailingTestSendModal' })
@@ -82,8 +80,6 @@ describe('useTemplateDrawer', () => {
 	})
 
 	it('calls back only when the dialog closes after a change', async () => {
-		const { useTemplateDrawer } =
-			await import('../app/composables/useTemplateDrawer')
 		const onDone = vi.fn()
 		useTemplateDrawer().openRealSend('t1', { onDone })
 		await Promise.resolve()
@@ -97,9 +93,7 @@ describe('useTemplateDrawer', () => {
 		expect(modalCalls[1]?.componentOptions).toEqual({ initialName: 'Refund' })
 	})
 
-	it('opens the details from the right and steps through the rows shown', async () => {
-		const { useTemplateDrawer } =
-			await import('../app/composables/useTemplateDrawer')
+	it('opens the details from the right and steps through the rows shown', () => {
 		const rows = [row('a'), row('b'), row('c')]
 		useTemplateDrawer().openDetails(rows[1]!, { rows })
 		const call = drawerCalls[0]!
@@ -115,9 +109,7 @@ describe('useTemplateDrawer', () => {
 		expect((options.navigation as Navigation).hasNext).toBe(false)
 	})
 
-	it('opens the details of a bare id without navigation', async () => {
-		const { useTemplateDrawer } =
-			await import('../app/composables/useTemplateDrawer')
+	it('opens the details of a bare id without navigation', () => {
 		useTemplateDrawer().openDetails('x')
 		expect(drawerCalls[0]?.componentOptions.templateId).toBe('x')
 		expect(drawerCalls[0]?.componentOptions.navigation).toBeUndefined()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.9.2",
+  "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.5.1",
+    "@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",

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/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";
@@ -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);

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/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");
 }
 
 /**