@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/frontend-vue/app/utils/problems.ts

@@ -0,0 +1,181 @@
+import type { SendEventRow, SendRow, SendStatus } from '../types/mailing'
+
+export type ProblemKind =
+	| 'address_missing'
+	| 'mailbox_full'
+	| 'rejected_spam'
+	| 'spam_report'
+	| 'provider_timeout'
+	| 'provider_unreachable'
+	| 'rejected'
+	| 'provider_error'
+	| 'unsubscribed'
+
+export interface ProblemDescription {
+	kind: ProblemKind
+	icon: string
+	/** i18n key of the plain-language title ("This address doesn't exist"). */
+	titleKey: string
+	/** i18n key of the one-line explanation under it. */
+	descriptionKey: string
+	params: Record<string, string>
+}
+
+export type ProblemSend = Pick<
+	SendRow,
+	'status' | 'error' | 'recipientEmail' | 'provider'
+>
+
+interface ProblemRule {
+	kind: ProblemKind
+	icon: string
+	statuses: SendStatus[]
+	/** Matched against the raw error; absent matches any error. */
+	pattern?: RegExp
+}
+
+const KEY_PREFIX = 'dms_mailing.sends.problems.'
+const DOMAIN_SEPARATOR = '@'
+
+/**
+ * Plain-language readings of a send problem, most specific first: the SMTP
+ * class or the provider's wording decides, the status is the fallback.
+ */
+const PROBLEM_RULES: ProblemRule[] = [
+	{
+		kind: 'address_missing',
+		icon: 'i-ph-at',
+		statuses: ['bounced', 'failed'],
+		pattern:
+			/5\.1\.[0-3]|\b550\b|\b553\b|does ?n[o']t exist|unknown (user|recipient)|no such (user|mailbox)|user unknown|invalid (recipient|address)/i,
+	},
+	{
+		kind: 'mailbox_full',
+		icon: 'i-ph-tray',
+		statuses: ['bounced', 'failed'],
+		pattern:
+			/\b452\b|\b552\b|[45]\.2\.2|mailbox (is )?full|over quota|quota exceeded/i,
+	},
+	{
+		kind: 'rejected_spam',
+		icon: 'i-ph-shield-warning',
+		statuses: ['bounced', 'failed'],
+		pattern: /5\.7\.[0-9]|\bspam\b|blocked|blacklist|reputation/i,
+	},
+	{ kind: 'spam_report', icon: 'i-ph-prohibit', statuses: ['spam'] },
+	{
+		kind: 'provider_timeout',
+		icon: 'i-ph-plugs',
+		statuses: ['failed'],
+		pattern: /time(d)? ?out|ETIMEDOUT|did ?n[o']t answer/i,
+	},
+	{
+		kind: 'provider_unreachable',
+		icon: 'i-ph-plugs',
+		statuses: ['failed'],
+		pattern:
+			/ECONNREFUSED|ECONNRESET|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|connection refused|unreachable/i,
+	},
+	{ kind: 'rejected', icon: 'i-ph-arrow-u-up-left', statuses: ['bounced'] },
+	{ kind: 'provider_error', icon: 'i-ph-warning', statuses: ['failed'] },
+	{ kind: 'unsubscribed', icon: 'i-ph-user-minus', statuses: ['unsubscribed'] },
+]
+
+/** Problems the recipient chose rather than suffered: told in amber. */
+const WARNING_KINDS = new Set<ProblemKind>(['spam_report', 'unsubscribed'])
+
+/** The banner tone a problem is told in. */
+export function problemTone(kind: ProblemKind): 'warning' | 'error' {
+	return WARNING_KINDS.has(kind) ? 'warning' : 'error'
+}
+
+/**
+ * Problems whose explanation quotes the provider's words; without them, a
+ * sentence that stops short of the colon.
+ */
+const KINDS_QUOTING_ERROR = new Set<ProblemKind>(['rejected', 'provider_error'])
+const NO_REASON_SUFFIX = '_no_reason'
+/**
+ * Problems whose explanation ends on the advice to send again; when sending
+ * again is not possible (the address is on the suppression list), a sentence
+ * without that advice.
+ */
+const KINDS_ADVISING_SEND_AGAIN = new Set<ProblemKind>([
+	'provider_timeout',
+	'provider_unreachable',
+	'provider_error',
+])
+const NO_ADVICE_SUFFIX = '_no_advice'
+
+function descriptionKey(
+	kind: ProblemKind,
+	error: string | undefined,
+	canSendAgain: boolean,
+): string {
+	let key = `${KEY_PREFIX}${kind}.description`
+	if (KINDS_QUOTING_ERROR.has(kind) && !error?.trim()) key += NO_REASON_SUFFIX
+	if (!canSendAgain && KINDS_ADVISING_SEND_AGAIN.has(kind))
+		key += NO_ADVICE_SUFFIX
+	return key
+}
+
+function matches(rule: ProblemRule, send: ProblemSend): boolean {
+	if (!rule.statuses.includes(send.status)) return false
+	return !rule.pattern || rule.pattern.test(send.error ?? '')
+}
+
+function domainOf(email: string): string {
+	return email.split(DOMAIN_SEPARATOR).at(-1) ?? email
+}
+
+/**
+ * What went wrong with a send, in the words of the person reading the log:
+ * the title and explanation keys plus the icon of the banner. `null` when the
+ * send has no problem. `provider` names the provider when the send does not;
+ * `canSendAgain` is false when the address can no longer be sent to.
+ */
+export function describeProblem(
+	send: ProblemSend,
+	provider = '',
+	canSendAgain = true,
+): ProblemDescription | null {
+	const rule = PROBLEM_RULES.find((candidate) => matches(candidate, send))
+	if (!rule) return null
+	return {
+		kind: rule.kind,
+		icon: rule.icon,
+		titleKey: `${KEY_PREFIX}${rule.kind}.title`,
+		descriptionKey: descriptionKey(rule.kind, send.error, canSendAgain),
+		params: {
+			provider: send.provider || provider,
+			domain: domainOf(send.recipientEmail),
+			error: send.error ?? '',
+		},
+	}
+}
+
+const PROBLEM_EVENT_TYPES: SendStatus[] = ['bounced', 'failed', 'spam']
+
+interface EventDetails {
+	reason?: unknown
+}
+
+function reasonOf(event: SendEventRow): string {
+	try {
+		const details = JSON.parse(event.json_details || '{}') as EventDetails
+		return typeof details.reason === 'string' ? details.reason : ''
+	} catch {
+		return ''
+	}
+}
+
+/**
+ * The provider's words for the latest problem event of a send, for sends
+ * logged before their error was kept on the send itself.
+ */
+export function problemEventReason(events: SendEventRow[]): string {
+	const problems = events.filter((event) =>
+		PROBLEM_EVENT_TYPES.includes(event.type),
+	)
+	return problems.map(reasonOf).filter(Boolean).at(-1) ?? ''
+}

package/frontend-vue/app/utils/recipients.ts

@@ -0,0 +1,49 @@
+import { languageLabel } from './locales'
+
+/** A manual send reaches at most this many addresses; a list needs an automation. */
+export const MAX_RECIPIENTS = 5
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+export function isEmailAddress(value: string): boolean {
+	return EMAIL_PATTERN.test(value.trim())
+}
+
+/** Whether a recipient list can be sent: not empty, not over the cap, all addresses. */
+export function isSendableRecipients(recipients: string[]): boolean {
+	return (
+		recipients.length > 0 &&
+		recipients.length <= MAX_RECIPIENTS &&
+		recipients.every(isEmailAddress)
+	)
+}
+
+/** One locale of a select, labelled with its workspace name when known. */
+export interface LocaleOption {
+	label: string
+	value: string
+}
+
+export interface NamedLocale {
+	code: string
+	name?: string
+}
+
+/**
+ * Select items for `codes`, named in the interface's language when `uiLocale`
+ * is given ("Anglais (EN)" in French), else after the workspace locales.
+ */
+export function localeOptions(
+	codes: string[],
+	workspace: NamedLocale[],
+	uiLocale?: string,
+): LocaleOption[] {
+	const names = new Map(workspace.map((entry) => [entry.code, entry.name]))
+	return codes.map((code) => {
+		const name = names.get(code)
+		if (uiLocale)
+			return { label: languageLabel(code, uiLocale, name), value: code }
+		const upper = code.toUpperCase()
+		return { label: name ? `${name} (${upper})` : upper, value: code }
+	})
+}

package/frontend-vue/app/utils/rendering-title.ts

@@ -0,0 +1,23 @@
+import type { SendStatus } from '../types/mailing'
+
+const KEY_PREFIX = 'dms_mailing.rendering'
+
+/** Statuses that prove the e-mail reached the recipient's mailbox. */
+const RECEIVED_STATUSES: ReadonlySet<SendStatus> = new Set<SendStatus>([
+	'delivered',
+	'opened',
+	'clicked',
+	'spam',
+	'unsubscribed',
+])
+
+/**
+ * The i18n key titling a send's rendering: "What {name} received" once the
+ * e-mail is known to have arrived, "The e-mail meant for {name}" while it is
+ * on its way, bounced, failed or was never sent.
+ */
+export function renderingTitleKey(status: SendStatus): string {
+	return RECEIVED_STATUSES.has(status)
+		? `${KEY_PREFIX}.received_by`
+		: `${KEY_PREFIX}.meant_for`
+}

package/frontend-vue/app/utils/send-actions.ts

@@ -0,0 +1,207 @@
+import type { SendRow, SendStatus } from '../types/mailing'
+import { isSuppressedStatus } from './suppression'
+
+export type SendActionId =
+	'rendering' | 'copy_address' | 'fix_address' | 'send_again'
+
+export type SendActionVariant = 'ghost' | 'outline' | 'solid'
+
+export interface SendAction {
+	id: SendActionId
+	variant: SendActionVariant
+	/** i18n key of the button label; absent for an icon-only button. */
+	labelKey?: string
+	icon: string
+}
+
+/**
+ * A send as the drawer reads it: what the API added to a send since `SendRow`
+ * — a temporary bounce, and the link between a send and its send again.
+ */
+export interface DrawerSend extends SendRow {
+	isSoftBounce?: 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
+}
+
+/** What decides a drawer's footer. */
+export interface FooterSend extends Pick<
+	DrawerSend,
+	'status' | 'isSoftBounce' | 'replayedBy'
+> {
+	/**
+	 * Whether the recipient is on the suppression list today; unknown until
+	 * the send's detail is loaded.
+	 */
+	isAddressSuppressed?: boolean
+}
+
+interface FooterRule {
+	matches: (send: FooterSend) => boolean
+	actions: SendAction[]
+}
+
+const KEY_PREFIX = 'dms_mailing.sends.drawer.actions.'
+const SHORT_ID_LENGTH = 8
+
+const RENDERING: SendAction = {
+	id: 'rendering',
+	variant: 'ghost',
+	labelKey: `${KEY_PREFIX}rendering`,
+	icon: 'i-ph-eye',
+}
+
+const COPY_ADDRESS: SendAction = {
+	id: 'copy_address',
+	variant: 'outline',
+	icon: 'i-ph-copy',
+}
+
+const FIX_ADDRESS: SendAction = {
+	id: 'fix_address',
+	variant: 'solid',
+	labelKey: `${KEY_PREFIX}fix_address`,
+	icon: 'i-ph-user-circle',
+}
+
+const sendAgain = (variant: SendActionVariant): SendAction => ({
+	id: 'send_again',
+	variant,
+	labelKey: `${KEY_PREFIX}send_again`,
+	icon: 'i-ph-arrow-clockwise',
+})
+
+/** The rendering, one label whatever the status, outlined beside a quiet resend. */
+const RENDERING_OUTLINED: SendAction = { ...RENDERING, variant: 'outline' }
+
+/** Footer of a send that went through: repeating it is possible but quiet. */
+const DEFAULT_ACTIONS: SendAction[] = [sendAgain('ghost'), RENDERING_OUTLINED]
+
+/** Nothing to send any more: what was received, and the address. */
+const LOOK_ONLY: SendAction[] = [RENDERING, COPY_ADDRESS]
+
+/**
+ * The drawer footer by status (ML-03): a bounce asks for another address
+ * since sending it again would bounce again, a spam report or an
+ * unsubscription is never answered with another e-mail, a provider failure is
+ * sent again as the main action.
+ */
+const ACTIONS_BY_STATUS: Partial<Record<SendStatus, SendAction[]>> = {
+	bounced: [RENDERING, COPY_ADDRESS, FIX_ADDRESS],
+	spam: LOOK_ONLY,
+	unsubscribed: LOOK_ONLY,
+	failed: [RENDERING, sendAgain('solid')],
+	suppressed: LOOK_ONLY,
+}
+
+/**
+ * Footers that win over the status: a send someone already sent again offers
+ * no second one, a temporary bounce (a full mailbox) may go to the same
+ * address later, and so may a suppressed send once its address is
+ * reactivated.
+ */
+const FOOTER_RULES: FooterRule[] = [
+	{ matches: (send) => !!send.replayedBy, actions: LOOK_ONLY },
+	{
+		matches: (send) => send.status === 'bounced' && !!send.isSoftBounce,
+		actions: [RENDERING, sendAgain('solid')],
+	},
+	{
+		matches: (send) =>
+			isSuppressedStatus(send.status) && send.isAddressSuppressed === false,
+		actions: [RENDERING, sendAgain('solid')],
+	},
+]
+
+const offersSendAgain = (actions: SendAction[]): boolean =>
+	actions.some((action) => action.id === 'send_again')
+
+/**
+ * The footer buttons of a send's drawer, in display order. While the address
+ * is on the suppression list a send again would not leave: the footer only
+ * looks, and the drawer's notice links to the list.
+ */
+export function sendFooterActions(send: FooterSend): SendAction[] {
+	const rule = FOOTER_RULES.find((candidate) => candidate.matches(send))
+	const actions =
+		rule?.actions ?? ACTIONS_BY_STATUS[send.status] ?? DEFAULT_ACTIONS
+	return send.isAddressSuppressed && offersSendAgain(actions)
+		? LOOK_ONLY
+		: actions
+}
+
+/** The short id the drawer's eyebrow shows ("SEND · 8f2a8c1e"). */
+export function shortSendId(id: string): string {
+	return id.slice(-SHORT_ID_LENGTH)
+}
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+/**
+ * Why a corrected address cannot be used, as an i18n key: empty, not an
+ * e-mail, or the address that already failed. `null` when it can.
+ */
+export function correctedAddressError(
+	value: string,
+	previous: string,
+): string | null {
+	const address = value.trim()
+	const rules: [boolean, string][] = [
+		[!address, 'dms_mailing.sends.fix_address.errors.required'],
+		[
+			!EMAIL_PATTERN.test(address),
+			'dms_mailing.sends.fix_address.errors.invalid',
+		],
+		[
+			address.toLowerCase() === previous.trim().toLowerCase(),
+			'dms_mailing.sends.fix_address.errors.same',
+		],
+	]
+	return rules.find(([failed]) => failed)?.[1] ?? null
+}
+
+/**
+ * What a send again did: went out, stopped by the suppression list (nothing
+ * went out, the original stays a problem), or failed at the provider.
+ */
+export type ReplayOutcome = 'sent' | 'suppressed' | 'failed'
+
+export function replayOutcome(result: {
+	status: string
+	error?: string
+}): ReplayOutcome {
+	if (isSuppressedStatus(result.status)) return 'suppressed'
+	return result.error || result.status === 'failed' ? 'failed' : 'sent'
+}
+
+const PAYLOAD_INDENT = 2
+
+/** The variables a send carried, pretty-printed; the raw text when unparsable. */
+export function formatPayload(raw: string | undefined): string {
+	if (!raw) return ''
+	try {
+		return JSON.stringify(JSON.parse(raw), null, PAYLOAD_INDENT)
+	} catch {
+		return raw
+	}
+}
+
+export type SendTone = 'neutral' | 'info' | 'success' | 'warning' | 'error'
+
+/** The tone of a send's status pill, the same in the log and the drawer. */
+export const SEND_STATUS_TONES: Record<SendStatus, SendTone> = {
+	queued: 'neutral',
+	sent: 'info',
+	delivered: 'success',
+	opened: 'info',
+	clicked: 'info',
+	bounced: 'error',
+	spam: 'warning',
+	failed: 'error',
+	unsubscribed: 'warning',
+	suppressed: 'neutral',
+}

package/frontend-vue/app/utils/send-link.ts

@@ -0,0 +1,28 @@
+import type { SendResult } from '../composables/useMailingApi'
+import { SENDS_PATH } from './pages'
+
+/** The DMS table's deep-link key: the send log opens that send's drawer. */
+const RECORD_QUERY_KEY = 'record'
+
+export interface SendLogRoute {
+	path: string
+	query: Record<string, string>
+}
+
+/**
+ * Where a send toast's "View in the send log" leads: the send itself when one
+ * went out, the log otherwise.
+ */
+export function sendLogRoute(results: SendResult[]): SendLogRoute {
+	const sent = results.filter((result) => !result.error && result.sendId)
+	const only = sent.length === 1 ? sent[0] : undefined
+	return {
+		path: SENDS_PATH,
+		query: only ? { [RECORD_QUERY_KEY]: only.sendId } : {},
+	}
+}
+
+/** One send of the log, its drawer open. */
+export function sendRoute(sendId: string): SendLogRoute {
+	return { path: SENDS_PATH, query: { [RECORD_QUERY_KEY]: sendId } }
+}

package/frontend-vue/app/utils/send-snippet.ts

@@ -0,0 +1,97 @@
+import { readPath } from './paths'
+import type { VariableType } from '../types/mailing'
+
+export interface SnippetVariable {
+	path: string
+	type: VariableType
+}
+
+export interface SendSnippetInput {
+	slug: string
+	locale: string
+	/**
+	 * The paths the content uses, declared or only detected, and the system
+	 * URLs its footer links need (`utils/system-variables.ts`).
+	 */
+	variables: SnippetVariable[]
+	/** The template's test data: example values where it has them. */
+	testData: Record<string, unknown>
+}
+
+type VariableTree = Record<string, unknown>
+
+const EXAMPLE_VALUES: Record<VariableType, unknown> = {
+	string: '…',
+	text: '…',
+	number: 0,
+	money: 0,
+	date: '2026-01-31',
+	url: 'https://…',
+	boolean: true,
+	array: [],
+}
+
+const ARRAY_SUFFIX = '[]'
+const PATH_SEPARATOR = '.'
+const INDENT = '  '
+const JSON_INDENT = 2
+const QUOTED_IDENTIFIER_KEY = /"([A-Za-z_$][\w$]*)":/g
+
+const isTree = (value: unknown): value is VariableTree =>
+	value !== null && typeof value === 'object' && !Array.isArray(value)
+
+/** A list item path (`order.items[].name`) stands for its list. */
+function rootVariable(variable: SnippetVariable): SnippetVariable {
+	const at = variable.path.indexOf(ARRAY_SUFFIX)
+	return at < 0 ? variable : { path: variable.path.slice(0, at), type: 'array' }
+}
+
+/** Sets `value` at a dotted path, never over a branch a deeper path built. */
+function setPath(tree: VariableTree, path: string, value: unknown): void {
+	const keys = path.split(PATH_SEPARATOR)
+	const leaf = keys.pop() as string
+	const parent = keys.reduce<VariableTree>((node, key) => {
+		if (!isTree(node[key])) node[key] = {}
+		return node[key] as VariableTree
+	}, tree)
+	if (!isTree(parent[leaf])) parent[leaf] = value
+}
+
+/** The variables a send passes, as one object of example values. */
+export function exampleVariables(input: SendSnippetInput): VariableTree {
+	const tree: VariableTree = {}
+	input.variables
+		.map(rootVariable)
+		.filter((variable) => variable.path)
+		.forEach((variable) => {
+			const example = readPath(input.testData, variable.path)
+			setPath(
+				tree,
+				variable.path,
+				example ?? EXAMPLE_VALUES[variable.type] ?? EXAMPLE_VALUES.string,
+			)
+		})
+	return tree
+}
+
+function literal(value: unknown): string {
+	return JSON.stringify(value, null, JSON_INDENT)
+		.replace(QUOTED_IDENTIFIER_KEY, '$1:')
+		.split('\n')
+		.join(`\n${INDENT}`)
+}
+
+/**
+ * The `SendTemplate` call that sends this template from code: every
+ * parameter the interface requires, and the variables its content uses.
+ */
+export function sendSnippet(input: SendSnippetInput): string {
+	return [
+		`await SendTemplate(${JSON.stringify(input.slug)}, {`,
+		`${INDENT}tenantId,`,
+		`${INDENT}to: customer.email,`,
+		`${INDENT}locale: ${JSON.stringify(input.locale)},`,
+		`${INDENT}variables: ${literal(exampleVariables(input))},`,
+		'});',
+	].join('\n')
+}

package/frontend-vue/app/utils/send-stats.ts

@@ -0,0 +1,24 @@
+/** Past this latency the drawer shows the API call in red. */
+export const SLOW_LATENCY_MS = 5000
+
+const MS_PER_SECOND = 1000
+const SECONDS_DECIMALS = 1
+
+/** A latency as the log prints it: milliseconds, seconds past 5 s, a dash when unknown. */
+export function formatLatency(
+	ms: number | null | undefined,
+	locale: string,
+): string {
+	if (ms === null || ms === undefined) return '—'
+	if (ms < SLOW_LATENCY_MS)
+		return `${new Intl.NumberFormat(locale).format(ms)} ms`
+	const seconds = new Intl.NumberFormat(locale, {
+		minimumFractionDigits: SECONDS_DECIMALS,
+		maximumFractionDigits: SECONDS_DECIMALS,
+	}).format(ms / MS_PER_SECOND)
+	return `${seconds} s`
+}
+
+export function isSlowLatency(ms: number | null | undefined): boolean {
+	return (ms ?? 0) >= SLOW_LATENCY_MS
+}