@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -1,4 +1,16 @@
-import type { VariableDefinition, VariableType } from '../types/mailing'
+import type {
+	Block,
+	Condition,
+	ConditionOperator,
+	LocaleContent,
+	TemplateChange,
+	TemplateContent,
+	TemplateContentResponse,
+	VariableDefinition,
+	VariableType,
+} from '../types/mailing'
+import { flattenBlocks } from './blocks/tree'
+import { pathsInBlocks, textPaths } from './paths'
 
 /**
  * `declared` — the content uses it and someone typed it;
@@ -46,3 +58,198 @@ export function mergeVariables(
 		}))
 	return [...used, ...unused]
 }
+
+/** One side of a template's variables: what it declares and references. */
+export interface VariableContract {
+	variables: VariableDefinition[]
+	detected: string[]
+}
+
+type ContractSource = Pick<
+	TemplateContentResponse,
+	| 'variables'
+	| 'detectedVariables'
+	| 'publishedVariables'
+	| 'publishedDetectedVariables'
+>
+
+/** The draft's side: what the editor works on. */
+export function workingContract(detail: ContractSource): VariableContract {
+	return { variables: detail.variables, detected: detail.detectedVariables }
+}
+
+/**
+ * What callers send against: the published declarations and the paths the
+ * published content references; the working side for a template never
+ * published.
+ */
+export function publishedContract(detail: ContractSource): VariableContract {
+	return {
+		variables: detail.publishedVariables ?? detail.variables,
+		detected: detail.publishedDetectedVariables ?? detail.detectedVariables,
+	}
+}
+
+/** Whether a pending change is about a variable declaration. */
+export function isDeclarationChange(change: TemplateChange): boolean {
+	return Boolean(change.variable)
+}
+
+/** A declaration saved from the variables panel. */
+export interface VariableSubmission {
+	value: VariableDefinition
+	/** Also point the content's references to the old path at the new one. */
+	shouldReplaceInContent: boolean
+}
+
+/** What a variable path may hold: letters, digits, `.`, `_` and `[]`. */
+export const VARIABLE_PATH_PATTERN = /^[A-Za-z0-9_.[\]]+$/
+
+const INVALID_PATH_CHARACTERS = /[^A-Za-z0-9_.[\]]+/g
+const PATH_FILLER = '_'
+const EDGE_FILLERS = /^_+|_+$/g
+const FALLBACK_PATH_EXAMPLE = 'first_name'
+
+export function isValidVariablePath(path: string): boolean {
+	return VARIABLE_PATH_PATTERN.test(path.trim())
+}
+
+/** A valid path close to `path` (`first name` → `first_name`). */
+export function suggestVariablePath(path: string): string {
+	const suggestion = path
+		.trim()
+		.replace(INVALID_PATH_CHARACTERS, PATH_FILLER)
+		.replace(EDGE_FILLERS, '')
+	return suggestion || FALLBACK_PATH_EXAMPLE
+}
+
+const localesOf = (content: TemplateContent): LocaleContent[] =>
+	Object.values(content.locales ?? {})
+
+/** The paths a block itself references, its branches left out. */
+function ownPaths(block: Block): string[] {
+	const shallow: Block =
+		block.type === 'if' ? { ...block, children: [], elseChildren: null } : block
+	return pathsInBlocks([shallow])
+}
+
+/**
+ * How many places of the content reference `path`, across every locale: each
+ * block counts once, the subject and the preheader once each.
+ */
+export function countPathUsages(
+	content: TemplateContent,
+	path: string,
+): number {
+	return localesOf(content).reduce((total, locale) => {
+		const envelope = [locale.subject, locale.preheader].filter((text) =>
+			textPaths(text).includes(path),
+		)
+		const blocks = flattenBlocks(locale.blocks).filter((block) =>
+			ownPaths(block).includes(path),
+		)
+		return total + envelope.length + blocks.length
+	}, 0)
+}
+
+const REGEXP_SPECIALS = /[.*+?^${}()|[\]\\]/g
+
+function tokenPattern(path: string): RegExp {
+	const escaped = path.replace(REGEXP_SPECIALS, '\\$&')
+	return new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, 'g')
+}
+
+function renameInCondition(
+	condition: Condition | null,
+	from: string,
+	to: string,
+): void {
+	if (condition?.path === from) condition.path = to
+}
+
+interface PathRename {
+	from: string
+	to: string
+	rewrite: (text: string) => string
+}
+
+function renameInBlock(block: Block, rename: PathRename): void {
+	const record = block as unknown as Record<string, unknown>
+	Object.entries(record)
+		.filter(([, value]) => typeof value === 'string')
+		.forEach(([key, value]) => (record[key] = rename.rewrite(value as string)))
+	renameInCondition(block.visibleIf, rename.from, rename.to)
+	if (block.type === 'if')
+		renameInCondition(block.condition, rename.from, rename.to)
+	if (block.type === 'list' && block.source === rename.from)
+		block.source = rename.to
+}
+
+/**
+ * Points every reference to `from` at `to`, in place and in every locale:
+ * `{{tokens}}`, list sources and condition paths.
+ */
+export function renameVariablePath(
+	content: TemplateContent,
+	from: string,
+	to: string,
+): void {
+	const pattern = tokenPattern(from)
+	const rename: PathRename = {
+		from,
+		to,
+		rewrite: (text) => text.replace(pattern, () => `{{${to}}}`),
+	}
+	localesOf(content).forEach((locale) => {
+		locale.subject = rename.rewrite(locale.subject)
+		locale.preheader = rename.rewrite(locale.preheader)
+		flattenBlocks(locale.blocks).forEach((block) =>
+			renameInBlock(block, rename),
+		)
+	})
+}
+
+const BOOLEAN_OPERATORS: ConditionOperator[] = ['truthy', 'falsy']
+
+const conditionsOf = (block: Block): Condition[] => [
+	...(block.visibleIf ? [block.visibleIf] : []),
+	...(block.type === 'if' ? [block.condition] : []),
+]
+
+interface TypeRule {
+	type: VariableType
+	matches: (block: Block, path: string) => boolean
+}
+
+const TYPE_RULES: TypeRule[] = [
+	{
+		type: 'array',
+		matches: (block, path) => block.type === 'list' && block.source === path,
+	},
+	{
+		type: 'boolean',
+		matches: (block, path) =>
+			conditionsOf(block).some(
+				(condition) =>
+					condition.path === path &&
+					BOOLEAN_OPERATORS.includes(condition.operator),
+			),
+	},
+]
+
+/**
+ * The type a declaration of `path` most likely has, from how the content uses
+ * it: a list source is an array, a "filled in / empty" test a boolean.
+ */
+export function inferVariableType(
+	content: TemplateContent,
+	path: string,
+): VariableType {
+	const blocks = localesOf(content).flatMap((locale) =>
+		flattenBlocks(locale.blocks),
+	)
+	const rule = TYPE_RULES.find((candidate) =>
+		blocks.some((block) => candidate.matches(block, path)),
+	)
+	return rule?.type ?? DEFAULT_TYPE
+}

package/frontend-vue/app/utils/version-history.ts

@@ -0,0 +1,53 @@
+import type { TemplateStatus, TemplateVersionSummary } from '../types/mailing'
+import { describeChanges, NO_SOURCES } from './changes'
+import type { ChangeTranslator } from './changes'
+
+/** What a version's preview resolves with, from its footer buttons. */
+export type VersionPreviewChoice = 'restore' | 'close'
+
+/** Changes a history row names; the others are counted. */
+export const SUMMARY_CHANGE_COUNT = 2
+
+const VERSION_DATE_FORMAT: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'short',
+	day: '2-digit',
+	hour: '2-digit',
+	minute: '2-digit',
+	hourCycle: 'h23',
+}
+
+/** A history row's reading of what its version changed. */
+export interface ChangeSummary {
+	/** The first changes, one sentence each ("EN · Subject changed"). */
+	named: string[]
+	/** How many more the version brought. */
+	more: number
+}
+
+export function changeSummary(
+	version: Pick<TemplateVersionSummary, 'changes'>,
+	t: ChangeTranslator,
+): ChangeSummary {
+	const lines = describeChanges(version.changes, NO_SOURCES, t)
+	return {
+		named: lines.slice(0, SUMMARY_CHANGE_COUNT).map((line) => line.text),
+		more: Math.max(0, lines.length - SUMMARY_CHANGE_COUNT),
+	}
+}
+
+/** Whether customers receive `version` right now. */
+export function isLiveVersion(
+	version: number,
+	current: number,
+	status: TemplateStatus | undefined,
+): boolean {
+	return status === 'live' && version === current
+}
+
+/** When a version was published, to the minute, in the reader's locale. */
+export function formatVersionDate(date: string, locale: string): string {
+	const time = new Date(date)
+	if (Number.isNaN(time.getTime())) return ''
+	return new Intl.DateTimeFormat(locale, VERSION_DATE_FORMAT).format(time)
+}

package/frontend-vue/app/utils/webhook-status.ts

@@ -0,0 +1,170 @@
+/** Why the webhook refused a call. */
+export type WebhookRefusal = 'missing_secret' | 'bad_secret' | 'invalid_event'
+
+/** The last call the webhook accepted. */
+export interface WebhookReceipt {
+	at: string
+	provider: string
+	type: string
+	/** Recorded against a send; not when no send carries its message id. */
+	isMatched: boolean
+	/** The settings' own test event. */
+	isTest: boolean
+}
+
+/** The last call the webhook refused. */
+export interface WebhookRejection {
+	at: string
+	provider: string
+	reason: WebhookRefusal
+}
+
+export interface WebhookStatus {
+	lastReceived: WebhookReceipt | null
+	lastRefused: WebhookRejection | null
+}
+
+/** What "Send a test event" found, and the status after it. */
+export interface WebhookTestResult {
+	isReceived: boolean
+	url: string
+	durationMs: number
+	httpStatus?: number
+	refusal?: WebhookRefusal
+	networkError?: string
+	status: WebhookStatus
+}
+
+export type WebhookLineTone = 'success' | 'warning' | 'error' | 'neutral'
+
+/** One line of the webhook status: what came in last, or was refused. */
+export interface WebhookStatusLine {
+	id: 'received' | 'refused'
+	icon: string
+	tone: WebhookLineTone
+	/** i18n key, interpolated with `params`. */
+	labelKey: string
+	params: Record<string, string>
+	/** i18n key of the refusal's reason, given to the label as `{reason}`. */
+	reasonKey?: string
+	/** When it happened; `null` for "nothing yet". */
+	at: string | null
+}
+
+/** The toast a test event ends with. */
+export interface WebhookTestMessage {
+	color: 'success' | 'error'
+	titleKey: string
+	descriptionKey?: string
+	params: Record<string, string>
+}
+
+const KEY_PREFIX = 'dms_mailing.settings.webhook_status.'
+/** What a front-end proxy answers a cross-site call it refuses. */
+const HTTP_FORBIDDEN = 403
+
+const key = (path: string): string => `${KEY_PREFIX}${path}`
+
+/** The i18n key of a refusal's reason, in plain words. */
+export function refusalKey(reason: WebhookRefusal): string {
+	return key(`refusals.${reason}`)
+}
+
+const receivedKey = (receipt: WebhookReceipt): string => {
+	if (receipt.isTest) return key('received_test')
+	return receipt.isMatched ? key('received') : key('received_unmatched')
+}
+
+const timeOf = (iso: string | undefined): number =>
+	iso ? new Date(iso).getTime() : Number.NEGATIVE_INFINITY
+
+/** Whether the last call refused came after the last one accepted. */
+export function isRefusalLatest(status: WebhookStatus): boolean {
+	if (!status.lastRefused) return false
+	return timeOf(status.lastRefused.at) > timeOf(status.lastReceived?.at)
+}
+
+function receivedLine(receipt: WebhookReceipt | null): WebhookStatusLine {
+	if (!receipt)
+		return {
+			id: 'received',
+			icon: 'i-ph-hourglass',
+			tone: 'neutral',
+			labelKey: key('never_received'),
+			params: {},
+			at: null,
+		}
+	return {
+		id: 'received',
+		icon: 'i-ph-check-circle',
+		tone: receipt.isMatched || receipt.isTest ? 'success' : 'warning',
+		labelKey: receivedKey(receipt),
+		params: { type: receipt.type, provider: receipt.provider },
+		at: receipt.at,
+	}
+}
+
+function refusedLine(status: WebhookStatus): WebhookStatusLine[] {
+	const rejection = status.lastRefused
+	if (!rejection) return []
+	return [
+		{
+			id: 'refused',
+			icon: 'i-ph-shield-warning',
+			tone: isRefusalLatest(status) ? 'error' : 'warning',
+			labelKey: key('refused'),
+			params: { provider: rejection.provider },
+			reasonKey: refusalKey(rejection.reason),
+			at: rejection.at,
+		},
+	]
+}
+
+/**
+ * The lines of the webhook status: the last event received (or none yet),
+ * then the last call refused when there was one, in red while nothing was
+ * accepted since.
+ */
+export function webhookStatusLines(status: WebhookStatus): WebhookStatusLine[] {
+	return [receivedLine(status.lastReceived), ...refusedLine(status)]
+}
+
+/**
+ * What a test event tells: received, refused (and why), answered with an
+ * error status, or not reached at all.
+ */
+export function webhookTestMessage(
+	result: WebhookTestResult,
+): WebhookTestMessage {
+	const params = {
+		url: result.url,
+		duration: String(result.durationMs),
+		status: String(result.httpStatus ?? ''),
+		error: result.networkError ?? '',
+	}
+	if (result.isReceived)
+		return { color: 'success', titleKey: key('test.received'), params }
+	if (result.refusal)
+		return {
+			color: 'error',
+			titleKey: key('test.refused'),
+			descriptionKey: refusalKey(result.refusal),
+			params,
+		}
+	if (result.httpStatus)
+		return {
+			color: 'error',
+			titleKey: key('test.http_error'),
+			descriptionKey:
+				result.httpStatus === HTTP_FORBIDDEN
+					? key('test.proxy_hint')
+					: undefined,
+			params,
+		}
+	return {
+		color: 'error',
+		titleKey: key('test.unreachable'),
+		descriptionKey: key('test.unreachable_hint'),
+		params,
+	}
+}

package/frontend-vue/dms.frontend.ts

@@ -1,28 +1,36 @@
 import { defineAsyncComponent, type Component } from 'vue'
 import type { DmsFrontendModule } from '#dms/frontend-module'
-import templateGallery from './app/plugins/template-gallery-display.client'
+import columnDisplays from './app/plugins/column-displays'
+import templateGallery from './app/plugins/template-gallery-display'
 
 interface VueModule {
 	default: Component
 }
 
+const COMPONENT_PREFIX = 'Mailing'
+const BLOCKS_DIRECTORY = '/components/blocks/'
+const BLOCK_NAME_PREFIX = 'Block'
+
 const components = import.meta.glob<VueModule>('./app/components/**/*.vue')
 
+function componentName(path: string): string {
+	const base = path
+		.split('/')
+		.at(-1)!
+		.replace(/\.vue$/, '')
+	return path.includes(BLOCKS_DIRECTORY) ? `${BLOCK_NAME_PREFIX}${base}` : base
+}
+
 const frontendModule: DmsFrontendModule = {
+	componentPrefix: COMPONENT_PREFIX,
 	setup(sdk) {
 		Object.entries(components)
-			.sort()
+			.sort(([left], [right]) => left.localeCompare(right))
 			.forEach(([path, loader]) => {
-				const name = path
-					.split('/')
-					.at(-1)!
-					.replace(/\.vue$/, '')
-				const prefix = path.includes('/components/blocks/')
-					? 'DmsMailingBlock'
-					: 'DmsMailing'
-				sdk.registerComponent(`${prefix}${name}`, defineAsyncComponent(loader))
+				sdk.registerComponent(componentName(path), defineAsyncComponent(loader))
 			})
-		sdk.registerPlugin(templateGallery, { clientOnly: true })
+		sdk.registerPlugin(templateGallery)
+		sdk.registerPlugin(columnDisplays)
 	},
 }