@antelopejs/dms-mailing 0.7.0 → 0.7.1

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,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: 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 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,
@@ -321,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>>();
 
@@ -359,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/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()) {

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/templates.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { HTTPResult } from "@antelopejs/interface-api";
+import { IsDuplicateKeyError } from "@antelopejs/interface-database";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import {
-  DEFAULT_FALLBACK_LOCALE,
   HTTP_CONFLICT,
   HTTP_NOT_FOUND,
   LOCALE_LIST_SEPARATOR,
@@ -12,9 +12,7 @@ import {
   type MailingTemplateVersion,
   type TemplateFields,
   TemplateModel,
-  TemplateSlugModel,
   TemplateVersionModel,
-  templateSlugIdOf,
 } from "../db";
 import { diffContents, diffVariables, type TemplateChange } from "../engine";
 import {
@@ -28,6 +26,7 @@ import type {
   TemplateContent,
   VariableDefinition,
 } from "../types";
+import { DEFAULT_FALLBACK_LOCALE } from "../types";
 
 export interface TemplateAuthor {
   name?: string;
@@ -45,6 +44,7 @@ const STALE_DRAFT: TemplateAttentionReason = "stale_draft";
 const VERSION_NOT_FOUND = "$dms_mailing.errors.version_not_found";
 const TEMPLATE_NOT_FOUND = "$dms_mailing.errors.template_not_found";
 const DUPLICATE_SLUG = "$dms_mailing.errors.duplicate_slug";
+const SLUG_FIELD = "slug";
 
 /** The template `id` names; 404 when there is none. */
 export async function requireTemplate(
@@ -57,49 +57,18 @@ export async function requireTemplate(
 }
 
 /**
- * Gives `slug` to the template just inserted; false when another template
- * holds it. A claim whose template is gone (deleted before its claim was
- * freed) is taken over, through the same insert that settles a race.
+ * Runs a write that gives a template its slug, refused with a 409 when
+ * another template of the tenant holds it: the slug's unique index settles
+ * concurrent creations, so nothing reads the table before writing.
  */
-async function claimTemplateSlug(
-  tenantId: string,
-  slug: string,
-  templateId: string,
-): Promise<boolean> {
-  const claims = GetModel(TemplateSlugModel, tenantId);
-  const id = templateSlugIdOf(tenantId, slug);
-  if (await claims.insertClaim(id, slug, templateId)) return true;
-  const holder = await claims.get(id);
-  if (holder?.templateId === templateId) return true;
-  if (holder) {
-    const templates = GetModel(TemplateModel, tenantId);
-    if (await templates.get(holder.templateId)) return false;
-    await claims.dropClaimOf(id, holder.templateId);
+export async function refuseTakenSlug<T>(write: Promise<T>): Promise<T> {
+  try {
+    return await write;
+  } catch (error) {
+    if (IsDuplicateKeyError(error) && error.fields.includes(SLUG_FIELD))
+      throw new HTTPResult(HTTP_CONFLICT, DUPLICATE_SLUG);
+    throw error;
   }
-  return claims.insertClaim(id, slug, templateId);
-}
-
-/**
- * Keeps the template just inserted if it got its slug, or removes it again
- * and refuses it like any taken slug: two creations racing past the free-slug
- * check both insert, and only the claim's primary key tells them apart.
- */
-export async function assertSlugClaimed(
-  tenantId: string,
-  slug: string,
-  templateId: string,
-): Promise<void> {
-  if (await claimTemplateSlug(tenantId, slug, templateId)) return;
-  await GetModel(TemplateModel, tenantId).delete(templateId);
-  throw new HTTPResult(HTTP_CONFLICT, DUPLICATE_SLUG);
-}
-
-/** Frees the slugs of deleted templates for new ones. */
-export async function releaseTemplateSlugs(
-  tenantId: string,
-  templateIds: string[],
-): Promise<void> {
-  await GetModel(TemplateSlugModel, tenantId).releaseTemplates(templateIds);
 }
 
 /** The content customers receive: the last published version. */
@@ -528,6 +497,52 @@ export async function initializeTemplate(
   await refreshTemplateAttention(tenantId);
 }
 
+/** The first version a template publishes. */
+const FIRST_VERSION = 1;
+
+/**
+ * A new template, published at once as version 1 of `draft`: its content
+ * and its history entry land in the one write that creates it, so no reader
+ * ever sees it unpublished. Materialize its version row afterwards, as a
+ * publication does.
+ */
+export function publishedAtCreation(
+  id: string,
+  draft: TemplateDraft,
+  author: string,
+): TemplateFields {
+  const shipped: TemplateFields = {
+    json_content: JSON.stringify(draft.content),
+    json_variables: JSON.stringify(draft.variables),
+    locales: localesOf(draft.content),
+    publishedAt: new Date(),
+    publishedBy: author,
+  };
+  const changes = [
+    ...diffContents({ locales: {} }, draft.content),
+    ...diffVariables([], draft.variables),
+  ];
+  return {
+    _id: id,
+    ...shipped,
+    json_published_version: JSON.stringify({
+      ...shipped,
+      _id: randomUUID(),
+      templateId: id,
+      version: FIRST_VERSION,
+      json_changes: JSON.stringify(changes),
+    }),
+    json_draft: "",
+    json_variables_draft: "",
+    isDraftPending: false,
+    draftRevision: FIRST_DRAFT_REVISION,
+    status: "live",
+    publishedVersion: FIRST_VERSION,
+    updatedBy: author,
+    ...NO_ATTENTION,
+  };
+}
+
 export function blankFields(content: TemplateContent): TemplateFields {
   return {
     json_content: "",