@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/frontend-vue/tests/webhook-status.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import {
+	isRefusalLatest,
+	refusalKey,
+	type WebhookReceipt,
+	type WebhookStatus,
+	webhookStatusLines,
+	type WebhookTestResult,
+	webhookTestMessage,
+} from '../app/utils/webhook-status'
+
+const EARLY = '2026-10-01T10:00:00.000Z'
+const LATE = '2026-10-01T11:00:00.000Z'
+const URL = 'https://api.example.com/api/mailing/events/smtp/default'
+
+const received = (overrides: Partial<WebhookReceipt> = {}): WebhookReceipt => ({
+	at: EARLY,
+	provider: 'postmark',
+	type: 'delivered',
+	isMatched: true,
+	isTest: false,
+	...overrides,
+})
+
+const tested = (overrides: Partial<WebhookTestResult>): WebhookTestResult => ({
+	isReceived: false,
+	url: URL,
+	durationMs: 42,
+	status: { lastReceived: null, lastRefused: null },
+	...overrides,
+})
+
+describe('webhookStatusLines', () => {
+	it('says nothing came in yet', () => {
+		const [line] = webhookStatusLines({ lastReceived: null, lastRefused: null })
+		expect(line).toMatchObject({
+			id: 'received',
+			tone: 'neutral',
+			labelKey: 'dms_mailing.settings.webhook_status.never_received',
+			at: null,
+		})
+	})
+
+	it('tells a matched, an unmatched and a test event apart', () => {
+		const keyOf = (receipt: WebhookReceipt) =>
+			webhookStatusLines({ lastReceived: receipt, lastRefused: null })[0]
+				?.labelKey
+		expect(keyOf(received())).toBe(
+			'dms_mailing.settings.webhook_status.received',
+		)
+		expect(keyOf(received({ isMatched: false }))).toBe(
+			'dms_mailing.settings.webhook_status.received_unmatched',
+		)
+		expect(keyOf(received({ isMatched: false, isTest: true }))).toBe(
+			'dms_mailing.settings.webhook_status.received_test',
+		)
+	})
+
+	it('shows a refusal in red while nothing was accepted since', () => {
+		const status: WebhookStatus = {
+			lastReceived: received(),
+			lastRefused: { at: LATE, provider: 'postmark', reason: 'bad_secret' },
+		}
+		expect(isRefusalLatest(status)).toBe(true)
+		expect(webhookStatusLines(status)[1]).toMatchObject({
+			id: 'refused',
+			tone: 'error',
+			reasonKey: refusalKey('bad_secret'),
+		})
+		const healed: WebhookStatus = {
+			lastReceived: received({ at: LATE }),
+			lastRefused: { at: EARLY, provider: 'postmark', reason: 'bad_secret' },
+		}
+		expect(webhookStatusLines(healed)[1]?.tone).toBe('warning')
+	})
+})
+
+describe('webhookTestMessage', () => {
+	it('confirms a received test event', () => {
+		expect(webhookTestMessage(tested({ isReceived: true }))).toMatchObject({
+			color: 'success',
+			titleKey: 'dms_mailing.settings.webhook_status.test.received',
+			params: { duration: '42' },
+		})
+	})
+
+	it('names a refusal, an error status and an unreachable URL', () => {
+		expect(
+			webhookTestMessage(tested({ httpStatus: 403, refusal: 'bad_secret' })),
+		).toMatchObject({
+			color: 'error',
+			descriptionKey: refusalKey('bad_secret'),
+		})
+		expect(webhookTestMessage(tested({ httpStatus: 403 }))).toMatchObject({
+			titleKey: 'dms_mailing.settings.webhook_status.test.http_error',
+			descriptionKey: 'dms_mailing.settings.webhook_status.test.proxy_hint',
+		})
+		expect(
+			webhookTestMessage(tested({ httpStatus: 502 })).descriptionKey,
+		).toBeUndefined()
+		expect(
+			webhookTestMessage(tested({ networkError: 'ECONNREFUSED' })),
+		).toMatchObject({
+			titleKey: 'dms_mailing.settings.webhook_status.test.unreachable',
+			params: { error: 'ECONNREFUSED', url: URL },
+		})
+	})
+})

package/frontend-vue/vitest.config.ts

@@ -4,7 +4,10 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
 	plugins: [vue()],
 	test: {
-		environment: 'jsdom',
+		// Most suites need no DOM, and setting jsdom up per file is the bulk of
+		// the run; the files that mount components opt in with a
+		// `// @vitest-environment jsdom` header.
+		environment: 'node',
 		include: ['tests/**/*.test.ts'],
 	},
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -12,8 +12,10 @@
     "README.md",
     "dist",
     "!dist/.tsbuildinfo",
+    "!dist/test",
     "frontend-vue",
-    "src"
+    "src",
+    "!src/test"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,17 +35,17 @@
     "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
     "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.6 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.2.1 <1.0.0",
-    "@antelopejs/interface-dms-mailing": ">=0.5.0 <0.6.0",
+    "@antelopejs/interface-data-api": ">=0.2.1 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.6.0 <1.0.0",
+    "@antelopejs/interface-dms-mailing": ">=0.7.0 <0.8.0",
     "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
     "node-cron": "^4.2.1",
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.10.1 <2",
+    "@antelopejs/core": ">=1.13.4 <2",
     "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10",
@@ -73,7 +75,7 @@
   },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "dev": "ajs project run -w -p playground",
+    "dev": "ajs project dev -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 && antelopejs-check-interface-ranges",
@@ -84,9 +86,9 @@
     "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:backend": "pnpm run build && ajs module test .",
+    "test:backend": "([ -n \"$DMS_PREBUILT\" ] || 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 ."
+    "test:unit": "([ -n \"$DMS_PREBUILT\" ] || pnpm run build) && DMS_MAILING_TEST_DIR=dist/test/unit ajs module test .",
+    "test:integration": "([ -n \"$DMS_PREBUILT\" ] || pnpm run build) && DMS_MAILING_TEST_DIR=dist/test/integration ajs module test ."
   }
 }

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

@@ -3,7 +3,7 @@ import type {
   JsonSchema,
   TriggerType,
 } from "@antelopejs/interface-dms-automation";
-import { SEND_STATUSES, type SendEventType } from "../types";
+import { SEND_EVENT_TYPES, type SendEventType } from "../types";
 
 export interface EmailEventPayload {
   tenantId: string;
@@ -29,7 +29,7 @@ const CONFIG_SCHEMA: JsonSchema = {
   properties: {
     types: {
       type: "array",
-      items: { type: "string", enum: SEND_STATUSES },
+      items: { type: "string", enum: SEND_EVENT_TYPES },
       description:
         "Event types the trigger fires on. Leave empty to fire on every event.",
     },
@@ -42,7 +42,7 @@ const OUTPUT_SCHEMA: JsonSchema = {
     tenantId: { type: "string" },
     sendId: { type: "string" },
     templateSlug: { type: "string" },
-    type: { type: "string", enum: SEND_STATUSES },
+    type: { type: "string", enum: SEND_EVENT_TYPES },
     recipientEmail: { type: "string" },
   },
 };

package/src/automation/send-template-action.ts

@@ -4,7 +4,7 @@ import type {
 } from "@antelopejs/interface-dms-automation";
 import type { EmailAddress } from "@antelopejs/interface-email";
 import type { SendTemplateResult } from "@antelopejs/interface-dms-mailing";
-import { sendTemplate } from "../services/send";
+import { sendUnlessSuppressed } from "../services/checked-send";
 import { SEND_STATUSES } from "../types";
 
 export interface SendTemplateActionInput {
@@ -25,9 +25,11 @@ const INPUT_SCHEMA: JsonSchema = {
   properties: {
     tenantId: { type: "string" },
     slug: { type: "string", description: "Slug of the live mailing template" },
-    // A list, not just one address: the automation module has no loop node, so
-    // a procedure cannot call this action once per contact — the fan-out has to
-    // happen here. `sendTemplate` already accepts both shapes.
+    /**
+     * A list, not just one address: the automation module has no loop node, so
+     * a procedure cannot call this action once per contact — the fan-out has
+     * to happen here. `sendUnlessSuppressed` already accepts both shapes.
+     */
     to: {
       type: ["string", "array"],
       items: { type: "string" },
@@ -76,7 +78,7 @@ export const sendTemplateAction: ActionType<
     const source =
       input.source ?? `${AUTOMATION_SOURCE_PREFIX}${ctx.procedureId}`;
     try {
-      const result = await sendTemplate(input.slug, {
+      const result = await sendUnlessSuppressed(input.slug, {
         tenantId: input.tenantId,
         to: input.to,
         locale: input.locale,

package/src/config.ts

@@ -2,7 +2,9 @@ export interface DmsMailingConfig {
   useHtmlRender?: boolean;
 }
 
-const DEFAULTS: Required<DmsMailingConfig> = { useHtmlRender: true };
+const DEFAULTS: Required<DmsMailingConfig> = {
+  useHtmlRender: true,
+};
 
 let current: Required<DmsMailingConfig> = DEFAULTS;
 

package/src/constants.ts

@@ -1,6 +1,12 @@
 export const MODULE_ID = "mailing";
 export const API_BASE_PATH = "/api/mailing";
 export const TABLES_BASE_PATH = `${API_BASE_PATH}/tables`;
+export const MODULE_BASE_PATH = `/modules/${MODULE_ID}`;
+export const TEMPLATES_PATH = `${MODULE_BASE_PATH}/templates`;
+export const SENDS_PATH = `${MODULE_BASE_PATH}/sends`;
+export const SETTINGS_PATH = `${MODULE_BASE_PATH}/settings`;
+export const NEW_TEMPLATE_BUTTON_ID = "create";
+export const NEW_TEMPLATE_ACTION_ID = "mailing.new-template";
 export const FRONTEND_MODULE_NAME = "@antelopejs/dms-mailing-frontend-vue";
 export const EMAIL_TEMPLATE_NAME = "EmailMailingTemplate";
 
@@ -11,7 +17,7 @@ export const SENDS_PERIOD_SCOPE = "mailing-sends";
 
 export const MAILING_SENDS_TOPIC = "mailing:sends";
 
-export const GALLERY_DISPLAY_ID = "gallery";
+export const GALLERY_DISPLAY_ID = `${MODULE_ID}:gallery`;
 export const TEMPLATE_CATEGORIES_TYPE_ID = "mailing_template_categories";
 export const TEMPLATE_CATEGORY_TYPE_ID = "mailing_template_category";
 
@@ -29,7 +35,17 @@ export const HTTP_UNPROCESSABLE = 422;
 
 export const LOCALE_LIST_SEPARATOR = ",";
 
-export const SYSTEM_VARIABLE_PATHS = ["unsubscribeUrl", "preferencesUrl"];
+/** The status of a template taken out of use. */
+export const ARCHIVED_STATUS = "archived";
+
+export const UNSUBSCRIBE_URL_PATH = "unsubscribeUrl";
+export const PREFERENCES_URL_PATH = "preferencesUrl";
+
+/** The URLs a caller passes for the footer links, not declared by hand. */
+export const SYSTEM_VARIABLE_PATHS = [
+  UNSUBSCRIBE_URL_PATH,
+  PREFERENCES_URL_PATH,
+];
 
 /**
  * Ceiling on a metrics window. `from`/`to` are plain query parameters, and the

package/src/crons/attention.ts

@@ -0,0 +1,21 @@
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { TenantModel } from "@antelopejs/interface-dms/db";
+import { refreshTemplateAttention } from "../services/template-attention";
+import type { CronJob } from "./jobs";
+
+/**
+ * Hourly: a draft turns stale and a live template's last send leaves the
+ * stats window as time passes, with no write to say so.
+ */
+const ATTENTION_SCHEDULE = "5 * * * *";
+
+export async function runAttentionRefresh(): Promise<void> {
+  const tenants = await GetModel(TenantModel).getAll();
+  for (const tenant of tenants) await refreshTemplateAttention(tenant._id);
+}
+
+export const ATTENTION_JOB: CronJob = {
+  name: "mailing-attention",
+  schedule: ATTENTION_SCHEDULE,
+  run: runAttentionRefresh,
+};

package/src/crons/index.ts

@@ -1 +1,3 @@
+export * from "./attention";
+export * from "./jobs";
 export * from "./retention";

package/src/crons/jobs.ts

@@ -0,0 +1,35 @@
+import { Logging } from "@antelopejs/interface-core/logging";
+import cron, { type ScheduledTask } from "node-cron";
+
+/** A periodic job of the module: its name for the logs, when it runs, what. */
+export interface CronJob {
+  name: string;
+  schedule: string;
+  run: () => Promise<unknown>;
+}
+
+/** A job as it runs once scheduled. */
+export interface ScheduledJob {
+  name: string;
+  task: ScheduledTask;
+}
+
+/** Schedules `job`; a failed run is logged, never thrown. */
+export function scheduleJob(job: CronJob): ScheduledJob {
+  const task = cron.schedule(job.schedule, () => {
+    void job.run().catch((error: unknown) => {
+      Logging.Error(`Cron '${job.name}' failed:`, error);
+    });
+  });
+  return { name: job.name, task };
+}
+
+/** Stops the task and drops it from node-cron's module-level registry. */
+export async function stopJob(job: ScheduledJob): Promise<void> {
+  try {
+    await job.task.stop();
+    await job.task.destroy();
+  } catch (error) {
+    Logging.Error(`Cron '${job.name}' failed to stop:`, error);
+  }
+}

package/src/crons/retention.ts

@@ -1,10 +1,8 @@
 import { Logging } from "@antelopejs/interface-core/logging";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import { TenantModel } from "@antelopejs/interface-dms/db";
-import cron, { type ScheduledTask } from "node-cron";
 import { SendEventModel, SendModel, SettingsModel } from "../db";
-
-export const RETENTION_CRON_NAME = "mailing-retention";
+import type { CronJob } from "./jobs";
 
 export interface RetentionLimits {
   pageSize: number;
@@ -92,9 +90,7 @@ export async function purgeOrphanEvents(
 }
 
 async function purgeTenant(tenantId: string, now: Date): Promise<number> {
-  const settings = await GetModel(SettingsModel, tenantId).getSingleton(
-    tenantId,
-  );
+  const settings = await GetModel(SettingsModel, tenantId).get(tenantId);
   if (!settings || settings.logRetentionDays < MIN_RETENTION_DAYS) return 0;
   const limit = retentionLimit(settings.logRetentionDays, now);
   const purged = await purgeInPages(tenantPass(tenantId, limit));
@@ -110,19 +106,8 @@ export async function runRetention(now: Date = new Date()): Promise<number> {
   return purged;
 }
 
-/** Stops the task and drops it from node-cron's module-level registry. */
-export async function stopRetention(
-  task: ScheduledTask | undefined,
-): Promise<void> {
-  if (!task) return;
-  await task.stop();
-  await task.destroy();
-}
-
-export function scheduleRetention(): ScheduledTask {
-  return cron.schedule(RETENTION_SCHEDULE, () => {
-    void runRetention().catch((error: unknown) => {
-      Logging.Error(`Cron '${RETENTION_CRON_NAME}' failed:`, error);
-    });
-  });
-}
+export const RETENTION_JOB: CronJob = {
+  name: "mailing-retention",
+  schedule: RETENTION_SCHEDULE,
+  run: runRetention,
+};

package/src/data/displays.ts

@@ -0,0 +1,18 @@
+import {
+  ColumnDisplay,
+  RegisterDisplay,
+} from "@antelopejs/interface-dms/base/table-view";
+
+/**
+ * A template's locale codes as mono chips, the workspace locales it lacks
+ * drawn dashed in the warning tone.
+ */
+@RegisterDisplay("mailing:locale-chips")
+export class LocaleChipsDisplay extends ColumnDisplay<Record<string, never>> {}
+
+/**
+ * A template's category as its settings label and icon, an id the settings
+ * no longer declare shown as is.
+ */
+@RegisterDisplay("mailing:category")
+export class CategoryDisplay extends ColumnDisplay<Record<string, never>> {}

package/src/data/index.ts

@@ -1,3 +1,4 @@
 export * from "./body";
 export * from "./sends-table";
+export * from "./suppressions-table";
 export * from "./templates-table";

package/src/data/locale-fallback.ts

@@ -0,0 +1,26 @@
+import type { CellSubline } from "@antelopejs/interface-dms/base/table-view";
+
+const FALLBACK_KEY = "$dms_mailing.sends.locale_fallback";
+
+/** A locale code as the log shows it: `EN`. */
+export function localeCode(locale: string | undefined): string {
+  return (locale ?? "").toUpperCase();
+}
+
+/**
+ * The line under a send's locale when the caller asked for another one
+ * ("DE asked"), in the warning tone; `null` when the asked locale was used.
+ */
+export function localeFallbackSubline(
+  locale: string | undefined,
+  requestedLocale: string | undefined,
+): CellSubline | null {
+  if (!requestedLocale || requestedLocale === locale) return null;
+  return {
+    text: {
+      key: FALLBACK_KEY,
+      params: { requested: localeCode(requestedLocale) },
+    },
+    tone: "warning",
+  };
+}

package/src/data/read-only-routes.ts

@@ -0,0 +1,14 @@
+import { TableViewRoutes } from "@antelopejs/interface-dms/base";
+
+/**
+ * The routes of a table the module writes through its own routes: reading,
+ * counting and exporting only.
+ */
+export const READ_ONLY_ROUTES = {
+  get: TableViewRoutes.Get,
+  list: TableViewRoutes.List,
+  count: TableViewRoutes.Count,
+  countBatch: TableViewRoutes.CountBatch,
+  select: TableViewRoutes.Select,
+  ...TableViewRoutes.ExportRoutes,
+};