@cosmicdrift/kumiko-renderer-mail-html 0.386.0 → 0.388.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-renderer-mail-html
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/document-kit.js

@@ -10,6 +10,7 @@ import { TENANT_TIMEZONE_CONFIG_KEY } from "@cosmicdrift/kumiko-framework/pipeli
 import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { DOCUMENT_FALLBACK_CURRENCY, formatDocumentDate, formatDocumentMoney, formatDocumentPercent, } from "@cosmicdrift/kumiko-renderer/headless";
 import Handlebars from "handlebars";
+import { convert as htmlToText } from "html-to-text";
 // Handlebars instance, template resolution and resource lookup shared by the
 // mail and PDF renderers, so both format money/dates and find images the same way.
 const documentKitLogger = createFallbackLogger("renderer-mail-html");
@@ -37,6 +38,15 @@ export function createDocumentHandlebars(format) {
         });
         return value;
     });
+    hbs.registerHelper("richTextPlain", (value) => typeof value === "string"
+        ? htmlToText(value, {
+            wordwrap: false,
+            selectors: [
+                { selector: "a", options: { ignoreHref: true } },
+                { selector: "img", format: "skip" },
+            ],
+        })
+        : "");
     hbs.registerHelper("link", (value) => typeof value === "string" && SAFE_LINK_PROTOCOL.test(value.trim()) ? value : "#");
     hbs.registerHelper("stepIs", function stepIs(value, index, keys, state, options) {
         return isStepInState(value, index, keys, state) ? options.fn(this) : options.inverse(this);
@@ -63,6 +73,7 @@ const KNOWN_HELPERS = {
     richText: true,
     stepIs: true,
     percent: true,
+    richTextPlain: true,
 };
 export function compileDocumentSource(hbs, source, options = {}) {
     return hbs.compile(source, {
@@ -86,6 +97,13 @@ async function readConfigText(ctx, key) {
 export async function readDocumentFormat(ctx, templateLocale) {
     const currency = await readConfigText(ctx, TENANT_CURRENCY_CONFIG_KEY);
     const zone = await readConfigText(ctx, TENANT_TIMEZONE_CONFIG_KEY);
+    if (zone !== undefined && !isValidIanaTimeZone(zone)) {
+        documentKitLogger.warn("tenant time zone is not a valid IANA zone, documents print UTC times", {
+            tenantId: ctx.tenantId,
+            configKey: TENANT_TIMEZONE_CONFIG_KEY,
+            zone,
+        });
+    }
     return {
         locale: templateLocale,
         currency: currency ?? DOCUMENT_FALLBACK_CURRENCY,

package/dist/mail-footer.js

@@ -80,5 +80,5 @@ export function buildMailFooterHtml(input) {
     return lines.join("<br>");
 }
 export function layoutLinksToPlaceholder(layoutHtml, name) {
-    return new RegExp(`href="\\{\\{\\s*${name}\\s*\\}\\}"`).test(layoutHtml);
+    return new RegExp(`<a\\b[^>]*href="\\{\\{\\s*${name}\\s*\\}\\}"[^>]*>\\s*[^<\\s]`).test(layoutHtml);
 }

package/dist/render.js

@@ -23,7 +23,13 @@ import { mailChromeText } from "./mail-strings.js";
 import { MAIL_IMAGE_MAX_WIDTH_PX, renderStructuredLayoutMjml } from "./structured-layout.js";
 const LINE_BREAKS = /[\r\n]+/g;
 const PLAIN_REFERENCE = /\{\{\s*([\w.]+)\s*\}\}/g;
-const FORMATTED_VARIABLE_TYPES = new Set(["money", "date", "percent"]);
+// richText becomes plain text: meta lines render unescaped into subject and layout rows.
+const META_FORMAT_HELPER_BY_TYPE = {
+    money: "money",
+    date: "date",
+    percent: "percent",
+    richText: "richTextPlain",
+};
 function describe(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -218,9 +224,10 @@ async function renderMailBody(tplApi, ctx, template, hbs, context, buttonInlineS
 function withFormatHelpers(source, variables) {
     return source.replace(PLAIN_REFERENCE, (reference, name) => {
         const type = variables[name]?.type;
-        return type !== undefined && FORMATTED_VARIABLE_TYPES.has(type)
-            ? `{{${type} ${name}}}`
-            : reference;
+        const helper = type !== undefined && Object.hasOwn(META_FORMAT_HELPER_BY_TYPE, type)
+            ? META_FORMAT_HELPER_BY_TYPE[type]
+            : undefined;
+        return helper === undefined ? reference : `{{${helper} ${name}}}`;
     });
 }
 function renderSubjectLine(hbs, source, context, variables) {
@@ -302,6 +309,17 @@ async function assembleMailAttachments(args) {
     });
     return combineMailAttachments(slug, inlineAttachments, mergeInheritedAttachments(template.fileAttachments ?? [], inherited.fileAttachments ?? [], (file) => file.fileName), renderedPdfs);
 }
+const MJML_FOOTER_SECTION = '<mj-section><mj-column><mj-text font-size="12px" color="#5A6170" align="center">{{{mailFooterHtml}}}</mj-text></mj-column></mj-section>';
+// The platform footer (imprint, privacy, unsubscribe) must not depend on the layout author
+// remembering the placeholder.
+function withPlatformFooter(mjmlSource) {
+    if (mjmlSource.includes("mailFooterHtml"))
+        return mjmlSource;
+    const bodyEnd = mjmlSource.lastIndexOf("</mj-body>");
+    return bodyEnd === -1
+        ? mjmlSource
+        : `${mjmlSource.slice(0, bodyEnd)}{{#if mailFooterHtml}}${MJML_FOOTER_SECTION}{{/if}}${mjmlSource.slice(bodyEnd)}`;
+}
 function compileLayoutMjml(args) {
     const { layout, hbs, contentHtml, appearance, accentColor, resourceFileRefs, layoutContext } = args;
     try {
@@ -321,7 +339,7 @@ function compileLayoutMjml(args) {
                 bandLinksHtml: args.bandLinksHtml,
                 footerHtml: args.footerHtml,
             })
-            : compileDocumentSource(hbs, layout.content)({
+            : compileDocumentSource(hbs, withPlatformFooter(layout.content))({
                 ...layoutContext,
                 content: contentHtml,
                 mailFooterHtml: args.footerHtml,
@@ -421,17 +439,23 @@ async function resolveMailSiteUrl(options, ctx, locale) {
         throw new RendererError(`renderer-mail-html: the site URL resolver failed — ${describe(e)}`, "other");
     }
 }
+// Only header, signature and footer reach the mail; a link elsewhere in the layout is never shown.
+function layoutRegionsSource(layoutHtml) {
+    const { header, signature, footer } = readLayoutRegions(layoutHtml);
+    return [header, signature, footer].join("");
+}
 // A structured layout shows the site and unsubscribe links inside the card and only the
 // platform line below it; an mjml layout gets everything in one line.
 function renderFooterParts(args) {
     const { layout, footer, unsubscribeUrl, locale } = args;
     const structured = layout.format === "html";
-    const layoutLinksUnsubscribe = structured && layoutLinksToPlaceholder(layout.content, "unsubscribeUrl");
+    const linkedRegions = structured ? layoutRegionsSource(layout.content) : "";
+    const layoutLinksUnsubscribe = layoutLinksToPlaceholder(linkedRegions, "unsubscribeUrl");
     const footerHtml = buildMailFooterHtml({
         footer,
         unsubscribeUrl: structured ? "" : unsubscribeUrl,
         locale,
-        layoutLinksImprint: structured && layoutLinksToPlaceholder(layout.content, "imprint"),
+        layoutLinksImprint: layoutLinksToPlaceholder(linkedRegions, "imprint"),
         layoutLinksUnsubscribe,
     });
     return {

package/dist/seeding.js

@@ -2,9 +2,10 @@
 // system layout (slug "default", kind "mail-layout", tenantId=SYSTEM_TENANT_ID)
 // into the template-resource table.
 //
-// **When to use?** When the app author wants the default layout editable in the
-// tenant admin UI. Without seeding the renderer falls back to the in-code
-// DEFAULT_MAIL_LAYOUT_MJML, which renders identically but is not editable.
+// **When to use?** When the app author wants an editable layout in the tenant admin
+// UI. Without seeding the renderer falls back to the structured in-code layout with
+// the tenant branding. A seeded MJML layout has its own look and must contain
+// {{{mailFooterHtml}}}, or the platform footer is appended after its body.
 //
 // Idempotent: a second call with unchanged content writes no event, a changed
 // layout updates the existing row.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-mail-html",
-  "version": "0.386.0",
+  "version": "0.388.0",
   "description": "Renderer-Foundation plugin for branded HTML emails: mail-kind templates (document HTML + subject meta) rendered with isolated Handlebars into an MJML layout, plus plain text via html-to-text. Templates resolved from template-resolver.",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "type": "module",
   "kumiko": {
@@ -19,17 +19,17 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.386.0",
-    "@cosmicdrift/kumiko-framework": "0.386.0",
-    "@cosmicdrift/kumiko-renderer": "0.386.0",
-    "@cosmicdrift/kumiko-types": "0.386.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.388.0",
+    "@cosmicdrift/kumiko-framework": "0.388.0",
+    "@cosmicdrift/kumiko-renderer": "0.388.0",
+    "@cosmicdrift/kumiko-types": "0.388.0",
     "handlebars": "^4.7.8",
     "html-to-text": "^9.0.5",
     "mjml": "^5.2.2"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.386.0",
-    "@cosmicdrift/kumiko-testing": "0.386.0",
+    "@cosmicdrift/kumiko-locale-de": "0.388.0",
+    "@cosmicdrift/kumiko-testing": "0.388.0",
     "@types/html-to-text": "^9.0.4",
     "@types/mjml": "^5.0.0"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Mail footer cannot be dropped, richText in subject is plain text",
+    "detail": "An mjml layout without the mailFooterHtml placeholder now gets the platform footer appended before the end of the body. Layout links to the imprint or unsubscribe URL only count when they sit in the header, signature or footer region and have link text. richText variables in subject, preview and other meta lines render as plain text instead of raw HTML. An invalid tenant time zone is logged as a warning."
+  },
   {
     "version": "0.378.0",
     "type": "fix",