@cosmicdrift/kumiko-renderer-mail-html 0.368.0 → 0.370.0

package/dist/feature.d.ts

@@ -1,3 +1,3 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-types/feature";
-import { type MailHtmlRenderOptions } from "./render.js";
+import { type MailHtmlRenderOptions } from "./render.ts";
 export declare function createRendererMailHtmlFeature(options?: MailHtmlRenderOptions): FeatureDefinition;

package/dist/feature.js

@@ -1,5 +1,5 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { mailHtmlRender } from "./render.js";
+import { mailHtmlRender, readMailChrome } from "./render.js";
 // renderer-mail-html: plugin for renderer-foundation, renders `kind="mail"`
 // requests to subject + email-safe HTML + plain text.
 //
@@ -19,12 +19,13 @@ import { mailHtmlRender } from "./render.js";
 // the tenant-editable footer region, so a tenant cannot remove it.
 export function createRendererMailHtmlFeature(options = {}) {
     return defineFeature("renderer-mail-html", (r) => {
-        r.describe('A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`\'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.');
+        r.describe('A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`\'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. `readMailChrome` hands the same brand row and footer, resolved for one locale, to pages a recipient opens from a mail, such as the unsubscribe page. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.');
         r.requires({ features: ["renderer-foundation"] });
         r.requires({ features: ["template-resolver"] });
         r.useExtension("renderer", "mail-html", {
             kinds: ["mail"],
             render: (req, ctx) => mailHtmlRender(req, ctx, options),
+            readMailChrome: (req, ctx) => readMailChrome(req, ctx, options),
         });
     });
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.js";
-export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, type DocumentFormat, mergeResourceFileRefs, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
-export { createRendererMailHtmlFeature } from "./feature.js";
-export type { MailFooter, MailFooterLink, MailFooterResolver } from "./mail-footer.js";
-export { MAIL_CHROME_EN } from "./mail-strings.js";
-export { type MailBrandSuffixResolver, type MailHtmlRenderOptions, type MailSiteUrlResolver, mailHtmlRender, } from "./render.js";
+export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.ts";
+export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, type DocumentFormat, mergeResourceFileRefs, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.ts";
+export { createRendererMailHtmlFeature } from "./feature.ts";
+export type { MailFooter, MailFooterLink, MailFooterResolver } from "./mail-footer.ts";
+export { MAIL_CHROME_EN } from "./mail-strings.ts";
+export { type MailBrandSuffixResolver, type MailHtmlRenderOptions, type MailSiteUrlResolver, mailHtmlRender, readMailChrome, } from "./render.ts";

package/dist/index.js

@@ -2,4 +2,4 @@ export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.js";
 export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, mergeResourceFileRefs, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
 export { createRendererMailHtmlFeature } from "./feature.js";
 export { MAIL_CHROME_EN } from "./mail-strings.js";
-export { mailHtmlRender, } from "./render.js";
+export { mailHtmlRender, readMailChrome, } from "./render.js";

package/dist/mail-footer.d.ts

@@ -13,12 +13,18 @@ export type MailFooterResolver = (input: {
     readonly locale: string;
     readonly ctx: RendererContext;
 }) => MailFooter | null | Promise<MailFooter | null>;
+type LabeledLink = {
+    readonly label: string;
+    readonly url: string;
+};
+export declare function webHost(url: string): string | null;
 export declare function buildMailBandLinksHtml(input: {
     readonly siteUrl: string | undefined;
     readonly unsubscribeUrl: string;
     readonly locale: string;
     readonly layoutLinksUnsubscribe: boolean;
 }): string;
+export declare function resolvedFooterLink(link: MailFooterLink | undefined, fallbackLabel: string): LabeledLink | undefined;
 export declare function safeFooterUrl(link: MailFooterLink | undefined): string;
 export declare function buildMailFooterHtml(input: {
     readonly footer: MailFooter | null;
@@ -28,3 +34,4 @@ export declare function buildMailFooterHtml(input: {
     readonly layoutLinksUnsubscribe: boolean;
 }): string;
 export declare function layoutLinksToPlaceholder(layoutHtml: string, name: string): boolean;
+export {};

package/dist/mail-footer.js

@@ -8,7 +8,7 @@ function linkHtml(link, color = "#888") {
         return null;
     return `<a href="${escapeHtmlAttr(url)}" style="color:${escapeHtmlAttr(color)}">${escapeHtml(link.label)}</a>`;
 }
-function webHost(url) {
+export function webHost(url) {
     try {
         const parsed = new URL(url);
         return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.host : null;
@@ -33,6 +33,13 @@ export function buildMailBandLinksHtml(input) {
     ];
     return links.filter((link) => link !== null).join(" · ");
 }
+export function resolvedFooterLink(link, fallbackLabel) {
+    if (link === undefined)
+        return undefined;
+    const url = link.url.trim();
+    const label = (link.label ?? fallbackLabel).trim();
+    return SAFE_FOOTER_URL.test(url) && label !== "" ? { label, url } : undefined;
+}
 export function safeFooterUrl(link) {
     return link !== undefined && SAFE_FOOTER_URL.test(link.url.trim()) ? link.url.trim() : "";
 }

package/dist/render.d.ts

@@ -1,5 +1,5 @@
-import { type RendererContext, type RenderRequest, type RenderResponse } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
-import { type MailFooterResolver } from "./mail-footer.js";
+import { type MailChromeRequest, type MailChrome as MailPageChrome, type RendererContext, type RenderRequest, type RenderResponse } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import { type MailFooterResolver } from "./mail-footer.ts";
 export type MailBrandSuffixResolver = (input: {
     readonly locale: string;
     readonly ctx: RendererContext;
@@ -15,4 +15,5 @@ export type MailHtmlRenderOptions = {
     /** Site link in the mail band when the tenant's branding has no site URL. */
     readonly siteUrl?: MailSiteUrlResolver;
 };
+export declare function readMailChrome(req: MailChromeRequest, ctx: RendererContext, options?: MailHtmlRenderOptions): Promise<MailPageChrome>;
 export declare function mailHtmlRender(req: RenderRequest, ctx: RendererContext, options?: MailHtmlRenderOptions): Promise<RenderResponse>;

package/dist/render.js

@@ -18,7 +18,7 @@ import { DEFAULT_MAIL_LAYOUT_SLUG } from "./default-layout.js";
 import { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, LOGO_RESOURCE_KEY, mergeResourceFileRefs, readBrandingAccentColor, readBrandingLogo, readBrandingLogoUrl, readBrandingSiteUrl, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
 import { buildRenderedPdfAttachments, combineMailAttachments, mergeInheritedAttachments, } from "./mail-attachments.js";
 import { brandHeaderHtml, DEFAULT_ACCENT_COLOR, readMailTone, toneColors, } from "./mail-chrome.js";
-import { buildMailBandLinksHtml, buildMailFooterHtml, layoutLinksToPlaceholder, safeFooterUrl, } from "./mail-footer.js";
+import { buildMailBandLinksHtml, buildMailFooterHtml, layoutLinksToPlaceholder, resolvedFooterLink, safeFooterUrl, webHost, } from "./mail-footer.js";
 import { mailChromeText } from "./mail-strings.js";
 import { MAIL_IMAGE_MAX_WIDTH_PX, renderStructuredLayoutMjml } from "./structured-layout.js";
 const LINE_BREAKS = /[\r\n]+/g;
@@ -433,6 +433,31 @@ function renderFooterParts(args) {
             : "",
     };
 }
+export async function readMailChrome(req, ctx, options = {}) {
+    const { locale } = req;
+    const [tenantName, footer, siteUrl, brandSuffix, logoUrl, accentColor] = await Promise.all([
+        readTenantName(ctx),
+        resolveMailFooter(options, ctx, locale),
+        resolveMailSiteUrl(options, ctx, locale),
+        resolveBrandSuffix(options, ctx, locale),
+        readBrandingLogoUrl(ctx),
+        readBrandingAccentColor(ctx),
+    ]);
+    const footerText = footer?.text?.trim() ?? "";
+    const imprint = resolvedFooterLink(footer?.imprint, mailChromeText(locale, "mail.footer.imprint"));
+    const privacy = resolvedFooterLink(footer?.privacy, mailChromeText(locale, "mail.footer.privacy"));
+    const safeSiteUrl = siteUrl?.trim();
+    return {
+        tenantName,
+        brandSuffix,
+        ...(logoUrl !== undefined && { logoUrl }),
+        ...(accentColor !== undefined && { accentColor }),
+        ...(safeSiteUrl !== undefined && webHost(safeSiteUrl) !== null && { siteUrl: safeSiteUrl }),
+        ...(footerText !== "" && { footerText }),
+        ...(imprint !== undefined && { imprint }),
+        ...(privacy !== undefined && { privacy }),
+    };
+}
 export async function mailHtmlRender(req, ctx, options = {}) {
     if (req.kind !== "mail") {
         // Foundation selects plugins only for matching kinds; defensive guard.

package/dist/structured-layout.d.ts

@@ -1,5 +1,5 @@
 import { type MailLayoutAppearance } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
-import { type ToneColors } from "./mail-chrome.js";
+import { type ToneColors } from "./mail-chrome.ts";
 export declare const MAIL_IMAGE_MAX_WIDTH_PX = 180;
 export type StructuredLayoutInput = {
     readonly layoutHtml: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-mail-html",
-  "version": "0.368.0",
+  "version": "0.370.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",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -19,17 +19,17 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.368.0",
-    "@cosmicdrift/kumiko-framework": "0.368.0",
-    "@cosmicdrift/kumiko-headless": "0.368.0",
-    "@cosmicdrift/kumiko-types": "0.368.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.370.0",
+    "@cosmicdrift/kumiko-framework": "0.370.0",
+    "@cosmicdrift/kumiko-headless": "0.370.0",
+    "@cosmicdrift/kumiko-types": "0.370.0",
     "handlebars": "^4.7.8",
     "html-to-text": "^9.0.5",
     "mjml": "^5.2.2"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.368.0",
-    "@cosmicdrift/kumiko-testing": "0.368.0",
+    "@cosmicdrift/kumiko-locale-de": "0.370.0",
+    "@cosmicdrift/kumiko-testing": "0.370.0",
     "@types/html-to-text": "^9.0.4",
     "@types/mjml": "^5.0.0"
   },

package/src/changes.json

@@ -78,7 +78,7 @@
     "version": "0.363.0",
     "type": "breaking",
     "title": "Package moved to the framework under the @cosmicdrift scope",
-    "detail": "Renamed from @cosmicdriftgamestudio/kumiko-renderer-mail-html (GitHub Packages, kumiko-enterprise) to @cosmicdrift/kumiko-renderer-mail-html on npmjs; the API is unchanged.",
+    "detail": "Renamed from @cosmicdriftgamestudio/kumiko-renderer-mail-html (GitHub Packages, kumiko-enterprise) to @cosmicdrift/kumiko-renderer-mail-html on npmjs. The rename itself changes no API; the other 0.363.0 entries list the API changes of this release.",
     "migration": "Replace @cosmicdriftgamestudio/kumiko-renderer-mail-html with @cosmicdrift/kumiko-renderer-mail-html in package.json and in every import; install from npmjs instead of GitHub Packages."
   },
   {