@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/services/send.ts

@@ -11,22 +11,44 @@ import {
 } from "@antelopejs/interface-email";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import { MODULE_ID } from "../constants";
-import { SendEventModel, SendModel, TemplateModel } from "../db";
-import { resolveEmail } from "../engine";
+import {
+  type MailingTemplate,
+  SendEventModel,
+  SendModel,
+  TemplateModel,
+} from "../db";
+import {
+  missingRequiredVariables,
+  missingSystemVariables,
+  renderPlainText,
+  resolveEmail,
+} from "../engine";
 import type {
   SendTemplateParams,
   SendTemplateResult,
 } from "@antelopejs/interface-dms-mailing";
-import type {
-  MailingSettingsValues,
-  SendStatus,
-  TemplateContent,
+import {
+  type MailingSettingsValues,
+  type ResolvedEmail,
+  type SendStatus,
+  stageOf,
+  type TemplateAttentionReason,
+  type TemplateContent,
 } from "../types";
 import { publishSendCreated } from "../realtime";
 import { renderEmailHtml } from "./render";
 import { getSettings } from "./settings";
 import { toSendStatus } from "./status";
-import { localeContentOf, parseContent, pickLocale } from "./templates";
+import { refreshAttentionIfFlagged } from "./template-attention";
+import {
+  hasDraft,
+  localeContentOf,
+  parseContent,
+  parseVariables,
+  pickLocale,
+  publishedVersionOf,
+  workingContent,
+} from "./templates";
 
 export class SendError extends Error {
   constructor(
@@ -40,13 +62,37 @@ export class SendError extends Error {
 export interface PreparedSend {
   content: TemplateContent;
   locale: string;
+  /** Locale the caller asked for, blank when it let the fallback pick. */
+  requestedLocale: string;
+  /** Template version the content belongs to; 0 for a draft. */
+  version: number;
   templateId: string;
   slug: string;
   tenantId: string;
+  /** The template's category: a marketing one requires its unsubscribe URL. */
+  category: string;
+  /** Why the template needed a look when the send started. */
+  attention: string;
+}
+
+/**
+ * What the module's own routes add to a `SendTemplate` call: the version a
+ * content override belongs to, so a send again records the version it
+ * repeats rather than the draft marker.
+ */
+export interface ModuleSendParams extends SendTemplateParams {
+  version?: number;
 }
 
+const DRAFT_VERSION = 0;
+const NEVER_SENT: TemplateAttentionReason = "never_sent";
+const TEST_SUBJECT_PREFIX = "[TEST] ";
+
+/** Source of a real send started by hand from the module's dialog. */
+export const MANUAL_SEND_SOURCE = "dms-mailing:manual";
+
 interface SendOutcome {
-  latencyMs: number;
+  latencyMs: number | null;
   provider?: string;
   providerMessageId?: string;
   error?: string;
@@ -71,6 +117,8 @@ export interface DeliveryInput {
   settings: MailingSettingsValues;
   subject: string;
   html: string;
+  /** The plain-text alternative of `html`. */
+  text?: string;
   recipients: EmailAddress[];
 }
 
@@ -99,9 +147,10 @@ const OUTCOME_SEVERITY: Record<SendStatus, number> = {
   sent: 3,
   queued: 4,
   unsubscribed: 5,
-  spam: 6,
-  bounced: 7,
-  failed: 8,
+  suppressed: 6,
+  spam: 7,
+  bounced: 8,
+  failed: 9,
 };
 
 const describeError = (error: unknown): string =>
@@ -116,10 +165,105 @@ const nameOf = (to: EmailAddress): string | undefined =>
 const toRecipients = (to: EmailAddress | EmailAddress[]): EmailAddress[] =>
   Array.isArray(to) ? to : [to];
 
-async function prepare(
+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
+ * change can be tried before it is published.
+ */
+function resolveContent(
+  template: MailingTemplate,
+  params: ModuleSendParams,
+): ResolvedContent {
+  if (params.content)
+    return {
+      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),
+  };
+}
+
+const isManualRealSend = (params: ModuleSendParams): boolean =>
+  params.source === MANUAL_SEND_SOURCE && !params.isTest;
+
+/**
+ * The required variables a manual real send lacks. Such a send is refused
+ * whatever `blockOnMissingVariables` says: a person typed its values for real
+ * recipients, so a blank there is a slip, not a caller's choice.
+ */
+export function missingManualVariables(
+  template: MailingTemplate,
+  params: ModuleSendParams,
+): string[] {
+  return isManualRealSend(params)
+    ? missingRequiredVariables(parseVariables(template), params.variables ?? {})
+    : [];
+}
+
+/**
+ * The missing values a send is refused over. `blockOnMissingVariables` refuses
+ * on any of them; a manual real send always refuses on the required system
+ * URLs, like on its other required variables. A test send never waits for
+ * an unsubscribe URL: it goes to the team, not to a subscriber.
+ */
+export function refusedMissing(
+  params: ModuleSendParams,
+  isBlocking: boolean,
+  missing: string[],
+  missingSystem: string[],
+): string[] {
+  const system = params.isTest ? [] : missingSystem;
+  if (isBlocking) return [...missing, ...system];
+  return isManualRealSend(params) ? system : [];
+}
+
+interface RenderedSend {
+  email: ResolvedEmail;
+  html: string;
+}
+
+/** The e-mail a send delivers, or a refusal over its missing values. */
+async function renderForSend(
+  prepared: PreparedSend,
+  params: ModuleSendParams,
+  isBlocking: boolean,
+): Promise<RenderedSend> {
+  const localeContent = localeContentOf(prepared.content, prepared.locale);
+  if (!localeContent) {
+    throw new SendError(
+      "invalid_content",
+      `Template "${prepared.slug}" has no content for "${prepared.locale}"`,
+    );
+  }
+  const variables = params.variables ?? {};
+  const email = resolveEmail(localeContent, variables, "send");
+  const refused = refusedMissing(
+    params,
+    isBlocking,
+    email.missing,
+    missingSystemVariables(localeContent, prepared.category, variables),
+  );
+  if (refused.length) {
+    throw new SendError("missing_variables", refused.join(", "));
+  }
+  return { email, html: await renderEmailHtml(email, prepared.locale) };
+}
+
+export async function prepare(
   tenantId: string,
   slug: string,
-  params: SendTemplateParams,
+  params: ModuleSendParams,
 ): Promise<PreparedSend> {
   const template = await GetModel(TemplateModel, tenantId).getBySlug(slug);
   if (!template) {
@@ -131,23 +275,40 @@ async function prepare(
       `Template "${slug}" is ${template.status}`,
     );
   }
-  const content = params.content ?? parseContent(template);
+  const missing = missingManualVariables(template, params);
+  if (missing.length) {
+    throw new SendError("missing_variables", missing.join(", "));
+  }
+  const { content, version } = resolveContent(template, params);
   const settings = await getSettings(tenantId);
   return {
     content,
     locale: pickLocale(content, params.locale, settings.fallbackLocale),
+    requestedLocale: params.locale ?? "",
+    version,
     templateId: template._id,
     slug,
     tenantId,
+    category: template.category ?? "",
+    attention: template.attention,
   };
 }
 
-function messageFor(input: DeliveryInput, to: EmailAddress): EmailParams {
-  const { prepared, settings, subject, html } = input;
+/** The subject a recipient sees: a test says so before anything else. */
+export function subjectFor(subject: string, isTest: boolean): string {
+  return isTest ? `${TEST_SUBJECT_PREFIX}${subject}` : subject;
+}
+
+export function messageFor(
+  input: DeliveryInput,
+  to: EmailAddress,
+): EmailParams {
+  const { prepared, settings, subject, html, text } = input;
   return {
     to,
     subject,
     html,
+    text: text || undefined,
     from: settings.senderEmail
       ? { email: settings.senderEmail, name: settings.senderName || undefined }
       : undefined,
@@ -291,9 +452,12 @@ async function record(
     templateId: prepared.templateId,
     templateSlug: prepared.slug,
     locale: prepared.locale,
+    requestedLocale: prepared.requestedLocale,
+    templateVersion: prepared.version,
     recipientEmail: addressOf(to),
     recipientName: nameOf(to),
     status,
+    stage: stageOf(status),
     provider: outcome.provider,
     providerMessageId: outcome.providerMessageId,
     latencyMs: outcome.latencyMs,
@@ -379,7 +543,7 @@ export function aggregateResults(
 
 export async function sendTemplate(
   slug: string,
-  params: SendTemplateParams,
+  params: ModuleSendParams,
 ): Promise<SendTemplateResult> {
   const recipients = toRecipients(params.to);
   if (recipients.length === 0) {
@@ -387,23 +551,21 @@ export async function sendTemplate(
   }
   const prepared = await prepare(params.tenantId, slug, params);
   const settings = await getSettings(params.tenantId);
-  const localeContent = localeContentOf(prepared.content, prepared.locale);
-  if (!localeContent) {
-    throw new SendError(
-      "invalid_content",
-      `Template "${slug}" has no content for "${prepared.locale}"`,
-    );
-  }
-  const email = resolveEmail(localeContent, params.variables ?? {});
-  if (settings.blockOnMissingVariables && email.missing.length) {
-    throw new SendError("missing_variables", email.missing.join(", "));
-  }
+  const { email, html } = await renderForSend(
+    prepared,
+    params,
+    settings.blockOnMissingVariables,
+  );
   const delivered = await deliver({
     prepared,
     settings,
-    subject: email.subject,
-    html: await renderEmailHtml(email, prepared.locale),
+    subject: subjectFor(email.subject, Boolean(params.isTest)),
+    html,
+    text: renderPlainText(email, prepared.locale),
     recipients,
   });
-  return aggregateResults(await recordAll(prepared, params, delivered));
+  const results = await recordAll(prepared, params, delivered);
+  if (!params.isTest)
+    await refreshAttentionIfFlagged(params.tenantId, prepared, NEVER_SENT);
+  return aggregateResults(results);
 }

package/src/services/settings.ts

@@ -11,7 +11,7 @@ import {
   type TemplateCategory,
 } from "../types";
 
-const SECRET_BYTES = 24;
+export const WEBHOOK_SECRET_BYTES = 24;
 
 function defaults(): MailingSettingsValues {
   return {
@@ -21,7 +21,7 @@ function defaults(): MailingSettingsValues {
     senderName: "",
     senderEmail: "",
     replyTo: "",
-    webhookSecret: randomBytes(SECRET_BYTES).toString("hex"),
+    webhookSecret: randomBytes(WEBHOOK_SECRET_BYTES).toString("hex"),
     categories: DEFAULT_CATEGORIES,
   };
 }
@@ -48,9 +48,7 @@ function toRow(values: MailingSettingsValues): Partial<MailingSettings> {
 export async function findSettings(
   tenantId: string,
 ): Promise<MailingSettingsValues | undefined> {
-  const existing = await GetModel(SettingsModel, tenantId).getSingleton(
-    tenantId,
-  );
+  const existing = await GetModel(SettingsModel, tenantId).get(tenantId);
   return existing ? toValues(existing) : undefined;
 }
 
@@ -88,9 +86,8 @@ export async function saveSettings(
   values: MailingSettingsValues,
 ): Promise<MailingSettingsValues> {
   const model = GetModel(SettingsModel, tenantId);
-  const existing = await model.getSingleton(tenantId);
-  if (existing) await model.update(existing._id, toRow(values));
-  else if (!(await insertKeyedSettings(tenantId, values)))
+  const isStored = Boolean(await model.get(tenantId));
+  if (isStored || !(await insertKeyedSettings(tenantId, values)))
     await model.update(tenantId, toRow(values));
   return values;
 }
@@ -101,3 +98,50 @@ export function findCategory(
 ): TemplateCategory | undefined {
   return categories.find((category) => category.id === id);
 }
+
+/** What a send does when a variable it needs is missing. */
+export type MissingVariablesPolicy = "refuse" | "send";
+
+const REFUSE_POLICY: MissingVariablesPolicy = "refuse";
+const SEND_POLICY: MissingVariablesPolicy = "send";
+
+export function missingVariablesPolicy(
+  values: MailingSettingsValues,
+): MissingVariablesPolicy {
+  return values.blockOnMissingVariables ? REFUSE_POLICY : SEND_POLICY;
+}
+
+/** The form-only field folded back into `blockOnMissingVariables`. */
+const MISSING_VARIABLES_KEY = "missingVariables";
+const CLEARED_VALUE = "";
+/** The patch with each cleared field (`null`) as the empty value it stores. */
+export function clearedToEmpty(
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(patch).map(([key, value]) => [key, value ?? CLEARED_VALUE]),
+  );
+}
+
+/**
+ * The settings once `patch` (the fields a form changed, `null` for a cleared
+ * one) is laid over the stored ones, the missing-variables choice folded back
+ * into its boolean.
+ */
+export function mergeSettingsPatch(
+  current: MailingSettingsValues,
+  patch: Record<string, unknown>,
+): MailingSettingsValues {
+  const written = Object.fromEntries(
+    Object.entries(clearedToEmpty(patch)).filter(
+      ([key]) => key !== MISSING_VARIABLES_KEY,
+    ),
+  );
+  const policy = patch.missingVariables;
+  const isChoice = policy === REFUSE_POLICY || policy === SEND_POLICY;
+  const guard =
+    isChoice && !("blockOnMissingVariables" in patch)
+      ? { blockOnMissingVariables: policy === REFUSE_POLICY }
+      : {};
+  return { ...current, ...written, ...guard } as MailingSettingsValues;
+}