vintasend-managed-templates 1.0.0-alpha2

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { BaseTemplateManagerBackend } from './base-template-manager-backend.js';
+export type { TemplateComposerOptions, TemplateReference, TemplateResolver, } from './composition.js';
+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 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 { 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';
+export { MAX_SLUG_LENGTH, nextAvailableSlug, normalizeTagText, slugifyTag } from './tags.js';
+export type { ManagedTemplate, ManagedTemplateCreateInput, ManagedTemplateId, ManagedTemplateStatusHistory, ManagedTemplateTag, ManagedTemplateUpdateInput, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,18 @@
+// Composition
+export { DEFAULT_MAX_DEPTH, DEFAULT_TAG_PREFIX, isAbstract, TemplateComposer, } from './composition.js';
+// 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';
+// 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';
+// Renderers
+export { ManagedTemplateEmailRenderer, ManagedTemplateRenderer, ManagedTemplateTextRenderer, requestedTemplateVersion, } from './managed-template-renderer.js';
+// The service
+export { DEFAULT_STATUS_TRANSITIONS, ManagedTemplateService } from './managed-template-service.js';
+// Tag slugging
+export { MAX_SLUG_LENGTH, nextAvailableSlug, normalizeTagText, slugifyTag } from './tags.js';

package/dist/managed-template-renderer.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The renderer that feeds a stored template to an ordinary VintaSend renderer.
+ *
+ * `ManagedTemplateRenderer` wraps another renderer and swaps out where the template comes from:
+ * instead of a path an engine's loader resolves, the notification's `bodyTemplate` is a key this
+ * package's storage seam looks up. What the inner renderer receives is template *source*, so it
+ * has to implement `renderFromTemplateContent` — which every renderer in the VintaSend ecosystem
+ * does, because that is the seam VintaSend already uses to render content it holds rather than
+ * loads.
+ *
+ * Templates are composed before they reach the inner renderer. A stored template can extend a
+ * base and include shared fragments (see `composition`), and none of that survives into what the
+ * engine sees: it gets one flat string. Composition is on by default and can be turned off per
+ * renderer with `composeTemplates: false`, which is the right call only if a store predates
+ * composition and holds `managed_`-prefixed text meant to be passed through.
+ */
+import type { AnyNotification, BaseLogger, BaseNotificationTemplateRenderer, BaseNotificationTypeConfig, EmailTemplate, EmailTemplateContent, JsonObject } from 'vintasend';
+import type { BaseTemplateManagerBackend } from './base-template-manager-backend.js';
+import { TemplateComposer, type TemplateComposerOptions } from './composition.js';
+import type { ManagedTemplate } from './types.js';
+/**
+ * A notification that names which version of its template it was recorded against.
+ *
+ * VintaSend declares `requestedTemplateVersion` on its own notification types, so this is only
+ * the shape {@link requestedTemplateVersion} needs — kept exported for a host with a notification
+ * type of its own, and for reading a pin off a record that came from somewhere else.
+ */
+export type VersionPinnedNotification = {
+    requestedTemplateVersion?: number | null;
+};
+/**
+ * Read a notification's template-version pin, if it carries one.
+ *
+ * Takes `unknown` rather than a notification type because it is also pointed at records that
+ * predate the field — a backend that never stored it hands back a notification with nothing
+ * there, and `null` is the right answer for those rather than a type error.
+ */
+export declare function requestedTemplateVersion(notification: unknown): number | null;
+/**
+ * What rendering a managed template produced, and which version produced it.
+ *
+ * `render` also stamps the version onto the rendered payload itself, which is how VintaSend's
+ * service picks it up — see {@link ManagedTemplateRenderer.render}. This richer result is for a
+ * caller driving the render directly, where reading a documented field beats fishing an optional
+ * one off the payload.
+ */
+export type ManagedTemplateRenderResult<RenderedType> = {
+    key: string;
+    version: number;
+    rendered: RenderedType;
+};
+/**
+ * The email content a managed template produces.
+ *
+ * `EmailTemplateContent` as VintaSend defines it, plus the preheader managed templates carry.
+ * A renderer that knows about preheaders can read it; one that does not ignores the extra field,
+ * which is why it is added rather than replacing the shape.
+ */
+export type ManagedEmailTemplateContent = EmailTemplateContent & {
+    preheader: string | null;
+};
+export type ManagedTemplateRendererOptions = {
+    /**
+     * When true (the default), `managed_*` inheritance and inclusion tags are resolved before the
+     * inner renderer sees the template.
+     */
+    composeTemplates?: boolean;
+    /**
+     * The composer to resolve them with. Defaults to one reading through the template manager
+     * backend; pass your own to change the tag prefix or the depth limit.
+     */
+    composer?: TemplateComposer;
+    /** Options for the default composer. Ignored when `composer` is given. */
+    composerOptions?: TemplateComposerOptions;
+};
+export declare abstract class ManagedTemplateRenderer<Config extends BaseNotificationTypeConfig, RenderedType, ContentType> implements BaseNotificationTemplateRenderer<Config, RenderedType> {
+    readonly managerBackend: BaseTemplateManagerBackend;
+    readonly renderer: BaseNotificationTemplateRenderer<Config, RenderedType>;
+    logger: BaseLogger | null;
+    readonly composeTemplates: boolean;
+    readonly composer: TemplateComposer;
+    constructor(managerBackend: BaseTemplateManagerBackend, renderer: BaseNotificationTemplateRenderer<Config, RenderedType>, options?: ManagedTemplateRendererOptions);
+    injectLogger(logger: BaseLogger): void;
+    /** Build the inner renderer's template content from a stored template. */
+    abstract createTemplateContent(template: ManagedTemplate): ContentType;
+    /**
+     * Resolve a template's composition tags, unless this renderer was told not to.
+     *
+     * @throws ManagedTemplateCompositionError if the template cannot be assembled.
+     */
+    compose(template: ManagedTemplate): Promise<ManagedTemplate>;
+    /**
+     * The newest version of a stored template, for a host to pin a notification to.
+     *
+     * Answers with whatever version the backend considers current for that key, which is the same
+     * version `render` would resolve to if the notification were left unpinned. A key with nothing
+     * behind it answers `null` rather than throwing: a missing template is the send's problem to
+     * report, and failing here would fail the *creation* of a notification over a template that
+     * might well exist by the time it is sent.
+     */
+    getLatestTemplateVersion(templateKey: string): Promise<number | null>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: ContentType, context: JsonObject): Promise<RenderedType>;
+    /**
+     * Render a notification against a template already in hand, with no backend read.
+     *
+     * The template is composed first, so one already fetched and edited in memory renders the same
+     * way a stored one does.
+     */
+    renderTemplate(notification: AnyNotification<Config>, template: ManagedTemplate, context: JsonObject): Promise<ManagedTemplateRenderResult<RenderedType>>;
+    /**
+     * Render a notification against a specific version of its template, reporting which version
+     * was used.
+     *
+     * The notification's `bodyTemplate` is the template key. Which version renders is decided in
+     * this order: the `version` argument, then the notification's own `requestedTemplateVersion`,
+     * then whatever the backend considers current.
+     *
+     * The argument is there to render a version the notification is *not* pinned to — previewing
+     * an unpublished draft, or reproducing what an old notification looked like. Leave it off and
+     * this renders what a real send would.
+     */
+    renderManaged(notification: AnyNotification<Config>, context: JsonObject, version?: number | null): Promise<ManagedTemplateRenderResult<RenderedType>>;
+    /**
+     * Render a notification against the version it is pinned to, or the current one.
+     *
+     * This is the `BaseNotificationTemplateRenderer` seam VintaSend itself calls, so the rendered
+     * payload is all it can return — and the version that produced it is stamped onto that payload
+     * as `templateVersion`. That is the channel VintaSend reads: an adapter returns the payload from
+     * `send()`, and the service records the version on the notification as `usedTemplateVersion`.
+     * On an unpinned notification it is the only record of which version went out, since the
+     * template has moved on by the time anyone asks.
+     *
+     * Call {@link renderManaged} instead when driving the render yourself and the version matters.
+     */
+    render(notification: AnyNotification<Config>, context: JsonObject): Promise<RenderedType>;
+}
+/** A managed-template renderer for email, feeding subject, body and preheader downstream. */
+export declare class ManagedTemplateEmailRenderer<Config extends BaseNotificationTypeConfig> extends ManagedTemplateRenderer<Config, EmailTemplate, ManagedEmailTemplateContent> {
+    createTemplateContent(template: ManagedTemplate): ManagedEmailTemplateContent;
+}
+/** The rendered payload of a text-only channel, as VintaSend's text renderers produce it. */
+export type TextTemplate = {
+    text: string;
+};
+/** The content a text-only renderer is fed. */
+export type TextTemplateContent = {
+    text: string;
+};
+/** A managed-template renderer for SMS and other text-only channels. */
+export declare class ManagedTemplateTextRenderer<Config extends BaseNotificationTypeConfig> extends ManagedTemplateRenderer<Config, TextTemplate, TextTemplateContent> {
+    createTemplateContent(template: ManagedTemplate): TextTemplateContent;
+}
+//# sourceMappingURL=managed-template-renderer.d.ts.map

package/dist/managed-template-renderer.d.ts.map

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

package/dist/managed-template-renderer.js

@@ -0,0 +1,152 @@
+/**
+ * The renderer that feeds a stored template to an ordinary VintaSend renderer.
+ *
+ * `ManagedTemplateRenderer` wraps another renderer and swaps out where the template comes from:
+ * instead of a path an engine's loader resolves, the notification's `bodyTemplate` is a key this
+ * package's storage seam looks up. What the inner renderer receives is template *source*, so it
+ * has to implement `renderFromTemplateContent` — which every renderer in the VintaSend ecosystem
+ * does, because that is the seam VintaSend already uses to render content it holds rather than
+ * loads.
+ *
+ * Templates are composed before they reach the inner renderer. A stored template can extend a
+ * base and include shared fragments (see `composition`), and none of that survives into what the
+ * engine sees: it gets one flat string. Composition is on by default and can be turned off per
+ * renderer with `composeTemplates: false`, which is the right call only if a store predates
+ * composition and holds `managed_`-prefixed text meant to be passed through.
+ */
+import { TemplateComposer } from './composition.js';
+import { ManagedTemplateNotFoundError } from './errors.js';
+/**
+ * Read a notification's template-version pin, if it carries one.
+ *
+ * Takes `unknown` rather than a notification type because it is also pointed at records that
+ * predate the field — a backend that never stored it hands back a notification with nothing
+ * there, and `null` is the right answer for those rather than a type error.
+ */
+export function requestedTemplateVersion(notification) {
+    const pin = notification?.requestedTemplateVersion;
+    return typeof pin === 'number' ? pin : null;
+}
+export class ManagedTemplateRenderer {
+    constructor(managerBackend, renderer, options = {}) {
+        this.managerBackend = managerBackend;
+        this.renderer = renderer;
+        this.logger = null;
+        this.composeTemplates = options.composeTemplates ?? true;
+        this.composer =
+            options.composer ?? TemplateComposer.fromBackend(managerBackend, options.composerOptions);
+    }
+    injectLogger(logger) {
+        this.logger = logger;
+        this.renderer.injectLogger?.(logger);
+    }
+    /**
+     * Resolve a template's composition tags, unless this renderer was told not to.
+     *
+     * @throws ManagedTemplateCompositionError if the template cannot be assembled.
+     */
+    async compose(template) {
+        if (!this.composeTemplates) {
+            return template;
+        }
+        return this.composer.compose(template);
+    }
+    /**
+     * The newest version of a stored template, for a host to pin a notification to.
+     *
+     * Answers with whatever version the backend considers current for that key, which is the same
+     * version `render` would resolve to if the notification were left unpinned. A key with nothing
+     * behind it answers `null` rather than throwing: a missing template is the send's problem to
+     * report, and failing here would fail the *creation* of a notification over a template that
+     * might well exist by the time it is sent.
+     */
+    async getLatestTemplateVersion(templateKey) {
+        try {
+            const template = await this.managerBackend.getTemplate(templateKey);
+            return template.version;
+        }
+        catch (error) {
+            if (error instanceof ManagedTemplateNotFoundError) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    renderFromTemplateContent(notification, templateContent, context) {
+        return this.renderer.renderFromTemplateContent(notification, templateContent, context);
+    }
+    /**
+     * Render a notification against a template already in hand, with no backend read.
+     *
+     * The template is composed first, so one already fetched and edited in memory renders the same
+     * way a stored one does.
+     */
+    async renderTemplate(notification, template, context) {
+        const content = this.createTemplateContent(await this.compose(template));
+        const rendered = await this.renderFromTemplateContent(notification, content, context);
+        return { key: template.key, version: template.version, rendered };
+    }
+    /**
+     * Render a notification against a specific version of its template, reporting which version
+     * was used.
+     *
+     * The notification's `bodyTemplate` is the template key. Which version renders is decided in
+     * this order: the `version` argument, then the notification's own `requestedTemplateVersion`,
+     * then whatever the backend considers current.
+     *
+     * The argument is there to render a version the notification is *not* pinned to — previewing
+     * an unpublished draft, or reproducing what an old notification looked like. Leave it off and
+     * this renders what a real send would.
+     */
+    async renderManaged(notification, context, version = null) {
+        const resolved = version ?? requestedTemplateVersion(notification);
+        const template = await this.managerBackend.getTemplate(notification.bodyTemplate, resolved);
+        return this.renderTemplate(notification, template, context);
+    }
+    /**
+     * Render a notification against the version it is pinned to, or the current one.
+     *
+     * This is the `BaseNotificationTemplateRenderer` seam VintaSend itself calls, so the rendered
+     * payload is all it can return — and the version that produced it is stamped onto that payload
+     * as `templateVersion`. That is the channel VintaSend reads: an adapter returns the payload from
+     * `send()`, and the service records the version on the notification as `usedTemplateVersion`.
+     * On an unpinned notification it is the only record of which version went out, since the
+     * template has moved on by the time anyone asks.
+     *
+     * Call {@link renderManaged} instead when driving the render yourself and the version matters.
+     */
+    async render(notification, context) {
+        const result = await this.renderManaged(notification, context);
+        return withTemplateVersion(result.rendered, result.version);
+    }
+}
+/**
+ * Stamp the version that rendered onto the payload, without mutating what the inner renderer
+ * returned.
+ *
+ * A renderer producing something that is not an object — nothing shipped does, but the seam is
+ * generic — is handed back untouched rather than wrapped, since there is nowhere to put the field
+ * and losing the payload would be the worse trade.
+ */
+function withTemplateVersion(rendered, version) {
+    if (rendered === null || typeof rendered !== 'object') {
+        return rendered;
+    }
+    return { ...rendered, templateVersion: version };
+}
+/** A managed-template renderer for email, feeding subject, body and preheader downstream. */
+export class ManagedTemplateEmailRenderer extends ManagedTemplateRenderer {
+    createTemplateContent(template) {
+        return {
+            subject: template.subjectTemplate,
+            body: template.bodyTemplate,
+            preheader: template.preheaderTemplate,
+        };
+    }
+}
+/** A managed-template renderer for SMS and other text-only channels. */
+export class ManagedTemplateTextRenderer extends ManagedTemplateRenderer {
+    createTemplateContent(template) {
+        return { text: template.bodyTemplate };
+    }
+}