@antelopejs/dms-mailing 0.6.1 → 0.7.1

package/src/services/declarations.ts

@@ -1,26 +1,18 @@
 import { randomUUID } from "node:crypto";
 import type {
-  DeclarationOutcome,
   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,
@@ -29,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: string;
-  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(
@@ -104,212 +60,62 @@ 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: template.name,
-    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.insert({
-    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 as TemplateContent,
+          variables: declaration.variables,
+        },
+        author,
+      ),
+    });
+    template = await requireTemplate(model, id as string);
   } catch (error) {
-    if (await model.getBySlug(slug)) return undefined;
+    // A concurrent declaration of the slug created it first: expected, the
+    // caller goes on with that template.
+    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,
@@ -320,23 +126,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 as TemplateContent, 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>>();
 
@@ -358,84 +159,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

@@ -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-import.ts

@@ -170,7 +170,8 @@ interface EntryOutcome {
 /**
  * Writes one send: its events first, under ids derived from the send's, then
  * the send itself. A run stopped half-way leaves events no send shows yet,
- * which the next run completes; a send present means it was fully imported.
+ * which the next run completes; each write skips the row an earlier run
+ * wrote, and a send present means it was fully imported.
  */
 async function importOne(
   tenantId: string,
@@ -180,7 +181,6 @@ async function importOne(
 ): Promise<EntryOutcome> {
   const id = importedSendIdOf(tenantId, send.importId);
   const sends = GetModel(SendModel, tenantId);
-  if (await sends.get(id)) return { id, isImported: false };
   const timeline = timelineOf(send);
   const events = GetModel(SendEventModel, tenantId);
   for (const [index, entry] of timeline.entries()) {