@antelopejs/dms-mailing 0.3.3 → 0.4.0

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

@@ -0,0 +1,156 @@
+import type { VariableDefinition, VariableType } from '../types/mailing'
+import { deepClone } from './clone'
+import { isPresent, readPath } from './paths'
+
+/**
+ * How a value of a real send is entered: typed, ticked, or a list or an object
+ * taken as is from the test data (neither has a one-line form).
+ */
+export type SendValueKind = 'text' | 'boolean' | 'list' | 'object'
+
+/** One variable the real-send dialog asks a value for. */
+export interface SendField {
+	path: string
+	required: boolean
+	kind: SendValueKind
+}
+
+/** The dialog's values, by variable path. */
+export type SendValues = Record<string, unknown>
+
+const PATH_SEPARATOR = '.'
+const ARRAY_SUFFIX = '[]'
+const RESERVED_SEGMENTS = ['__proto__', 'constructor', 'prototype']
+
+const KIND_BY_TYPE: Partial<Record<VariableType, SendValueKind>> = {
+	boolean: 'boolean',
+	array: 'list',
+}
+
+function kindOfValue(value: unknown): SendValueKind {
+	if (typeof value === 'boolean') return 'boolean'
+	if (Array.isArray(value)) return 'list'
+	return value !== null && typeof value === 'object' ? 'object' : 'text'
+}
+
+function normalize(path: string): string {
+	const trimmed = path.trim()
+	return trimmed.endsWith(ARRAY_SUFFIX)
+		? trimmed.slice(0, -ARRAY_SUFFIX.length)
+		: trimmed
+}
+
+/** Whether `path` holds `other` (`order` holds `order.number`). */
+function isAncestor(path: string, other: string): boolean {
+	return other.startsWith(`${path}${PATH_SEPARATOR}`)
+}
+
+/**
+ * The variables a real send needs values for: the declared ones first, then
+ * the ones the content uses without declaring them, never required. An
+ * undeclared path whose children are asked for (`{{order}}` next to
+ * `{{order.number}}`) gets no field of its own: its children build it.
+ */
+export function sendFields(
+	declared: VariableDefinition[],
+	detected: string[],
+	testData: Record<string, unknown>,
+): SendField[] {
+	const fields = declared.map((variable) => ({
+		path: normalize(variable.path),
+		required: variable.required,
+		kind:
+			KIND_BY_TYPE[variable.type] ??
+			kindOfValue(readPath(testData, variable.path)),
+	}))
+	const known = new Set(fields.map((field) => field.path))
+	const paths = [...new Set(detected.map(normalize))].filter(
+		(path) => path && !known.has(path),
+	)
+	const every = [...known, ...paths]
+	const undeclared = paths
+		.filter((path) => !every.some((other) => isAncestor(path, other)))
+		.map((path) => ({
+			path,
+			required: false,
+			kind: kindOfValue(readPath(testData, path)),
+		}))
+	return [...fields, ...undeclared]
+}
+
+const INITIAL_VALUES: Record<SendValueKind, (value: unknown) => unknown> = {
+	text: (value) => (isPresent(value) ? String(value) : ''),
+	boolean: (value) => Boolean(value),
+	list: (value) => (isPresent(value) ? value : undefined),
+	object: (value) => (isPresent(value) ? value : undefined),
+}
+
+/** The values the dialog opens with: the template's test data. */
+export function initialSendValues(
+	fields: SendField[],
+	testData: Record<string, unknown>,
+): SendValues {
+	return Object.fromEntries(
+		fields.map((field) => [
+			field.path,
+			INITIAL_VALUES[field.kind](readPath(testData, field.path)),
+		]),
+	)
+}
+
+const HAS_VALUE: Record<SendValueKind, (value: unknown) => boolean> = {
+	text: (value) => typeof value === 'string' && value.trim() !== '',
+	boolean: () => true,
+	list: isPresent,
+	object: isPresent,
+}
+
+/** The required variables still without a value: the send waits for them. */
+export function missingRequiredPaths(
+	fields: SendField[],
+	values: SendValues,
+): string[] {
+	return fields
+		.filter((field) => field.required)
+		.filter((field) => !HAS_VALUE[field.kind](values[field.path]))
+		.map((field) => field.path)
+}
+
+function setPath(
+	target: Record<string, unknown>,
+	path: string,
+	value: unknown,
+): void {
+	const segments = path.split(PATH_SEPARATOR)
+	if (segments.some((segment) => RESERVED_SEGMENTS.includes(segment))) return
+	const last = segments.pop() as string
+	const parent = segments.reduce<Record<string, unknown>>((node, segment) => {
+		const child = node[segment]
+		if (child === null || typeof child !== 'object') node[segment] = {}
+		return node[segment] as Record<string, unknown>
+	}, target)
+	parent[last] = value
+}
+
+function depth(field: SendField): number {
+	return field.path.split(PATH_SEPARATOR).length
+}
+
+/**
+ * The `data` a real send carries: every value given, nested by its path. The
+ * shallow paths go first, copied, so a value typed for `order.number` always
+ * wins over the `order` object taken from the test data.
+ */
+export function buildSendData(
+	fields: SendField[],
+	values: SendValues,
+): Record<string, unknown> {
+	const data: Record<string, unknown> = {}
+	fields
+		.filter((field) => HAS_VALUE[field.kind](values[field.path]))
+		.sort((left, right) => depth(left) - depth(right))
+		.forEach((field) =>
+			setPath(data, field.path, deepClone(values[field.path])),
+		)
+	return data
+}

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

@@ -0,0 +1,113 @@
+export type EditorShortcut =
+	| 'save'
+	| 'publish'
+	| 'test'
+	| 'search'
+	| 'delete'
+	| 'duplicate'
+	| 'escape'
+	| 'undo'
+	| 'redo'
+
+/** The parts of a `KeyboardEvent` a shortcut is matched on. */
+export interface KeyStroke {
+	key: string
+	metaKey: boolean
+	ctrlKey: boolean
+	shiftKey: boolean
+	altKey: boolean
+}
+
+interface ShortcutRule {
+	shortcut: EditorShortcut
+	keys: string[]
+	hasModifier: boolean
+	hasShift?: boolean
+	isAllowedWhileTyping: boolean
+}
+
+const rule = (
+	shortcut: EditorShortcut,
+	keys: string[],
+	hasModifier: boolean,
+	isAllowedWhileTyping: boolean,
+	hasShift?: boolean,
+): ShortcutRule => ({
+	shortcut,
+	keys,
+	hasModifier,
+	isAllowedWhileTyping,
+	hasShift,
+})
+
+const RULES: ShortcutRule[] = [
+	rule('save', ['s'], true, true),
+	rule('publish', ['enter'], true, true),
+	rule('duplicate', ['d'], true, false),
+	rule('redo', ['z'], true, false, true),
+	rule('redo', ['y'], true, false),
+	rule('undo', ['z'], true, false, false),
+	rule('test', ['t'], false, false),
+	rule('search', ['/'], false, false),
+	rule('delete', ['backspace', 'delete'], false, false),
+	rule('escape', ['escape'], false, false),
+]
+
+const NON_TEXT_INPUT_TYPES = [
+	'button',
+	'checkbox',
+	'radio',
+	'range',
+	'reset',
+	'submit',
+	'color',
+	'file',
+]
+const TEXT_TAGS = ['TEXTAREA', 'SELECT']
+const INPUT_TAG = 'INPUT'
+const EDITABLE_SELECTOR = '[contenteditable=""], [contenteditable="true"]'
+
+interface TargetLike {
+	tagName?: string
+	type?: string
+	isContentEditable?: boolean
+	closest?: (selector: string) => unknown
+}
+
+/**
+ * Whether the keystroke lands in something the user types in: single-key
+ * shortcuts (T, /, ⌫) must leave those alone.
+ */
+export function isTypingTarget(target: EventTarget | null): boolean {
+	const element = target as TargetLike | null
+	if (!element?.tagName) return false
+	if (TEXT_TAGS.includes(element.tagName)) return true
+	if (element.tagName === INPUT_TAG)
+		return !NON_TEXT_INPUT_TYPES.includes(element.type ?? '')
+	if (element.isContentEditable) return true
+	return Boolean(element.closest?.(EDITABLE_SELECTOR))
+}
+
+function matches(stroke: KeyStroke, candidate: ShortcutRule): boolean {
+	const hasModifier = stroke.metaKey || stroke.ctrlKey
+	if (stroke.altKey || hasModifier !== candidate.hasModifier) return false
+	if (
+		candidate.hasShift !== undefined &&
+		candidate.hasShift !== stroke.shiftKey
+	)
+		return false
+	return candidate.keys.includes(stroke.key.toLowerCase())
+}
+
+/** The editor shortcut a keystroke triggers, or `null`. */
+export function matchShortcut(
+	stroke: KeyStroke,
+	isTyping: boolean,
+): EditorShortcut | null {
+	const found = RULES.find(
+		(candidate) =>
+			matches(stroke, candidate) &&
+			(!isTyping || candidate.isAllowedWhileTyping),
+	)
+	return found?.shortcut ?? null
+}

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

@@ -0,0 +1,82 @@
+/** Mirrors the backend `SLUG_PATTERN`: what `SendTemplate(slug)` accepts. */
+export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+export const MAX_SLUG_LENGTH = 64
+
+export const MAX_NAME_LENGTH = 120
+
+const SLUG_SEPARATOR = '-'
+
+const FIRST_FREE_SUFFIX = 2
+
+export type SlugIssue = 'required' | 'format' | 'too_long' | 'taken'
+
+export type NameIssue = 'required' | 'too_long'
+
+/**
+ * The slug a name suggests: ASCII, lowercase, words joined by dashes, cut to
+ * the maximum length without a trailing dash.
+ */
+export function slugify(name: string): string {
+	return name
+		.normalize('NFD')
+		.replace(/\p{Diacritic}/gu, '')
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, SLUG_SEPARATOR)
+		.replace(/^-+|-+$/g, '')
+		.slice(0, MAX_SLUG_LENGTH)
+		.replace(/-+$/, '')
+}
+
+/**
+ * What is wrong with a slug, or `null` when it can be created: present, in
+ * the backend format, short enough and not used by another template.
+ */
+export function validateSlug(
+	slug: string,
+	takenSlugs: ReadonlySet<string>,
+): SlugIssue | null {
+	if (!slug) return 'required'
+	if (slug.length > MAX_SLUG_LENGTH) return 'too_long'
+	if (!SLUG_PATTERN.test(slug)) return 'format'
+	return takenSlugs.has(slug) ? 'taken' : null
+}
+
+/** What is wrong with a template name, or `null` when it is fine. */
+export function validateName(name: string): NameIssue | null {
+	const trimmed = name.trim()
+	if (!trimmed) return 'required'
+	return trimmed.length > MAX_NAME_LENGTH ? 'too_long' : null
+}
+
+/** `base` with a `-N` suffix, the base cut so the whole fits the slug limit. */
+function suffixedSlug(base: string, suffix: number): string {
+	const ending = `${SLUG_SEPARATOR}${suffix}`
+	const kept = base.slice(0, MAX_SLUG_LENGTH - ending.length).replace(/-+$/, '')
+	return `${kept}${ending}`
+}
+
+/**
+ * The first free slug from `base`: itself, else `base-2`, `base-3`… cut to
+ * the slug limit, so a duplicate of "welcome (copy)" never starts out refused.
+ */
+export function freeSlug(
+	base: string,
+	takenSlugs: ReadonlySet<string>,
+): string {
+	if (!takenSlugs.has(base)) return base
+	let suffix = FIRST_FREE_SUFFIX
+	while (takenSlugs.has(suffixedSlug(base, suffix))) suffix += 1
+	return suffixedSlug(base, suffix)
+}
+
+/**
+ * A name wrapped by `wrap` ("{name} (copy)"), the inner name cut so the whole
+ * stays within the name limit.
+ */
+export function fitName(name: string, wrap: (inner: string) => string): string {
+	const wrapped = wrap(name)
+	if (wrapped.length <= MAX_NAME_LENGTH) return wrapped
+	const room = Math.max(0, MAX_NAME_LENGTH - wrap('').length)
+	return wrap(name.slice(0, room).trimEnd())
+}

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

@@ -0,0 +1,23 @@
+import type { StarterSummary } from '../types/mailing'
+import type { OptionalTranslate } from './categories'
+
+const STARTER_NAME_KEY_PREFIX = 'dms_mailing.starters.names'
+
+/** The i18n key naming a shipped starter ("Order confirmation"). */
+export function starterNameKey(id: string): string {
+	return `${STARTER_NAME_KEY_PREFIX}.${id}`
+}
+
+/**
+ * The starters named in the interface's language; one the catalog does not
+ * know keeps the name the backend gives it.
+ */
+export function localizeStarters(
+	starters: StarterSummary[],
+	translate: OptionalTranslate,
+): StarterSummary[] {
+	return starters.map((starter) => ({
+		...starter,
+		name: translate(starterNameKey(starter.id)) ?? starter.name,
+	}))
+}

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

@@ -0,0 +1,112 @@
+import type { SuppressionReason, SuppressionSummary } from '../types/mailing'
+import { SUPPRESSIONS_PATH } from './pages'
+
+/** The status of a send nothing was sent for: its address is suppressed. */
+export const SUPPRESSED_STATUS = 'suppressed'
+
+const EMAIL_QUERY_KEY = 'email'
+const KEY_PREFIX = 'dms_mailing.suppressions.'
+
+export type { SuppressionReason, SuppressionSummary }
+
+/** A banner of the send drawer about the recipient's suppression. */
+export interface SuppressionNotice {
+	tone: 'warning' | 'info' | 'success'
+	icon: string
+	/** i18n keys, interpolated with `params`. */
+	titleKey: string
+	descriptionKey: string
+	params: Record<string, string>
+	/** Whether the banner links to the address on the suppression list. */
+	hasListLink: boolean
+}
+
+/** What the drawer reads of a send to tell its suppression. */
+export interface SuppressionSend {
+	status: string
+	recipientEmail: string
+}
+
+/** How the drawer words a suppression's date and reason. */
+export interface SuppressionWording {
+	date: (iso: string) => string
+	reason: (reason: SuppressionReason) => string
+}
+
+export interface SuppressionRoute {
+	path: string
+	query: Record<string, string>
+}
+
+export function isSuppressedStatus(status: string | undefined): boolean {
+	return status === SUPPRESSED_STATUS
+}
+
+/** The i18n key naming a suppression reason ("Hard bounce"). */
+export function reasonKey(reason: SuppressionReason): string {
+	return `${KEY_PREFIX}reasons.${reason}`
+}
+
+/** The prefix of the error a suppressed send keeps, one key per reason. */
+const SUPPRESSED_ERROR_PREFIX = '$dms_mailing.errors.suppressed.'
+
+/**
+ * The reason a suppressed send's error names ("manual" out of
+ * `$dms_mailing.errors.suppressed.manual`); `null` for any other error.
+ */
+export function suppressedReasonOf(
+	error: string | undefined,
+): SuppressionReason | null {
+	if (!error?.startsWith(SUPPRESSED_ERROR_PREFIX)) return null
+	return error.slice(SUPPRESSED_ERROR_PREFIX.length) as SuppressionReason
+}
+
+/**
+ * The suppression list, narrowed to one address. The list filters on the
+ * stored address exactly, and addresses are stored trimmed and lowercased.
+ */
+export function suppressionRoute(email: string): SuppressionRoute {
+	return {
+		path: SUPPRESSIONS_PATH,
+		query: { [EMAIL_QUERY_KEY]: email.trim().toLowerCase() },
+	}
+}
+
+const notice = (
+	key: string,
+	tone: SuppressionNotice['tone'],
+	hasListLink: boolean,
+	params: Record<string, string>,
+): SuppressionNotice => ({
+	tone,
+	icon: 'i-ph-prohibit',
+	titleKey: `${KEY_PREFIX}notice.${key}.title`,
+	descriptionKey: `${KEY_PREFIX}notice.${key}.description`,
+	params,
+	hasListLink,
+})
+
+/**
+ * What the drawer says about the recipient's suppression: a send that was
+ * not sent (and whether the address is still suppressed), or an address that
+ * receives nothing any more since this send. `null` when there is nothing to
+ * say.
+ */
+export function suppressionNotice(
+	send: SuppressionSend,
+	suppression: SuppressionSummary | null | undefined,
+	wording: SuppressionWording,
+): SuppressionNotice | null {
+	const params = suppression
+		? {
+				date: wording.date(suppression.createdAt),
+				reason: wording.reason(suppression.reason),
+				email: suppression.email,
+			}
+		: { date: '', reason: '', email: send.recipientEmail }
+	if (isSuppressedStatus(send.status))
+		return suppression
+			? notice('not_sent', 'warning', true, params)
+			: notice('reactivated', 'success', false, params)
+	return suppression ? notice('on_list', 'info', true, params) : null
+}

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

@@ -0,0 +1,165 @@
+import type {
+	Block,
+	FooterBlock,
+	LocaleContent,
+	TemplateContent,
+	VariableDefinition,
+} from '../types/mailing'
+import type { EditorCheck } from './editor-checks'
+import {
+	PREFERENCES_URL_PATH,
+	SYSTEM_PATHS,
+	UNSUBSCRIBE_URL_PATH,
+	pathsInBlocks,
+	textPaths,
+} from './paths'
+
+/** The category whose e-mails are campaigns; the settings never remove it. */
+export const MARKETING_CATEGORY = 'marketing'
+
+type FooterLabelKey = 'unsubscribeLabel' | 'preferencesLabel'
+
+/**
+ * Each footer link: the label that shows it and the URL the caller passes.
+ * The footer links are the system variables of a template's contract, as in
+ * the server's `src/engine/system-variables.ts`, which the layer cannot
+ * import: a link shows when its label is filled.
+ */
+export const FOOTER_LINK_PATHS: Record<FooterLabelKey, string> = {
+	unsubscribeLabel: UNSUBSCRIBE_URL_PATH,
+	preferencesLabel: PREFERENCES_URL_PATH,
+}
+
+const LABEL_KEYS = Object.keys(FOOTER_LINK_PATHS) as FooterLabelKey[]
+const SYSTEM_VARIABLE_TYPE = 'url'
+const CHECK_KEY_PREFIX = 'dms_mailing.editor.checks'
+
+/** A system variable: declared by the content itself, never by hand. */
+export interface SystemVariable extends VariableDefinition {
+	system: true
+}
+
+export function isMarketingCategory(category?: string | null): boolean {
+	return category === MARKETING_CATEGORY
+}
+
+/**
+ * Whether a new footer of this category carries the unsubscribe and
+ * preferences links: a transactional e-mail is not subscribed to, so only an
+ * uncategorised or marketing one does.
+ */
+export function hasFooterLinksByDefault(category?: string | null): boolean {
+	return !category || isMarketingCategory(category)
+}
+
+const isFooter = (block: Block): block is FooterBlock => block.type === 'footer'
+
+/** The URL paths a footer shows a link for: the ones with a label. */
+export function footerLinkPaths(block: FooterBlock): string[] {
+	return LABEL_KEYS.filter((key) => block[key].trim()).map(
+		(key) => FOOTER_LINK_PATHS[key],
+	)
+}
+
+function footersIn(blocks: Block[]): FooterBlock[] {
+	return blocks.flatMap((block) => {
+		if (isFooter(block)) return [block]
+		if (block.type !== 'if') return []
+		return footersIn([...block.children, ...(block.elseChildren ?? [])])
+	})
+}
+
+function localeSystemPaths(locale: LocaleContent): string[] {
+	const linked = footersIn(locale.blocks).flatMap(footerLinkPaths)
+	const referenced = [
+		...textPaths(locale.subject),
+		...textPaths(locale.preheader),
+		...pathsInBlocks(locale.blocks),
+	]
+	return [...linked, ...referenced]
+}
+
+/** The system paths any locale of the content uses, in a stable order. */
+export function contentSystemPaths(
+	content: Pick<TemplateContent, 'locales'>,
+): string[] {
+	const used = new Set(
+		Object.values(content.locales ?? {}).flatMap(localeSystemPaths),
+	)
+	return SYSTEM_PATHS.filter((path) => used.has(path))
+}
+
+/**
+ * The URLs a template's caller passes for the links its content shows, as
+ * declarations: type url, required when the template is marketing.
+ */
+export function systemVariables(
+	content: Pick<TemplateContent, 'locales'>,
+	category?: string | null,
+): SystemVariable[] {
+	const required = isMarketingCategory(category)
+	return contentSystemPaths(content).map((path) => ({
+		path,
+		type: SYSTEM_VARIABLE_TYPE,
+		required,
+		system: true,
+	}))
+}
+
+const hasUnsubscribeLink = (locale: LocaleContent): boolean =>
+	localeSystemPaths(locale).includes(UNSUBSCRIBE_URL_PATH)
+
+const check = (
+	id: string,
+	key: string,
+	params: Record<string, string | number>,
+): EditorCheck => ({
+	id,
+	state: 'warn',
+	key: `${CHECK_KEY_PREFIX}.${key}`,
+	params,
+})
+
+function unlinkedMarketingLocales(
+	content: Pick<TemplateContent, 'locales'>,
+	category?: string | null,
+): EditorCheck[] {
+	if (!isMarketingCategory(category)) return []
+	return Object.entries(content.locales ?? {})
+		.filter(([, locale]) => !hasUnsubscribeLink(locale))
+		.map(([code]) =>
+			check(`unsubscribe-${code}`, 'marketing_no_unsubscribe', {
+				locale: code.toUpperCase(),
+			}),
+		)
+}
+
+/**
+ * What the publish review warns about the footer links: a marketing locale
+ * without an unsubscribe link, and a required system URL the test data does
+ * not carry — a send without it is refused or goes out without the link.
+ */
+export function systemVariableChecks(
+	content: Pick<TemplateContent, 'locales'>,
+	category: string | null | undefined,
+	data: Record<string, unknown>,
+): EditorCheck[] {
+	const missing = systemVariables(content, category)
+		.filter((variable) => variable.required)
+		.filter((variable) => !hasSystemUrl(data, variable.path))
+		.map((variable) =>
+			check(`system-${variable.path}`, 'system_url_missing', {
+				path: variable.path,
+			}),
+		)
+	return [...unlinkedMarketingLocales(content, category), ...missing]
+}
+
+/** Whether the data a canvas previews carries a usable URL for `path`. */
+export function hasSystemUrl(
+	data: Record<string, unknown> | null | undefined,
+	path: string,
+): boolean {
+	const value = data?.[path]
+	return typeof value === 'string' && value.trim() !== ''
+}