@antelopejs/dms-mailing 0.6.0 → 0.7.0

package/src/routes/metrics.ts

@@ -23,6 +23,7 @@ import {
 import { OverviewPageController } from "../pages/overview";
 import { readCapabilities } from "../services/provider";
 import { trackingOf } from "../services/send-stats";
+import { localeOfRequest } from "../services/localized-text";
 import { findSettings } from "../services/settings";
 import { attentionFeedItem, buildAttentionItems } from "../services/attention";
 import {
@@ -44,7 +45,12 @@ import {
   type TotalsExtractor,
 } from "../services/metrics";
 import { SEND_AUDIENCE_QUERY_KEY, type SendAudience } from "../types";
-import { comparisonRange, currentRange, isComparisonWanted } from "./period";
+import {
+  comparisonLabel,
+  comparisonRange,
+  currentRange,
+  isComparisonWanted,
+} from "./period";
 
 const UNKNOWN_METRIC = "$dms_mailing.errors.unknown_metric";
 const TEMPLATES_PATH = "/modules/mailing/templates";
@@ -140,12 +146,18 @@ export interface FunnelStepResponse {
   rate: number | null;
   /** `false` when nothing reports the events the step counts. */
   isMeasured: boolean;
+  /** The step's count over the comparison window, when both measure it. */
+  previousCount?: number;
+  /** The change of the count, in percent; absent from an empty comparison. */
+  delta?: number;
 }
 
 /** The sends of the window the figures are compared with. */
 export interface ComparedWindow {
   range: DateRange;
   sends: SendSummary[];
+  /** What the comparison series is called: the previous period, year… */
+  label: string;
 }
 
 /** What the Overview's first-run checklist reads. */
@@ -173,6 +185,13 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
     return getRequestTenantId(this.ctx);
   }
 
+  /** The tenant's templates, their names in the reader's language. */
+  private async namedTemplates(): Promise<MailingTemplate[]> {
+    const locale = localeOfRequest(this.ctx);
+    const templates = await this.templates.getAll();
+    return templates.map((template) => template.localize(locale, ["name"]));
+  }
+
   /**
    * Which sends this request describes. Declared by the calling page, never
    * inferred: the Overview asks for the business view, the Sends page for the
@@ -193,7 +212,11 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
   ): Promise<ComparedWindow | null> {
     if (!isComparisonWanted(this.ctx)) return null;
     const previousRange = comparisonRange(this.ctx, range);
-    return { range: previousRange, sends: await this.load(previousRange) };
+    return {
+      range: previousRange,
+      sends: await this.load(previousRange),
+      label: comparisonLabel(this.ctx),
+    };
   }
 
   @Get("/kpi/:metric")
@@ -231,37 +254,58 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
     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 range = currentRange(this.ctx);
+    const [sends, previous, templates] = await Promise.all([
+      this.load(range),
+      this.loadComparison(range),
+      this.namedTemplates(),
     ]);
-    const items = [...groupBy(sends, (send) => send.templateSlug)].map(
-      ([slug, rows]) =>
-        toTemplateItem(slug, aggregate(rows), templates, metric),
+    const bySlug = (send: SendSummary) => send.templateSlug;
+    const before = previous ? totalsBy(previous.sends, bySlug) : null;
+    const items = [...groupBy(sends, bySlug)].map(([slug, rows]) =>
+      toTemplateItem(
+        slug,
+        aggregate(rows),
+        templates,
+        metric,
+        before?.get(slug),
+      ),
     );
     return { items: ranked(items, 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]) => toDomainItem(domain, aggregate(rows)));
+    const range = currentRange(this.ctx);
+    const [sends, previous] = await Promise.all([
+      this.load(range),
+      this.loadComparison(range),
+    ]);
+    const byDomain = (send: SendSummary) => domainOf(send.recipientEmail);
+    const before = previous ? totalsBy(previous.sends, byDomain) : null;
+    const items = [...groupBy(sends, byDomain)].map(([domain, rows]) =>
+      toDomainItem(domain, aggregate(rows), before?.get(domain)),
+    );
     return { items: ranked(items, MAX_TOP_DOMAINS) };
   }
 
   @Get("/funnel")
   async funnel() {
     const kind = readFunnelKind(this.ctx.url.searchParams.get("kind"));
-    const [sends, templates, tracking] = await Promise.all([
-      this.load(currentRange(this.ctx)),
-      this.templates.getAll(),
+    const range = currentRange(this.ctx);
+    const [sends, previous, templates, tracking] = await Promise.all([
+      this.load(range),
+      this.loadComparison(range),
+      this.namedTemplates(),
       readTracking(),
     ]);
-    const kept = filterByKind(sends, templates, kind);
+    const funnelOf = (rows: SendSummary[]): FunnelStepResponse[] => {
+      const kept = filterByKind(rows, templates, kind);
+      return funnelSteps(aggregate(kept), isDeliveryUntracked(kept, tracking));
+    };
+    const steps = funnelOf(sends);
     return {
-      steps: funnelSteps(aggregate(kept), isDeliveryUntracked(kept, tracking)),
+      steps: previous ? comparedSteps(steps, funnelOf(previous.sends)) : steps,
     };
   }
 
@@ -269,7 +313,7 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
   async attention() {
     const range = currentRange(this.ctx);
     const [templates, rows, tracking, settings] = await Promise.all([
-      this.templates.getAll(),
+      this.namedTemplates(),
       this.sends.listBetween(range.from, range.to),
       readTracking(),
       findSettings(this.tenantId),
@@ -292,7 +336,7 @@ export class MetricsController extends Controller(`${API_BASE_PATH}/metrics`) {
   async setup(): Promise<SetupFactsResponse> {
     const [capabilities, templates, settings, testSends] = await Promise.all([
       readCapabilities(),
-      this.templates.getAll(),
+      this.namedTemplates(),
       findSettings(this.tenantId),
       this.sends.table
         .filter((row) => row.key("isTest").eq(true))
@@ -366,21 +410,22 @@ export function volumeChart(
   const sent = current.filter(leftForProvider);
   const previousSent = previous?.sends.filter(leftForProvider) ?? null;
   const series = dailySeries(sent, range.from, range.to);
-  const comparison =
+  const comparisonSeries =
     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),
+            name: previous.label,
+            data: alignSeries(
+              dailySeries(previousSent, previous.range.from, previous.range.to),
+              series,
+            ),
           },
         ]
-      : [],
+      : [];
+  return {
+    ...comparedFigure(sent.length, previousSent ? previousSent.length : null),
+    series: [{ name: "$dms_mailing.metrics.sends", data: series }],
+    comparisonSeries,
   };
 }
 
@@ -397,6 +442,28 @@ export function funnelSteps(
   }));
 }
 
+/**
+ * The steps with their count over the comparison window, step by step. A step
+ * either window does not measure states no comparison: a zero there would
+ * read as a fall that never happened.
+ */
+export function comparedSteps(
+  current: FunnelStepResponse[],
+  previous: FunnelStepResponse[],
+): FunnelStepResponse[] {
+  return current.map((step) => {
+    const before = previous.find((candidate) => candidate.id === step.id);
+    if (!step.isMeasured || !before?.isMeasured) return step;
+    const compared: FunnelStepResponse = {
+      ...step,
+      previousCount: before.count,
+    };
+    const delta = deltaPercent(step.count, before.count);
+    if (delta !== null) compared.delta = delta;
+    return compared;
+  });
+}
+
 /** Which sends the funnel counts: all, or one side of the marketing split. */
 export type FunnelKind = "all" | "marketing" | "transactional";
 
@@ -441,6 +508,35 @@ async function readTracking(): Promise<ProviderTracking | null> {
   return trackingOf(await readCapabilities());
 }
 
+/** The totals of each group of sends, by the key `keyOf` gives a send. */
+export function totalsBy(
+  sends: SendSummary[],
+  keyOf: (send: SendSummary) => string,
+): Map<string, Totals> {
+  return new Map(
+    [...groupBy(sends, keyOf)].map(([key, rows]) => [key, aggregate(rows)]),
+  );
+}
+
+/**
+ * A ranked row's change against the comparison window: `null` when the row
+ * had too few deliveries there to be ranked, its figure being then a guess.
+ */
+export function rowDelta(
+  value: number,
+  previous: Totals | undefined,
+  metric: TopMetric,
+): number | null {
+  if (!previous || previous.delivered < metric.minDeliveries) return null;
+  return deltaPercent(value, metric.extract(previous));
+}
+
+/** The row with its change; with none to state, the row carries no delta. */
+function withDelta(item: TopListItem, delta: number | null): TopListItem {
+  if (delta !== null) item.delta = delta;
+  return item;
+}
+
 /** The rows that can be ranked, best first, at most `limit` of them. */
 export function ranked(
   items: Array<TopListItem | null>,
@@ -457,37 +553,54 @@ const deliveredCount = (delivered: number): ComposedText => ({
   params: { count: { type: "count", value: delivered } },
 });
 
+/** The domains are ranked on their open rate, as the templates by default. */
+const DOMAIN_METRIC = DEFAULT_TOP_METRIC;
+
+/**
+ * A domain's row. `previous`, its totals over the comparison window when the
+ * toolbar compares, gives the row its change.
+ */
 export function toDomainItem(
   domain: string,
   totals: Totals,
+  previous?: Totals,
 ): TopListItem | null {
-  if (totals.openRate === null || totals.delivered < MIN_RANKED_DELIVERIES)
+  const value = DOMAIN_METRIC.extract(totals);
+  if (value === null || totals.delivered < DOMAIN_METRIC.minDeliveries)
     return null;
-  return {
-    id: domain,
-    title: domain,
-    description: deliveredCount(totals.delivered),
-    value: totals.openRate,
-  };
+  return withDelta(
+    {
+      id: domain,
+      title: domain,
+      description: deliveredCount(totals.delivered),
+      value,
+    },
+    rowDelta(value, previous, DOMAIN_METRIC),
+  );
 }
 
+/** A template's row, its change read from `previous` as a domain's. */
 export function toTemplateItem(
   slug: string,
   totals: Totals,
   templates: MailingTemplate[],
   metric: TopMetric,
+  previous?: Totals,
 ): 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: {
-      key: TEMPLATE_VOLUME_KEY,
-      params: { slug, count: { type: "count", value: totals.delivered } },
+  return withDelta(
+    {
+      id: slug,
+      title: template?.name ?? slug,
+      description: {
+        key: TEMPLATE_VOLUME_KEY,
+        params: { slug, count: { type: "count", value: totals.delivered } },
+      },
+      value,
+      to: template ? `${TEMPLATES_PATH}/${template._id}` : undefined,
     },
-    value,
-    to: template ? `${TEMPLATES_PATH}/${template._id}` : undefined,
-  };
+    rowDelta(value, previous, metric),
+  );
 }

package/src/routes/period.ts

@@ -12,6 +12,17 @@ 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";
+const PREVIOUS_YEAR = "previous-year";
+
+/**
+ * What the comparison series is called, by the selector's `comparison`. A
+ * custom window, or a caller naming none, is neither of the two.
+ */
+const COMPARISON_SERIES_LABELS: Record<string, string> = {
+  "previous-period": "$dms_mailing.metrics.previous",
+  [PREVIOUS_YEAR]: "$dms_mailing.metrics.previous_year",
+};
+const COMPARED_SERIES_LABEL = "$dms_mailing.metrics.compared";
 
 function readQuery(ctx: RangeContext, key: string): string | undefined {
   return ctx.url.searchParams.get(key) ?? undefined;
@@ -53,6 +64,24 @@ export function isComparisonWanted(ctx: RangeContext): boolean {
   return readQuery(ctx, "comparison") !== NO_COMPARISON;
 }
 
+/** The label of the comparison series, for the comparison the caller asks. */
+export function comparisonLabel(ctx: RangeContext): string {
+  const comparison = readQuery(ctx, "comparison") ?? "previous-period";
+  return COMPARISON_SERIES_LABELS[comparison] ?? COMPARED_SERIES_LABEL;
+}
+
+function yearBefore(date: Date): Date {
+  const shifted = new Date(date.getTime());
+  shifted.setUTCFullYear(shifted.getUTCFullYear() - 1);
+  return shifted;
+}
+
+/**
+ * The window the current one is compared with. The DMS selector resolves it
+ * itself and sends `compareFrom` / `compareTo`, for the previous year as for
+ * the previous period; a caller sending only `comparison` gets the same
+ * window a year back, or the equal-length span just before.
+ */
 export function comparisonRange(
   ctx: RangeContext,
   current: DateRange,
@@ -60,6 +89,9 @@ export function comparisonRange(
   const from = parseDate(readQuery(ctx, "compareFrom"));
   const to = parseDate(readQuery(ctx, "compareTo"));
   if (from && to) return boundedWindow(from, to);
+  if (readQuery(ctx, "comparison") === PREVIOUS_YEAR) {
+    return { from: yearBefore(current.from), to: yearBefore(current.to) };
+  }
   const span = current.to.getTime() - current.from.getTime();
   return {
     from: new Date(current.from.getTime() - span),

package/src/routes/sends.ts

@@ -35,9 +35,10 @@ import {
   SendModel,
   TemplateModel,
 } from "../db";
-import { resolveEmail } from "../engine";
+import { resolveEmail, valueFormatOf } from "../engine";
 import type { InterpolationMode } from "../engine/tokens";
 import { SendsPageController } from "../pages/sends";
+import { localeOfRequest } from "../services/localized-text";
 import { readCapabilities } from "../services/provider";
 import { buildProviderBanner } from "../services/provider-banner";
 import { renderEmailHtml } from "../services/render";
@@ -65,6 +66,7 @@ import {
   pickLocale,
   publishedVersionOf,
   requireTemplate,
+  snapshotOfVersion,
 } from "../services/templates";
 import type {
   SendStatus,
@@ -383,7 +385,9 @@ export class SendsController extends Controller(API_BASE_PATH) {
     return {
       send,
       events,
-      template: template ? summarize(template) : null,
+      template: template
+        ? summarize(template.localize(localeOfRequest(this.ctx), ["name"]))
+        : null,
       suppression,
     };
   }
@@ -396,7 +400,7 @@ export class SendsController extends Controller(API_BASE_PATH) {
   async html(@Parameter("id", "param") id: string): Promise<SendHtmlResponse> {
     const send = await this.requireSend(id);
     const template = await requireTemplate(this.templates, send.templateId);
-    const content = await contentOfVersion(
+    const { content, variables } = await snapshotOfVersion(
       this.tenantId,
       template,
       send.templateVersion,
@@ -405,7 +409,12 @@ export class SendsController extends Controller(API_BASE_PATH) {
     const locale = pickLocale(content, send.locale, settings.fallbackLocale);
     const localeContent = localeContentOf(content, locale);
     assert(localeContent, HTTP_UNPROCESSABLE, INVALID_CONTENT);
-    const email = resolveEmail(localeContent, variablesOf(send), SEND_MODE);
+    const email = resolveEmail(
+      localeContent,
+      variablesOf(send),
+      SEND_MODE,
+      valueFormatOf(locale, variables),
+    );
     const version = send.templateVersion;
     return {
       html: await renderEmailHtml(email, locale),

package/src/routes/settings.ts

@@ -71,7 +71,11 @@ const retentionDaysSchema = z.coerce
   .min(MIN_RETENTION_DAYS)
   .max(MAX_RETENTION_DAYS);
 
-/** The settings as the form reads them, with the values derived for display. */
+/**
+ * The settings as the form reads them, with the values derived for display.
+ * The DMS form reads and writes localized values whole
+ * (`x-content-language: *`): category labels travel with every language.
+ */
 export interface MailingSettingsResponse extends MailingSettingsValues {
   /** Where the provider posts its events; read-only. */
   webhookUrl: string;
@@ -217,14 +221,13 @@ export class MailingSettingsController extends Controller(
    */
   @Put("")
   async update(@RawBody() raw: Buffer): Promise<SettingsWriteResponse> {
-    const patch = this.readPatch(raw);
+    const { categories: entries, ...patch } = this.readPatch(raw);
     const current = await getSettings(this.tenantId);
     const merged = mergeSettingsPatch(current, patch);
-    const entries = patch.categories ?? current.categories;
-    const values = { ...merged, categories: keptCategories(entries) };
-    const saved = await saveSettings(this.tenantId, values);
-    const reassigned = patch.categories
-      ? await this.reassignCategories(values.categories, categoryMoves(entries))
+    const categories = entries ? keptCategories(entries) : current.categories;
+    const saved = await saveSettings(this.tenantId, { ...merged, categories });
+    const reassigned = entries
+      ? await this.reassignCategories(categories, categoryMoves(entries))
       : 0;
     const [notice] = [...reassignedNotice(reassigned), ...senderNotice(saved)];
     return { ...saved, ...(notice && { notice }) };
@@ -324,7 +327,7 @@ export class MailingSettingsController extends Controller(
     const templates = await this.templates.getAll();
     const changes = reassignRemovedCategories(templates, categories, moves);
     for (const { templateId, category } of changes) {
-      await this.templates.update(templateId, { category });
+      await this.templates.updateFields(templateId, { category });
     }
     return changes.length;
   }