@antelopejs/dms-mailing 0.6.0 → 0.7.0

package/src/routes/templates.ts

@@ -5,6 +5,7 @@ import {
   JSONBody,
   Parameter,
   Post,
+  Put,
   type RequestContext,
 } from "@antelopejs/interface-api";
 import { assert, assertValidation } from "@antelopejs/interface-api-util";
@@ -22,12 +23,21 @@ import {
   collectContentVariablePaths,
   resolveEmail,
   type TemplateChange,
+  valueFormatOf,
 } from "../engine";
-import { type MailingTemplate, SendModel, TemplateModel } from "../db";
+import {
+  type MailingTemplate,
+  SendModel,
+  type TemplateFields,
+  TemplateModel,
+} from "../db";
+import { saveDetails } from "../data/templates-table";
 import { TemplatesPageController } from "../pages/templates";
 import { forAudience, statsWindowStart } from "../services/metrics";
 import { refreshTemplateAttention } from "../services/template-attention";
 import { renderEmailHtml } from "../services/render";
+import { categoriesIn } from "../services/categories";
+import { localeOfRequest, withTextIn } from "../services/localized-text";
 import { getSettings } from "../services/settings";
 import { findStarter, STARTER_TEMPLATES } from "../services/starters";
 import {
@@ -39,7 +49,6 @@ import {
 import {
   assertSlugClaimed,
   contentFieldsOf,
-  contentOfVersion,
   discardDraft,
   displayName,
   hasDraft,
@@ -55,13 +64,17 @@ import {
   publishedVersionOf,
   publishTemplate,
   saveDraft,
+  publishedSnapshot,
+  snapshotOfVersion,
+  type TemplateDraft,
+  workingSnapshot,
   workingContent,
   workingVariables,
   requireTemplate,
 } from "../services/templates";
 import {
   BUSINESS_AUDIENCE,
-  type MailingSettingsValues,
+  type CategoryInLocale,
   type TemplateContent,
   type TemplateStatus,
   type VariableDefinition,
@@ -104,14 +117,13 @@ const TARGET_STATUS: Record<
 };
 
 /** What a lifecycle action records besides the new status. */
-const TRANSITION_FIELDS: Partial<
-  Record<TemplateAction, () => Partial<MailingTemplate>>
-> = {
-  unpublish: () => ({ unpublishedAt: new Date() }),
-};
+const TRANSITION_FIELDS: Partial<Record<TemplateAction, () => TemplateFields>> =
+  {
+    unpublish: () => ({ unpublishedAt: new Date() }),
+  };
 
 export interface CategoriesResponse {
-  categories: MailingSettingsValues["categories"];
+  categories: CategoryInLocale[];
 }
 
 export interface TemplateSender {
@@ -121,6 +133,7 @@ export interface TemplateSender {
 }
 
 export interface TemplateContentResponse {
+  /** The template, its name in the reader's language. */
   template: MailingTemplate;
   /** The content the editor works on: the draft, else the published one. */
   content: TemplateContent;
@@ -146,7 +159,7 @@ export interface TemplateContentResponse {
   fallbackLocale: string;
   /** Whether a send missing a variable fails rather than goes out blank. */
   blockOnMissingVariables: boolean;
-  categories: MailingSettingsValues["categories"];
+  categories: CategoryInLocale[];
   sender: TemplateSender;
 }
 
@@ -192,6 +205,11 @@ export class TemplatesController extends Controller(
     return displayName(this.user);
   }
 
+  /** The language the reader reads names and labels in. */
+  private get locale(): string {
+    return localeOfRequest(this.ctx);
+  }
+
   /**
    * The tenant's categories for a category picker. Separate from `/settings`,
    * which is guarded by the settings page permission a template editor need
@@ -200,7 +218,7 @@ export class TemplatesController extends Controller(
   @Get("/categories")
   async categories(): Promise<CategoriesResponse> {
     const settings = await getSettings(this.tenantId);
-    return { categories: settings.categories };
+    return { categories: categoriesIn(settings.categories, this.locale) };
   }
 
   @Get("/starters")
@@ -236,7 +254,12 @@ export class TemplatesController extends Controller(
     );
     const localeContent = localeContentOf(starter.content, locale);
     assert(localeContent, HTTP_UNPROCESSABLE, INVALID_CONTENT);
-    const email = resolveEmail(localeContent, starter.testDataFor(locale));
+    const email = resolveEmail(
+      localeContent,
+      starter.testDataFor(locale),
+      undefined,
+      valueFormatOf(locale, starter.variables),
+    );
     return { html: await renderEmailHtml(email, locale), locale };
   }
 
@@ -289,7 +312,7 @@ export class TemplatesController extends Controller(
       ? parseContent(template)
       : null;
     return {
-      template,
+      template: template.localize(this.locale, ["name"]),
       content,
       publishedContent,
       hasDraft: hasDraft(template),
@@ -305,7 +328,7 @@ export class TemplatesController extends Controller(
       testData: parseTestData(template),
       fallbackLocale: settings.fallbackLocale,
       blockOnMissingVariables: settings.blockOnMissingVariables,
-      categories: settings.categories,
+      categories: categoriesIn(settings.categories, this.locale),
       sender: {
         name: settings.senderName,
         email: settings.senderEmail,
@@ -431,7 +454,7 @@ export class TemplatesController extends Controller(
   ) {
     await this.requireTransition(id, action);
     const status = TARGET_STATUS[action];
-    await this.templates.update(id, {
+    await this.templates.updateFields(id, {
       status,
       updatedBy: this.author,
       ...TRANSITION_FIELDS[action]?.(),
@@ -472,7 +495,9 @@ export class TemplatesController extends Controller(
       testDataSchema.parse(value),
     );
     await requireTemplate(this.templates, id);
-    await this.templates.update(id, { json_test_data: JSON.stringify(data) });
+    await this.templates.updateFields(id, {
+      json_test_data: JSON.stringify(data),
+    });
     return { data };
   }
 
@@ -487,9 +512,12 @@ export class TemplatesController extends Controller(
       () => INVALID_CONTENT,
     );
     const template = await requireTemplate(this.templates, id);
-    const content =
-      (input.content as TemplateContent | undefined) ??
-      (await this.previewContent(template, input.version));
+    const { content, variables } = input.content
+      ? {
+          ...workingSnapshot(template),
+          content: input.content as TemplateContent,
+        }
+      : await this.previewSnapshot(template, input.version);
     const settings = await getSettings(this.tenantId);
     const locale = pickLocale(content, input.locale, settings.fallbackLocale);
     const localeContent = localeContentOf(content, locale);
@@ -497,6 +525,8 @@ export class TemplatesController extends Controller(
     const email = resolveEmail(
       localeContent,
       input.data ?? parseTestData(template),
+      undefined,
+      valueFormatOf(locale, variables),
     );
     const html = await renderEmailHtml(email, locale);
     return {
@@ -508,14 +538,30 @@ export class TemplatesController extends Controller(
     };
   }
 
-  private previewContent(
+  private previewSnapshot(
     template: MailingTemplate,
     version: "draft" | "published" | number | undefined,
-  ): Promise<TemplateContent> | TemplateContent {
-    if (version === "published") return parseContent(template);
+  ): Promise<TemplateDraft> | TemplateDraft {
+    if (version === "published") return publishedSnapshot(template);
     if (typeof version === "number")
-      return contentOfVersion(this.tenantId, template, version);
-    return workingContent(template);
+      return snapshotOfVersion(this.tenantId, template, version);
+    return workingSnapshot(template);
+  }
+
+  /**
+   * Renames a template in the reader's language, its other languages kept,
+   * and sets its category: what the module's drawer and editor save, each
+   * showing one language. The DMS edit form, which shows every language,
+   * writes through the table's edit route.
+   */
+  @Put("/:id/details")
+  async details(
+    @Parameter("id", "param") id: string,
+    @JSONBody() body: unknown,
+  ) {
+    const template = await requireTemplate(this.templates, id);
+    await saveDetails(this.ctx, template, body, this.author);
+    return { id };
   }
 
   @Post("/:id/duplicate")
@@ -529,9 +575,9 @@ export class TemplatesController extends Controller(
     const source = await requireTemplate(this.templates, id);
     const clash = await this.templates.getBySlug(slug);
     assert(!clash, HTTP_CONFLICT, DUPLICATE_SLUG);
-    const [copyId] = await this.templates.insert({
+    const [copyId] = await this.templates.insertFields({
       slug,
-      name,
+      name: withTextIn(undefined, this.locale, name),
       category: source.category,
       status: "draft",
       ...contentFieldsOf(source),

package/src/services/categories.ts

@@ -1,6 +1,19 @@
 import type { MailingTemplate } from "../db";
-import type { TemplateCategory } from "../types";
+import type { CategoryInLocale, TemplateCategory } from "../types";
 import type { CategoryEntry } from "../validation/settings.schema";
+import { textIn } from "./localized-text";
+
+/** The categories as a reader of `locale` sees them. */
+export function categoriesIn(
+  categories: TemplateCategory[],
+  locale: string,
+): CategoryInLocale[] {
+  return categories.map(({ id, label, icon }) => ({
+    id,
+    label: textIn(label, locale),
+    icon,
+  }));
+}
 
 /** The categories a list keeps, without the removed ones it moves away. */
 export function keptCategories(entries: CategoryEntry[]): TemplateCategory[] {

package/src/services/declarations.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type {
   DeclarationOutcome,
+  LocalizedText,
   DeclareTemplateCategoryResult,
   DeclareTemplateResult,
   TemplateCategoryDeclaration,
@@ -55,7 +56,7 @@ const MAX_DECLARATION_ATTEMPTS = 5;
 
 /** What a declaration fingerprints: everything a user may change after it. */
 interface DeclaredTemplateState {
-  name: string;
+  name: LocalizedText;
   category: string;
   content: TemplateContent;
   variables: VariableDefinition[];
@@ -131,7 +132,7 @@ function planTemplate(declaration: ParsedTemplateDeclaration): TemplatePlan {
 function currentFingerprint(template: MailingTemplate): string | null {
   if (template.status !== LIVE_STATUS || hasDraft(template)) return null;
   return fingerprintOf({
-    name: template.name,
+    name: TemplateModel.namesOf(template),
     category: template.category ?? "",
     content: parseContent(template),
     variables: parseVariables(template),
@@ -165,7 +166,7 @@ async function createDeclared(
   const settings = await getSettings(tenantId);
   assertKnownCategory(settings.categories, state.category, slug);
   const revision = randomUUID();
-  const [id] = await model.insert({
+  const [id] = await model.insertFields({
     slug,
     name: state.name,
     category: state.category,

package/src/services/events.ts

@@ -135,7 +135,7 @@ async function publishEmailEvent(
   send: MailingSend,
 ): Promise<void> {
   emitEmailEvent(payload);
-  publishSendUpdated(payload.sendId);
+  publishSendUpdated(payload.tenantId, payload.sendId);
   await notifyProblems(payload.tenantId, {
     sendId: send._id,
     templateSlug: send.templateSlug,

package/src/services/localized-text.ts

@@ -0,0 +1,53 @@
+import type { RequestContext } from "@antelopejs/interface-api";
+import {
+  LOCALIZED_TEXT_FALLBACK_LOCALE,
+  type LocalizedText,
+} from "@antelopejs/interface-dms-mailing";
+
+/** Header the DMS frontend states the reader's language in on every request. */
+export const CONTENT_LANGUAGE_HEADER = "x-content-language";
+
+/**
+ * The language to read localized texts in: the header's, else the one every
+ * localized text falls back to.
+ *
+ * @param header Value of {@link CONTENT_LANGUAGE_HEADER}
+ */
+export function requestLocale(header: unknown): string {
+  return typeof header === "string" && header.length > 0
+    ? header
+    : LOCALIZED_TEXT_FALLBACK_LOCALE;
+}
+
+/** The language a request reads and writes localized texts in. */
+export function localeOfRequest(ctx: RequestContext): string {
+  return requestLocale(ctx.rawRequest.headers[CONTENT_LANGUAGE_HEADER]);
+}
+
+/**
+ * A localized text in `locale`, else in the fallback language, as
+ * `@Localized({ fallbackLocale })` reads a table field.
+ */
+export function textIn(
+  text: LocalizedText | undefined,
+  locale: string,
+): string {
+  return text?.[locale] ?? text?.[LOCALIZED_TEXT_FALLBACK_LOCALE] ?? "";
+}
+
+/**
+ * `text` with `value` written in `locale`. The fallback language gets the
+ * same value while it has none, so a text first written in another language
+ * still reads in every language.
+ */
+export function withTextIn(
+  text: LocalizedText | undefined,
+  locale: string,
+  value: string,
+): LocalizedText {
+  return {
+    [LOCALIZED_TEXT_FALLBACK_LOCALE]: value,
+    ...text,
+    [locale]: value,
+  };
+}

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

@@ -3,6 +3,7 @@ import type {
   BlockText,
   ComposedText,
 } from "@antelopejs/interface-dms/base/types";
+import { deltaPercent } from "./metrics";
 import type { SendStats } from "./send-stats";
 
 /** Past this wait the oldest queued send is worth a warning. */
@@ -39,11 +40,24 @@ function joined(parts: ComposedText[], fallback: ComposedText): BlockText {
   return parts.reduce((left, right) => text("joined", { left, right }));
 }
 
-function deltaText(delta: number | null): ComposedText[] {
-  if (!delta) return [];
+/** A figure of the comparison window, as its cell writes it. */
+type ComparedValue = NonNullable<ComposedText["params"]>[string];
+
+/**
+ * The change and the figure it is measured against ("▲ 8 % vs 120"), or the
+ * figure alone when no change can be stated (an equal or a zero figure).
+ * Nothing when the comparison is off or the window has no such figure.
+ */
+function comparedText(
+  delta: number | null,
+  previous: ComparedValue | null,
+): ComposedText[] {
+  if (previous === null) return [];
+  if (!delta) return [text("versus", { previous })];
   return [
-    text(delta > 0 ? "delta_up" : "delta_down", {
+    text(delta > 0 ? "delta_up_versus" : "delta_down_versus", {
       delta: percent(Math.abs(delta)),
+      previous,
     }),
   ];
 }
@@ -52,18 +66,29 @@ function sendsItem(stats: SendStats): StatGroupItem {
   const tests = stats.tests
     ? [text("tests_excluded", { count: count(stats.tests) })]
     : [];
+  const previous = stats.compared?.sends ?? null;
   return {
     id: "sends",
     icon: "i-ph-paper-plane-tilt",
     eyebrow: key("sends"),
     value: stats.sends,
     detail: joined(
-      [...deltaText(stats.sendsDelta), ...tests],
+      [...comparedText(stats.sendsDelta, previous), ...tests],
       text("no_tests"),
     ),
   };
 }
 
+/** The deliverability's change; none without a figure on either side. */
+function deliverabilityCompared(stats: SendStats): ComposedText[] {
+  const previous = stats.compared?.deliverability ?? null;
+  if (!stats.sends || previous === null) return [];
+  return comparedText(
+    deltaPercent(stats.deliverability, previous),
+    percent(previous),
+  );
+}
+
 function deliveredItem(stats: SendStats, provider: string): StatGroupItem {
   if (stats.isDeliveryUntracked) {
     return {
@@ -74,6 +99,10 @@ function deliveredItem(stats: SendStats, provider: string): StatGroupItem {
       detail: text("not_tracked", { provider: provider || THE_PROVIDER }),
     };
   }
+  const deliveredOf = text("delivered_of", {
+    delivered: stats.delivered,
+    sends: stats.sends,
+  });
   return {
     id: "delivered",
     icon: "i-ph-check-circle",
@@ -82,10 +111,10 @@ function deliveredItem(stats: SendStats, provider: string): StatGroupItem {
       stats.sends && stats.deliverability !== null
         ? text("rate", { rate: percent(stats.deliverability) })
         : EMPTY_FIGURE,
-    detail: text("delivered_of", {
-      delivered: stats.delivered,
-      sends: stats.sends,
-    }),
+    detail: joined(
+      [...deliverabilityCompared(stats), deliveredOf],
+      deliveredOf,
+    ),
   };
 }
 
@@ -93,13 +122,19 @@ function problemsItem(stats: SendStats): StatGroupItem {
   const parts = PROBLEM_PARTS.filter((part) => stats[part]).map((part) =>
     text(`breakdown.${part}`, { count: count(stats[part]) }),
   );
+  const previous = stats.compared?.problems ?? null;
+  const compared = comparedText(
+    deltaPercent(stats.problems, previous),
+    previous,
+  );
+  const breakdown = parts.length ? parts : [text("no_problems")];
   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")),
+    detail: joined([...compared, ...breakdown], text("no_problems")),
     to: stats.problems ? PROBLEMS_PAGE : undefined,
   };
 }
@@ -127,15 +162,26 @@ export function latencyText(ms: number): ComposedText {
   });
 }
 
+/** The latency's change; none without a timed send on either side. */
+function latencyCompared(stats: SendStats): ComposedText[] {
+  const previous = stats.compared?.latencyMedian ?? null;
+  if (!stats.sends || previous === null) return [];
+  return comparedText(
+    deltaPercent(stats.latencyMedian, previous),
+    latencyText(previous),
+  );
+}
+
 function latencyItem(stats: SendStats, provider: string): StatGroupItem {
+  const call = provider
+    ? text("latency_detail", { provider })
+    : text("latency_detail_generic");
   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"),
+    detail: joined([...latencyCompared(stats), call], call),
   };
 }
 
@@ -143,7 +189,8 @@ function latencyItem(stats: SendStats, provider: string): StatGroupItem {
  * 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.
+ * oldest wait, and the median API latency. Every cell but the queue, which is
+ * what waits now, states its change against the comparison window.
  */
 export function buildSendStatItems(
   stats: SendStats,

package/src/services/send-stats.ts

@@ -35,6 +35,21 @@ export interface SendStats {
   /** When the oldest send still queued was made; `null` with none queued. */
   oldestQueuedAt: string | null;
   latencyMedian: number;
+  /** The same figures over the comparison window; `null` with it turned off. */
+  compared: ComparedSendStats | null;
+}
+
+/**
+ * The figures of the strip a comparison window states. The queue is left out:
+ * it is what waits now, and what waited back then has long left.
+ */
+export interface ComparedSendStats {
+  sends: number;
+  /** `null` without a real send, or when nothing reported deliveries. */
+  deliverability: number | null;
+  problems: number;
+  /** `null` without a real send to time. */
+  latencyMedian: number | null;
 }
 
 const isQueued = (send: SendSummary): boolean => send.status === "queued";
@@ -74,20 +89,36 @@ function problemBreakdown(real: SendSummary[]): ProblemBreakdown {
   return { problems: bounced + failed + spam, bounced, failed, spam };
 }
 
+const isRealSend = (send: SendSummary): boolean => !send.isTest;
+
+function comparedStats(
+  previous: SendSummary[],
+  tracking: ProviderTracking | null,
+): ComparedSendStats {
+  const real = previous.filter(isRealSend);
+  const totals = aggregate(real);
+  return {
+    sends: totals.sends,
+    deliverability: isDeliveryUntracked(real, tracking)
+      ? null
+      : totals.deliverability,
+    problems: problemBreakdown(real).problems,
+    latencyMedian: totals.sends ? totals.latencyMedian : null,
+  };
+}
+
 /** `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 real = current.filter(isRealSend);
   const totals = aggregate(real);
-  const previousTotals = previous
-    ? aggregate(previous.filter((send) => !send.isTest))
-    : null;
+  const compared = previous ? comparedStats(previous, tracking) : null;
   return {
     sends: totals.sends,
-    sendsDelta: deltaPercent(totals.sends, previousTotals?.sends ?? null),
+    sendsDelta: deltaPercent(totals.sends, compared?.sends ?? null),
     tests: current.length - real.length,
     delivered: totals.delivered,
     deliverability: totals.deliverability,
@@ -96,6 +127,7 @@ export function buildSendStats(
     queued: totals.queued,
     oldestQueuedAt: oldestQueuedAt(real),
     latencyMedian: totals.latencyMedian,
+    compared,
   };
 }
 

package/src/services/send.ts

@@ -22,6 +22,8 @@ import {
   missingSystemVariables,
   renderPlainText,
   resolveEmail,
+  type ValueFormat,
+  valueFormatOf,
 } from "../engine";
 import type {
   SendTemplateParams,
@@ -43,11 +45,12 @@ import { refreshAttentionIfFlagged } from "./template-attention";
 import {
   hasDraft,
   localeContentOf,
-  parseContent,
   parseVariables,
   pickLocale,
+  publishedSnapshot,
   publishedVersionOf,
-  workingContent,
+  type VersionedSnapshot,
+  workingSnapshot,
 } from "./templates";
 
 export class SendError extends Error {
@@ -66,6 +69,8 @@ export interface PreparedSend {
   requestedLocale: string;
   /** Template version the content belongs to; 0 for a draft. */
   version: number;
+  /** How its typed values are written: the locale, the version's `date` paths. */
+  format: ValueFormat;
   templateId: string;
   slug: string;
   tenantId: string;
@@ -165,11 +170,6 @@ const nameOf = (to: EmailAddress): string | undefined =>
 const toRecipients = (to: EmailAddress | EmailAddress[]): EmailAddress[] =>
   Array.isArray(to) ? to : [to];
 
-interface ResolvedContent {
-  content: TemplateContent;
-  version: number;
-}
-
 /**
  * The content a send renders and the version it belongs to. A real send gets
  * what customers receive; a test send gets the draft when there is one, so a
@@ -178,20 +178,17 @@ interface ResolvedContent {
 function resolveContent(
   template: MailingTemplate,
   params: ModuleSendParams,
-): ResolvedContent {
+): VersionedSnapshot {
   if (params.content)
     return {
+      ...workingSnapshot(template),
       content: params.content,
       version: params.version ?? DRAFT_VERSION,
     };
-  if (params.isTest && hasDraft(template))
-    return { content: workingContent(template), version: DRAFT_VERSION };
-  if (params.isTest && !publishedVersionOf(template))
-    return { content: workingContent(template), version: DRAFT_VERSION };
-  return {
-    content: parseContent(template),
-    version: publishedVersionOf(template),
-  };
+  if (params.isTest && (hasDraft(template) || !publishedVersionOf(template)))
+    return { ...workingSnapshot(template), version: DRAFT_VERSION };
+  const version = publishedVersionOf(template);
+  return { ...publishedSnapshot(template), version };
 }
 
 const isManualRealSend = (params: ModuleSendParams): boolean =>
@@ -247,7 +244,7 @@ async function renderForSend(
     );
   }
   const variables = params.variables ?? {};
-  const email = resolveEmail(localeContent, variables, "send");
+  const email = resolveEmail(localeContent, variables, "send", prepared.format);
   const refused = refusedMissing(
     params,
     isBlocking,
@@ -279,13 +276,15 @@ export async function prepare(
   if (missing.length) {
     throw new SendError("missing_variables", missing.join(", "));
   }
-  const { content, version } = resolveContent(template, params);
+  const { content, version, variables } = resolveContent(template, params);
   const settings = await getSettings(tenantId);
+  const locale = pickLocale(content, params.locale, settings.fallbackLocale);
   return {
     content,
-    locale: pickLocale(content, params.locale, settings.fallbackLocale),
+    locale,
     requestedLocale: params.locale ?? "",
     version,
+    format: valueFormatOf(locale, variables),
     templateId: template._id,
     slug,
     tenantId,
@@ -476,7 +475,7 @@ async function record(
       outcome.error ? { reason: outcome.error } : {},
     ),
   });
-  publishSendCreated(sendId as string);
+  publishSendCreated(tenantId, sendId as string);
   return sendId as string;
 }