@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/frontend-vue/tests/overview-gate.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, onBeforeUnmount, ref } from 'vue'
+import OverviewGate from '../app/components/OverviewGate.vue'
+import type { SetupFacts } from '../app/utils/overview-setup'
+import { flush, mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+
+const api = { setupFacts: vi.fn() }
+const hidesPeriod = ref(false)
+
+vi.mock('../app/composables/useMailingApi', () => ({
+	useMailingApi: () => api,
+}))
+
+vi.mock('../app/composables/useOverviewSetup', () => ({
+	useSetupHidesPeriod: () => hidesPeriod,
+}))
+
+interface ButtonAction {
+	label: string
+	onClick: () => void
+}
+
+const EmptyStateStub = defineComponent({
+	props: {
+		title: { type: String, default: '' },
+		actions: { type: Array, default: () => [] },
+	},
+	setup: (props) => () =>
+		h('div', { 'data-empty-state': '' }, [
+			props.title,
+			...(props.actions as ButtonAction[]).map((action) =>
+				h('button', { onClick: action.onClick }, action.label),
+			),
+		]),
+})
+
+const ButtonStub = defineComponent({
+	props: { label: { type: String, default: '' } },
+	emits: ['click'],
+	setup:
+		(props, { emit }) =>
+		() =>
+			h('button', { onClick: () => emit('click') }, props.label),
+})
+
+const ListRowStub = defineComponent({
+	props: { title: { type: String, default: '' } },
+	setup:
+		(props, { slots }) =>
+		() =>
+			h('div', { 'data-step': props.title }, [
+				slots.leading?.(),
+				slots.trailing?.(),
+			]),
+})
+
+const Dashboard = defineComponent({
+	setup: () => () => h('div', { 'data-dashboard': '' }),
+})
+
+const Gate = defineComponent({
+	setup: () => () => h(OverviewGate, null, { default: () => h(Dashboard) }),
+})
+
+const GLOBALS = {
+	DmsCard: slotStub('DmsCard'),
+	DmsEmptyState: EmptyStateStub,
+	DmsIconWell: slotStub('DmsIconWell'),
+	DmsListRow: ListRowStub,
+	UButton: ButtonStub,
+	UPopover: slotStub('UPopover'),
+	USkeleton: slotStub('USkeleton'),
+	UIcon: slotStub('UIcon'),
+}
+
+const facts = (overrides: Partial<SetupFacts> = {}): SetupFacts => ({
+	isProviderConnected: true,
+	isSenderSet: true,
+	liveTemplateCount: 1,
+	hasTestSend: true,
+	...overrides,
+})
+
+beforeEach(() => {
+	stubNuxtGlobals()
+	vi.stubGlobal('onBeforeUnmount', onBeforeUnmount)
+	api.setupFacts.mockReset()
+	hidesPeriod.value = false
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	document.body.innerHTML = ''
+})
+
+describe('OverviewGate', () => {
+	it('mounts nothing of the dashboard before the facts are known', () => {
+		api.setupFacts.mockReturnValue(new Promise(() => undefined))
+		const { host } = mount(Gate, {}, GLOBALS)
+		expect(host.querySelector('[data-dashboard]')).toBeNull()
+		expect(host.querySelector('[data-stub="USkeleton"]')).not.toBeNull()
+	})
+
+	it('says the facts failed to load and retries', async () => {
+		api.setupFacts.mockRejectedValueOnce(new Error('500'))
+		api.setupFacts.mockResolvedValueOnce(facts())
+		const { host } = mount(Gate, {}, GLOBALS)
+		await flush()
+		expect(host.querySelector('[data-dashboard]')).toBeNull()
+		host.querySelector<HTMLButtonElement>('[data-empty-state] button')?.click()
+		await flush()
+		expect(host.querySelector('[data-dashboard]')).not.toBeNull()
+	})
+
+	it('holds the dashboard and the period back while nothing can be sent', async () => {
+		api.setupFacts.mockResolvedValue(facts({ liveTemplateCount: 0 }))
+		const { host } = mount(Gate, {}, GLOBALS)
+		await flush()
+		expect(host.querySelector('[data-dashboard]')).toBeNull()
+		expect(host.querySelectorAll('[data-step]')).toHaveLength(4)
+		expect(hidesPeriod.value).toBe(true)
+	})
+
+	it('lets an unfinished setup be resumed above the dashboard', async () => {
+		api.setupFacts.mockResolvedValue(facts({ hasTestSend: false }))
+		const { host } = mount(Gate, {}, GLOBALS)
+		await flush()
+		expect(host.querySelector('[data-dashboard]')).not.toBeNull()
+		expect(host.querySelector('[data-step]')).toBeNull()
+		const resume = [...host.querySelectorAll('button')].find((button) =>
+			button.textContent?.includes('dms_mailing.setup.resume'),
+		)
+		resume?.click()
+		await flush()
+		expect(host.querySelectorAll('[data-step]')).toHaveLength(4)
+		expect(host.querySelector('[data-dashboard]')).not.toBeNull()
+		expect(hidesPeriod.value).toBe(false)
+	})
+
+	it('offers no resume once every step is done', async () => {
+		api.setupFacts.mockResolvedValue(facts())
+		const { host } = mount(Gate, {}, GLOBALS)
+		await flush()
+		expect(host.textContent).not.toContain('dms_mailing.setup.resume')
+	})
+})

package/frontend-vue/tests/overview-setup.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import {
+	isSetupComplete,
+	needsSetup,
+	setupSteps,
+	type SetupFacts,
+} from '../app/utils/overview-setup'
+
+const facts = (overrides: Partial<SetupFacts> = {}): SetupFacts => ({
+	isProviderConnected: true,
+	isSenderSet: true,
+	liveTemplateCount: 1,
+	hasTestSend: true,
+	...overrides,
+})
+
+describe('setupSteps', () => {
+	it('lists what the workspace still has to do, without a step always done', () => {
+		const steps = setupSteps(
+			facts({ isProviderConnected: false, liveTemplateCount: 0 }),
+		)
+		expect(steps.map((step) => step.id)).toEqual([
+			'provider',
+			'sender',
+			'publish',
+			'test',
+		])
+		expect(steps.map((step) => step.state)).toEqual([
+			'current',
+			'done',
+			'todo',
+			'done',
+		])
+		expect(steps.map((step) => step.number)).toEqual([1, 2, 3, 4])
+	})
+
+	it('links the sender step to its settings section', () => {
+		const steps = setupSteps(facts({ isSenderSet: false }))
+		expect(steps.find((step) => step.state === 'current')).toMatchObject({
+			id: 'sender',
+			to: '/modules/mailing/settings#dms-form-content-section-sender',
+		})
+	})
+
+	// The provider is set in the project's configuration: no button leads to
+	// a read-only field.
+	it('offers no destination for the provider step', () => {
+		const provider = setupSteps(facts({ isProviderConnected: false }))[0]
+		expect(provider?.to).toBeUndefined()
+	})
+
+	it('ticks the template steps on a live template and a test send, not a draft', () => {
+		const steps = setupSteps(
+			facts({ liveTemplateCount: 0, hasTestSend: false }),
+		)
+		expect(
+			steps.filter((step) => step.state !== 'done').map((step) => step.id),
+		).toEqual(['publish', 'test'])
+	})
+})
+
+describe('needsSetup', () => {
+	it('holds the dashboard back until a provider and a live template exist', () => {
+		expect(needsSetup(facts({ isProviderConnected: false }))).toBe(true)
+		expect(needsSetup(facts({ liveTemplateCount: 0 }))).toBe(true)
+		expect(needsSetup(facts({ isSenderSet: false, hasTestSend: false }))).toBe(
+			false,
+		)
+	})
+})
+
+describe('isSetupComplete', () => {
+	it('is complete only once every step is done', () => {
+		expect(isSetupComplete(facts())).toBe(true)
+		expect(isSetupComplete(facts({ hasTestSend: false }))).toBe(false)
+		expect(isSetupComplete(facts({ isSenderSet: false }))).toBe(false)
+	})
+})

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

@@ -3,7 +3,10 @@ import type { Block } from '../app/types/mailing'
 import {
 	collectContentPaths,
 	collectPaths,
+	isPresent,
+	pathBreakSegments,
 	pathsInBlocks,
+	readPath,
 } from '../app/utils/paths'
 
 const blocks: Block[] = [
@@ -126,3 +129,23 @@ describe('collectContentPaths', () => {
 		expect(collectContentPaths(content)).toEqual(['real.one'])
 	})
 })
+
+describe('readPath', () => {
+	it('reads nested values and array paths like the engine', () => {
+		const data = { order: { lines: [1, 2], total: 0, note: null } }
+		expect(readPath(data, 'order.total')).toBe(0)
+		expect(readPath(data, 'order.lines[]')).toEqual([1, 2])
+		expect(readPath(data, ' order.missing.deep ')).toBeUndefined()
+		expect(readPath(data, 'constructor')).toBeUndefined()
+		expect(isPresent(readPath(data, 'order.note'))).toBe(false)
+		expect(isPresent(readPath(data, 'order.total'))).toBe(true)
+	})
+})
+
+describe('pathBreakSegments', () => {
+	it('cuts a path after each dot, so it wraps between names', () => {
+		expect(pathBreakSegments('order.number')).toEqual(['order.', 'number'])
+		expect(pathBreakSegments('items[].name')).toEqual(['items[].', 'name'])
+		expect(pathBreakSegments('firstName')).toEqual(['firstName'])
+	})
+})

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

@@ -1,13 +1,62 @@
 import { describe, expect, it } from 'vitest'
-import { periodQuery } from '../app/utils/period'
-
-describe('periodQuery', () => {
-	it('serialises a period state into the query the backend expects', () => {
-		const from = new Date('2026-08-10T00:00:00.000Z')
-		const to = new Date('2026-09-09T00:00:00.000Z')
-		expect(periodQuery({ range: { from, to }, compareRange: null })).toEqual({
-			from: from.toISOString(),
-			to: to.toISOString(),
-		})
+import {
+	clampRetention,
+	formatClock,
+	isWithinADay,
+	minutesSince,
+	presetShortLabelKey,
+	RETENTION_CUSTOM,
+	retentionChoice,
+} from '../app/utils/period'
+
+describe('formatClock', () => {
+	it('reads a 24-hour clock whatever the locale', () => {
+		const afternoon = new Date(2026, 9, 11, 17, 5)
+		expect(formatClock(afternoon, 'en')).toBe('17:05')
+		expect(formatClock(afternoon, 'fr-FR')).toBe('17:05')
+	})
+})
+
+describe('presetShortLabelKey', () => {
+	it('maps a preset id onto an i18n key', () => {
+		expect(presetShortLabelKey('last-24h')).toBe(
+			'dms_mailing.period.short.last_24h',
+		)
+		expect(presetShortLabelKey('last-30-days')).toBe(
+			'dms_mailing.period.short.last_30_days',
+		)
+	})
+})
+
+describe('minutesSince', () => {
+	const now = new Date('2026-09-09T10:35:00.000Z')
+	it('counts whole minutes', () => {
+		expect(minutesSince('2026-09-09T10:00:00.000Z', now)).toBe(35)
+	})
+	it('answers 0 for a missing or future date', () => {
+		expect(minutesSince(null, now)).toBe(0)
+		expect(minutesSince('2026-09-09T11:00:00.000Z', now)).toBe(0)
+	})
+})
+
+describe('isWithinADay', () => {
+	const now = new Date('2026-09-09T22:00:00.000Z')
+	it('says tonight for a run within 24 hours', () => {
+		expect(isWithinADay('2026-09-10T03:15:00.000Z', now)).toBe(true)
+		expect(isWithinADay('2026-09-11T03:15:00.000Z', now)).toBe(false)
+	})
+})
+
+describe('retention presets', () => {
+	it('picks the preset segment, else custom', () => {
+		expect(retentionChoice(90)).toBe('90')
+		expect(retentionChoice(45)).toBe(RETENTION_CUSTOM)
+		expect(retentionChoice(null)).toBe(RETENTION_CUSTOM)
+	})
+	it('brings a typed value between 1 day and 10 years', () => {
+		expect(clampRetention(0)).toBe(1)
+		expect(clampRetention(5000)).toBe(3650)
+		expect(clampRetention(12.6)).toBe(13)
+		expect(clampRetention(Number.NaN)).toBe(1)
 	})
 })

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

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest'
+import {
+	describeProblem,
+	problemEventReason,
+	problemTone,
+	type ProblemSend,
+} from '../app/utils/problems'
+
+const send = (patch: Partial<ProblemSend>): ProblemSend => ({
+	status: 'bounced',
+	error: '',
+	recipientEmail: 'procurement@stark.com',
+	provider: 'Brevo',
+	...patch,
+})
+
+describe('describeProblem', () => {
+	it('has nothing to say about a send that went through', () => {
+		expect(describeProblem(send({ status: 'delivered' }))).toBeNull()
+		expect(describeProblem(send({ status: 'queued' }))).toBeNull()
+	})
+
+	it.each([
+		['550 5.1.1 Mailbox does not exist', 'address_missing'],
+		['User unknown', 'address_missing'],
+		['452 4.2.2 Mailbox full', 'mailbox_full'],
+		['552 Quota exceeded', 'mailbox_full'],
+		['554 5.7.1 Message rejected as spam', 'rejected_spam'],
+		['421 Try again later', 'rejected'],
+	])('reads the bounce "%s" as %s', (error, kind) => {
+		expect(describeProblem(send({ error }))?.kind).toBe(kind)
+	})
+
+	it('reads a provider timeout as safe to send again', () => {
+		const problem = describeProblem(
+			send({ status: 'failed', error: 'Provider timeout after 30 s' }),
+		)
+		expect(problem).toMatchObject({
+			kind: 'provider_timeout',
+			icon: 'i-ph-plugs',
+			titleKey: 'dms_mailing.sends.problems.provider_timeout.title',
+			params: { provider: 'Brevo' },
+		})
+	})
+
+	it.each([
+		['connect ECONNREFUSED 127.0.0.1:1025', 'provider_unreachable'],
+		['getaddrinfo ENOTFOUND smtp.example.test', 'provider_unreachable'],
+		['connect EHOSTUNREACH 10.0.0.9:587', 'provider_unreachable'],
+		['read ECONNRESET', 'provider_unreachable'],
+		['connect ETIMEDOUT 10.0.0.9:587', 'provider_timeout'],
+		['Connection timeout', 'provider_timeout'],
+	])('reads the failure "%s" as %s', (error, kind) => {
+		expect(describeProblem(send({ status: 'failed', error }))?.kind).toBe(kind)
+	})
+
+	it('tells an unreachable provider apart from a slow one', () => {
+		const problem = describeProblem(
+			send({ status: 'failed', error: 'connect ECONNREFUSED 127.0.0.1:1025' }),
+			'nodemailer',
+			false,
+		)
+		expect(problem).toMatchObject({
+			titleKey: 'dms_mailing.sends.problems.provider_unreachable.title',
+			descriptionKey:
+				'dms_mailing.sends.problems.provider_unreachable.description_no_advice',
+		})
+	})
+
+	it('falls back on a generic provider error', () => {
+		expect(
+			describeProblem(send({ status: 'failed', error: 'Invalid API key' }))
+				?.kind,
+		).toBe('provider_error')
+	})
+
+	it('reports a spam complaint', () => {
+		expect(describeProblem(send({ status: 'spam' }))?.kind).toBe('spam_report')
+	})
+
+	it('explains an unsubscription, in amber like a spam report', () => {
+		const problem = describeProblem(send({ status: 'unsubscribed' }))
+		expect(problem?.kind).toBe('unsubscribed')
+		expect(problem?.titleKey).toBe(
+			'dms_mailing.sends.problems.unsubscribed.title',
+		)
+		expect(problemTone('unsubscribed')).toBe('warning')
+		expect(problemTone('spam_report')).toBe('warning')
+		expect(problemTone('address_missing')).toBe('error')
+	})
+
+	it('stops short of the colon when the provider gave no reason', () => {
+		expect(describeProblem(send({ error: '' }))?.descriptionKey).toBe(
+			'dms_mailing.sends.problems.rejected.description_no_reason',
+		)
+		expect(
+			describeProblem(send({ status: 'failed', error: ' ' }))?.descriptionKey,
+		).toBe('dms_mailing.sends.problems.provider_error.description_no_reason')
+		expect(describeProblem(send({ error: '421 Later' }))?.descriptionKey).toBe(
+			'dms_mailing.sends.problems.rejected.description',
+		)
+	})
+
+	it('drops the advice to send again when the address is suppressed', () => {
+		const failed = send({ status: 'failed', error: 'Invalid API key' })
+		expect(describeProblem(failed, '', false)?.descriptionKey).toBe(
+			'dms_mailing.sends.problems.provider_error.description_no_advice',
+		)
+		expect(
+			describeProblem({ ...failed, error: '' }, '', false)?.descriptionKey,
+		).toBe(
+			'dms_mailing.sends.problems.provider_error.description_no_reason_no_advice',
+		)
+		expect(
+			describeProblem(send({ error: '' }), '', false)?.descriptionKey,
+		).toBe('dms_mailing.sends.problems.rejected.description_no_reason')
+	})
+
+	it('names the domain and the fallback provider', () => {
+		const problem = describeProblem(
+			send({ provider: undefined, error: '550' }),
+			'The provider',
+		)
+		expect(problem?.params).toMatchObject({
+			domain: 'stark.com',
+			provider: 'The provider',
+		})
+	})
+})
+
+describe('problemEventReason', () => {
+	const event = (type: string, details: object) =>
+		({
+			_id: type,
+			sendId: 's',
+			type,
+			at: '2026-10-07T10:00:00Z',
+			json_details: JSON.stringify(details),
+		}) as never
+
+	it('reads the reason of the latest problem event', () => {
+		expect(
+			problemEventReason([
+				event('sent', {}),
+				event('bounced', { reason: '550 5.1.1 Mailbox does not exist' }),
+			]),
+		).toBe('550 5.1.1 Mailbox does not exist')
+	})
+
+	it('answers an empty string without a problem event', () => {
+		expect(problemEventReason([event('delivered', { reason: 'x' })])).toBe('')
+	})
+})

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import {
+	MAX_RECIPIENTS,
+	isEmailAddress,
+	isSendableRecipients,
+	localeOptions,
+} from '../app/utils/recipients'
+
+describe('isSendableRecipients', () => {
+	it('needs one to five valid addresses', () => {
+		expect(isSendableRecipients(['camille@acme.com'])).toBe(true)
+		expect(isSendableRecipients([])).toBe(false)
+		expect(isSendableRecipients(['camille@acme'])).toBe(false)
+		expect(
+			isSendableRecipients(
+				Array.from({ length: MAX_RECIPIENTS + 1 }, (_, i) => `u${i}@acme.com`),
+			),
+		).toBe(false)
+	})
+
+	it('reads an address loosely but refuses spaces', () => {
+		expect(isEmailAddress(' julie@acme.com ')).toBe(true)
+		expect(isEmailAddress('julie @acme.com')).toBe(false)
+	})
+})
+
+describe('localeOptions', () => {
+	it('names a locale after the workspace, else shows its code', () => {
+		expect(
+			localeOptions(['fr', 'it'], [{ code: 'fr', name: 'Français' }]),
+		).toEqual([
+			{ label: 'Français (FR)', value: 'fr' },
+			{ label: 'IT', value: 'it' },
+		])
+	})
+})
+
+describe('localeOptions in the interface language', () => {
+	it('names every locale in the language the interface speaks', () => {
+		expect(
+			localeOptions(['en', 'fr'], [{ code: 'fr', name: 'français' }], 'fr'),
+		).toEqual([
+			{ label: 'Anglais (EN)', value: 'en' },
+			{ label: 'Français (FR)', value: 'fr' },
+		])
+	})
+})

package/frontend-vue/tests/rendering-title.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { renderingTitleKey } from '../app/utils/rendering-title'
+
+describe('renderingTitleKey', () => {
+	it('says "received" only once the e-mail reached the mailbox', () => {
+		expect(renderingTitleKey('delivered')).toBe(
+			'dms_mailing.rendering.received_by',
+		)
+		expect(renderingTitleKey('opened')).toBe(
+			'dms_mailing.rendering.received_by',
+		)
+	})
+	it('says "meant for" for a send that never arrived or may not have', () => {
+		for (const status of [
+			'queued',
+			'sent',
+			'bounced',
+			'failed',
+			'suppressed',
+		] as const) {
+			expect(renderingTitleKey(status)).toBe('dms_mailing.rendering.meant_for')
+		}
+	})
+})

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

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useReplayToast } from '../app/composables/useReplayToast'
+import { stubNuxtGlobals, type NuxtStubs } from './helpers/nuxt-globals'
+
+interface ToastAction {
+	label: string
+	onClick: () => void
+}
+
+describe('useReplayToast', () => {
+	let stubs: NuxtStubs
+
+	beforeEach(() => {
+		stubs = stubNuxtGlobals()
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+	})
+
+	it('says sent again, with a link to the new send', () => {
+		useReplayToast()({ sendId: 's2', status: 'sent' }, 'a@x.test', 'Sent again')
+		expect(stubs.toasts).toHaveLength(1)
+		const [toast] = stubs.toasts
+		expect(toast).toMatchObject({ color: 'success', title: 'Sent again' })
+		;(toast.actions as ToastAction[])[0].onClick()
+		expect(stubs.navigations).toEqual([
+			{ path: '/modules/mailing/sends', query: { record: 's2' } },
+		])
+	})
+
+	it('warns instead when the address is on the suppression list', () => {
+		useReplayToast()(
+			{
+				sendId: 's3',
+				status: 'suppressed',
+				error: '$dms_mailing.errors.suppressed.unsubscribe',
+			},
+			'a@x.test',
+			'Sent again',
+		)
+		const [toast] = stubs.toasts
+		expect(toast).toMatchObject({
+			color: 'warning',
+			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',
+		})
+		;(toast.actions as ToastAction[])[0].onClick()
+		expect(stubs.navigations).toEqual([
+			{ path: '/modules/mailing/suppressions', query: { email: 'a@x.test' } },
+		])
+	})
+
+	it('reports a provider failure as an error', () => {
+		useReplayToast()(
+			{ sendId: 's4', status: 'failed', error: 'ECONNREFUSED' },
+			'a@x.test',
+			'Sent again',
+		)
+		expect(stubs.toasts[0]).toMatchObject({
+			color: 'error',
+			title: 'a@x.test',
+			description: 'ECONNREFUSED',
+		})
+	})
+})