@antelopejs/dms-mailing 0.5.0 → 0.5.1

package/skills/dms-mailing/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: dms-mailing
+description: Sends and manages transactional e-mail with the @antelopejs/dms-mailing module of the AntelopeJS DMS. Use when installing or configuring dms-mailing, sending a template from code with SendTemplate, reporting provider events with RecordEmailEvent or the webhook, designing templates (blocks, variables, locales, versions), or debugging suppressed, refused, missing-variable or fallback-locale sends.
+icon: i-lucide-mail
+category: messaging
+tags: [email, templates, transactional, webhook, dms-module]
+---
+
+# dms-mailing
+
+Templates edited in the dashboard, sent by slug from code, logged with provider events.
+Pages under `/modules/mailing` (owner-only): Overview, Templates, editor (`templates/:id`), Sends,
+Settings, Suppression list. User docs: `docs/` of this package, published at
+https://dms.antelopejs.com/docs/modules/mailing (sending from code and the webhook format: `extending`).
+
+## When to reach for it
+
+- Code must send an e-mail a non-developer can reword, translate or restyle: create a template, call it by slug.
+  Hard-coding HTML in a route is the path this module replaces.
+- Delivery must be traceable (bounces, opens, clicks) or addresses must stop receiving after a hard bounce.
+
+## Setup
+
+- `ajs project modules add @antelopejs/dms-mailing`, plus a module implementing `@antelopejs/interface-email`
+  (`@antelopejs/nodemailer`, `config: { ethereal: true }` in dev).
+- Mailing 0.5 requires `@antelopejs/dms` >=0.9 (interface-dms 0.7, renderer `@antelopejs/dms-frontend` 0.6);
+  0.4 is the DMS 0.8 line. `@antelopejs/interface-dms-mailing` stays 0.7, so callers do not change.
+- Module option: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML).
+- Set the DMS `clientBaseUrl`: the webhook URL and the e-mail logo are built on it.
+- Per-workspace settings (sender, missing-variable guard, fallback locale, webhook secret, retention,
+  categories) live on the Settings page and `GET`/`PUT /api/mailing/settings` (changed fields only).
+
+## Send from code
+
+```typescript
+import { SendTemplate, RecordEmailEvent } from "@antelopejs/interface-dms-mailing";
+
+const result = await SendTemplate("order-confirmed", {
+  tenantId,
+  to: [{ email: "ana@example.com", name: "Ana" }], // one address or an array
+  locale: "fr",
+  variables: { customer: { firstName: "Ana" }, order: { number: "#1042" } },
+  source: "checkout", // shows as "Called from" in the template's performance
+});
+// result.status: queued | sent | ... | failed | suppressed; result.results[] per recipient
+```
+
+- Only the **published** version is sent; drafts go out only as tests (`[TEST]` subject, out of the figures).
+- Variables are typed (`string`, `text`, `number`, `money`, `date`, `url`, `boolean`, `array`) and declared on
+  the template; pass every required one.
+- In-process events: `RecordEmailEvent(tenantId, { provider, messageId, type, details })`.
+  HTTP: `POST <clientBaseUrl>/api/mailing/events/<provider>/<tenantId>` with header `x-mailing-webhook-secret`.
+- Automation (if `interface-dms-automation` is loaded): action `mailing.send-template`, trigger `mailing.email-event`.
+
+## Gotchas
+
+- `status: "suppressed"` = address on the suppression list (hard bounce, spam, unsubscribe, manual). Never retry.
+- `marketing` templates whose footer shows unsubscribe/preferences links require `unsubscribeUrl` /
+  `preferencesUrl` in `variables`; a link without URL is dropped.
+- A missing locale falls back to the workspace's fallback locale (logged as `DE asked`).
+- The template slug is fixed at creation: code depends on it.
+- `mailing.send` permission gates every route that reaches recipients; writes publish on realtime topic `mailing:sends`.
+- 0.4+ does not read a 0.3 database and moved the webhook path (tenant in the URL).

package/src/data/templates-table.ts

@@ -55,11 +55,13 @@ import { findCategory, getSettings } from "../services/settings";
 import { findStarter, starterFields } from "../services/starters";
 import { refreshTemplateAttention } from "../services/template-attention";
 import {
+  assertSlugClaimed,
   blankContent,
   blankFields,
   contentFieldsOf,
   displayName,
   initializeTemplate,
+  releaseTemplateSlugs,
 } from "../services/templates";
 import type { TemplateCategory } from "../types";
 
@@ -142,29 +144,6 @@ function assertKnownCategory(
   throw new HTTPResult(HTTP_UNPROCESSABLE, UNKNOWN_CATEGORY);
 }
 
-const creationTime = (template: MailingTemplate) =>
-  new Date(template.createdAt).getTime();
-
-/**
- * Nothing in the database keeps slugs unique, so two creations racing past
- * the free-slug check both land: the earliest one stays, a later one is
- * removed again and refused like any taken slug.
- */
-async function assertFirstOfSlug(
-  model: TemplateModel,
-  slug: string,
-  templateId: string,
-): Promise<void> {
-  const [first] = (await model.getBy("slug", slug)).sort(
-    (left, right) =>
-      creationTime(left) - creationTime(right) ||
-      left._id.localeCompare(right._id),
-  );
-  if (!first || first._id === templateId) return;
-  await model.delete(templateId);
-  throw new HTTPResult(HTTP_CONFLICT, DUPLICATE_SLUG);
-}
-
 /** The creation's seed, and the body to store: slug and name trimmed. */
 function parseCreation(body: Buffer | string) {
   const raw = parseBody(body);
@@ -209,7 +188,7 @@ function withSeeding(base: DataControllerCallback): DataControllerCallback {
         ...rest,
       )) as string[];
       const templateId = ids[0] as string;
-      await assertFirstOfSlug(model, seed.slug, templateId);
+      await assertSlugClaimed(tenantId, seed.slug, templateId);
       const user = await authenticateTenantRequest(ctx);
       await initializeTemplate(tenantId, templateId, displayName(user), fields);
       return ids;
@@ -270,14 +249,15 @@ export function afterDelete(tenantId: string, ids: string[]): AfterWrite {
     await Promise.all(
       ids.map((id) => versions.getAll(id, "templateId").delete().run()),
     );
+    await releaseTemplateSlugs(tenantId, ids);
     await refreshTemplateAttention(tenantId);
   };
 }
 
 /**
- * Sends resolve templates by slug and nothing enforces its uniqueness but the
- * create checks, so a slug never changes once set; a category must be one the
- * settings declare, and a name holds more than spaces.
+ * Sends resolve templates by slug and only the create paths claim it, so a
+ * slug never changes once set; a category must be one the settings declare,
+ * and a name holds more than spaces.
  */
 export async function assertEditable(
   tenantId: string,

package/src/db/models/index.ts

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

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

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import {
+  MAILING_TEMPLATE_SLUGS_TABLE_NAME,
+  MailingTemplateSlug,
+} from "../tables";
+
+const ID_LENGTH = 32;
+
+/**
+ * The id of a slug's claim, the same whoever creates the template. The tenant
+ * is part of it: a driver may keep every tenant's rows in one collection,
+ * where a key made of the slug alone would collide across tenants.
+ */
+export function templateSlugIdOf(tenantId: string, slug: string): string {
+  return createHash("sha256")
+    .update(`${tenantId}\n${slug}`)
+    .digest("hex")
+    .slice(0, ID_LENGTH);
+}
+
+export class TemplateSlugModel extends BasicDataModel(
+  MailingTemplateSlug,
+  MAILING_TEMPLATE_SLUGS_TABLE_NAME,
+) {
+  /**
+   * Inserts the claim; false when the key is taken. Probed by state rather
+   * than by error, since the database interface exposes no typed conflict
+   * error: a claim present after a failed insert is the lost race.
+   */
+  async insertClaim(
+    id: string,
+    slug: string,
+    templateId: string,
+  ): Promise<boolean> {
+    try {
+      await this.insert({ _id: id, slug, templateId });
+      return true;
+    } catch (error) {
+      if (await this.get(id)) return false;
+      throw error;
+    }
+  }
+
+  /** Drops the claim if `templateId` still holds it, never a newer one. */
+  async dropClaimOf(id: string, templateId: string): Promise<void> {
+    await this.table
+      .atomicMutation(id, {
+        type: "deleteIfEqual",
+        field: "templateId",
+        expectedValue: templateId,
+      })
+      .run();
+  }
+
+  /** Frees the slugs the templates held. */
+  async releaseTemplates(templateIds: string[]): Promise<void> {
+    if (!templateIds.length) return;
+    await this.table.getAll(templateIds, "templateId").delete().run();
+  }
+}

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

@@ -2,6 +2,7 @@ import { HTTPResult } from "@antelopejs/interface-api";
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import {
   DEFAULT_FALLBACK_LOCALE,
+  HTTP_CONFLICT,
   HTTP_NOT_FOUND,
   LOCALE_LIST_SEPARATOR,
 } from "../constants";
@@ -9,7 +10,9 @@ import {
   type MailingTemplate,
   type MailingTemplateVersion,
   TemplateModel,
+  TemplateSlugModel,
   TemplateVersionModel,
+  templateSlugIdOf,
 } from "../db";
 import { diffContents, diffVariables, type TemplateChange } from "../engine";
 import {
@@ -39,6 +42,7 @@ const NEVER_PUBLISHED = 0;
 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";
 
 /** The template `id` names; 404 when there is none. */
 export async function requireTemplate(
@@ -50,6 +54,51 @@ export async function requireTemplate(
   return template;
 }
 
+/**
+ * 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.
+ */
+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) {
+    const templates = GetModel(TemplateModel, tenantId);
+    if (await templates.get(holder.templateId)) return false;
+    await claims.dropClaimOf(id, holder.templateId);
+  }
+  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. */
 export function parseContent(template: MailingTemplate): TemplateContent {
   return JSON.parse(template.json_content || EMPTY_CONTENT) as TemplateContent;