@antelopejs/dms-mailing 0.6.1 → 0.7.1

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;
 }
 

package/src/services/sender-declaration.ts

@@ -0,0 +1,27 @@
+import type { SenderDeclaration } from "@antelopejs/interface-dms-mailing";
+import { senderDeclarationSchema } from "../validation/declarations.schema";
+import { parseDeclared } from "./declaration-error";
+import { getSettings, saveSettings } from "./settings";
+
+/**
+ * Writes the workspace's sender (from name, address, reply-to) a project
+ * sets up when it provisions the workspace. A plain write: the declared
+ * sender replaces the stored one, and later edits in the settings are the
+ * user's.
+ */
+export async function declareSender(input: SenderDeclaration): Promise<void> {
+  const declaration = parseDeclared(
+    senderDeclarationSchema,
+    input,
+    "invalid_sender",
+    "sender declaration",
+  );
+  const { tenantId } = declaration;
+  const settings = await getSettings(tenantId);
+  await saveSettings(tenantId, {
+    ...settings,
+    senderName: declaration.name,
+    senderEmail: declaration.email,
+    replyTo: declaration.replyTo,
+  });
+}

package/src/services/settings.ts

@@ -1,12 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { GetModel } from "@antelopejs/interface-database-decorators";
-import {
-  DEFAULT_FALLBACK_LOCALE,
-  DEFAULT_LOG_RETENTION_DAYS,
-} from "../constants";
 import { type MailingSettings, SettingsModel } from "../db";
 import {
-  DEFAULT_CATEGORIES,
+  MODULE_DEFAULT_SETTINGS,
   type MailingSettingsValues,
   type TemplateCategory,
 } from "../types";
@@ -15,14 +11,11 @@ export const WEBHOOK_SECRET_BYTES = 24;
 
 function defaults(): MailingSettingsValues {
   return {
-    fallbackLocale: DEFAULT_FALLBACK_LOCALE,
-    logRetentionDays: DEFAULT_LOG_RETENTION_DAYS,
-    blockOnMissingVariables: false,
+    ...MODULE_DEFAULT_SETTINGS,
     senderName: "",
     senderEmail: "",
     replyTo: "",
     webhookSecret: randomBytes(WEBHOOK_SECRET_BYTES).toString("hex"),
-    categories: DEFAULT_CATEGORIES,
   };
 }
 
@@ -106,7 +99,7 @@ const REFUSE_POLICY: MissingVariablesPolicy = "refuse";
 const SEND_POLICY: MissingVariablesPolicy = "send";
 
 export function missingVariablesPolicy(
-  values: MailingSettingsValues,
+  values: Pick<MailingSettingsValues, "blockOnMissingVariables">,
 ): MissingVariablesPolicy {
   return values.blockOnMissingVariables ? REFUSE_POLICY : SEND_POLICY;
 }

package/src/services/starters.ts

@@ -1,11 +1,11 @@
-import type { MailingTemplate } from "../db";
+import type { TemplateFields } from "../db";
 import type {
   Block,
   LocaleContent,
   TemplateContent,
   VariableDefinition,
 } from "../types";
-import { footerForCategory } from "../engine";
+import { footerForCategory, formattingLocale } from "../engine";
 import { blankFields, footerBlock } from "./templates";
 
 /**
@@ -31,18 +31,6 @@ type StarterSource = Omit<StarterTemplate, "testData">;
 const DEFAULT_TEST_DATA_LOCALE = "en";
 const STARTER_CURRENCY = "EUR";
 
-/** `locale` when the runtime can format for it, English otherwise. */
-function formattingLocale(locale: string): string {
-  try {
-    return (
-      Intl.NumberFormat.supportedLocalesOf(locale)[0] ??
-      DEFAULT_TEST_DATA_LOCALE
-    );
-  } catch {
-    return DEFAULT_TEST_DATA_LOCALE;
-  }
-}
-
 /** The ordered item of the order starter's test data, by language. */
 const ORDER_LINE_NAMES: Record<string, string> = {
   en: "Ergo chair · Graphite × 4",
@@ -374,7 +362,7 @@ export function findStarter(id: string): StarterTemplate | undefined {
 export function starterFields(
   starter: StarterTemplate,
   locale: string = DEFAULT_TEST_DATA_LOCALE,
-): Partial<MailingTemplate> {
+): TemplateFields {
   return {
     ...blankFields(starter.content),
     json_variables: JSON.stringify(starter.variables),