@antelopejs/dms-mailing 0.2.2

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

@@ -0,0 +1,365 @@
+/**
+ * Layer-side mirror of the backend mailing contracts.
+ *
+ * The block model, the resolved e-mail and the HTTP payloads are declared once
+ * here so every component and composable reads the same shapes; the source of
+ * truth is `src/types/blocks.ts` / `src/engine/resolved.ts` on the backend.
+ */
+
+export type ConditionOperator = 'truthy' | 'falsy' | 'eq' | 'ne' | 'gt' | 'lt'
+
+export interface Condition {
+	path: string
+	operator: ConditionOperator
+	value: string
+}
+
+export type TextAlign = 'left' | 'center' | 'right'
+
+export type BlockType =
+	| 'hero'
+	| 'heading'
+	| 'paragraph'
+	| 'code'
+	| 'list'
+	| 'total'
+	| 'button'
+	| 'if'
+	| 'divider'
+	| 'footer'
+
+export const BLOCK_TYPES: BlockType[] = [
+	'hero',
+	'heading',
+	'paragraph',
+	'code',
+	'list',
+	'total',
+	'button',
+	'if',
+	'divider',
+	'footer',
+]
+
+export interface BlockBase {
+	id: string
+	type: BlockType
+	visibleIf: Condition | null
+}
+
+export interface HeroBlock extends BlockBase {
+	type: 'hero'
+	imageUrl: string
+	alt: string
+}
+
+export interface HeadingBlock extends BlockBase {
+	type: 'heading'
+	text: string
+	align: TextAlign
+	size: number
+}
+
+export interface ParagraphBlock extends BlockBase {
+	type: 'paragraph'
+	text: string
+	align: TextAlign
+}
+
+export interface CodeBlock extends BlockBase {
+	type: 'code'
+	text: string
+}
+
+export interface ListBlock extends BlockBase {
+	type: 'list'
+	source: string
+	labelPath: string
+	valuePath: string
+}
+
+export interface TotalBlock extends BlockBase {
+	type: 'total'
+	label: string
+	value: string
+}
+
+export interface ButtonBlock extends BlockBase {
+	type: 'button'
+	text: string
+	href: string
+	align: TextAlign
+}
+
+export interface IfBlock extends BlockBase {
+	type: 'if'
+	condition: Condition
+	children: Block[]
+	elseChildren: Block[] | null
+}
+
+export interface DividerBlock extends BlockBase {
+	type: 'divider'
+}
+
+export interface FooterBlock extends BlockBase {
+	type: 'footer'
+	text: string
+	unsubscribeLabel: string
+	preferencesLabel: string
+}
+
+export type Block =
+	| HeroBlock
+	| HeadingBlock
+	| ParagraphBlock
+	| CodeBlock
+	| ListBlock
+	| TotalBlock
+	| ButtonBlock
+	| IfBlock
+	| DividerBlock
+	| FooterBlock
+
+export interface LocaleContent {
+	subject: string
+	preheader: string
+	blocks: Block[]
+}
+
+export interface TemplateContent {
+	locales: Record<string, LocaleContent>
+}
+
+export type VariableType =
+	'string' | 'text' | 'number' | 'money' | 'date' | 'url' | 'boolean' | 'array'
+
+export const VARIABLE_TYPES: VariableType[] = [
+	'string',
+	'text',
+	'number',
+	'money',
+	'date',
+	'url',
+	'boolean',
+	'array',
+]
+
+export interface VariableDefinition {
+	path: string
+	type: VariableType
+	required: boolean
+}
+
+export type TemplateStatus = 'draft' | 'live' | 'archived'
+
+export const TEMPLATE_STATUSES: TemplateStatus[] = ['draft', 'live', 'archived']
+
+export interface ResolvedListRow {
+	label: string
+	value: string
+}
+
+export interface ResolvedHero {
+	id: string
+	type: 'hero'
+	imageUrl: string
+	alt: string
+}
+
+export interface ResolvedHeading {
+	id: string
+	type: 'heading'
+	text: string
+	align: TextAlign
+	size: number
+}
+
+export interface ResolvedParagraph {
+	id: string
+	type: 'paragraph'
+	text: string
+	align: TextAlign
+}
+
+export interface ResolvedCode {
+	id: string
+	type: 'code'
+	text: string
+}
+
+export interface ResolvedList {
+	id: string
+	type: 'list'
+	rows: ResolvedListRow[]
+}
+
+export interface ResolvedTotal {
+	id: string
+	type: 'total'
+	label: string
+	value: string
+}
+
+export interface ResolvedButton {
+	id: string
+	type: 'button'
+	text: string
+	href: string
+	align: TextAlign
+}
+
+export interface ResolvedDivider {
+	id: string
+	type: 'divider'
+}
+
+export interface ResolvedFooter {
+	id: string
+	type: 'footer'
+	text: string
+	unsubscribeLabel: string
+	preferencesLabel: string
+	unsubscribeUrl: string
+	preferencesUrl: string
+}
+
+export type ResolvedBlock =
+	| ResolvedHero
+	| ResolvedHeading
+	| ResolvedParagraph
+	| ResolvedCode
+	| ResolvedList
+	| ResolvedTotal
+	| ResolvedButton
+	| ResolvedDivider
+	| ResolvedFooter
+
+export interface ResolvedEmail {
+	subject: string
+	preheader: string
+	blocks: ResolvedBlock[]
+	missing: string[]
+	hiddenBlockIds: string[]
+}
+
+export type SendStatus =
+	| 'queued'
+	| 'sent'
+	| 'delivered'
+	| 'opened'
+	| 'clicked'
+	| 'bounced'
+	| 'spam'
+	| 'failed'
+	| 'unsubscribed'
+
+export const SEND_STATUSES: SendStatus[] = [
+	'queued',
+	'sent',
+	'delivered',
+	'opened',
+	'clicked',
+	'bounced',
+	'spam',
+	'failed',
+	'unsubscribed',
+]
+
+export type SendEventType = SendStatus
+
+export interface TemplateCategory {
+	id: string
+	label: string
+	icon: string
+}
+
+export interface TemplateRow {
+	_id: string
+	slug: string
+	name: string
+	/** Absent or empty when the template is uncategorised. */
+	category?: string
+	status: TemplateStatus
+	/** Comma-separated locale codes of the content; blank means unknown. */
+	locales?: string
+	updatedAt: string
+	updatedBy: string
+}
+
+export interface TemplateContentResponse {
+	template: TemplateRow
+	content: TemplateContent
+	variables: VariableDefinition[]
+	/** Paths the content actually references, across every locale. */
+	detectedVariables: string[]
+	testData: Record<string, unknown>
+	fallbackLocale: string
+	categories: TemplateCategory[]
+}
+
+export interface PreviewResponse {
+	html: string
+	subject: string
+	locale: string
+	missing: string[]
+	hiddenBlockIds: string[]
+}
+
+export interface SendRow {
+	_id: string
+	templateId: string
+	templateSlug: string
+	locale: string
+	recipientEmail: string
+	recipientName?: string
+	status: SendStatus
+	provider?: string
+	providerMessageId?: string
+	latencyMs: number
+	error?: string
+	source?: string
+	json_variables: string
+	opens: number
+	clicks: number
+	createdAt: string
+	isTest: boolean
+}
+
+export interface SendEventRow {
+	_id: string
+	sendId: string
+	type: SendStatus
+	at: string
+	json_details: string
+}
+
+export interface SendDetailResponse {
+	send: SendRow
+	events: SendEventRow[]
+}
+
+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 FunnelStep {
+	id: string
+	label: string
+	count: number
+	rate: number
+}
+
+export interface ProviderInfo {
+	name: string
+	connected: boolean
+	features: Record<string, boolean> | null
+}

package/frontend-vue/app/utils/blocks/components.ts

@@ -0,0 +1,14 @@
+import type { BlockType } from '../../types/mailing'
+
+export const BLOCK_COMPONENT_NAMES: Record<BlockType, string> = {
+	hero: 'DmsMailingBlockHero',
+	heading: 'DmsMailingBlockHeading',
+	paragraph: 'DmsMailingBlockParagraph',
+	code: 'DmsMailingBlockCode',
+	list: 'DmsMailingBlockList',
+	total: 'DmsMailingBlockTotal',
+	button: 'DmsMailingBlockButton',
+	if: 'DmsMailingEditorIfBlock',
+	divider: 'DmsMailingBlockDivider',
+	footer: 'DmsMailingBlockFooter',
+}

package/frontend-vue/app/utils/blocks/dnd.ts

@@ -0,0 +1,15 @@
+import type { Block } from '../../types/mailing'
+import type { PaletteEntry } from './factory'
+import { createBlock } from './factory'
+
+export const DRAG_GROUP = { name: 'mailing-blocks' }
+export const PALETTE_GROUP = {
+	name: 'mailing-blocks',
+	pull: 'clone' as const,
+	put: false,
+}
+export const DRAG_HANDLE = '.mailing-drag-handle'
+
+export function cloneFromPalette(entry: PaletteEntry): Block {
+	return createBlock(entry.type)
+}

package/frontend-vue/app/utils/blocks/factory.ts

@@ -0,0 +1,100 @@
+import type { Block, BlockType } from '../../types/mailing'
+
+export interface PaletteEntry {
+	type: BlockType
+	icon: string
+}
+
+export const BLOCK_PALETTE: PaletteEntry[] = [
+	{ type: 'heading', icon: 'i-ph-text-h' },
+	{ type: 'paragraph', icon: 'i-ph-text-align-left' },
+	{ type: 'button', icon: 'i-ph-cursor-click' },
+	{ type: 'hero', icon: 'i-ph-image' },
+	{ type: 'list', icon: 'i-ph-table' },
+	{ type: 'total', icon: 'i-ph-sigma' },
+	{ type: 'code', icon: 'i-ph-lock-key' },
+	{ type: 'divider', icon: 'i-ph-minus' },
+	{ type: 'footer', icon: 'i-ph-list-dashes' },
+]
+
+export const LOGIC_PALETTE: PaletteEntry[] = [
+	{ type: 'if', icon: 'i-ph-git-branch' },
+]
+
+const ID_RADIX = 36
+const ID_LENGTH = 6
+const ID_PADDING = '0'
+const DEFAULT_HEADING_SIZE = 23
+
+export function newBlockId(type: BlockType): string {
+	const random = Math.random()
+		.toString(ID_RADIX)
+		.slice(2, 2 + ID_LENGTH)
+	return `${type}_${random.padEnd(ID_LENGTH, ID_PADDING)}`
+}
+
+type BlockBuilder = (id: string) => Block
+
+const BUILDERS: Record<BlockType, BlockBuilder> = {
+	hero: (id) => ({ id, type: 'hero', imageUrl: '', alt: '', visibleIf: null }),
+	heading: (id) => ({
+		id,
+		type: 'heading',
+		text: 'New heading',
+		align: 'left',
+		size: DEFAULT_HEADING_SIZE,
+		visibleIf: null,
+	}),
+	paragraph: (id) => ({
+		id,
+		type: 'paragraph',
+		text: 'Paragraph text…',
+		align: 'left',
+		visibleIf: null,
+	}),
+	code: (id) => ({ id, type: 'code', text: '{{code}}', visibleIf: null }),
+	list: (id) => ({
+		id,
+		type: 'list',
+		source: 'order.lines',
+		labelPath: 'label',
+		valuePath: 'total',
+		visibleIf: null,
+	}),
+	total: (id) => ({
+		id,
+		type: 'total',
+		label: 'Total',
+		value: '{{order.total}}',
+		visibleIf: null,
+	}),
+	button: (id) => ({
+		id,
+		type: 'button',
+		text: 'Button',
+		href: 'https://',
+		align: 'left',
+		visibleIf: null,
+	}),
+	if: (id) => ({
+		id,
+		type: 'if',
+		condition: { path: 'contact.isPro', operator: 'truthy', value: '' },
+		children: [],
+		elseChildren: null,
+		visibleIf: null,
+	}),
+	divider: (id) => ({ id, type: 'divider', visibleIf: null }),
+	footer: (id) => ({
+		id,
+		type: 'footer',
+		text: '',
+		unsubscribeLabel: 'Unsubscribe',
+		preferencesLabel: 'Preferences',
+		visibleIf: null,
+	}),
+}
+
+export function createBlock(type: BlockType): Block {
+	return BUILDERS[type](newBlockId(type))
+}

package/frontend-vue/app/utils/blocks/fields.ts

@@ -0,0 +1,58 @@
+import type { BlockType } from '../../types/mailing'
+
+export type FieldKind = 'text' | 'textarea' | 'url' | 'align' | 'size'
+
+export interface BlockField {
+	key: string
+	kind: FieldKind
+	label: string
+	help?: string
+}
+
+const LABEL_PREFIX = 'dms_mailing.editor.block_settings'
+
+const snakeCase = (key: string): string =>
+	key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+
+const field = (key: string, kind: FieldKind, help?: string): BlockField => ({
+	key,
+	kind,
+	label: `${LABEL_PREFIX}.${snakeCase(key)}`,
+	help,
+})
+
+const FIELDS: Record<BlockType, BlockField[]> = {
+	hero: [field('imageUrl', 'url'), field('alt', 'text')],
+	heading: [
+		field('text', 'textarea', 'insert_hint'),
+		field('align', 'align'),
+		field('size', 'size'),
+	],
+	paragraph: [
+		field('text', 'textarea', 'insert_hint'),
+		field('align', 'align'),
+	],
+	code: [field('text', 'text')],
+	list: [
+		field('source', 'text', 'source_help'),
+		field('labelPath', 'text'),
+		field('valuePath', 'text'),
+	],
+	total: [field('label', 'text'), field('value', 'text')],
+	button: [
+		field('text', 'text'),
+		field('href', 'url'),
+		field('align', 'align'),
+	],
+	if: [],
+	divider: [],
+	footer: [
+		field('text', 'textarea'),
+		field('unsubscribeLabel', 'text'),
+		field('preferencesLabel', 'text'),
+	],
+}
+
+export function fieldsFor(type: BlockType): BlockField[] {
+	return FIELDS[type]
+}

package/frontend-vue/app/utils/blocks/index.ts

@@ -0,0 +1,5 @@
+export * from './components'
+export * from './dnd'
+export * from './factory'
+export * from './fields'
+export * from './tree'

package/frontend-vue/app/utils/blocks/tree.ts

@@ -0,0 +1,74 @@
+import type { Block, IfBlock } from '../../types/mailing'
+import { deepClone } from '../clone'
+import { newBlockId } from './factory'
+
+const isIf = (block: Block): block is IfBlock => block.type === 'if'
+
+const branchesOf = (block: Block): Block[][] =>
+	isIf(block)
+		? [block.children, ...(block.elseChildren ? [block.elseChildren] : [])]
+		: []
+
+export function findParentList(blocks: Block[], id: string): Block[] | null {
+	if (blocks.some((block) => block.id === id)) return blocks
+	for (const block of blocks) {
+		for (const branch of branchesOf(block)) {
+			const found = findParentList(branch, id)
+			if (found) return found
+		}
+	}
+	return null
+}
+
+export function findBlock(blocks: Block[], id: string): Block | null {
+	return findParentList(blocks, id)?.find((block) => block.id === id) ?? null
+}
+
+export function moveBlock(
+	blocks: Block[],
+	id: string,
+	direction: -1 | 1,
+): boolean {
+	const list = findParentList(blocks, id)
+	if (!list) return false
+	const index = list.findIndex((block) => block.id === id)
+	const target = index + direction
+	if (target < 0 || target >= list.length) return false
+	const [moved] = list.splice(index, 1)
+	list.splice(target, 0, moved as Block)
+	return true
+}
+
+export function cloneWithNewIds(block: Block): Block {
+	const copy = deepClone(block)
+	copy.id = newBlockId(copy.type)
+	if (!isIf(copy)) return copy
+	copy.children = copy.children.map(cloneWithNewIds)
+	copy.elseChildren = copy.elseChildren
+		? copy.elseChildren.map(cloneWithNewIds)
+		: null
+	return copy
+}
+
+export function duplicateBlock(blocks: Block[], id: string): Block | null {
+	const list = findParentList(blocks, id)
+	if (!list) return null
+	const index = list.findIndex((block) => block.id === id)
+	const copy = cloneWithNewIds(list[index] as Block)
+	list.splice(index + 1, 0, copy)
+	return copy
+}
+
+export function removeBlock(blocks: Block[], id: string): boolean {
+	const list = findParentList(blocks, id)
+	if (!list) return false
+	list.splice(
+		list.findIndex((block) => block.id === id),
+		1,
+	)
+	return true
+}
+
+export function insertBlock(list: Block[], index: number, block: Block): void {
+	list.splice(index, 0, block)
+}

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

@@ -0,0 +1,54 @@
+import type { TemplateCategory } from '../types/mailing'
+
+const ID_SEPARATOR = '-'
+
+/**
+ * Reads the category list off the settings form field, which stores it either
+ * as the array or as the JSON string the DMS round-trips. Never throws: this
+ * runs while rendering the field.
+ */
+export function parseCategories(
+	value: TemplateCategory[] | string | null | undefined,
+): TemplateCategory[] {
+	if (Array.isArray(value)) return value
+	if (!value) return []
+	try {
+		const parsed: unknown = JSON.parse(value)
+		return Array.isArray(parsed) ? (parsed as TemplateCategory[]) : []
+	} catch {
+		return []
+	}
+}
+
+export function serializeCategories(categories: TemplateCategory[]): string {
+	return JSON.stringify(categories)
+}
+
+/**
+ * The id a new category gets from its label. Ids are stored on every template,
+ * so they stay ASCII and stable rather than following a later rename.
+ */
+export function slugifyId(label: string): string {
+	return label
+		.normalize('NFD')
+		.replace(/\p{Diacritic}/gu, '')
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, ID_SEPARATOR)
+		.replace(/^-+|-+$/g, '')
+}
+
+/**
+ * `USelect` is backed by Reka's `Select`, which reserves the empty string for
+ * "nothing selected". An item carrying it makes the listbox refuse to open at
+ * all — silently, with no console error. "No category" therefore travels as
+ * this sentinel inside the widget and is mapped back on the way out.
+ */
+export const NO_CATEGORY = '__none__'
+
+export function toCategoryOption(value: string | null | undefined): string {
+	return value || NO_CATEGORY
+}
+
+export function fromCategoryOption(value: string): string {
+	return value === NO_CATEGORY ? '' : value
+}

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

@@ -0,0 +1,3 @@
+export function deepClone<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T
+}