@antelopejs/dms-mailing 0.3.3 → 0.4.0

package/src/routes/metrics.ts

@@ -7,10 +7,13 @@ import {
 } from "@antelopejs/interface-api";
 import { assert } 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 { TopListItem } from "@antelopejs/interface-dms/base";
+import type { KpiCardData, TopListItem } from "@antelopejs/interface-dms/base";
+import type { ComposedText } from "@antelopejs/interface-dms/base/types";
 import type { User } from "@antelopejs/interface-dms/auth/db";
 import { API_BASE_PATH, HTTP_NOT_FOUND } from "../constants";
+import { isMarketingCategory } from "../engine";
 import {
   type SendSummary,
   type MailingTemplate,
@@ -19,32 +22,42 @@ import {
 } from "../db";
 import { OverviewPageController } from "../pages/overview";
 import { readCapabilities } from "../services/provider";
-import {
-  buildAttentionItems,
-  type ProviderTracking,
-} from "../services/attention";
+import { trackingOf } from "../services/send-stats";
+import { findSettings } from "../services/settings";
+import { attentionFeedItem, buildAttentionItems } from "../services/attention";
 import {
   aggregate,
+  alignSeries,
   dailySeries,
+  dailyValues,
   deltaPercent,
   domainOf,
   forAudience,
   groupBy,
+  isDeliveryUntracked,
+  leftForProvider,
   ratio,
   readAudience,
   type DateRange,
+  type ProviderTracking,
   type Totals,
+  type TotalsExtractor,
 } from "../services/metrics";
 import { SEND_AUDIENCE_QUERY_KEY, type SendAudience } from "../types";
-import { comparisonRange, currentRange } from "./period";
+import { comparisonRange, currentRange, isComparisonWanted } from "./period";
 
 const UNKNOWN_METRIC = "$dms_mailing.errors.unknown_metric";
-const EDITOR_PATH = "/modules/mailing/editor";
+const TEMPLATES_PATH = "/modules/mailing/templates";
 const MAX_TOP_TEMPLATES = 10;
 const MAX_TOP_DOMAINS = 6;
-const FULL_RATE = 100;
+/** Below this many deliveries a rate swings on a single e-mail: not ranked. */
+export const MIN_RANKED_DELIVERIES = 5;
+const DELIVERED_COUNT_KEY = "$dms_mailing.metrics.delivered_count";
+const TEMPLATE_VOLUME_KEY = "$dms_mailing.metrics.template_volume";
+const FIRST_ROW_OFFSET = 0;
+const SINGLE_ROW = 1;
 
-const KPI_EXTRACTORS: Record<string, (totals: Totals) => number> = {
+const KPI_EXTRACTORS: Record<string, TotalsExtractor> = {
   sends: (totals) => totals.sends,
   deliverability: (totals) => totals.deliverability,
   "open-rate": (totals) => totals.openRate,
@@ -55,20 +68,94 @@ const KPI_EXTRACTORS: Record<string, (totals: Totals) => number> = {
   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,
+/** The KPIs read from delivery events: unmeasured when nothing reports them. */
+const DELIVERY_METRICS = new Set(["deliverability", "open-rate", "click-rate"]);
+
+export interface TopMetric {
+  extract: TotalsExtractor;
+  /** Deliveries a row needs before its value is ranked. */
+  minDeliveries: number;
+}
+
+const TOP_METRICS: Record<string, TopMetric> = {
+  "open-rate": {
+    extract: (totals) => totals.openRate,
+    minDeliveries: MIN_RANKED_DELIVERIES,
+  },
+  "click-rate": {
+    extract: (totals) => totals.clickRate,
+    minDeliveries: MIN_RANKED_DELIVERIES,
+  },
+  sends: { extract: (totals) => totals.sends, minDeliveries: 0 },
 };
+const DEFAULT_TOP_METRIC = TOP_METRICS["open-rate"] as TopMetric;
+
+interface FunnelStepDefinition {
+  id: string;
+  count: (totals: Totals) => number;
+  /** What the step's rate is a share of, the base its KPI uses. */
+  base: (totals: Totals) => number;
+  /** Counted from events the provider reports back. */
+  isDeliveryEvent: boolean;
+}
 
-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],
+const FUNNEL_STEPS: FunnelStepDefinition[] = [
+  {
+    id: "sent",
+    count: (totals) => totals.sends,
+    base: (totals) => totals.sends,
+    isDeliveryEvent: false,
+  },
+  {
+    id: "delivered",
+    count: (totals) => totals.delivered,
+    base: (totals) => totals.sends,
+    isDeliveryEvent: true,
+  },
+  {
+    id: "opened",
+    count: (totals) => totals.opened,
+    base: (totals) => totals.delivered,
+    isDeliveryEvent: true,
+  },
+  {
+    id: "clicked",
+    count: (totals) => totals.clicked,
+    base: (totals) => totals.delivered,
+    isDeliveryEvent: true,
+  },
+  {
+    id: "unsubscribed",
+    count: (totals) => totals.unsubscribed,
+    base: (totals) => totals.delivered,
+    isDeliveryEvent: false,
+  },
 ];
 
+export interface FunnelStepResponse {
+  id: string;
+  label: string;
+  count: number;
+  /** Share of the step's base, as its KPI counts it; `null` on an empty base. */
+  rate: number | null;
+  /** `false` when nothing reports the events the step counts. */
+  isMeasured: boolean;
+}
+
+/** The sends of the window the figures are compared with. */
+export interface ComparedWindow {
+  range: DateRange;
+  sends: SendSummary[];
+}
+
+/** What the Overview's first-run checklist reads. */
+export interface SetupFactsResponse {
+  isProviderConnected: boolean;
+  isSenderSet: boolean;
+  liveTemplateCount: number;
+  hasTestSend: boolean;
+}
+
 export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
   @Context()
   declare ctx: RequestContext;
@@ -82,6 +169,10 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
   @TenantScopedModel(TemplateModel)
   declare templates: TemplateModel;
 
+  private get tenantId(): string {
+    return getRequestTenantId(this.ctx);
+  }
+
   /**
    * Which sends this request describes. Declared by the calling page, never
    * inferred: the Overview asks for the business view, the Sends page for the
@@ -96,73 +187,59 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
     return forAudience(rows, this.audience);
   }
 
+  /** The comparison window and its sends; `null` when the user turned it off. */
+  private async loadComparison(
+    range: DateRange,
+  ): Promise<ComparedWindow | null> {
+    if (!isComparisonWanted(this.ctx)) return null;
+    const previousRange = comparisonRange(this.ctx, range);
+    return { range: previousRange, sends: await this.load(previousRange) };
+  }
+
   @Get("/kpi/:metric")
-  async kpi(@Parameter("metric", "param") metric: string) {
+  async kpi(
+    @Parameter("metric", "param") metric: string,
+  ): Promise<KpiCardData> {
     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([
+    const [current, previous, tracking] = await Promise.all([
       this.load(range),
-      this.load(previousRange),
+      this.loadComparison(range),
+      readTracking(),
     ]);
-    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,
-      ),
-    };
+    if (isUnmeasured(metric, current, tracking)) return {};
+    const previousSends =
+      previous && !isUnmeasured(metric, previous.sends, tracking)
+        ? previous.sends
+        : null;
+    return kpiFigure(extract, current, previousSends, range);
   }
 
   @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),
+      this.loadComparison(range),
     ]);
-    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),
-        },
-      ],
-    };
+    return volumeChart(current, range, previous);
   }
 
   @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 metric =
+      TOP_METRICS[this.ctx.url.searchParams.get("metric") ?? ""] ??
+      DEFAULT_TOP_METRIC;
+    const [sends, templates] = await Promise.all([
+      this.load(currentRange(this.ctx)),
+      this.templates.getAll(),
+    ]);
     const items = [...groupBy(sends, (send) => send.templateSlug)].map(
-      ([slug, rows]) => toTemplateItem(slug, rows, templates, extract),
+      ([slug, rows]) =>
+        toTemplateItem(slug, aggregate(rows), templates, metric),
     );
-    return {
-      items: items
-        .sort((left, right) => right.value - left.value)
-        .slice(0, MAX_TOP_TEMPLATES),
-    };
+    return { items: ranked(items, MAX_TOP_TEMPLATES) };
   }
 
   @Get("/domains")
@@ -170,74 +247,247 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
     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),
-    };
+    ].map(([domain, rows]) => toDomainItem(domain, aggregate(rows)));
+    return { items: ranked(items, MAX_TOP_DOMAINS) };
   }
 
   @Get("/funnel")
   async funnel() {
-    const totals = aggregate(await this.load(currentRange(this.ctx)));
+    const kind = readFunnelKind(this.ctx.url.searchParams.get("kind"));
+    const [sends, templates, tracking] = await Promise.all([
+      this.load(currentRange(this.ctx)),
+      this.templates.getAll(),
+      readTracking(),
+    ]);
+    const kept = filterByKind(sends, templates, kind);
     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),
-      })),
+      steps: funnelSteps(aggregate(kept), isDeliveryUntracked(kept, tracking)),
     };
   }
 
   @Get("/attention")
   async attention() {
     const range = currentRange(this.ctx);
-    const [templates, rows] = await Promise.all([
+    const [templates, rows, tracking, settings] = await Promise.all([
       this.templates.getAll(),
       this.sends.listBetween(range.from, range.to),
+      readTracking(),
+      findSettings(this.tenantId),
     ]);
     const sends = forAudience(rows, this.audience);
     const excluded = rows.filter((row) => !sends.includes(row));
-    const tracking = await readTracking();
+    const items = buildAttentionItems({
+      templates,
+      sends,
+      excluded,
+      windowEnd: range.to,
+      tracking,
+      isSenderSet: Boolean(settings?.senderEmail),
+    });
+    return { items: items.map(attentionFeedItem) };
+  }
+
+  /** The facts behind the Overview's first-run checklist, in one read. */
+  @Get("/setup")
+  async setup(): Promise<SetupFactsResponse> {
+    const [capabilities, templates, settings, testSends] = await Promise.all([
+      readCapabilities(),
+      this.templates.getAll(),
+      findSettings(this.tenantId),
+      this.sends.table
+        .filter((row) => row.key("isTest").eq(true))
+        .slice(FIRST_ROW_OFFSET, SINGLE_ROW)
+        .without("json_variables")
+        .run(),
+    ]);
     return {
-      items: buildAttentionItems({ templates, sends, excluded, tracking }),
+      isProviderConnected: capabilities !== null,
+      isSenderSet: Boolean(settings?.senderEmail),
+      liveTemplateCount: templates.filter(
+        (template) => template.status === "live",
+      ).length,
+      hasTestSend: testSends.length > 0,
     };
   }
 }
 
+/** A figure and its change, each left out when it cannot be stated. */
+export function comparedFigure(
+  value: number | null,
+  previousValue: number | null,
+): KpiCardData {
+  const figure: KpiCardData = {};
+  const delta = deltaPercent(value, previousValue);
+  if (value !== null) figure.value = value;
+  if (previousValue !== null) figure.previousValue = previousValue;
+  if (delta !== null) figure.delta = delta;
+  return figure;
+}
+
+/**
+ * A KPI card's answer: the figure, its change when a comparison window is
+ * read, and the figure's own daily trend as the sparkline.
+ */
+export function kpiFigure(
+  extract: TotalsExtractor,
+  current: SendSummary[],
+  previous: SendSummary[] | null,
+  range: DateRange,
+): KpiCardData {
+  const value = extract(aggregate(current));
+  const previousValue = previous ? extract(aggregate(previous)) : null;
+  return {
+    ...comparedFigure(value, previousValue),
+    sparkline: dailyValues(current, range, extract),
+  };
+}
+
+/**
+ * Whether a window cannot state a delivery KPI: nothing reported deliveries
+ * for its sends. A previous window in that case has nothing to compare.
+ */
+export function isUnmeasured(
+  metric: string,
+  sends: SendSummary[],
+  tracking: ProviderTracking | null,
+): boolean {
+  return DELIVERY_METRICS.has(metric) && isDeliveryUntracked(sends, tracking);
+}
+
+/**
+ * The send volume chart; the comparison series overlaps the current one. A
+ * suppressed send never left, so it is not counted, as in the Sends KPI.
+ */
+export function volumeChart(
+  current: SendSummary[],
+  range: DateRange,
+  previous: ComparedWindow | null,
+) {
+  const sent = current.filter(leftForProvider);
+  const previousSent = previous?.sends.filter(leftForProvider) ?? null;
+  const series = dailySeries(sent, range.from, range.to);
+  const comparison =
+    previous && previousSent
+      ? dailySeries(previousSent, previous.range.from, previous.range.to)
+      : null;
+  return {
+    ...comparedFigure(sent.length, previousSent ? previousSent.length : null),
+    series: [{ name: "$dms_mailing.metrics.sends", data: series }],
+    comparisonSeries: comparison
+      ? [
+          {
+            name: "$dms_mailing.metrics.previous",
+            data: alignSeries(comparison, series),
+          },
+        ]
+      : [],
+  };
+}
+
+export function funnelSteps(
+  totals: Totals,
+  isUntracked: boolean,
+): FunnelStepResponse[] {
+  return FUNNEL_STEPS.map((step) => ({
+    id: step.id,
+    label: `$dms_mailing.funnel.${step.id}`,
+    count: step.count(totals),
+    rate: ratio(step.count(totals), step.base(totals)),
+    isMeasured: !(isUntracked && step.isDeliveryEvent),
+  }));
+}
+
+/** Which sends the funnel counts: all, or one side of the marketing split. */
+export type FunnelKind = "all" | "marketing" | "transactional";
+
+const FUNNEL_KINDS: Record<string, FunnelKind> = {
+  all: "all",
+  marketing: "marketing",
+  transactional: "transactional",
+};
+
+export function readFunnelKind(raw: string | null): FunnelKind {
+  return FUNNEL_KINDS[raw ?? ""] ?? "all";
+}
+
+const KIND_KEEPS: Record<FunnelKind, (category: string) => boolean> = {
+  all: () => true,
+  marketing: (category) => isMarketingCategory(category),
+  transactional: (category) => !isMarketingCategory(category),
+};
+
+/**
+ * Sends of the templates on one side of the split. A template's category
+ * decides: "marketing" is the campaign side, everything else transactional.
+ */
+export function filterByKind(
+  sends: SendSummary[],
+  templates: MailingTemplate[],
+  kind: FunnelKind,
+): SendSummary[] {
+  const categories = new Map(
+    templates.map((template) => [template.slug, template.category ?? ""]),
+  );
+  const keeps = KIND_KEEPS[kind];
+  return sends.filter((send) => keeps(categories.get(send.templateSlug) ?? ""));
+}
+
 /**
  * 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 trackingOf(await readCapabilities());
+}
+
+/** The rows that can be ranked, best first, at most `limit` of them. */
+export function ranked(
+  items: Array<TopListItem | null>,
+  limit: number,
+): TopListItem[] {
+  return items
+    .filter((item): item is TopListItem => item !== null)
+    .sort((left, right) => right.value - left.value)
+    .slice(0, limit);
+}
+
+const deliveredCount = (delivered: number): ComposedText => ({
+  key: DELIVERED_COUNT_KEY,
+  params: { count: { type: "count", value: delivered } },
+});
+
+export function toDomainItem(
+  domain: string,
+  totals: Totals,
+): TopListItem | null {
+  if (totals.openRate === null || totals.delivered < MIN_RANKED_DELIVERIES)
+    return null;
   return {
-    name: capabilities.name,
-    openTracking: capabilities.features.openTracking,
-    clickTracking: capabilities.features.clickTracking,
+    id: domain,
+    title: domain,
+    description: deliveredCount(totals.delivered),
+    value: totals.openRate,
   };
 }
 
-function toTemplateItem(
+export function toTemplateItem(
   slug: string,
-  rows: SendSummary[],
+  totals: Totals,
   templates: MailingTemplate[],
-  extract: (totals: Totals) => number,
-): TopListItem {
+  metric: TopMetric,
+): TopListItem | null {
+  const value = metric.extract(totals);
+  if (value === null || totals.delivered < metric.minDeliveries) return null;
   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,
+    description: {
+      key: TEMPLATE_VOLUME_KEY,
+      params: { slug, count: { type: "count", value: totals.delivered } },
+    },
+    value,
+    to: template ? `${TEMPLATES_PATH}/${template._id}` : undefined,
   };
 }

package/src/routes/period.ts

@@ -1,15 +1,17 @@
 import type { RequestContext } from "@antelopejs/interface-api";
+import { MAX_WINDOW_DAYS } from "../constants";
+import type { DateRange } from "../services/metrics";
 
 /**
  * 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;
+/** The DMS period selector's `comparison` value when the user turned it off. */
+const NO_COMPARISON = "none";
 
 function readQuery(ctx: RangeContext, key: string): string | undefined {
   return ctx.url.searchParams.get(key) ?? undefined;
@@ -21,8 +23,14 @@ function parseDate(raw: string | undefined): Date | undefined {
   return Number.isNaN(parsed.getTime()) ? undefined : parsed;
 }
 
-/** Every window is read from the send log in full, so none may exceed the cap. */
-function clampToMaxWindow(requested: Date, to: Date): DateRange {
+/**
+ * Every window is read from the send log in full, so none may exceed the cap.
+ * Bounds given the wrong way round are swapped: a reversed window is a typo,
+ * not a request for a comparison in the future.
+ */
+function boundedWindow(first: Date, second: Date): DateRange {
+  const [requested, to] =
+    first.getTime() <= second.getTime() ? [first, second] : [second, first];
   const earliest = to.getTime() - MAX_WINDOW_DAYS * DAY_MS;
   const from = requested.getTime() < earliest ? new Date(earliest) : requested;
   return { from, to };
@@ -33,7 +41,16 @@ export function currentRange(ctx: RangeContext): DateRange {
   const requested =
     parseDate(readQuery(ctx, "from")) ??
     new Date(to.getTime() - DEFAULT_WINDOW_DAYS * DAY_MS);
-  return clampToMaxWindow(requested, to);
+  return boundedWindow(requested, to);
+}
+
+/**
+ * Whether the caller compares the window with another one. The DMS period
+ * selector says `comparison=none` when the user turned it off; a caller that
+ * says nothing keeps the previous period.
+ */
+export function isComparisonWanted(ctx: RangeContext): boolean {
+  return readQuery(ctx, "comparison") !== NO_COMPARISON;
 }
 
 export function comparisonRange(
@@ -42,7 +59,7 @@ export function comparisonRange(
 ): DateRange {
   const from = parseDate(readQuery(ctx, "compareFrom"));
   const to = parseDate(readQuery(ctx, "compareTo"));
-  if (from && to) return clampToMaxWindow(from, to);
+  if (from && to) return boundedWindow(from, to);
   const span = current.to.getTime() - current.from.getTime();
   return {
     from: new Date(current.from.getTime() - span),