@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -0,0 +1,125 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { TemplateRow } from '../app/types/mailing'
+
+interface OpenCall {
+	title: string
+	component: unknown
+	componentOptions: Record<string, unknown>
+	componentKey?: string
+	direction?: string
+	size?: string
+}
+
+interface Navigation {
+	hasPrev: boolean
+	hasNext: boolean
+	next: () => void
+}
+
+const drawerCalls: OpenCall[] = []
+const modalCalls: OpenCall[] = []
+const patches: Record<string, unknown>[] = []
+let nextResult: unknown = undefined
+
+function handle() {
+	return {
+		result: Promise.resolve(nextResult),
+		patch: (patch: Record<string, unknown>) => patches.push(patch),
+		close: () => undefined,
+	}
+}
+
+beforeEach(() => {
+	drawerCalls.length = 0
+	modalCalls.length = 0
+	patches.length = 0
+	nextResult = undefined
+	vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
+	vi.stubGlobal('resolveComponent', (name: string) => ({ name }))
+	vi.stubGlobal('useDrawer', () => ({
+		open: (options: OpenCall) => {
+			drawerCalls.push(options)
+			return handle()
+		},
+	}))
+	vi.stubGlobal('useModal', () => ({
+		open: (options: OpenCall) => {
+			modalCalls.push(options)
+			return handle()
+		},
+	}))
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	vi.resetModules()
+})
+
+function row(id: string): TemplateRow {
+	return {
+		_id: id,
+		slug: id,
+		name: id,
+		status: 'live',
+		updatedAt: '',
+		updatedBy: '',
+	}
+}
+
+describe('useTemplateDrawer', () => {
+	it('opens the test send with the editor draft and locale', async () => {
+		const { useTemplateDrawer } =
+			await import('../app/composables/useTemplateDrawer')
+		const content = { locales: {} }
+		useTemplateDrawer().openTestSend('t1', { locale: 'fr', content })
+		expect(modalCalls[0]?.component).toEqual({ name: 'MailingTestSendModal' })
+		expect(modalCalls[0]?.componentOptions).toEqual({
+			templateId: 't1',
+			locale: 'fr',
+			content,
+		})
+	})
+
+	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()
+		await Promise.resolve()
+		expect(onDone).not.toHaveBeenCalled()
+		nextResult = true
+		useTemplateDrawer().openNewTemplate({ initialName: 'Refund', onDone })
+		await Promise.resolve()
+		await Promise.resolve()
+		expect(onDone).toHaveBeenCalledTimes(1)
+		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')
+		const rows = [row('a'), row('b'), row('c')]
+		useTemplateDrawer().openDetails(rows[1]!, { rows })
+		const call = drawerCalls[0]!
+		expect(call.direction).toBe('right')
+		expect(call.component).toEqual({ name: 'MailingTemplateDrawer' })
+		const navigation = call.componentOptions.navigation as Navigation
+		expect(navigation.hasPrev).toBe(true)
+		expect(navigation.hasNext).toBe(true)
+		navigation.next()
+		expect(patches[0]?.componentKey).toBe('c')
+		const options = patches[0]?.componentOptions as Record<string, unknown>
+		expect(options.templateId).toBe('c')
+		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')
+		useTemplateDrawer().openDetails('x')
+		expect(drawerCalls[0]?.componentOptions.templateId).toBe('x')
+		expect(drawerCalls[0]?.componentOptions.navigation).toBeUndefined()
+	})
+})

package/frontend-vue/tests/timeline.test.ts

@@ -1,29 +1,184 @@
 import { describe, expect, it } from 'vitest'
-import { buildTimeline } from '../app/utils/timeline'
+import { buildTimeline, type TimelineSend } from '../app/utils/timeline'
+import type { SendEventRow } from '../app/types/mailing'
+
+const SEND: TimelineSend = {
+	_id: 'snd_1',
+	status: 'bounced',
+	createdAt: '2026-09-09T09:59:58.000Z',
+	provider: 'Brevo',
+	providerMessageId: '<202609291429.84712@brevo>',
+	error: '550 5.1.1 Mailbox does not exist',
+}
+
+const event = (
+	id: string,
+	type: SendEventRow['type'],
+	at: string,
+	details = '{}',
+): SendEventRow => ({
+	_id: id,
+	sendId: SEND._id,
+	type,
+	at,
+	json_details: details,
+})
 
 describe('buildTimeline', () => {
-	it('orders events by time and marks problems', () => {
-		const items = buildTimeline([
-			{
-				_id: '2',
-				sendId: 's',
-				type: 'bounced',
-				at: '2026-09-09T10:01:00.000Z',
-				json_details: '{"reason":"550"}',
-			},
+	it('starts on the queued step, then orders the events by time', () => {
+		const items = buildTimeline(
+			[
+				event(
+					'2',
+					'bounced',
+					'2026-09-09T10:01:00.000Z',
+					'{"reason":"550 5.1.1"}',
+				),
+				event('1', 'sent', '2026-09-09T10:00:00.000Z'),
+			],
+			SEND,
+		)
+		expect(items.map((item) => item.type)).toEqual([
+			'queued',
+			'sent',
+			'bounced',
+		])
+		expect(items[0]).toMatchObject({ at: SEND.createdAt, isPending: false })
+	})
+
+	it('names the provider and shows its message id in mono', () => {
+		const [, sent] = buildTimeline(
+			[event('1', 'sent', '2026-09-09T10:00:00.000Z')],
+			SEND,
+		)
+		expect(sent).toMatchObject({
+			titleKey: 'dms_mailing.sends.timeline.sent_to',
+			titleParams: { provider: 'Brevo' },
+			detail: SEND.providerMessageId,
+			isDetailMono: true,
+		})
+	})
+
+	it('falls back to the generic title when the provider is unknown', () => {
+		const [, sent] = buildTimeline(
+			[event('1', 'sent', '2026-09-09T10:00:00.000Z')],
 			{
-				_id: '1',
-				sendId: 's',
-				type: 'sent',
-				at: '2026-09-09T10:00:00.000Z',
-				json_details: '{}',
+				...SEND,
+				provider: undefined,
 			},
-		])
-		expect(items.map((item) => item.type)).toEqual(['sent', 'bounced'])
-		expect(items[1]).toMatchObject({
+		)
+		expect(sent?.titleKey).toBe('dms_mailing.sends.timeline.sent')
+	})
+
+	it('keeps the raw SMTP answer of a bounce, from the event or the send', () => {
+		const fromEvent = buildTimeline(
+			[
+				event(
+					'2',
+					'bounced',
+					'2026-09-09T10:01:00.000Z',
+					'{"reason":"550 5.1.1"}',
+				),
+			],
+			SEND,
+		).at(-1)
+		expect(fromEvent).toMatchObject({
 			tone: 'error',
-			description: '550',
-			icon: 'i-ph-warning',
+			detail: '550 5.1.1',
+			isDetailMono: true,
 		})
+		const fromSend = buildTimeline(
+			[event('2', 'bounced', '2026-09-09T10:01:00.000Z')],
+			SEND,
+		).at(-1)
+		expect(fromSend?.detail).toBe(SEND.error)
+	})
+
+	it('ghosts the happy-path steps still to come', () => {
+		const items = buildTimeline(
+			[event('1', 'sent', '2026-09-09T10:00:00.000Z')],
+			{
+				...SEND,
+				status: 'sent',
+			},
+		)
+		const pending = items.filter((item) => item.isPending)
+		expect(pending.map((item) => item.type)).toEqual(['delivered', 'opened'])
+		expect(pending.every((item) => item.at === null)).toBe(true)
+	})
+
+	it('draws no step to come after a problem', () => {
+		const items = buildTimeline(
+			[event('1', 'failed', '2026-09-09T10:00:30.000Z')],
+			{
+				...SEND,
+				status: 'failed',
+			},
+		)
+		expect(items.some((item) => item.isPending)).toBe(false)
+	})
+
+	it('draws no step to come after an unsubscription', () => {
+		const items = buildTimeline(
+			[
+				event('1', 'delivered', '2026-09-09T10:00:30.000Z'),
+				event('2', 'unsubscribed', '2026-09-09T10:05:00.000Z'),
+			],
+			{ ...SEND, status: 'unsubscribed' },
+		)
+		expect(items.some((item) => item.isPending)).toBe(false)
+	})
+
+	it('calls a 4.x.x bounce temporary', () => {
+		const bounce = buildTimeline(
+			[
+				event(
+					'2',
+					'bounced',
+					'2026-09-09T10:01:00.000Z',
+					'{"reason":"452 4.2.2 The recipient mailbox is full"}',
+				),
+			],
+			SEND,
+		).at(-1)
+		expect(bounce?.titleKey).toBe('dms_mailing.sends.timeline.soft_bounce')
+		const typed = buildTimeline(
+			[
+				event(
+					'2',
+					'bounced',
+					'2026-09-09T10:01:00.000Z',
+					'{"bounceType":"hard","reason":"452 4.2.2"}',
+				),
+			],
+			SEND,
+		).at(-1)
+		expect(typed?.titleKey).toBe('dms_mailing.sends.timeline.bounced')
+	})
+
+	it('waits only for what the provider reports', () => {
+		const sent = { ...SEND, status: 'sent' as const }
+		const events = [event('1', 'sent', '2026-09-09T10:00:00.000Z')]
+		const pendingOf = (openTracking: boolean, clickTracking: boolean) =>
+			buildTimeline(events, sent, { openTracking, clickTracking })
+				.filter((item) => item.isPending)
+				.map((item) => item.type)
+		expect(pendingOf(false, false)).toEqual([])
+		expect(pendingOf(false, true)).toEqual(['delivered'])
+		expect(pendingOf(true, true)).toEqual(['delivered', 'opened'])
+	})
+
+	it('does not repeat the queued step when an event records it', () => {
+		const items = buildTimeline(
+			[event('0', 'queued', '2026-09-09T10:00:00.000Z')],
+			{
+				...SEND,
+				status: 'queued',
+			},
+		)
+		expect(items.filter((item) => item.type === 'queued')).toHaveLength(1)
+		expect(
+			items.filter((item) => item.isPending).map((item) => item.type),
+		).toEqual(['sent', 'delivered', 'opened'])
 	})
 })

package/frontend-vue/tests/tokens.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from 'vitest'
-import { splitTokens } from '../app/utils/tokens'
+import {
+	interpolateText,
+	resolveToken,
+	splitRawSegments,
+	splitTokens,
+} from '../app/utils/tokens'
+import { textPaths } from '../app/utils/paths'
+import { interpolate } from '../../src/engine/tokens'
 
 describe('splitTokens', () => {
 	it('splits text into literal and token parts', () => {
@@ -9,4 +16,75 @@ describe('splitTokens', () => {
 			{ kind: 'text', value: '!' },
 		])
 	})
+	it('flags what looks like a token but breaks the engine grammar', () => {
+		expect(splitTokens('{{user-name}} {{first name}} {{a.b[]}}')).toEqual([
+			{ kind: 'invalid', value: '{{user-name}}' },
+			{ kind: 'text', value: ' ' },
+			{ kind: 'invalid', value: '{{first name}}' },
+			{ kind: 'text', value: ' ' },
+			{ kind: 'token', value: 'a.b[]' },
+		])
+		expect(textPaths('{{user-name}} {{ok}}')).toEqual(['ok'])
+	})
+})
+
+describe('token values', () => {
+	const data = { customer: { firstName: 'Margaux' }, order: { lines: [1] } }
+	it('resolves a token against test data', () => {
+		expect(resolveToken('customer.firstName', data)).toEqual({
+			isPresent: true,
+			text: 'Margaux',
+		})
+		expect(resolveToken('order.total', data)).toEqual({
+			isPresent: false,
+			text: 'order.total',
+		})
+	})
+	it('interpolates the tokens it can and keeps the others', () => {
+		expect(
+			interpolateText('Hi {{ customer.firstName }}, {{order.total}}', data),
+		).toBe('Hi Margaux, {{order.total}}')
+	})
+	it('blanks a missing token in send mode, as a real e-mail', () => {
+		expect(
+			interpolateText(
+				'Hi {{ customer.firstName }}{{order.total}}!',
+				data,
+				'send',
+			),
+		).toBe('Hi Margaux!')
+	})
+	it('keeps the raw spelling of each token for the highlight layer', () => {
+		expect(splitRawSegments('a {{ x.y }}b {{x-y}}')).toEqual([
+			{ kind: 'text', raw: 'a ', value: 'a ' },
+			{ kind: 'token', raw: '{{ x.y }}', value: 'x.y' },
+			{ kind: 'text', raw: 'b ', value: 'b ' },
+			{ kind: 'invalid', raw: '{{x-y}}', value: '{{x-y}}' },
+		])
+	})
+})
+
+describe('parity with the send engine', () => {
+	const data = {
+		'user-name': 'Bob',
+		'first name': 'Ann',
+		user: { name: 'Zoe' },
+		order: { total: '€20', lines: ['a', 'b'] },
+		tags: ['a', 'b'],
+		count: 0,
+		flag: false,
+	}
+	const samples = [
+		'Hi {{user-name}} / {{first name}}',
+		'{{ user.name }} {{user.missing}}',
+		'{{order}} / {{tags}} / {{order.lines[]}}',
+		'{{count}}-{{flag}} {{{user.name}}} {{}} {{ }}',
+		'Line one\nLine two {{order.total}}',
+	]
+	it.each(samples)('prints %j as the engine does', (sample) => {
+		expect(interpolateText(sample, data)).toBe(interpolate(sample, data).text)
+		expect(interpolateText(sample, data, 'send')).toBe(
+			interpolate(sample, data, 'send').text,
+		)
+	})
 })

package/frontend-vue/tests/variable-path.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import VariablePath from '../app/components/VariablePath.vue'
+import { mount, stubNuxtGlobals } from './helpers/nuxt-globals'
+
+describe('VariablePath', () => {
+	beforeEach(() => {
+		stubNuxtGlobals()
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+	})
+
+	it('reads as the path, with a wrap point after each dot only', () => {
+		const { host, unmount } = mount(VariablePath, { path: 'order.number' })
+		const code = host.querySelector('code')
+		expect(code?.textContent).toBe('order.number')
+		expect(code?.querySelectorAll('wbr')).toHaveLength(2)
+		expect(code?.className).not.toContain('break-all')
+		unmount()
+	})
+})

package/frontend-vue/tests/variable-types.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { VARIABLE_TYPES } from '../app/types/mailing'
+import {
+	variableTypeItems,
+	variableTypeLabelKey,
+} from '../app/utils/variable-types'
+
+describe('variable types', () => {
+	it('labels each stored type with its i18n key', () => {
+		expect(variableTypeLabelKey('money')).toBe(
+			'dms_mailing.variable_types.money',
+		)
+		const items = variableTypeItems((key) => `t:${key}`)
+		expect(items.map((item) => item.value)).toEqual(VARIABLE_TYPES)
+		expect(items[0]).toEqual({
+			value: 'string',
+			label: 't:dms_mailing.variable_types.string',
+		})
+	})
+})

package/frontend-vue/tests/variables.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest'
-import { mergeVariables } from '../app/utils/variables'
-import type { VariableDefinition } from '../app/types/mailing'
+import {
+	countPathUsages,
+	inferVariableType,
+	isValidVariablePath,
+	mergeVariables,
+	renameVariablePath,
+	suggestVariablePath,
+} from '../app/utils/variables'
+import type { TemplateContent, VariableDefinition } from '../app/types/mailing'
 
 const DECLARED: VariableDefinition[] = [
 	{ path: 'order.total', type: 'money', required: true },
@@ -44,3 +51,84 @@ describe('mergeVariables', () => {
 		])
 	})
 })
+
+function usingContent(): TemplateContent {
+	return {
+		locales: {
+			en: {
+				subject: 'Order {{ order.id }}',
+				preheader: '',
+				blocks: [
+					{
+						id: 'p1',
+						type: 'paragraph',
+						text: 'Total {{order.total}}, again {{ order.total }}',
+						align: 'left',
+						visibleIf: { path: 'order.total', operator: 'gt', value: '0' },
+					},
+					{
+						id: 'if1',
+						type: 'if',
+						condition: { path: 'contact.vip', operator: 'truthy', value: '' },
+						children: [
+							{
+								id: 'l1',
+								type: 'list',
+								source: 'order.lines',
+								labelPath: 'label',
+								valuePath: 'total',
+								visibleIf: null,
+							},
+						],
+						elseChildren: null,
+						visibleIf: null,
+					},
+				],
+			},
+			fr: {
+				subject: '',
+				preheader: '{{order.total}}',
+				blocks: [
+					{ id: 'c1', type: 'code', text: '{{order.totals}}', visibleIf: null },
+				],
+			},
+		},
+	}
+}
+
+describe('variable paths in the content', () => {
+	it('validates a path and suggests a valid one', () => {
+		expect(isValidVariablePath('first name')).toBe(false)
+		expect(isValidVariablePath('order.lines[]')).toBe(true)
+		expect(suggestVariablePath('first name')).toBe('first_name')
+		expect(suggestVariablePath(' -- ')).toBe('first_name')
+	})
+	it('counts the blocks and envelope fields using a path, every locale', () => {
+		expect(countPathUsages(usingContent(), 'order.total')).toBe(2)
+		expect(countPathUsages(usingContent(), 'order.lines')).toBe(1)
+		expect(countPathUsages(usingContent(), 'contact.vip')).toBe(1)
+		expect(countPathUsages(usingContent(), 'nothing')).toBe(0)
+	})
+	it('renames tokens, conditions and list sources in every locale', () => {
+		const content = usingContent()
+		renameVariablePath(content, 'order.total', 'order.amount')
+		renameVariablePath(content, 'order.lines', 'cart.items')
+		const [paragraph, branch] = content.locales.en!.blocks
+		expect(paragraph).toMatchObject({
+			text: 'Total {{order.amount}}, again {{order.amount}}',
+			visibleIf: { path: 'order.amount' },
+		})
+		expect(branch?.type === 'if' && branch.children[0]).toMatchObject({
+			source: 'cart.items',
+		})
+		expect(content.locales.fr).toMatchObject({
+			preheader: '{{order.amount}}',
+			blocks: [{ text: '{{order.totals}}' }],
+		})
+	})
+	it('infers the type a declaration likely has', () => {
+		expect(inferVariableType(usingContent(), 'order.lines')).toBe('array')
+		expect(inferVariableType(usingContent(), 'contact.vip')).toBe('boolean')
+		expect(inferVariableType(usingContent(), 'order.total')).toBe('string')
+	})
+})

package/frontend-vue/tests/version-history.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import type { TemplateChange } from '../app/types/mailing'
+import {
+	changeSummary,
+	formatVersionDate,
+	isLiveVersion,
+} from '../app/utils/version-history'
+
+const translate = (key: string, params: Record<string, string> = {}) =>
+	`${key.split('.').at(-1)}${params.variable ? `:${params.variable}` : ''}`
+
+describe('version history', () => {
+	it('names the first changes of a version and counts the rest', () => {
+		const changes: TemplateChange[] = [
+			{ locale: 'en', kind: 'subject' },
+			{ locale: 'fr', kind: 'locale_added' },
+			{ locale: '', kind: 'variable_added', variable: 'order.id' },
+		]
+		expect(changeSummary({ changes }, translate)).toEqual({
+			named: ['EN · subject', 'FR · locale_added'],
+			more: 1,
+		})
+		expect(changeSummary({ changes: [] }, translate)).toEqual({
+			named: [],
+			more: 0,
+		})
+	})
+
+	it('marks live only the version customers receive', () => {
+		expect(isLiveVersion(3, 3, 'live')).toBe(true)
+		expect(isLiveVersion(2, 3, 'live')).toBe(false)
+		expect(isLiveVersion(3, 3, 'draft')).toBe(false)
+	})
+
+	it('dates a version to the minute, on a 24-hour clock', () => {
+		const text = formatVersionDate('2026-10-07T15:04:00Z', 'en-GB')
+		expect(text).toMatch(/2026/)
+		expect(text).not.toMatch(/PM|AM/i)
+		expect(formatVersionDate('not a date', 'en-GB')).toBe('')
+	})
+})