@antelopejs/dms-mailing 0.2.2

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

@@ -0,0 +1,100 @@
+import type {
+  ActionType,
+  JsonSchema,
+} 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 { SEND_STATUSES } from "../types";
+
+export interface SendTemplateActionInput {
+  tenantId: string;
+  slug: string;
+  to: EmailAddress | EmailAddress[];
+  locale?: string;
+  variables?: Record<string, unknown>;
+  source?: string;
+}
+
+export const SEND_TEMPLATE_ACTION_ID = "mailing.send-template";
+
+const AUTOMATION_SOURCE_PREFIX = "automation:";
+
+const INPUT_SCHEMA: JsonSchema = {
+  type: "object",
+  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.
+    to: {
+      type: ["string", "array"],
+      items: { type: "string" },
+      description: "Recipient address, or the list of addresses to send to",
+    },
+    locale: { type: "string" },
+    variables: { type: "object" },
+    source: { type: "string" },
+  },
+  required: ["tenantId", "slug", "to"],
+};
+
+const RESULT_PROPERTIES: JsonSchema = {
+  sendId: { type: "string" },
+  status: { type: "string", enum: SEND_STATUSES },
+  messageId: { type: "string" },
+  error: { type: "string" },
+};
+
+const OUTPUT_SCHEMA: JsonSchema = {
+  type: "object",
+  properties: {
+    ...RESULT_PROPERTIES,
+    results: {
+      type: "array",
+      description: "One entry per recipient",
+      items: { type: "object", properties: RESULT_PROPERTIES },
+    },
+  },
+};
+
+const failedRecipients = (result: SendTemplateResult): SendTemplateResult[] =>
+  (result.results ?? [result]).filter((entry) => entry.status === "failed");
+
+export const sendTemplateAction: ActionType<
+  SendTemplateActionInput,
+  SendTemplateResult
+> = {
+  id: SEND_TEMPLATE_ACTION_ID,
+  name: "Send e-mail template",
+  description: "Render a live mailing template and send it to a recipient",
+  icon: "i-ph-envelope-simple",
+  inputSchema: INPUT_SCHEMA,
+  outputSchema: OUTPUT_SCHEMA,
+  async execute(input, ctx) {
+    const source =
+      input.source ?? `${AUTOMATION_SOURCE_PREFIX}${ctx.procedureId}`;
+    try {
+      const result = await sendTemplate(input.slug, {
+        tenantId: input.tenantId,
+        to: input.to,
+        locale: input.locale,
+        variables: input.variables,
+        source,
+      });
+      const failures = failedRecipients(result);
+      if (failures.length > 0) {
+        ctx.log(
+          "error",
+          `Template "${input.slug}" was rejected for ${failures.length} recipient(s)`,
+          failures,
+        );
+      }
+      return result;
+    } catch (error) {
+      ctx.log("error", `Template "${input.slug}" could not be sent`, error);
+      throw error;
+    }
+  },
+};

package/src/config.ts

@@ -0,0 +1,15 @@
+export interface DmsMailingConfig {
+  useHtmlRender?: boolean;
+}
+
+const DEFAULTS: Required<DmsMailingConfig> = { useHtmlRender: true };
+
+let current: Required<DmsMailingConfig> = DEFAULTS;
+
+export function setConfig(config: DmsMailingConfig): void {
+  current = { ...DEFAULTS, ...config };
+}
+
+export function getConfig(): Required<DmsMailingConfig> {
+  return current;
+}

package/src/constants.ts

@@ -0,0 +1,42 @@
+export const MODULE_ID = "mailing";
+export const API_BASE_PATH = "/api/mailing";
+export const TABLES_BASE_PATH = `${API_BASE_PATH}/tables`;
+export const FRONTEND_MODULE_NAME = "@antelopejs/dms-mailing-frontend-vue";
+export const EMAIL_TEMPLATE_NAME = "EmailMailingTemplate";
+
+export const MAILING_ACCESS_PERMISSION = "mailing.access";
+export const MAILING_TEMPLATES_MANAGE_PERMISSION = "mailing.templates.manage";
+export const MAILING_SEND_PERMISSION = "mailing.send";
+export const MAILING_SETTINGS_MANAGE_PERMISSION = "mailing.settings.manage";
+
+export const OVERVIEW_PERIOD_SCOPE = "mailing-overview";
+export const SENDS_PERIOD_SCOPE = "mailing-sends";
+
+export const MAILING_SENDS_TOPIC = "mailing:sends";
+
+export const GALLERY_DISPLAY_ID = "gallery";
+export const TEMPLATE_CATEGORIES_TYPE_ID = "mailing_template_categories";
+export const TEMPLATE_CATEGORY_TYPE_ID = "mailing_template_category";
+
+export const DEFAULT_FALLBACK_LOCALE = "en";
+export const DEFAULT_LOG_RETENTION_DAYS = 90;
+export const MAX_SLUG_LENGTH = 64;
+export const MAX_NAME_LENGTH = 120;
+export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const HTTP_BAD_REQUEST = 400;
+export const HTTP_FORBIDDEN = 403;
+export const HTTP_NOT_FOUND = 404;
+export const HTTP_CONFLICT = 409;
+export const HTTP_UNPROCESSABLE = 422;
+
+export const LOCALE_LIST_SEPARATOR = ",";
+
+export const SYSTEM_VARIABLE_PATHS = ["unsubscribeUrl", "preferencesUrl"];
+
+/**
+ * Ceiling on a metrics window. `from`/`to` are plain query parameters, and the
+ * daily series allocates one bucket per day, so an unbounded window lets a
+ * caller size the response by hand.
+ */
+export const MAX_WINDOW_DAYS = 400;

package/src/crons/index.ts

@@ -0,0 +1 @@
+export * from "./retention";

package/src/crons/retention.ts

@@ -0,0 +1,126 @@
+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";
+
+export interface RetentionLimits {
+  pageSize: number;
+  maxRows: number;
+}
+
+export interface RetentionPass {
+  loadPage(size: number): Promise<string[]>;
+  purgeSend(sendId: string): Promise<number>;
+}
+
+/**
+ * How many stale sends one pass reads at a time, and how many it retires per
+ * tenant per run. What the cap leaves behind drains over the following nights.
+ */
+export const RETENTION_LIMITS: RetentionLimits = {
+  pageSize: 500,
+  maxRows: 20_000,
+};
+
+const DAY_MS = 86_400_000;
+const RETENTION_SCHEDULE = "15 3 * * *";
+const MIN_RETENTION_DAYS = 1;
+const NO_ROWS = 0;
+
+export function retentionLimit(days: number, now: Date): Date {
+  return new Date(now.getTime() - days * DAY_MS);
+}
+
+export async function purgeInPages(
+  pass: RetentionPass,
+  limits: RetentionLimits = RETENTION_LIMITS,
+): Promise<number> {
+  let purged = NO_ROWS;
+  let inspected = NO_ROWS;
+  while (inspected < limits.maxRows) {
+    const size = Math.min(limits.pageSize, limits.maxRows - inspected);
+    const page = await pass.loadPage(size);
+    for (const sendId of page) purged += await pass.purgeSend(sendId);
+    inspected += page.length;
+    if (page.length < size) break;
+  }
+  return purged;
+}
+
+/** Replays interrupted cleanup without touching a send that became active after discovery. */
+export async function purgeSend(
+  tenantId: string,
+  sendId: string,
+  limit: Date,
+): Promise<number> {
+  const sends = GetModel(SendModel, tenantId);
+  if (!(await sends.retire(sendId, limit))) return NO_ROWS;
+  await GetModel(SendEventModel, tenantId).deleteBySend(sendId);
+  return sends.deleteRetired(sendId);
+}
+
+function tenantPass(tenantId: string, limit: Date): RetentionPass {
+  const sends = GetModel(SendModel, tenantId);
+  return {
+    async loadPage(size) {
+      const stale = await sends.listOlderThan(limit, size);
+      return stale.map((send) => send._id);
+    },
+    purgeSend: (sendId) => purgeSend(tenantId, sendId, limit),
+  };
+}
+
+/** Reconciles late inserts whose writer crashed before checking the retired parent. */
+export async function purgeOrphanEvents(
+  tenantId: string,
+  pageSize = RETENTION_LIMITS.pageSize,
+): Promise<void> {
+  const sends = GetModel(SendModel, tenantId);
+  const events = GetModel(SendEventModel, tenantId);
+  let after = "";
+  for (;;) {
+    const page = await events.listAfter(after, pageSize);
+    for (const sendId of new Set(page.map((event) => event.sendId))) {
+      if (!(await sends.get(sendId))) await events.deleteBySend(sendId);
+    }
+    if (page.length < pageSize) return;
+    after = page[page.length - 1]._id;
+  }
+}
+
+async function purgeTenant(tenantId: string, now: Date): Promise<number> {
+  const settings = await GetModel(SettingsModel, tenantId).getSingleton();
+  if (!settings || settings.logRetentionDays < MIN_RETENTION_DAYS) return 0;
+  const limit = retentionLimit(settings.logRetentionDays, now);
+  const purged = await purgeInPages(tenantPass(tenantId, limit));
+  await purgeOrphanEvents(tenantId);
+  return purged;
+}
+
+export async function runRetention(now: Date = new Date()): Promise<number> {
+  const tenants = await GetModel(TenantModel).getAll();
+  let purged = 0;
+  for (const tenant of tenants) purged += await purgeTenant(tenant._id, now);
+  Logging.Info(`[dms-mailing] Retention purged ${purged} sends`);
+  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);
+    });
+  });
+}

package/src/data/body.ts

@@ -0,0 +1,14 @@
+import { HTTPResult } from "@antelopejs/interface-api";
+import { HTTP_BAD_REQUEST } from "../constants";
+
+const INVALID_BODY = "$dms_mailing.errors.invalid_body";
+
+export function parseBody(body: Buffer | string): Record<string, unknown> {
+  const raw = typeof body === "string" ? body : body.toString("utf8");
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    throw new HTTPResult(HTTP_BAD_REQUEST, INVALID_BODY);
+  }
+}

package/src/data/index.ts

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

package/src/data/sends-table.ts

@@ -0,0 +1,154 @@
+import { Controller } from "@antelopejs/interface-api";
+import {
+  DataController,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  ModelReference,
+  Sortable,
+} from "@antelopejs/interface-data-api/metadata";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import {
+  Column,
+  Exported,
+  Searchable,
+  Select,
+  TableViewRoutes,
+} from "@antelopejs/interface-dms/base";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { TABLES_BASE_PATH } from "../constants";
+import { MailingSend, SendModel } from "../db";
+import { SEND_STATUSES, type SendStatus } from "../types";
+
+const STATUS_ITEMS = SEND_STATUSES.map((value) => ({
+  value,
+  label: `$dms_mailing.sends.status.${value}`,
+}));
+
+const readOnlyRoutes = {
+  get: TableViewRoutes.Get,
+  list: TableViewRoutes.List,
+  count: TableViewRoutes.Count,
+  select: TableViewRoutes.Select,
+  ...TableViewRoutes.ExportRoutes,
+};
+
+@RegisterDataController()
+export class SendsTableAPI extends DataController(
+  MailingSend,
+  readOnlyRoutes,
+  Controller(`${TABLES_BASE_PATH}/sends`),
+) {
+  @ModelReference()
+  @TenantScopedModel(SendModel)
+  declare model: SendModel;
+
+  @Select()
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Exported()
+  @Searchable()
+  @Sortable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.recipientEmail",
+    type: new DefaultDataTypes.EmailType({}),
+  })
+  declare recipientEmail: string;
+
+  @Listable()
+  @Exported()
+  @Searchable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.recipientName",
+    type: new DefaultDataTypes.StringType({}),
+  })
+  declare recipientName: string;
+
+  @Listable()
+  @Exported()
+  @Searchable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.templateSlug",
+    type: new DefaultDataTypes.StringType({}),
+    filterable: true,
+  })
+  declare templateSlug: string;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.status",
+    type: new DefaultDataTypes.SelectType({ items: STATUS_ITEMS }),
+    filterable: true,
+  })
+  declare status: SendStatus;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.locale",
+    type: new DefaultDataTypes.StringType({}),
+  })
+  declare locale: string;
+
+  @Listable()
+  @Exported()
+  @Sortable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.latencyMs",
+    type: new DefaultDataTypes.NumberType({}),
+  })
+  declare latencyMs: number;
+
+  @Listable()
+  @Exported()
+  @Sortable()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.createdAt",
+    type: new DefaultDataTypes.DateType({}),
+  })
+  declare createdAt: Date;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.source",
+    type: new DefaultDataTypes.StringType({}),
+  })
+  declare source: string;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.isTest",
+    type: new DefaultDataTypes.BooleanType({}),
+    filterable: true,
+  })
+  declare isTest: boolean;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.sends.cols.error",
+    type: new DefaultDataTypes.StringType({}),
+    isVisible: false,
+  })
+  declare error: string;
+}

package/src/data/templates-table.ts

@@ -0,0 +1,202 @@
+import {
+  Controller,
+  HTTPResult,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import {
+  DataController,
+  type DataControllerCallback,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  Mandatory,
+  ModelReference,
+  Sortable,
+} from "@antelopejs/interface-data-api/metadata";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { authenticateTenantRequest } from "@antelopejs/interface-dms/guards";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import {
+  Column,
+  Exported,
+  Searchable,
+  Select,
+  TableViewRoutes,
+} from "@antelopejs/interface-dms/base";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { ReadonlyBehaviorType } from "@antelopejs/interface-dms/base/types";
+import { HTTP_CONFLICT, HTTP_NOT_FOUND, TABLES_BASE_PATH } from "../constants";
+import { TemplateCategoryType } from "../data-types";
+import { MailingTemplate, TemplateModel } from "../db";
+import { getSettings } from "../services/settings";
+import { displayName, initializeTemplate } from "../services/templates";
+
+import { createTemplateSchema } from "../validation/templates.schema";
+import { parseBody } from "./body";
+
+const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
+const SOURCE_NOT_FOUND = "$dms_mailing.errors.template_not_found";
+const CREATE_ONLY = { edit: ReadonlyBehaviorType.disabled };
+// Read-only columns render as empty dashes on the create form; the four fields
+// a template is actually created from are the only ones worth asking for.
+const NEVER_ON_CREATE = { new: ReadonlyBehaviorType.hidden };
+
+const STATUS_ITEMS = ["draft", "live", "archived"].map((value) => ({
+  value,
+  label: `$dms_mailing.templates.status.${value}`,
+}));
+
+/** The template a creation copies from, refused rather than silently ignored. */
+async function resolveSource(
+  tenantId: string,
+  sourceTemplateId: string | undefined,
+): Promise<MailingTemplate | undefined> {
+  if (!sourceTemplateId) return undefined;
+  const source = await GetModel(TemplateModel, tenantId).get(sourceTemplateId);
+  if (!source) throw new HTTPResult(HTTP_NOT_FOUND, SOURCE_NOT_FOUND);
+  return source;
+}
+
+function withSeeding(base: DataControllerCallback): DataControllerCallback {
+  return {
+    ...base,
+    func: async function (
+      this: unknown,
+      ctx: RequestContext,
+      params: unknown,
+      body: Buffer | string,
+      ...rest: unknown[]
+    ) {
+      const seed = createTemplateSchema.parse(parseBody(body));
+      const tenantId = getRequestTenantId(ctx);
+      const existing = await GetModel(TemplateModel, tenantId).getBySlug(
+        seed.slug,
+      );
+      if (existing) throw new HTTPResult(HTTP_CONFLICT, DUPLICATE_SLUG);
+      const source = await resolveSource(tenantId, seed.sourceTemplateId);
+      const ids = (await base.func.call(
+        this,
+        ctx,
+        params,
+        body,
+        ...rest,
+      )) as string[];
+      const user = await authenticateTenantRequest(ctx);
+      const settings = await getSettings(tenantId);
+      await initializeTemplate(
+        tenantId,
+        ids[0] as string,
+        settings.fallbackLocale,
+        displayName(user),
+        source,
+      );
+      return ids;
+    },
+  };
+}
+
+const templateRoutes = {
+  ...TableViewRoutes.All,
+  new: withSeeding(TableViewRoutes.New),
+};
+
+@RegisterDataController()
+export class TemplatesTableAPI extends DataController(
+  MailingTemplate,
+  templateRoutes,
+  Controller(`${TABLES_BASE_PATH}/templates`),
+) {
+  @ModelReference()
+  @TenantScopedModel(TemplateModel)
+  declare model: TemplateModel;
+
+  @Select()
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Select()
+  @Listable()
+  @Sortable()
+  @Exported()
+  @Searchable()
+  @Mandatory("new")
+  @Access(AccessMode.ReadWrite)
+  @Column({
+    name: "$dms_mailing.templates.cols.name",
+    type: new DefaultDataTypes.StringType({}),
+  })
+  declare name: string;
+
+  @Select()
+  @Listable()
+  @Sortable()
+  @Exported()
+  @Searchable()
+  @Mandatory("new")
+  @Access(AccessMode.ReadWrite)
+  @Column({
+    name: "$dms_mailing.templates.cols.slug",
+    type: new DefaultDataTypes.StringType({}),
+    readonlyBehavior: CREATE_ONLY,
+  })
+  declare slug: string;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadWrite)
+  @Column({
+    name: "$dms_mailing.templates.cols.category",
+    type: new TemplateCategoryType(),
+    filterable: true,
+  })
+  declare category: string;
+
+  @Listable()
+  @Sortable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.templates.cols.status",
+    type: new DefaultDataTypes.SelectType({ items: STATUS_ITEMS }),
+    filterable: true,
+    readonlyBehavior: NEVER_ON_CREATE,
+  })
+  declare status: string;
+
+  @Listable()
+  @Sortable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.templates.cols.updatedAt",
+    type: new DefaultDataTypes.DateType({}),
+    readonlyBehavior: NEVER_ON_CREATE,
+  })
+  declare updatedAt: Date;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.templates.cols.locales",
+    type: new DefaultDataTypes.StringType({}),
+    readonlyBehavior: NEVER_ON_CREATE,
+  })
+  declare locales: string;
+
+  @Listable()
+  @Exported()
+  @Access(AccessMode.ReadOnly)
+  @Column({
+    name: "$dms_mailing.templates.cols.updatedBy",
+    type: new DefaultDataTypes.StringType({}),
+    readonlyBehavior: NEVER_ON_CREATE,
+  })
+  declare updatedBy: string;
+}

package/src/data-types/categories-type.ts

@@ -0,0 +1,29 @@
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import {
+  DataType,
+  RegisterDataType,
+} from "@antelopejs/interface-dms/base/data-types";
+import { TEMPLATE_CATEGORIES_TYPE_ID } from "../constants";
+import { CATEGORIES_SCHEMA } from "../services/categories";
+
+/**
+ * The tenant's template categories as a settings field — a repeatable list of
+ * {id, label, icon} that no built-in DataType models: the input is ours, and
+ * the validation accepts the array or the JSON string a form field stores.
+ */
+@RegisterDataType(TEMPLATE_CATEGORIES_TYPE_ID)
+export class TemplateCategoriesType extends DataType {
+  constructor(public readonly options: Record<string, unknown> = {}) {
+    super([], undefined, options);
+  }
+
+  protected defaultInputComponent() {
+    return CustomComponent("DmsMailingCategoriesInput")
+      .options(this.options)
+      .serializeSync();
+  }
+
+  getValidation() {
+    return CATEGORIES_SCHEMA;
+  }
+}