@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/frontend-vue/app/utils/template-attention.ts

@@ -0,0 +1,104 @@
+import type {
+	TemplateRow,
+	TemplateStats,
+	TemplateStatus,
+	VariableDefinition,
+} from '../types/mailing'
+import { readPath } from './paths'
+
+const MS_PER_DAY = 86_400_000
+
+export type AttentionReason = 'stale_draft' | 'never_sent' | 'missing_locale'
+
+/** How the row's `attention` field separates its reasons. */
+const REASON_SEPARATOR = ','
+
+/** Why the server says a template needs a look, read off its row. */
+export function attentionReasons(row: TemplateRow): AttentionReason[] {
+	return row.attention
+		.split(REASON_SEPARATOR)
+		.filter(Boolean) as AttentionReason[]
+}
+
+/** Whole days between `date` and `now`; 0 for an unreadable date. */
+export function daysSince(date: string | null | undefined, now: Date): number {
+	const time = date ? new Date(date).getTime() : Number.NaN
+	if (Number.isNaN(time)) return 0
+	return Math.max(0, Math.floor((now.getTime() - time) / MS_PER_DAY))
+}
+
+export type CardFooterKind = 'stats' | 'edited' | 'no_send'
+
+/** Which line a card's footer reads, with the figures it needs. */
+export interface CardFooter {
+	kind: CardFooterKind
+	sends: number
+	openRate: number
+	/** The date the line names: last edit, or the day it went live. */
+	at: string
+	by: string
+}
+
+/**
+ * The footer of a gallery card: the 30-day figures once real sends exist,
+ * otherwise who last edited a draft, or since when a live template waits for
+ * its first send.
+ */
+export function cardFooter(
+	row: TemplateRow,
+	stats?: TemplateStats,
+): CardFooter {
+	const base = {
+		sends: stats?.sends ?? 0,
+		openRate: stats?.openRate ?? 0,
+		at: row.updatedAt,
+		by: row.updatedBy,
+	}
+	if (base.sends > 0) return { ...base, kind: 'stats' }
+	if (row.status === 'live') {
+		return { ...base, kind: 'no_send', at: row.publishedAt || row.updatedAt }
+	}
+	return { ...base, kind: 'edited' }
+}
+
+export type LifecycleAction = 'publish' | 'unpublish' | 'archive' | 'restore'
+
+type TransitionRule = (row: TemplateRow) => LifecycleAction[]
+
+/**
+ * The backend refuses any other move with `409 invalid_transition`. On a live
+ * template, publishing only makes sense when a draft waits.
+ */
+const TRANSITIONS: Record<TemplateStatus, TransitionRule> = {
+	draft: () => ['publish', 'archive'],
+	live: (row) =>
+		row.isDraftPending
+			? ['publish', 'unpublish', 'archive']
+			: ['unpublish', 'archive'],
+	archived: () => ['restore'],
+}
+
+/** The lifecycle moves a template accepts from its current status. */
+export function validTransitions(row: TemplateRow): LifecycleAction[] {
+	return TRANSITIONS[row.status]?.(row) ?? []
+}
+
+const isFilled = (value: unknown) =>
+	value !== undefined && value !== null && value !== ''
+
+/**
+ * Whether the variables are ready for a real send: every path the content
+ * uses is declared, and every required one has a test value.
+ */
+export function variablesCovered(
+	declared: VariableDefinition[],
+	detected: string[],
+	testData: Record<string, unknown>,
+): boolean {
+	const declaredPaths = new Set(declared.map((entry) => entry.path))
+	const everyUsedDeclared = detected.every((path) => declaredPaths.has(path))
+	const everyRequiredFilled = declared
+		.filter((entry) => entry.required)
+		.every((entry) => isFilled(readPath(testData, entry.path)))
+	return everyUsedDeclared && everyRequiredFilled
+}

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

@@ -1,4 +1,5 @@
-import type { SendEventRow, SendStatus } from '../types/mailing'
+import type { SendEventRow, SendRow, SendStatus } from '../types/mailing'
+import { isSuppressedStatus, SUPPRESSED_STATUS } from './suppression'
 
 export type TimelineTone =
 	'neutral' | 'success' | 'primary' | 'error' | 'warning'
@@ -13,8 +14,30 @@ export interface TimelineItem {
 	type: SendStatus
 	icon: string
 	tone: TimelineTone
-	description: string
-	at: string
+	/** i18n key of the step's title. */
+	titleKey: string
+	titleParams: Record<string, string>
+	/** One line under the title: a raw SMTP answer, a message id, a URL… */
+	detail: string
+	/** Whether `detail` is a machine value, shown in mono. */
+	isDetailMono: boolean
+	/** `null` for a step still to come. */
+	at: string | null
+	/** A step that has not happened yet, drawn ghosted. */
+	isPending: boolean
+}
+
+export interface TimelineSend extends Pick<
+	SendRow,
+	'_id' | 'status' | 'createdAt' | 'provider' | 'providerMessageId' | 'error'
+> {
+	isSoftBounce?: boolean
+}
+
+/** What the provider reports by itself; `null` while it is unknown. */
+export interface TimelineTracking {
+	openTracking: boolean
+	clickTracking: boolean
 }
 
 export const TIMELINE_META: Record<SendStatus, TimelineMeta> = {
@@ -27,14 +50,47 @@ export const TIMELINE_META: Record<SendStatus, TimelineMeta> = {
 	spam: { icon: 'i-ph-prohibit', tone: 'warning' },
 	failed: { icon: 'i-ph-warning', tone: 'error' },
 	unsubscribed: { icon: 'i-ph-user-minus', tone: 'warning' },
+	suppressed: { icon: 'i-ph-prohibit', tone: 'neutral' },
 }
 
-const DESCRIPTION_KEYS = ['reason', 'url', 'userAgent']
+/** The happy path a send walks; pending steps are drawn from it. */
+const HAPPY_PATH: SendStatus[] = ['queued', 'sent', 'delivered', 'opened']
+/** A provider that reports no open stops the path at the delivery. */
+const DELIVERY_PATH: SendStatus[] = ['queued', 'sent', 'delivered']
+/** A provider that reports nothing (SMTP) stops it once the e-mail left. */
+const HANDOFF_PATH: SendStatus[] = ['queued', 'sent']
+
+/** Statuses after which nothing more is waited for. */
+const TERMINAL_STATUSES: SendStatus[] = [
+	'bounced',
+	'spam',
+	'failed',
+	'unsubscribed',
+	SUPPRESSED_STATUS,
+]
 
-interface EventDetails {
-	[key: string]: unknown
+const SOFT_BOUNCE_TYPE = /soft|transient|temporary/i
+const HARD_BOUNCE_TYPE = /hard|permanent/i
+const SOFT_SMTP_ANSWER = /^\s*4\d\d\b|\b4\.\d{1,3}\.\d{1,3}\b/
+
+const TITLE_KEY_PREFIX = 'dms_mailing.sends.timeline.'
+
+/** Detail keys read off an event, in order; the first present one is shown. */
+const DETAIL_KEYS = ['reason', 'smtp', 'code', 'url', 'userAgent', 'client']
+const MONO_DETAIL_KEYS = new Set(['reason', 'smtp', 'code', 'url'])
+
+type EventDetails = Record<string, unknown>
+
+interface Detail {
+	text: string
+	isMono: boolean
 }
 
+const NO_DETAIL: Detail = { text: '', isMono: false }
+
+/** Steps whose reason the drawer tells in a banner, not as a raw detail. */
+const WORDED_ELSEWHERE = new Set<SendStatus>([SUPPRESSED_STATUS])
+
 function parseDetails(raw: string): EventDetails {
 	try {
 		const parsed: unknown = raw ? JSON.parse(raw) : {}
@@ -46,23 +102,169 @@ function parseDetails(raw: string): EventDetails {
 	}
 }
 
-function describe(details: EventDetails): string {
-	const key = DESCRIPTION_KEYS.find((candidate) => details[candidate])
-	return key ? String(details[key]) : ''
+function eventDetail(details: EventDetails): Detail {
+	const key = DETAIL_KEYS.find((candidate) => details[candidate])
+	if (!key) return NO_DETAIL
+	return { text: String(details[key]), isMono: MONO_DETAIL_KEYS.has(key) }
+}
+
+/** What a step says beyond its event: the message id, the raw error. */
+const SEND_DETAILS: Partial<
+	Record<SendStatus, (send: TimelineSend) => Detail>
+> = {
+	sent: (send) => ({ text: send.providerMessageId ?? '', isMono: true }),
+	bounced: (send) => ({ text: send.error ?? '', isMono: true }),
+	failed: (send) => ({ text: send.error ?? '', isMono: true }),
+}
+
+/** Steps whose title names the provider when the send knows it. */
+const PROVIDER_TITLE_KEYS: Partial<Record<SendStatus, string>> = {
+	sent: `${TITLE_KEY_PREFIX}sent_to`,
 }
 
+interface StepTitle {
+	titleKey: string
+	titleParams: Record<string, string>
+}
+
+const textOf = (value: unknown): string =>
+	typeof value === 'string' ? value : ''
+
 /**
- * Orders a send's events oldest-first and resolves the icon, tone and one-line
- * description each row shows.
+ * Whether a bounce event was temporary: the provider's `bounceType` when it
+ * gives one, else the SMTP answer's class, else what the send recorded.
  */
-export function buildTimeline(events: SendEventRow[]): TimelineItem[] {
+export function isSoftBounceEvent(
+	details: EventDetails,
+	send: TimelineSend,
+): boolean {
+	const bounceType = textOf(details.bounceType)
+	if (SOFT_BOUNCE_TYPE.test(bounceType)) return true
+	if (HARD_BOUNCE_TYPE.test(bounceType)) return false
+	const reason = textOf(details.reason)
+	return reason ? SOFT_SMTP_ANSWER.test(reason) : !!send.isSoftBounce
+}
+
+/** Event titles that depend on what the event says. */
+const EVENT_TITLE_KEYS: Partial<
+	Record<SendStatus, (details: EventDetails, send: TimelineSend) => string>
+> = {
+	bounced: (details, send) =>
+		`${TITLE_KEY_PREFIX}${isSoftBounceEvent(details, send) ? 'soft_bounce' : 'bounced'}`,
+}
+
+function titleOf(
+	type: SendStatus,
+	send: TimelineSend,
+	details: EventDetails = {},
+): StepTitle {
+	const providerKey = PROVIDER_TITLE_KEYS[type]
+	if (providerKey && send.provider)
+		return { titleKey: providerKey, titleParams: { provider: send.provider } }
+	const eventKey = EVENT_TITLE_KEYS[type]?.(details, send)
+	return { titleKey: eventKey ?? `${TITLE_KEY_PREFIX}${type}`, titleParams: {} }
+}
+
+interface StepInput {
+	id: string
+	type: SendStatus
+	at: string | null
+	detail: Detail
+	details?: EventDetails
+}
+
+function stepOf(input: StepInput, send: TimelineSend): TimelineItem {
+	return {
+		id: input.id,
+		type: input.type,
+		at: input.at,
+		...TIMELINE_META[input.type],
+		...titleOf(input.type, send, input.details),
+		detail: input.detail.text,
+		isDetailMono: input.detail.isMono,
+		isPending: input.at === null,
+	}
+}
+
+function happenedSteps(
+	events: SendEventRow[],
+	send: TimelineSend,
+): TimelineItem[] {
 	return [...events]
 		.sort((a, b) => new Date(a.at).getTime() - new Date(b.at).getTime())
-		.map((event) => ({
-			id: event._id,
-			type: event.type,
-			at: event.at,
-			description: describe(parseDetails(event.json_details)),
-			...TIMELINE_META[event.type],
-		}))
+		.map((event) => {
+			const details = parseDetails(event.json_details)
+			const fromEvent = WORDED_ELSEWHERE.has(event.type)
+				? NO_DETAIL
+				: eventDetail(details)
+			const fromSend = SEND_DETAILS[event.type]?.(send) ?? NO_DETAIL
+			const detail = fromEvent.text ? fromEvent : fromSend
+			return stepOf(
+				{ id: event._id, type: event.type, at: event.at, detail, details },
+				send,
+			)
+		})
+}
+
+/** The steps a send can still be seen walking with this provider. */
+function trackedPath(tracking: TimelineTracking | null): SendStatus[] {
+	if (!tracking || tracking.openTracking) return HAPPY_PATH
+	return tracking.clickTracking ? DELIVERY_PATH : HANDOFF_PATH
+}
+
+function pendingSteps(
+	send: TimelineSend,
+	reached: SendStatus[],
+	tracking: TimelineTracking | null,
+): TimelineItem[] {
+	const isOver = [send.status, ...reached].some((type) =>
+		TERMINAL_STATUSES.includes(type),
+	)
+	if (isOver) return []
+	const path = trackedPath(tracking)
+	const furthest = Math.max(
+		...reached.map((type) => path.indexOf(type as SendStatus)),
+		path.indexOf(send.status),
+	)
+	if (furthest < 0) return []
+	return path
+		.slice(furthest + 1)
+		.map((type) =>
+			stepOf(
+				{ id: `pending-${type}`, type, at: null, detail: NO_DETAIL },
+				send,
+			),
+		)
+}
+
+/**
+ * The steps of a send, oldest first: when it was queued (the send's own date
+ * unless an event says so), every recorded event with the detail worth
+ * reading (the raw SMTP answer, the provider's message id), then the steps of
+ * the happy path still to come, ghosted. A problem or an unsubscription has
+ * no step to come, and neither has a step the provider never reports. A send
+ * to a suppressed address was never queued: its one step says so.
+ */
+export function buildTimeline(
+	events: SendEventRow[],
+	send: TimelineSend,
+	tracking: TimelineTracking | null = null,
+): TimelineItem[] {
+	const happened = happenedSteps(events, send)
+	const reached = happened.map((step) => step.type)
+	const isQueued = reached.includes('queued') || isSuppressedStatus(send.status)
+	const queued = isQueued
+		? []
+		: [
+				stepOf(
+					{
+						id: `queued-${send._id}`,
+						type: 'queued',
+						at: send.createdAt,
+						detail: NO_DETAIL,
+					},
+					send,
+				),
+			]
+	return [...queued, ...happened, ...pendingSteps(send, reached, tracking)]
 }

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

@@ -1,24 +1,126 @@
-export type TextPartKind = 'text' | 'token'
+import type { InjectionKey, Ref } from 'vue'
+import { isPresent, readPath } from './paths'
+
+/**
+ * `token` is a `{{path}}` the engine fills in; `invalid` looks like one but
+ * breaks its grammar, so the engine leaves it as typed.
+ */
+export type TextPartKind = 'text' | 'token' | 'invalid'
 
 export interface TextPart {
 	kind: TextPartKind
 	value: string
 }
 
-const TOKEN_SPLIT = /(\{\{[^}]+\}\})/g
-const TOKEN_OPEN = '{{'
+/** A token read against test data: its value when the data provides one. */
+export interface ResolvedToken {
+	isPresent: boolean
+	text: string
+}
+
+/** The test data the paper renders tokens with; `null` shows the paths. */
+export type TokenData = Record<string, unknown> | null
+
+/**
+ * Provided by the canvas in Data mode so every `MailingTokenText` on the paper
+ * swaps its tokens for values without each block renderer passing data down.
+ */
+export const TOKEN_DATA_KEY: InjectionKey<Ref<TokenData>> = Symbol(
+	'dms-mailing-token-data',
+)
+
+/**
+ * The engine's token grammar (`src/engine/tokens.ts` `TOKEN_PATTERN`), with
+ * a capture around the whole token so `split` keeps it.
+ */
+const TOKEN_SPLIT = /(\{\{\s*[A-Za-z0-9_.[\]]+\s*\}\})/
+const TOKEN_LIKE_SPLIT = /(\{\{[^}]*\}\})/
 const TOKEN_MARKER_LENGTH = 2
+const SPLIT_TOKEN_STEP = 2
 
-export function splitTokens(text: string): TextPart[] {
+/**
+ * How a token without a value prints, as the engine's interpolation modes:
+ * `preview` keeps it visible, `send` blanks it as a real e-mail does.
+ */
+export type InterpolationMode = 'preview' | 'send'
+
+const MISSING_TOKEN: Record<InterpolationMode, (path: string) => string> = {
+	preview: (path) => `{{${path}}}`,
+	send: () => '',
+}
+
+/** A piece of text with tokens kept exactly as typed (spaces included). */
+export interface RawSegment {
+	kind: TextPartKind
+	raw: string
+	/** The trimmed path of a token; the raw text otherwise. */
+	value: string
+}
+
+const isSplitMatch = (index: number): boolean => index % SPLIT_TOKEN_STEP === 1
+
+function literalSegments(text: string): RawSegment[] {
 	return text
-		.split(TOKEN_SPLIT)
-		.filter(Boolean)
-		.map((part) =>
-			part.startsWith(TOKEN_OPEN)
-				? {
+		.split(TOKEN_LIKE_SPLIT)
+		.map((raw, index) => ({
+			kind: isSplitMatch(index) ? ('invalid' as const) : ('text' as const),
+			raw,
+			value: raw,
+		}))
+		.filter((segment) => segment.raw)
+}
+
+/**
+ * Splits `text` into literal text, tokens and token look-alikes, keeping each
+ * token's raw spelling: the token field's highlight layer must line up
+ * character for character with the textarea.
+ */
+export function splitRawSegments(text: string): RawSegment[] {
+	return text.split(TOKEN_SPLIT).flatMap((raw, index) =>
+		isSplitMatch(index)
+			? [
+					{
 						kind: 'token' as const,
-						value: part.slice(TOKEN_MARKER_LENGTH, -TOKEN_MARKER_LENGTH).trim(),
-					}
-				: { kind: 'text' as const, value: part },
-		)
+						raw,
+						value: raw.slice(TOKEN_MARKER_LENGTH, -TOKEN_MARKER_LENGTH).trim(),
+					},
+				]
+			: literalSegments(raw),
+	)
+}
+
+export function splitTokens(text: string): TextPart[] {
+	return splitRawSegments(text).map(({ kind, value }) => ({ kind, value }))
+}
+
+function formatValue(value: unknown): string {
+	return value instanceof Date ? value.toISOString() : String(value)
+}
+
+/** Reads one token path in `data`, formatted like the engine prints it. */
+export function resolveToken(
+	path: string,
+	data: Record<string, unknown>,
+): ResolvedToken {
+	const value = readPath(data, path)
+	return isPresent(value)
+		? { isPresent: true, text: formatValue(value) }
+		: { isPresent: false, text: path }
+}
+
+/** Replaces every token of `text` with its value, as the engine does. */
+export function interpolateText(
+	text: string,
+	data: Record<string, unknown>,
+	mode: InterpolationMode = 'preview',
+): string {
+	return splitTokens(text)
+		.map((part) => {
+			if (part.kind !== 'token') return part.value
+			const resolved = resolveToken(part.value, data)
+			return resolved.isPresent
+				? resolved.text
+				: MISSING_TOKEN[mode](part.value)
+		})
+		.join('')
 }

package/frontend-vue/app/utils/variable-types.ts

@@ -0,0 +1,23 @@
+import { VARIABLE_TYPES, type VariableType } from '../types/mailing'
+
+const VARIABLE_TYPE_KEY_PREFIX = 'dms_mailing.variable_types'
+
+export interface VariableTypeItem {
+	value: VariableType
+	label: string
+}
+
+/** The i18n key naming a variable type for a writer ("Amount" for `money`). */
+export function variableTypeLabelKey(type: VariableType): string {
+	return `${VARIABLE_TYPE_KEY_PREFIX}.${type}`
+}
+
+/** The type picker's items: the stored value, the label a writer reads. */
+export function variableTypeItems(
+	translate: (key: string) => string,
+): VariableTypeItem[] {
+	return VARIABLE_TYPES.map((type) => ({
+		value: type,
+		label: translate(variableTypeLabelKey(type)),
+	}))
+}