@antelopejs/dms-mailing 0.3.3 → 0.4.0

package/frontend-vue/app/emails/components/MailingBlocks.vue

@@ -1,23 +1,49 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import EmailButton from '#dms-layout/app/emails/components/EmailButton.vue'
-import EmailOTP from '#dms-layout/app/emails/components/EmailOTP.vue'
 import { emailStyles } from '#dms-layout/app/emails/components/index'
+import MailingTextLines from './MailingTextLines.vue'
 import type {
 	ResolvedBlock,
+	ResolvedButton,
+	ResolvedFooter,
 	ResolvedHeading,
 	ResolvedParagraph,
 } from '../../types/mailing'
 
-const FOOTER_TYPE = 'footer'
+interface FooterLink {
+	label: string
+	href: string
+}
 
-const heroStyle = { width: '100%', borderRadius: '8px', marginBottom: '20px' }
-const totalStyle = { ...emailStyles.text, fontWeight: '600' }
-const rowLabelStyle = { ...emailStyles.text, margin: '0' }
-const rowValueStyle = {
-	...emailStyles.text,
-	margin: '0',
-	textAlign: 'right' as const,
+const FOOTER_TYPE = 'footer'
+const FOOTER_LINK_SEPARATOR = ' · '
+
+/** Long words (a URL, a reference) wrap instead of widening the e-mail. */
+const wrap = { overflowWrap: 'anywhere', wordBreak: 'break-word' }
+const blockSpacing = { margin: '0 0 16px' }
+const textStyle = { ...emailStyles.text, ...wrap }
+const heroStyle = {
+	display: 'block',
+	width: '100%',
+	borderRadius: '8px',
+	margin: '0 0 20px',
+}
+const cellStyle = { ...textStyle, margin: '0' }
+const valueCellStyle = { ...cellStyle, textAlign: 'right' as const }
+const totalStyle = { ...cellStyle, fontWeight: '600' }
+const totalValueStyle = { ...valueCellStyle, fontWeight: '600' }
+const codeStyle = { ...emailStyles.otp.code, ...wrap }
+const dividerStyle = { border: '0', ...emailStyles.divider }
+/** Darker than the DMS footer grey: small print stays readable (4.8:1). */
+const FOOTER_TEXT_COLOR = '#71717a'
+const footerStyle = {
+	...emailStyles.footer,
+	color: FOOTER_TEXT_COLOR,
+	...wrap,
+}
+const footerLinkStyle = {
+	color: FOOTER_TEXT_COLOR,
+	textDecoration: 'underline',
 }
 
 interface Props {
@@ -27,28 +53,49 @@ interface Props {
 
 const props = defineProps<Props>()
 
+/** A footer with neither text nor link would draw a lone divider. */
+const isEmptyFooter = (block: ResolvedBlock): boolean =>
+	block.type === FOOTER_TYPE && !block.text.trim() && !footerLinks(block).length
+
 const visibleBlocks = computed(() =>
-	props.blocks.filter((block) =>
-		props.footerOnly ? block.type === FOOTER_TYPE : block.type !== FOOTER_TYPE,
-	),
+	props.blocks
+		.filter((block) =>
+			props.footerOnly
+				? block.type === FOOTER_TYPE
+				: block.type !== FOOTER_TYPE,
+		)
+		.filter((block) => !isEmptyFooter(block)),
 )
 
 const headingStyle = (block: ResolvedHeading) => ({
 	...emailStyles.heading,
+	...wrap,
 	textAlign: block.align,
 	fontSize: `${block.size}px`,
 })
 
 const paragraphStyle = (block: ResolvedParagraph) => ({
-	...emailStyles.text,
+	...textStyle,
 	textAlign: block.align,
 })
+
+const buttonRowStyle = (block: ResolvedButton) => ({
+	...emailStyles.buttonContainer,
+	textAlign: block.align,
+})
+
+function footerLinks(block: ResolvedFooter): FooterLink[] {
+	return [
+		{ label: block.unsubscribeLabel, href: block.unsubscribeUrl },
+		{ label: block.preferencesLabel, href: block.preferencesUrl },
+	].filter((link) => link.href && link.label.trim())
+}
 </script>
 
 <template>
 	<template v-for="block in visibleBlocks" :key="block.id">
 		<EImg
-			v-if="block.type === 'hero'"
+			v-if="block.type === 'hero' && block.imageUrl"
 			:src="block.imageUrl"
 			:alt="block.alt"
 			:style="heroStyle"
@@ -59,59 +106,70 @@ const paragraphStyle = (block: ResolvedParagraph) => ({
 			as="h1"
 			:style="headingStyle(block)"
 		>
-			{{ block.text }}
+			<MailingTextLines :text="block.text" />
 		</EHeading>
 
 		<EText
 			v-else-if="block.type === 'paragraph'"
 			:style="paragraphStyle(block)"
 		>
-			{{ block.text }}
+			<MailingTextLines :text="block.text" />
 		</EText>
 
-		<EmailOTP v-else-if="block.type === 'code'" :code="block.text" />
+		<ESection v-else-if="block.type === 'code'" :style="emailStyles.otp.box">
+			<EText :style="codeStyle">{{ block.text }}</EText>
+		</ESection>
 
-		<ESection v-else-if="block.type === 'list'">
+		<ESection v-else-if="block.type === 'list'" :style="blockSpacing">
 			<ERow v-for="(row, index) in block.rows" :key="index">
 				<EColumn>
-					<EText :style="rowLabelStyle">{{ row.label }}</EText>
+					<EText :style="cellStyle">{{ row.label }}</EText>
 				</EColumn>
 				<EColumn align="right">
-					<EText :style="rowValueStyle">{{ row.value }}</EText>
+					<EText :style="valueCellStyle">{{ row.value }}</EText>
 				</EColumn>
 			</ERow>
 		</ESection>
 
-		<ESection v-else-if="block.type === 'total'">
+		<ESection v-else-if="block.type === 'total'" :style="blockSpacing">
 			<ERow>
 				<EColumn>
 					<EText :style="totalStyle">{{ block.label }}</EText>
 				</EColumn>
 				<EColumn align="right">
-					<EText :style="totalStyle">{{ block.value }}</EText>
+					<EText :style="totalValueStyle">{{ block.value }}</EText>
 				</EColumn>
 			</ERow>
 		</ESection>
 
 		<ESection
 			v-else-if="block.type === 'button'"
-			:style="{ textAlign: block.align }"
+			:style="buttonRowStyle(block)"
 		>
-			<EmailButton :href="block.href">{{ block.text }}</EmailButton>
+			<EButton :href="block.href" :style="emailStyles.button">
+				{{ block.text }}
+			</EButton>
 		</ESection>
 
-		<EHr v-else-if="block.type === 'divider'" :style="emailStyles.divider" />
-
-		<EText v-else-if="block.type === 'footer'" :style="emailStyles.footer">
-			{{ block.text }}
-			<br />
-			<ELink v-if="block.unsubscribeUrl" :href="block.unsubscribeUrl">
-				{{ block.unsubscribeLabel }}
-			</ELink>
-			·
-			<ELink v-if="block.preferencesUrl" :href="block.preferencesUrl">
-				{{ block.preferencesLabel }}
-			</ELink>
-		</EText>
+		<EHr v-else-if="block.type === 'divider'" :style="dividerStyle" />
+
+		<template v-else-if="block.type === 'footer'">
+			<EHr :style="dividerStyle" />
+			<EText :style="footerStyle">
+				<MailingTextLines :text="block.text" />
+				<template v-if="footerLinks(block).length">
+					<br />
+					<template
+						v-for="(link, index) in footerLinks(block)"
+						:key="link.href"
+					>
+						<template v-if="index > 0">{{ FOOTER_LINK_SEPARATOR }}</template>
+						<ELink :href="link.href" :style="footerLinkStyle">
+							{{ link.label }}
+						</ELink>
+					</template>
+				</template>
+			</EText>
+		</template>
 	</template>
 </template>

package/frontend-vue/app/emails/components/MailingTextLines.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+interface Props {
+	text: string
+}
+
+const LINE_BREAK = /\r?\n/
+
+const props = defineProps<Props>()
+
+const lines = computed(() => props.text.split(LINE_BREAK))
+</script>
+
+<template>
+	<template v-for="(line, index) in lines" :key="index">
+		<br v-if="index > 0" />
+		{{ line }}
+	</template>
+</template>

package/frontend-vue/app/plugins/column-displays.ts

@@ -0,0 +1,65 @@
+import { h, type VNode } from 'vue'
+import CategoryLabel from '../components/CategoryLabel.vue'
+import { localeChipClass, localeChips } from '../utils/locales'
+
+export const LOCALE_CHIPS_DISPLAY_ID = 'mailing:locale-chips'
+export const CATEGORY_DISPLAY_ID = 'mailing:category'
+
+const EMPTY_CELL = '—'
+const CHIP_ROW_CLASS = 'inline-flex items-center gap-1'
+
+interface WorkspaceLocale {
+	code: string
+}
+
+const emptyCell = () => h('span', { class: 'text-dimmed' }, EMPTY_CELL)
+
+/**
+ * A template's locales as mono chips, the workspace locales it lacks drawn
+ * dashed in the warning tone, like the gallery card.
+ */
+export function renderLocaleChips(
+	value: unknown,
+	workspaceCodes: string[],
+): VNode {
+	const chips = localeChips(
+		typeof value === 'string' ? value : '',
+		workspaceCodes,
+	)
+	if (!chips.length) return emptyCell()
+	return h(
+		'span',
+		{ class: CHIP_ROW_CLASS },
+		chips.map((chip) =>
+			h('span', { class: localeChipClass(chip.present) }, chip.code),
+		),
+	)
+}
+
+/** A template's category as its settings label and icon. */
+export function renderCategory(value: unknown): VNode {
+	return h(CategoryLabel, { value: typeof value === 'string' ? value : null })
+}
+
+function workspaceCodes(): string[] {
+	const { uniqueLocales } = useUniqueLocales()
+	return uniqueLocales.value.map((entry: WorkspaceLocale) => entry.code)
+}
+
+/**
+ * Frontend renderers of the backend column displays `mailing:locale-chips`
+ * and `mailing:category` (`src/data/displays.ts`).
+ */
+export default defineDmsPlugin(() => {
+	const { registerDataType } = useDataTypes()
+	registerDataType({
+		id: LOCALE_CHIPS_DISPLAY_ID,
+		formatter: {
+			default: (value: unknown) => renderLocaleChips(value, workspaceCodes()),
+		},
+	})
+	registerDataType({
+		id: CATEGORY_DISPLAY_ID,
+		formatter: { default: renderCategory },
+	})
+})

package/frontend-vue/app/plugins/{template-gallery-display.client.ts → template-gallery-display.ts}

@@ -1,6 +1,6 @@
 import TemplateGallery from '../components/TemplateGallery.vue'
 
-const GALLERY_DISPLAY_ID = 'gallery'
+const GALLERY_DISPLAY_ID = 'mailing:gallery'
 const GALLERY_DISPLAY_ORDER = 5
 
 export default defineDmsPlugin(() => {

package/frontend-vue/app/types/mailing.ts

@@ -253,6 +253,7 @@ export type SendStatus =
 	| 'spam'
 	| 'failed'
 	| 'unsubscribed'
+	| 'suppressed'
 
 export const SEND_STATUSES: SendStatus[] = [
 	'queued',
@@ -264,9 +265,11 @@ export const SEND_STATUSES: SendStatus[] = [
 	'spam',
 	'failed',
 	'unsubscribed',
+	'suppressed',
 ]
 
-export type SendEventType = SendStatus
+/** What a provider reports: a suppressed send never reached one. */
+export type SendEventType = Exclude<SendStatus, 'suppressed'>
 
 export interface TemplateCategory {
 	id: string
@@ -278,26 +281,140 @@ export interface TemplateRow {
 	_id: string
 	slug: string
 	name: string
-	/** Absent or empty when the template is uncategorised. */
-	category?: string
+	/** Absent, `null` or empty when the template is uncategorised. */
+	category?: string | null
 	status: TemplateStatus
 	/** Comma-separated locale codes of the content; blank means unknown. */
 	locales?: string
 	updatedAt: string
 	updatedBy: string
+	/** Version customers receive; 0 or absent when never published. */
+	publishedVersion?: number
+	publishedAt?: string | null
+	/** When the template last left `live` by an unpublish. */
+	unpublishedAt?: string | null
+	/** Whether a draft holds changes customers do not receive yet. */
+	isDraftPending?: boolean
+	/** Why the template needs a look, comma-separated; blank when nothing does. */
+	attention: string
+}
+
+export type TemplateChangeKind =
+	| 'locale_added'
+	| 'locale_removed'
+	| 'subject'
+	| 'preheader'
+	| 'block_added'
+	| 'block_removed'
+	| 'block_changed'
+	| 'blocks_reordered'
+	| 'variable_added'
+	| 'variable_removed'
+	| 'variable_changed'
+
+/**
+ * One difference between what customers receive and the draft: per locale
+ * for the content, per path for the variable declarations.
+ */
+export interface TemplateChange {
+	/** Blank for a change of the variable declarations. */
+	locale: string
+	kind: TemplateChangeKind
+	blockId?: string
+	blockType?: BlockType
+	/** The declared path a variable change is about. */
+	variable?: string
+}
+
+export interface TemplateSender {
+	name: string
+	email: string
+	replyTo: string
 }
 
 export interface TemplateContentResponse {
-	template: TemplateRow
+	template: TemplateRow & {
+		json_variables?: string
+		draftUpdatedAt?: string
+		draftUpdatedBy?: string
+		publishedBy?: string
+	}
+	/** The content the editor works on: the draft, else the published one. */
 	content: TemplateContent
+	/** What customers receive; `null` when the template was never published. */
+	publishedContent: TemplateContent | null
+	hasDraft: boolean
+	/** Version customers receive; 0 when never published. */
+	version: number
+	/** The draft revision a save or a publish carries back. */
+	revision: number
+	changes: TemplateChange[]
+	/** The declarations the editor works on: the draft's, else the published. */
 	variables: VariableDefinition[]
-	/** Paths the content actually references, across every locale. */
+	/** Paths the working content references, across every locale. */
 	detectedVariables: string[]
+	/**
+	 * The contract callers send against: the published declarations and the
+	 * paths the published content references; `null` when never published.
+	 */
+	publishedVariables?: VariableDefinition[] | null
+	publishedDetectedVariables?: string[] | null
 	testData: Record<string, unknown>
 	fallbackLocale: string
+	/** Whether a send missing a variable fails rather than goes out blank. */
+	blockOnMissingVariables: boolean
 	categories: TemplateCategory[]
+	sender: TemplateSender
+}
+
+export interface TemplateVersionSummary {
+	version: number
+	publishedAt: string
+	publishedBy: string
+	locales: string
+	changes: TemplateChange[]
+	/** The declarations the version shipped with. */
+	variables: VariableDefinition[]
+}
+
+/** Last 30 days of real sends of one template. */
+export interface TemplateStats {
+	id: string
+	slug: string
+	sends: number
+	openRate: number
+	problems: number
+	lastSentAt: string | null
 }
 
+export interface SourceCount {
+	source: string
+	count: number
+}
+
+/** Recipients who asked for a locale the template did not carry. */
+export interface FallbackCount {
+	requested: string
+	used: string
+	count: number
+}
+
+export interface TemplatePerformance extends TemplateStats {
+	sources: SourceCount[]
+	fallbacks: FallbackCount[]
+}
+
+export interface StarterSummary {
+	id: string
+	name: string
+	slug: string
+	category: string
+	locales: string[]
+}
+
+/** Which content a preview renders when it carries none. */
+export type PreviewVersion = 'draft' | 'published' | number
+
 export interface PreviewResponse {
 	html: string
 	subject: string
@@ -306,17 +423,31 @@ export interface PreviewResponse {
 	hiddenBlockIds: string[]
 }
 
+export type SendStage =
+	| 'problem'
+	| 'resolved'
+	| 'suppressed'
+	| 'in_progress'
+	| 'delivered'
+	| 'engaged'
+	| 'unsubscribed'
+
 export interface SendRow {
 	_id: string
 	templateId: string
 	templateSlug: string
 	locale: string
+	/** Locale the caller asked for; differs from `locale` on a fallback. */
+	requestedLocale?: string
+	/** Template version the send used; 0 for a test send of a draft. */
+	templateVersion?: number
+	stage?: SendStage
 	recipientEmail: string
 	recipientName?: string
 	status: SendStatus
 	provider?: string
 	providerMessageId?: string
-	latencyMs: number
+	latencyMs: number | null
 	error?: string
 	source?: string
 	json_variables: string
@@ -324,38 +455,72 @@ export interface SendRow {
 	clicks: number
 	createdAt: string
 	isTest: boolean
+	/** The send this one repeats. */
+	replayOf?: string
+	/** The send that repeated this one, once someone sent it again. */
+	replayedBy?: string
+	/** When someone sent it again. */
+	resolvedAt?: string
+	/** Who sent it again: a user id. */
+	resolvedBy?: string
 }
 
 export interface SendEventRow {
 	_id: string
 	sendId: string
-	type: SendStatus
+	type: SendEventType
 	at: string
 	json_details: string
 }
 
+export type SuppressionReason =
+	'hard_bounce' | 'complaint' | 'unsubscribe' | 'manual'
+
+/** An address's entry on the suppression list, as the API answers it. */
+export interface SuppressionSummary {
+	id: string
+	email: string
+	reason: SuppressionReason
+	createdAt: string
+	/** The send whose event put the address on the list. */
+	sendId?: string
+}
+
+export interface SendTemplateSummary {
+	id: string
+	name: string
+	status: TemplateStatus
+	publishedVersion: number
+}
+
 export interface SendDetailResponse {
 	send: SendRow
 	events: SendEventRow[]
+	/** `null` when the template was deleted since. */
+	template: SendTemplateSummary | null
+	/** The recipient's entry on the suppression list, if any. */
+	suppression?: SuppressionSummary | null
 }
 
-export type AttentionTone = 'warning' | 'error' | 'neutral'
-
-export interface AttentionItem {
-	id: string
-	tone: AttentionTone
-	icon: string
-	title: string
-	description: string
-	to?: string
-	params?: Record<string, string | number>
+export interface SendHtmlResponse {
+	html: string
+	subject: string
+	locale: string
+	version: number
+	/** A draft test is rendered from today's draft, which may differ from what was sent. */
+	approximate?: boolean
+	from: string
+	fromName: string
 }
 
 export interface FunnelStep {
 	id: string
 	label: string
 	count: number
-	rate: number
+	/** Share of the previous step; `null` when there is nothing to divide by. */
+	rate: number | null
+	/** `false` when nothing reports the events this step counts. */
+	isMeasured?: boolean
 }
 
 export interface ProviderInfo {
@@ -363,3 +528,13 @@ export interface ProviderInfo {
 	connected: boolean
 	features: Record<string, boolean> | null
 }
+
+export type MissingVariablesPolicy = 'refuse' | 'send'
+
+export interface RetentionPreview {
+	days: number
+	count: number
+	nextRunAt: string
+}
+
+export type FunnelKind = 'all' | 'marketing' | 'transactional'

package/frontend-vue/app/utils/api-error.ts

@@ -0,0 +1,33 @@
+/** What a failed `$authFetch` call carries, as far as the module reads it. */
+export interface FetchFailure {
+	statusCode?: number
+	status?: number
+	data?: unknown
+	message?: string
+}
+
+export const HTTP_CONFLICT = 409
+
+const asFailure = (error: unknown): FetchFailure =>
+	error !== null && typeof error === 'object' ? (error as FetchFailure) : {}
+
+/** The HTTP status of a failed call; 0 for a network failure. */
+export function apiErrorStatus(error: unknown): number {
+	const failure = asFailure(error)
+	return failure.statusCode ?? failure.status ?? 0
+}
+
+/**
+ * The message a failed call answers: the backend's i18n key (`$dms_mailing…`)
+ * when it sent one, else the error's own text, for `processApiMessage`.
+ */
+export function apiErrorMessage(error: unknown): string {
+	const failure = asFailure(error)
+	const data = failure.data
+	if (data && typeof data === 'object') {
+		const message = (data as Record<string, unknown>).message
+		if (typeof message === 'string') return message
+	}
+	if (typeof data === 'string' && data) return data
+	return failure.message ?? String(error)
+}