@antelopejs/dms-mailing 0.3.4 → 0.4.1

package/src/services/attention.ts

@@ -1,5 +1,16 @@
+import type { ActivityFeedItem } from "@antelopejs/interface-dms/base";
+import type {
+  ComposedText,
+  ComposedTextParam,
+} from "@antelopejs/interface-dms/base/types";
 import type { SendSummary, MailingTemplate } from "../db";
-import { PROBLEM_STATUSES } from "../types";
+import { LOCALE_LIST_SEPARATOR } from "../constants";
+import {
+  isResolvedStage,
+  PROBLEM_STATUSES,
+  type TemplateAttentionReason,
+} from "../types";
+import { isDeliveryUntracked, type ProviderTracking } from "./metrics";
 
 export type AttentionTone = "error" | "warning" | "neutral";
 
@@ -9,13 +20,24 @@ export interface AttentionItem {
   icon: string;
   title: string;
   description: string;
+  /** The verb of the next step, an i18n key ("Review problems"). */
+  action: string;
   to: string;
-  params?: Record<string, string | number>;
+  /** The figure the title leads with, shown bold. */
+  count?: number;
+  params?: Record<string, ComposedTextParam>;
+  /** Details shown in place of `description` where a feed lists them. */
+  details?: ComposedText[];
 }
 
 const TEMPLATES_PAGE = "/modules/mailing/templates";
+const TEMPLATES_ATTENTION_PAGE = `${TEMPLATES_PAGE}?tab=attention`;
 const SENDS_PAGE = "/modules/mailing/sends";
-const SENDS_PROBLEMS_PAGE = `${SENDS_PAGE}?tab=problems`;
+const SENDS_PROBLEMS_PAGE = `${SENDS_PAGE}?view=problems`;
+/** A settings form section, by the id the DMS form gives its anchor. */
+const SETTINGS_SECTION = "/modules/mailing/settings#dms-form-content-section-";
+const SENDER_SETTINGS = `${SETTINGS_SECTION}sender`;
+const PROVIDER_SETTINGS = `${SETTINGS_SECTION}provider`;
 const STALE_DRAFT_DAYS = 7;
 const DAY_MS = 86_400_000;
 
@@ -25,8 +47,9 @@ const isStaleDraft = (template: MailingTemplate, now: number): boolean =>
   now - new Date(template.updatedAt).getTime() > STALE_DRAFT_DAYS * DAY_MS;
 
 function problemsItem(sends: SendSummary[]): AttentionItem[] {
-  const problems = sends.filter((send) =>
-    PROBLEM_STATUSES.includes(send.status),
+  const problems = sends.filter(
+    (send) =>
+      PROBLEM_STATUSES.includes(send.status) && !isResolvedStage(send.stage),
   );
   if (!problems.length) return [];
   return [
@@ -36,8 +59,11 @@ function problemsItem(sends: SendSummary[]): AttentionItem[] {
       icon: "i-ph-warning-octagon",
       title: "$dms_mailing.attention.problem_sends.title",
       description: "$dms_mailing.attention.problem_sends.description",
+      action: "$dms_mailing.attention.problem_sends.action",
       to: SENDS_PROBLEMS_PAGE,
-      params: { count: problems.length },
+      count: problems.length,
+      params: problemBreakdown(problems),
+      details: problemDetails(problems),
     },
   ];
 }
@@ -54,19 +80,30 @@ function staleDraftsItem(templates: MailingTemplate[]): AttentionItem[] {
       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 },
+      action: "$dms_mailing.attention.stale_drafts.action",
+      to: TEMPLATES_ATTENTION_PAGE,
+      count: stale.length,
+      params: { count: stale.length, days: STALE_DRAFT_DAYS },
     },
   ];
 }
 
-function neverSentItem(
-  templates: MailingTemplate[],
-  sends: SendSummary[],
-): AttentionItem[] {
-  const used = new Set(sends.map((send) => send.templateSlug));
-  const unused = templates.filter(
-    (template) => template.status === "live" && !used.has(template.slug),
+const publishedBy = (template: MailingTemplate, end: Date): boolean =>
+  !template.publishedAt ||
+  new Date(template.publishedAt).getTime() <= end.getTime();
+
+/**
+ * Live templates no send of the window used. Only the window is read, so the
+ * item says "not sent in this period" rather than "never sent", and leaves
+ * out a template published after the window closed.
+ */
+function unusedLiveItem(window: AttentionWindow): AttentionItem[] {
+  const used = new Set(window.sends.map((send) => send.templateSlug));
+  const unused = window.templates.filter(
+    (template) =>
+      template.status === "live" &&
+      !used.has(template.slug) &&
+      publishedBy(template, window.windowEnd),
   );
   if (!unused.length) return [];
   return [
@@ -76,8 +113,10 @@ function neverSentItem(
       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 },
+      action: "$dms_mailing.attention.unused_live.action",
+      to: TEMPLATES_ATTENTION_PAGE,
+      count: unused.length,
+      params: { count: unused.length, names: namesOf(unused) },
     },
   ];
 }
@@ -91,15 +130,12 @@ export interface AttentionWindow {
   templates: MailingTemplate[];
   sends: SendSummary[];
   excluded: SendSummary[];
+  /** When the window closes. */
+  windowEnd: Date;
   /** 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;
+  /** Whether the settings name the address e-mails go out from. */
+  isSenderSet: boolean;
 }
 
 function testOnlyWindowItem(window: AttentionWindow): AttentionItem[] {
@@ -111,22 +147,65 @@ function testOnlyWindowItem(window: AttentionWindow): AttentionItem[] {
       icon: "i-ph-flask",
       title: "$dms_mailing.attention.test_only_window.title",
       description: "$dms_mailing.attention.test_only_window.description",
+      action: "$dms_mailing.attention.test_only_window.action",
       to: SENDS_PAGE,
+      count: window.excluded.length,
       params: { count: window.excluded.length },
     },
   ];
 }
 
+function senderMissingItem(window: AttentionWindow): AttentionItem[] {
+  if (window.isSenderSet) return [];
+  return [
+    {
+      id: "sender-missing",
+      tone: "warning",
+      icon: "i-ph-at",
+      title: "$dms_mailing.attention.sender_missing.title",
+      description: "$dms_mailing.attention.sender_missing.description",
+      action: "$dms_mailing.attention.sender_missing.action",
+      to: SENDER_SETTINGS,
+    },
+  ];
+}
+
+/**
+ * With nothing reported back, every send stays "sent": the delivery figures
+ * show "—" and this item says why, and where the webhook that would report
+ * them is set.
+ */
+function untrackedDeliveryItem(window: AttentionWindow): AttentionItem[] {
+  if (!isDeliveryUntracked(window.sends, window.tracking)) return [];
+  return [
+    {
+      id: "untracked-delivery",
+      tone: "neutral",
+      icon: "i-ph-plugs",
+      title: "$dms_mailing.attention.untracked_delivery.title",
+      description: "$dms_mailing.attention.untracked_delivery.description",
+      action: "$dms_mailing.attention.untracked_delivery.action",
+      to: PROVIDER_SETTINGS,
+      params: { provider: window.tracking?.name ?? "" },
+    },
+  ];
+}
+
+const showsEngagement = (send: SendSummary): boolean =>
+  send.opens > 0 || send.clicks > 0;
+
 /**
- * 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.
+ * Open and click rates can only move if something reports those events: the
+ * provider itself, or its webhook. Said only while the window shows none at
+ * all, so the item never contradicts rates the webhook does fill; when the
+ * delivery itself is unmeasured, that item says it already.
  */
 function untrackedRatesItem(window: AttentionWindow): AttentionItem[] {
   const { tracking } = window;
   if (!tracking || !window.sends.length) return [];
   if (tracking.openTracking && tracking.clickTracking) return [];
+  if (isDeliveryUntracked(window.sends, tracking)) return [];
+  if (window.sends.some(showsEngagement)) return [];
   return [
     {
       id: "untracked-rates",
@@ -134,18 +213,192 @@ function untrackedRatesItem(window: AttentionWindow): AttentionItem[] {
       icon: "i-ph-eye-slash",
       title: "$dms_mailing.attention.untracked_rates.title",
       description: "$dms_mailing.attention.untracked_rates.description",
-      to: SENDS_PAGE,
+      action: "$dms_mailing.attention.untracked_rates.action",
+      to: PROVIDER_SETTINGS,
       params: { provider: tracking.name },
     },
   ];
 }
 
+const MAX_LISTED_NAMES = 2;
+const LIST_SEPARATOR = ", ";
+const MORE_NAMES_KEY = "$dms_mailing.attention.more_names";
+
+/** The first names, and how many others there are ("A, B and 2 more"). */
+function namesOf(templates: MailingTemplate[]): ComposedTextParam {
+  const names = templates
+    .slice(0, MAX_LISTED_NAMES)
+    .map((template) => template.name)
+    .join(LIST_SEPARATOR);
+  const more = templates.length - MAX_LISTED_NAMES;
+  if (more <= 0) return names;
+  return {
+    key: MORE_NAMES_KEY,
+    params: { names, count: { type: "count", value: more } },
+  };
+}
+
+function problemBreakdown(problems: SendSummary[]): Record<string, number> {
+  const countOf = (status: string) =>
+    problems.filter((send) => send.status === status).length;
+  return {
+    count: problems.length,
+    bounced: countOf("bounced"),
+    failed: countOf("failed"),
+    spam: countOf("spam"),
+  };
+}
+
+const PROBLEM_PARTS = ["bounced", "failed", "spam"] as const;
+const PROBLEM_PART_KEY = "$dms_mailing.attention.problem_sends.parts.";
+
+/** One counted detail per problem kind present ("2 provider failures"). */
+function problemDetails(problems: SendSummary[]): ComposedText[] {
+  return PROBLEM_PARTS.map((status) => ({
+    status,
+    count: problems.filter((send) => send.status === status).length,
+  }))
+    .filter((part) => part.count > 0)
+    .map((part) => ({
+      key: `${PROBLEM_PART_KEY}${part.status}`,
+      params: { count: { type: "count", value: part.count } },
+    }));
+}
+
+const localeCodes = (template: MailingTemplate): string[] =>
+  template.locales.split(LOCALE_LIST_SEPARATOR).filter(Boolean);
+
+/**
+ * The locales any live template carries: they stand for the workspace's
+ * languages, since the server holds no list of its own.
+ */
+export function knownLocalesOf(templates: MailingTemplate[]): Set<string> {
+  return new Set(
+    templates
+      .filter((template) => template.status === "live")
+      .flatMap(localeCodes),
+  );
+}
+
+/** A live template missing one of the `known` locales. */
+function isMissingLocale(
+  template: MailingTemplate,
+  known: Set<string>,
+): boolean {
+  if (template.status !== "live") return false;
+  const own = new Set(localeCodes(template));
+  return [...known].some((code) => !own.has(code));
+}
+
+/** Live templates missing a locale the workspace writes in elsewhere. */
+export function missingLocaleTemplates(
+  templates: MailingTemplate[],
+): MailingTemplate[] {
+  const known = knownLocalesOf(templates);
+  return templates.filter((template) => isMissingLocale(template, known));
+}
+
+function missingLocalesItem(templates: MailingTemplate[]): AttentionItem[] {
+  const missing = missingLocaleTemplates(templates);
+  if (!missing.length) return [];
+  return [
+    {
+      id: "missing-locales",
+      tone: "warning",
+      icon: "i-ph-translate",
+      title: "$dms_mailing.attention.missing_locales.title",
+      description: "$dms_mailing.attention.missing_locales.description",
+      action: "$dms_mailing.attention.missing_locales.action",
+      to: TEMPLATES_ATTENTION_PAGE,
+      count: missing.length,
+      params: { count: missing.length, names: namesOf(missing) },
+    },
+  ];
+}
+
 export function buildAttentionItems(window: AttentionWindow): AttentionItem[] {
   return [
     ...problemsItem(window.sends),
+    ...missingLocalesItem(window.templates),
+    ...senderMissingItem(window),
+    ...untrackedDeliveryItem(window),
     ...testOnlyWindowItem(window),
     ...untrackedRatesItem(window),
-    ...neverSentItem(window.templates, window.sends),
+    ...unusedLiveItem(window),
     ...staleDraftsItem(window.templates),
   ];
 }
+
+const COUNT_PARAM = "count";
+
+function feedParams(
+  item: AttentionItem,
+): Record<string, ComposedTextParam> | undefined {
+  const params: Record<string, ComposedTextParam> = { ...item.params };
+  const count = item.count ?? item.params?.[COUNT_PARAM];
+  if (typeof count === "number") {
+    params[COUNT_PARAM] = { type: "count", value: count };
+  }
+  return Object.keys(params).length ? params : undefined;
+}
+
+/**
+ * An attention item as an `ActivityFeed` entry: the explanation (or its
+ * counted details) under the title, the verb of the next step as its trailing
+ * text, the whole entry linking to that step.
+ */
+export function attentionFeedItem(item: AttentionItem): ActivityFeedItem {
+  return {
+    id: item.id,
+    icon: item.icon,
+    tone: item.tone,
+    title: item.title,
+    meta: item.details?.length ? item.details : [item.description],
+    params: feedParams(item),
+    time: item.action,
+    to: item.to,
+  };
+}
+
+/** What the template rules read besides the template itself. */
+export interface TemplateAttentionContext {
+  now: number;
+  /** The slugs a real send used in the stats window. */
+  sentSlugs: Set<string>;
+  /** The locales any live template carries. */
+  knownLocales: Set<string>;
+}
+
+type TemplateAttentionRule = (
+  template: MailingTemplate,
+  context: TemplateAttentionContext,
+) => boolean;
+
+const TEMPLATE_ATTENTION_RULES: Record<
+  TemplateAttentionReason,
+  TemplateAttentionRule
+> = {
+  stale_draft: (template, context) => isStaleDraft(template, context.now),
+  never_sent: (template, context) =>
+    template.status === "live" && !context.sentSlugs.has(template.slug),
+  missing_locale: (template, context) =>
+    isMissingLocale(template, context.knownLocales),
+};
+
+const TEMPLATE_ATTENTION_REASONS = Object.keys(
+  TEMPLATE_ATTENTION_RULES,
+) as TemplateAttentionReason[];
+
+/**
+ * Why a template needs a look, in a stable order: a draft never published and
+ * untouched for a week, a live template no real send used in the stats
+ * window, a live template missing a locale the others carry.
+ */
+export function templateAttentionReasons(
+  template: MailingTemplate,
+  context: TemplateAttentionContext,
+): TemplateAttentionReason[] {
+  return TEMPLATE_ATTENTION_REASONS.filter((reason) =>
+    TEMPLATE_ATTENTION_RULES[reason](template, context),
+  );
+}

package/src/services/catalog.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import type { ModuleStatus } from "@antelopejs/interface-dms/page";
+import { readCapabilities } from "./provider";
+
+const PACKAGE_JSON_PATH = path.join(__dirname, "../../package.json");
+
+interface PackageManifest {
+  version?: string;
+}
+
+/** The module's published version, as the catalog tile and the sidebar show it. */
+export function moduleVersion(): string | undefined {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(PACKAGE_JSON_PATH, "utf8"),
+    ) as PackageManifest;
+    return manifest.version;
+  } catch {
+    return undefined;
+  }
+}
+
+/** No provider answering means no e-mail can leave: the owner must look. */
+export async function catalogStatus(): Promise<ModuleStatus> {
+  const capabilities = await readCapabilities();
+  return capabilities ? "live" : "attention";
+}

package/src/services/categories.ts

@@ -1,43 +1,44 @@
-import { z } from "zod";
 import type { MailingTemplate } from "../db";
 import type { TemplateCategory } from "../types";
-import { categorySchema } from "../validation/settings.schema";
+import type { CategoryEntry } 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));
+/** The categories a list keeps, without the removed ones it moves away. */
+export function keptCategories(entries: CategoryEntry[]): TemplateCategory[] {
+  return entries
+    .filter((entry) => entry.moveTo === undefined)
+    .map(({ id, label, icon }) => ({ id, label, icon }));
+}
 
-export const CATEGORIES_SCHEMA = categoriesSchema;
+/** Where the templates of each removed category go, by its id. */
+export function categoryMoves(entries: CategoryEntry[]): Map<string, string> {
+  return new Map(
+    entries.flatMap((entry) =>
+      entry.moveTo === undefined ? [] : [[entry.id, entry.moveTo] as const],
+    ),
+  );
+}
 
-/**
- * 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 : [];
+/** A template whose category has to change, and the one it gets. */
+export interface CategoryReassignment {
+  templateId: string;
+  category: string;
 }
 
 /**
- * Ids of the templates whose category is not in `categories` any more. Deleting
- * a category must leave them uncategorised, never pointing at nothing.
+ * The templates whose category is not in `categories` any more, each with the
+ * category it moves to: the one `moves` names, else none. Deleting a category
+ * must never leave a template pointing at nothing.
  */
 export function reassignRemovedCategories(
   templates: MailingTemplate[],
   categories: TemplateCategory[],
-): string[] {
+  moves: ReadonlyMap<string, string> = new Map(),
+): CategoryReassignment[] {
   const kept = new Set(categories.map((category) => category.id));
   return templates
     .filter((template) => template.category && !kept.has(template.category))
-    .map((template) => template._id);
+    .map((template) => ({
+      templateId: template._id,
+      category: moves.get(template.category as string) ?? "",
+    }));
 }

package/src/services/checked-send.ts

@@ -0,0 +1,123 @@
+import type { EmailAddress } from "@antelopejs/interface-email";
+import type { SendTemplateResult } from "@antelopejs/interface-dms-mailing";
+import { type MailingSuppression, normalizeAddress } from "../db";
+import {
+  aggregateResults,
+  type DeliveredMessage,
+  type ModuleSendParams,
+  prepare,
+  recordAll,
+  sendTemplate,
+} from "./send";
+import { suppressionsOf } from "./suppressions";
+
+/**
+ * A send the module checks against the suppression list. `allowSuppressed`
+ * names the addresses that still get it: the editor's own address on a test.
+ */
+export interface CheckedSendParams extends ModuleSendParams {
+  allowSuppressed?: string[];
+}
+
+/** Why nothing was sent to a recipient, as the log and the dialogs say it. */
+export const SUPPRESSED_ERROR_PREFIX = "$dms_mailing.errors.suppressed.";
+
+const NO_LATENCY = null;
+
+const addressOf = (to: EmailAddress): string =>
+  typeof to === "string" ? to : to.email;
+
+const toRecipients = (to: EmailAddress | EmailAddress[]): EmailAddress[] =>
+  Array.isArray(to) ? to : [to];
+
+/** The error a suppressed recipient's send keeps: an i18n key per reason. */
+export function suppressedError(row: MailingSuppression): string {
+  return `${SUPPRESSED_ERROR_PREFIX}${row.reason}`;
+}
+
+/** The entry of each recipient nothing may be sent to, by its address. */
+async function blockedRecipients(
+  params: CheckedSendParams,
+  recipients: EmailAddress[],
+): Promise<Map<string, MailingSuppression>> {
+  const suppressed = await suppressionsOf(
+    params.tenantId,
+    recipients.map(addressOf),
+  );
+  for (const allowed of params.allowSuppressed ?? []) {
+    suppressed.delete(normalizeAddress(allowed));
+  }
+  return suppressed;
+}
+
+function suppressedMessage(
+  to: EmailAddress,
+  row: MailingSuppression,
+): DeliveredMessage {
+  return {
+    to,
+    status: "suppressed",
+    outcome: { latencyMs: NO_LATENCY, error: suppressedError(row) },
+  };
+}
+
+/**
+ * Logs a `suppressed` send for each blocked recipient, after the same checks
+ * as a real send: an unknown or paused template is still refused.
+ */
+async function recordSuppressed(
+  slug: string,
+  params: CheckedSendParams,
+  blocked: EmailAddress[],
+  rows: Map<string, MailingSuppression>,
+): Promise<SendTemplateResult[]> {
+  const prepared = await prepare(params.tenantId, slug, params);
+  const messages = blocked.map((to) =>
+    suppressedMessage(
+      to,
+      rows.get(normalizeAddress(addressOf(to))) as MailingSuppression,
+    ),
+  );
+  return recordAll(prepared, params, messages);
+}
+
+async function sendAllowed(
+  slug: string,
+  params: CheckedSendParams,
+  allowed: EmailAddress[],
+): Promise<SendTemplateResult[]> {
+  if (!allowed.length) return [];
+  const result = await sendTemplate(slug, { ...params, to: allowed });
+  return result.results ?? [result];
+}
+
+/**
+ * Sends a template to every recipient but those on the suppression list,
+ * which are logged as `suppressed` instead. The results keep the order the
+ * recipients were given in.
+ */
+export async function sendUnlessSuppressed(
+  slug: string,
+  params: CheckedSendParams,
+): Promise<SendTemplateResult> {
+  const recipients = toRecipients(params.to);
+  const rows = await blockedRecipients(params, recipients);
+  if (!rows.size) return sendTemplate(slug, params);
+  const isBlocked = (to: EmailAddress): boolean =>
+    rows.has(normalizeAddress(addressOf(to)));
+  const blocked = recipients.filter(isBlocked);
+  const suppressedResults = await recordSuppressed(slug, params, blocked, rows);
+  const sentResults = await sendAllowed(
+    slug,
+    params,
+    recipients.filter((to) => !isBlocked(to)),
+  );
+  return aggregateResults(
+    recipients.map(
+      (to) =>
+        (isBlocked(to)
+          ? suppressedResults.shift()
+          : sentResults.shift()) as SendTemplateResult,
+    ),
+  );
+}