@antelopejs/dms-mailing 0.2.2

package/frontend-vue/app/components/editor/EditorWorkspace.vue

@@ -0,0 +1,189 @@
+<script setup lang="ts">
+import { computed, reactive, ref } from 'vue'
+import type {
+	PreviewResponse,
+	TemplateContentResponse,
+	TemplateRow,
+	TemplateStatus,
+	VariableDefinition,
+} from '../../types/mailing'
+import { provideEditorContext } from '../../composables/useEditorContext'
+import { useMailingApi } from '../../composables/useMailingApi'
+import { createEditorState } from '../../composables/useTemplateEditor'
+import { deepClone } from '../../utils/clone'
+
+interface Props {
+	loaded: TemplateContentResponse
+	templateId: string
+	requestedLocale: string | null
+}
+
+const props = defineProps<Props>()
+
+const { t } = useI18n()
+const toast = useToast()
+const { processApiMessage } = useTranslation()
+const { confirm } = useConfirm()
+const { uniqueLocales } = useUniqueLocales()
+const { registerGuard } = usePageLeaveGuard()
+const api = useMailingApi()
+
+const localeCodes = computed(() =>
+	uniqueLocales.value.map((locale) => locale.code),
+)
+
+const editor = createEditorState(
+	props.loaded.content,
+	props.requestedLocale ?? props.loaded.fallbackLocale,
+	localeCodes.value,
+)
+
+const template = ref<TemplateRow>(props.loaded.template)
+const name = ref(props.loaded.template.name)
+const category = ref(props.loaded.template.category ?? '')
+const variables = ref<VariableDefinition[]>(props.loaded.variables ?? [])
+const detectedVariables = ref<string[]>(props.loaded.detectedVariables ?? [])
+const testData = ref(JSON.stringify(props.loaded.testData ?? {}, null, 2))
+const preview = ref<PreviewResponse | null>(null)
+const simulation = reactive<Record<string, boolean>>({})
+const savedContent = ref(deepClone(props.loaded.content))
+const testSendOpen = ref(false)
+
+registerGuard(
+	() =>
+		editor.dirty === 0 ||
+		confirm({
+			title: t('dms_mailing.editor.leave_guard'),
+			description: t('dms_mailing.editor.unsaved', { count: editor.dirty }),
+			confirmColor: 'error',
+		}),
+)
+
+// The slug travels unchanged: `edit` replaces the writable fields, so omitting
+// it would null it.
+async function saveDetails(): Promise<void> {
+	const trimmed = name.value.trim() || template.value.name
+	const next = {
+		name: trimmed,
+		slug: template.value.slug,
+		category: category.value || undefined,
+	}
+	if (
+		next.name === template.value.name &&
+		next.category === (template.value.category || undefined)
+	) {
+		return
+	}
+	await api.saveTemplateDetails(props.templateId, next)
+	template.value = { ...template.value, ...next }
+	name.value = trimmed
+}
+
+/**
+ * Surfaces a rejected call. Save and the status actions used to discard their
+ * promise at the click handler, so a duplicate slug, a 403 or a dropped
+ * connection left the author with no toast at all — and an editor that still
+ * looked saved.
+ */
+function reportFailure(error: unknown): void {
+	toast.add({
+		color: 'error',
+		title: processApiMessage(
+			(error as { data?: { message?: string } }).data?.message ?? error,
+		),
+	})
+}
+
+async function save(): Promise<void> {
+	try {
+		await saveDetails()
+		const { detectedVariables: detected } = await api.saveContent(
+			props.templateId,
+			deepClone(editor.content),
+		)
+		detectedVariables.value = detected ?? detectedVariables.value
+		savedContent.value = deepClone(editor.content)
+		editor.markSaved()
+		toast.add({ title: t('dms_mailing.editor.saved'), color: 'success' })
+	} catch (error) {
+		reportFailure(error)
+	}
+}
+
+type StatusAction = 'publish' | 'unpublish' | 'archive'
+
+async function runStatusAction(action: StatusAction): Promise<void> {
+	const calls = {
+		publish: api.publish,
+		unpublish: api.unpublish,
+		archive: api.archive,
+	}
+	try {
+		const { status } = await calls[action](props.templateId)
+		template.value = { ...template.value, status: status as TemplateStatus }
+		toast.add({
+			title: t(`dms_mailing.templates.actions.${action}`),
+			color: 'success',
+		})
+	} catch (error) {
+		reportFailure(error)
+	}
+}
+
+function publish(): Promise<void> {
+	return runStatusAction('publish')
+}
+
+async function discard(): Promise<void> {
+	const confirmed = await confirm({
+		title: t('dms_mailing.editor.discard_title'),
+		description: t('dms_mailing.editor.discard_description'),
+		confirmColor: 'error',
+	})
+	if (!confirmed) return
+	editor.reset(savedContent.value)
+}
+
+provideEditorContext({
+	editor,
+	api,
+	templateId: props.templateId,
+	template,
+	variables,
+	detectedVariables,
+	name,
+	category,
+	runStatusAction,
+	testData,
+	preview,
+	simulation,
+	save,
+	publish,
+	discard,
+	openTestSend: () => (testSendOpen.value = true),
+})
+</script>
+
+<template>
+	<div class="flex h-full min-h-0 flex-col">
+		<DmsMailingEditorToolbar />
+		<DmsMailingEditorDraftBar v-if="editor.dirty > 0" />
+
+		<div class="flex min-h-0 flex-1">
+			<DmsMailingEditorMissingLocale
+				v-if="!editor.current"
+				:fallback="loaded.fallbackLocale"
+			/>
+			<DmsMailingEditorCanvas v-else />
+
+			<aside
+				v-if="editor.railOpen"
+				class="border-default bg-default flex w-[340px] shrink-0 flex-col overflow-y-auto border-l"
+			>
+				<DmsMailingEditorRail />
+			</aside>
+		</div>
+
+		<DmsMailingEditorTestSendModal v-model:open="testSendOpen" />
+	</div>
+</template>

package/frontend-vue/app/composables/useEditorContext.ts

@@ -0,0 +1,44 @@
+import { inject, provide } from 'vue'
+import type { InjectionKey, Ref } from 'vue'
+import type {
+	PreviewResponse,
+	TemplateRow,
+	VariableDefinition,
+} from '../types/mailing'
+import type { MailingApi } from './useMailingApi'
+import type { EditorState } from './useTemplateEditor'
+
+export interface EditorContext {
+	editor: EditorState
+	api: MailingApi
+	templateId: string
+	template: Ref<TemplateRow>
+	variables: Ref<VariableDefinition[]>
+	detectedVariables: Ref<string[]>
+	name: Ref<string>
+	category: Ref<string>
+	runStatusAction: (
+		action: 'publish' | 'unpublish' | 'archive',
+	) => Promise<void>
+	testData: Ref<string>
+	preview: Ref<PreviewResponse | null>
+	simulation: Record<string, boolean>
+	save: () => Promise<void>
+	publish: () => Promise<void>
+	discard: () => Promise<void>
+	openTestSend: () => void
+}
+
+const EDITOR_KEY: InjectionKey<EditorContext> = Symbol('dms-mailing-editor')
+const MISSING_CONTEXT =
+	'useEditorContext() must be called inside DmsMailingEditor'
+
+export function provideEditorContext(context: EditorContext): void {
+	provide(EDITOR_KEY, context)
+}
+
+export function useEditorContext(): EditorContext {
+	const context = inject(EDITOR_KEY, null)
+	if (!context) throw new Error(MISSING_CONTEXT)
+	return context
+}

package/frontend-vue/app/composables/useMailingApi.ts

@@ -0,0 +1,197 @@
+import type {
+	AttentionItem,
+	FunnelStep,
+	PreviewResponse,
+	ProviderInfo,
+	SendDetailResponse,
+	TemplateContent,
+	TemplateCategory,
+	TemplateContentResponse,
+	TemplateRow,
+	VariableDefinition,
+} from '../types/mailing'
+
+const BASE = '/api/mailing'
+
+/** Far above any real tenant's template count; the data-api caps at 100. */
+const TEMPLATE_LIST_LIMIT = '100'
+
+/**
+ * Joins the module's API segments. Exported on its own so the path shape stays
+ * testable without a Nuxt runtime.
+ */
+export function mailingPath(...segments: string[]): string {
+	return [BASE, ...segments].join('/')
+}
+
+export interface PreviewInput {
+	/** Absent lets the server pick the tenant fallback locale. */
+	locale?: string
+	content?: TemplateContent
+	data?: Record<string, unknown>
+}
+
+export interface TestSendInput extends PreviewInput {
+	to: string[]
+}
+
+/** A real send never carries a content override: it uses the saved template. */
+export interface RealSendInput {
+	to: string[]
+	locale?: string
+	data?: Record<string, unknown>
+}
+
+export interface SendResult {
+	sendId: string
+	status: string
+	error?: string
+}
+
+export interface AttentionResponse {
+	items: AttentionItem[]
+}
+
+export interface FunnelResponse {
+	steps: FunnelStep[]
+}
+
+export interface SavedResponse {
+	saved: boolean
+	detectedVariables: string[]
+}
+
+/**
+ * The template's own writable fields. All of them, always: the data-api `edit`
+ * route replaces the writable set rather than patching it, so a body missing
+ * one nulls it in the database.
+ */
+export interface TemplateDetails {
+	name: string
+	slug: string
+	category?: string
+}
+
+export interface CategoriesResponse {
+	categories: TemplateCategory[]
+}
+
+export interface TemplateListResponse {
+	results: TemplateRow[]
+	total: number
+}
+
+export interface CreateTemplateInput {
+	name: string
+	slug: string
+	category?: string
+	/** Absent starts blank; otherwise the template to copy. */
+	sourceTemplateId?: string
+}
+
+export interface StatusResponse {
+	status: string
+}
+
+export interface DuplicateResponse {
+	id: string
+}
+
+export interface VariablesResponse {
+	variables: VariableDefinition[]
+}
+
+export interface TestDataResponse {
+	data: Record<string, unknown>
+}
+
+export interface TestSendResponse {
+	results: SendResult[]
+}
+
+export interface HtmlResponse {
+	html: string
+}
+
+export interface MailingSettings extends Record<string, unknown> {
+	blockOnMissingVariables?: boolean
+}
+
+/**
+ * The single place that knows the mailing endpoints; every component reads
+ * through it so a route change is a one-file edit.
+ */
+export function useMailingApi() {
+	const { $authFetch } = useAuthFetch()
+	const post = <T>(path: string, body: object) =>
+		$authFetch<T>(path, { method: 'POST', body })
+
+	return {
+		provider: () => $authFetch<ProviderInfo>(mailingPath('provider')),
+		attention: (query: Record<string, string>) =>
+			$authFetch<AttentionResponse>(mailingPath('metrics', 'attention'), {
+				query,
+			}),
+		funnel: (query: Record<string, string>) =>
+			$authFetch<FunnelResponse>(mailingPath('metrics', 'funnel'), { query }),
+		templateContent: (id: string) =>
+			$authFetch<TemplateContentResponse>(
+				mailingPath('templates', id, 'content'),
+			),
+		saveTemplateDetails: (id: string, details: TemplateDetails) =>
+			$authFetch<unknown>(mailingPath('tables', 'templates', 'edit'), {
+				method: 'PUT',
+				query: { id },
+				body: details,
+			}),
+		listCategories: () =>
+			$authFetch<CategoriesResponse>(mailingPath('templates', 'categories')),
+		listTemplates: () =>
+			$authFetch<TemplateListResponse>(
+				mailingPath('tables', 'templates', 'list'),
+				{ query: { limit: TEMPLATE_LIST_LIMIT, sortKey: 'name' } },
+			),
+		createTemplate: (input: CreateTemplateInput) =>
+			post<string[]>(mailingPath('tables', 'templates', 'new'), input),
+		saveContent: (id: string, content: TemplateContent) =>
+			post<SavedResponse>(mailingPath('templates', id, 'content'), {
+				content,
+			}),
+		publish: (id: string) =>
+			post<StatusResponse>(mailingPath('templates', id, 'publish'), {}),
+		unpublish: (id: string) =>
+			post<StatusResponse>(mailingPath('templates', id, 'unpublish'), {}),
+		archive: (id: string) =>
+			post<StatusResponse>(mailingPath('templates', id, 'archive'), {}),
+		duplicate: (id: string, slug: string, name: string) =>
+			post<DuplicateResponse>(mailingPath('templates', id, 'duplicate'), {
+				slug,
+				name,
+			}),
+		saveVariables: (id: string, variables: VariableDefinition[]) =>
+			post<VariablesResponse>(mailingPath('templates', id, 'variables'), {
+				variables,
+			}),
+		saveTestData: (id: string, data: Record<string, unknown>) =>
+			post<TestDataResponse>(mailingPath('templates', id, 'test-data'), {
+				data,
+			}),
+		preview: (id: string, input: PreviewInput) =>
+			post<PreviewResponse>(mailingPath('templates', id, 'preview'), input),
+		realSend: (id: string, input: RealSendInput) =>
+			post<TestSendResponse>(mailingPath('templates', id, 'send'), input),
+		testSend: (id: string, input: TestSendInput) =>
+			post<TestSendResponse>(mailingPath('templates', id, 'test-send'), input),
+		send: (id: string) =>
+			$authFetch<SendDetailResponse>(mailingPath('sends', id)),
+		sendHtml: (id: string) =>
+			$authFetch<HtmlResponse>(mailingPath('sends', id, 'html')),
+		replay: (id: string) =>
+			post<SendResult>(mailingPath('sends', id, 'replay'), {}),
+		settings: () => $authFetch<MailingSettings>(mailingPath('settings')),
+		saveSettings: (settings: MailingSettings) =>
+			post<MailingSettings>(mailingPath('settings'), settings),
+	}
+}
+
+export type MailingApi = ReturnType<typeof useMailingApi>

package/frontend-vue/app/composables/useMailingPeriodData.ts

@@ -0,0 +1,39 @@
+import type { Ref } from 'vue'
+import { periodQuery } from '../utils/period'
+
+export interface PeriodDataState<T> {
+	data: Ref<T | null>
+	loading: Ref<boolean>
+	refresh: () => Promise<void>
+}
+
+/**
+ * Reads a DMS period-selector scope and re-runs `load` whenever the window
+ * changes. The scope registers when the selector mounts, so the first run is
+ * driven by the watcher rather than by `onMounted`.
+ */
+export function useMailingPeriodData<T>(
+	scope: string,
+	load: (query: Record<string, string>) => Promise<T>,
+): PeriodDataState<T> {
+	const period = usePeriodScope(scope)
+	const data = ref(null) as Ref<T | null>
+	const loading = ref(false)
+
+	async function refresh(): Promise<void> {
+		const state = period.value
+		if (!state) return
+		loading.value = true
+		try {
+			data.value = await load(periodQuery(state))
+		} catch {
+			data.value = null
+		} finally {
+			loading.value = false
+		}
+	}
+
+	watch(period, refresh, { immediate: true })
+
+	return { data, loading, refresh }
+}

package/frontend-vue/app/composables/useTemplateDrawer.ts

@@ -0,0 +1,90 @@
+import type { Component } from 'vue'
+import type { TemplateContent, TemplateRow } from '../types/mailing'
+
+/**
+ * How a DMS row action reaches these containers (verified against
+ * `@antelopejs/interface-dms/base/types/action-target` and
+ * `useTableViewRowActions.ts`):
+ *
+ * - the declared target is
+ *   `{ type: 'drawer' | 'modal', component: CustomComponent('DmsMailingX'), title?, description?, size? }`;
+ *   there is no `event` target type — the set is
+ *   `drawer | modal | page | external | api | exportJob`.
+ * - the DMS opens the container itself and mounts the component with
+ *   `{ ...target.component.options, pageId, componentId, containerId, rowData, onSuccessCallback }`,
+ *   where `rowData` is the full row and `onSuccessCallback` closes the
+ *   container and refreshes the table view.
+ *
+ * The same components are opened from our own surfaces (the gallery) through
+ * `useDrawer()` / `useModal()` with an explicit id instead of `rowData`.
+ */
+const TEMPLATE_DRAWER_COMPONENT = 'DmsMailingTemplateDrawer'
+const TEST_SEND_MODAL_COMPONENT = 'DmsMailingTestSendModal'
+const DRAWER_DIRECTION = 'right'
+const TEST_SEND_MODAL_SIZE = 'md'
+
+export interface TemplateDrawerHandle {
+	open: (templateId: string) => void
+}
+
+export function useTemplateDrawer(): TemplateDrawerHandle {
+	const { open } = useDrawer()
+	const { t } = useI18n()
+	const component = resolveComponent(TEMPLATE_DRAWER_COMPONENT) as Component
+
+	return {
+		open: (templateId: string) =>
+			void open({
+				title: t('dms_mailing.templates.actions.details'),
+				component,
+				componentOptions: { templateId },
+				direction: DRAWER_DIRECTION,
+			}),
+	}
+}
+
+export interface TestSendModalHandle {
+	open: (
+		templateId: string,
+		locale?: string,
+		content?: TemplateContent,
+		data?: Record<string, unknown>,
+	) => void
+}
+
+export interface RealSendModalHandle {
+	open: (templateId: string, rowData: TemplateRow, locale?: string) => void
+}
+
+/** The real-send modal: same component, `real` mode, its own title. */
+export function useRealSendModal(): RealSendModalHandle {
+	const { open } = useModal()
+	const { t } = useI18n()
+	const component = resolveComponent(TEST_SEND_MODAL_COMPONENT) as Component
+
+	return {
+		open: (templateId, rowData, locale) =>
+			void open({
+				title: t('dms_mailing.templates.send_modal.title'),
+				component,
+				componentOptions: { templateId, rowData, locale, mode: 'real' },
+				size: TEST_SEND_MODAL_SIZE,
+			}),
+	}
+}
+
+export function useTestSendModal(): TestSendModalHandle {
+	const { open } = useModal()
+	const { t } = useI18n()
+	const component = resolveComponent(TEST_SEND_MODAL_COMPONENT) as Component
+
+	return {
+		open: (templateId, locale, content, data) =>
+			void open({
+				title: t('dms_mailing.editor.test_send_modal.title'),
+				component,
+				componentOptions: { templateId, locale, content, data },
+				size: TEST_SEND_MODAL_SIZE,
+			}),
+	}
+}