@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/services/notify.ts

@@ -6,57 +6,107 @@ import {
   Notification,
 } from "@antelopejs/interface-dms/notifications";
 import type { NotificationData } from "@antelopejs/interface-dms/notifications/types";
+import { type SendSummary, SendModel } from "../db";
 import { PROBLEM_STATUSES, type SendEventType } from "../types";
 
-export interface BounceNotificationInput {
+/** The problem event that may tip a template over the alert threshold. */
+export interface ProblemNotificationInput {
   sendId: string;
   templateSlug: string;
-  recipientEmail: string;
   type: SendEventType;
+  isTest: boolean;
 }
 
-export interface IdempotentNotificationTarget {
-  toUsersIdempotently(userIds: string[], idempotencyKey: string): Promise<void>;
+/** A template's real sends of the last hour, and how many had a problem. */
+export interface ProblemWindow {
+  sends: number;
+  problems: number;
 }
 
-export interface BounceNotificationData extends NotificationData {
+export interface ProblemNotificationData extends NotificationData {
   linkTo: string;
   params: Record<string, string | number>;
 }
 
-const SENDS_PROBLEMS_LINK = "/modules/mailing/sends?tab=problems";
+/** Below this many problems in the hour a template is not worth a ping. */
+export const ALERT_MIN_PROBLEMS = 3;
+/** Share of the hour's sends, in percent, that must have had a problem. */
+export const ALERT_MIN_RATE = 5;
+export const ALERT_WINDOW_MS = 3_600_000;
+
+const PERCENT = 100;
+const SENDS_PAGE = "/modules/mailing/sends";
+const PROBLEMS_VIEW = "problems";
 const IDEMPOTENCY_KEY_SEPARATOR = ":";
-const BOUNCE_ICON = "i-ph-warning";
-const BOUNCE_TITLE = "$dms_mailing.notifications.bounce_title";
-const BOUNCE_DESCRIPTION = "$dms_mailing.notifications.bounce_description";
+// The DMS keys notifications across every module: ours carry the module's name.
+const IDEMPOTENCY_KEY_PREFIX = "mailing:problems";
+const PROBLEMS_ICON = "i-ph-warning";
+const PROBLEMS_TITLE = "$dms_mailing.notifications.problems_title";
+const PROBLEMS_DESCRIPTION = "$dms_mailing.notifications.problems_description";
+/** Only a real send's problem counts: a test bouncing is the tester's business. */
+export function shouldNotify(input: ProblemNotificationInput): boolean {
+  return PROBLEM_STATUSES.includes(input.type) && !input.isTest;
+}
 
-export function shouldNotify(type: SendEventType): boolean {
-  return PROBLEM_STATUSES.includes(type);
+export function problemRate(window: ProblemWindow): number {
+  return window.sends
+    ? Math.round((window.problems * PERCENT) / window.sends)
+    : 0;
 }
 
-export function bounceNotification(
-  input: BounceNotificationInput,
-): BounceNotificationData {
+/** Whether a template's last hour went wrong often enough to tell its owners. */
+export function crossesThreshold(window: ProblemWindow): boolean {
+  return (
+    window.problems >= ALERT_MIN_PROBLEMS &&
+    problemRate(window) >= ALERT_MIN_RATE
+  );
+}
+
+export function problemWindowOf(sends: SendSummary[]): ProblemWindow {
+  const real = sends.filter((send) => !send.isTest);
   return {
-    icon: BOUNCE_ICON,
-    title: BOUNCE_TITLE,
-    description: BOUNCE_DESCRIPTION,
-    subject: GeneralSubject,
-    linkTo: SENDS_PROBLEMS_LINK,
-    params: { slug: input.templateSlug, email: input.recipientEmail },
+    sends: real.length,
+    problems: real.filter((send) => PROBLEM_STATUSES.includes(send.status))
+      .length,
   };
 }
 
-export function bounceIdempotencyKey(input: BounceNotificationInput): string {
-  return `${input.sendId}${IDEMPOTENCY_KEY_SEPARATOR}${input.type}`;
+/** The send log on the Problems tab, the drawer open on the send that tipped it. */
+export function problemsLink(sendId: string): string {
+  const query = new URLSearchParams({ view: PROBLEMS_VIEW, record: sendId });
+  return `${SENDS_PAGE}?${query.toString()}`;
 }
 
-export function deliverBounceNotification(
-  target: IdempotentNotificationTarget,
-  userIds: string[],
-  input: BounceNotificationInput,
-): Promise<void> {
-  return target.toUsersIdempotently(userIds, bounceIdempotencyKey(input));
+export function problemsNotification(
+  input: ProblemNotificationInput,
+  window: ProblemWindow,
+): ProblemNotificationData {
+  return {
+    icon: PROBLEMS_ICON,
+    title: PROBLEMS_TITLE,
+    description: PROBLEMS_DESCRIPTION,
+    subject: GeneralSubject,
+    linkTo: problemsLink(input.sendId),
+    params: {
+      count: window.problems,
+      slug: input.templateSlug,
+      rate: problemRate(window),
+    },
+  };
+}
+
+/**
+ * One notification per template and clock hour, however many problems follow:
+ * the DMS keeps the first delivery under a key and ignores the later ones.
+ */
+export function problemsIdempotencyKey(
+  input: ProblemNotificationInput,
+  at: Date,
+): string {
+  const hour = Math.floor(at.getTime() / ALERT_WINDOW_MS);
+  return [IDEMPOTENCY_KEY_PREFIX, input.templateSlug, hour].join(
+    IDEMPOTENCY_KEY_SEPARATOR,
+  );
 }
 
 async function tenantOwnerIds(tenantId: string): Promise<string[]> {
@@ -64,27 +114,59 @@ async function tenantOwnerIds(tenantId: string): Promise<string[]> {
   return owners.map((owner) => owner.userId);
 }
 
-export async function notifyBounce(
+async function lastHourOf(
+  tenantId: string,
+  templateSlug: string,
+  now: Date,
+): Promise<ProblemWindow> {
+  const since = new Date(now.getTime() - ALERT_WINDOW_MS);
+  const sends = await GetModel(SendModel, tenantId).listForTemplate(
+    templateSlug,
+    since,
+  );
+  return problemWindowOf(sends);
+}
+
+async function sendProblemsNotification(
+  tenantId: string,
+  input: ProblemNotificationInput,
+  now: Date,
+): Promise<void> {
+  const window = await lastHourOf(tenantId, input.templateSlug, now);
+  if (!crossesThreshold(window)) return;
+  const userIds = await tenantOwnerIds(tenantId);
+  if (userIds.length === 0) return;
+  const data = problemsNotification(input, window);
+  const notification = Notification()
+    .icon(data.icon)
+    .title(data.title)
+    .description(data.description)
+    .subject(data.subject)
+    .linkTo(data.linkTo)
+    .params(data.params)
+    .build();
+  await notification.toUsersIdempotently(
+    userIds,
+    problemsIdempotencyKey(input, now),
+  );
+}
+
+/**
+ * Tells the tenant's owners once a template's real sends keep failing: one
+ * aggregated notification per template and hour, past a threshold, never one
+ * per bounce.
+ */
+export async function notifyProblems(
   tenantId: string,
-  input: BounceNotificationInput,
+  input: ProblemNotificationInput,
+  now: Date = new Date(),
 ): Promise<void> {
-  if (!shouldNotify(input.type)) return;
+  if (!shouldNotify(input)) return;
   try {
-    const userIds = await tenantOwnerIds(tenantId);
-    if (userIds.length === 0) return;
-    const data = bounceNotification(input);
-    const notification = Notification()
-      .icon(data.icon)
-      .title(data.title)
-      .description(data.description)
-      .subject(data.subject)
-      .linkTo(data.linkTo)
-      .params(data.params)
-      .build();
-    await deliverBounceNotification(notification, userIds, input);
+    await sendProblemsNotification(tenantId, input, now);
   } catch (error) {
     Logging.Error(
-      `[dms-mailing] Failed to notify the bounce of "${input.recipientEmail}": ${String(error)}`,
+      `[dms-mailing] Failed to notify the problems of "${input.templateSlug}": ${String(error)}`,
     );
   }
 }

package/src/services/provider-banner.ts

@@ -0,0 +1,165 @@
+import type {
+  BannerAction,
+  BannerContent,
+} from "@antelopejs/interface-dms/base";
+import type { ComposedText } from "@antelopejs/interface-dms/base/types";
+import { API_BASE_PATH } from "../constants";
+import { MAX_BULK_REPLAY } from "./send-stats";
+
+/** What the provider banner is computed from. */
+export interface ProviderHealth {
+  /** Empty when no provider is connected. */
+  providerName: string;
+  providerReachable: boolean;
+  /** Provider failures since `since`, the ones a send again may fix. */
+  recentFailures: number;
+  /** Of those, the ones where the provider could not be reached at all. */
+  transportFailures: number;
+  /**
+   * Of those, the ones whose address is on the suppression list: a send
+   * again leaves them out, nothing would reach it.
+   */
+  suppressedFailures: number;
+  /** Real sends since `since`, the base of the failure rate. */
+  recentSends: number;
+  since: Date;
+}
+
+/** Fewer failures than this in the hour are a recipient's, not the provider's. */
+export const FAILING_MIN_COUNT = 3;
+/** Share of the hour's sends, in percent, that must have failed. */
+export const FAILING_MIN_RATE = 10;
+
+const PERCENT = 100;
+
+type BannerState = "missing" | "unreachable" | "failing";
+
+const KEY = "$dms_mailing.sends.banner.";
+const SETTINGS_PROVIDER_PAGE = "/modules/mailing/settings#provider";
+
+const TITLE_KEYS: Record<BannerState, string> = {
+  missing: "missing_title",
+  unreachable: "unreachable_title",
+  failing: "failures_title",
+};
+
+const key = (path: string): string => `${KEY}${path}`;
+
+function bannerState(health: ProviderHealth): BannerState {
+  if (health.providerReachable) return "failing";
+  return health.providerName ? "unreachable" : "missing";
+}
+
+const providerParam = (health: ProviderHealth): ComposedText | string =>
+  health.providerName || { key: key("the_provider") };
+
+function description(health: ProviderHealth, state: BannerState): ComposedText {
+  if (!health.recentFailures) return { key: key(`${state}_description`) };
+  return {
+    key: key("failures_description"),
+    params: {
+      count: { type: "count", value: health.recentFailures },
+      provider: providerParam(health),
+    },
+  };
+}
+
+/**
+ * Whether the failures add up to a provider problem: any connection failure,
+ * or enough failures, and a large enough share of the hour's sends. A single
+ * recipient's rejection is told on its own row, not here.
+ */
+export function isProviderFailing(health: ProviderHealth): boolean {
+  if (health.transportFailures) return true;
+  const rate = health.recentSends
+    ? (health.recentFailures * PERCENT) / health.recentSends
+    : 0;
+  return health.recentFailures >= FAILING_MIN_COUNT && rate >= FAILING_MIN_RATE;
+}
+
+/** The failures a send again would send: not those to a suppressed address. */
+const sendableFailures = (health: ProviderHealth): number =>
+  Math.max(health.recentFailures - health.suppressedFailures, 0);
+
+function confirmTexts(total: number) {
+  const count = Math.min(total, MAX_BULK_REPLAY);
+  const isCapped = total > count;
+  return {
+    description: key(
+      isCapped ? "confirm.description_capped" : "confirm.description",
+    ),
+    params: isCapped ? { count, total } : { count },
+  };
+}
+
+/** The failures left out, listed in the dialog so its count adds up. */
+function confirmImpact(health: ProviderHealth) {
+  if (!health.suppressedFailures) return {};
+  return {
+    impact: [
+      {
+        icon: "i-ph-prohibit",
+        label: key("confirm.suppressed"),
+        count: health.suppressedFailures,
+      },
+    ],
+  };
+}
+
+function replayAction(health: ProviderHealth): BannerAction {
+  return {
+    label: key("send_again"),
+    icon: "i-ph-arrow-clockwise",
+    color: "error",
+    target: {
+      type: "api",
+      url: `${API_BASE_PATH}/sends/replay-failed`,
+      method: "POST",
+      body: { since: health.since.toISOString() },
+      successMessage: key("replayed"),
+    },
+    confirm: {
+      title: key("confirm.title"),
+      ...confirmTexts(sendableFailures(health)),
+      ...confirmImpact(health),
+      color: "warning",
+      icon: "i-ph-arrow-clockwise",
+      confirmLabel: key("confirm.confirm"),
+      cancelLabel: key("confirm.cancel"),
+    },
+  };
+}
+
+function actions(health: ProviderHealth): BannerAction[] {
+  const settings: BannerAction = {
+    label: key("settings"),
+    to: SETTINGS_PROVIDER_PAGE,
+    variant: "outline",
+    color: "neutral",
+  };
+  return sendableFailures(health)
+    ? [settings, replayAction(health)]
+    : [settings];
+}
+
+/**
+ * The send log's provider banner: `null` while the provider answers and its
+ * failures do not add up to a provider problem, otherwise what is wrong and
+ * the way out.
+ */
+export function buildProviderBanner(
+  health: ProviderHealth,
+): BannerContent | null {
+  if (health.providerReachable && !isProviderFailing(health)) return null;
+  const state = bannerState(health);
+  return {
+    tone: "error",
+    icon: "i-ph-plugs",
+    title: {
+      key: key(TITLE_KEYS[state]),
+      params: { provider: providerParam(health) },
+    },
+    description: description(health, state),
+    actions: actions(health),
+  };
+}

package/src/services/render.ts

@@ -23,6 +23,7 @@ export async function renderEmailHtml(
 ): Promise<string> {
   if (!getConfig().useHtmlRender) return renderFallbackHtml(email, locale);
   try {
+    // The DMS renderer already drops Vue's SSR markers (dms-frontend 0.5.4).
     return await GenerateHtml(MailingEmailTemplate, { locale, email });
   } catch (error) {
     Logging.Warn(

package/src/services/send-stat-items.ts

@@ -0,0 +1,160 @@
+import type { StatGroupItem } from "@antelopejs/interface-dms/base";
+import type {
+  BlockText,
+  ComposedText,
+} from "@antelopejs/interface-dms/base/types";
+import type { SendStats } from "./send-stats";
+
+/** Past this wait the oldest queued send is worth a warning. */
+export const QUEUE_WARNING_MS = 10 * 60_000;
+/** Past this latency the figure switches to seconds. */
+export const SLOW_LATENCY_MS = 5000;
+
+const KEY = "$dms_mailing.sends.stats.";
+const PERCENT = 100;
+const MS_PER_SECOND = 1000;
+const EMPTY_FIGURE = "—";
+const PROBLEMS_PAGE = "/modules/mailing/sends?view=problems";
+const PROBLEM_PARTS = ["bounced", "failed", "spam"] as const;
+const THE_PROVIDER: ComposedText = {
+  key: "$dms_mailing.sends.banner.the_provider",
+};
+
+const key = (path: string): string => `${KEY}${path}`;
+
+const text = (path: string, params?: ComposedText["params"]): ComposedText =>
+  params ? { key: key(path), params } : { key: key(path) };
+
+const count = (value: number) => ({ type: "count" as const, value });
+
+const percent = (rate: number) => ({
+  type: "number" as const,
+  value: Math.round(rate) / PERCENT,
+  format: "percent" as const,
+});
+
+/** A list of texts joined as one line ("▲ 8 % · + 3 tests, not counted"). */
+function joined(parts: ComposedText[], fallback: ComposedText): BlockText {
+  if (!parts.length) return fallback;
+  return parts.reduce((left, right) => text("joined", { left, right }));
+}
+
+function deltaText(delta: number | null): ComposedText[] {
+  if (!delta) return [];
+  return [
+    text(delta > 0 ? "delta_up" : "delta_down", {
+      delta: percent(Math.abs(delta)),
+    }),
+  ];
+}
+
+function sendsItem(stats: SendStats): StatGroupItem {
+  const tests = stats.tests
+    ? [text("tests_excluded", { count: count(stats.tests) })]
+    : [];
+  return {
+    id: "sends",
+    icon: "i-ph-paper-plane-tilt",
+    eyebrow: key("sends"),
+    value: stats.sends,
+    detail: joined(
+      [...deltaText(stats.sendsDelta), ...tests],
+      text("no_tests"),
+    ),
+  };
+}
+
+function deliveredItem(stats: SendStats, provider: string): StatGroupItem {
+  if (stats.isDeliveryUntracked) {
+    return {
+      id: "delivered",
+      icon: "i-ph-check-circle",
+      eyebrow: key("delivered"),
+      value: EMPTY_FIGURE,
+      detail: text("not_tracked", { provider: provider || THE_PROVIDER }),
+    };
+  }
+  return {
+    id: "delivered",
+    icon: "i-ph-check-circle",
+    eyebrow: key("delivered"),
+    value:
+      stats.sends && stats.deliverability !== null
+        ? text("rate", { rate: percent(stats.deliverability) })
+        : EMPTY_FIGURE,
+    detail: text("delivered_of", {
+      delivered: stats.delivered,
+      sends: stats.sends,
+    }),
+  };
+}
+
+function problemsItem(stats: SendStats): StatGroupItem {
+  const parts = PROBLEM_PARTS.filter((part) => stats[part]).map((part) =>
+    text(`breakdown.${part}`, { count: count(stats[part]) }),
+  );
+  return {
+    id: "problems",
+    icon: "i-ph-warning-octagon",
+    tone: stats.problems ? "error" : undefined,
+    eyebrow: key("problems"),
+    value: stats.problems,
+    detail: joined(parts, text("no_problems")),
+    to: stats.problems ? PROBLEMS_PAGE : undefined,
+  };
+}
+
+function queuedItem(stats: SendStats, now: number): StatGroupItem {
+  const oldest = stats.oldestQueuedAt;
+  const waited = oldest ? now - new Date(oldest).getTime() : 0;
+  return {
+    id: "queued",
+    icon: "i-ph-clock",
+    eyebrow: key("queued"),
+    value: stats.queued,
+    detail: oldest
+      ? text("oldest_waiting", { time: { type: "relative", value: oldest } })
+      : text("nothing_waiting"),
+    detailTone: waited > QUEUE_WARNING_MS ? "warning" : undefined,
+  };
+}
+
+/** The median latency in milliseconds, or in seconds past five seconds. */
+export function latencyText(ms: number): ComposedText {
+  if (ms < SLOW_LATENCY_MS) return text("latency_ms", { value: ms });
+  return text("latency_s", {
+    value: { type: "number", value: ms / MS_PER_SECOND, format: "decimal" },
+  });
+}
+
+function latencyItem(stats: SendStats, provider: string): StatGroupItem {
+  return {
+    id: "latency",
+    icon: "i-ph-timer",
+    eyebrow: key("latency"),
+    value: stats.sends ? latencyText(stats.latencyMedian) : EMPTY_FIGURE,
+    detail: provider
+      ? text("latency_detail", { provider })
+      : text("latency_detail_generic"),
+  };
+}
+
+/**
+ * The five cells of the send log's stat strip, as `StatGroup` items whose
+ * texts the DMS composes in the reader's language: sends with the tests left
+ * out, deliverability, problems with their breakdown, the queue with its
+ * oldest wait, and the median API latency.
+ */
+export function buildSendStatItems(
+  stats: SendStats,
+  provider: string,
+  now: number = Date.now(),
+): StatGroupItem[] {
+  return [
+    sendsItem(stats),
+    deliveredItem(stats, provider),
+    problemsItem(stats),
+    queuedItem(stats, now),
+    latencyItem(stats, provider),
+  ];
+}

package/src/services/send-stats.ts

@@ -0,0 +1,122 @@
+import type { ProviderCapabilities } from "@antelopejs/interface-email";
+import type { SendSummary } from "../db";
+import { isResolvedStage, type SendStatus } from "../types";
+import {
+  aggregate,
+  deltaPercent,
+  isDeliveryUntracked,
+  type ProviderTracking,
+} from "./metrics";
+
+/** The figures of the send log's stat strip, for one period. */
+export interface SendStats {
+  sends: number;
+  /** `null` when the previous period had no send to compare with. */
+  sendsDelta: number | null;
+  /** Test sends of the period, shown next to the count but not in it. */
+  tests: number;
+  delivered: number;
+  /** `null` without a real send in the period. */
+  deliverability: number | null;
+  /**
+   * The provider reports no delivery (SMTP) and no webhook event came back:
+   * every send stays "sent", and a deliverability would mislead.
+   */
+  isDeliveryUntracked: boolean;
+  /**
+   * Problems nobody dealt with yet, like the Problems tab and the nav badge: a
+   * send again resolves its original. The breakdown counts the same sends.
+   */
+  problems: number;
+  bounced: number;
+  failed: number;
+  spam: number;
+  queued: number;
+  /** When the oldest send still queued was made; `null` with none queued. */
+  oldestQueuedAt: string | null;
+  latencyMedian: number;
+}
+
+const isQueued = (send: SendSummary): boolean => send.status === "queued";
+
+function oldestQueuedAt(sends: SendSummary[]): string | null {
+  const queued = sends
+    .filter(isQueued)
+    .map((send) => new Date(send.createdAt).getTime());
+  if (!queued.length) return null;
+  return new Date(Math.min(...queued)).toISOString();
+}
+
+/** What the provider says it tracks; `null` while it cannot be reached. */
+export function trackingOf(
+  capabilities: ProviderCapabilities | null,
+): ProviderTracking | null {
+  if (!capabilities) return null;
+  return {
+    name: capabilities.name,
+    openTracking: capabilities.features.openTracking,
+    clickTracking: capabilities.features.clickTracking,
+  };
+}
+
+type ProblemBreakdown = Pick<
+  SendStats,
+  "problems" | "bounced" | "failed" | "spam"
+>;
+
+function problemBreakdown(real: SendSummary[]): ProblemBreakdown {
+  const open = real.filter((send) => !isResolvedStage(send.stage));
+  const countOf = (status: SendStatus): number =>
+    open.filter((send) => send.status === status).length;
+  const bounced = countOf("bounced");
+  const failed = countOf("failed");
+  const spam = countOf("spam");
+  return { problems: bounced + failed + spam, bounced, failed, spam };
+}
+
+/** `previous` is `null` when the user turned the comparison off. */
+export function buildSendStats(
+  current: SendSummary[],
+  previous: SendSummary[] | null,
+  tracking: ProviderTracking | null = null,
+): SendStats {
+  const real = current.filter((send) => !send.isTest);
+  const totals = aggregate(real);
+  const previousTotals = previous
+    ? aggregate(previous.filter((send) => !send.isTest))
+    : null;
+  return {
+    sends: totals.sends,
+    sendsDelta: deltaPercent(totals.sends, previousTotals?.sends ?? null),
+    tests: current.length - real.length,
+    delivered: totals.delivered,
+    deliverability: totals.deliverability,
+    isDeliveryUntracked: isDeliveryUntracked(real, tracking),
+    ...problemBreakdown(real),
+    queued: totals.queued,
+    oldestQueuedAt: oldestQueuedAt(real),
+    latencyMedian: totals.latencyMedian,
+  };
+}
+
+/** At most this many failures go again in one "send the failures again". */
+export const MAX_BULK_REPLAY = 100;
+
+/** An error of the connection to the provider rather than of one recipient. */
+const TRANSPORT_ERROR =
+  /ECONN|ETIMEDOUT|EHOSTUNREACH|ENOTFOUND|EAI_AGAIN|ESOCKET|timed? ?out|connection/i;
+
+/**
+ * Provider failures worth a send again: failed, not a bounce, not a test, and
+ * not already sent again by someone.
+ */
+export function isProviderFailure(send: SendSummary): boolean {
+  return (
+    send.status === "failed" && !send.isTest && !isResolvedStage(send.stage)
+  );
+}
+
+/** A provider failure that says the provider could not be reached at all. */
+export function isTransportFailure(send: SendSummary): boolean {
+  return isProviderFailure(send) && TRANSPORT_ERROR.test(send.error ?? "");
+}