@antelopejs/dms-mailing 0.5.0 → 0.6.0

package/src/db/models/template-versions.model.ts

@@ -1,23 +1,69 @@
 import { BasicDataModel } from "@antelopejs/interface-database-decorators";
 import {
   MAILING_TEMPLATE_VERSIONS_TABLE_NAME,
+  type MailingTemplate,
   MailingTemplateVersion,
 } from "../tables";
+import { TemplateModel } from "./templates.model";
+
+/** The latest committed history row, even before its separate insert completes. */
+export function committedVersionOf(
+  template: Pick<MailingTemplate, "json_published_version">,
+): MailingTemplateVersion | undefined {
+  if (!template.json_published_version) return undefined;
+  const row = JSON.parse(
+    template.json_published_version,
+  ) as MailingTemplateVersion;
+  row.publishedAt = new Date(row.publishedAt);
+  return row;
+}
 
 export class TemplateVersionModel extends BasicDataModel(
   MailingTemplateVersion,
   MAILING_TEMPLATE_VERSIONS_TABLE_NAME,
 ) {
+  /** Must complete before replacing the only recoverable snapshot of this version. */
+  async materialize(
+    template: Pick<MailingTemplate, "json_published_version">,
+  ): Promise<void> {
+    const version = committedVersionOf(template);
+    if (!version) return;
+    if (await this.get(version._id)) return;
+    try {
+      await this.insert(version);
+    } catch (error) {
+      const stored = await this.get(version._id);
+      if (
+        !stored ||
+        Object.entries(version).some(
+          ([key, value]) =>
+            JSON.stringify(stored[key as keyof MailingTemplateVersion]) !==
+            JSON.stringify(value),
+        )
+      )
+        throw error;
+    }
+  }
+
   async listForTemplate(templateId: string): Promise<MailingTemplateVersion[]> {
+    // Read the publication first: any later publication must have materialized it.
+    const template = await new TemplateModel(this.database).get(templateId);
+    if (!template) return [];
     const rows = await this.getBy("templateId", templateId);
-    return rows.sort((left, right) => right.version - left.version);
+    const current = committedVersionOf(template);
+    const history = rows.filter(
+      (row) => row.version <= template.publishedVersion,
+    );
+    if (current && !history.some((row) => row.version === current.version))
+      history.push(current);
+    return history.sort((left, right) => right.version - left.version);
   }
 
   async getVersion(
     templateId: string,
     version: number,
   ): Promise<MailingTemplateVersion | undefined> {
-    const rows = await this.getBy("templateId", templateId);
+    const rows = await this.listForTemplate(templateId);
     return rows.find((row) => row.version === version);
   }
 }

package/src/db/models/templates.model.ts

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { BasicDataModel } from "@antelopejs/interface-database-decorators";
 import { MAILING_TEMPLATES_TABLE_NAME, MailingTemplate } from "../tables";
+import { TemplateSlugModel } from "./template-slugs.model";
 
 /** The attention fields of a template, as the refresh writes them. */
 export type TemplateAttentionFields = Pick<
@@ -11,8 +13,37 @@ export class TemplateModel extends BasicDataModel(
   MailingTemplate,
   MAILING_TEMPLATES_TABLE_NAME,
 ) {
+  /** Publishes only over the exact semantic revision that was inspected. */
+  async publishIfCurrent(
+    template: MailingTemplate,
+    patch: Partial<MailingTemplate>,
+  ): Promise<boolean> {
+    const outcome = await this.table
+      .atomicMutation(template._id, {
+        type: "update",
+        revisionField: "revision",
+        expectedRevision: template.revision ?? { kind: "missing" },
+        nextRevision: randomUUID(),
+        patch: { ...patch, updatedAt: new Date() },
+      })
+      .run();
+    if (outcome === "unknown")
+      throw new Error("Mailing publication outcome is unknown; not retrying");
+    return outcome === "applied";
+  }
+
   async getBySlug(slug: string): Promise<MailingTemplate | undefined> {
     const rows = await this.getBy("slug", slug);
+    // A losing creation can still be cleaning up (or its process can crash).
+    // Senders must see the claimed template, not an earlier draft candidate.
+    if (rows.length > 1) {
+      const claims = await new TemplateSlugModel(this.database).getBy(
+        "templateId",
+        ...rows.map((row) => row._id),
+      );
+      const claim = claims.find((candidate) => candidate.slug === slug);
+      if (claim) return rows.find((row) => row._id === claim.templateId);
+    }
     return rows[0];
   }
 

package/src/db/tables/index.ts

@@ -2,6 +2,7 @@ export * from "./send-events.table";
 export * from "./sends.table";
 export * from "./settings.table";
 export * from "./suppressions.table";
+export * from "./template-slugs.table";
 export * from "./template-versions.table";
 export * from "./templates.table";
 export * from "./webhook-status.table";

package/src/db/tables/settings.table.ts

@@ -46,4 +46,12 @@ export class MailingSettings extends Table {
 
   @Field("string")
   declare webhookSecret: string;
+
+  /**
+   * JSON-serialized fingerprint of each category `DeclareTemplateCategory`
+   * applied, by its id: what tells a category untouched since from one a
+   * user relabelled or removed.
+   */
+  @Field("string")
+  declare json_declared_categories?: string;
 }

package/src/db/tables/template-slugs.table.ts

@@ -0,0 +1,29 @@
+import {
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+
+export const MAILING_TEMPLATE_SLUGS_TABLE_NAME = "mailing_template_slugs";
+
+/**
+ * The template a slug belongs to. Its id derives from the tenant and the
+ * slug, so the primary key is what keeps a slug to one template: the database
+ * interface declares no unique secondary index, and two creations racing
+ * past the free-slug check both insert their template, but only one claim.
+ */
+@RegisterTable(MAILING_TEMPLATE_SLUGS_TABLE_NAME, TENANT_SCHEMA_NAME)
+export class MailingTemplateSlug extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  declare slug: string;
+
+  /** The template holding the slug; a deleted one leaves the claim free. */
+  @Index()
+  @Field("string")
+  declare templateId: string;
+}

package/src/db/tables/templates.table.ts

@@ -1,7 +1,10 @@
+import { randomUUID } from "node:crypto";
 import {
+  attachModifier,
   CreationTime,
   Field,
   Index,
+  Modifier,
   RegisterTable,
   Table,
   UpdateTime,
@@ -128,4 +131,39 @@ export class MailingTemplate extends Table {
   /** When the template last left `live` by an unpublish. */
   @Field("date")
   declare unpublishedAt?: Date;
+
+  /**
+   * Fingerprint of the last declaration `DeclareTemplate` applied; blank for
+   * a template made in the dashboard. A template still matching it is
+   * untouched since, and the next declaration may refresh it.
+   */
+  @Field("string")
+  declare declaredHash?: string;
+
+  /** Every semantic edit invalidates a publication's optimistic snapshot. */
+  @Field("string")
+  declare revision?: string;
+
+  /** An unmodified declaration seed can be completed after a crashed creator. */
+  @Field("string")
+  declare declarationSeedRevision?: string;
+
+  @Field("string")
+  declare pendingDeclaredHash?: string;
+
+  /**
+   * Complete latest version row, committed atomically with its content. Its
+   * history row can be recovered after an interrupted publication.
+   */
+  @Field("string")
+  declare json_published_version?: string;
+}
+
+/** Covers model updates and generated data-api edits in the same database write. */
+class TemplateRevisionModifier extends Modifier {
+  update(object: Record<string, unknown>, field: string): void {
+    object[field] = randomUUID();
+  }
 }
+
+attachModifier(MailingTemplate, TemplateRevisionModifier, "revision", {});

package/src/hooks/database-ready.ts

@@ -0,0 +1,47 @@
+import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
+
+/** A promise opened once, and the calls that wait for it. */
+export interface ReadyGate {
+  open(): void;
+  /** `task`, run once the gate is open. */
+  after<Args extends unknown[], Result>(
+    task: (...args: Args) => Promise<Result>,
+  ): (...args: Args) => Promise<Result>;
+}
+
+export function createReadyGate(): ReadyGate {
+  let open: () => void = () => undefined;
+  const opened = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  return {
+    open: () => open(),
+    after:
+      (task) =>
+      async (...args) => {
+        await opened;
+        return task(...args);
+      },
+  };
+}
+
+/**
+ * Opens once the DMS reports its schemas registered, which it does from its
+ * own `start()`. Modules construct and start in parallel, so a project
+ * declaring its content early waits here instead of failing.
+ */
+const databaseGate = createReadyGate();
+
+/**
+ * The DMS fires the hook on every start and runs a handler registered after
+ * that at once: whatever the load order, the first firing opens the gate.
+ * Its handlers run in series, so this one is registered first thing in
+ * `construct()`, ahead of handlers that may wait on the gate.
+ */
+export function registerDatabaseReady(): void {
+  RegisterHook(Hook.DATABASE_INITIALIZED, () => databaseGate.open());
+}
+
+/** `task`, run once the database is ready. */
+export const afterDatabaseReady: ReadyGate["after"] = (task) =>
+  databaseGate.after(task);

package/src/hooks/index.ts

@@ -1 +1,2 @@
+export * from "./database-ready";
 export * from "./tenant-export";

package/src/implementations/dms-mailing/index.ts

@@ -1,2 +1,19 @@
+import { afterDatabaseReady } from "../../hooks/database-ready";
+import {
+  declareTemplate,
+  declareTemplateCategory,
+} from "../../services/declarations";
+import { importSends } from "../../services/send-import";
+
 export { recordEmailEvent as RecordEmailEvent } from "../../services/events";
 export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send";
+
+/*
+ * Projects call these from their `start()`, which runs in parallel with the
+ * DMS's: they wait for the database the DMS opens there rather than fail.
+ */
+export const DeclareTemplate = afterDatabaseReady(declareTemplate);
+export const DeclareTemplateCategory = afterDatabaseReady(
+  declareTemplateCategory,
+);
+export const ImportSends = afterDatabaseReady(importSends);

package/src/index.ts

@@ -16,7 +16,11 @@ import {
   scheduleJob,
   stopJob,
 } from "./crons";
-import { registerTenantExport, unregisterTenantExport } from "./hooks";
+import {
+  registerDatabaseReady,
+  registerTenantExport,
+  unregisterTenantExport,
+} from "./hooks";
 import { registerRealtimeTopics } from "./realtime";
 import { WEBHOOK_SECRET_HEADER } from "./services/webhook-status";
 
@@ -44,6 +48,7 @@ const PROVIDER_WEBHOOK_ENDPOINT = {
 let scheduledJobs: ScheduledJob[] = [];
 
 export async function construct(config: DmsMailingConfig = {}): Promise<void> {
+  registerDatabaseReady();
   setConfig(config);
   ImplementInterface(
     await import("@antelopejs/interface-dms-mailing"),

package/src/routes/templates.ts

@@ -37,6 +37,7 @@ import {
   type TemplateStats,
 } from "../services/template-stats";
 import {
+  assertSlugClaimed,
   contentFieldsOf,
   contentOfVersion,
   discardDraft,
@@ -536,6 +537,7 @@ export class TemplatesController extends Controller(
       ...contentFieldsOf(source),
       updatedBy: this.author,
     });
+    await assertSlugClaimed(this.tenantId, slug, copyId as string);
     await refreshTemplateAttention(this.tenantId);
     return { id: copyId };
   }

package/src/services/declaration-error.ts

@@ -0,0 +1,39 @@
+import type { ZodError, ZodType, ZodTypeDef } from "zod";
+
+/**
+ * Why a call made from code (a declaration, an import) was refused: `code`
+ * names the rule, like `SendError` does for a send, and the message says
+ * which field broke it.
+ */
+export class DeclarationError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const ISSUE_SEPARATOR = "; ";
+const ROOT_PATH = "(root)";
+
+function describeIssues(error: ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.join(".") || ROOT_PATH}: ${issue.message}`)
+    .join(ISSUE_SEPARATOR);
+}
+
+/** `input` parsed by `schema`, or a `DeclarationError` under `code`. */
+export function parseDeclared<Output, Input>(
+  schema: ZodType<Output, ZodTypeDef, Input>,
+  input: unknown,
+  code: string,
+  subject: string,
+): Output {
+  const parsed = schema.safeParse(input);
+  if (parsed.success) return parsed.data;
+  throw new DeclarationError(
+    code,
+    `Invalid ${subject}: ${describeIssues(parsed.error)}`,
+  );
+}