@antelopejs/dms-mailing 0.2.2

package/src/services/metrics.ts

@@ -0,0 +1,175 @@
+import type { MailingSend } from "../db";
+import {
+  BUSINESS_AUDIENCE,
+  OPERATIONAL_AUDIENCE,
+  type SendAudience,
+  type SendStatus,
+} from "../types";
+
+const AUDIENCE_KEEPS: Record<SendAudience, (send: MailingSend) => boolean> = {
+  [BUSINESS_AUDIENCE]: (send) => !send.isTest,
+  [OPERATIONAL_AUDIENCE]: () => true,
+};
+
+const AUDIENCE_BY_NAME: Record<string, SendAudience> = {
+  [BUSINESS_AUDIENCE]: BUSINESS_AUDIENCE,
+  [OPERATIONAL_AUDIENCE]: OPERATIONAL_AUDIENCE,
+};
+
+/** Named audience behind a query value; anything unknown is the business view. */
+export function readAudience(raw: string | null | undefined): SendAudience {
+  return AUDIENCE_BY_NAME[raw ?? ""] ?? BUSINESS_AUDIENCE;
+}
+
+export function forAudience(
+  sends: MailingSend[],
+  audience: SendAudience,
+): MailingSend[] {
+  return sends.filter(AUDIENCE_KEEPS[audience]);
+}
+
+export interface Totals {
+  sends: number;
+  queued: number;
+  sent: number;
+  delivered: number;
+  opened: number;
+  clicked: number;
+  bounced: number;
+  failed: number;
+  spam: number;
+  unsubscribed: number;
+  deliverability: number;
+  openRate: number;
+  clickRate: number;
+  latencyMedian: number;
+}
+
+export interface SeriesPoint {
+  x: string;
+  y: number;
+}
+
+export interface DateRange {
+  from: Date;
+  to: Date;
+}
+
+const PERCENT = 100;
+const DAY_MS = 86_400_000;
+const DAY_KEY_LENGTH = 10;
+const DELTA_PRECISION = 1;
+const DELIVERED_LIKE: SendStatus[] = [
+  "delivered",
+  "opened",
+  "clicked",
+  "unsubscribed",
+  "spam",
+];
+const OPENED_LIKE: SendStatus[] = ["opened", "clicked"];
+
+export const ratio = (part: number, whole: number): number =>
+  whole ? (part / whole) * PERCENT : 0;
+
+const countIf = (
+  sends: MailingSend[],
+  predicate: (send: MailingSend) => boolean,
+): number => sends.filter(predicate).length;
+
+const byStatus =
+  (status: SendStatus) =>
+  (send: MailingSend): boolean =>
+    send.status === status;
+
+function median(values: number[]): number {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.floor(sorted.length / 2)] as number;
+}
+
+export function aggregate(sends: MailingSend[]): Totals {
+  const delivered = countIf(sends, (send) =>
+    DELIVERED_LIKE.includes(send.status),
+  );
+  const opened = countIf(sends, (send) => OPENED_LIKE.includes(send.status));
+  const clicked = countIf(sends, byStatus("clicked"));
+  return {
+    sends: sends.length,
+    queued: countIf(sends, byStatus("queued")),
+    sent: countIf(sends, byStatus("sent")),
+    delivered,
+    opened,
+    clicked,
+    bounced: countIf(sends, byStatus("bounced")),
+    failed: countIf(sends, byStatus("failed")),
+    spam: countIf(sends, byStatus("spam")),
+    unsubscribed: countIf(sends, byStatus("unsubscribed")),
+    deliverability: ratio(delivered, sends.length),
+    openRate: ratio(opened, delivered),
+    clickRate: ratio(clicked, delivered),
+    latencyMedian: median(sends.map((send) => send.latencyMs)),
+  };
+}
+
+export function deltaPercent(current: number, previous: number): number {
+  if (!previous) return 0;
+  return Number(
+    (((current - previous) / previous) * PERCENT).toFixed(DELTA_PRECISION),
+  );
+}
+
+const dayKey = (date: Date): string =>
+  date.toISOString().slice(0, DAY_KEY_LENGTH);
+
+/**
+ * One point per day of the window, counted from the window's own boundaries.
+ *
+ * The DMS period selector cuts on *local* midnights, so a UTC+2 tenant asks for
+ * 2026-09-03T22:00Z → 2026-09-10T21:59:59.999Z. Buckets are therefore offsets
+ * from `from` rather than UTC calendar days, and each is labelled by the date at
+ * its middle, which lands on the tenant's own day for every offset strictly
+ * inside ±12 h — every inhabited zone but UTC+13/+14, where the label falls a
+ * day early. The boundaries alone cannot settle it: local midnight at UTC+13 and
+ * at UTC−11 arrive at the same instant, so the midpoint picks the reading
+ * closest to UTC.
+ *
+ * Counting whole buckets also keeps the last day: cutting the walk at `to` used
+ * to drop it, so a send made today was missing from the chart while the KPI
+ * still counted it.
+ */
+export function dailySeries(
+  sends: MailingSend[],
+  from: Date,
+  to: Date,
+): SeriesPoint[] {
+  const start = from.getTime();
+  const span = to.getTime() - start;
+  const dayCount = Math.max(1, Math.ceil(span / DAY_MS));
+  const counts: number[] = Array.from({ length: dayCount }, () => 0);
+  for (const send of sends) {
+    const offset = new Date(send.createdAt).getTime() - start;
+    if (offset < 0 || offset >= dayCount * DAY_MS) continue;
+    const index = Math.floor(offset / DAY_MS);
+    counts[index] = (counts[index] ?? 0) + 1;
+  }
+  return counts.map((y, index) => ({
+    x: dayKey(new Date(start + index * DAY_MS + DAY_MS / 2)),
+    y,
+  }));
+}
+
+export function domainOf(email: string): string {
+  return email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+}
+
+export function groupBy<T>(
+  items: T[],
+  key: (item: T) => string,
+): Map<string, T[]> {
+  const groups = new Map<string, T[]>();
+  for (const item of items) {
+    const id = key(item);
+    groups.set(id, [...(groups.get(id) ?? []), item]);
+  }
+  return groups;
+}

package/src/services/notify.ts

@@ -0,0 +1,90 @@
+import { Logging } from "@antelopejs/interface-core/logging";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { TenantMemberModel } from "@antelopejs/interface-dms/db";
+import {
+  GeneralSubject,
+  Notification,
+} from "@antelopejs/interface-dms/notifications";
+import type { NotificationData } from "@antelopejs/interface-dms/notifications/types";
+import { PROBLEM_STATUSES, type SendEventType } from "../types";
+
+export interface BounceNotificationInput {
+  sendId: string;
+  templateSlug: string;
+  recipientEmail: string;
+  type: SendEventType;
+}
+
+export interface IdempotentNotificationTarget {
+  toUsersIdempotently(userIds: string[], idempotencyKey: string): Promise<void>;
+}
+
+export interface BounceNotificationData extends NotificationData {
+  linkTo: string;
+  params: Record<string, string | number>;
+}
+
+const SENDS_PROBLEMS_LINK = "/modules/mailing/sends?tab=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";
+
+export function shouldNotify(type: SendEventType): boolean {
+  return PROBLEM_STATUSES.includes(type);
+}
+
+export function bounceNotification(
+  input: BounceNotificationInput,
+): BounceNotificationData {
+  return {
+    icon: BOUNCE_ICON,
+    title: BOUNCE_TITLE,
+    description: BOUNCE_DESCRIPTION,
+    subject: GeneralSubject,
+    linkTo: SENDS_PROBLEMS_LINK,
+    params: { slug: input.templateSlug, email: input.recipientEmail },
+  };
+}
+
+export function bounceIdempotencyKey(input: BounceNotificationInput): string {
+  return `${input.sendId}${IDEMPOTENCY_KEY_SEPARATOR}${input.type}`;
+}
+
+export function deliverBounceNotification(
+  target: IdempotentNotificationTarget,
+  userIds: string[],
+  input: BounceNotificationInput,
+): Promise<void> {
+  return target.toUsersIdempotently(userIds, bounceIdempotencyKey(input));
+}
+
+async function tenantOwnerIds(tenantId: string): Promise<string[]> {
+  const owners = await GetModel(TenantMemberModel, tenantId).listOwners();
+  return owners.map((owner) => owner.userId);
+}
+
+export async function notifyBounce(
+  tenantId: string,
+  input: BounceNotificationInput,
+): Promise<void> {
+  if (!shouldNotify(input.type)) 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);
+  } catch (error) {
+    Logging.Error(
+      `[dms-mailing] Failed to notify the bounce of "${input.recipientEmail}": ${String(error)}`,
+    );
+  }
+}

package/src/services/permissions.ts

@@ -0,0 +1,42 @@
+import { assert } from "@antelopejs/interface-api-util";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { RoleModel, TenantMemberModel } from "@antelopejs/interface-dms/db";
+import {
+  GetEffectiveUserPermissions,
+  HasPermission,
+} from "@antelopejs/interface-dms/permissions";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { HTTP_FORBIDDEN, MAILING_SEND_PERMISSION } from "../constants";
+
+const MISSING_SEND_PERMISSION = "$dms_mailing.errors.missing_send_permission";
+
+/**
+ * Refuses a caller who may read the mailing pages but was not granted
+ * `mailing.send`.
+ *
+ * `@AuthUserWithPermission` only accepts a page, component or action as its
+ * target, and derives the permission from the component tree — it cannot be
+ * pointed at a standalone registered permission. The sends controller is
+ * therefore gated on the page's *read* permission, and the routes that actually
+ * reach recipients add this check on top. It mirrors what the DMS guard does
+ * once it has resolved a permission id.
+ */
+export async function assertSendPermission(
+  user: User,
+  tenantId: string,
+): Promise<void> {
+  const member = await GetModel(TenantMemberModel, tenantId).getByUser(
+    user._id,
+  );
+  const permissions = await GetEffectiveUserPermissions(
+    user,
+    tenantId,
+    member?.roleIds ?? [],
+    GetModel(RoleModel, tenantId),
+  );
+  assert(
+    await HasPermission(permissions, MAILING_SEND_PERMISSION),
+    HTTP_FORBIDDEN,
+    MISSING_SEND_PERMISSION,
+  );
+}

package/src/services/provider.ts

@@ -0,0 +1,46 @@
+import {
+  GetCapabilities,
+  type ProviderCapabilities,
+} from "@antelopejs/interface-email";
+
+/**
+ * How long a capability read stays good. The provider card and the Overview's
+ * attention list both ask on every request, and for a hosted provider
+ * `GetCapabilities` is a network call — but what it answers only changes when
+ * the project is reconfigured, so a short window costs nothing.
+ */
+export const CAPABILITIES_TTL_MS = 60_000;
+
+type CapabilityLoader = () => Promise<ProviderCapabilities>;
+
+interface CacheEntry {
+  at: number;
+  value: ProviderCapabilities | null;
+}
+
+let entry: CacheEntry | undefined;
+
+/** Drops the memo so the next read hits the provider. For tests and teardown. */
+export function resetCapabilitiesCache(): void {
+  entry = undefined;
+}
+
+/**
+ * The provider's capabilities, or `null` when it cannot be reached. A failure
+ * is memoised too: an unreachable provider must not be retried once per request
+ * while the dashboard polls.
+ */
+export async function readCapabilities(
+  load: CapabilityLoader = GetCapabilities,
+  now: number = Date.now(),
+): Promise<ProviderCapabilities | null> {
+  if (entry && now - entry.at < CAPABILITIES_TTL_MS) return entry.value;
+  try {
+    const value = await load();
+    entry = { at: now, value };
+    return value;
+  } catch {
+    entry = { at: now, value: null };
+    return null;
+  }
+}

package/src/services/render.ts

@@ -0,0 +1,33 @@
+import { Logging } from "@antelopejs/interface-core/logging";
+import {
+  GenerateHtml,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+import { getConfig } from "../config";
+import { EMAIL_TEMPLATE_NAME } from "../constants";
+import { renderFallbackHtml } from "../engine";
+import type { ResolvedEmail } from "../types";
+
+/** Props the `EmailMailingTemplate` Vue component receives from the DMS renderer. */
+export interface MailingEmailProps {
+  locale: string;
+  email: ResolvedEmail;
+}
+
+const MailingEmailTemplate =
+  RegisterHtmlTemplate<MailingEmailProps>(EMAIL_TEMPLATE_NAME);
+
+export async function renderEmailHtml(
+  email: ResolvedEmail,
+  locale: string,
+): Promise<string> {
+  if (!getConfig().useHtmlRender) return renderFallbackHtml(email, locale);
+  try {
+    return await GenerateHtml(MailingEmailTemplate, { locale, email });
+  } catch (error) {
+    Logging.Warn(
+      `[dms-mailing] html-render unavailable, using fallback: ${String(error)}`,
+    );
+    return renderFallbackHtml(email, locale);
+  }
+}