vintasend-managed-templates 1.0.0-alpha3 → 1.0.0-alpha4

package/README.md

@@ -95,7 +95,53 @@ await notificationService.createNotification({
 });
 ```
 
-Nothing else about creating or sending notifications changes.
+Nothing else about creating or sending notifications changes. A send renders the key's newest
+**active** version — see [Which version a send renders](#which-version-a-send-renders) — so a
+template has to be activated before it goes out.
+
+### Sending before a template is written: fallbacks
+
+An application can register a default for each key, so it can send a notification before anyone
+has written its template in the store. While a key has nothing published, `render` hands the
+default to a renderer of your choosing; once a version of the key is activated, sends use it.
+
+```ts
+import { PugEmailTemplateRendererFactory } from 'vintasend-pug';
+
+const renderer = new ManagedTemplateEmailRenderer<Config>(managerBackend, innerRenderer, {
+  fallback: {
+    // Optional; defaults to the inner renderer. Its `render` gets a copy of the notification
+    // with `bodyTemplate` / `subjectTemplate` replaced by the values registered below.
+    renderer: new PugEmailTemplateRendererFactory<Config>().create(),
+    templates: {
+      welcome: {
+        subjectTemplate: 'emails/welcome/subject.pug', // file paths, for a file renderer
+        bodyTemplate: 'emails/welcome/body.pug',
+      },
+    },
+  },
+});
+
+renderer.getFallbackTemplate('welcome'); // the registered default, or null — for a dashboard
+```
+
+The text renderer takes the same option. The rules:
+
+* **Only when the key itself has nothing published** — no versions at all, or only drafts and
+  retired ones. A stored template that fails to compose (it extends a base that is missing) throws
+  `ManagedTemplateCompositionReferenceError` instead: that template exists and is broken, and a
+  default must not hide it.
+* **Only for an unpinned notification.** If a pinned version is missing, the template existed when
+  the notification was created, so the render throws.
+* **Only for a registered key**, matched as an own property — a key such as `constructor` never
+  matches the prototype.
+* **Only on `render`**, the send path. `renderManaged`, `renderTemplate` and the service's
+  `render` (what previews use) never fall back, and `getLatestTemplateVersion` still answers `null`
+  for a key with nothing published.
+
+A fallback payload carries `templateSource: 'fallback'` and no `templateVersion`, so the
+notification's `usedTemplateVersion` stays `null` and a host can tell the default went out. The
+renderer logs the key and the notification id when it falls back — never the context.
 
 ### What the inner renderer has to do
 
@@ -307,14 +353,33 @@ await service.updateTemplate('welcome', {
   // tags: undefined carries them forward; [] clears them
 });
 
-await service.getTemplate('welcome'); // latest version
+await service.getTemplate('welcome'); // latest version, whatever its status
 await service.getTemplate('welcome', 1); // a specific one
+await service.getActiveTemplate('welcome'); // what an unpinned send renders
 await service.getTemplateVersions('welcome'); // every version, newest first
 ```
 
-An absent `version` means "the latest version of this key" everywhere in the service — reads,
-status changes, tagging, and rendering — so callers only deal with version numbers when they
-actually want a specific one.
+An absent `version` means "the latest version of this key" for reads, status changes and tagging —
+the editing view, which includes a draft someone is working on. Sends are the exception, below.
+
+### Which version a send renders
+
+"Latest" means two things, and they are kept apart:
+
+| | Resolves to | Used by |
+|---|---|---|
+| The editing view | the newest version, whatever its status | `getTemplate(key)`, status changes, tagging, the API's reads |
+| The send path | the newest **`active`** version | `render`, `renderManaged` with no version and no pin, `getLatestTemplateVersion` |
+
+A draft is never sent: publishing is the deliberate act that puts a version in front of
+recipients. When several versions of a key are active at once, the **highest-numbered** active one
+renders. A key with no active version throws `ManagedTemplateNoActiveVersionError`, a subclass of
+`ManagedTemplateNotFoundError` — so a key holding only drafts counts as "not customized yet", and a
+registered fallback applies.
+
+A notification **pinned** to a version renders that version whatever its status today. The pin is
+there so a notification renders what was reviewed when it was created, so deactivating the version
+later does not change what a pinned notification renders.
 
 ### Version-pinned rendering
 
@@ -326,12 +391,13 @@ const { version, rendered } = await renderer.renderManaged(notification, context
 ```
 
 Which version renders is decided in this order: an explicit `version` argument, then the
-notification's own `requestedTemplateVersion`, then whatever the backend considers current.
+notification's own `requestedTemplateVersion`, then the key's newest active version.
 
 `requestedTemplateVersion` is a first-class VintaSend field: pass it to `createNotification`, or
 let the service resolve it for you with `pinTemplateVersions`. This package is what makes it mean
-anything — `getLatestTemplateVersion` is how the service resolves "whatever is current right now",
-and it is overridden here to read the store.
+anything — `getLatestTemplateVersion` is how the service resolves "what would be sent right now",
+and it is overridden here to answer the key's newest active version (or `null` when nothing is
+published).
 
 `render` also stamps the version it used onto the payload it returns, as `templateVersion`. An
 adapter returns that payload from `send()`, and the service records it on the notification as
@@ -370,9 +436,27 @@ application.
 Two things the service deliberately does *not* decide for you:
 
 * **A key may have several `active` versions at once.** Activating one does not deactivate the
-  others; choosing which active version wins at render time is the host's call.
+  others. An unpinned send renders the highest-numbered active one.
 * **`changedBy` is passed through untouched, `null` included.** Attribution is never required.
 
+### Deleting a version
+
+Only a version that was **never published** can be deleted: one still in `draft` whose status
+history records nothing but `draft`. Anything else throws `ManagedTemplateDeletionNotAllowedError`
+— a published version may have rendered a notification that is pinned to it, and its status history
+is the record of who published it. Retire it with `archive` instead.
+
+```ts
+await service.deleteTemplate('welcome', 3); // fine while v3 is an unpublished draft
+await service.deleteTemplate('welcome', 1); // throws once v1 has been activated
+```
+
+The status history is never deleted, even when the version is. The service checks the rule
+before it calls the backend, so every backend is held to it; the backends shipped with VintaSend
+check it themselves too. If an operator genuinely needs to hard-delete a published version, pass
+`allowDeletingPublishedVersions: true` to both the service and the backend.
+`isTemplateVersionDeletable(template, history)` answers the question without attempting the delete.
+
 ## Tags
 
 Tags are many-to-many with template *versions* and are identified by a slug derived from the text
@@ -502,15 +586,25 @@ Implement `BaseTemplateManagerBackend`. `InMemoryTemplateManagerBackend` is a co
 implementation to read against, and the seam's own test suite
 (`src/__tests__/in-memory-backend.test.ts`) doubles as a conformance checklist.
 
-The three rules that are easy to miss:
+The four rules that are easy to miss:
 
 1. **Derive `isAbstract` on every write** that touches a source field, with `isAbstract()` from
    this package, and store the answer. A source whose composition tags are malformed has no answer:
    store `false` rather than letting the syntax error out of the write.
-2. **`updateTemplate` inserts, never updates.** Copy the latest version forward, bump the version,
-   start the copy in `draft`, and leave the version it was copied from untouched.
+2. **`updateTemplate` inserts, never updates.** Copy the latest version forward, start the copy in
+   `draft`, and leave the version it was copied from untouched. Number it one above the highest
+   version the key has *ever* had — a deleted version's number is never reused, or the new version
+   would inherit its status history and the notifications pinned to it.
 3. **`mostRecentActiveVersion` is answered against the key, not the row.** "This row is `active` or
    `draft`, and no `active`-or-`draft` row of the same key is numbered higher."
+4. **`deleteTemplate` refuses a published version and keeps the status history.** Use
+   `assertTemplateVersionDeletable`, and put any hard delete of a published version behind an
+   option that is off by default.
+
+`getActiveTemplate` — the newest `active` version, for the send path — is optional. Leave it out
+and the library answers it with `getFilteredTemplates({ key, status: 'active' })`; implement it when
+your store can answer more cheaply, throwing `noActiveVersion(key)` for a key with no active
+version.
 
 Slug every tag with `slugifyTag` and keep slugs unique with `nextAvailableSlug`, so your store and
 every other one derive the same identity from the same text.

package/dist/base-template-manager-backend.d.ts

@@ -38,11 +38,30 @@ export interface BaseTemplateManagerBackend {
      */
     createTemplate(data: ManagedTemplateCreateInput): Promise<ManagedTemplate>;
     /**
-     * One version of a template. `version` absent or `null` returns the latest version.
+     * One version of a template. `version` absent or `null` returns the latest version, whatever
+     * its status.
+     *
+     * That is the *editing view*: an editor or an API wants the draft someone is working on. A send
+     * never renders it — sends go through {@link getActiveTemplate} instead.
      *
      * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
      */
     getTemplate(templateKey: string, version?: number | null): Promise<ManagedTemplate>;
+    /**
+     * The version an unpinned send renders: the highest-numbered version whose status is `active`.
+     *
+     * Drafts are skipped whatever their number, and so are `inactive` and `archived` versions. A key
+     * may hold several active versions at once; the newest of them wins.
+     *
+     * Optional, so a backend written before it existed keeps compiling. The library answers for a
+     * backend that leaves it out by filtering on `{ key, status: 'active' }` — implement it when the
+     * store can answer more cheaply. `newestActiveVersion` and `noActiveVersion` are exported so an
+     * implementation shares the rule and the error rather than re-deriving them.
+     *
+     * @throws ManagedTemplateNotFoundError if the key does not exist.
+     * @throws ManagedTemplateNoActiveVersionError if the key exists but no version of it is active.
+     */
+    getActiveTemplate?(templateKey: string): Promise<ManagedTemplate>;
     /**
      * Create a new version of an existing template, copied forward from its latest one.
      *
@@ -51,6 +70,12 @@ export interface BaseTemplateManagerBackend {
      * went out against v1 renders v1 forever, however many versions follow it, and several
      * versions of one key are live at the same time as a matter of course.
      *
+     * The new version number is one above the highest the key has **ever** had, not one above the
+     * latest live version. A deleted version's status history survives it and is read by key and
+     * version, so a reused number would inherit that history — and a notification pinned to the
+     * deleted number would start rendering the newcomer. The same goes for `createTemplate` on a key
+     * whose versions were all deleted.
+     *
      * The new version starts in `draft` whatever its predecessor's status was, so a copy nobody
      * has reviewed is never published by the act of creating it. Fields left absent on the input —
      * tags included — carry forward from the version copied.
@@ -64,7 +89,17 @@ export interface BaseTemplateManagerBackend {
     /**
      * Delete one version of a template, or its latest version when `version` is absent.
      *
+     * Only a version that was never published may be deleted — still in `draft`, with nothing but
+     * `draft` in its status history (`isTemplateVersionDeletable`). A backend should refuse anything
+     * else with `ManagedTemplateDeletionNotAllowedError` unless its operator explicitly configured
+     * it to allow hard deletes; `ManagedTemplateService` checks the rule before calling this either
+     * way, so a backend that does not enforce it is still protected behind the service.
+     *
+     * Never delete the version's status history. It is the audit trail of who published what, and
+     * it has to outlive the version it describes.
+     *
      * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
+     * @throws ManagedTemplateDeletionNotAllowedError if the version has been published.
      */
     deleteTemplate(templateKey: string, version?: number | null): Promise<void>;
     /** Record a status change for one version in the audit trail. */

package/dist/base-template-manager-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-template-manager-backend.d.ts","sourceRoot":"","sources":["../src/base-template-manager-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-template-manager-backend.d.ts","sourceRoot":"","sources":["../src/base-template-manager-backend.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -11,6 +11,27 @@ export declare class ManagedTemplateError extends Error {
 /** Raised when a template is not found in the backend. */
 export declare class ManagedTemplateNotFoundError extends ManagedTemplateError {
 }
+/**
+ * Raised when a send resolves a key that has versions, but none of them is `active`.
+ *
+ * A subclass of {@link ManagedTemplateNotFoundError} on purpose: from a send's point of view a
+ * key holding only drafts (or only retired versions) has nothing published to render, which is
+ * the same answer as a key with nothing stored. That is what lets a renderer's fallback treat a
+ * key nobody has published yet as "not customized", and what lets an API keep mapping it to 404.
+ * Catch this subclass to tell "exists but unpublished" apart from "never created".
+ */
+export declare class ManagedTemplateNoActiveVersionError extends ManagedTemplateNotFoundError {
+}
+/**
+ * Raised when deleting a template version the deletion rule protects.
+ *
+ * Only a version that was never published can be deleted: one still in `draft` whose status
+ * history records nothing but its creation. Anything else may have rendered a notification that
+ * is pinned to it, and its status history is the record of who published it — retire it with
+ * `archive` instead. See `isTemplateVersionDeletable`.
+ */
+export declare class ManagedTemplateDeletionNotAllowedError extends ManagedTemplateError {
+}
 /** Raised when a filter is malformed or names a field the vocabulary does not have. */
 export declare class ManagedTemplateInvalidFilterError extends ManagedTemplateError {
 }

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAK5B;AAED,0DAA0D;AAC1D,qBAAa,4BAA6B,SAAQ,oBAAoB;CAAG;AAEzE,uFAAuF;AACvF,qBAAa,iCAAkC,SAAQ,oBAAoB;CAAG;AAE9E;;;;;;;GAOG;AACH,qBAAa,uCAAwC,SAAQ,oBAAoB;CAAG;AAEpF,sFAAsF;AACtF,qBAAa,sCAAuC,SAAQ,oBAAoB;CAAG;AAEnF,oFAAoF;AACpF,qBAAa,oCAAqC,SAAQ,oBAAoB;CAAG;AAEjF,qDAAqD;AACrD,qBAAa,+BAAgC,SAAQ,oBAAoB;CAAG;AAE5E,gFAAgF;AAChF,qBAAa,oCAAqC,SAAQ,oBAAoB;CAAG;AAEjF,8EAA8E;AAC9E,qBAAa,8BAA+B,SAAQ,oBAAoB;CAAG;AAE3E;;;;;;GAMG;AACH,qBAAa,+BAAgC,SAAQ,oBAAoB;CAAG;AAE5E,qFAAqF;AACrF,qBAAa,qCAAsC,SAAQ,+BAA+B;CAAG;AAE7F;;;;;;;;;GASG;AACH,qBAAa,wCAAyC,SAAQ,+BAA+B;CAAG;AAEhG,wFAAwF;AACxF,qBAAa,oCAAqC,SAAQ,+BAA+B;CAAG;AAE5F,oFAAoF;AACpF,qBAAa,oCAAqC,SAAQ,+BAA+B;CAAG;AAE5F;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKvD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAK5B;AAED,0DAA0D;AAC1D,qBAAa,4BAA6B,SAAQ,oBAAoB;CAAG;AAEzE;;;;;;;;GAQG;AACH,qBAAa,mCAAoC,SAAQ,4BAA4B;CAAG;AAExF;;;;;;;GAOG;AACH,qBAAa,sCAAuC,SAAQ,oBAAoB;CAAG;AAEnF,uFAAuF;AACvF,qBAAa,iCAAkC,SAAQ,oBAAoB;CAAG;AAE9E;;;;;;;GAOG;AACH,qBAAa,uCAAwC,SAAQ,oBAAoB;CAAG;AAEpF,sFAAsF;AACtF,qBAAa,sCAAuC,SAAQ,oBAAoB;CAAG;AAEnF,oFAAoF;AACpF,qBAAa,oCAAqC,SAAQ,oBAAoB;CAAG;AAEjF,qDAAqD;AACrD,qBAAa,+BAAgC,SAAQ,oBAAoB;CAAG;AAE5E,gFAAgF;AAChF,qBAAa,oCAAqC,SAAQ,oBAAoB;CAAG;AAEjF,8EAA8E;AAC9E,qBAAa,8BAA+B,SAAQ,oBAAoB;CAAG;AAE3E;;;;;;GAMG;AACH,qBAAa,+BAAgC,SAAQ,oBAAoB;CAAG;AAE5E,qFAAqF;AACrF,qBAAa,qCAAsC,SAAQ,+BAA+B;CAAG;AAE7F;;;;;;;;;GASG;AACH,qBAAa,wCAAyC,SAAQ,+BAA+B;CAAG;AAEhG,wFAAwF;AACxF,qBAAa,oCAAqC,SAAQ,+BAA+B;CAAG;AAE5F,oFAAoF;AACpF,qBAAa,oCAAqC,SAAQ,+BAA+B;CAAG;AAE5F;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKvD"}

package/dist/errors.js

@@ -15,6 +15,27 @@ export class ManagedTemplateError extends Error {
 /** Raised when a template is not found in the backend. */
 export class ManagedTemplateNotFoundError extends ManagedTemplateError {
 }
+/**
+ * Raised when a send resolves a key that has versions, but none of them is `active`.
+ *
+ * A subclass of {@link ManagedTemplateNotFoundError} on purpose: from a send's point of view a
+ * key holding only drafts (or only retired versions) has nothing published to render, which is
+ * the same answer as a key with nothing stored. That is what lets a renderer's fallback treat a
+ * key nobody has published yet as "not customized", and what lets an API keep mapping it to 404.
+ * Catch this subclass to tell "exists but unpublished" apart from "never created".
+ */
+export class ManagedTemplateNoActiveVersionError extends ManagedTemplateNotFoundError {
+}
+/**
+ * Raised when deleting a template version the deletion rule protects.
+ *
+ * Only a version that was never published can be deleted: one still in `draft` whose status
+ * history records nothing but its creation. Anything else may have rendered a notification that
+ * is pinned to it, and its status history is the record of who published it — retire it with
+ * `archive` instead. See `isTemplateVersionDeletable`.
+ */
+export class ManagedTemplateDeletionNotAllowedError extends ManagedTemplateError {
+}
 /** Raised when a filter is malformed or names a field the vocabulary does not have. */
 export class ManagedTemplateInvalidFilterError extends ManagedTemplateError {
 }

package/dist/in-memory-template-manager-backend.d.ts

@@ -17,17 +17,28 @@ import type { ManagedTemplate, ManagedTemplateCreateInput, ManagedTemplateStatus
 export type InMemoryTemplateManagerBackendOptions = {
     /** Overridden in tests so timestamps are deterministic. */
     now?: () => Date;
+    /**
+     * When true, `deleteTemplate` removes a version whatever its status. Off by default: only a
+     * version that was never published can be deleted (see `isTemplateVersionDeletable`).
+     * `ManagedTemplateService` checks the rule too, under its own option of the same name.
+     */
+    allowDeletingPublishedVersions?: boolean;
 };
 export declare class InMemoryTemplateManagerBackend implements BaseTemplateManagerBackend {
     private templates;
     private tags;
     private history;
     private nextId;
+    /** The highest version number each key has had deleted, so it is never handed out again. */
+    private highestDeletedVersion;
     private readonly now;
+    private readonly allowDeletingPublishedVersions;
     constructor(options?: InMemoryTemplateManagerBackendOptions);
     createTemplate(data: ManagedTemplateCreateInput): Promise<ManagedTemplate>;
     getTemplate(templateKey: string, version?: number | null): Promise<ManagedTemplate>;
+    getActiveTemplate(templateKey: string): Promise<ManagedTemplate>;
     updateTemplate(templateKey: string, data: ManagedTemplateUpdateInput): Promise<ManagedTemplate>;
+    /** Delete one never-published version. Its status history is kept either way. */
     deleteTemplate(templateKey: string, version?: number | null): Promise<void>;
     createTemplateStatusUpdate(params: {
         templateKey: string;
@@ -59,6 +70,16 @@ export declare class InMemoryTemplateManagerBackend implements BaseTemplateManag
     getPaginatedTemplates(page: number, pageSize: number, orderBy?: ManagedTemplateOrderBy): Promise<ManagedTemplate[]>;
     getPaginatedFilteredTemplates(filters: ManagedTemplateFilter, page: number, pageSize: number, orderBy?: ManagedTemplateOrderBy): Promise<ManagedTemplate[]>;
     private deriveIsAbstract;
+    /**
+     * One above the highest version number the key has ever had — live, deleted or only in its
+     * status history.
+     *
+     * A number is never reused. Status history outlives a deleted version and is read by key and
+     * version, so a new version that took a deleted one's number would inherit its history: a
+     * publish that never happened, and a draft the deletion rule then refuses. A notification pinned
+     * to the deleted number would also start rendering the newcomer.
+     */
+    private nextVersion;
     private versionsOf;
     private find;
     private requireTag;

package/dist/in-memory-template-manager-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-template-manager-backend.d.ts","sourceRoot":"","sources":["../src/in-memory-template-manager-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"in-memory-template-manager-backend.d.ts","sourceRoot":"","sources":["../src/in-memory-template-manager-backend.ts"],"names":[],"mappings":"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"}

package/dist/in-memory-template-manager-backend.js

@@ -14,6 +14,7 @@ import { isAbstract } from './composition.js';
 import { ManagedTemplateInvalidTagError, ManagedTemplateNotFoundError, ManagedTemplateTagAlreadyExistsError, ManagedTemplateTagNotFoundError, } from './errors.js';
 import { matchesTemplateFilter, paginate, sortTemplates } from './filter-evaluation.js';
 import { MANAGED_TEMPLATE_ORDER_BY_FIELDS, orderByCapabilityKey, } from './filters.js';
+import { assertTemplateVersionDeletable, newestActiveVersion, noActiveVersion, } from './lifecycle.js';
 import { nextAvailableSlug, normalizeTagText, slugifyTag } from './tags.js';
 export class InMemoryTemplateManagerBackend {
     constructor(options = {}) {
@@ -21,7 +22,10 @@ export class InMemoryTemplateManagerBackend {
         this.tags = [];
         this.history = [];
         this.nextId = 1;
+        /** The highest version number each key has had deleted, so it is never handed out again. */
+        this.highestDeletedVersion = new Map();
         this.now = options.now ?? (() => new Date());
+        this.allowDeletingPublishedVersions = options.allowDeletingPublishedVersions ?? false;
     }
     // -------------------------------------------------------------------------------------------
     // Templates
@@ -31,7 +35,8 @@ export class InMemoryTemplateManagerBackend {
         const template = {
             id: this.nextId++,
             key: data.key,
-            version: 1,
+            // A key whose versions were all deleted starts above every number it used before.
+            version: this.versionsOf(data.key).length > 0 ? 1 : this.nextVersion(data.key),
             name: data.name,
             description: data.description,
             templateManagedBackend: data.templateManagedBackend,
@@ -55,6 +60,17 @@ export class InMemoryTemplateManagerBackend {
         }
         return structuredCloneTemplate(template);
     }
+    async getActiveTemplate(templateKey) {
+        const versions = this.versionsOf(templateKey);
+        if (versions.length === 0) {
+            throw new ManagedTemplateNotFoundError(describeMissing(templateKey, null));
+        }
+        const active = newestActiveVersion(versions);
+        if (active === undefined) {
+            throw noActiveVersion(templateKey);
+        }
+        return structuredCloneTemplate(active);
+    }
     async updateTemplate(templateKey, data) {
         const previous = this.find(templateKey, null);
         if (previous === undefined) {
@@ -74,7 +90,8 @@ export class InMemoryTemplateManagerBackend {
         const template = {
             id: this.nextId++,
             key: previous.key,
-            version: previous.version + 1,
+            // Not `previous.version + 1`: a deleted version above it keeps its number.
+            version: this.nextVersion(previous.key),
             name: data.name || previous.name,
             description: data.description ?? previous.description,
             templateManagedBackend: previous.templateManagedBackend,
@@ -90,12 +107,17 @@ export class InMemoryTemplateManagerBackend {
         this.templates.push(template);
         return structuredCloneTemplate(template);
     }
+    /** Delete one never-published version. Its status history is kept either way. */
     async deleteTemplate(templateKey, version = null) {
         const template = this.find(templateKey, version);
         if (template === undefined) {
             throw new ManagedTemplateNotFoundError(describeMissing(templateKey, version));
         }
+        if (!this.allowDeletingPublishedVersions) {
+            assertTemplateVersionDeletable(template, this.history);
+        }
         this.templates = this.templates.filter((candidate) => candidate !== template);
+        this.highestDeletedVersion.set(templateKey, Math.max(this.highestDeletedVersion.get(templateKey) ?? 0, template.version));
     }
     async createTemplateStatusUpdate(params) {
         const template = this.find(params.templateKey, params.version);
@@ -234,6 +256,20 @@ export class InMemoryTemplateManagerBackend {
             return false;
         }
     }
+    /**
+     * One above the highest version number the key has ever had — live, deleted or only in its
+     * status history.
+     *
+     * A number is never reused. Status history outlives a deleted version and is read by key and
+     * version, so a new version that took a deleted one's number would inherit its history: a
+     * publish that never happened, and a draft the deletion rule then refuses. A notification pinned
+     * to the deleted number would also start rendering the newcomer.
+     */
+    nextVersion(templateKey) {
+        return (Math.max(0, this.highestDeletedVersion.get(templateKey) ?? 0, ...this.versionsOf(templateKey).map((template) => template.version), ...this.history
+            .filter((record) => record.templateKey === templateKey)
+            .map((record) => record.version)) + 1);
+    }
     versionsOf(templateKey) {
         return this.templates.filter((template) => template.key === templateKey);
     }

package/dist/index.d.ts

@@ -3,14 +3,15 @@ export type { TemplateComposerOptions, TemplateReference, TemplateResolver, } fr
 export { DEFAULT_MAX_DEPTH, DEFAULT_TAG_PREFIX, isAbstract, TemplateComposer, } from './composition.js';
 export type { ManagedTemplateStatus, ManagedTemplateTagStatus, TemplateField, } from './constants.js';
 export { MANAGED_TEMPLATE_STATUSES, MANAGED_TEMPLATE_TAG_STATUSES, MOST_RECENT_ACTIVE_VERSION_STATUSES, TEMPLATE_FIELDS, } from './constants.js';
-export { isNotFoundError, ManagedTemplateChangeUserNotFoundError, ManagedTemplateCompositionCycleError, ManagedTemplateCompositionDepthError, ManagedTemplateCompositionError, ManagedTemplateCompositionReferenceError, ManagedTemplateCompositionSyntaxError, ManagedTemplateError, ManagedTemplateInvalidFilterError, ManagedTemplateInvalidTagError, ManagedTemplateNotFoundError, ManagedTemplateStatusTransitionError, ManagedTemplateTagAlreadyExistsError, ManagedTemplateTagNotFoundError, ManagedTemplateUnsupportedOrderingError, } from './errors.js';
+export { isNotFoundError, ManagedTemplateChangeUserNotFoundError, ManagedTemplateCompositionCycleError, ManagedTemplateCompositionDepthError, ManagedTemplateCompositionError, ManagedTemplateCompositionReferenceError, ManagedTemplateCompositionSyntaxError, ManagedTemplateDeletionNotAllowedError, ManagedTemplateError, ManagedTemplateInvalidFilterError, ManagedTemplateInvalidTagError, ManagedTemplateNoActiveVersionError, ManagedTemplateNotFoundError, ManagedTemplateStatusTransitionError, ManagedTemplateTagAlreadyExistsError, ManagedTemplateTagNotFoundError, ManagedTemplateUnsupportedOrderingError, } from './errors.js';
 export type { FilterEvaluationContext } from './filter-evaluation.js';
 export { isMostRecentActiveVersion, matchesDateRange, matchesInteger, matchesStatus, matchesString, matchesTemplateFilter, normalizeSlugs, paginate, sortTemplates, } from './filter-evaluation.js';
 export type { DateRange, IntegerFieldFilter, ManagedTemplateFilter, ManagedTemplateFilterCapabilities, ManagedTemplateFilterFields, ManagedTemplateOrderBy, ManagedTemplateOrderByField, ManagedTemplateOrderDirection, ManagedTemplateStatusFilter, NumericFilterLookup, StringFieldFilter, StringFilterLookup, TagsFieldFilter, } from './filters.js';
 export { DEFAULT_TEMPLATE_BACKEND_FILTER_CAPABILITIES, FLAG_FILTER_FIELDS, isDateRange, isEmptyFilter, isFieldFilter, isNumericFilterLookup, isStatusExactLookup, isStatusInLookup, isStringFilterLookup, isTagsFilter, KNOWN_FILTER_FIELDS, MANAGED_TEMPLATE_ORDER_BY_FIELDS, orderByCapabilityKey, pruneUnsupportedFilters, supportsCapability, TAG_FILTER_FIELDS, } from './filters.js';
 export type { InMemoryTemplateManagerBackendOptions } from './in-memory-template-manager-backend.js';
 export { InMemoryTemplateManagerBackend } from './in-memory-template-manager-backend.js';
-export type { ManagedEmailTemplateContent, ManagedTemplateRendererOptions, ManagedTemplateRenderResult, TextTemplate, TextTemplateContent, VersionPinnedNotification, } from './managed-template-renderer.js';
+export { assertTemplateVersionDeletable, isTemplateVersionDeletable, newestActiveVersion, noActiveVersion, resolveActiveTemplate, } from './lifecycle.js';
+export type { ManagedEmailTemplateContent, ManagedTemplateFallbackOptions, ManagedTemplateFallbackTemplate, ManagedTemplateRendererOptions, ManagedTemplateRenderResult, TextTemplate, TextTemplateContent, VersionPinnedNotification, } from './managed-template-renderer.js';
 export { ManagedTemplateEmailRenderer, ManagedTemplateRenderer, ManagedTemplateTextRenderer, requestedTemplateVersion, } from './managed-template-renderer.js';
 export type { ManagedTemplateServiceOptions } from './managed-template-service.js';
 export { DEFAULT_STATUS_TRANSITIONS, ManagedTemplateService } from './managed-template-service.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mCAAmC,EACnC,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,EACpC,+BAA+B,EAC/B,wCAAwC,EACxC,qCAAqC,EACrC,oBAAoB,EACpB,iCAAiC,EACjC,8BAA8B,EAC9B,4BAA4B,EAC5B,oCAAoC,EACpC,oCAAoC,EACpC,+BAA+B,EAC/B,uCAAuC,GACxC,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,EAC7B,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,4CAA4C,EAC5C,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,gCAAgC,EAChC,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,qCAAqC,EAAE,MAAM,yCAAyC,CAAC;AAErG,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,YAAY,EACV,2BAA2B,EAC3B,8BAA8B,EAC9B,2BAA2B,EAC3B,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAEnF,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEnG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7F,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mCAAmC,EACnC,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,EACpC,+BAA+B,EAC/B,wCAAwC,EACxC,qCAAqC,EACrC,sCAAsC,EACtC,oBAAoB,EACpB,iCAAiC,EACjC,8BAA8B,EAC9B,mCAAmC,EACnC,4BAA4B,EAC5B,oCAAoC,EACpC,oCAAoC,EACpC,+BAA+B,EAC/B,uCAAuC,GACxC,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,EAC7B,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,4CAA4C,EAC5C,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,gCAAgC,EAChC,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,qCAAqC,EAAE,MAAM,yCAAyC,CAAC;AAErG,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAEzF,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,mBAAmB,EACnB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,2BAA2B,EAC3B,8BAA8B,EAC9B,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAEnF,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEnG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7F,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -3,13 +3,15 @@ export { DEFAULT_MAX_DEPTH, DEFAULT_TAG_PREFIX, isAbstract, TemplateComposer, }
 // Constants
 export { MANAGED_TEMPLATE_STATUSES, MANAGED_TEMPLATE_TAG_STATUSES, MOST_RECENT_ACTIVE_VERSION_STATUSES, TEMPLATE_FIELDS, } from './constants.js';
 // Errors
-export { isNotFoundError, ManagedTemplateChangeUserNotFoundError, ManagedTemplateCompositionCycleError, ManagedTemplateCompositionDepthError, ManagedTemplateCompositionError, ManagedTemplateCompositionReferenceError, ManagedTemplateCompositionSyntaxError, ManagedTemplateError, ManagedTemplateInvalidFilterError, ManagedTemplateInvalidTagError, ManagedTemplateNotFoundError, ManagedTemplateStatusTransitionError, ManagedTemplateTagAlreadyExistsError, ManagedTemplateTagNotFoundError, ManagedTemplateUnsupportedOrderingError, } from './errors.js';
+export { isNotFoundError, ManagedTemplateChangeUserNotFoundError, ManagedTemplateCompositionCycleError, ManagedTemplateCompositionDepthError, ManagedTemplateCompositionError, ManagedTemplateCompositionReferenceError, ManagedTemplateCompositionSyntaxError, ManagedTemplateDeletionNotAllowedError, ManagedTemplateError, ManagedTemplateInvalidFilterError, ManagedTemplateInvalidTagError, ManagedTemplateNoActiveVersionError, ManagedTemplateNotFoundError, ManagedTemplateStatusTransitionError, ManagedTemplateTagAlreadyExistsError, ManagedTemplateTagNotFoundError, ManagedTemplateUnsupportedOrderingError, } from './errors.js';
 // Filter evaluation, for a backend that has to finish a filter its query language cannot express
 export { isMostRecentActiveVersion, matchesDateRange, matchesInteger, matchesStatus, matchesString, matchesTemplateFilter, normalizeSlugs, paginate, sortTemplates, } from './filter-evaluation.js';
 // Filters and capabilities
 export { DEFAULT_TEMPLATE_BACKEND_FILTER_CAPABILITIES, FLAG_FILTER_FIELDS, isDateRange, isEmptyFilter, isFieldFilter, isNumericFilterLookup, isStatusExactLookup, isStatusInLookup, isStringFilterLookup, isTagsFilter, KNOWN_FILTER_FIELDS, MANAGED_TEMPLATE_ORDER_BY_FIELDS, orderByCapabilityKey, pruneUnsupportedFilters, supportsCapability, TAG_FILTER_FIELDS, } from './filters.js';
 // A backend to develop and test against
 export { InMemoryTemplateManagerBackend } from './in-memory-template-manager-backend.js';
+// Lifecycle rules: which version a send renders, which versions may be deleted
+export { assertTemplateVersionDeletable, isTemplateVersionDeletable, newestActiveVersion, noActiveVersion, resolveActiveTemplate, } from './lifecycle.js';
 // Renderers
 export { ManagedTemplateEmailRenderer, ManagedTemplateRenderer, ManagedTemplateTextRenderer, requestedTemplateVersion, } from './managed-template-renderer.js';
 // The service

package/dist/lifecycle.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The two lifecycle rules every backend has to agree on: which version a send renders, and which
+ * versions may be deleted.
+ *
+ * Both live here rather than in one backend so the in-memory store, a FHIR store and the service
+ * apply the same rule, and so a backend author has a function to call instead of prose to
+ * re-derive.
+ *
+ * **Which version a send renders.** "The latest version" means two different things, and the
+ * seam keeps them apart:
+ *
+ * * The *editing view* — `getTemplate(key)` with no version — is the newest version whatever its
+ *   status. An editor or an API listing a key's history wants the draft someone is working on.
+ * * The *send path* — {@link resolveActiveTemplate} — is the newest `active` version. A draft is
+ *   unreviewed by definition, so publishing is the deliberate act that puts a version in front of
+ *   recipients. When several versions are active at once (the lifecycle allows it), the
+ *   highest-numbered one wins.
+ *
+ * **Which versions may be deleted.** Only one that was never published — see
+ * {@link isTemplateVersionDeletable}.
+ */
+import type { BaseTemplateManagerBackend } from './base-template-manager-backend.js';
+import { ManagedTemplateNoActiveVersionError } from './errors.js';
+import type { ManagedTemplate, ManagedTemplateStatusHistory } from './types.js';
+/**
+ * The highest-numbered `active` version among `versions`, or `undefined` when none is active.
+ *
+ * `versions` may hold several keys' rows; the caller narrows it to one key first.
+ */
+export declare function newestActiveVersion(versions: readonly ManagedTemplate[]): ManagedTemplate | undefined;
+/**
+ * The version an unpinned send of `templateKey` renders: its highest-numbered `active` version.
+ *
+ * Uses the backend's own `getActiveTemplate` when it has one. A backend written before that method
+ * existed is answered through the filter seam instead — an exact key match plus `status: 'active'`
+ * — which every backend supports by default.
+ *
+ * @throws ManagedTemplateNotFoundError if the key does not exist.
+ * @throws ManagedTemplateNoActiveVersionError if it exists but no version of it is active.
+ */
+export declare function resolveActiveTemplate(backend: BaseTemplateManagerBackend, templateKey: string): Promise<ManagedTemplate>;
+/** The error a backend throws for a key that exists but has no `active` version. */
+export declare function noActiveVersion(templateKey: string): ManagedTemplateNoActiveVersionError;
+/**
+ * Whether a template version may be hard-deleted: it was never published.
+ *
+ * That means it is still in `draft` and its status history records nothing but `draft` — a
+ * backend that writes a creation entry is fine, and one that writes none is too. A version that
+ * was ever `active`, `inactive` or `archived` may have rendered a notification that is pinned to
+ * it, and its history is the record of who published it; retire it with `archive` instead.
+ */
+export declare function isTemplateVersionDeletable(template: ManagedTemplate, history: readonly ManagedTemplateStatusHistory[]): boolean;
+/**
+ * Throw unless {@link isTemplateVersionDeletable} allows deleting `template`.
+ *
+ * @throws ManagedTemplateDeletionNotAllowedError
+ */
+export declare function assertTemplateVersionDeletable(template: ManagedTemplate, history: readonly ManagedTemplateStatusHistory[]): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAEL,mCAAmC,EACpC,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,eAAe,GAAG,SAAS,CAQ7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,0BAA0B,EACnC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAe1B;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,mCAAmC,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,SAAS,4BAA4B,EAAE,GAC/C,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,SAAS,4BAA4B,EAAE,GAC/C,IAAI,CAQN"}