@antelopejs/dms-mailing 0.3.4 → 0.4.0

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

@@ -0,0 +1,299 @@
+import { computed, onBeforeUnmount, reactive, watch } from 'vue'
+import type {
+	TemplateCategory,
+	TemplateChange,
+	TemplateContent,
+	TemplateContentResponse,
+	TemplatePerformance,
+	TemplateRow,
+} from '../types/mailing'
+import type { MailingApi, TemplateDetails } from './useMailingApi'
+import type { EditorState } from './useTemplateEditor'
+import type { TokenFieldHandle } from './useEditorContext'
+import { deepClone } from '../utils/clone'
+import { collectContentPaths } from '../utils/paths'
+import { parseTestData } from '../utils/testData'
+import type { SaveStatus } from '../utils/lifecycle'
+import { noticeFor, statusKeyOf } from '../utils/lifecycle'
+import {
+	apiErrorMessage,
+	apiErrorStatus,
+	HTTP_CONFLICT,
+} from '../utils/api-error'
+
+export type { SaveStatus } from '../utils/lifecycle'
+
+/** The draft is written this long after the last change. */
+export const AUTOSAVE_DELAY_MS = 1500
+
+/** A failed save is tried again after this, doubling up to the maximum. */
+export const RETRY_BASE_DELAY_MS = 2000
+export const RETRY_MAX_DELAY_MS = 60_000
+
+/** Browsers refuse a `keepalive` request whose body passes 64 KiB. */
+const KEEPALIVE_MAX_LENGTH = 60_000
+const SERVER_ERROR_STATUS = 500
+const NETWORK_ERROR_STATUS = 0
+const DRAFT_CONFLICT = '$dms_mailing.errors.draft_conflict'
+const DRAFT_CONFLICT_KEY = 'draft_conflict'
+
+const JSON_INDENT = 2
+
+/**
+ * Everything the editor knows about the template besides its draft (the
+ * content and the variable declarations live in the editor state).
+ */
+export interface SessionState {
+	template: TemplateRow
+	version: number
+	/** The draft revision the next save or publish carries back. */
+	revision: number
+	publishedContent: TemplateContent | null
+	changes: TemplateChange[]
+	serverDetected: string[]
+	testDataSource: string
+	savedTestDataSource: string
+	categories: TemplateCategory[]
+	fallbackLocale: string
+	blockOnMissingVariables: boolean
+	performance: TemplatePerformance | null
+	saveStatus: SaveStatus
+	activeField: TokenFieldHandle | null
+}
+
+export interface SessionDeps {
+	editor: EditorState
+	api: MailingApi
+	templateId: string
+	loaded: TemplateContentResponse
+	onError: (error: unknown) => void
+}
+
+function createState(loaded: TemplateContentResponse): SessionState {
+	const testData = JSON.stringify(loaded.testData, null, JSON_INDENT)
+	return reactive({
+		template: { ...loaded.template },
+		version: loaded.version,
+		revision: loaded.revision,
+		publishedContent: loaded.publishedContent,
+		changes: loaded.changes,
+		serverDetected: loaded.detectedVariables,
+		testDataSource: testData,
+		savedTestDataSource: testData,
+		categories: loaded.categories,
+		fallbackLocale: loaded.fallbackLocale,
+		blockOnMissingVariables: loaded.blockOnMissingVariables,
+		performance: null,
+		saveStatus: 'idle',
+		activeField: null,
+	}) as SessionState
+}
+
+function createViews(state: SessionState, editor: EditorState) {
+	return {
+		detected: computed(() => [
+			...new Set([
+				...state.serverDetected,
+				...collectContentPaths(editor.content),
+			]),
+		]),
+		testData: computed(() => parseTestData(state.testDataSource)),
+		isTestDataDirty: computed(
+			() => state.testDataSource !== state.savedTestDataSource,
+		),
+		isSaving: computed(() => state.saveStatus === 'saving' || editor.dirty > 0),
+		/** Work leaving the editor would lose: a failed save, a conflict, test data. */
+		hasUnsavedWork: computed(
+			() =>
+				state.saveStatus === 'error' ||
+				state.saveStatus === 'conflict' ||
+				state.testDataSource !== state.savedTestDataSource,
+		),
+		statusKey: computed(() =>
+			statusKeyOf(state.template.status, state.version),
+		),
+		notice: computed(() =>
+			noticeFor({
+				status: state.template.status,
+				version: state.version,
+				changeCount: state.changes.length,
+				saveStatus: state.saveStatus,
+			}),
+		),
+	}
+}
+
+/** Whether a failed call is the server refusing a draft moved on elsewhere. */
+export function isDraftConflict(error: unknown): boolean {
+	return (
+		apiErrorStatus(error) === HTTP_CONFLICT &&
+		apiErrorMessage(error).includes(DRAFT_CONFLICT_KEY)
+	)
+}
+
+/** A failure worth trying again on its own: the network or the server. */
+function isTransient(error: unknown): boolean {
+	const status = apiErrorStatus(error)
+	return status === NETWORK_ERROR_STATUS || status >= SERVER_ERROR_STATUS
+}
+
+export function retryDelay(failures: number): number {
+	return Math.min(RETRY_BASE_DELAY_MS * 2 ** (failures - 1), RETRY_MAX_DELAY_MS)
+}
+
+function createSaver(deps: SessionDeps, state: SessionState) {
+	const { editor, api, templateId, onError } = deps
+	let timer: ReturnType<typeof setTimeout> | null = null
+	let inFlight: Promise<boolean> | null = null
+	let failures = 0
+	let isDisposed = false
+	const cancel = (): void => {
+		if (timer) clearTimeout(timer)
+		timer = null
+	}
+	function schedule(delay = AUTOSAVE_DELAY_MS): void {
+		cancel()
+		if (isDisposed) return
+		timer = setTimeout(() => void save(), delay)
+	}
+	function markConflict(): void {
+		cancel()
+		if (state.saveStatus !== 'conflict') onError(DRAFT_CONFLICT)
+		state.saveStatus = 'conflict'
+	}
+	function onFailure(error: unknown): void {
+		if (isDraftConflict(error)) return markConflict()
+		failures += 1
+		state.saveStatus = 'error'
+		if (failures === 1) onError(error)
+		if (isTransient(error)) schedule(retryDelay(failures))
+	}
+	async function write(): Promise<boolean> {
+		const revision = editor.revision
+		state.saveStatus = 'saving'
+		try {
+			const response = await api.saveContent(templateId, {
+				content: deepClone(editor.content),
+				variables: deepClone(editor.variables),
+				revision: state.revision,
+			})
+			state.revision = response.revision
+			state.changes = response.changes
+			state.serverDetected = response.detectedVariables
+			editor.markSaved(revision)
+			failures = 0
+			state.saveStatus = 'idle'
+			return true
+		} catch (error) {
+			onFailure(error)
+			return false
+		}
+	}
+	async function run(): Promise<boolean> {
+		inFlight = write()
+		const isSaved = await inFlight
+		inFlight = null
+		if (isSaved && editor.dirty > 0) schedule()
+		return isSaved
+	}
+	async function save(): Promise<boolean> {
+		cancel()
+		if (inFlight) await inFlight
+		if (state.saveStatus === 'conflict') return false
+		if (editor.dirty === 0) return state.saveStatus !== 'error'
+		return run()
+	}
+	/** Writes this editor's content over the draft saved elsewhere. */
+	async function overwrite(): Promise<boolean> {
+		cancel()
+		if (inFlight) await inFlight
+		const latest = await api.changes(templateId).catch(() => null)
+		if (!latest) return false
+		state.revision = latest.revision
+		return run()
+	}
+	/** The page is going away: hands the pending draft to a request that outlives it. */
+	function flush(): void {
+		if (editor.dirty === 0 || state.saveStatus === 'conflict') return
+		cancel()
+		const draft = {
+			content: deepClone(editor.content),
+			variables: deepClone(editor.variables),
+		}
+		const keepalive = JSON.stringify(draft).length < KEEPALIVE_MAX_LENGTH
+		void api
+			.saveContent(templateId, {
+				...draft,
+				revision: state.revision,
+				keepalive,
+			})
+			.catch(() => undefined)
+	}
+	watch(
+		() => editor.revision,
+		() => (editor.dirty > 0 ? schedule() : undefined),
+	)
+	onBeforeUnmount(() => {
+		if (editor.dirty > 0) void save()
+		isDisposed = true
+		cancel()
+	})
+	return {
+		save,
+		cancel,
+		overwrite,
+		flush,
+		markConflict,
+		settle: () => inFlight ?? Promise.resolve(true),
+	}
+}
+
+function createRecordActions(
+	{ api, templateId }: SessionDeps,
+	state: SessionState,
+) {
+	return {
+		async saveDetails(patch: Partial<TemplateDetails>): Promise<void> {
+			const details: TemplateDetails = {
+				name: state.template.name,
+				slug: state.template.slug,
+				category: state.template.category || null,
+				...patch,
+			}
+			await api.saveTemplateDetails(templateId, details)
+			state.template = { ...state.template, ...details }
+		},
+		async saveTestData(): Promise<boolean> {
+			const data = parseTestData(state.testDataSource)
+			if (!data) return false
+			await api.saveTestData(templateId, data)
+			state.savedTestDataSource = state.testDataSource
+			return true
+		},
+		resetTestData(): void {
+			state.testDataSource = state.savedTestDataSource
+		},
+		async loadPerformance(): Promise<void> {
+			state.performance = await api.performance(templateId).catch(() => null)
+		},
+	}
+}
+
+/**
+ * The editor's link to the server: the template record, autosave of the
+ * draft (content and variable declarations), test data and performance.
+ * Publishing, discarding, restoring and the dialogs live in
+ * `useEditorActions`.
+ */
+export function useEditorSession(deps: SessionDeps) {
+	const state = createState(deps.loaded)
+	return reactive({
+		state,
+		reportError: deps.onError,
+		...createViews(state, deps.editor),
+		...createSaver(deps, state),
+		...createRecordActions(deps, state),
+	})
+}
+
+export type EditorSession = ReturnType<typeof useEditorSession>

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

@@ -0,0 +1,81 @@
+import { onBeforeUnmount, onMounted } from 'vue'
+import type { EditorActions } from './useEditorActions'
+import type { EditorSession } from './useEditorSession'
+import type { EditorState } from './useTemplateEditor'
+import type { EditorShortcut } from '../utils/shortcuts'
+import { isTypingTarget, matchShortcut } from '../utils/shortcuts'
+import { TEMPLATES_PATH } from '../utils/pages'
+
+const OPEN_DIALOG_SELECTOR =
+	'[role="dialog"][data-state="open"], [role="alertdialog"][data-state="open"]'
+
+type ShortcutHandlers = Record<EditorShortcut, () => void>
+
+function handlersFor(
+	editor: EditorState,
+	actions: EditorActions,
+): ShortcutHandlers {
+	const withSelection = (run: (id: string) => void) => () => {
+		if (editor.selectedId) run(editor.selectedId)
+	}
+	return {
+		save: () => void actions.save(),
+		publish: () => void actions.publish(),
+		test: actions.test,
+		search: editor.requestSearch,
+		delete: withSelection(editor.removeBlockById),
+		duplicate: withSelection(editor.duplicateBlockById),
+		undo: editor.undo,
+		redo: editor.redo,
+		escape: () =>
+			editor.selectedId
+				? editor.select(null)
+				: void navigateDms(TEMPLATES_PATH),
+	}
+}
+
+/**
+ * The editor's keyboard (ML-08): ⌘S, ⌘↵, T, /, ⌫, ⌘D, ⌘Z, Esc. Nothing fires
+ * while a dialog is open, and single keys leave text fields alone.
+ */
+export function useEditorShortcuts(
+	editor: EditorState,
+	actions: EditorActions,
+): void {
+	const handlers = handlersFor(editor, actions)
+	function onKeydown(event: KeyboardEvent): void {
+		if (event.defaultPrevented || document.querySelector(OPEN_DIALOG_SELECTOR))
+			return
+		const shortcut = matchShortcut(event, isTypingTarget(event.target))
+		if (!shortcut) return
+		event.preventDefault()
+		handlers[shortcut]()
+	}
+	onMounted(() => window.addEventListener('keydown', onKeydown))
+	onBeforeUnmount(() => window.removeEventListener('keydown', onKeydown))
+}
+
+/**
+ * Leaving the editor never loses work silently. A draft waiting for its
+ * autosave is written on the way out (on unmount, or by a request outliving
+ * a closed tab, after the browser's own prompt); a save that failed, a
+ * conflict or unsaved test data ask the DMS "Discard unsaved changes?" first,
+ * whether the user follows a link, goes back or reloads.
+ */
+export function useEditorLeaveGuard(session: EditorSession): void {
+	useUnsavedChanges({ dirty: () => session.hasUnsavedWork })
+	function onBeforeUnload(event: BeforeUnloadEvent): void {
+		if (!session.isSaving) return
+		event.preventDefault()
+		event.returnValue = ''
+	}
+	const onPageHide = (): void => session.flush()
+	onMounted(() => {
+		window.addEventListener('beforeunload', onBeforeUnload)
+		window.addEventListener('pagehide', onPageHide)
+	})
+	onBeforeUnmount(() => {
+		window.removeEventListener('beforeunload', onBeforeUnload)
+		window.removeEventListener('pagehide', onPageHide)
+	})
+}

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

@@ -0,0 +1,17 @@
+import type { StarterSummary, TemplateCategory } from '../types/mailing'
+import { localizeCategories, type OptionalTranslate } from '../utils/categories'
+import { localizeStarters } from '../utils/starters'
+
+/**
+ * What the module ships by default (starters, the first categories) named in
+ * the interface's language, without touching what is stored.
+ */
+export function useLocalizedDefaults() {
+	const { t, te } = useI18n()
+	const translate: OptionalTranslate = (key) => (te(key) ? t(key) : undefined)
+	return {
+		categories: (list: TemplateCategory[]) =>
+			localizeCategories(list, translate),
+		starters: (list: StarterSummary[]) => localizeStarters(list, translate),
+	}
+}

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

@@ -1,15 +1,25 @@
 import type {
-	AttentionItem,
 	FunnelStep,
 	PreviewResponse,
+	PreviewVersion,
 	ProviderInfo,
+	RetentionPreview,
 	SendDetailResponse,
+	SendHtmlResponse,
+	StarterSummary,
+	SuppressionSummary,
+	TemplateChange,
 	TemplateContent,
 	TemplateCategory,
 	TemplateContentResponse,
+	TemplatePerformance,
 	TemplateRow,
+	TemplateStats,
+	TemplateVersionSummary,
 	VariableDefinition,
 } from '../types/mailing'
+import type { SetupFacts } from '../utils/overview-setup'
+import type { WebhookStatus, WebhookTestResult } from '../utils/webhook-status'
 
 const BASE = '/api/mailing'
 
@@ -27,6 +37,8 @@ export function mailingPath(...segments: string[]): string {
 export interface PreviewInput {
 	/** Absent lets the server pick the tenant fallback locale. */
 	locale?: string
+	/** Which content to render when `content` is absent; the draft by default. */
+	version?: PreviewVersion
 	content?: TemplateContent
 	data?: Record<string, unknown>
 }
@@ -48,28 +60,75 @@ export interface SendResult {
 	error?: string
 }
 
-export interface AttentionResponse {
-	items: AttentionItem[]
-}
-
 export interface FunnelResponse {
 	steps: FunnelStep[]
 }
 
 export interface SavedResponse {
 	saved: boolean
+	/** The draft revision the next save or publish carries. */
+	revision: number
 	detectedVariables: string[]
+	changes: TemplateChange[]
+}
+
+export interface ChangesResponse {
+	version: number
+	revision: number
+	changes: TemplateChange[]
+}
+
+/**
+ * A draft save: the content and the variable declarations, which follow the
+ * draft. `revision` is the one the editor last saw: the server refuses the
+ * save (409) when the draft moved on since. `keepalive` lets the request
+ * outlive the page being closed.
+ */
+export interface SaveContentInput {
+	content: TemplateContent
+	variables?: VariableDefinition[]
+	revision?: number
+	keepalive?: boolean
+}
+
+/** A version copied into the draft; the review then publishes it. */
+export interface RestoreVersionResponse {
+	/** The draft revision the editor carries on with. */
+	revision: number
+}
+
+export interface PublishResponse {
+	status: string
+	version: number
+	changes: TemplateChange[]
+}
+
+export interface VersionsResponse {
+	versions: TemplateVersionSummary[]
+}
+
+export interface StartersResponse {
+	starters: StarterSummary[]
+}
+
+export interface TemplateOverviewResponse {
+	items: TemplateStats[]
+}
+
+export interface CategoryUsageResponse {
+	counts: Record<string, number>
 }
 
 /**
  * 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.
+ * one nulls it in the database. `null` clears the category on every data-api
+ * version, including those that leave an absent key unchanged.
  */
 export interface TemplateDetails {
 	name: string
 	slug: string
-	category?: string
+	category: string | null
 }
 
 export interface CategoriesResponse {
@@ -87,6 +146,8 @@ export interface CreateTemplateInput {
 	category?: string
 	/** Absent starts blank; otherwise the template to copy. */
 	sourceTemplateId?: string
+	/** A starter template to start from, when no template is copied. */
+	starterId?: string
 }
 
 export interface StatusResponse {
@@ -99,6 +160,8 @@ export interface DuplicateResponse {
 
 export interface VariablesResponse {
 	variables: VariableDefinition[]
+	/** The draft revision the declarations were written at. */
+	revision: number
 }
 
 export interface TestDataResponse {
@@ -107,14 +170,20 @@ export interface TestDataResponse {
 
 export interface TestSendResponse {
 	results: SendResult[]
+	/**
+	 * The sender's own address is on the suppression list: the test went out
+	 * anyway, with this entry to warn about.
+	 */
+	ownAddressSuppressed?: SuppressionSummary
 }
 
 export interface HtmlResponse {
 	html: string
 }
 
-export interface MailingSettings extends Record<string, unknown> {
-	blockOnMissingVariables?: boolean
+export interface StarterPreviewResponse {
+	html: string
+	locale: string
 }
 
 /**
@@ -128,12 +197,11 @@ export function useMailingApi() {
 
 	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 }),
+		setupFacts: () => $authFetch<SetupFacts>(mailingPath('metrics', 'setup')),
+		webhookStatus: () =>
+			$authFetch<WebhookStatus>(mailingPath('settings', 'webhook-status')),
+		webhookTest: () =>
+			post<WebhookTestResult>(mailingPath('settings', 'webhook-test'), {}),
 		templateContent: (id: string) =>
 			$authFetch<TemplateContentResponse>(
 				mailingPath('templates', id, 'content'),
@@ -153,24 +221,65 @@ export function useMailingApi() {
 			),
 		createTemplate: (input: CreateTemplateInput) =>
 			post<string[]>(mailingPath('tables', 'templates', 'new'), input),
-		saveContent: (id: string, content: TemplateContent) =>
-			post<SavedResponse>(mailingPath('templates', id, 'content'), {
-				content,
+		saveContent: (id: string, input: SaveContentInput) =>
+			$authFetch<SavedResponse>(mailingPath('templates', id, 'content'), {
+				method: 'POST',
+				body: {
+					content: input.content,
+					variables: input.variables,
+					revision: input.revision,
+				},
+				keepalive: input.keepalive,
 			}),
-		publish: (id: string) =>
-			post<StatusResponse>(mailingPath('templates', id, 'publish'), {}),
+		changes: (id: string) =>
+			$authFetch<ChangesResponse>(mailingPath('templates', id, 'changes')),
+		versions: (id: string) =>
+			$authFetch<VersionsResponse>(mailingPath('templates', id, 'versions')),
+		restoreVersion: (id: string, version: number, revision?: number) =>
+			post<RestoreVersionResponse>(
+				mailingPath('templates', id, 'versions', String(version), 'restore'),
+				{ revision },
+			),
+		performance: (id: string) =>
+			$authFetch<TemplatePerformance>(
+				mailingPath('templates', id, 'performance'),
+			),
+		templatesOverview: () =>
+			$authFetch<TemplateOverviewResponse>(
+				mailingPath('templates', 'overview'),
+			),
+		starters: () =>
+			$authFetch<StartersResponse>(mailingPath('templates', 'starters')),
+		starterPreview: (starterId: string, locale?: string) =>
+			$authFetch<StarterPreviewResponse>(
+				mailingPath('templates', 'starters', starterId, 'preview'),
+				{ query: locale ? { locale } : {} },
+			),
+		publish: (id: string, revision?: number) =>
+			post<PublishResponse>(mailingPath('templates', id, 'publish'), {
+				revision,
+			}),
+		discard: (id: string) =>
+			post<unknown>(mailingPath('templates', id, 'discard'), {}),
 		unpublish: (id: string) =>
 			post<StatusResponse>(mailingPath('templates', id, 'unpublish'), {}),
 		archive: (id: string) =>
 			post<StatusResponse>(mailingPath('templates', id, 'archive'), {}),
+		restore: (id: string) =>
+			post<StatusResponse>(mailingPath('templates', id, 'restore'), {}),
 		duplicate: (id: string, slug: string, name: string) =>
 			post<DuplicateResponse>(mailingPath('templates', id, 'duplicate'), {
 				slug,
 				name,
 			}),
-		saveVariables: (id: string, variables: VariableDefinition[]) =>
+		saveVariables: (
+			id: string,
+			variables: VariableDefinition[],
+			revision?: number,
+		) =>
 			post<VariablesResponse>(mailingPath('templates', id, 'variables'), {
 				variables,
+				revision,
 			}),
 		saveTestData: (id: string, data: Record<string, unknown>) =>
 			post<TestDataResponse>(mailingPath('templates', id, 'test-data'), {
@@ -185,12 +294,18 @@ export function useMailingApi() {
 		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),
+			$authFetch<SendHtmlResponse>(mailingPath('sends', id, 'html')),
+		replay: (id: string, to?: string) =>
+			post<SendResult>(mailingPath('sends', id, 'replay'), to ? { to } : {}),
+		retentionPreview: (days: number) =>
+			$authFetch<RetentionPreview>(
+				mailingPath('settings', 'retention-preview'),
+				{ query: { days: String(days) } },
+			),
+		categoryUsage: () =>
+			$authFetch<CategoryUsageResponse>(
+				mailingPath('settings', 'category-usage'),
+			),
 	}
 }
 

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

@@ -0,0 +1,13 @@
+import type { Ref } from 'vue'
+
+const HIDES_PERIOD_KEY = 'mailing-setup-hides-period:'
+
+/**
+ * Whether the page header should hold its period selector back for `scope`:
+ * the setup card stands in for the dashboard, so there is no figure for a
+ * period to filter. Shared between the Overview gate, which sets it, and the
+ * page header, which reads it.
+ */
+export function useSetupHidesPeriod(scope: string | undefined): Ref<boolean> {
+	return useDmsState<boolean>(`${HIDES_PERIOD_KEY}${scope ?? ''}`, () => false)
+}