@antelopejs/dms-mailing 0.2.2

package/frontend-vue/tests/paths.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import type { Block } from '../app/types/mailing'
+import {
+	collectContentPaths,
+	collectPaths,
+	pathsInBlocks,
+} from '../app/utils/paths'
+
+const blocks: Block[] = [
+	{
+		id: 'h1',
+		type: 'heading',
+		text: 'Hi {{customer.firstName}}',
+		align: 'left',
+		size: 23,
+		visibleIf: null,
+	},
+	{
+		id: 'if1',
+		type: 'if',
+		condition: { path: 'order.hasGift', operator: 'truthy', value: '' },
+		children: [
+			{
+				id: 'l1',
+				type: 'list',
+				source: 'order.lines',
+				labelPath: 'label',
+				valuePath: 'total',
+				visibleIf: null,
+			},
+		],
+		elseChildren: null,
+		visibleIf: { path: 'contact.isPro', operator: 'truthy', value: '' },
+	},
+]
+
+describe('paths', () => {
+	it('collects every variable path used by the content', () => {
+		expect(pathsInBlocks(blocks).sort()).toEqual([
+			'contact.isPro',
+			'customer.firstName',
+			'order.hasGift',
+			'order.lines',
+		])
+	})
+	it('merges declared paths, used paths and the current one, deduplicated', () => {
+		expect(
+			collectPaths(['customer.firstName', 'invoice.ref'], blocks, 'ad.hoc'),
+		).toEqual([
+			'ad.hoc',
+			'contact.isPro',
+			'customer.firstName',
+			'invoice.ref',
+			'order.hasGift',
+			'order.lines',
+		])
+	})
+})
+
+const localeContent = (subject: string, blocks: Block[]) => ({
+	subject,
+	preheader: '',
+	blocks,
+})
+
+describe('collectContentPaths', () => {
+	// The variables panel marks a declared path "unused" when nothing references
+	// it. Its detected list comes from the server and only refreshes on save, so
+	// a path wired into a condition read as unused until then. This is the live
+	// equivalent, and it has to see every source the backend sees.
+	it('sees a path used only by a display condition', () => {
+		const content = {
+			locales: {
+				en: localeContent('Hello', [
+					{
+						id: 'b',
+						type: 'button',
+						text: 'Go',
+						href: '#',
+						align: 'left',
+						visibleIf: { path: 'order.mix', operator: 'truthy', value: '' },
+					},
+				] as Block[]),
+			},
+		}
+		expect(collectContentPaths(content)).toContain('order.mix')
+	})
+
+	it('unions every locale, so a path used in one is not unused in another', () => {
+		const content = {
+			locales: {
+				en: localeContent('Hi {{customer.firstName}}', []),
+				fr: localeContent('Bonjour {{contact.civility}}', []),
+			},
+		}
+		expect(collectContentPaths(content)).toEqual([
+			'contact.civility',
+			'customer.firstName',
+		])
+	})
+
+	it('reads the subject and the preheader, not just the blocks', () => {
+		const content = {
+			locales: {
+				en: {
+					subject: '{{a.one}}',
+					preheader: '{{a.two}}',
+					blocks: [] as Block[],
+				},
+			},
+		}
+		expect(collectContentPaths(content)).toEqual(['a.one', 'a.two'])
+	})
+
+	// The backend drops these before answering, so the panel must too or they
+	// would show up as undeclared variables nobody can declare.
+	it('drops the system paths the runtime fills in', () => {
+		const content = {
+			locales: {
+				en: localeContent(
+					'{{unsubscribeUrl}} {{preferencesUrl}} {{real.one}}',
+					[],
+				),
+			},
+		}
+		expect(collectContentPaths(content)).toEqual(['real.one'])
+	})
+})

package/frontend-vue/tests/period.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+import { periodQuery } from '../app/utils/period'
+
+describe('periodQuery', () => {
+	it('serialises a period state into the query the backend expects', () => {
+		const from = new Date('2026-08-10T00:00:00.000Z')
+		const to = new Date('2026-09-09T00:00:00.000Z')
+		expect(periodQuery({ range: { from, to }, compareRange: null })).toEqual({
+			from: from.toISOString(),
+			to: to.toISOString(),
+		})
+	})
+})

package/frontend-vue/tests/smoke.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest'
+import { SEND_STATUSES } from '../app/types/mailing'
+
+describe('types', () => {
+	it('exposes the send statuses', () => {
+		expect(SEND_STATUSES).toContain('bounced')
+	})
+})

package/frontend-vue/tests/template-editor.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { createEditorState } from '../app/composables/useTemplateEditor'
+import type { TemplateContent } from '../app/types/mailing'
+
+const CONTENT: TemplateContent = {
+	locales: {
+		en: {
+			subject: 'S',
+			preheader: '',
+			blocks: [
+				{
+					id: 'h1',
+					type: 'heading',
+					text: 'Hi',
+					align: 'left',
+					size: 23,
+					visibleIf: null,
+				},
+			],
+		},
+	},
+}
+
+describe('editor state', () => {
+	it('starts clean on the requested locale and tracks dirtiness', () => {
+		const state = createEditorState(CONTENT, 'en', ['en', 'fr'])
+		expect(state.locale).toBe('en')
+		expect(state.dirty).toBe(0)
+		state.updateBlock('h1', { text: 'Hello' })
+		expect(state.dirty).toBe(1)
+		expect(state.current?.blocks[0]).toMatchObject({ text: 'Hello' })
+	})
+	it('selects and deselects blocks and the subject', () => {
+		const state = createEditorState(CONTENT, 'en', ['en'])
+		state.select('h1')
+		expect(state.selected?.id).toBe('h1')
+		state.selectSubject()
+		expect(state.selected).toBeNull()
+		expect(state.subjectSelected).toBe(true)
+	})
+	it('reports missing locales and creates one from a source locale', () => {
+		const state = createEditorState(CONTENT, 'fr', ['en', 'fr'])
+		expect(state.current).toBeNull()
+		expect(state.missingLocales).toEqual(['fr'])
+		state.createLocale('fr', 'en')
+		expect(state.current?.subject).toBe('S')
+		expect(state.current?.blocks[0]?.id).not.toBe('h1')
+	})
+	it('removes a block by id and marks the state dirty', () => {
+		const state = createEditorState(CONTENT, 'en', ['en'])
+		state.removeBlockById('h1')
+		expect(state.current?.blocks).toHaveLength(0)
+		expect(state.dirty).toBe(1)
+	})
+	it('adds blocks at the end of a list, inside branches too, and resets on save', () => {
+		const state = createEditorState(CONTENT, 'en', ['en'])
+		const branch = state.addBlock('if')
+		state.addBlock('paragraph', { parentId: branch.id, branch: 'children' })
+		expect(state.current?.blocks.at(-1)?.type).toBe('if')
+		const found = state.findBlock(branch.id)
+		expect(found?.type === 'if' && found.children).toHaveLength(1)
+		state.markSaved()
+		expect(state.dirty).toBe(0)
+	})
+})

package/frontend-vue/tests/test-data.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { parseTestData } from '../app/utils/testData'
+
+describe('parseTestData', () => {
+	it('returns the object for a valid JSON object', () => {
+		expect(parseTestData('{"order":{"total":42}}')).toEqual({
+			order: { total: 42 },
+		})
+	})
+	it('returns null for invalid JSON and for non-objects', () => {
+		expect(parseTestData('{')).toBeNull()
+		expect(parseTestData('[1,2]')).toBeNull()
+		expect(parseTestData('"text"')).toBeNull()
+	})
+})

package/frontend-vue/tests/timeline.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { buildTimeline } from '../app/utils/timeline'
+
+describe('buildTimeline', () => {
+	it('orders events by time and marks problems', () => {
+		const items = buildTimeline([
+			{
+				_id: '2',
+				sendId: 's',
+				type: 'bounced',
+				at: '2026-09-09T10:01:00.000Z',
+				json_details: '{"reason":"550"}',
+			},
+			{
+				_id: '1',
+				sendId: 's',
+				type: 'sent',
+				at: '2026-09-09T10:00:00.000Z',
+				json_details: '{}',
+			},
+		])
+		expect(items.map((item) => item.type)).toEqual(['sent', 'bounced'])
+		expect(items[1]).toMatchObject({
+			tone: 'error',
+			description: '550',
+			icon: 'i-ph-warning',
+		})
+	})
+})

package/frontend-vue/tests/tokens.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { splitTokens } from '../app/utils/tokens'
+
+describe('splitTokens', () => {
+	it('splits text into literal and token parts', () => {
+		expect(splitTokens('Hi {{ customer.firstName }}!')).toEqual([
+			{ kind: 'text', value: 'Hi ' },
+			{ kind: 'token', value: 'customer.firstName' },
+			{ kind: 'text', value: '!' },
+		])
+	})
+})

package/frontend-vue/tests/variables.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { mergeVariables } from '../app/utils/variables'
+import type { VariableDefinition } from '../app/types/mailing'
+
+const DECLARED: VariableDefinition[] = [
+	{ path: 'order.total', type: 'money', required: true },
+	{ path: 'legacy.path', type: 'string', required: false },
+]
+
+describe('mergeVariables', () => {
+	it('enriches a detected path with its declaration', () => {
+		const merged = mergeVariables(['order.total'], DECLARED)
+		expect(merged[0]).toEqual({
+			path: 'order.total',
+			type: 'money',
+			required: true,
+			usage: 'declared',
+		})
+	})
+
+	it('gives a detected path with no declaration a neutral default', () => {
+		const merged = mergeVariables(['customer.firstName'], [])
+		expect(merged[0]).toEqual({
+			path: 'customer.firstName',
+			type: 'string',
+			required: false,
+			usage: 'detected',
+		})
+	})
+
+	it('lists a declared path the content no longer uses as unused, last', () => {
+		const merged = mergeVariables(['order.total'], DECLARED)
+		expect(merged.map((entry) => entry.path)).toEqual([
+			'order.total',
+			'legacy.path',
+		])
+		expect(merged[1]?.usage).toBe('unused')
+	})
+
+	it('answers the declarations alone when nothing is detected', () => {
+		expect(mergeVariables([], DECLARED).map((entry) => entry.usage)).toEqual([
+			'unused',
+			'unused',
+		])
+	})
+})

package/frontend-vue/vitest.config.ts

@@ -0,0 +1,10 @@
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	plugins: [vue()],
+	test: {
+		environment: 'jsdom',
+		include: ['tests/**/*.test.ts'],
+	},
+})

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@antelopejs/dms-mailing",
+  "version": "0.2.2",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AntelopeJS/dms-mailing.git",
+    "directory": "packages/dms-mailing"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "frontend-vue",
+    "src"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
+    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
+    "@antelopejs/interface-core": ">=0.0.13 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-database": "0.1.7",
+    "@antelopejs/interface-database-decorators": ">=0.1.6 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.1.0 <1.0.0",
+    "@antelopejs/interface-dms-mailing": ">=0.2.0 <1.0.0",
+    "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
+    "node-cron": "^4.2.1",
+    "zod": "~3.24.2"
+  },
+  "devDependencies": {
+    "@antelopejs/core": ">=1.8.0 <2",
+    "@antelopejs/dms": ">=0.3.5 <1.0.0",
+    "@antelopejs/dms-frontend": ">=0.2.0 <1.0.0",
+    "@antelopejs/tooling-configs": ">=0.0.6 <1.0.0",
+    "@types/chai": "^4.3.20",
+    "@types/mocha": "^10",
+    "@types/node": "^24.0.0",
+    "@types/semver": "^7.7.1",
+    "axios": "^1.7.9",
+    "chai": "^4.5.0",
+    "knip": "^6.34.0",
+    "mongodb-memory-server-core": "^11.0.1",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "release-it": "^19.2.4",
+    "release-it-changelogen": "^0.1.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3"
+  },
+  "optionalDependencies": {
+    "@antelopejs/interface-dms-automation": ">=0.0.1 <1.0.0"
+  },
+  "antelopeJs": {
+    "baseUrl": "dist",
+    "implements": [
+      "@antelopejs/interface-dms-mailing"
+    ],
+    "test": "src/test/antelope.test.ts"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "dev": "ajs project run -w -p playground",
+    "dev:frontend": "cd playground && pnpm frontend:dev",
+    "frontend:dev": "cd playground && pnpm frontend:dev",
+    "lint": "oxlint && oxfmt --check . && cd frontend-vue && pnpm lint",
+    "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt . && cd frontend-vue && pnpm lint:fix",
+    "format": "oxfmt . && cd frontend-vue && pnpm format",
+    "typecheck": "tsc -p tsconfig.json",
+    "knip": "knip --dependencies",
+    "knip:all": "knip",
+    "release": "pnpm --filter @antelopejs/interface-dms-mailing build && pnpm --dir frontend-vue install --frozen-lockfile && release-it",
+    "test": "pnpm run test:backend && pnpm run test:layer",
+    "test:frontend": "node scripts/check-frontend.mjs",
+    "test:backend": "pnpm run build && ajs module test .",
+    "test:layer": "cd frontend-vue && pnpm test",
+    "test:unit": "pnpm run build && DMS_MAILING_TEST_DIR=dist/test/unit ajs module test .",
+    "test:integration": "pnpm run build && DMS_MAILING_TEST_DIR=dist/test/integration ajs module test ."
+  }
+}

package/src/antelope-modules.ts

@@ -0,0 +1,48 @@
+/**
+ * The package modules the playground and the test stack both run.
+ *
+ * Declared once so a version bump lands in a single place: the two configs
+ * previously repeated these, and an upgrade that missed one failed the whole
+ * test run with `Incompatible interface package resolution` — the harness
+ * resolves its own module set, so a stale pin there is not caught by the
+ * module's own `package.json`.
+ *
+ * Only the *source* is shared. Each config supplies its own per-module
+ * `config`, since the playground talks to a real Mongo and Ethereal while the
+ * tests drive a memory replica set and an SMTP fixture.
+ *
+ * Modules only one stack needs — the playground's `dms-automation`, the local
+ * checkouts — stay in their own config.
+ */
+export const SHARED_MODULE_SOURCES = {
+  dms: {
+    type: "package",
+    package: "@antelopejs/dms",
+    version: ">=0.0.1 <1.0.0",
+  },
+  mongodb: {
+    type: "package",
+    package: "@antelopejs/mongodb",
+    version: "^1.3.0",
+  },
+  "auth-jwt": {
+    type: "package",
+    package: "@antelopejs/auth-jwt",
+    version: "^1.0.3",
+  },
+  api: {
+    type: "package",
+    package: "@antelopejs/api",
+    version: "1.2.5",
+  },
+  "file-storage-local": {
+    type: "package",
+    package: "@antelopejs/file-storage-local",
+    version: "^0.1.4",
+  },
+  nodemailer: {
+    type: "package",
+    package: "@antelopejs/nodemailer",
+    version: "^0.0.4",
+  },
+} as const;

package/src/automation/email-event-trigger.ts

@@ -0,0 +1,112 @@
+import { Logging } from "@antelopejs/interface-core/logging";
+import type {
+  JsonSchema,
+  TriggerType,
+} from "@antelopejs/interface-dms-automation";
+import { SEND_STATUSES, type SendEventType } from "../types";
+
+export interface EmailEventPayload {
+  tenantId: string;
+  sendId: string;
+  templateSlug: string;
+  type: SendEventType;
+  recipientEmail: string;
+}
+
+export interface EmailEventTriggerConfig {
+  types?: SendEventType[];
+}
+
+interface EmailEventSubscription {
+  types: SendEventType[];
+  emit: (payload: EmailEventPayload) => void;
+}
+
+export const EMAIL_EVENT_TRIGGER_ID = "mailing.email-event";
+
+const CONFIG_SCHEMA: JsonSchema = {
+  type: "object",
+  properties: {
+    types: {
+      type: "array",
+      items: { type: "string", enum: SEND_STATUSES },
+      description:
+        "Event types the trigger fires on. Leave empty to fire on every event.",
+    },
+  },
+};
+
+const OUTPUT_SCHEMA: JsonSchema = {
+  type: "object",
+  properties: {
+    tenantId: { type: "string" },
+    sendId: { type: "string" },
+    templateSlug: { type: "string" },
+    type: { type: "string", enum: SEND_STATUSES },
+    recipientEmail: { type: "string" },
+  },
+};
+
+const FIRST_SUBSCRIPTION_INDEX = 1;
+
+const SUBSCRIPTION_FAILURE_PREFIX = "[dms-mailing] E-mail event subscription";
+
+const subscriptions = new Map<string, EmailEventSubscription>();
+
+let nextSubscriptionIndex = FIRST_SUBSCRIPTION_INDEX;
+
+const accepts = (
+  subscription: EmailEventSubscription,
+  payload: EmailEventPayload,
+): boolean =>
+  subscription.types.length === 0 || subscription.types.includes(payload.type);
+
+function deliver(
+  handle: string,
+  subscription: EmailEventSubscription,
+  payload: EmailEventPayload,
+): void {
+  try {
+    subscription.emit(payload);
+  } catch (error) {
+    Logging.Warn(
+      `${SUBSCRIPTION_FAILURE_PREFIX} "${handle}" failed on a "${payload.type}" event:`,
+      error,
+    );
+  }
+}
+
+export function emitEmailEvent(payload: EmailEventPayload): void {
+  for (const [handle, subscription] of subscriptions) {
+    if (accepts(subscription, payload)) deliver(handle, subscription, payload);
+  }
+}
+
+/** Drops every active subscription so a reloaded module starts from nothing. */
+export function clearEmailEventSubscriptions(): void {
+  subscriptions.clear();
+}
+
+export const emailEventTrigger: TriggerType<
+  EmailEventTriggerConfig,
+  EmailEventPayload
+> = {
+  id: EMAIL_EVENT_TRIGGER_ID,
+  name: "E-mail event",
+  description:
+    "Fires when a provider reports a delivery event on a mailing send",
+  icon: "i-ph-bell-ringing",
+  cluster: "replicated",
+  configSchema: CONFIG_SCHEMA,
+  outputSchema: OUTPUT_SCHEMA,
+  activate(config, emit) {
+    const handle = `${EMAIL_EVENT_TRIGGER_ID}:${nextSubscriptionIndex}`;
+    nextSubscriptionIndex += 1;
+    subscriptions.set(handle, { types: config?.types ?? [], emit });
+    return Promise.resolve(handle);
+  },
+  deactivate(handle) {
+    subscriptions.delete(String(handle));
+    return Promise.resolve();
+  },
+};

package/src/automation/index.ts

@@ -0,0 +1,33 @@
+import {
+  RegisterActionType,
+  RegisterTriggerType,
+  UnregisterActionType,
+  UnregisterTriggerType,
+} from "@antelopejs/interface-dms-automation";
+import {
+  clearEmailEventSubscriptions,
+  emailEventTrigger,
+} from "./email-event-trigger";
+import { sendTemplateAction } from "./send-template-action";
+
+export * from "./email-event-trigger";
+export * from "./send-template-action";
+
+const TRIGGERS = [emailEventTrigger];
+const ACTIONS = [sendTemplateAction];
+
+/**
+ * Declares the mailing automation node types. The registrations are inert
+ * no-ops when no module implements `@antelopejs/interface-dms-automation`,
+ * so the module works with or without the automation module in the project.
+ */
+export function registerAutomationNodes(): void {
+  for (const trigger of TRIGGERS) RegisterTriggerType(trigger);
+  for (const action of ACTIONS) RegisterActionType(action);
+}
+
+export function unregisterAutomationNodes(): void {
+  for (const trigger of TRIGGERS) UnregisterTriggerType(trigger.id);
+  for (const action of ACTIONS) UnregisterActionType(action.id);
+  clearEmailEventSubscriptions();
+}