@antelopejs/dms-mailing 0.6.1 → 0.7.0

package/frontend-vue/tests/replay-toast.test.ts

@@ -42,7 +42,8 @@ describe('useReplayToast', () => {
 		const [toast] = stubs.toasts
 		expect(toast).toMatchObject({
 			color: 'warning',
-			title: 'dms_mailing.suppressions.notice.not_sent.toast_title email=a@x.test',
+			title:
+				'dms_mailing.suppressions.notice.not_sent.toast_title email=a@x.test',
 			description:
 				'dms_mailing.suppressions.notice.not_sent.reason reason=dms_mailing.suppressions.reasons.unsubscribe',
 		})

package/frontend-vue/tests/send-drawer.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import SendDrawer from '../app/components/SendDrawer.vue'
+import type { SendRow } from '../app/types/mailing'
+import { flush, mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+import { mailingReads, stubApiData } from './helpers/api-data'
+
+vi.mock('../app/composables/useMailingApi', async (importOriginal) => ({
+	...(await importOriginal<object>()),
+	useMailingApi: () => ({ replay: vi.fn() }),
+}))
+
+const SEND: SendRow = {
+	_id: '041f125a00000000',
+	templateId: 't1',
+	templateSlug: 'invoice-reminder',
+	locale: 'fr',
+	templateVersion: 1,
+	recipientEmail: 'marc@boulangerie-lejeune.example',
+	recipientName: 'Marc Lejeune',
+	status: 'sent',
+	providerMessageId: '<f1c836b9-226e-1c5a-ab39-10b4beb00a4c@ethereal.email>',
+	latencyMs: 822,
+	source: 'automation.overdue-reminders',
+	json_variables: '{"customer":{"name":"Marc"}}',
+	opens: 0,
+	clicks: 0,
+	createdAt: '2026-10-20T08:00:02Z',
+	isTest: false,
+}
+
+const STUB_NAMES = [
+	'USkeleton',
+	'UButton',
+	'UIcon',
+	'DmsEyebrow',
+	'DmsStatusPill',
+	'DmsStatGroup',
+	'DmsBanner',
+	'DmsActivityItem',
+	'DmsListRow',
+	'DmsKeyValueList',
+	'DmsContainerFooter',
+]
+const STUBS = Object.fromEntries(
+	STUB_NAMES.map((name) => [name, slotStub(name)]),
+)
+
+async function render(): Promise<HTMLElement> {
+	const { host } = mount(SendDrawer, { rowData: SEND }, STUBS)
+	await flush()
+	return host
+}
+
+describe('send drawer layout', () => {
+	beforeEach(() => {
+		stubNuxtGlobals()
+		vi.stubGlobal('useApiError', () => undefined)
+		stubApiData().respond(
+			mailingReads({ send: () => ({ send: SEND, events: [] }) }),
+		)
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+		document.body.innerHTML = ''
+	})
+
+	it('adds no inset or scroller of its own inside the drawer body', async () => {
+		const host = await render()
+		const root = host.firstElementChild as HTMLElement
+		expect(root.className).not.toMatch(/(^|\s)(p|px|py|m)-\d/)
+		expect(root.className).not.toContain('h-full')
+		expect(host.querySelector('.overflow-y-auto')).toBeNull()
+		expect(host.querySelector('header')?.className).not.toMatch(/px-\d/)
+	})
+
+	// The DMS drawer body is a flex column: a root that grows keeps the
+	// DmsContainerFooter, which sticks and sits flush, at the drawer's bottom.
+	it('grows in the drawer body and puts its actions in the DMS footer', async () => {
+		const host = await render()
+		const root = host.firstElementChild as HTMLElement
+		expect(root.className).toContain('flex-1')
+		expect(root.className).toContain('flex-col')
+		expect(root.style.minHeight).toBe('')
+		const footer = host.querySelector('[data-send-footer]')
+		expect(footer?.getAttribute('data-stub')).toBe('DmsContainerFooter')
+		expect(
+			footer?.querySelectorAll('[data-stub="UButton"]').length,
+		).toBeGreaterThan(0)
+	})
+
+	it('keeps the template / locale / latency trio on one row in a 600px drawer', async () => {
+		const group = (await render()).querySelector('[data-stub="DmsStatGroup"]')
+		expect(group?.getAttribute('columns-from')).toBe('md')
+		expect(group?.className).not.toContain('grid-cols')
+	})
+
+	it('wraps the timeline so a Message-ID is never clipped', async () => {
+		const items = (await render()).querySelectorAll(
+			'[data-stub="DmsActivityItem"]',
+		)
+		expect(items.length).toBeGreaterThan(0)
+		items.forEach((item) => expect(item.hasAttribute('wrap')).toBe(true))
+	})
+
+	it('lets the address give way before the date on a phone', async () => {
+		const line = (await render()).querySelector('[data-send-recipient]')
+		const [address, date] = Array.from(line?.children ?? [])
+		expect(line?.className).toContain('flex-wrap')
+		expect(line?.className).not.toContain('truncate')
+		expect(address?.className).toContain('truncate')
+		expect(address?.getAttribute('title')).toBe(SEND.recipientEmail)
+		expect(date?.className).toContain('whitespace-nowrap')
+	})
+
+	it('puts the "source" label under the source, not beside it', async () => {
+		const row = (await render()).querySelector('[data-send-source]')
+		expect(row?.hasAttribute('trailing')).toBe(false)
+		expect(row?.getAttribute('meta')).toContain('source')
+		expect(row?.textContent).toContain(SEND.source)
+	})
+})

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

@@ -434,7 +434,7 @@ describe('StarterGallery', () => {
 	})
 
 	it('creates a starter as a draft and opens it', async () => {
-		api.createTemplate.mockResolvedValue(['new-id'])
+		api.createTemplate.mockResolvedValue({ _id: 'new-id' })
 		const view = mount(StarterGallery, {}, globals)
 		await flush()
 		;(view.host.querySelector('[data-stub="DmsCard"]') as HTMLElement).click()

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

@@ -2,7 +2,6 @@
 import { reactive } from 'vue'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import TemplateGallery from '../app/components/TemplateGallery.vue'
-import TemplateCard from '../app/components/TemplateCard.vue'
 import type { TemplateRow, TemplateStats } from '../app/types/mailing'
 import {
 	flush,
@@ -22,6 +21,11 @@ const CATEGORIES_URL = '/api/mailing/templates/categories'
 const OVERVIEW_URL = '/api/mailing/templates/overview'
 const LIST_URL = '/api/mailing/tables/templates/list'
 
+vi.mock('../app/components/TemplatePreviewFrame.vue', async () => {
+	const { slotStub } = await import('./helpers/nuxt-globals')
+	return { default: slotStub('MailingTemplatePreviewFrame') }
+})
+
 const RECENT = new Date(Date.now() - 3_600_000).toISOString()
 
 function row(overrides: Partial<TemplateRow>): TemplateRow {
@@ -107,8 +111,6 @@ function context({ items, query = {} }: ContextOptions) {
 }
 
 const globals = {
-	MailingTemplateCard: TemplateCard,
-	MailingTemplatePreviewFrame: slotStub('MailingTemplatePreviewFrame'),
 	MailingStarterGallery: slotStub('MailingStarterGallery'),
 	DmsEmptyState: slotStub('DmsEmptyState'),
 }
@@ -371,6 +373,91 @@ describe('TemplateGallery', () => {
 		view.unmount()
 	})
 
+	it('keeps its skeleton until the categories answered, then draws the cards in their group', async () => {
+		let answerCategories: (value: unknown) => void = () => {}
+		api.respond(({ url }) => {
+			if (url === CATEGORIES_URL)
+				return new Promise((resolve) => (answerCategories = resolve))
+			if (url === OVERVIEW_URL) return { items: [] }
+			return { results: [LIVE], total: 1 }
+		})
+		const view = mount(
+			TemplateGallery,
+			{ context: context({ items: [LIVE] }) },
+			globals,
+		)
+		await flush()
+		expect(view.host.querySelector('[data-gallery-skeleton]')).not.toBeNull()
+		expect(cardNames(view.host)).toEqual([])
+		answerCategories({
+			categories: [{ id: 'orders', label: 'Orders', icon: 'i-ph-package' }],
+		})
+		await flush()
+		expect(view.host.querySelector('[data-gallery-skeleton]')).toBeNull()
+		expect(view.host.querySelector('h2')?.textContent?.trim()).toBe('Orders')
+		view.unmount()
+	})
+
+	it('draws no skeleton once the cards are on screen, a refresh included', async () => {
+		const ctx = reactive(context({ items: [LIVE] }))
+		const view = mount(TemplateGallery, { context: ctx }, globals)
+		await flush()
+		ctx.loading = true
+		ctx.items = [LIVE]
+		await flush()
+		expect(view.host.querySelector('uskeleton')).toBeNull()
+		expect(cardNames(view.host)).toEqual(['Order confirmation'])
+		view.unmount()
+	})
+
+	it('lays its skeleton out like a group of cards, so they replace it in place', async () => {
+		api.respond(({ url }) => {
+			if (url === CATEGORIES_URL) return new Promise(() => {})
+			return { items: [], results: [LIVE], total: 1 }
+		})
+		const loading = mount(
+			TemplateGallery,
+			{ context: context({ items: [LIVE] }) },
+			globals,
+		)
+		await flush()
+		const skeleton = loading.host.querySelector(
+			'[data-gallery-skeleton]',
+		) as HTMLElement
+		const skeletonCard = skeleton.querySelector('dmscard') as HTMLElement
+		const skeletonHeading = skeleton.firstElementChild as HTMLElement
+		const skeletonBody = skeletonCard.lastElementChild as HTMLElement
+
+		api.respond(({ url }) =>
+			url === CATEGORIES_URL
+				? { categories: [] }
+				: { items: [], results: [LIVE], total: 1 },
+		)
+		const loaded = mount(
+			TemplateGallery,
+			{ context: context({ items: [MISSING_DE] }) },
+			globals,
+		)
+		await flush()
+		expect(loaded.host.querySelector('[data-gallery-skeleton]')).toBeNull()
+		const section = loaded.host.querySelector('section') as HTMLElement
+		const card = section.querySelector('article, dmscard') as HTMLElement
+		const body = card.lastElementChild as HTMLElement
+
+		expect(skeleton.className).toBe(section.className)
+		expect(skeletonHeading.className).toContain('flex items-center gap-2')
+		expect(skeletonCard.querySelector('uskeleton')?.className).toContain(
+			'h-[172px]',
+		)
+		expect(skeletonBody.className).toBe(body.className)
+		expect(skeletonBody.children).toHaveLength(body.children.length)
+		expect(skeletonBody.lastElementChild?.className).toBe(
+			body.lastElementChild?.className.replace(' text-muted', ''),
+		)
+		loading.unmount()
+		loaded.unmount()
+	})
+
 	it('opens the editor on a missing locale chip', async () => {
 		const view = mount(
 			TemplateGallery,

package/frontend-vue/tests/template-preview-frame.test.ts

@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import TemplatePreviewFrame from '../app/components/TemplatePreviewFrame.vue'
+import { flush, mount, stubNuxtGlobals } from './helpers/nuxt-globals'
+import { stubApiData } from './helpers/api-data'
+
+/** Past the frame's debounce before it reads. */
+const DEBOUNCE_WAIT_MS = 400
+
+const api = { preview: vi.fn() }
+
+vi.mock('../app/composables/useMailingApi', async (importOriginal) => ({
+	...(await importOriginal<object>()),
+	useMailingApi: () => api,
+}))
+
+const skeleton = (host: HTMLElement) => host.querySelector('uskeleton')
+const placeholder = (host: HTMLElement) =>
+	host.querySelector('[data-preview-placeholder]')
+const fallback = (host: HTMLElement) =>
+	host.querySelector('[data-preview-fallback]')
+
+async function settle(): Promise<void> {
+	await vi.advanceTimersByTimeAsync(DEBOUNCE_WAIT_MS)
+	await flush()
+}
+
+beforeEach(() => {
+	vi.useFakeTimers()
+	stubNuxtGlobals()
+	stubApiData()
+	api.preview.mockReset()
+})
+
+afterEach(() => {
+	vi.useRealTimers()
+	vi.unstubAllGlobals()
+	document.body.innerHTML = ''
+})
+
+describe('TemplatePreviewFrame', () => {
+	it('holds a skeleton from its first render until the HTML is in', async () => {
+		api.preview.mockResolvedValue({ html: '<p>Hello</p>' })
+		const view = mount(TemplatePreviewFrame, { templateId: 't1', width: 600 })
+		expect(skeleton(view.host)).not.toBeNull()
+		expect(view.host.querySelector('iframe')).toBeNull()
+		await settle()
+		expect(skeleton(view.host)).toBeNull()
+		expect(view.host.querySelector('iframe')?.getAttribute('srcdoc')).toContain(
+			'Hello',
+		)
+		view.unmount()
+	})
+
+	it('waits on a blank sheet, never a skeleton, as a lazy thumbnail', async () => {
+		api.preview.mockResolvedValue({ html: '<p>Hello</p>' })
+		const view = mount(TemplatePreviewFrame, {
+			templateId: 't1',
+			width: 600,
+			lazy: true,
+		})
+		await settle()
+		expect(skeleton(view.host)).toBeNull()
+		expect(placeholder(view.host)).not.toBeNull()
+		expect(view.host.querySelector('iframe')).toBeNull()
+		view.unmount()
+	})
+
+	it('shows its fallback when the preview cannot be read, not a skeleton for ever', async () => {
+		api.preview.mockRejectedValue(new Error('500'))
+		const view = mount(TemplatePreviewFrame, { templateId: 't1', width: 600 })
+		await settle()
+		expect(skeleton(view.host)).toBeNull()
+		expect(fallback(view.host)?.textContent).toContain(
+			'dms_mailing.common.preview_unavailable',
+		)
+		view.unmount()
+	})
+
+	it('keeps the box its size while it waits', () => {
+		const view = mount(TemplatePreviewFrame, {
+			templateId: 't1',
+			width: 600,
+			scale: 0.4,
+			lazy: true,
+		})
+		const box = view.host.firstElementChild as HTMLElement
+		expect(box.style.width).toBe('240px')
+		expect(box.style.height).toBe('192px')
+		view.unmount()
+	})
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.6.1",
+  "version": "0.7.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",
@@ -49,17 +49,17 @@
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.3.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
-    "@antelopejs/interface-dms-mailing": ">=0.8.0 <0.9.0",
+    "@antelopejs/interface-dms": ">=0.8.0 <1.0.0",
+    "@antelopejs/interface-dms-mailing": ">=0.9.0 <0.10.0",
     "@antelopejs/interface-email": ">=0.0.6 <1.0.0",
     "node-cron": "^4.2.1",
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.16.0 <2",
+    "@antelopejs/core": ">=1.17.0 <2",
     "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10",
@@ -90,6 +90,7 @@
       "./skills"
     ]
   },
+  "dmsFrontend": "dist/frontend-module.js",
   "scripts": {
     "build": "rimraf dist && tsc",
     "dev": "ajs project dev -w -p playground",

package/skills/dms-mailing/SKILL.md

@@ -25,7 +25,7 @@ https://dms.antelopejs.com/docs/modules/mailing (sending from code and the webho
   (`@antelopejs/nodemailer`, `config: { ethereal: true }` in dev).
 - Mailing 0.6 requires `@antelopejs/dms` >=0.9 (interface-dms 0.7, renderer `@antelopejs/dms-frontend` 0.6);
   0.4 is the DMS 0.8 line. Mailing 0.6 implements `@antelopejs/interface-dms-mailing` `>=0.8.0 <0.9.0`, adding declaration and import calls;
-  `SendTemplate` / `RecordEmailEvent` callers do not change.
+  interface 0.9 adds `DeclareSender`; `SendTemplate` / `RecordEmailEvent` callers do not change.
 - Module option: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML).
 - Set the DMS `clientBaseUrl`: the webhook URL and the e-mail logo are built on it.
 - Per-workspace settings (sender, missing-variable guard, fallback locale, webhook secret, retention,
@@ -49,6 +49,8 @@ const result = await SendTemplate("order-confirmed", {
 - Only the **published** version is sent; drafts go out only as tests (`[TEST]` subject, out of the figures).
 - Variables are typed (`string`, `text`, `number`, `money`, `date`, `url`, `boolean`, `array`) and declared on
   the template; pass every required one.
+- Don't pre-format amounts and dates per locale: pass `{ value: 987420, currency: "EUR" }` (minor units) or a
+  `Date`, or an ISO string at a `date` path; the send locale formats them. Plain strings print as given.
 - In-process events: `RecordEmailEvent(tenantId, { provider, messageId, type, details })`.
   HTTP: `POST <clientBaseUrl>/api/mailing/events/<provider>/<tenantId>` with header `x-mailing-webhook-secret`.
 - Automation (if `interface-dms-automation` is loaded): action `mailing.send-template`, trigger `mailing.email-event`.
@@ -56,12 +58,13 @@ const result = await SendTemplate("order-confirmed", {
 ## Ship templates as code
 
 ```typescript
-import { DeclareTemplate, DeclareTemplateCategory, ImportSends } from "@antelopejs/interface-dms-mailing";
+import { DeclareSender, DeclareTemplate, DeclareTemplateCategory, ImportSends } from "@antelopejs/interface-dms-mailing";
 
 export async function declareMailingContent(tenantId: string) {
-  await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: "Subscriptions", icon: "i-ph-repeat" }); // before templates naming it
+  await DeclareSender({ tenantId, name: "Acme", email: "hello@acme.example" }); // a plain write: call it once, at provisioning
+  await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: { en: "Subscriptions", fr: "Abonnements" }, icon: "i-ph-repeat" }); // before templates naming it
   const { outcome } = await DeclareTemplate({
-    tenantId, slug: "subscription-renewed", name: "Subscription renewed", category: "subscriptions",
+    tenantId, slug: "subscription-renewed", name: { en: "Subscription renewed", fr: "Abonnement renouvelé" }, category: "subscriptions",
     content: { locales: { en: { subject: "Your {{plan.name}} plan is renewed", preheader: "", blocks: [] } } },
     variables: [{ path: "plan.name", type: "string", required: true }],
     testData: { plan: { name: "Pro" } },
@@ -82,6 +85,10 @@ export async function declareMailingContent(tenantId: string) {
   draft and still holds exactly the last declaration (fingerprint on `declaredHash`); otherwise `kept`.
   A dashboard-made template under that slug is never taken over. Deleted → recreated next boot; archive instead.
 - Categories: added once; a category a user relabelled/removed, or a default one, is `kept`.
+- `name` / `label` are localized texts `{ en, fr, … }` (stored `@Localized`, `en` required as fallback), never `$`
+  i18n keys; each user reads, searches and sorts them in their language (`x-content-language`).
+- `DeclareSender({ tenantId, email, name?, replyTo? })` writes the settings' sender (resolves `void`); call it once
+  from `Hook.TENANT_BEING_PROVISIONED`, not on every boot, since it replaces what a user set. Refusals use `invalid_sender`.
 - Refusals reject with `error.code`: `invalid_template`, `unknown_category`, `empty_subject`,
   `nothing_to_publish`, `invalid_category`; invalid tenant input rejects before writes. Storage errors can occur after publication.
 - `ImportSends({ tenantId, sends: [{ importId, templateSlug, to, sentAt, events }] })` writes past sends with their own
@@ -96,6 +103,12 @@ export async function declareMailingContent(tenantId: string) {
 - A missing locale falls back to the workspace's fallback locale (logged as `DE asked`).
 - The template slug is fixed at creation: code depends on it.
 - `mailing.send` permission gates every route that reaches recipients; writes publish on realtime topic `mailing:sends`.
+- Overview and Sends are live pages (`live: { maxRate: 5, rememberKey: "mailing" }`) with the DMS `PageToolbar`
+  (provider pill, Direct / Pause, period) under their `header` static; the send log `liveHold`s its rows.
+  The period offers a comparison menu (`previous-period` default, `previous-year`, `none`); routes read
+  `compareFrom` / `compareTo`, and `comparison=none` drops every delta and comparison series. Every period
+  figure renders it: KPI deltas, the volume chart's dashed series, funnel steps (`previousCount`, `delta`),
+  the top lists' row `delta` and the Sends stat strip (`compared`); period blocks carry `realtimeTopic: "mailing:sends"`.
 - 0.4+ does not read a 0.3 database and moved the webhook path (tenant in the URL).
 - nodemailer `ethereal: true` creates its account online at startup: offline, the whole project fails to
   start (nodemailer's `construct()` throws, before Mailing runs). Use a local SMTP server (Mailpit) offline.

package/src/constants.ts

@@ -8,6 +8,8 @@ export const SETTINGS_PATH = `${MODULE_BASE_PATH}/settings`;
 export const NEW_TEMPLATE_BUTTON_ID = "create";
 export const NEW_TEMPLATE_ACTION_ID = "mailing.new-template";
 export const FRONTEND_MODULE_NAME = "@antelopejs/dms-mailing-frontend-vue";
+/** The header a provider webhook carries the secret its route checks in. */
+export const WEBHOOK_SECRET_HEADER = "x-mailing-webhook-secret";
 export const EMAIL_TEMPLATE_NAME = "EmailMailingTemplate";
 
 export const MAILING_SEND_PERMISSION = "mailing.send";

package/src/data/sends-table.ts

@@ -231,7 +231,7 @@ export class SendsTableAPI extends DataController(
   declare requestedLocale: string;
 
   /**
-   * Hidden by default: the side panel shows it under "Origin", and the room
+   * Hidden by default: the send drawer shows it under "Origin", and the room
    * goes to the recipient and the provider's error.
    */
   @Listable()