@antelopejs/dms-mailing 0.5.0 → 0.6.0

package/frontend-vue/tests/sortable-list.test.ts

@@ -0,0 +1,253 @@
+// @vitest-environment jsdom
+/**
+ * The drag and drop of the categories, the canvas blocks and the palette:
+ * SortableJS moves the dragged element in the DOM, the list puts it back and
+ * changes its array, and Vue renders the new order. The drags are replayed as
+ * SortableJS reports them, DOM moves included.
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import {
+	createApp,
+	defineComponent,
+	h,
+	nextTick,
+	reactive,
+	ref,
+	type App,
+} from 'vue'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+type Options = Record<string, unknown>
+
+interface FakeSortable {
+	el: HTMLElement
+	options: Options
+}
+
+const instances: FakeSortable[] = []
+
+// SortableJS needs a pointer to drag with: what the test drives is the
+// options the list hands it, called as SortableJS calls them.
+vi.mock('@vueuse/integrations/useSortable', async () => {
+	const { onMounted, unref } = await import('vue')
+	return {
+		useSortable: (
+			target: { value: HTMLElement },
+			_list: unknown,
+			options: Options,
+		) => {
+			const sortable = { el: undefined as unknown as HTMLElement, options }
+			onMounted(() => {
+				sortable.el = unref(target)
+				instances.push(sortable)
+			})
+			return {
+				option: (name: string, value: unknown) => {
+					sortable.options[name] = value
+				},
+			}
+		},
+	}
+})
+
+const { useSortableList } = await import('../app/composables/useSortableList')
+
+interface Item {
+	id: string
+}
+
+let app: App | undefined
+
+afterEach(() => {
+	app?.unmount()
+	app = undefined
+	instances.length = 0
+})
+
+const List = defineComponent({
+	props: {
+		items: { type: Array as () => Item[], required: true },
+		options: { type: Object, default: () => ({}) },
+	},
+	setup(props) {
+		const root = ref<HTMLElement | null>(null)
+		useSortableList(root, () => props.items, props.options)
+		return () =>
+			h(
+				'div',
+				{ ref: root },
+				props.items.map((item) =>
+					h('p', { key: item.id, 'data-id': item.id }, item.id),
+				),
+			)
+	},
+})
+
+function mountLists(lists: { items: Item[]; options: Options }[]) {
+	const host = document.createElement('div')
+	document.body.append(host)
+	app = createApp({
+		render: () => lists.map((list) => h(List, list)),
+	})
+	app.mount(host)
+	return host
+}
+
+const ids = (items: Item[]) => items.map((item) => item.id)
+const domIds = (sortable: FakeSortable) =>
+	[...sortable.el.children].map((child) => child.getAttribute('data-id'))
+const call = (sortable: FakeSortable, name: string, event: unknown) =>
+	(sortable.options[name] as (event: unknown) => void)(event)
+
+describe('useSortableList', () => {
+	it('reorders a list in place and renders the new order', async () => {
+		const items = reactive([{ id: 'a' }, { id: 'b' }, { id: 'c' }])
+		const changes: unknown[] = []
+		const ended = vi.fn()
+		mountLists([
+			{
+				items,
+				options: { onChange: (c: unknown) => changes.push(c), onEnd: ended },
+			},
+		])
+		const [list] = instances
+		const item = list!.el.children[0] as HTMLElement
+		call(list!, 'onStart', { item, oldIndex: 0 })
+		// SortableJS has moved the element already when it reports the update.
+		list!.el.append(item)
+		call(list!, 'onUpdate', { item, oldIndex: 0, newIndex: 2 })
+		call(list!, 'onEnd', {})
+		await nextTick()
+		expect(ids(items)).toEqual(['b', 'c', 'a'])
+		expect(domIds(list!)).toEqual(['b', 'c', 'a'])
+		expect(changes).toEqual([
+			{ moved: { element: { id: 'a' }, oldIndex: 0, newIndex: 2 } },
+		])
+		expect(ended).toHaveBeenCalledOnce()
+	})
+
+	it('moves an item to another list of its group', async () => {
+		const source = reactive([{ id: 'a' }, { id: 'b' }])
+		const target = reactive([{ id: 'x' }])
+		const sourceChanges: unknown[] = []
+		const targetChanges: unknown[] = []
+		mountLists([
+			{
+				items: source,
+				options: {
+					group: 'g',
+					onChange: (c: unknown) => sourceChanges.push(c),
+				},
+			},
+			{
+				items: target,
+				options: {
+					group: 'g',
+					onChange: (c: unknown) => targetChanges.push(c),
+				},
+			},
+		])
+		const [from, to] = instances
+		const item = from!.el.children[1] as HTMLElement
+		call(from!, 'onStart', { item, oldIndex: 1 })
+		to!.el.prepend(item)
+		// SortableJS reports the add on the target first, then the remove.
+		call(to!, 'onAdd', { item, newIndex: 0 })
+		call(from!, 'onRemove', { item, oldIndex: 1 })
+		call(from!, 'onEnd', {})
+		await nextTick()
+		expect(ids(source)).toEqual(['a'])
+		expect(ids(target)).toEqual(['b', 'x'])
+		expect(domIds(from!)).toEqual(['a'])
+		expect(domIds(to!)).toEqual(['b', 'x'])
+		expect(sourceChanges).toEqual([
+			{ removed: { element: { id: 'b' }, oldIndex: 1 } },
+		])
+		expect(targetChanges).toEqual([
+			{ added: { element: { id: 'b' }, newIndex: 0 } },
+		])
+	})
+
+	it('hands a copy to the other list and keeps its own item (pull: clone)', async () => {
+		const palette = reactive([{ id: 'tile' }])
+		const canvas = reactive<Item[]>([])
+		const group = { name: 'g', pull: 'clone', put: false }
+		mountLists([
+			{
+				items: palette,
+				options: {
+					group,
+					sort: false,
+					clone: (item: Item) => ({ id: `${item.id}-copy` }),
+				},
+			},
+			{ items: canvas, options: { group: { name: 'g' } } },
+		])
+		const [from, to] = instances
+		expect(from!.options.group).toBe(group)
+		expect(from!.options.sort).toBe(false)
+		const item = from!.el.children[0] as HTMLElement
+		call(from!, 'onStart', { item, oldIndex: 0 })
+		// SortableJS leaves a stand-in where the tile was and drags the tile.
+		const stand = item.cloneNode(true) as HTMLElement
+		from!.el.insertBefore(stand, item)
+		to!.el.append(item)
+		call(to!, 'onAdd', { item, newIndex: 0 })
+		call(from!, 'onRemove', {
+			item,
+			clone: stand,
+			oldIndex: 0,
+			pullMode: 'clone',
+		})
+		call(from!, 'onEnd', {})
+		await nextTick()
+		expect(ids(palette)).toEqual(['tile'])
+		expect(ids(canvas)).toEqual(['tile-copy'])
+		expect(domIds(from!)).toEqual(['tile'])
+		expect(domIds(to!)).toEqual(['tile-copy'])
+	})
+
+	it('passes the handle, the item selector and a disabled state it follows', async () => {
+		const disabled = ref(false)
+		mountLists([
+			{
+				items: reactive([{ id: 'a' }]),
+				options: {
+					handle: '[data-drag-handle]',
+					draggable: '>[data-drag-item]',
+					ghostClass: 'opacity-30',
+					disabled: () => disabled.value,
+				},
+			},
+		])
+		const [list] = instances
+		expect(list!.options).toMatchObject({
+			handle: '[data-drag-handle]',
+			draggable: '>[data-drag-item]',
+			ghostClass: 'opacity-30',
+			disabled: false,
+			sort: true,
+		})
+		disabled.value = true
+		await nextTick()
+		expect(list!.options.disabled).toBe(true)
+	})
+
+	it('leaves SortableJS its defaults for what the list does not set', () => {
+		mountLists([{ items: reactive([{ id: 'a' }]), options: {} }])
+		const [list] = instances
+		// A key present with `undefined` would replace the default: an
+		// undefined `draggable` makes no child an item, and nothing drags.
+		for (const name of ['group', 'handle', 'draggable', 'ghostClass'])
+			expect(list!.options).not.toHaveProperty(name)
+	})
+
+	it('no longer ships vuedraggable, which bundled the Vue compiler', () => {
+		const manifest = JSON.parse(
+			readFileSync(resolve(__dirname, '../package.json'), 'utf8'),
+		) as { dependencies: Record<string, string> }
+		expect(manifest.dependencies).not.toHaveProperty('vuedraggable')
+		expect(manifest.dependencies).toHaveProperty('sortablejs')
+	})
+})

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@antelopejs/dms-mailing",
-  "version": "0.5.0",
+  "version": "0.6.0",
+  "description": "E-mail templates for the AntelopeJS DMS: a block editor with drafts and versions, a send log, delivery metrics and a suppression list.",
+  "keywords": [
+    "antelopejs",
+    "dms",
+    "dms-module",
+    "email",
+    "mailing",
+    "templates"
+  ],
+  "homepage": "https://dms.antelopejs.com/docs/modules/mailing",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/dms-mailing/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,6 +27,7 @@
     "!dist/.tsbuildinfo",
     "!dist/test",
     "frontend-vue",
+    "skills",
     "src",
     "!src/test"
   ],
@@ -32,21 +46,21 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
-    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.7.0 <1.0.0",
-    "@antelopejs/interface-dms-mailing": ">=0.7.0 <0.8.0",
-    "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
+    "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
+    "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
+    "@antelopejs/interface-dms-mailing": ">=0.8.0 <0.9.0",
+    "@antelopejs/interface-email": ">=0.0.6 <1.0.0",
     "node-cron": "^4.2.1",
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.13.4 <2",
-    "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
+    "@antelopejs/core": ">=1.16.0 <2",
+    "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10",
     "@types/node": "^24.0.0",
@@ -64,14 +78,17 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "@antelopejs/interface-dms-automation": ">=0.1.0 <1.0.0"
+    "@antelopejs/interface-dms-automation": ">=0.2.1 <1.0.0"
   },
   "antelopeJs": {
     "baseUrl": "dist",
     "implements": [
       "@antelopejs/interface-dms-mailing"
     ],
-    "test": "src/test/antelope.test.ts"
+    "test": "src/test/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   },
   "scripts": {
     "build": "rimraf dist && tsc",

package/skills/dms-mailing/SKILL.md

@@ -0,0 +1,101 @@
+---
+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, shipping templates or categories as code with DeclareTemplate / DeclareTemplateCategory, importing past sends with ImportSends, 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.6 requires `@antelopejs/dms` >=0.9 (interface-dms 0.7, renderer `@antelopejs/dms-frontend` 0.6);
+  0.4 is the DMS 0.8 line. Mailing 0.6 implements `@antelopejs/interface-dms-mailing` `>=0.8.0 <0.9.0`, adding declaration and import calls;
+  `SendTemplate` / `RecordEmailEvent` 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`.
+
+## Ship templates as code
+
+```typescript
+import { DeclareTemplate, DeclareTemplateCategory, ImportSends } from "@antelopejs/interface-dms-mailing";
+
+export async function declareMailingContent(tenantId: string) {
+  await DeclareTemplateCategory({ tenantId, id: "subscriptions", label: "Subscriptions", icon: "i-ph-repeat" }); // before templates naming it
+  const { outcome } = await DeclareTemplate({
+    tenantId, slug: "subscription-renewed", name: "Subscription renewed", category: "subscriptions",
+    content: { locales: { en: { subject: "Your {{plan.name}} plan is renewed", preheader: "", blocks: [] } } },
+    variables: [{ path: "plan.name", type: "string", required: true }],
+    testData: { plan: { name: "Pro" } },
+  }); // created | updated | unchanged | kept
+}
+```
+
+- Require explicit non-blank `tenantId` for declarations and imports, including an explicitly selected default tenant.
+  The application must authorize the target and establish provisioning readiness.
+- For SaaS initialization, follow the consumer reference's **Initialize new SaaS workspaces** section:
+  register the durable `created` consumer synchronously in `construct()`, without awaiting declarations,
+  before startup reconciliation; deduplicate `operationId`, bind resources
+  durably, then return a receipt. Mailing registers no consumer. `start()` is process-global, not per tenant;
+  `TENANT_BEING_PROVISIONED` is prepayment and is not the durable `created` transition.
+  Deployment updates/backfills require an authorized inventory and `IsWorkspaceProvisioningCommitted`, failing closed.
+- Idempotent on the tenant's slug, published at once (v1, version rows, slug claim, attention refresh: a normal template).
+- Rule: same declaration → `unchanged`; changed declaration → `updated` only if the template is live, has no
+  draft and still holds exactly the last declaration (fingerprint on `declaredHash`); otherwise `kept`.
+  A dashboard-made template under that slug is never taken over. Deleted → recreated next boot; archive instead.
+- Categories: added once; a category a user relabelled/removed, or a default one, is `kept`.
+- Refusals reject with `error.code`: `invalid_template`, `unknown_category`, `empty_subject`,
+  `nothing_to_publish`, `invalid_category`; invalid tenant input rejects before writes. Storage errors can occur after publication.
+- `ImportSends({ tenantId, sends: [{ importId, templateSlug, to, sentAt, events }] })` writes past sends with their own
+  dates (demo data, migration): no delivery, no suppression/automation/realtime; skipped when `importId` was
+  already imported. Retention still applies (90 days default).
+
+## 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).
+- nodemailer `ethereal: true` creates its account online at startup: offline, the whole project fails to
+  start (nodemailer's `construct()` throws, before Mailing runs). Use a local SMTP server (Mailpit) offline.

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/send-events.model.ts

@@ -23,6 +23,19 @@ export class SendEventModel extends BasicDataModel(
     return false;
   }
 
+  /**
+   * Writes an imported event under its own id, unless an interrupted run of
+   * the same import already did.
+   */
+  async insertImported(event: MailingSendEvent): Promise<void> {
+    if (await this.get(event._id)) return;
+    try {
+      await this.insert(event);
+    } catch (error) {
+      if (!(await this.get(event._id))) throw error;
+    }
+  }
+
   /** Keyset pagination remains stable when overlapping sweeps delete earlier rows. */
   listAfter(after: string, size: number): Promise<MailingSendEvent[]> {
     return this.table

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

@@ -15,6 +15,12 @@ type NewSend = Omit<
   "_id" | "createdAt" | "revision" | "isRetiring" | "lastActivityAt"
 >;
 
+/** A send written by an import: its own id and date, as it happened. */
+export type ImportedSendRow = Omit<
+  MailingSend,
+  "revision" | "isRetiring" | "lastActivityAt"
+>;
+
 const MAX_MUTATION_ATTEMPTS = 5;
 
 /** A send as the metrics read it: everything but the rendered variables. */
@@ -82,6 +88,22 @@ export class SendModel extends BasicDataModel(
       .run();
   }
 
+  /**
+   * Writes an imported send under its own id; false when that id is already
+   * taken, by an earlier run of the same import. Probed by state like the
+   * slug claims, since the database exposes no typed conflict error.
+   */
+  async insertImported(send: ImportedSendRow): Promise<boolean> {
+    if (await this.get(send._id)) return false;
+    try {
+      await this.table.insert({ ...send, revision: randomUUID() }).run();
+      return true;
+    } catch (error) {
+      if (await this.get(send._id)) return false;
+      throw error;
+    }
+  }
+
   /** Reads the stored row, including the revision the mutation contract compares. */
   getSnapshot(sendId: string): Promise<MailingSend | undefined> {
     return this.table.get(sendId).run();

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();
+  }
+}