@antelopejs/dms-mailing 0.3.4 → 0.4.1

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { exampleVariables, sendSnippet } from '../app/utils/send-snippet'
+
+describe('exampleVariables', () => {
+	it('nests the paths, system URLs included, with test values or examples', () => {
+		expect(
+			exampleVariables({
+				slug: 'password-reset',
+				locale: 'en',
+				variables: [
+					{ path: 'user.firstName', type: 'string' },
+					{ path: 'reset.url', type: 'url' },
+					{ path: 'order.items[].name', type: 'string' },
+					{ path: 'unsubscribeUrl', type: 'url' },
+					{ path: 'user', type: 'string' },
+				],
+				testData: { user: { firstName: 'Sofie' } },
+			}),
+		).toEqual({
+			user: { firstName: 'Sofie' },
+			reset: { url: 'https://…' },
+			order: { items: [] },
+			unsubscribeUrl: 'https://…',
+		})
+	})
+})
+
+describe('sendSnippet', () => {
+	it('writes a call with every required parameter', () => {
+		const snippet = sendSnippet({
+			slug: 'password-reset',
+			locale: 'fr',
+			variables: [{ path: 'reset.url', type: 'url' }],
+			testData: {},
+		})
+		expect(snippet).toBe(
+			[
+				'await SendTemplate("password-reset", {',
+				'  tenantId,',
+				'  to: customer.email,',
+				'  locale: "fr",',
+				'  variables: {',
+				'    reset: {',
+				'      url: "https://…"',
+				'    }',
+				'  },',
+				'});',
+			].join('\n'),
+		)
+	})
+})

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

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { formatLatency, isSlowLatency } from '../app/utils/send-stats'
+
+describe('formatLatency', () => {
+	it('prints milliseconds, seconds past 5 s, a dash when unknown', () => {
+		expect(formatLatency(204, 'en-GB')).toBe('204 ms')
+		expect(formatLatency(30000, 'en-GB')).toBe('30.0 s')
+		expect(formatLatency(null, 'en-GB')).toBe('—')
+		expect(isSlowLatency(30000)).toBe(true)
+		expect(isSlowLatency(204)).toBe(false)
+	})
+})

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest'
+import {
+	buildSendData,
+	initialSendValues,
+	missingRequiredPaths,
+	sendFields,
+} from '../app/utils/send-values'
+import { sendLogRoute } from '../app/utils/send-link'
+
+const TEST_DATA = {
+	user: { firstName: 'Julie', isPro: true },
+	order: { lines: [{ label: 'Chair' }] },
+	promo: 'AUTUMN',
+}
+
+describe('real send values', () => {
+	const fields = sendFields(
+		[
+			{ path: 'user.firstName', type: 'string', required: true },
+			{ path: 'reset.url', type: 'url', required: true },
+			{ path: 'order.lines[]', type: 'array', required: false },
+		],
+		['user.firstName', 'user.isPro', 'promo', 'order.lines'],
+		TEST_DATA,
+	)
+
+	it('lists the declared variables, then the undeclared ones the content uses', () => {
+		expect(fields).toEqual([
+			{ path: 'user.firstName', required: true, kind: 'text' },
+			{ path: 'reset.url', required: true, kind: 'text' },
+			{ path: 'order.lines', required: false, kind: 'list' },
+			{ path: 'user.isPro', required: false, kind: 'boolean' },
+			{ path: 'promo', required: false, kind: 'text' },
+		])
+	})
+
+	it('starts from the test data and names the required values still missing', () => {
+		const values = initialSendValues(fields, TEST_DATA)
+		expect(values).toEqual({
+			'user.firstName': 'Julie',
+			'reset.url': '',
+			'order.lines': [{ label: 'Chair' }],
+			'user.isPro': true,
+			promo: 'AUTUMN',
+		})
+		expect(missingRequiredPaths(fields, values)).toEqual(['reset.url'])
+		expect(
+			missingRequiredPaths(fields, { ...values, 'reset.url': '  ' }),
+		).toEqual(['reset.url'])
+	})
+
+	it('nests the values given into the data of the send', () => {
+		const values = {
+			...initialSendValues(fields, TEST_DATA),
+			'reset.url': 'https://x.test/r',
+			promo: '',
+		}
+		expect(buildSendData(fields, values)).toEqual({
+			user: { firstName: 'Julie', isPro: true },
+			reset: { url: 'https://x.test/r' },
+			order: { lines: [{ label: 'Chair' }] },
+		})
+	})
+
+	it('keeps a typed child value over the object the content also prints', () => {
+		const orderData = {
+			user: { firstName: 'Julie' },
+			order: { number: 'A-42', total: 12 },
+			meta: { source: 'shop' },
+		}
+		const orderFields = sendFields(
+			[{ path: 'order.number', type: 'string', required: true }],
+			['order', 'order.number', 'user', 'user.firstName', 'meta'],
+			orderData,
+		)
+		expect(orderFields).toEqual([
+			{ path: 'order.number', required: true, kind: 'text' },
+			{ path: 'user.firstName', required: false, kind: 'text' },
+			{ path: 'meta', required: false, kind: 'object' },
+		])
+		const values = {
+			...initialSendValues(orderFields, orderData),
+			'order.number': 'B-7',
+		}
+		expect(values.meta).toEqual({ source: 'shop' })
+		expect(buildSendData(orderFields, values)).toEqual({
+			order: { number: 'B-7' },
+			user: { firstName: 'Julie' },
+			meta: { source: 'shop' },
+		})
+	})
+
+	it('applies the parent object first and never changes the test data', () => {
+		const data = { order: { number: 'A-42', total: 12 } }
+		const parentFirst = [
+			{ path: 'order.number', required: true, kind: 'text' as const },
+			{ path: 'order', required: false, kind: 'object' as const },
+		]
+		expect(
+			buildSendData(parentFirst, { 'order.number': 'B-7', order: data.order }),
+		).toEqual({ order: { number: 'B-7', total: 12 } })
+		expect(data.order.number).toBe('A-42')
+	})
+})
+
+describe('send log link', () => {
+	it('opens the one send that went out, the log otherwise', () => {
+		expect(sendLogRoute([{ sendId: 's1', status: 'sent' }])).toEqual({
+			path: '/modules/mailing/sends',
+			query: { record: 's1' },
+		})
+		expect(
+			sendLogRoute([
+				{ sendId: 's1', status: 'sent' },
+				{ sendId: 's2', status: 'sent' },
+			]),
+		).toEqual({ path: '/modules/mailing/sends', query: {} })
+	})
+})

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

@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { isTypingTarget, matchShortcut } from '../app/utils/shortcuts'
+import type { KeyStroke } from '../app/utils/shortcuts'
+
+const stroke = (key: string, extra: Partial<KeyStroke> = {}): KeyStroke => ({
+	key,
+	metaKey: false,
+	ctrlKey: false,
+	shiftKey: false,
+	altKey: false,
+	...extra,
+})
+
+describe('matchShortcut', () => {
+	it('matches ⌘ and Ctrl alike for the modifier shortcuts', () => {
+		expect(matchShortcut(stroke('s', { metaKey: true }), false)).toBe('save')
+		expect(matchShortcut(stroke('s', { ctrlKey: true }), false)).toBe('save')
+		expect(matchShortcut(stroke('Enter', { metaKey: true }), false)).toBe(
+			'publish',
+		)
+		expect(matchShortcut(stroke('d', { ctrlKey: true }), false)).toBe(
+			'duplicate',
+		)
+	})
+	it('tells undo from redo by Shift', () => {
+		expect(matchShortcut(stroke('z', { metaKey: true }), false)).toBe('undo')
+		expect(
+			matchShortcut(stroke('Z', { metaKey: true, shiftKey: true }), false),
+		).toBe('redo')
+		expect(matchShortcut(stroke('y', { ctrlKey: true }), false)).toBe('redo')
+	})
+	it('matches the single keys, whatever their case', () => {
+		expect(matchShortcut(stroke('t'), false)).toBe('test')
+		expect(matchShortcut(stroke('T', { shiftKey: true }), false)).toBe('test')
+		expect(matchShortcut(stroke('/'), false)).toBe('search')
+		expect(matchShortcut(stroke('Backspace'), false)).toBe('delete')
+		expect(matchShortcut(stroke('Delete'), false)).toBe('delete')
+		expect(matchShortcut(stroke('Escape'), false)).toBe('escape')
+	})
+	it('leaves single keys alone while typing, but keeps save and publish', () => {
+		expect(matchShortcut(stroke('t'), true)).toBeNull()
+		expect(matchShortcut(stroke('Backspace'), true)).toBeNull()
+		expect(matchShortcut(stroke('Escape'), true)).toBeNull()
+		expect(matchShortcut(stroke('z', { metaKey: true }), true)).toBeNull()
+		expect(matchShortcut(stroke('s', { metaKey: true }), true)).toBe('save')
+		expect(matchShortcut(stroke('Enter', { ctrlKey: true }), true)).toBe(
+			'publish',
+		)
+	})
+	it('ignores Alt combinations and unknown keys', () => {
+		expect(
+			matchShortcut(stroke('s', { metaKey: true, altKey: true }), false),
+		).toBeNull()
+		expect(matchShortcut(stroke('t', { metaKey: true }), false)).toBeNull()
+		expect(matchShortcut(stroke('x'), false)).toBeNull()
+	})
+})
+
+describe('isTypingTarget', () => {
+	it('recognises text fields and editable content', () => {
+		const input = document.createElement('input')
+		const checkbox = document.createElement('input')
+		checkbox.type = 'checkbox'
+		const editable = document.createElement('div')
+		editable.setAttribute('contenteditable', 'true')
+		const child = document.createElement('span')
+		editable.appendChild(child)
+		expect(isTypingTarget(input)).toBe(true)
+		expect(isTypingTarget(document.createElement('textarea'))).toBe(true)
+		expect(isTypingTarget(checkbox)).toBe(false)
+		expect(isTypingTarget(child)).toBe(true)
+		expect(isTypingTarget(document.createElement('button'))).toBe(false)
+		expect(isTypingTarget(null)).toBe(false)
+	})
+})

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import {
+	MAX_NAME_LENGTH,
+	MAX_SLUG_LENGTH,
+	fitName,
+	freeSlug,
+	slugify,
+	validateName,
+	validateSlug,
+} from '../app/utils/slug'
+
+const NONE = new Set<string>()
+
+describe('slugify', () => {
+	it('derives an ASCII dashed slug from a name', () => {
+		expect(slugify('Quote accepted')).toBe('quote-accepted')
+		expect(slugify('Réinitialiser le mot de passe')).toBe(
+			'reinitialiser-le-mot-de-passe',
+		)
+		expect(slugify('  Autumn sale — 20% off!  ')).toBe('autumn-sale-20-off')
+	})
+
+	it('answers an empty slug for a name without letters or digits', () => {
+		expect(slugify('—')).toBe('')
+	})
+
+	it('cuts to the maximum length without a trailing dash', () => {
+		const slug = slugify(`${'a'.repeat(MAX_SLUG_LENGTH - 1)} b`)
+		expect(slug.length).toBeLessThanOrEqual(MAX_SLUG_LENGTH)
+		expect(slug.endsWith('-')).toBe(false)
+	})
+})
+
+describe('validateSlug', () => {
+	it('accepts a well-formed free slug', () => {
+		expect(validateSlug('order-confirmed', NONE)).toBeNull()
+		expect(validateSlug('2fa-code', NONE)).toBeNull()
+	})
+
+	it('names what is wrong', () => {
+		expect(validateSlug('', NONE)).toBe('required')
+		expect(validateSlug('-order', NONE)).toBe('format')
+		expect(validateSlug('Order', NONE)).toBe('format')
+		expect(validateSlug('order_confirmed', NONE)).toBe('format')
+		expect(validateSlug('a'.repeat(MAX_SLUG_LENGTH + 1), NONE)).toBe('too_long')
+		expect(validateSlug('welcome', new Set(['welcome']))).toBe('taken')
+	})
+})
+
+describe('validateName', () => {
+	it('requires a non-blank name under the maximum length', () => {
+		expect(validateName('Welcome')).toBeNull()
+		expect(validateName('   ')).toBe('required')
+		expect(validateName('a'.repeat(MAX_NAME_LENGTH + 1))).toBe('too_long')
+	})
+})
+
+describe('freeSlug', () => {
+	it('keeps a free slug and numbers a taken one', () => {
+		expect(freeSlug('welcome-copy', NONE)).toBe('welcome-copy')
+		expect(freeSlug('welcome-copy', new Set(['welcome-copy']))).toBe(
+			'welcome-copy-2',
+		)
+		expect(
+			freeSlug('welcome-copy', new Set(['welcome-copy', 'welcome-copy-2'])),
+		).toBe('welcome-copy-3')
+	})
+
+	it('cuts the base so a numbered slug stays within the limit', () => {
+		const base = 'a'.repeat(MAX_SLUG_LENGTH)
+		const slug = freeSlug(base, new Set([base]))
+		expect(slug).toHaveLength(MAX_SLUG_LENGTH)
+		expect(slug.endsWith('-2')).toBe(true)
+		expect(validateSlug(slug, new Set([base]))).toBeNull()
+	})
+})
+
+describe('fitName', () => {
+	const copy = (name: string) => `${name} (copy)`
+
+	it('keeps a name that fits and cuts the inner name of one that does not', () => {
+		expect(fitName('Welcome', copy)).toBe('Welcome (copy)')
+		const long = fitName('a'.repeat(MAX_NAME_LENGTH), copy)
+		expect(long).toHaveLength(MAX_NAME_LENGTH)
+		expect(long.endsWith(' (copy)')).toBe(true)
+		expect(validateName(long)).toBeNull()
+	})
+})

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

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import { SEND_STATUS_TONES, sendFooterActions } from '../app/utils/send-actions'
+import {
+	isSuppressedStatus,
+	reasonKey,
+	suppressedReasonOf,
+	suppressionNotice,
+	suppressionRoute,
+	type SuppressionSummary,
+} from '../app/utils/suppression'
+import { buildTimeline } from '../app/utils/timeline'
+import type { SendEventRow, SendStatus } from '../app/types/mailing'
+
+const ENTRY: SuppressionSummary = {
+	id: 'sup_1',
+	email: 'ana@example.com',
+	reason: 'complaint',
+	createdAt: '2026-10-01T10:00:00.000Z',
+	sendId: 'snd_1',
+}
+
+const WORDING = {
+	date: (iso: string) => `on ${iso.slice(0, 10)}`,
+	reason: (reason: string) => `[${reason}]`,
+}
+
+/** A send of the log nothing was sent for, as the API answers it. */
+const SUPPRESSED = 'suppressed' as SendStatus
+
+const ids = (send: Parameters<typeof sendFooterActions>[0]) =>
+	sendFooterActions(send).map((action) => action.id)
+
+describe('suppressionNotice', () => {
+	it('says a suppressed send was not sent, and links to the list', () => {
+		const notice = suppressionNotice(
+			{ status: 'suppressed', recipientEmail: 'ana@example.com' },
+			ENTRY,
+			WORDING,
+		)
+		expect(notice).toMatchObject({
+			tone: 'warning',
+			titleKey: 'dms_mailing.suppressions.notice.not_sent.title',
+			hasListLink: true,
+			params: { date: 'on 2026-10-01', reason: '[complaint]' },
+		})
+	})
+
+	it('tells a suppressed send whose address was reactivated since', () => {
+		const notice = suppressionNotice(
+			{ status: 'suppressed', recipientEmail: 'ana@example.com' },
+			null,
+			WORDING,
+		)
+		expect(notice).toMatchObject({
+			tone: 'success',
+			titleKey: 'dms_mailing.suppressions.notice.reactivated.title',
+			hasListLink: false,
+		})
+	})
+
+	it('tells that a sent address receives nothing any more', () => {
+		expect(
+			suppressionNotice(
+				{ status: 'spam', recipientEmail: 'ana@example.com' },
+				ENTRY,
+				WORDING,
+			)?.titleKey,
+		).toBe('dms_mailing.suppressions.notice.on_list.title')
+		expect(
+			suppressionNotice(
+				{ status: 'delivered', recipientEmail: 'ana@example.com' },
+				null,
+				WORDING,
+			),
+		).toBeNull()
+	})
+
+	it('links to the list narrowed to the address', () => {
+		expect(suppressionRoute('ana@example.com')).toEqual({
+			path: '/modules/mailing/suppressions',
+			query: { email: 'ana@example.com' },
+		})
+		expect(suppressionRoute(' Ana@Example.com ').query).toEqual({
+			email: 'ana@example.com',
+		})
+		expect(reasonKey('hard_bounce')).toBe(
+			'dms_mailing.suppressions.reasons.hard_bounce',
+		)
+		expect(isSuppressedStatus('suppressed')).toBe(true)
+		expect(isSuppressedStatus('failed')).toBe(false)
+	})
+})
+
+describe('a suppressed send in the drawer', () => {
+	it('offers no send again while the address is suppressed', () => {
+		expect(ids({ status: SUPPRESSED })).toEqual(['rendering', 'copy_address'])
+		expect(ids({ status: SUPPRESSED, isAddressSuppressed: true })).toEqual([
+			'rendering',
+			'copy_address',
+		])
+	})
+
+	it('offers no send again of a failure whose address is suppressed', () => {
+		expect(ids({ status: 'failed', isAddressSuppressed: true })).toEqual([
+			'rendering',
+			'copy_address',
+		])
+		expect(ids({ status: 'failed', isAddressSuppressed: false })).toEqual([
+			'rendering',
+			'send_again',
+		])
+		expect(ids({ status: 'bounced', isAddressSuppressed: true })).toContain(
+			'fix_address',
+		)
+	})
+
+	it('offers to send again once the address is reactivated', () => {
+		expect(ids({ status: SUPPRESSED, isAddressSuppressed: false })).toEqual([
+			'rendering',
+			'send_again',
+		])
+		expect(SEND_STATUS_TONES.suppressed).toBe('neutral')
+	})
+
+	it('draws one step, without a queued one nor a raw reason', () => {
+		const events: SendEventRow[] = [
+			{
+				_id: 'evt_1',
+				sendId: 'snd_2',
+				type: SUPPRESSED,
+				at: '2026-10-02T10:00:00.000Z',
+				json_details: JSON.stringify({
+					reason: '$dms_mailing.errors.suppressed_complaint',
+				}),
+			},
+		]
+		const steps = buildTimeline(events, {
+			_id: 'snd_2',
+			status: SUPPRESSED,
+			createdAt: '2026-10-02T10:00:00.000Z',
+		})
+		expect(steps.map((step) => step.type)).toEqual(['suppressed'])
+		expect(steps[0]).toMatchObject({
+			titleKey: 'dms_mailing.sends.timeline.suppressed',
+			detail: '',
+			isPending: false,
+		})
+	})
+})
+
+describe('the suppression list narrowed by a link', () => {
+	it('reads the reason a suppressed send keeps, nothing for another error', () => {
+		expect(suppressedReasonOf('$dms_mailing.errors.suppressed.manual')).toBe(
+			'manual',
+		)
+		expect(suppressedReasonOf('ECONNREFUSED')).toBe(null)
+		expect(suppressedReasonOf(undefined)).toBe(null)
+	})
+})

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import type { FooterBlock, LocaleContent } from '../app/types/mailing'
+import {
+	contentSystemPaths,
+	hasFooterLinksByDefault,
+	hasSystemUrl,
+	systemVariableChecks,
+	systemVariables,
+} from '../app/utils/system-variables'
+import { createBlock } from '../app/utils/blocks/factory'
+
+const footer = (overrides: Partial<FooterBlock> = {}): FooterBlock => ({
+	id: 'f',
+	type: 'footer',
+	text: '',
+	unsubscribeLabel: 'Unsubscribe',
+	preferencesLabel: 'Preferences',
+	visibleIf: null,
+	...overrides,
+})
+
+const page = (block: FooterBlock, subject = 'Hello'): LocaleContent => ({
+	subject,
+	preheader: '',
+	blocks: [block],
+})
+
+const content = (block: FooterBlock, subject?: string) => ({
+	locales: { en: page(block, subject) },
+})
+
+describe('contentSystemPaths', () => {
+	it('declares the URL of every footer link with a label', () => {
+		expect(contentSystemPaths(content(footer()))).toEqual([
+			'unsubscribeUrl',
+			'preferencesUrl',
+		])
+		expect(
+			contentSystemPaths(content(footer({ unsubscribeLabel: '  ' }))),
+		).toEqual(['preferencesUrl'])
+	})
+
+	it('counts a system URL used as a token', () => {
+		const bare = footer({ unsubscribeLabel: '', preferencesLabel: '' })
+		expect(
+			contentSystemPaths(content(bare, 'Leave: {{unsubscribeUrl}}')),
+		).toEqual(['unsubscribeUrl'])
+	})
+
+	it('finds a footer inside a condition', () => {
+		const nested = {
+			locales: {
+				en: {
+					subject: '',
+					preheader: '',
+					blocks: [
+						{
+							id: 'if',
+							type: 'if' as const,
+							condition: { path: 'x', operator: 'truthy' as const, value: '' },
+							children: [footer({ preferencesLabel: '' })],
+							elseChildren: null,
+							visibleIf: null,
+						},
+					],
+				},
+			},
+		}
+		expect(contentSystemPaths(nested)).toEqual(['unsubscribeUrl'])
+	})
+})
+
+describe('systemVariables', () => {
+	it('types them as urls, required for a marketing template only', () => {
+		expect(systemVariables(content(footer()), 'marketing')).toEqual([
+			{ path: 'unsubscribeUrl', type: 'url', required: true, system: true },
+			{ path: 'preferencesUrl', type: 'url', required: true, system: true },
+		])
+		expect(
+			systemVariables(content(footer()), 'orders').map((v) => v.required),
+		).toEqual([false, false])
+	})
+})
+
+describe('systemVariableChecks', () => {
+	it('warns about a marketing locale without an unsubscribe link', () => {
+		const bare = footer({ unsubscribeLabel: '' })
+		const checks = systemVariableChecks(content(bare), 'marketing', {
+			preferencesUrl: 'https://p',
+		})
+		expect(checks.map((check) => check.key)).toEqual([
+			'dms_mailing.editor.checks.marketing_no_unsubscribe',
+		])
+		expect(checks[0]?.params).toEqual({ locale: 'EN' })
+	})
+
+	it('warns about a required URL the test data lacks', () => {
+		const checks = systemVariableChecks(content(footer()), 'marketing', {
+			unsubscribeUrl: 'https://u',
+		})
+		expect(checks.map((check) => check.id)).toEqual(['system-preferencesUrl'])
+	})
+
+	it('stays quiet for a transactional template', () => {
+		expect(systemVariableChecks(content(footer()), 'orders', {})).toEqual([])
+	})
+})
+
+describe('footer links by category', () => {
+	it('keeps the links of uncategorised and marketing footers only', () => {
+		expect(hasFooterLinksByDefault(null)).toBe(true)
+		expect(hasFooterLinksByDefault('marketing')).toBe(true)
+		expect(hasFooterLinksByDefault('billing')).toBe(false)
+	})
+
+	it('creates a transactional footer without links', () => {
+		const block = createBlock('footer', { locale: 'fr', category: 'orders' })
+		expect(block).toMatchObject({ unsubscribeLabel: '', preferencesLabel: '' })
+		const marketing = createBlock('footer', {
+			locale: 'fr',
+			category: 'marketing',
+		})
+		expect(marketing).toMatchObject({ unsubscribeLabel: 'Se désinscrire' })
+	})
+
+	it('reads a URL from preview data', () => {
+		expect(
+			hasSystemUrl({ unsubscribeUrl: 'https://u' }, 'unsubscribeUrl'),
+		).toBe(true)
+		expect(hasSystemUrl({ unsubscribeUrl: ' ' }, 'unsubscribeUrl')).toBe(false)
+		expect(hasSystemUrl(null, 'unsubscribeUrl')).toBe(false)
+	})
+})