@antelopejs/dms-mailing 0.7.0 → 0.8.0

package/src/services/declarations.ts

@@ -1,27 +1,18 @@
 import { randomUUID } from "node:crypto";
 import type {
-  DeclarationOutcome,
-  LocalizedText,
   DeclareTemplateCategoryResult,
   DeclareTemplateResult,
   TemplateCategoryDeclaration,
   TemplateDeclaration,
 } from "@antelopejs/interface-dms-mailing";
-import { Logging } from "@antelopejs/interface-core/logging";
+import { IsDuplicateKeyError } from "@antelopejs/interface-database";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import {
   type MailingTemplate,
-  SettingsModel,
   TemplateModel,
-  TemplateSlugModel,
   TemplateVersionModel,
-  templateSlugIdOf,
 } from "../db";
-import type {
-  TemplateCategory,
-  TemplateContent,
-  VariableDefinition,
-} from "../types";
+import type { TemplateCategory, TemplateContent } from "../types";
 import {
   categoryDeclarationSchema,
   type ParsedCategoryDeclaration,
@@ -30,54 +21,18 @@ import {
 } from "../validation/declarations.schema";
 import { categoriesSchema } from "../validation/settings.schema";
 import { DeclarationError, parseDeclared } from "./declaration-error";
-import { fingerprintOf } from "./fingerprint";
 import { findCategory, getSettings, saveSettings } from "./settings";
+import { refreshTemplateAttention } from "./template-attention";
 import {
-  assertSlugClaimed,
-  blankFields,
-  hasDraft,
   localesWithoutSubject,
-  parseContent,
-  parseTestData,
-  parseVariables,
   publishedVersionOf,
-  publishSnapshot,
+  publishedAtCreation,
   requireTemplate,
-  workingContent,
-  workingVariables,
 } from "./templates";
 
 /** Who a declaration's writes are shown as by default. */
 const DECLARATION_AUTHOR = "system";
 
-const LIVE_STATUS = "live";
-const LOG_PREFIX = "[dms-mailing]";
-const MAX_DECLARATION_ATTEMPTS = 5;
-
-/** What a declaration fingerprints: everything a user may change after it. */
-interface DeclaredTemplateState {
-  name: LocalizedText;
-  category: string;
-  content: TemplateContent;
-  variables: VariableDefinition[];
-  testData: Record<string, unknown>;
-}
-
-/** A declaration ready to write: validated, defaulted and fingerprinted. */
-interface TemplatePlan {
-  tenantId: string;
-  slug: string;
-  state: DeclaredTemplateState;
-  author: string;
-  hash: string;
-}
-
-/**
- * The values as the database gives them back: a `Date` in the test data is
- * stored as its ISO string, and the fingerprint must compare alike.
- */
-const asStored = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
-
 function assertPublishable(content: TemplateContent, slug: string): void {
   if (!Object.keys(content.locales).length)
     throw new DeclarationError(
@@ -105,212 +60,60 @@ function assertKnownCategory(
   );
 }
 
-function planTemplate(declaration: ParsedTemplateDeclaration): TemplatePlan {
-  const { tenantId } = declaration;
-  const { slug } = declaration;
-  const state = asStored<DeclaredTemplateState>({
-    name: declaration.name,
-    category: declaration.category,
-    content: declaration.content as TemplateContent,
-    variables: declaration.variables,
-    testData: declaration.testData,
-  });
-  assertPublishable(state.content, slug);
-  return {
-    tenantId,
-    slug,
-    state,
-    author: declaration.author ?? DECLARATION_AUTHOR,
-    hash: fingerprintOf(state),
-  };
-}
-
-/**
- * The fingerprint of what the template holds now, `null` when a user took it
- * out of the state a declaration leaves it in: live, with no draft waiting.
- */
-function currentFingerprint(template: MailingTemplate): string | null {
-  if (template.status !== LIVE_STATUS || hasDraft(template)) return null;
-  return fingerprintOf({
-    name: TemplateModel.namesOf(template),
-    category: template.category ?? "",
-    content: parseContent(template),
-    variables: parseVariables(template),
-    testData: parseTestData(template),
-  });
-}
-
 function resultOf(
   template: MailingTemplate,
-  outcome: DeclarationOutcome,
-  version = publishedVersionOf(template),
+  outcome: DeclareTemplateResult["outcome"],
 ): DeclareTemplateResult {
   return {
     templateId: template._id,
     slug: template.slug,
     outcome,
-    version,
+    version: publishedVersionOf(template),
   };
 }
 
 /**
- * Inserts the template as a fresh draft of the declared content, claims its
- * slug like the dashboard's creation does. The seed is not an applied
- * declaration: any caller can finish its first publication after a crash.
+ * Inserts the declared template already published, as version 1, in one
+ * write. `undefined` when a concurrent call created the slug first (the slug
+ * index is unique): that call's row is published too.
  */
 async function createDeclared(
-  plan: TemplatePlan,
+  declaration: ParsedTemplateDeclaration,
 ): Promise<MailingTemplate | undefined> {
-  const { tenantId, slug, state, author } = plan;
+  const { tenantId, slug } = declaration;
   const model = GetModel(TemplateModel, tenantId);
-  const settings = await getSettings(tenantId);
-  assertKnownCategory(settings.categories, state.category, slug);
-  const revision = randomUUID();
-  const [id] = await model.insertFields({
-    slug,
-    name: state.name,
-    category: state.category,
-    status: "draft",
-    ...blankFields(state.content),
-    json_variables: JSON.stringify(state.variables),
-    json_test_data: JSON.stringify(state.testData),
-    updatedBy: author,
-    revision,
-    declarationSeedRevision: revision,
-    pendingDeclaredHash: plan.hash,
-  });
-  const templateId = id as string;
+  const author = declaration.author ?? DECLARATION_AUTHOR;
+  let template: MailingTemplate;
   try {
-    await assertSlugClaimed(tenantId, slug, templateId);
+    const [id] = await model.insertFields({
+      slug,
+      name: declaration.name,
+      category: declaration.category,
+      json_test_data: JSON.stringify(declaration.testData),
+      ...publishedAtCreation(
+        randomUUID(),
+        {
+          content: declaration.content,
+          variables: declaration.variables,
+        },
+        author,
+      ),
+    });
+    template = await requireTemplate(model, id);
   } catch (error) {
-    if (await model.getBySlug(slug)) return undefined;
+    if (IsDuplicateKeyError(error)) return undefined;
     throw error;
   }
-  return requireTemplate(model, templateId);
+  await GetModel(TemplateVersionModel, tenantId).materialize(template);
+  await refreshTemplateAttention(tenantId);
+  return template;
 }
 
 /**
- * A slug claim, not an arbitrary candidate row, decides which template won
- * concurrent creation. An unclaimed seed can be claimed by its next caller.
- */
-async function declaredTemplate(
-  tenantId: string,
-  slug: string,
-): Promise<MailingTemplate | undefined> {
-  const model = GetModel(TemplateModel, tenantId);
-  const claim = await GetModel(TemplateSlugModel, tenantId).get(
-    templateSlugIdOf(tenantId, slug),
-  );
-  const winner = claim && (await model.get(claim.templateId));
-  return winner || model.getBySlug(slug);
-}
-
-function isUnmodifiedSeed(template: MailingTemplate): boolean {
-  return Boolean(
-    template.pendingDeclaredHash &&
-    template.declarationSeedRevision &&
-    template.revision === template.declarationSeedRevision &&
-    template.status === "draft" &&
-    template.publishedVersion === 0,
-  );
-}
-
-/** Finishes the stored seed, never substituting a later caller's declaration. */
-async function finishSeed(
-  tenantId: string,
-  template: MailingTemplate,
-): Promise<boolean> {
-  try {
-    await assertSlugClaimed(tenantId, template.slug, template._id);
-  } catch (error) {
-    const winner = await declaredTemplate(tenantId, template.slug);
-    if (winner && winner._id !== template._id) return false;
-    throw error;
-  }
-  const settings = await getSettings(tenantId);
-  assertKnownCategory(settings.categories, template.category, template.slug);
-  return Boolean(
-    await publishSnapshot(
-      tenantId,
-      template,
-      {
-        content: workingContent(template),
-        variables: workingVariables(template),
-      },
-      template.updatedBy,
-      {
-        declaredHash: template.pendingDeclaredHash,
-        pendingDeclaredHash: "",
-        declarationSeedRevision: "",
-      },
-    ),
-  );
-}
-
-/** Why an existing template is left alone, `null` when it may be refreshed. */
-function keepReason(template: MailingTemplate): string | null {
-  if (!template.declaredHash) return "it was created in the dashboard";
-  if (currentFingerprint(template) !== template.declaredHash)
-    return "a user changed it since it was declared";
-  return null;
-}
-
-async function applyToExisting(
-  plan: TemplatePlan,
-  template: MailingTemplate,
-): Promise<DeclareTemplateResult> {
-  const { tenantId, state, author } = plan;
-  for (let attempt = 0; attempt < MAX_DECLARATION_ATTEMPTS; attempt++) {
-    if (isUnmodifiedSeed(template)) {
-      const created = await finishSeed(tenantId, template);
-      if (created && template.pendingDeclaredHash === plan.hash)
-        return resultOf(template, "created", 1);
-    } else {
-      await GetModel(TemplateVersionModel, tenantId).materialize(template);
-      if (template.publishedVersion > 0 && template.declaredHash === plan.hash)
-        return resultOf(template, "unchanged");
-      const reason = keepReason(template);
-      if (reason) {
-        Logging.Info(
-          `${LOG_PREFIX} Kept template "${plan.slug}" as it is: ${reason}`,
-        );
-        return resultOf(template, "kept");
-      }
-      const settings = await getSettings(tenantId);
-      assertKnownCategory(settings.categories, state.category, plan.slug);
-      const outcome = await publishSnapshot(tenantId, template, state, author, {
-        name: state.name,
-        category: state.category,
-        json_test_data: JSON.stringify(state.testData),
-        declaredHash: plan.hash,
-      });
-      if (outcome) return resultOf(template, "updated", outcome.version);
-    }
-    const current = await declaredTemplate(tenantId, plan.slug);
-    if (!current) break;
-    template = current;
-  }
-  throw new DeclarationError(
-    "declaration_conflict",
-    `Template "${plan.slug}" changed repeatedly; retry the declaration`,
-  );
-}
-
-/**
- * Creates or refreshes the template a project declares from code. The rule,
- * keyed on the slug:
- *
- * - no template has the slug: it is created and published (`created`);
- * - the declaration is the one last applied: nothing is written
- *   (`unchanged`), whatever a user did to the template since;
- * - the declaration changed and the template is still live, with no draft,
- *   and holds exactly what the last declaration wrote (name, category,
- *   content, variables, test data): the new declaration is published
- *   (`updated`);
- * - otherwise (edited, unpublished, archived, a draft pending, or made in the
- *   dashboard): it is left as it is (`kept`).
- *
- * A declared template a user deleted is created again by the next call.
+ * Writes a template a project ships as code, once: call it when the tenant
+ * is provisioned. A new slug is created and published (`created`). A slug the
+ * tenant already has is left as it is (`kept`): from its creation on, the
+ * template belongs to the tenant, and a later declaration never changes it.
  */
 export async function declareTemplate(
   input: TemplateDeclaration,
@@ -321,23 +124,18 @@ export async function declareTemplate(
     "invalid_template",
     `template declaration "${String(input?.slug)}"`,
   );
-  const plan = planTemplate(declaration);
-  const existing = await declaredTemplate(plan.tenantId, plan.slug);
-  if (existing) return applyToExisting(plan, existing);
-  const created = await createDeclared(plan);
-  if (created) return applyToExisting(plan, created);
-  const winner = (await declaredTemplate(
-    plan.tenantId,
-    plan.slug,
-  )) as MailingTemplate;
-  return applyToExisting(plan, winner);
+  const { tenantId, slug } = declaration;
+  assertPublishable(declaration.content, slug);
+  const model = GetModel(TemplateModel, tenantId);
+  const existing = await model.getBySlug(slug);
+  if (existing) return resultOf(existing, "kept");
+  const settings = await getSettings(tenantId);
+  assertKnownCategory(settings.categories, declaration.category, slug);
+  const created = await createDeclared(declaration);
+  if (created) return resultOf(created, "created");
+  return resultOf((await model.getBySlug(slug)) as MailingTemplate, "kept");
 }
 
-type DeclaredCategories = Record<string, string>;
-
-const categoryFingerprint = (category: Omit<TemplateCategory, "id">) =>
-  fingerprintOf({ label: category.label, icon: category.icon });
-
 /** Category declarations of one tenant run one after the other. */
 const categoryQueues = new Map<string, Promise<unknown>>();
 
@@ -359,84 +157,30 @@ function inTenantQueue<T>(
   return next;
 }
 
-async function readDeclaredCategories(
-  tenantId: string,
-): Promise<DeclaredCategories> {
-  const row = await GetModel(SettingsModel, tenantId).get(tenantId);
-  return JSON.parse(
-    row?.json_declared_categories || "{}",
-  ) as DeclaredCategories;
-}
-
-/** The category list once the declared category is added or relabelled. */
-function withCategory(
-  categories: TemplateCategory[],
-  declared: TemplateCategory,
-): TemplateCategory[] {
-  const isPresent = Boolean(findCategory(categories, declared.id));
-  const next = isPresent
-    ? categories.map((category) =>
-        category.id === declared.id ? declared : category,
-      )
-    : [...categories, declared];
-  return parseDeclared(
-    categoriesSchema,
-    next,
-    "invalid_category",
-    `category declaration "${declared.id}"`,
-  ).map(({ id, label, icon }) => ({ id, label, icon }));
-}
-
-/** What a category declaration does to the stored list, by its state. */
-function categoryOutcome(
-  current: TemplateCategory | undefined,
-  previousHash: string | undefined,
-  hash: string,
-): DeclarationOutcome {
-  if (!current) return previousHash ? "kept" : "created";
-  if (!previousHash) return "kept";
-  if (previousHash === hash) return "unchanged";
-  return categoryFingerprint(current) === previousHash ? "updated" : "kept";
-}
-
-const WRITING_OUTCOMES = new Set<DeclarationOutcome>(["created", "updated"]);
-
 async function applyCategory(
   declaration: ParsedCategoryDeclaration,
 ): Promise<DeclareTemplateCategoryResult> {
-  const { tenantId } = declaration;
-  const category = {
-    id: declaration.id,
-    label: declaration.label,
-    icon: declaration.icon,
-  };
-  const hash = categoryFingerprint(category);
+  const { tenantId, id, label, icon } = declaration;
   const settings = await getSettings(tenantId);
-  const declared = await readDeclaredCategories(tenantId);
-  const outcome = categoryOutcome(
-    findCategory(settings.categories, category.id),
-    declared[category.id],
-    hash,
-  );
-  if (!WRITING_OUTCOMES.has(outcome)) return { id: category.id, outcome };
-  const categories = withCategory(settings.categories, category);
+  if (findCategory(settings.categories, id)) return { id, outcome: "kept" };
+  const categories = parseDeclared(
+    categoriesSchema,
+    [...settings.categories, { id, label, icon }],
+    "invalid_category",
+    `category declaration "${id}"`,
+  ).map((category) => ({
+    id: category.id,
+    label: category.label,
+    icon: category.icon,
+  }));
   await saveSettings(tenantId, { ...settings, categories });
-  await GetModel(SettingsModel, tenantId).update(tenantId, {
-    json_declared_categories: JSON.stringify({
-      ...declared,
-      [category.id]: hash,
-    }),
-  });
-  return { id: category.id, outcome };
+  return { id, outcome: "created" };
 }
 
 /**
- * Adds or refreshes a template category a project declares from code, keyed
- * on its id: a new id is added (`created`); the declaration last applied is
- * left alone (`unchanged`); a changed declaration relabels a category still
- * as last declared (`updated`); a category a user relabelled or removed
- * since, or one that existed before any declaration (the defaults among
- * them), is left as it is (`kept`).
+ * Adds a template category a project ships as code, once: call it when the
+ * tenant is provisioned. A new id is added (`created`); an id the workspace
+ * settings already hold, the defaults among them, is left as it is (`kept`).
  */
 export function declareTemplateCategory(
   input: TemplateCategoryDeclaration,

package/src/services/events.ts

@@ -16,6 +16,7 @@ import { publishSendUpdated } from "../realtime";
 import type { SendEventType, SendStatus } from "../types";
 import { notifyProblems } from "./notify";
 import { suppressAddress, suppressionReasonOf } from "./suppressions";
+import { isObject, isText } from "../validation/guards";
 
 export interface SendCounters {
   status: SendStatus;
@@ -59,8 +60,11 @@ const HARD_BOUNCE_TYPE = /hard|permanent/i;
 /** A temporary SMTP answer: a `4xx` reply code or a `4.x.x` enhanced status. */
 const SOFT_SMTP_ANSWER = /^\s*4\d\d\b|\b4\.\d{1,3}\.\d{1,3}\b/;
 
-const textOf = (value: unknown): string =>
-  typeof value === "string" ? value : "";
+/** The text an event's details hold under `key`, else an empty string. */
+function textOf(details: EmailEvent["details"], key: string): string {
+  const value = details?.[key];
+  return isText(value) ? value : "";
+}
 
 /**
  * The provider's own words for a problem event (`550 5.1.1 Mailbox does not
@@ -70,7 +74,7 @@ const textOf = (value: unknown): string =>
 export function problemReason(event: EmailEvent): string | undefined {
   if (!PROBLEM_EVENTS.has(event.type)) return undefined;
   const reason = event.details?.reason;
-  return typeof reason === "string" && reason ? reason : undefined;
+  return isText(reason) && reason ? reason : undefined;
 }
 
 function overridesStatus(current: SendStatus, next: SendStatus): boolean {
@@ -95,10 +99,10 @@ export function applyEvent(
  * provider's `bounceType` when it gives one, else the SMTP answer's class.
  */
 export function isSoftBounce(event: EmailEvent): boolean {
-  const bounceType = textOf(event.details?.bounceType);
+  const bounceType = textOf(event.details, "bounceType");
   if (SOFT_BOUNCE_TYPE.test(bounceType)) return true;
   if (HARD_BOUNCE_TYPE.test(bounceType)) return false;
-  return SOFT_SMTP_ANSWER.test(textOf(event.details?.reason));
+  return SOFT_SMTP_ANSWER.test(textOf(event.details, "reason"));
 }
 
 /**
@@ -144,8 +148,8 @@ async function publishEmailEvent(
   });
 }
 
-const eventIdOf = (details: Record<string, unknown> | undefined): string =>
-  textOf(details?.eventId);
+const eventIdOf = (details: EmailEvent["details"]): string =>
+  textOf(details, "eventId");
 
 type StoredEventIdentity = Pick<
   MailingSendEvent,
@@ -163,11 +167,10 @@ export function isSameEvent(
 ): boolean {
   const eventId = eventIdOf(event.details);
   if (eventId) {
-    const storedDetails = JSON.parse(stored.json_details || "{}") as Record<
-      string,
-      unknown
-    >;
-    return eventIdOf(storedDetails) === eventId;
+    const storedDetails: unknown = JSON.parse(stored.json_details || "{}");
+    return (
+      eventIdOf(isObject(storedDetails) ? storedDetails : undefined) === eventId
+    );
   }
   if (!event.at || stored.type !== event.type) return false;
   return (
@@ -223,7 +226,7 @@ async function suppressAfterEvent(
       email: send.recipientEmail,
       reason,
       sendId: send._id,
-      detail: textOf(event.details?.reason) || undefined,
+      detail: textOf(event.details, "reason") || undefined,
     });
   } catch (error) {
     Logging.Error("[dms-mailing] Could not suppress an address:", error);

package/src/services/localized-text.ts

@@ -1,8 +1,10 @@
+import type { IncomingHttpHeaders } from "node:http";
 import type { RequestContext } from "@antelopejs/interface-api";
 import {
   LOCALIZED_TEXT_FALLBACK_LOCALE,
   type LocalizedText,
 } from "@antelopejs/interface-dms-mailing";
+import { isText } from "../validation/guards";
 
 /** Header the DMS frontend states the reader's language in on every request. */
 export const CONTENT_LANGUAGE_HEADER = "x-content-language";
@@ -13,8 +15,8 @@ export const CONTENT_LANGUAGE_HEADER = "x-content-language";
  *
  * @param header Value of {@link CONTENT_LANGUAGE_HEADER}
  */
-export function requestLocale(header: unknown): string {
-  return typeof header === "string" && header.length > 0
+export function requestLocale(header: IncomingHttpHeaders[string]): string {
+  return isText(header) && header.length > 0
     ? header
     : LOCALIZED_TEXT_FALLBACK_LOCALE;
 }

package/src/services/metrics.ts

@@ -122,7 +122,7 @@ const wasOpened = (send: SendSummary): boolean =>
 function median(values: number[]): number {
   if (!values.length) return 0;
   const sorted = [...values].sort((left, right) => left - right);
-  return sorted[Math.floor(sorted.length / 2)] as number;
+  return sorted[Math.floor(sorted.length / 2)];
 }
 
 /** A send to a suppressed address never left: no figure counts it. */
@@ -262,7 +262,7 @@ export function alignSeries(
   axis: SeriesPoint[],
 ): SeriesPoint[] {
   return points.slice(0, axis.length).map((point, index) => ({
-    x: (axis[index] as SeriesPoint).x,
+    x: axis[index].x,
     y: point.y,
   }));
 }

package/src/services/notify.ts

@@ -38,7 +38,7 @@ const PERCENT = 100;
 const SENDS_PAGE = "/modules/mailing/sends";
 const PROBLEMS_VIEW = "problems";
 const IDEMPOTENCY_KEY_SEPARATOR = ":";
-// The DMS keys notifications across every module: ours carry the module's name.
+/** The DMS keys notifications across every module: ours carry the module's name. */
 const IDEMPOTENCY_KEY_PREFIX = "mailing:problems";
 const PROBLEMS_ICON = "i-ph-warning";
 const PROBLEMS_TITLE = "$dms_mailing.notifications.problems_title";

package/src/services/render.ts

@@ -17,13 +17,17 @@ export interface MailingEmailProps {
 const MailingEmailTemplate =
   RegisterHtmlTemplate<MailingEmailProps>(EMAIL_TEMPLATE_NAME);
 
+/**
+ * The HTML of `email`: through the DMS renderer, which already drops Vue's
+ * SSR markers (dms-frontend 0.5.4), else the module's fallback HTML when the
+ * configuration turns HTML rendering off or the renderer fails.
+ */
 export async function renderEmailHtml(
   email: ResolvedEmail,
   locale: string,
 ): Promise<string> {
   if (!getConfig().useHtmlRender) return renderFallbackHtml(email, locale);
   try {
-    // The DMS renderer already drops Vue's SSR markers (dms-frontend 0.5.4).
     return await GenerateHtml(MailingEmailTemplate, { locale, email });
   } catch (error) {
     Logging.Warn(