@antelopejs/dms-mailing 0.4.0 → 0.5.0

package/frontend-vue/tests/helpers/api-data.ts

@@ -0,0 +1,173 @@
+import { vi } from 'vitest'
+import { computed, ref, toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+/** A backend read a component made through `useApiData`. */
+export interface ApiRead {
+	url: string
+	query: Record<string, unknown>
+}
+
+export type ApiBackend = (read: ApiRead) => unknown
+
+interface ApiDataOptions {
+	query?: MaybeRefOrGetter<Record<string, unknown> | undefined>
+	pick?: string[]
+	immediate?: boolean
+}
+
+export interface ApiDataStub {
+	/** Every read made, in order. */
+	reads: ApiRead[]
+	/** Answers the next reads; a thrown error or a rejection fails them. */
+	respond: (backend: ApiBackend) => void
+}
+
+function picked(value: unknown, keys: string[] | undefined): unknown {
+	if (!keys || !value || typeof value !== 'object') return value
+	const source = value as Record<string, unknown>
+	return Object.fromEntries(keys.map((key) => [key, source[key]]))
+}
+
+/**
+ * Stands in for the DMS's `useApiData` (an auto-import the layer's tests do
+ * not have): reads the URL, and again whenever it or its query changes, from
+ * `respond`'s backend, with the result's `data`, `error`, `status` and
+ * `refresh()`; with `immediate: false`, only once `execute()` asks. Whether the server renders it and hands it over is the DMS's
+ * and the renderer's, proven on the playground.
+ */
+export function stubApiData(): ApiDataStub {
+	const stub: ApiDataStub = {
+		reads: [],
+		respond: (next) => {
+			backend = next
+		},
+	}
+	let backend: ApiBackend = () => ({})
+	vi.stubGlobal(
+		'useApiData',
+		(
+			url: MaybeRefOrGetter<string | null | undefined>,
+			options: ApiDataOptions = {},
+		) => {
+			const data = ref<unknown>(null)
+			const error = ref<unknown>(null)
+			const status = ref<'idle' | 'pending' | 'success' | 'error'>('idle')
+			const request = () => ({
+				url: toValue(url),
+				query: toValue(options.query) ?? {},
+			})
+			async function refresh(): Promise<void> {
+				const { url: path, query } = request()
+				if (!path) return
+				const read = { url: path, query }
+				stub.reads.push(read)
+				status.value = 'pending'
+				try {
+					data.value = picked(await backend(read), options.pick)
+					error.value = null
+					status.value = 'success'
+				} catch (failure) {
+					error.value = failure
+					status.value = 'error'
+				}
+			}
+			// A read made on demand (`immediate: false`) waits for `execute()`.
+			if (options.immediate !== false)
+				watch(
+					() => JSON.stringify(request()),
+					() => void refresh(),
+					{
+						immediate: true,
+					},
+				)
+			return {
+				data,
+				error,
+				status,
+				pending: computed(() => status.value === 'pending'),
+				refresh,
+				execute: refresh,
+				clear: () => {
+					data.value = null
+				},
+			}
+		},
+	)
+	return stub
+}
+
+/** The DMS's regional formatter, in the zone the tests run in. */
+export function stubRegionalFormat(): void {
+	vi.stubGlobal('useRegionalFormat', () => ({
+		dateTimeFormat: (options: Intl.DateTimeFormatOptions) =>
+			new Intl.DateTimeFormat('en', options),
+	}))
+}
+
+/** The read routes of the mailing API, as a component's tests mock them. */
+export interface MailingReadMocks {
+	templateContent?: (id: string) => unknown
+	performance?: (id: string) => unknown
+	changes?: (id: string) => unknown
+	versions?: (id: string) => unknown
+	listTemplates?: () => unknown
+	starters?: () => unknown
+	starterPreview?: (id: string, locale?: string) => unknown
+	send?: (id: string) => unknown
+	sendHtml?: (id: string) => unknown
+	provider?: () => unknown
+}
+
+type ReadRoute = (
+	mocks: MailingReadMocks,
+	match: RegExpExecArray,
+	read: ApiRead,
+) => unknown
+
+const READ_ROUTES: Array<[RegExp, ReadRoute]> = [
+	[/^\/api\/mailing\/templates\/starters$/, (m) => m.starters?.()],
+	[
+		/^\/api\/mailing\/templates\/starters\/([^/]+)\/preview$/,
+		(m, [, id], { query }) =>
+			m.starterPreview?.(id!, query.locale as string | undefined),
+	],
+	[
+		/^\/api\/mailing\/templates\/([^/]+)\/content$/,
+		(m, [, id]) => m.templateContent?.(id!),
+	],
+	[
+		/^\/api\/mailing\/templates\/([^/]+)\/performance$/,
+		(m, [, id]) => m.performance?.(id!),
+	],
+	[
+		/^\/api\/mailing\/templates\/([^/]+)\/changes$/,
+		(m, [, id]) => m.changes?.(id!),
+	],
+	[
+		/^\/api\/mailing\/templates\/([^/]+)\/versions$/,
+		(m, [, id]) => m.versions?.(id!),
+	],
+	[/^\/api\/mailing\/tables\/templates\/list$/, (m) => m.listTemplates?.()],
+	[/^\/api\/mailing\/sends\/([^/]+)\/html$/, (m, [, id]) => m.sendHtml?.(id!)],
+	[/^\/api\/mailing\/sends\/([^/]+)$/, (m, [, id]) => m.send?.(id!)],
+	[/^\/api\/mailing\/provider$/, (m) => m.provider?.()],
+]
+
+/**
+ * A backend answering the reads a component makes on demand with the
+ * test's mocks of them, and the others (or a read with no mock) with
+ * `fallback`.
+ */
+export function mailingReads(
+	mocks: MailingReadMocks,
+	fallback: ApiBackend = () => ({}),
+): ApiBackend {
+	return (read) => {
+		for (const [pattern, route] of READ_ROUTES) {
+			const match = pattern.exec(read.url)
+			const answer = match ? route(mocks, match, read) : undefined
+			if (answer !== undefined) return answer
+		}
+		return fallback(read)
+	}
+}

package/frontend-vue/tests/i18n-editor.test.ts

@@ -2,7 +2,6 @@ import { readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import en from '../i18n/locales/mailing-en-GB.json'
-import fr from '../i18n/locales/mailing-fr-FR.json'
 
 const APP = join(__dirname, '..', 'app')
 const EDITOR_SOURCES = [
@@ -40,14 +39,6 @@ function keysOf(value: unknown, prefix = ''): string[] {
 }
 
 describe('editor locales', () => {
-	it('carry the same key set', () => {
-		expect(keysOf(fr).sort()).toEqual(keysOf(en).sort())
-	})
-	it('cover the namespaces the editor uses', () => {
-		for (const namespace of ['editor', 'blocks']) {
-			expect(en.dms_mailing).toHaveProperty(namespace)
-		}
-	})
 	it('define every literal key the editor components use', () => {
 		const known = new Set(keysOf(en))
 		const used = EDITOR_SOURCES.flatMap((file) =>

package/frontend-vue/tests/new-template-modal.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import NewTemplateModal from '../app/components/NewTemplateModal.vue'
 import {
@@ -9,15 +10,16 @@ import {
 	typeInto,
 	type NuxtStubs,
 } from './helpers/nuxt-globals'
+import { mailingReads, stubApiData } from './helpers/api-data'
 
 const api = {
 	listTemplates: vi.fn(),
 	starters: vi.fn(),
-	listCategories: vi.fn(),
 	createTemplate: vi.fn(),
 }
 
-vi.mock('../app/composables/useMailingApi', () => ({
+vi.mock('../app/composables/useMailingApi', async (importOriginal) => ({
+	...(await importOriginal<object>()),
 	useMailingApi: () => api,
 }))
 
@@ -53,9 +55,20 @@ beforeEach(() => {
 			},
 		],
 	})
-	api.listCategories.mockResolvedValue({
-		categories: [{ id: 'billing', label: 'Billing', icon: 'i-ph-file-text' }],
-	})
+	stubApiData().respond(
+		mailingReads(
+			{ listTemplates: api.listTemplates, starters: api.starters },
+			({ url }) => {
+				if (url !== '/api/mailing/templates/categories')
+					throw new Error(`unexpected read ${url}`)
+				return {
+					categories: [
+						{ id: 'billing', label: 'Billing', icon: 'i-ph-file-text' },
+					],
+				}
+			},
+		),
+	)
 	api.createTemplate.mockResolvedValue(['new-id'])
 })
 

package/frontend-vue/tests/on-demand-reads.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { effectScope, ref } from 'vue'
+import {
+	useStarterPreviewRead,
+	useTemplateContentRead,
+	useTemplateListRead,
+} from '../app/composables/useMailingReads'
+import { stubApiData, type ApiDataStub } from './helpers/api-data'
+
+let reads: ApiDataStub
+const options: Record<string, unknown>[] = []
+
+beforeEach(() => {
+	reads = stubApiData()
+	options.length = 0
+	const stubbed = globalThis.useApiData
+	vi.stubGlobal(
+		'useApiData',
+		(url: unknown, readOptions: Record<string, unknown>) => {
+			options.push(readOptions)
+			return stubbed(url as string, readOptions)
+		},
+	)
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+})
+
+const inScope = <T>(setup: () => T): T => effectScope().run(setup) as T
+
+describe('reads made on demand', () => {
+	it('read nothing until asked, then the current URL each time', async () => {
+		reads.respond(({ url }) => ({ url }))
+		const id = ref('t1')
+		const readContent = inScope(() => useTemplateContentRead(id))
+		await Promise.resolve()
+		expect(reads.reads).toEqual([])
+		expect(options[0]).toMatchObject({
+			immediate: false,
+			refreshOnPageRefresh: false,
+		})
+
+		await expect(readContent()).resolves.toEqual({
+			url: '/api/mailing/templates/t1/content',
+		})
+		id.value = 't2'
+		await readContent()
+		expect(reads.reads.map((read) => read.url)).toEqual([
+			'/api/mailing/templates/t1/content',
+			'/api/mailing/templates/t2/content',
+		])
+	})
+
+	it('reject with what the read failed with', async () => {
+		const failure = Object.assign(new Error('gone'), { statusCode: 404 })
+		reads.respond(() => Promise.reject(failure))
+		const readContent = inScope(() => useTemplateContentRead('t1'))
+		await expect(readContent()).rejects.toBe(failure)
+	})
+
+	it('send their query with the read', async () => {
+		reads.respond(() => ({}))
+		const readList = inScope(() => useTemplateListRead())
+		const readPreview = inScope(() =>
+			useStarterPreviewRead('invoice-ready', 'fr'),
+		)
+		await readList()
+		await readPreview()
+		expect(reads.reads).toEqual([
+			{
+				url: '/api/mailing/tables/templates/list',
+				query: { limit: '100', sortKey: 'name' },
+			},
+			{
+				url: '/api/mailing/templates/starters/invoice-ready/preview',
+				query: { locale: 'fr' },
+			},
+		])
+	})
+})

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

@@ -1,19 +1,14 @@
+// @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { defineComponent, h, onBeforeUnmount, ref } from 'vue'
+import { createApp, defineComponent, h, onBeforeUnmount } from 'vue'
 import OverviewGate from '../app/components/OverviewGate.vue'
+import { useSetupHidesPeriod } from '../app/composables/useOverviewSetup'
 import type { SetupFacts } from '../app/utils/overview-setup'
+import { stubApiData, type ApiDataStub } from './helpers/api-data'
 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,
-}))
+let api: ApiDataStub
+const SETUP_URL = '/api/mailing/metrics/setup'
 
 interface ButtonAction {
 	label: string
@@ -62,6 +57,15 @@ const Gate = defineComponent({
 	setup: () => () => h(OverviewGate, null, { default: () => h(Dashboard) }),
 })
 
+/** What the page header renders of the period selector. */
+const PeriodHolder = defineComponent({
+	props: { scope: { type: String, default: undefined } },
+	setup: (props) => {
+		const hidesPeriod = useSetupHidesPeriod(props.scope)
+		return () => h('span', { 'data-hides-period': String(hidesPeriod.value) })
+	},
+})
+
 const GLOBALS = {
 	DmsCard: slotStub('DmsCard'),
 	DmsEmptyState: EmptyStateStub,
@@ -84,8 +88,10 @@ const facts = (overrides: Partial<SetupFacts> = {}): SetupFacts => ({
 beforeEach(() => {
 	stubNuxtGlobals()
 	vi.stubGlobal('onBeforeUnmount', onBeforeUnmount)
-	api.setupFacts.mockReset()
-	hidesPeriod.value = false
+	vi.stubGlobal('holdPageHeaderActions', () =>
+		defineComponent({ setup: () => () => null }),
+	)
+	api = stubApiData()
 })
 
 afterEach(() => {
@@ -95,34 +101,44 @@ afterEach(() => {
 
 describe('OverviewGate', () => {
 	it('mounts nothing of the dashboard before the facts are known', () => {
-		api.setupFacts.mockReturnValue(new Promise(() => undefined))
+		api.respond(() => 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())
+		api.respond(() => Promise.reject(new Error('500')))
 		const { host } = mount(Gate, {}, GLOBALS)
 		await flush()
 		expect(host.querySelector('[data-dashboard]')).toBeNull()
+		expect(api.reads).toEqual([{ url: SETUP_URL, query: {} }])
+		api.respond(() => facts())
 		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 }))
+		api.respond(() => 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('hides the overview header period from the same facts, on no other page', async () => {
+		api.respond(() => facts({ liveTemplateCount: 0 }))
+		const overview = mount(PeriodHolder, { scope: 'mailing-overview' })
+		const sends = mount(PeriodHolder, { scope: 'mailing-sends' })
+		await flush()
+		expect(overview.host.innerHTML).toContain('data-hides-period="true"')
+		expect(sends.host.innerHTML).toContain('data-hides-period="false"')
+		expect(api.reads).toEqual([{ url: SETUP_URL, query: {} }])
 	})
 
 	it('lets an unfinished setup be resumed above the dashboard', async () => {
-		api.setupFacts.mockResolvedValue(facts({ hasTestSend: false }))
+		api.respond(() => facts({ hasTestSend: false }))
 		const { host } = mount(Gate, {}, GLOBALS)
 		await flush()
 		expect(host.querySelector('[data-dashboard]')).not.toBeNull()
@@ -134,11 +150,34 @@ describe('OverviewGate', () => {
 		await flush()
 		expect(host.querySelectorAll('[data-step]')).toHaveLength(4)
 		expect(host.querySelector('[data-dashboard]')).not.toBeNull()
-		expect(hidesPeriod.value).toBe(false)
+	})
+
+	it('takes the props the page renderer adds without a fragment warning', async () => {
+		api.respond(() => facts())
+		const warnings: string[] = []
+		const app = createApp(() =>
+			h(
+				OverviewGate,
+				{ childCount: 0, routeParams: {} },
+				{ default: () => h(Dashboard) },
+			),
+		)
+		Object.entries(GLOBALS).forEach(([name, value]) =>
+			app.component(name, value),
+		)
+		app.config.warnHandler = (message) => warnings.push(message)
+		app.mount(document.body.appendChild(document.createElement('div')))
+		await flush()
+		app.unmount()
+		expect(
+			warnings.filter((message) =>
+				message.includes('Extraneous non-props attributes'),
+			),
+		).toEqual([])
 	})
 
 	it('offers no resume once every step is done', async () => {
-		api.setupFacts.mockResolvedValue(facts())
+		api.respond(() => facts())
 		const { host } = mount(Gate, {}, GLOBALS)
 		await flush()
 		expect(host.textContent).not.toContain('dms_mailing.setup.resume')

package/frontend-vue/tests/page-reads.test.ts

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, type VNodeChild } from 'vue'
+import PageHeader from '../app/components/PageHeader.vue'
+import WebhookStatus from '../app/components/WebhookStatus.vue'
+import type { WebhookStatus as Status } from '../app/utils/webhook-status'
+import {
+	stubApiData,
+	stubRegionalFormat,
+	type ApiDataStub,
+} from './helpers/api-data'
+import { flush, mount, slotStub, stubNuxtGlobals } from './helpers/nuxt-globals'
+
+const api = { webhookTest: vi.fn() }
+
+vi.mock('../app/composables/useMailingApi', async (importOriginal) => ({
+	...(await importOriginal<object>()),
+	useMailingApi: () => api,
+}))
+
+const PROVIDER_URL = '/api/mailing/provider'
+const STATUS_URL = '/api/mailing/settings/webhook-status'
+
+const NEVER: Status = { lastReceived: null, lastRefused: null }
+const TESTED: Status = {
+	lastReceived: {
+		at: new Date().toISOString(),
+		provider: 'smtp',
+		type: 'delivered',
+		isMatched: false,
+		isTest: true,
+	},
+	lastRefused: null,
+}
+
+const PillStub = defineComponent({
+	props: { label: { type: String, default: '' } },
+	setup: (props) => () => h('span', { 'data-pill': props.label }),
+})
+
+const ButtonStub = defineComponent({
+	props: { label: { type: String, default: '' } },
+	emits: ['click'],
+	setup:
+		(props, { emit }) =>
+		() =>
+			h('button', { onClick: () => emit('click') }, props.label),
+})
+
+let api$: ApiDataStub
+let headerActions: (() => VNodeChild) | null
+
+/** The page header: renders the actions `PageHeader` set up. */
+const Header = defineComponent({
+	setup: () => () => h('header', headerActions?.()),
+})
+
+const HeaderOutlet = defineComponent({
+	props: { showProvider: { type: Boolean, default: true } },
+	setup: (props) => () =>
+		h('div', [h(PageHeader, { showProvider: props.showProvider }), h(Header)]),
+})
+
+beforeEach(() => {
+	stubNuxtGlobals()
+	stubRegionalFormat()
+	headerActions = null
+	vi.stubGlobal('resolveComponent', (name: string) =>
+		name === 'DmsStatusPill' ? PillStub : slotStub(name),
+	)
+	vi.stubGlobal('usePageHeaderActions', (render: () => VNodeChild) => {
+		headerActions = render
+	})
+	vi.stubGlobal('useApiError', vi.fn())
+	api$ = stubApiData()
+	api.webhookTest.mockReset()
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	document.body.innerHTML = ''
+})
+
+describe('PageHeader', () => {
+	it('names the provider read with the page', async () => {
+		api$.respond(() => ({ name: 'smtp', connected: true, features: null }))
+		const view = mount(HeaderOutlet, {})
+		await flush()
+		expect(api$.reads).toEqual([{ url: PROVIDER_URL, query: {} }])
+		expect(
+			view.host.querySelector('[data-pill]')?.getAttribute('data-pill'),
+		).toBe('dms_mailing.page_header.provider_connected name=smtp')
+		view.unmount()
+	})
+
+	it('says no provider when the read fails, and reads nothing when hidden', async () => {
+		api$.respond(() => Promise.reject(new Error('503')))
+		const failed = mount(HeaderOutlet, {})
+		await flush()
+		expect(
+			failed.host.querySelector('[data-pill]')?.getAttribute('data-pill'),
+		).toBe('dms_mailing.page_header.no_provider')
+		failed.unmount()
+		api$.reads.length = 0
+		const hidden = mount(HeaderOutlet, { showProvider: false })
+		await flush()
+		expect(api$.reads).toEqual([])
+		expect(hidden.host.querySelector('[data-pill]')).toBeNull()
+		hidden.unmount()
+	})
+})
+
+describe('WebhookStatus', () => {
+	it('shows the status read, then the one a test event answers', async () => {
+		api$.respond(() => NEVER)
+		api.webhookTest.mockResolvedValue({
+			isReceived: true,
+			url: 'https://example.test/hook',
+			durationMs: 12,
+			status: TESTED,
+		})
+		const view = mount(
+			WebhookStatus,
+			{},
+			{
+				UButton: ButtonStub,
+				UIcon: slotStub('UIcon'),
+				USkeleton: slotStub('USkeleton'),
+			},
+		)
+		await flush()
+		expect(view.host.textContent).toContain(
+			'dms_mailing.settings.webhook_status.never_received',
+		)
+		view.host.querySelector('button')?.click()
+		await flush()
+		expect(view.host.textContent).toContain(
+			'dms_mailing.settings.webhook_status.received_test',
+		)
+		expect(api$.reads).toEqual([{ url: STATUS_URL, query: {} }])
+		view.unmount()
+	})
+
+	it('says the status is unavailable when its read fails', async () => {
+		api$.respond(() => Promise.reject(new Error('500')))
+		const view = mount(
+			WebhookStatus,
+			{},
+			{ UButton: ButtonStub, USkeleton: slotStub('USkeleton') },
+		)
+		await flush()
+		expect(view.host.textContent).toContain(
+			'dms_mailing.settings.webhook_status.unavailable',
+		)
+		view.unmount()
+	})
+})

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

@@ -1,7 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
 	clampRetention,
-	formatClock,
 	isWithinADay,
 	minutesSince,
 	presetShortLabelKey,
@@ -9,14 +8,6 @@ import {
 	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(