@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/services/starters.ts

@@ -0,0 +1,383 @@
+import type { MailingTemplate } from "../db";
+import type {
+  Block,
+  LocaleContent,
+  TemplateContent,
+  VariableDefinition,
+} from "../types";
+import { footerForCategory } from "../engine";
+import { blankFields, footerBlock } from "./templates";
+
+/**
+ * A ready-made template a new workspace can start from instead of a blank
+ * page. It arrives as a draft with its variables declared and test data
+ * filled in, so it previews and test-sends right away.
+ */
+export interface StarterTemplate {
+  id: string;
+  name: string;
+  slug: string;
+  category: string;
+  content: TemplateContent;
+  variables: VariableDefinition[];
+  /** The test data as an English-speaking workspace gets it. */
+  testData: Record<string, unknown>;
+  /** The test data with its amounts written the way `locale` writes them. */
+  testDataFor: (locale: string) => Record<string, unknown>;
+}
+
+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",
+  fr: "Fauteuil ergonomique · Graphite × 4",
+};
+const LOCALE_PARTS = /[-_]/;
+
+/** A test text in the language of `locale`, English when it has none. */
+function inLanguageOf(texts: Record<string, string>, locale: string): string {
+  const language = locale.toLowerCase().split(LOCALE_PARTS)[0] ?? "";
+  return texts[language] ?? (texts[DEFAULT_TEST_DATA_LOCALE] as string);
+}
+
+/** An amount the way `locale` writes it: "€1,556.00", "1 556,00 €". */
+function money(amount: number, locale: string): string {
+  return new Intl.NumberFormat(formattingLocale(locale), {
+    style: "currency",
+    currency: STARTER_CURRENCY,
+  }).format(amount);
+}
+
+interface StarterCopy {
+  subject: string;
+  preheader: string;
+  heading: string;
+  body: string;
+  button?: string;
+  /** Why the recipient gets this e-mail: the footer's legal line. */
+  footer: string;
+}
+
+const HEADING_SIZE = 26;
+
+function localeContent(
+  locale: string,
+  copy: StarterCopy,
+  extra: Block[],
+  buttonHref: string,
+): LocaleContent {
+  const button: Block[] = copy.button
+    ? [
+        {
+          id: "cta",
+          type: "button",
+          text: copy.button,
+          href: buttonHref,
+          align: "left",
+          visibleIf: null,
+        },
+      ]
+    : [];
+  return {
+    subject: copy.subject,
+    preheader: copy.preheader,
+    blocks: [
+      {
+        id: "heading",
+        type: "heading",
+        text: copy.heading,
+        align: "left",
+        size: HEADING_SIZE,
+        visibleIf: null,
+      },
+      {
+        id: "intro",
+        type: "paragraph",
+        text: copy.body,
+        align: "left",
+        visibleIf: null,
+      },
+      ...extra,
+      ...button,
+      footerBlock(locale, copy.footer),
+    ],
+  };
+}
+
+const orderLines: Block[] = [
+  {
+    id: "lines",
+    type: "list",
+    source: "order.lines",
+    labelPath: "name",
+    valuePath: "total",
+    visibleIf: null,
+  },
+  {
+    id: "total",
+    type: "total",
+    label: "Total",
+    value: "{{order.total}}",
+    visibleIf: null,
+  },
+];
+
+const v = (
+  path: string,
+  type: VariableDefinition["type"],
+  required = true,
+): VariableDefinition => ({ path, type, required });
+
+const ORDER_TOTAL = 1556;
+const INVOICE_AMOUNT = 318.9;
+
+const STARTER_SOURCES: StarterSource[] = [
+  {
+    id: "order-confirmed",
+    name: "Order confirmation",
+    slug: "order-confirmed",
+    category: "orders",
+    variables: [
+      v("customer.firstName", "string"),
+      v("order.number", "string"),
+      v("order.total", "money"),
+      v("order.lines", "array"),
+      v("order.url", "url"),
+    ],
+    testDataFor: (locale) => ({
+      customer: { firstName: "Julie" },
+      order: {
+        number: "#10482",
+        total: money(ORDER_TOTAL, locale),
+        url: "https://example.com/orders/10482",
+        lines: [
+          {
+            name: inLanguageOf(ORDER_LINE_NAMES, locale),
+            total: money(ORDER_TOTAL, locale),
+          },
+        ],
+      },
+    }),
+    content: {
+      locales: {
+        en: localeContent(
+          "en",
+          {
+            subject: "Thanks for your order {{order.number}}",
+            preheader: "We're getting it ready. Here's your summary.",
+            heading: "Thanks for your order, {{customer.firstName}}!",
+            body: "We've received order {{order.number}} and we're getting it ready.",
+            button: "Track your order",
+            footer:
+              "You are receiving this e-mail because you placed an order with us.",
+          },
+          orderLines,
+          "{{order.url}}",
+        ),
+        fr: localeContent(
+          "fr",
+          {
+            subject: "Merci pour votre commande {{order.number}}",
+            preheader: "Nous la préparons. Voici votre récapitulatif.",
+            heading: "Merci pour votre commande, {{customer.firstName}} !",
+            body: "Nous avons bien reçu la commande {{order.number}} et nous la préparons.",
+            button: "Suivre ma commande",
+            footer: "Vous recevez cet e-mail suite à votre commande.",
+          },
+          orderLines,
+          "{{order.url}}",
+        ),
+      },
+    },
+  },
+  {
+    id: "order-shipped",
+    name: "Shipping update",
+    slug: "order-shipped",
+    category: "orders",
+    variables: [
+      v("customer.firstName", "string"),
+      v("order.number", "string"),
+      v("shipment.trackingUrl", "url"),
+    ],
+    testDataFor: () => ({
+      customer: { firstName: "Julie" },
+      order: { number: "#10482" },
+      shipment: { trackingUrl: "https://example.com/track/10482" },
+    }),
+    content: {
+      locales: {
+        en: localeContent(
+          "en",
+          {
+            subject: "Your order {{order.number}} has shipped",
+            preheader: "It's on its way.",
+            heading: "Your order {{order.number}} has shipped",
+            body: "Good news {{customer.firstName}}, your parcel is on its way.",
+            button: "Track the parcel",
+            footer:
+              "You are receiving this e-mail because you placed an order with us.",
+          },
+          [],
+          "{{shipment.trackingUrl}}",
+        ),
+        fr: localeContent(
+          "fr",
+          {
+            subject: "Votre commande {{order.number}} est expédiée",
+            preheader: "Elle est en route.",
+            heading: "Votre commande {{order.number}} est expédiée",
+            body: "Bonne nouvelle {{customer.firstName}}, votre colis est en route.",
+            button: "Suivre le colis",
+            footer: "Vous recevez cet e-mail suite à votre commande.",
+          },
+          [],
+          "{{shipment.trackingUrl}}",
+        ),
+      },
+    },
+  },
+  {
+    id: "password-reset",
+    name: "Password reset",
+    slug: "password-reset",
+    category: "account",
+    variables: [v("user.firstName", "string"), v("reset.url", "url")],
+    testDataFor: () => ({
+      user: { firstName: "Julie" },
+      reset: { url: "https://example.com/reset/abc123" },
+    }),
+    content: {
+      locales: {
+        en: localeContent(
+          "en",
+          {
+            subject: "Reset your password",
+            preheader: "The link works for one hour.",
+            heading: "Reset your password",
+            body: "Hi {{user.firstName}}, click the button below to choose a new password. If you didn't ask for it, ignore this e-mail.",
+            button: "Choose a new password",
+            footer:
+              "You are receiving this e-mail because a password reset was requested for your account.",
+          },
+          [],
+          "{{reset.url}}",
+        ),
+        fr: localeContent(
+          "fr",
+          {
+            subject: "Réinitialisez votre mot de passe",
+            preheader: "Le lien est valable une heure.",
+            heading: "Réinitialisez votre mot de passe",
+            body: "Bonjour {{user.firstName}}, cliquez sur le bouton ci-dessous pour choisir un nouveau mot de passe. Si vous ne l'avez pas demandé, ignorez cet e-mail.",
+            button: "Choisir un nouveau mot de passe",
+            footer:
+              "Vous recevez cet e-mail car une réinitialisation du mot de passe a été demandée pour votre compte.",
+          },
+          [],
+          "{{reset.url}}",
+        ),
+      },
+    },
+  },
+  {
+    id: "invoice-ready",
+    name: "Invoice available",
+    slug: "invoice-ready",
+    category: "billing",
+    variables: [
+      v("customer.firstName", "string"),
+      v("invoice.number", "string"),
+      v("invoice.amount", "money"),
+      v("invoice.url", "url"),
+    ],
+    testDataFor: (locale) => ({
+      customer: { firstName: "Julie" },
+      invoice: {
+        number: "INV-2026-0918",
+        amount: money(INVOICE_AMOUNT, locale),
+        url: "https://example.com/invoices/0918",
+      },
+    }),
+    content: {
+      locales: {
+        en: localeContent(
+          "en",
+          {
+            subject: "Invoice {{invoice.number}} is available",
+            preheader: "Amount due: {{invoice.amount}}.",
+            heading: "Invoice {{invoice.number}} is available",
+            body: "Hi {{customer.firstName}}, your invoice of {{invoice.amount}} is ready.",
+            button: "Download the invoice",
+            footer:
+              "You are receiving this e-mail because an invoice was issued for your account.",
+          },
+          [],
+          "{{invoice.url}}",
+        ),
+        fr: localeContent(
+          "fr",
+          {
+            subject: "La facture {{invoice.number}} est disponible",
+            preheader: "Montant dû : {{invoice.amount}}.",
+            heading: "La facture {{invoice.number}} est disponible",
+            body: "Bonjour {{customer.firstName}}, votre facture de {{invoice.amount}} est prête.",
+            button: "Télécharger la facture",
+            footer:
+              "Vous recevez cet e-mail car une facture a été émise pour votre compte.",
+          },
+          [],
+          "{{invoice.url}}",
+        ),
+      },
+    },
+  },
+];
+
+/**
+ * The starters, each with the footer its category calls for: the shipped ones
+ * are transactional, so their footer states why the e-mail was sent and
+ * carries no unsubscribe link.
+ */
+export const STARTER_TEMPLATES: StarterTemplate[] = STARTER_SOURCES.map(
+  (starter) => ({
+    ...starter,
+    testData: starter.testDataFor(DEFAULT_TEST_DATA_LOCALE),
+    content: footerForCategory(starter.content, starter.category),
+  }),
+);
+
+export function findStarter(id: string): StarterTemplate | undefined {
+  return STARTER_TEMPLATES.find((starter) => starter.id === id);
+}
+
+/**
+ * The content fields a template created from `starter` starts with, its test
+ * data written in the workspace's `locale`: its amounts and its texts.
+ */
+export function starterFields(
+  starter: StarterTemplate,
+  locale: string = DEFAULT_TEST_DATA_LOCALE,
+): Partial<MailingTemplate> {
+  return {
+    ...blankFields(starter.content),
+    json_variables: JSON.stringify(starter.variables),
+    json_test_data: JSON.stringify(starter.testDataFor(locale)),
+  };
+}

package/src/services/suppressions.ts

@@ -0,0 +1,116 @@
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  type MailingSuppression,
+  normalizeAddress,
+  type SendSummary,
+  SuppressionModel,
+} from "../db";
+import type {
+  SendEventType,
+  SuppressionReason,
+  SuppressionSummary,
+} from "../types";
+
+/** What the event of a send says about its address. */
+export interface SuppressingEvent {
+  type: SendEventType;
+  isTest: boolean;
+  isSoftBounce: boolean;
+}
+
+/** An address to put on the list. */
+export interface SuppressionEntry {
+  email: string;
+  reason: SuppressionReason;
+  sendId?: string;
+  detail?: string;
+  createdBy?: string;
+}
+
+const REASON_BY_EVENT: Partial<Record<SendEventType, SuppressionReason>> = {
+  bounced: "hard_bounce",
+  spam: "complaint",
+  unsubscribed: "unsubscribe",
+};
+
+/**
+ * Reasons a test send puts its address on the list too: an address that does
+ * not exist does not exist for anyone. A spam report or an unsubscription on
+ * a test is the editor's own gesture, not a recipient's choice.
+ */
+const REASONS_FROM_TESTS = new Set<SuppressionReason>(["hard_bounce"]);
+
+/**
+ * The reason an event puts its address on the suppression list, `null` when
+ * it does not: a temporary bounce (a full mailbox) may get through later.
+ */
+export function suppressionReasonOf(
+  event: SuppressingEvent,
+): SuppressionReason | null {
+  const reason = REASON_BY_EVENT[event.type];
+  if (!reason) return null;
+  if (event.type === "bounced" && event.isSoftBounce) return null;
+  if (event.isTest && !REASONS_FROM_TESTS.has(reason)) return null;
+  return reason;
+}
+
+export function summarizeSuppression(
+  row: MailingSuppression,
+): SuppressionSummary {
+  return {
+    id: row._id,
+    email: row.email,
+    reason: row.reason,
+    createdAt: row.createdAt,
+    sendId: row.sendId || undefined,
+  };
+}
+
+/**
+ * Puts an address on the tenant's suppression list; an address already on it
+ * keeps its first reason.
+ * @returns Whether the address was added
+ */
+export function suppressAddress(
+  tenantId: string,
+  entry: SuppressionEntry,
+): Promise<boolean> {
+  return GetModel(SuppressionModel, tenantId).add(entry);
+}
+
+/** The suppression entries of the addresses given, by normalized address. */
+export async function suppressionsOf(
+  tenantId: string,
+  emails: string[],
+): Promise<Map<string, MailingSuppression>> {
+  const rows = await GetModel(SuppressionModel, tenantId).listByEmails(emails);
+  return new Map(rows.map((row) => [normalizeAddress(row.email), row]));
+}
+
+/**
+ * The ids of the sends whose address is on the suppression list today: a send
+ * again of them would not leave.
+ */
+export async function suppressedSendIds(
+  tenantId: string,
+  sends: Pick<SendSummary, "_id" | "recipientEmail">[],
+): Promise<Set<string>> {
+  const entries = await suppressionsOf(
+    tenantId,
+    sends.map((send) => send.recipientEmail),
+  );
+  return new Set(
+    sends
+      .filter((send) => entries.has(normalizeAddress(send.recipientEmail)))
+      .map((send) => send._id),
+  );
+}
+
+/** The entry of one address, `null` when nothing stops sending to it. */
+export async function findSuppression(
+  tenantId: string,
+  email: string,
+): Promise<SuppressionSummary | null> {
+  const row = await GetModel(SuppressionModel, tenantId).findByEmail(email);
+  return row ? summarizeSuppression(row) : null;
+}

package/src/services/template-attention.ts

@@ -0,0 +1,82 @@
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  type MailingTemplate,
+  SendModel,
+  type TemplateAttentionFields,
+  TemplateModel,
+} from "../db";
+import { BUSINESS_AUDIENCE, type TemplateAttentionReason } from "../types";
+import {
+  knownLocalesOf,
+  type TemplateAttentionContext,
+  templateAttentionReasons,
+} from "./attention";
+import { forAudience, statsWindowStart } from "./metrics";
+
+/** How the stored `attention` field separates its reasons. */
+const REASON_SEPARATOR = ",";
+
+/** The attention fields a template gets for its reasons. */
+function attentionFields(
+  reasons: TemplateAttentionReason[],
+): TemplateAttentionFields {
+  return {
+    attention: reasons.join(REASON_SEPARATOR),
+    needsAttention: reasons.length > 0,
+  };
+}
+
+async function attentionContext(
+  tenantId: string,
+  templates: MailingTemplate[],
+): Promise<TemplateAttentionContext> {
+  const now = Date.now();
+  const sends = await GetModel(SendModel, tenantId).listBetween(
+    statsWindowStart(now),
+    new Date(now),
+  );
+  const real = forAudience(sends, BUSINESS_AUDIENCE);
+  return {
+    now,
+    sentSlugs: new Set(real.map((send) => send.templateSlug)),
+    knownLocales: knownLocalesOf(templates),
+  };
+}
+
+/**
+ * Works out again why each template of the tenant needs a look, and stores it
+ * on the ones whose reasons changed: the templates page filters its "Needs
+ * attention" tab on it and the cards show it.
+ */
+export async function refreshTemplateAttention(
+  tenantId: string,
+): Promise<void> {
+  const model = GetModel(TemplateModel, tenantId);
+  const templates = await model.getAll();
+  const context = await attentionContext(tenantId, templates);
+  const changed = templates
+    .map((template) => ({
+      template,
+      fields: attentionFields(templateAttentionReasons(template, context)),
+    }))
+    .filter(({ template, fields }) => template.attention !== fields.attention);
+  await Promise.all(
+    changed.map(({ template, fields }) =>
+      model.writeAttention(template._id, fields),
+    ),
+  );
+}
+
+/**
+ * Refreshes the tenant's attention when `template` was flagged for `reason`,
+ * which the write just made may have settled (a stale draft saved, a live
+ * template sent).
+ */
+export async function refreshAttentionIfFlagged(
+  tenantId: string,
+  template: Pick<MailingTemplate, "attention">,
+  reason: TemplateAttentionReason,
+): Promise<void> {
+  if (template.attention.split(REASON_SEPARATOR).includes(reason))
+    await refreshTemplateAttention(tenantId);
+}

package/src/services/template-stats.ts

@@ -0,0 +1,97 @@
+import type { SendSummary } from "../db";
+import { aggregate, groupBy } from "./metrics";
+import { PROBLEM_STATUSES } from "../types";
+
+/** What a template card and the details drawer say about recent sends. */
+export interface TemplateStats {
+  id: string;
+  slug: string;
+  sends: number;
+  openRate: number;
+  problems: number;
+  lastSentAt: string | null;
+}
+
+export interface SourceCount {
+  source: string;
+  count: number;
+}
+
+/** Recipients who asked for a locale the template did not carry. */
+export interface FallbackCount {
+  requested: string;
+  used: string;
+  count: number;
+}
+
+export interface TemplatePerformance extends TemplateStats {
+  sources: SourceCount[];
+  fallbacks: FallbackCount[];
+}
+
+const UNKNOWN_SOURCE = "";
+const MAX_SOURCES = 5;
+
+const isProblem = (send: SendSummary): boolean =>
+  PROBLEM_STATUSES.includes(send.status);
+
+function lastSentAt(sends: SendSummary[]): string | null {
+  const latest = sends.reduce<Date | null>((current, send) => {
+    const at = new Date(send.createdAt);
+    return !current || at > current ? at : current;
+  }, null);
+  return latest ? latest.toISOString() : null;
+}
+
+export function statsOf(
+  id: string,
+  slug: string,
+  sends: SendSummary[],
+): TemplateStats {
+  return {
+    id,
+    slug,
+    sends: sends.length,
+    openRate: aggregate(sends).openRate ?? 0,
+    problems: sends.filter(isProblem).length,
+    lastSentAt: lastSentAt(sends),
+  };
+}
+
+/** Sends grouped by the code path that made them, busiest first. */
+export function sourcesOf(sends: SendSummary[]): SourceCount[] {
+  return [...groupBy(sends, (send) => send.source ?? UNKNOWN_SOURCE)]
+    .map(([source, rows]) => ({ source, count: rows.length }))
+    .sort((left, right) => right.count - left.count)
+    .slice(0, MAX_SOURCES);
+}
+
+export function isFallback(send: SendSummary): boolean {
+  return Boolean(send.requestedLocale && send.requestedLocale !== send.locale);
+}
+
+export function fallbacksOf(sends: SendSummary[]): FallbackCount[] {
+  const fallbacks = sends.filter(isFallback);
+  return [
+    ...groupBy(fallbacks, (send) => `${send.requestedLocale}>${send.locale}`),
+  ].map(([, rows]) => {
+    const first = rows[0] as SendSummary;
+    return {
+      requested: first.requestedLocale as string,
+      used: first.locale,
+      count: rows.length,
+    };
+  });
+}
+
+export function performanceOf(
+  id: string,
+  slug: string,
+  sends: SendSummary[],
+): TemplatePerformance {
+  return {
+    ...statsOf(id, slug, sends),
+    sources: sourcesOf(sends),
+    fallbacks: fallbacksOf(sends),
+  };
+}