@antelopejs/dms-mailing 0.2.2

package/src/realtime.ts

@@ -0,0 +1,53 @@
+import type { ControllerClass } from "@antelopejs/interface-api";
+import { GetMetadata } from "@antelopejs/interface-core";
+import { Logging } from "@antelopejs/interface-core/logging";
+import { PageMetadata } from "@antelopejs/interface-dms/page";
+import {
+  PublishMessage,
+  RegisterPageTopic,
+} from "@antelopejs/interface-dms/realtime";
+import { MAILING_SENDS_TOPIC, TABLES_BASE_PATH } from "./constants";
+import { OverviewPageController } from "./pages/overview";
+import { SendsPageController } from "./pages/sends";
+
+const SENDS_ROW_TOPIC = `tableview:row:${TABLES_BASE_PATH}/sends`;
+const SEND_CREATED_TYPE = "created";
+const SEND_UPDATED_TYPE = "updated";
+
+const TOPIC_PAGES: ControllerClass[] = [
+  SendsPageController,
+  OverviewPageController,
+];
+
+export function realtimePageIds(): string[] {
+  return TOPIC_PAGES.map(
+    (page) => GetMetadata(page, PageMetadata).pageInfo?.fullId ?? "",
+  ).filter((fullId) => fullId.length > 0);
+}
+
+export function registerRealtimeTopics(): void {
+  for (const pageId of realtimePageIds()) {
+    RegisterPageTopic(pageId, MAILING_SENDS_TOPIC);
+  }
+}
+
+function publishSendChange(type: string, sendId: string): void {
+  const payload = { ids: [sendId] };
+  void Promise.all([
+    PublishMessage(SENDS_ROW_TOPIC, type, { payload }),
+    PublishMessage(MAILING_SENDS_TOPIC, type, { payload }),
+  ]).catch((error: unknown) => {
+    Logging.Error(
+      `[dms-mailing] Failed to publish "${type}" for send "${sendId}":`,
+      error,
+    );
+  });
+}
+
+export function publishSendCreated(sendId: string): void {
+  publishSendChange(SEND_CREATED_TYPE, sendId);
+}
+
+export function publishSendUpdated(sendId: string): void {
+  publishSendChange(SEND_UPDATED_TYPE, sendId);
+}

package/src/routes/events.ts

@@ -0,0 +1,57 @@
+import {
+  Context,
+  Controller,
+  JSONBody,
+  Parameter,
+  Post,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assert, assertValidation } from "@antelopejs/interface-api-util";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import { z } from "zod";
+import { API_BASE_PATH, HTTP_FORBIDDEN } from "../constants";
+import { recordEmailEvent, webhookSecretMatches } from "../services/events";
+import { getSettings } from "../services/settings";
+import { SEND_STATUSES, type SendStatus } from "../types";
+
+const SECRET_HEADER = "x-mailing-webhook-secret";
+const BAD_SECRET = "$dms_mailing.errors.bad_webhook_secret";
+
+const eventSchema = z.object({
+  messageId: z.string().min(1),
+  type: z.enum(SEND_STATUSES as [SendStatus, ...SendStatus[]]),
+  at: z.coerce.date().optional(),
+  details: z.record(z.unknown()).optional(),
+  tenantId: z.string().optional(),
+});
+
+export class MailingEventsController extends Controller(
+  `${API_BASE_PATH}/events`,
+) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @Post("/:provider")
+  async receive(
+    @Parameter("provider", "param") provider: string,
+    @Parameter(SECRET_HEADER, "header") secret: string | undefined,
+    @JSONBody() body: unknown,
+  ) {
+    const event = assertValidation(body, (value) => eventSchema.parse(value));
+    const tenantId = event.tenantId ?? getRequestTenantId(this.ctx);
+    const settings = await getSettings(tenantId);
+    assert(
+      webhookSecretMatches(secret, settings.webhookSecret),
+      HTTP_FORBIDDEN,
+      BAD_SECRET,
+    );
+    const recorded = await recordEmailEvent(tenantId, {
+      provider,
+      messageId: event.messageId,
+      type: event.type,
+      at: event.at,
+      details: event.details,
+    });
+    return { recorded };
+  }
+}

package/src/routes/index.ts

@@ -0,0 +1,7 @@
+export * from "./events";
+export * from "./metrics";
+export * from "./period";
+export * from "./provider";
+export * from "./sends";
+export * from "./settings";
+export * from "./templates";

package/src/routes/metrics.ts

@@ -0,0 +1,243 @@
+import {
+  Context,
+  Controller,
+  Get,
+  Parameter,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { assert } from "@antelopejs/interface-api-util";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import type { TopListItem } from "@antelopejs/interface-dms/base";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { API_BASE_PATH, HTTP_NOT_FOUND } from "../constants";
+import {
+  type MailingSend,
+  type MailingTemplate,
+  SendModel,
+  TemplateModel,
+} from "../db";
+import { OverviewPageController } from "../pages/overview";
+import { readCapabilities } from "../services/provider";
+import {
+  buildAttentionItems,
+  type ProviderTracking,
+} from "../services/attention";
+import {
+  aggregate,
+  dailySeries,
+  deltaPercent,
+  domainOf,
+  forAudience,
+  groupBy,
+  ratio,
+  readAudience,
+  type DateRange,
+  type Totals,
+} from "../services/metrics";
+import { SEND_AUDIENCE_QUERY_KEY, type SendAudience } from "../types";
+import { comparisonRange, currentRange } from "./period";
+
+const UNKNOWN_METRIC = "$dms_mailing.errors.unknown_metric";
+const EDITOR_PATH = "/modules/mailing/editor";
+const MAX_TOP_TEMPLATES = 10;
+const MAX_TOP_DOMAINS = 6;
+const FULL_RATE = 100;
+
+const KPI_EXTRACTORS: Record<string, (totals: Totals) => number> = {
+  sends: (totals) => totals.sends,
+  deliverability: (totals) => totals.deliverability,
+  "open-rate": (totals) => totals.openRate,
+  "click-rate": (totals) => totals.clickRate,
+  bounces: (totals) => totals.bounced,
+  unsubscribes: (totals) => totals.unsubscribed,
+  queued: (totals) => totals.queued,
+  latency: (totals) => totals.latencyMedian,
+};
+
+const TOP_METRICS: Record<string, (totals: Totals) => number> = {
+  "open-rate": (totals) => totals.openRate,
+  "click-rate": (totals) => totals.clickRate,
+  sends: (totals) => totals.sends,
+};
+
+const FUNNEL_STEPS: Array<[string, (totals: Totals) => number]> = [
+  ["sent", (totals) => totals.sends],
+  ["delivered", (totals) => totals.delivered],
+  ["opened", (totals) => totals.opened],
+  ["clicked", (totals) => totals.clicked],
+  ["unsubscribed", (totals) => totals.unsubscribed],
+];
+
+export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(OverviewPageController)
+  declare user: User;
+
+  @TenantScopedModel(SendModel)
+  declare sends: SendModel;
+
+  @TenantScopedModel(TemplateModel)
+  declare templates: TemplateModel;
+
+  /**
+   * Which sends this request describes. Declared by the calling page, never
+   * inferred: the Overview asks for the business view, the Sends page for the
+   * operational one.
+   */
+  private get audience(): SendAudience {
+    return readAudience(this.ctx.url.searchParams.get(SEND_AUDIENCE_QUERY_KEY));
+  }
+
+  private async load(range: DateRange): Promise<MailingSend[]> {
+    const rows = await this.sends.listBetween(range.from, range.to);
+    return forAudience(rows, this.audience);
+  }
+
+  @Get("/kpi/:metric")
+  async kpi(@Parameter("metric", "param") metric: string) {
+    const extract = KPI_EXTRACTORS[metric];
+    assert(extract, HTTP_NOT_FOUND, UNKNOWN_METRIC);
+    const range = currentRange(this.ctx);
+    const previousRange = comparisonRange(this.ctx, range);
+    const [current, previous] = await Promise.all([
+      this.load(range),
+      this.load(previousRange),
+    ]);
+    const value = extract(aggregate(current));
+    const previousValue = extract(aggregate(previous));
+    return {
+      value,
+      previousValue,
+      delta: deltaPercent(value, previousValue),
+      sparkline: dailySeries(current, range.from, range.to).map(
+        (point) => point.y,
+      ),
+    };
+  }
+
+  @Get("/volume")
+  async volume() {
+    const range = currentRange(this.ctx);
+    const previousRange = comparisonRange(this.ctx, range);
+    const [current, previous] = await Promise.all([
+      this.load(range),
+      this.load(previousRange),
+    ]);
+    const totals = aggregate(current);
+    const previousTotals = aggregate(previous);
+    return {
+      value: totals.sends,
+      previousValue: previousTotals.sends,
+      delta: deltaPercent(totals.sends, previousTotals.sends),
+      series: [
+        {
+          name: "$dms_mailing.metrics.sends",
+          data: dailySeries(current, range.from, range.to),
+        },
+      ],
+      comparisonSeries: [
+        {
+          name: "$dms_mailing.metrics.previous",
+          data: dailySeries(previous, previousRange.from, previousRange.to),
+        },
+      ],
+    };
+  }
+
+  @Get("/top-templates")
+  async topTemplates() {
+    const metric = this.ctx.url.searchParams.get("metric") ?? "open-rate";
+    const extract =
+      TOP_METRICS[metric] ??
+      (TOP_METRICS["open-rate"] as (totals: Totals) => number);
+    const sends = await this.load(currentRange(this.ctx));
+    const templates = await this.templates.getAll();
+    const items = [...groupBy(sends, (send) => send.templateSlug)].map(
+      ([slug, rows]) => toTemplateItem(slug, rows, templates, extract),
+    );
+    return {
+      items: items
+        .sort((left, right) => right.value - left.value)
+        .slice(0, MAX_TOP_TEMPLATES),
+    };
+  }
+
+  @Get("/domains")
+  async domains() {
+    const sends = await this.load(currentRange(this.ctx));
+    const items = [
+      ...groupBy(sends, (send) => domainOf(send.recipientEmail)),
+    ].map(([domain, rows]) => ({
+      id: domain,
+      title: domain,
+      value: aggregate(rows).openRate,
+    }));
+    return {
+      items: items
+        .sort((left, right) => right.value - left.value)
+        .slice(0, MAX_TOP_DOMAINS),
+    };
+  }
+
+  @Get("/funnel")
+  async funnel() {
+    const totals = aggregate(await this.load(currentRange(this.ctx)));
+    return {
+      steps: FUNNEL_STEPS.map(([id, extract]) => ({
+        id,
+        label: `$dms_mailing.funnel.${id}`,
+        count: extract(totals),
+        rate: id === "sent" ? FULL_RATE : ratio(extract(totals), totals.sends),
+      })),
+    };
+  }
+
+  @Get("/attention")
+  async attention() {
+    const range = currentRange(this.ctx);
+    const [templates, rows] = await Promise.all([
+      this.templates.getAll(),
+      this.sends.listBetween(range.from, range.to),
+    ]);
+    const sends = forAudience(rows, this.audience);
+    const excluded = rows.filter((row) => !sends.includes(row));
+    const tracking = await readTracking();
+    return {
+      items: buildAttentionItems({ templates, sends, excluded, tracking }),
+    };
+  }
+}
+
+/**
+ * What the provider says it can report. An unreachable provider yields `null`
+ * rather than an error: the Overview keeps its other notices, and the provider
+ * card is the one that reports the outage.
+ */
+async function readTracking(): Promise<ProviderTracking | null> {
+  const capabilities = await readCapabilities();
+  if (!capabilities) return null;
+  return {
+    name: capabilities.name,
+    openTracking: capabilities.features.openTracking,
+    clickTracking: capabilities.features.clickTracking,
+  };
+}
+
+function toTemplateItem(
+  slug: string,
+  rows: MailingSend[],
+  templates: MailingTemplate[],
+  extract: (totals: Totals) => number,
+): TopListItem {
+  const template = templates.find((candidate) => candidate.slug === slug);
+  return {
+    id: slug,
+    title: template?.name ?? slug,
+    description: slug,
+    value: extract(aggregate(rows)),
+    to: template ? `${EDITOR_PATH}?id=${template._id}` : undefined,
+  };
+}

package/src/routes/period.ts

@@ -0,0 +1,46 @@
+import type { RequestContext } from "@antelopejs/interface-api";
+
+/**
+ * Both readers only ever touch the query string, so they ask for that slice
+ * rather than the whole request: a full `RequestContext` still satisfies it.
+ */
+export type RangeContext = Pick<RequestContext, "url">;
+import { MAX_WINDOW_DAYS } from "../constants";
+import type { DateRange } from "../services/metrics";
+
+const DAY_MS = 86_400_000;
+const DEFAULT_WINDOW_DAYS = 30;
+
+function readQuery(ctx: RangeContext, key: string): string | undefined {
+  return ctx.url.searchParams.get(key) ?? undefined;
+}
+
+function parseDate(raw: string | undefined): Date | undefined {
+  if (!raw) return undefined;
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+
+export function currentRange(ctx: RangeContext): DateRange {
+  const to = parseDate(readQuery(ctx, "to")) ?? new Date();
+  const requested =
+    parseDate(readQuery(ctx, "from")) ??
+    new Date(to.getTime() - DEFAULT_WINDOW_DAYS * DAY_MS);
+  const earliest = to.getTime() - MAX_WINDOW_DAYS * DAY_MS;
+  const from = requested.getTime() < earliest ? new Date(earliest) : requested;
+  return { from, to };
+}
+
+export function comparisonRange(
+  ctx: RangeContext,
+  current: DateRange,
+): DateRange {
+  const from = parseDate(readQuery(ctx, "compareFrom"));
+  const to = parseDate(readQuery(ctx, "compareTo"));
+  if (from && to) return { from, to };
+  const span = current.to.getTime() - current.from.getTime();
+  return {
+    from: new Date(current.from.getTime() - span),
+    to: new Date(current.from.getTime()),
+  };
+}

package/src/routes/provider.ts

@@ -0,0 +1,31 @@
+import { Controller, Get } from "@antelopejs/interface-api";
+import type { ProviderFeatures } from "@antelopejs/interface-email";
+import { readCapabilities } from "../services/provider";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { API_BASE_PATH } from "../constants";
+import { OverviewPageController } from "../pages/overview";
+
+export interface ProviderResponse {
+  name: string;
+  connected: boolean;
+  features: ProviderFeatures | null;
+}
+
+export class MailingProviderController extends Controller(
+  `${API_BASE_PATH}/provider`,
+) {
+  @AuthUserWithPermission(OverviewPageController)
+  declare user: User;
+
+  @Get("")
+  async describe(): Promise<ProviderResponse> {
+    const capabilities = await readCapabilities();
+    if (!capabilities) return { name: "", connected: false, features: null };
+    return {
+      name: capabilities.name,
+      connected: true,
+      features: capabilities.features,
+    };
+  }
+}

package/src/routes/sends.ts

@@ -0,0 +1,215 @@
+import {
+  Context,
+  Controller,
+  Get,
+  HTTPResult,
+  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_NOT_FOUND,
+  HTTP_UNPROCESSABLE,
+} from "../constants";
+import {
+  type MailingSend,
+  type MailingSendEvent,
+  SendEventModel,
+  SendModel,
+  TemplateModel,
+} from "../db";
+import { resolveEmail } from "../engine";
+import type {
+  SendTemplateParams,
+  SendTemplateResult,
+} from "@antelopejs/interface-dms-mailing";
+import { SendsPageController } from "../pages/sends";
+import { renderEmailHtml } from "../services/render";
+import { SendError, sendTemplate } from "../services/send";
+import { assertSendPermission } from "../services/permissions";
+import { getSettings } from "../services/settings";
+import {
+  localeContentOf,
+  parseContent,
+  pickLocale,
+} from "../services/templates";
+import type { TemplateContent } from "../types";
+import { realSendSchema, testSendSchema } from "../validation/templates.schema";
+
+const NOT_FOUND = "$dms_mailing.errors.send_not_found";
+const TEMPLATE_NOT_FOUND = "$dms_mailing.errors.template_not_found";
+const TEMPLATE_GONE = "$dms_mailing.errors.template_not_found";
+const INVALID_CONTENT = "$dms_mailing.errors.invalid_content";
+const TEST_SEND_SOURCE = "dms-mailing:test-send";
+const REPLAY_SOURCE = "dms-mailing:replay";
+const MANUAL_SEND_SOURCE = "dms-mailing:manual";
+
+interface TestSendInput {
+  locale: string;
+  content?: TemplateContent;
+  data?: Record<string, unknown>;
+}
+
+export interface SendDetailResponse {
+  send: MailingSend;
+  events: MailingSendEvent[];
+}
+
+export class SendsController extends Controller(API_BASE_PATH) {
+  @Context()
+  declare ctx: RequestContext;
+
+  @AuthUserWithPermission(SendsPageController)
+  declare user: User;
+
+  @TenantScopedModel(SendModel)
+  declare sends: SendModel;
+
+  @TenantScopedModel(SendEventModel)
+  declare events: SendEventModel;
+
+  @TenantScopedModel(TemplateModel)
+  declare templates: TemplateModel;
+
+  private get tenantId(): string {
+    return getRequestTenantId(this.ctx);
+  }
+
+  private async requireSend(id: string): Promise<MailingSend> {
+    const send = await this.sends.get(id);
+    assert(send, HTTP_NOT_FOUND, NOT_FOUND);
+    return send;
+  }
+
+  @Post("/templates/:id/test-send")
+  async testSend(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    await assertSendPermission(this.user, this.tenantId);
+    const input = assertValidation(
+      body,
+      (value) => testSendSchema.parse(value),
+      () => INVALID_CONTENT,
+    );
+    const template = await this.templates.get(id);
+    assert(template, HTTP_NOT_FOUND, TEMPLATE_NOT_FOUND);
+    const result = await this.send(
+      {
+        tenantId: this.tenantId,
+        to: input.to,
+        locale: (input as TestSendInput).locale,
+        variables: (input as TestSendInput).data,
+        content: (input as TestSendInput).content,
+        isTest: true,
+        source: TEST_SEND_SOURCE,
+      },
+      template.slug,
+    );
+    return { results: result.results ?? [result] };
+  }
+
+  /**
+   * A genuine send: it reaches real recipients and counts in the business
+   * figures. `prepareSend` refuses anything but a live template.
+   */
+  @Post("/templates/:id/send")
+  async realSend(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    await assertSendPermission(this.user, this.tenantId);
+    const input = assertValidation(
+      body,
+      (value) => realSendSchema.parse(value),
+      () => INVALID_CONTENT,
+    );
+    const template = await this.templates.get(id);
+    assert(template, HTTP_NOT_FOUND, TEMPLATE_NOT_FOUND);
+    const result = await this.send(
+      {
+        tenantId: this.tenantId,
+        to: input.to,
+        locale: input.locale,
+        variables: input.data,
+        isTest: false,
+        source: MANUAL_SEND_SOURCE,
+      },
+      template.slug,
+    );
+    return { results: result.results ?? [result] };
+  }
+
+  @Get("/sends/:id")
+  async detail(
+    @Parameter("id", "param") id: string,
+  ): Promise<SendDetailResponse> {
+    const send = await this.requireSend(id);
+    const events = await this.events.getBySend(id);
+    events.sort((left, right) => left.at.getTime() - right.at.getTime());
+    return { send, events };
+  }
+
+  @Get("/sends/:id/html")
+  async html(@Parameter("id", "param") id: string) {
+    const send = await this.requireSend(id);
+    // There is no version history: this re-renders the template as it stands
+    // today, which may differ from what actually went out.
+    const template = await this.templates.get(send.templateId);
+    assert(template, HTTP_NOT_FOUND, TEMPLATE_GONE);
+    const content = parseContent(template);
+    const settings = await getSettings(this.tenantId);
+    const locale = pickLocale(content, send.locale, settings.fallbackLocale);
+    const localeContent = localeContentOf(content, locale);
+    assert(localeContent, HTTP_UNPROCESSABLE, INVALID_CONTENT);
+    const email = resolveEmail(
+      localeContent,
+      JSON.parse(send.json_variables || "{}") as Record<string, unknown>,
+    );
+    return { html: await renderEmailHtml(email, locale) };
+  }
+
+  @Post("/sends/:id/replay")
+  async replay(@Parameter("id", "param") id: string) {
+    await assertSendPermission(this.user, this.tenantId);
+    const send = await this.requireSend(id);
+    return this.send(
+      {
+        tenantId: this.tenantId,
+        to: send.recipientEmail,
+        locale: send.locale,
+        variables: JSON.parse(send.json_variables || "{}") as Record<
+          string,
+          unknown
+        >,
+        isTest: send.isTest,
+        source: REPLAY_SOURCE,
+      },
+      send.templateSlug,
+    );
+  }
+
+  private async send(
+    params: SendTemplateParams,
+    slug: string,
+  ): Promise<SendTemplateResult> {
+    try {
+      return await sendTemplate(slug, params);
+    } catch (error) {
+      if (error instanceof SendError) {
+        throw new HTTPResult(
+          HTTP_UNPROCESSABLE,
+          `$dms_mailing.errors.${error.code}`,
+        );
+      }
+      throw error;
+    }
+  }
+}