@antelopejs/dms-mailing 0.2.2

package/src/routes/settings.ts

@@ -0,0 +1,66 @@
+import {
+  Context,
+  Controller,
+  Get,
+  JSONBody,
+  Post,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assertValidation } from "@antelopejs/interface-api-util";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import { API_BASE_PATH } from "../constants";
+import { TemplateModel } from "../db";
+import { MailingSettingsPage } from "../pages/settings/page";
+import { reassignRemovedCategories } from "../services/categories";
+import { getSettings, saveSettings } from "../services/settings";
+import type { MailingSettingsValues } from "../types";
+import { settingsSchema } from "../validation/settings.schema";
+
+const INVALID_SETTINGS = "$dms_mailing.errors.invalid_settings";
+
+export class MailingSettingsController extends Controller(
+  `${API_BASE_PATH}/settings`,
+) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(MailingSettingsPage)
+  declare user: User;
+
+  @TenantScopedModel(TemplateModel)
+  declare templates: TemplateModel;
+
+  @Get("")
+  read(): Promise<MailingSettingsValues> {
+    return getSettings(getRequestTenantId(this.ctx));
+  }
+
+  @Post("")
+  async write(@JSONBody() body: unknown): Promise<MailingSettingsValues> {
+    const values = assertValidation(
+      body,
+      (value) => settingsSchema.parse(value),
+      () => INVALID_SETTINGS,
+    );
+    const saved = await saveSettings(getRequestTenantId(this.ctx), values);
+    await this.dropRemovedCategories(values.categories);
+    return saved;
+  }
+
+  /**
+   * A deleted category must not leave templates pointing at nothing: they fall
+   * back to no category.
+   */
+  private async dropRemovedCategories(
+    categories: MailingSettingsValues["categories"],
+  ): Promise<void> {
+    const templates = await this.templates.getAll();
+    const orphaned = reassignRemovedCategories(templates, categories);
+    for (const id of orphaned) {
+      await this.templates.update(id, { category: "" });
+    }
+  }
+}

package/src/routes/templates.ts

@@ -0,0 +1,256 @@
+import {
+  Context,
+  Controller,
+  Get,
+  JSONBody,
+  Parameter,
+  Post,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import {
+  API_BASE_PATH,
+  HTTP_CONFLICT,
+  HTTP_NOT_FOUND,
+  HTTP_UNPROCESSABLE,
+} from "../constants";
+import { collectContentVariablePaths, resolveEmail } from "../engine";
+import { type MailingTemplate, TemplateModel } from "../db";
+import { TemplatesPageController } from "../pages/templates";
+import { renderEmailHtml } from "../services/render";
+import { getSettings } from "../services/settings";
+import {
+  contentFieldsOf,
+  displayName,
+  localeContentOf,
+  parseContent,
+  parseTestData,
+  parseVariables,
+  pickLocale,
+  saveContent,
+} from "../services/templates";
+import type {
+  MailingSettingsValues,
+  TemplateContent,
+  TemplateStatus,
+  VariableDefinition,
+} from "../types";
+import {
+  duplicateSchema,
+  previewSchema,
+  templateContentSchema,
+  testDataSchema,
+  variablesSchema,
+} from "../validation/templates.schema";
+
+const NOT_FOUND = "$dms_mailing.errors.template_not_found";
+const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
+const INVALID_CONTENT = "$dms_mailing.errors.invalid_content";
+
+const STATUS_TRANSITIONS: Record<string, TemplateStatus> = {
+  publish: "live",
+  unpublish: "draft",
+  archive: "archived",
+};
+
+export interface CategoriesResponse {
+  categories: MailingSettingsValues["categories"];
+}
+
+export interface TemplateContentResponse {
+  template: MailingTemplate;
+  content: TemplateContent;
+  variables: VariableDefinition[];
+  /** Paths the content actually references, across every locale. */
+  detectedVariables: string[];
+  testData: Record<string, unknown>;
+  fallbackLocale: string;
+  categories: MailingSettingsValues["categories"];
+}
+
+export class TemplatesController extends Controller(
+  `${API_BASE_PATH}/templates`,
+) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(TemplatesPageController)
+  declare user: User;
+
+  @TenantScopedModel(TemplateModel)
+  declare templates: TemplateModel;
+
+  private get tenantId(): string {
+    return getRequestTenantId(this.ctx);
+  }
+
+  private async requireTemplate(id: string): Promise<MailingTemplate> {
+    const template = await this.templates.get(id);
+    assert(template, HTTP_NOT_FOUND, NOT_FOUND);
+    return template;
+  }
+
+  /**
+   * The tenant's categories for a category picker. Separate from `/settings`,
+   * which is guarded by the settings-manage permission a template editor need
+   * not hold.
+   */
+  @Get("/categories")
+  async categories(): Promise<CategoriesResponse> {
+    const settings = await getSettings(this.tenantId);
+    return { categories: settings.categories };
+  }
+
+  @Get("/:id/content")
+  async content(
+    @Parameter("id", "param") id: string,
+  ): Promise<TemplateContentResponse> {
+    const template = await this.requireTemplate(id);
+    const settings = await getSettings(this.tenantId);
+    const content = parseContent(template);
+    return {
+      template,
+      content,
+      variables: parseVariables(template),
+      detectedVariables: collectContentVariablePaths(content),
+      testData: parseTestData(template),
+      fallbackLocale: settings.fallbackLocale,
+      categories: settings.categories,
+    };
+  }
+
+  @Post("/:id/content")
+  async replaceContent(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const content = assertValidation(
+      body,
+      (value) =>
+        templateContentSchema.parse(
+          (value as { content: unknown }).content,
+        ) as TemplateContent,
+      () => INVALID_CONTENT,
+    );
+    await this.requireTemplate(id);
+    await saveContent(this.tenantId, id, content, displayName(this.user));
+    return {
+      saved: true,
+      detectedVariables: collectContentVariablePaths(content),
+    };
+  }
+
+  @Post("/:id/publish")
+  publish(@Parameter("id", "param") id: string) {
+    return this.transition(id, "publish");
+  }
+
+  @Post("/:id/unpublish")
+  unpublish(@Parameter("id", "param") id: string) {
+    return this.transition(id, "unpublish");
+  }
+
+  @Post("/:id/archive")
+  archive(@Parameter("id", "param") id: string) {
+    return this.transition(id, "archive");
+  }
+
+  private async transition(id: string, action: string) {
+    const template = await this.requireTemplate(id);
+    const status = STATUS_TRANSITIONS[action] as TemplateStatus;
+    const publishedAt = status === "live" ? new Date() : template.publishedAt;
+    await this.templates.update(id, {
+      status,
+      publishedAt,
+      updatedBy: displayName(this.user),
+    });
+    return { status };
+  }
+
+  @Post("/:id/variables")
+  async variables(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const { variables } = assertValidation(body, (value) =>
+      variablesSchema.parse(value),
+    );
+    await this.requireTemplate(id);
+    await this.templates.update(id, {
+      json_variables: JSON.stringify(variables),
+      updatedBy: displayName(this.user),
+    });
+    return { variables };
+  }
+
+  @Post("/:id/test-data")
+  async testData(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const { data } = assertValidation(body, (value) =>
+      testDataSchema.parse(value),
+    );
+    await this.requireTemplate(id);
+    await this.templates.update(id, { json_test_data: JSON.stringify(data) });
+    return { data };
+  }
+
+  @Post("/:id/preview")
+  async preview(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const input = assertValidation(
+      body,
+      (value) => previewSchema.parse(value),
+      () => INVALID_CONTENT,
+    );
+    const template = await this.requireTemplate(id);
+    const content =
+      (input.content as TemplateContent | undefined) ?? parseContent(template);
+    const settings = await getSettings(this.tenantId);
+    const locale = pickLocale(content, input.locale, settings.fallbackLocale);
+    const localeContent = localeContentOf(content, locale);
+    assert(localeContent, HTTP_UNPROCESSABLE, INVALID_CONTENT);
+    const email = resolveEmail(
+      localeContent,
+      input.data ?? parseTestData(template),
+    );
+    const html = await renderEmailHtml(email, locale);
+    return {
+      html,
+      subject: email.subject,
+      locale,
+      missing: email.missing,
+      hiddenBlockIds: email.hiddenBlockIds,
+    };
+  }
+
+  @Post("/:id/duplicate")
+  async duplicate(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const { slug, name } = assertValidation(body, (value) =>
+      duplicateSchema.parse(value),
+    );
+    const source = await this.requireTemplate(id);
+    const clash = await this.templates.getBySlug(slug);
+    assert(!clash, HTTP_CONFLICT, DUPLICATE_SLUG);
+    const author = displayName(this.user);
+    const [copyId] = await this.templates.insert({
+      slug,
+      name,
+      category: source.category,
+      status: "draft",
+      ...contentFieldsOf(source),
+      updatedBy: author,
+    });
+    return { id: copyId };
+  }
+}

package/src/services/attention.ts

@@ -0,0 +1,151 @@
+import type { MailingSend, MailingTemplate } from "../db";
+import { PROBLEM_STATUSES } from "../types";
+
+export type AttentionTone = "error" | "warning" | "neutral";
+
+export interface AttentionItem {
+  id: string;
+  tone: AttentionTone;
+  icon: string;
+  title: string;
+  description: string;
+  to: string;
+  params?: Record<string, string | number>;
+}
+
+const TEMPLATES_PAGE = "/modules/mailing/templates";
+const SENDS_PAGE = "/modules/mailing/sends";
+const SENDS_PROBLEMS_PAGE = `${SENDS_PAGE}?tab=problems`;
+const STALE_DRAFT_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+const isStaleDraft = (template: MailingTemplate, now: number): boolean =>
+  template.status === "draft" &&
+  !template.publishedAt &&
+  now - new Date(template.updatedAt).getTime() > STALE_DRAFT_DAYS * DAY_MS;
+
+function problemsItem(sends: MailingSend[]): AttentionItem[] {
+  const problems = sends.filter((send) =>
+    PROBLEM_STATUSES.includes(send.status),
+  );
+  if (!problems.length) return [];
+  return [
+    {
+      id: "problem-sends",
+      tone: "error",
+      icon: "i-ph-warning-octagon",
+      title: "$dms_mailing.attention.problem_sends.title",
+      description: "$dms_mailing.attention.problem_sends.description",
+      to: SENDS_PROBLEMS_PAGE,
+      params: { count: problems.length },
+    },
+  ];
+}
+
+function staleDraftsItem(templates: MailingTemplate[]): AttentionItem[] {
+  const stale = templates.filter((template) =>
+    isStaleDraft(template, Date.now()),
+  );
+  if (!stale.length) return [];
+  return [
+    {
+      id: "stale-drafts",
+      tone: "neutral",
+      icon: "i-ph-pencil-simple",
+      title: "$dms_mailing.attention.stale_drafts.title",
+      description: "$dms_mailing.attention.stale_drafts.description",
+      to: TEMPLATES_PAGE,
+      params: { count: stale.length },
+    },
+  ];
+}
+
+function neverSentItem(
+  templates: MailingTemplate[],
+  sends: MailingSend[],
+): AttentionItem[] {
+  const used = new Set(sends.map((send) => send.templateSlug));
+  const unused = templates.filter(
+    (template) => template.status === "live" && !used.has(template.slug),
+  );
+  if (!unused.length) return [];
+  return [
+    {
+      id: "unused-live",
+      tone: "warning",
+      icon: "i-ph-eye-slash",
+      title: "$dms_mailing.attention.unused_live.title",
+      description: "$dms_mailing.attention.unused_live.description",
+      to: TEMPLATES_PAGE,
+      params: { count: unused.length },
+    },
+  ];
+}
+
+/**
+ * Every send the Overview window holds, split the way the business view counts
+ * them: `sends` are the ones behind the figures, `excluded` the test sends the
+ * business audience drops.
+ */
+export interface AttentionWindow {
+  templates: MailingTemplate[];
+  sends: MailingSend[];
+  excluded: MailingSend[];
+  /** What the configured provider can report; `null` when it is unreachable. */
+  tracking: ProviderTracking | null;
+}
+
+/** The provider features the Overview's rates depend on. */
+export interface ProviderTracking {
+  name: string;
+  openTracking: boolean;
+  clickTracking: boolean;
+}
+
+function testOnlyWindowItem(window: AttentionWindow): AttentionItem[] {
+  if (window.sends.length || !window.excluded.length) return [];
+  return [
+    {
+      id: "test-only-window",
+      tone: "neutral",
+      icon: "i-ph-flask",
+      title: "$dms_mailing.attention.test_only_window.title",
+      description: "$dms_mailing.attention.test_only_window.description",
+      to: SENDS_PAGE,
+      params: { count: window.excluded.length },
+    },
+  ];
+}
+
+/**
+ * Open and click rates can only move if the provider reports those events. An
+ * SMTP provider reports neither, so the rates sit at 0 % forever — which reads
+ * as "nobody opened it" rather than "nobody can tell". Say so next to the
+ * figures, and only while the window actually shows some.
+ */
+function untrackedRatesItem(window: AttentionWindow): AttentionItem[] {
+  const { tracking } = window;
+  if (!tracking || !window.sends.length) return [];
+  if (tracking.openTracking && tracking.clickTracking) return [];
+  return [
+    {
+      id: "untracked-rates",
+      tone: "neutral",
+      icon: "i-ph-eye-slash",
+      title: "$dms_mailing.attention.untracked_rates.title",
+      description: "$dms_mailing.attention.untracked_rates.description",
+      to: SENDS_PAGE,
+      params: { provider: tracking.name },
+    },
+  ];
+}
+
+export function buildAttentionItems(window: AttentionWindow): AttentionItem[] {
+  return [
+    ...problemsItem(window.sends),
+    ...testOnlyWindowItem(window),
+    ...untrackedRatesItem(window),
+    ...neverSentItem(window.templates, window.sends),
+    ...staleDraftsItem(window.templates),
+  ];
+}

package/src/services/categories.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { MailingTemplate } from "../db";
+import type { TemplateCategory } from "../types";
+import { categorySchema } from "../validation/settings.schema";
+
+/** Direct API callers may send a JSON string; accept both string and array. */
+const categoriesSchema = z
+  .union([z.string(), z.array(categorySchema)])
+  .transform((value) => {
+    if (typeof value !== "string") return value;
+    if (value === "") return [];
+    try {
+      return JSON.parse(value) as unknown;
+    } catch {
+      return [];
+    }
+  })
+  .pipe(z.array(categorySchema));
+
+export const CATEGORIES_SCHEMA = categoriesSchema;
+
+/**
+ * Reads a category list off a form field or an API body. Never throws on shape:
+ * this runs while rendering a settings field.
+ */
+export function parseCategories(raw: unknown): TemplateCategory[] {
+  const parsed = categoriesSchema.safeParse(raw ?? []);
+  return parsed.success ? parsed.data : [];
+}
+
+/**
+ * Ids of the templates whose category is not in `categories` any more. Deleting
+ * a category must leave them uncategorised, never pointing at nothing.
+ */
+export function reassignRemovedCategories(
+  templates: MailingTemplate[],
+  categories: TemplateCategory[],
+): string[] {
+  const kept = new Set(categories.map((category) => category.id));
+  return templates
+    .filter((template) => template.category && !kept.has(template.category))
+    .map((template) => template._id);
+}

package/src/services/events.ts

@@ -0,0 +1,121 @@
+import { timingSafeEqual } from "node:crypto";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  emitEmailEvent,
+  type EmailEventPayload,
+} from "../automation/email-event-trigger";
+import { type MailingSend, SendEventModel, SendModel } from "../db";
+import type { EmailEvent } from "@antelopejs/interface-dms-mailing";
+import { publishSendUpdated } from "../realtime";
+import type { SendEventType, SendStatus } from "../types";
+import { notifyBounce } from "./notify";
+
+export interface SendCounters {
+  status: SendStatus;
+  opens: number;
+  clicks: number;
+}
+
+type CounterKey = keyof Pick<SendCounters, "opens" | "clicks">;
+
+const RANK: Record<SendStatus, number> = {
+  queued: 0,
+  sent: 1,
+  delivered: 2,
+  opened: 3,
+  clicked: 4,
+  unsubscribed: 5,
+  spam: 6,
+  bounced: 7,
+  failed: 7,
+};
+
+const COUNTERS: Partial<Record<SendEventType, CounterKey>> = {
+  opened: "opens",
+  clicked: "clicks",
+};
+
+const MAX_ACTIVITY_ATTEMPTS = 5;
+
+export function applyEvent(
+  current: SendCounters,
+  type: SendEventType,
+): SendCounters {
+  const counter = COUNTERS[type];
+  const next: SendCounters = { ...current };
+  if (counter) next[counter] = current[counter] + 1;
+  if (RANK[type] > RANK[current.status]) next.status = type;
+  return next;
+}
+
+async function publishEmailEvent(payload: EmailEventPayload): Promise<void> {
+  emitEmailEvent(payload);
+  publishSendUpdated(payload.sendId);
+  await notifyBounce(payload.tenantId, payload);
+}
+
+async function acceptEmailActivity(
+  tenantId: string,
+  event: EmailEvent,
+): Promise<MailingSend | undefined> {
+  const sends = GetModel(SendModel, tenantId);
+  for (let attempt = 0; attempt < MAX_ACTIVITY_ATTEMPTS; attempt++) {
+    const send = await sends.getByProviderMessageId(event.messageId);
+    if (!send || send.isRetiring) return undefined;
+    const accepted = await sends.recordActivity(send, {
+      ...applyEvent(
+        { status: send.status, opens: send.opens, clicks: send.clicks },
+        event.type,
+      ),
+      lastEventAt: event.at ?? new Date(),
+      provider: event.provider,
+    });
+    if (accepted) return send;
+  }
+  throw new Error("Mailing activity conflicted repeatedly; retry the webhook");
+}
+
+export async function recordEmailEvent(
+  tenantId: string,
+  event: EmailEvent,
+): Promise<boolean> {
+  const send = await acceptEmailActivity(tenantId, event);
+  if (!send) return false;
+  const at = event.at ?? new Date();
+  const recorded = await GetModel(SendEventModel, tenantId).insertForActiveSend(
+    {
+      sendId: send._id,
+      type: event.type,
+      at,
+      json_details: JSON.stringify(event.details ?? {}),
+    },
+  );
+  if (!recorded) return false;
+  await publishEmailEvent({
+    tenantId,
+    sendId: send._id,
+    templateSlug: send.templateSlug,
+    type: event.type,
+    recipientEmail: send.recipientEmail,
+  });
+  return true;
+}
+
+/**
+ * Whether a webhook request carries the tenant's secret.
+ *
+ * Fails closed on a blank stored secret: the event endpoint is the module's
+ * only unauthenticated route, so "no secret configured" must refuse everything
+ * rather than accept an empty header. The comparison itself is constant-time;
+ * only the length is observable.
+ */
+export function webhookSecretMatches(
+  provided: string | undefined,
+  stored: string,
+): boolean {
+  if (!stored || !provided) return false;
+  const left = Buffer.from(provided);
+  const right = Buffer.from(stored);
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}