vintasend-managed-templates 1.0.0-alpha2

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

@@ -0,0 +1,202 @@
+import type { ManagedTemplateStatus, ManagedTemplateTagStatus } from './constants.js';
+import type { ManagedTemplateFilter, ManagedTemplateFilterCapabilities, ManagedTemplateOrderBy } from './filters.js';
+import type { ManagedTemplate, ManagedTemplateCreateInput, ManagedTemplateStatusHistory, ManagedTemplateTag, ManagedTemplateUpdateInput } from './types.js';
+/**
+ * Where managed templates are stored, versioned, tagged and queried.
+ *
+ * One responsibility here is easy to miss because no method is named for it:
+ * **`ManagedTemplate.isAbstract` is the backend's to derive.** It is denormalized from the
+ * template's own source — `composition.isAbstract` computes it — and neither write input carries
+ * it, because it is a fact about the source rather than something a caller decides. Derive it on
+ * every write that touches a source field and store the answer, so the `isAbstract` filter can
+ * be a field lookup instead of a full-store parse. A backend that never sets it reports every
+ * template as concrete, and that filter quietly stops working.
+ *
+ * A source whose composition tags are malformed has no answer: store `false` rather than letting
+ * the syntax error out of the write. The flag is a search convenience, a template nobody can
+ * parse cannot be extended either, and a write is the wrong place to report a syntax error — the
+ * edit boundary already refuses it, and `compose` reports it in full at the point where it
+ * actually matters.
+ *
+ * Every method is asynchronous, unlike the Python sibling: a TypeScript store is a network call
+ * more often than not, and `ManagedTemplateService` awaits throughout.
+ */
+export interface BaseTemplateManagerBackend {
+    /**
+     * Which filters this backend can honour, declaring only what it *cannot* do.
+     *
+     * Optional. A backend that says nothing is taken at
+     * `DEFAULT_TEMPLATE_BACKEND_FILTER_CAPABILITIES` — fully capable — which is the same reading
+     * a backend returning `{}` gets. Callers merge the report over the default, so a capability
+     * added in a later release does not force every backend to re-declare it.
+     */
+    getFilterCapabilities?(): ManagedTemplateFilterCapabilities;
+    /**
+     * Create a new template's first version.
+     *
+     * Derive `isAbstract` from the source being stored — see the interface docs.
+     */
+    createTemplate(data: ManagedTemplateCreateInput): Promise<ManagedTemplate>;
+    /**
+     * One version of a template. `version` absent or `null` returns the latest version.
+     *
+     * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
+     */
+    getTemplate(templateKey: string, version?: number | null): Promise<ManagedTemplate>;
+    /**
+     * Create a new version of an existing template, copied forward from its latest one.
+     *
+     * A new version is a new row, and the version it was copied from is left exactly as it was —
+     * content, status and history. That is what versioning is for: a notification that already
+     * 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 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.
+     *
+     * `isAbstract` is re-derived from the new version's source rather than carried forward: an
+     * edit that adds or removes a `{% managed_children %}` hole changes what the template is.
+     *
+     * @throws ManagedTemplateNotFoundError if the key does not exist.
+     */
+    updateTemplate(templateKey: string, data: ManagedTemplateUpdateInput): Promise<ManagedTemplate>;
+    /**
+     * Delete one version of a template, or its latest version when `version` is absent.
+     *
+     * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
+     */
+    deleteTemplate(templateKey: string, version?: number | null): Promise<void>;
+    /** Record a status change for one version in the audit trail. */
+    createTemplateStatusUpdate(params: {
+        templateKey: string;
+        version: number;
+        status: ManagedTemplateStatus;
+        changedBy?: string | null;
+    }): Promise<void>;
+    /**
+     * The status audit trail for a template.
+     *
+     * `version` absent asks for the whole key's history. Unlike everywhere else in this seam,
+     * `version` absent here does *not* mean "the latest version".
+     */
+    getTemplateStatusHistory(templateKey: string, version?: number | null): Promise<ManagedTemplateStatusHistory[]>;
+    /**
+     * Resolve tag texts to tags, creating the ones that do not exist yet.
+     *
+     * This is the on-the-fly path every tagging call goes through: a caller tags a template with
+     * what a person typed and never has to check first whether that tag exists. Texts that slugify
+     * onto an existing tag resolve to it rather than creating a duplicate, and an existing tag is
+     * returned as it stands — its text and status are left alone, so re-using an archived tag does
+     * not quietly bring it back.
+     *
+     * @returns one tag per distinct text, in the order given.
+     * @throws ManagedTemplateInvalidTagError if a text has nothing that can be slugified.
+     */
+    getOrCreateTags(texts: string[], tenant?: string | null): Promise<ManagedTemplateTag[]>;
+    /**
+     * Create a tag, failing if its text already slugs onto an existing one.
+     *
+     * Use `getOrCreateTags` when a duplicate should resolve to the existing tag; this is the
+     * explicit-create path, where a collision is worth reporting to the caller.
+     *
+     * @throws ManagedTemplateTagAlreadyExistsError if a tag with that slug exists.
+     * @throws ManagedTemplateInvalidTagError if the text has nothing that can be slugified.
+     */
+    createTag(text: string, tenant?: string | null): Promise<ManagedTemplateTag>;
+    /**
+     * One tag by slug (or by the text it was created from).
+     *
+     * @throws ManagedTemplateTagNotFoundError if no tag has that slug.
+     */
+    getTag(slug: string): Promise<ManagedTemplateTag>;
+    /**
+     * Rename a tag, regenerating its slug from the new text.
+     *
+     * The slug changes, so anything holding the old one — a bookmarked filter, a cached query —
+     * stops matching. The tag keeps its identity and its templates: only the strings change.
+     *
+     * @throws ManagedTemplateTagNotFoundError if no tag has that slug.
+     * @throws ManagedTemplateInvalidTagError if the new text has nothing to slugify.
+     */
+    updateTag(slug: string, text: string): Promise<ManagedTemplateTag>;
+    /**
+     * Archive a tag, or bring an archived one back.
+     *
+     * Archiving keeps every link to a template: filtering by an archived tag still returns the
+     * templates carrying it. What archiving is for is dropping the tag out of the pickers a UI
+     * builds from the active list.
+     *
+     * @throws ManagedTemplateTagNotFoundError if no tag has that slug.
+     */
+    setTagStatus(slug: string, status: ManagedTemplateTagStatus): Promise<ManagedTemplateTag>;
+    /**
+     * Delete a tag and remove it from every template carrying it.
+     *
+     * Unlike archiving, this is not reversible and the templates lose the label.
+     *
+     * @throws ManagedTemplateTagNotFoundError if no tag has that slug.
+     */
+    deleteTag(slug: string): Promise<void>;
+    /**
+     * Tags, optionally narrowed by status, by a text search, or by tenant.
+     *
+     * @param status every status when absent.
+     * @param search a case-insensitive substring of the text or the slug.
+     * @param tenant every tenant when absent.
+     */
+    getTags(status?: ManagedTemplateTagStatus[] | null, search?: string | null, tenant?: string | null): Promise<ManagedTemplateTag[]>;
+    /**
+     * The tags on one version of a template, or on its latest version.
+     *
+     * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
+     */
+    getTemplateTags(templateKey: string, version?: number | null): Promise<ManagedTemplateTag[]>;
+    /**
+     * Replace the tags on one version of a template, creating any that do not exist.
+     *
+     * This edits a version in place rather than creating a new one, which is the one thing about a
+     * template that does: tags are search metadata, not template content, so retagging for
+     * findability should not spawn a version and reset it to `draft`.
+     *
+     * @param tags tag texts (or slugs). Empty clears the version's tags.
+     * @throws ManagedTemplateNotFoundError if the key (or that version of it) does not exist.
+     * @throws ManagedTemplateInvalidTagError if a text has nothing that can be slugified.
+     */
+    setTemplateTags(templateKey: string, tags: string[], version?: number | null): Promise<ManagedTemplate>;
+    /** Every version of every template in the store. */
+    getAllTemplates(): Promise<ManagedTemplate[]>;
+    /** Every template version in any of the given statuses. */
+    getTemplatesByStatus(status: ManagedTemplateStatus[]): Promise<ManagedTemplate[]>;
+    /**
+     * The templates matching `filters`.
+     *
+     * Every field of `ManagedTemplateFilterFields` tests an attribute of the row — `isAbstract`
+     * included, which is why it is stored rather than parsed here — with one exception:
+     * `mostRecentActiveVersion` is about the *key*. `true` keeps only the highest-numbered version
+     * of each key whose status is in `MOST_RECENT_ACTIVE_VERSION_STATUSES`, and `false` keeps every
+     * other row — so an implementation answers it by comparing the row against its key's other
+     * versions rather than by reading a field. It is what the service's listing methods apply by
+     * default, so a backend that cannot evaluate it cannot serve a default listing.
+     */
+    getFilteredTemplates(filters: ManagedTemplateFilter): Promise<ManagedTemplate[]>;
+    /**
+     * One page of templates.
+     *
+     * @param page 1-indexed. `ManagedTemplateService` validates `page >= 1` before calling, so
+     *   unlike `vintasend`'s notification backends there is no per-backend page numbering to
+     *   negotiate.
+     */
+    getPaginatedTemplates(page: number, pageSize: number, orderBy?: ManagedTemplateOrderBy): Promise<ManagedTemplate[]>;
+    /**
+     * One page of the templates matching `filters`. `page` is 1-indexed.
+     *
+     * `orderBy` is optional and every `orderBy.*` capability defaults to false, so a backend
+     * written before ordering existed keeps compiling and keeps its honest report. A backend that
+     * *does* accept it must apply the order to the whole result set before paging, and must
+     * declare the fields it can order by — a page sorted after it was chosen is sorted within
+     * itself and wrong across page boundaries.
+     */
+    getPaginatedFilteredTemplates(filters: ManagedTemplateFilter, page: number, pageSize: number, orderBy?: ManagedTemplateOrderBy): Promise<ManagedTemplate[]>;
+}
+//# sourceMappingURL=base-template-manager-backend.d.ts.map

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

@@ -0,0 +1 @@
+{"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/base-template-manager-backend.js

@@ -0,0 +1 @@
+export {};

package/dist/composition.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Inheritance and inclusion for managed templates, resolved before the engine runs.
+ *
+ * A file-based renderer gets composition for free. Pug's `extends` and Nunjucks' `include` hand
+ * a *name* to a loader, and a loader reads files, so the header, the footer and the wrapper
+ * every email shares live in one file that every other file points at.
+ *
+ * Managed templates are not files. They reach the engine as source, pulled out of a store and
+ * handed to `renderFromTemplateContent` as a string, so a loader has nothing to resolve and
+ * those tags have nothing to load. Without this module the shared chrome would have to be
+ * pasted into every template in the store, and changing the footer would mean editing every row
+ * that has one.
+ *
+ * This module puts composition back where the store can serve it. It defines a small tag
+ * language, resolves it against the template store, and hands the engine one flat string with no
+ * trace of itself left in it. Whatever runs next — Pug, Nunjucks, React Email, anything — sees
+ * only its own syntax, and its own `extends` / `include` are left untouched for it to deal with.
+ *
+ * ## The tags
+ *
+ * Every tag carries the `managed_` prefix, so nothing here can be mistaken for an engine tag
+ * that is meant to survive composition. The prefix is configurable per composer, but it is
+ * reserved: an unknown `{% managed_* %}` tag is a syntax error rather than text passed through,
+ * which is what turns a typo into an error instead of into a broken email.
+ *
+ * - `{% managed_extends "base-email" %}` — this template is a child of `base-email`. At most one
+ *   per template, at the top level (never inside a block). Takes an optional `version=2` to pin
+ *   the parent.
+ * - `{% managed_children %}` — in a parent: where the child's content goes. This is what makes a
+ *   template *abstract*: it is a layout with a hole in it, filled by whatever the child writes
+ *   outside its blocks. Rendered on its own, with no child, the hole is simply empty.
+ * - `{% managed_block name %}...{% managed_endblock %}` — a named, overridable region. A
+ *   parent's block renders its own content unless a child declares a block with the same name;
+ *   the child's wins. Blocks may nest.
+ * - `{% managed_super %}` — inside a child's block: the content of the block it is overriding.
+ *   Chains through as many levels of inheritance as there are.
+ * - `{% managed_include "footer" %}` — splice another template in at this point. The included
+ *   template is composed in full first, so an include may itself extend and include.
+ *
+ * ## How a child fills a parent
+ *
+ * Everything the child writes *outside* a block is its children content, and it lands in the
+ * parent's `{% managed_children %}`. Blocks are pulled out of that content first, so the two
+ * mechanisms compose: a child can both fill the hole and override named regions.
+ *
+ * ```
+ * parent "base-email"    <html><body>
+ *                          {% managed_block header %}<h1>Acme</h1>{% managed_endblock %}
+ *                          {% managed_children %}
+ *                        </body></html>
+ *
+ * child  "welcome"       {% managed_extends "base-email" %}
+ *                        {% managed_block header %}<h1>Welcome</h1>{% managed_endblock %}
+ *                        <p>Hi #{name}</p>
+ *
+ * composed               <html><body>
+ *                          <h1>Welcome</h1>
+ *                          <p>Hi #{name}</p>
+ *                        </body></html>
+ * ```
+ *
+ * `#{name}` is untouched: composition never looks at engine syntax, and the context is the
+ * engine's business.
+ *
+ * ## One field at a time
+ *
+ * A template carries three sources — body, subject and preheader — and each is composed against
+ * the *same* field of the template it references. A child's body extends the parent's body; its
+ * subject extends the parent's subject. So a base can define a subject prefix and a body wrapper
+ * at once, and neither leaks into the other. A field the referenced template leaves empty
+ * composes to nothing rather than to an error.
+ *
+ * ## Versions
+ *
+ * A reference with no `version=` resolves through the backend the same way any other read does:
+ * to whatever version that key currently is. Pin it when a template must keep composing against
+ * an exact parent — re-rendering an old notification resolves the child's version explicitly,
+ * but its unpinned parents still resolve to today's.
+ *
+ * ## Cycles and depth
+ *
+ * A reference chain that comes back to a template already being composed throws
+ * `ManagedTemplateCompositionCycleError` naming the chain, and a chain longer than `maxDepth`
+ * throws `ManagedTemplateCompositionDepthError`. Neither can be caught by the engine
+ * downstream, so both are found here rather than as a hang at send time.
+ */
+import { type TemplateField } from './constants.js';
+import type { ManagedTemplate } from './types.js';
+/**
+ * Prefixed so a composition tag can never be confused with an engine tag meant to survive into
+ * the rendered output. Configurable on a composer, but the whole prefix is reserved: unknown
+ * tags carrying it are rejected instead of passed through.
+ */
+export declare const DEFAULT_TAG_PREFIX = "managed_";
+/**
+ * How many references deep a single chain may go — extends and include both count, since both
+ * resolve another template. High enough that no real layout hits it, low enough that a
+ * pathological store fails fast instead of exhausting the stack.
+ */
+export declare const DEFAULT_MAX_DEPTH = 25;
+/**
+ * What `getTemplate` looks like from here: a key and an optional version in, one template out.
+ * `BaseTemplateManagerBackend.getTemplate` satisfies it as it stands.
+ */
+export type TemplateResolver = (key: string, version: number | null) => Promise<ManagedTemplate>;
+/** One direct reference from a template's field to another template. */
+export type TemplateReference = {
+    kind: 'extends' | 'include';
+    key: string;
+    version: number | null;
+    field: TemplateField;
+};
+export type TemplateComposerOptions = {
+    tagPrefix?: string;
+    maxDepth?: number;
+};
+/** Resolves `managed_*` composition tags against a template store. */
+export declare class TemplateComposer {
+    private readonly resolveTemplate;
+    readonly tagPrefix: string;
+    readonly maxDepth: number;
+    /**
+     * @param resolveTemplate how a referenced key becomes a template — normally a backend's
+     *   `getTemplate`. Left out, the composer still parses (so `references`, `isAbstract` and
+     *   syntax checking work), but any template that actually references another throws
+     *   `ManagedTemplateCompositionReferenceError`.
+     * @param options `tagPrefix` — the reserved prefix every composition tag carries; change it
+     *   only if `managed_` collides with something the engine downstream must receive verbatim.
+     *   `maxDepth` — how many references deep one chain may go before it is called runaway.
+     */
+    constructor(resolveTemplate?: TemplateResolver | null, options?: TemplateComposerOptions);
+    /** A composer that resolves references through `backend.getTemplate`. */
+    static fromBackend(backend: {
+        getTemplate(key: string, version?: number | null): Promise<ManagedTemplate>;
+    }, options?: TemplateComposerOptions): TemplateComposer;
+    /**
+     * Resolve every composition tag in a template, returning the flattened result.
+     *
+     * Each of the three sources is composed against the same field of whatever it references. The
+     * template handed in is never mutated; a template with no composition tags in it is returned
+     * as it stands, same object and all.
+     */
+    compose(template: ManagedTemplate): Promise<ManagedTemplate>;
+    /**
+     * Compose one source string that is not (yet) a stored template.
+     *
+     * This is the path for source in hand rather than in the store: an admin validating what was
+     * typed into a form before saving it, a preview of an unsaved draft.
+     *
+     * Pass `key` (and `version`) when the source belongs to a template that exists, so a chain
+     * that leads back to it is reported as the cycle it is instead of composing the stored — and
+     * by then stale — copy of the very row being edited.
+     */
+    composeSource(source: string, options?: {
+        field?: TemplateField;
+        key?: string;
+        version?: number | null;
+    }): Promise<string>;
+    /** Compose a single field of a template, leaving the other two alone. */
+    composeField(template: ManagedTemplate, field: TemplateField): Promise<string | null>;
+    /**
+     * Compose the template and throw the result away, to surface any problem now.
+     *
+     * What an admin form or a deploy check calls: it throws exactly what rendering would have
+     * thrown, at a point where someone can still fix it.
+     */
+    validate(template: ManagedTemplate): Promise<void>;
+    /**
+     * Every template this one directly names, across all three fields.
+     *
+     * Direct only: what the references themselves reference is not followed, so this needs no
+     * store and never throws for a missing template. Order is the order they appear, field by
+     * field.
+     */
+    references(template: ManagedTemplate): TemplateReference[];
+    /** Every template one source string directly names. */
+    sourceReferences(source: string, field?: TemplateField): TemplateReference[];
+    /**
+     * Whether this template is a base to build on rather than one to send.
+     *
+     * True when any of its fields declares a `{% managed_children %}` hole, or declares blocks
+     * without extending anything — the two shapes that only make sense with a child underneath.
+     * Nothing is stored: abstractness is a property of the source, so a template becomes abstract
+     * the moment someone writes the hole into it and stops being abstract the moment they take it
+     * out.
+     *
+     * Composing an abstract template directly is allowed and yields the layout with an empty hole.
+     * Use this to keep one out of a picker where a *sendable* template is being chosen.
+     */
+    isAbstract(template: ManagedTemplate): boolean;
+    /**
+     * Whether one source string is a base to build on rather than one to send.
+     *
+     * The per-field half of {@link isAbstract}, for source in hand rather than a whole template.
+     */
+    sourceIsAbstract(source: string, field?: TemplateField): boolean;
+    /**
+     * Walk the inheritance chain from this source upwards, rendering once at the top.
+     *
+     * Overrides accumulate on the way up: each level's blocks are pushed *under* the ones already
+     * collected, so the most derived definition stays at the head of every chain and
+     * `{% managed_super %}` reaches the next one down it. The content each level writes outside its
+     * blocks is rendered as it is passed, becoming the children of the level above — which is what
+     * lets a middle template wrap its own child's content before handing it on.
+     */
+    private composeInternal;
+    private render;
+    /**
+     * Fetch a referenced template and extend the chain with it.
+     *
+     * Cycles are compared on the *resolved* version rather than on the requested one, so a template
+     * reached once by name and once by an explicit `version=` is recognized as the same row.
+     */
+    private resolve;
+    /**
+     * Turn a source string into a node tree, rejecting anything malformed.
+     *
+     * A tag sitting alone on its line takes the whole line with it — its indentation and the
+     * newline after it — so a layout written to be readable does not compose into one full of
+     * blank lines. A tag with content beside it is removed exactly, and the whitespace around it
+     * is the author's.
+     */
+    private parse;
+    private tag;
+    private syntax;
+    private referenceArgs;
+    private blockName;
+    private expectNoArgs;
+}
+/**
+ * Whether a template is a base to build on rather than one to send.
+ *
+ * The store-free shortcut for `TemplateComposer.isAbstract`: abstractness is read off the
+ * source, so no backend is needed to answer it. This is what a backend calls on every write to
+ * keep `ManagedTemplate.isAbstract` in step with the sources.
+ */
+export declare function isAbstract(template: Pick<ManagedTemplate, TemplateField>, tagPrefix?: string): boolean;
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEjG,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAoLF,sEAAsE;AACtE,qBAAa,gBAAgB;IAezB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAdlC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;;OAQG;gBAEgB,eAAe,GAAE,gBAAgB,GAAG,IAAW,EAChE,OAAO,GAAE,uBAA4B;IAMvC,yEAAyE;IACzE,MAAM,CAAC,WAAW,CAChB,OAAO,EAAE;QAAE,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;KAAE,EACxF,OAAO,GAAE,uBAA4B,GACpC,gBAAgB;IAQnB;;;;;;OAMG;IACG,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAkClE;;;;;;;;;OASG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,aAAa,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GAC7E,OAAO,CAAC,MAAM,CAAC;IAOlB,yEAAyE;IACnE,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAW3F;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxD;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,iBAAiB,EAAE;IAY1D,uDAAuD;IACvD,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,aAA8B,GAAG,iBAAiB,EAAE;IAc5F;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAI9C;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,aAA8B,GAAG,OAAO;IAyBhF;;;;;;;;OAQG;YACW,eAAe;YA4Cf,MAAM;IA2EpB;;;;;OAKG;YACW,OAAO;IAmDrB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK;IAqGb,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,YAAY;CAUrB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,EAC9C,SAAS,GAAE,MAA2B,GACrC,OAAO,CAGT"}

package/dist/constants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The vocabulary every other module in this package is written against.
+ *
+ * Statuses are string unions rather than enums, matching how `vintasend` spells
+ * `NotificationStatus`: the values travel over HTTP and through a database as strings, and a
+ * union keeps the stored form and the typed form the same thing.
+ */
+export declare const MANAGED_TEMPLATE_STATUSES: readonly ["draft", "active", "inactive", "archived"];
+export type ManagedTemplateStatus = (typeof MANAGED_TEMPLATE_STATUSES)[number];
+/**
+ * The statuses a version has to be in to count as its key's current one for the
+ * `mostRecentActiveVersion` filter: what is published now, plus the draft on its way to
+ * replacing it. `inactive` and `archived` versions are history — a key whose versions are all
+ * retired has no current version at all and drops out of that filter entirely.
+ */
+export declare const MOST_RECENT_ACTIVE_VERSION_STATUSES: readonly ManagedTemplateStatus[];
+/**
+ * Whether a tag is still offered when tagging a template.
+ *
+ * `archived` retires a tag from the pickers and suggestion lists a UI builds without breaking
+ * the templates already carrying it: an archived tag keeps its links, and filtering by it keeps
+ * working. Deleting the tag is the operation that severs those links.
+ */
+export declare const MANAGED_TEMPLATE_TAG_STATUSES: readonly ["active", "archived"];
+export type ManagedTemplateTagStatus = (typeof MANAGED_TEMPLATE_TAG_STATUSES)[number];
+/**
+ * The three sources a template carries, composed independently and each against the same field
+ * of whatever it references.
+ */
+export declare const TEMPLATE_FIELDS: readonly ["bodyTemplate", "subjectTemplate", "preheaderTemplate"];
+export type TemplateField = (typeof TEMPLATE_FIELDS)[number];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,yBAAyB,sDAAuD,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,EAAE,SAAS,qBAAqB,EAG/E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,iCAAkC,CAAC;AAE7E,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtF;;;GAGG;AACH,eAAO,MAAM,eAAe,mEAAoE,CAAC;AAEjG,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,31 @@
+/**
+ * The vocabulary every other module in this package is written against.
+ *
+ * Statuses are string unions rather than enums, matching how `vintasend` spells
+ * `NotificationStatus`: the values travel over HTTP and through a database as strings, and a
+ * union keeps the stored form and the typed form the same thing.
+ */
+export const MANAGED_TEMPLATE_STATUSES = ['draft', 'active', 'inactive', 'archived'];
+/**
+ * The statuses a version has to be in to count as its key's current one for the
+ * `mostRecentActiveVersion` filter: what is published now, plus the draft on its way to
+ * replacing it. `inactive` and `archived` versions are history — a key whose versions are all
+ * retired has no current version at all and drops out of that filter entirely.
+ */
+export const MOST_RECENT_ACTIVE_VERSION_STATUSES = [
+    'active',
+    'draft',
+];
+/**
+ * Whether a tag is still offered when tagging a template.
+ *
+ * `archived` retires a tag from the pickers and suggestion lists a UI builds without breaking
+ * the templates already carrying it: an archived tag keeps its links, and filtering by it keeps
+ * working. Deleting the tag is the operation that severs those links.
+ */
+export const MANAGED_TEMPLATE_TAG_STATUSES = ['active', 'archived'];
+/**
+ * The three sources a template carries, composed independently and each against the same field
+ * of whatever it references.
+ */
+export const TEMPLATE_FIELDS = ['bodyTemplate', 'subjectTemplate', 'preheaderTemplate'];

package/dist/errors.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Every failure this package reports, as a class a caller can branch on.
+ *
+ * `instanceof` works across the whole hierarchy because each constructor restores the prototype
+ * chain — TypeScript compiled to an ES5-era target breaks it otherwise, and this package is
+ * consumed by applications that pick their own target.
+ */
+export declare class ManagedTemplateError extends Error {
+    constructor(message: string);
+}
+/** Raised when a template is not found in the backend. */
+export declare class ManagedTemplateNotFoundError extends ManagedTemplateError {
+}
+/** Raised when a filter is malformed or names a field the vocabulary does not have. */
+export declare class ManagedTemplateInvalidFilterError extends ManagedTemplateError {
+}
+/**
+ * Raised when a listing asks for an order the configured backend cannot apply.
+ *
+ * This throws rather than quietly dropping the order, which is the difference between ordering
+ * and filtering: a dropped filter returns more rows than asked for, which a caller can see, while
+ * a dropped order returns the same rows in an arbitrary sequence that looks sorted. Read
+ * `getBackendSupportedFilterCapabilities()` and offer only the fields it reports.
+ */
+export declare class ManagedTemplateUnsupportedOrderingError extends ManagedTemplateError {
+}
+/** Raised when a status change is attributed to a user the backend cannot resolve. */
+export declare class ManagedTemplateChangeUserNotFoundError extends ManagedTemplateError {
+}
+/** Raised when a status change is not allowed from the version's current status. */
+export declare class ManagedTemplateStatusTransitionError extends ManagedTemplateError {
+}
+/** Raised when a tag is not found in the backend. */
+export declare class ManagedTemplateTagNotFoundError extends ManagedTemplateError {
+}
+/** Raised when creating a tag whose text already slugs onto an existing tag. */
+export declare class ManagedTemplateTagAlreadyExistsError extends ManagedTemplateError {
+}
+/** Raised when a tag's text is empty or has nothing that can be slugified. */
+export declare class ManagedTemplateInvalidTagError extends ManagedTemplateError {
+}
+/**
+ * Base class for every failure of {@link TemplateComposer}.
+ *
+ * Composition runs before the template engine does, so nothing here can be caught (or reported)
+ * by the engine downstream. Catch this to treat "the template could not be assembled" as one
+ * condition, or a subclass to tell a typo apart from a missing base.
+ */
+export declare class ManagedTemplateCompositionError extends ManagedTemplateError {
+}
+/** Raised when a `managed_*` composition tag is malformed, unknown or unbalanced. */
+export declare class ManagedTemplateCompositionSyntaxError extends ManagedTemplateCompositionError {
+}
+/**
+ * Raised when a template extends or includes a template that does not exist.
+ *
+ * The Python sibling makes this a `ManagedTemplateNotFoundError` as well, so code already
+ * handling a missing template keeps working. TypeScript has no multiple inheritance, so the
+ * relationship is carried by {@link isNotFoundError} instead — check with that rather than with
+ * a bare `instanceof ManagedTemplateNotFoundError`, and test for
+ * `ManagedTemplateCompositionError` *before* "not found" wherever the distinction matters: a
+ * base that does not exist is a broken composition of a template that does.
+ */
+export declare class ManagedTemplateCompositionReferenceError extends ManagedTemplateCompositionError {
+}
+/** Raised when a chain of extends/include references comes back to where it started. */
+export declare class ManagedTemplateCompositionCycleError extends ManagedTemplateCompositionError {
+}
+/** Raised when a chain of references runs deeper than the composer's `maxDepth`. */
+export declare class ManagedTemplateCompositionDepthError extends ManagedTemplateCompositionError {
+}
+/**
+ * Whether an error means "the thing you asked for is not in the store".
+ *
+ * True for {@link ManagedTemplateNotFoundError} and for
+ * {@link ManagedTemplateCompositionReferenceError}, which is a missing template reached through
+ * a template that exists.
+ */
+export declare function isNotFoundError(error: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +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"}