@broberg/mail-templates 0.0.0-stage → 0.2.2

package/dist/index.d.cts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+
+/** Escape text for HTML. Covers quotes too, so the same function is safe in an attribute. */
+declare function escapeHtml(s: string): string;
+/** Escape an attribute value. Same job as escapeHtml here; named so a call site says which it means. */
+declare function escapeAttr(s: string): string;
+/** A body BLOCK. The template supplies structure; the shell supplies markup.
+ *
+ *  vn-leker, reviewing their own v1: a body field that takes `<p class style>`
+ *  works while one person writes both halves — a foreign filler either loses all
+ *  formatting (plain text) or breaks the layout (HTML). */
+declare const MailBlock: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"paragraph">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"note">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"button">;
+    text: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"divider">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"html">;
+    text: z.ZodString;
+}, z.core.$strip>], "type">;
+type MailBlock = z.infer<typeof MailBlock>;
+/** A brand COLOUR — REFUSED, not escaped, when it is not one.
+ *
+ *  Proved against the built shell: an accent colour of
+ *  `#fff;"></td></tr></table><a href="https://phish.example">Log ind her</a>…`
+ *  put that anchor into the mail. An escaped non-colour still leaves the building
+ *  as a broken mail nobody sees an error for; a refusal is an error the project
+ *  reads while it still has the file open. */
+declare function isBrandColor(v: string): boolean;
+/** A font STACK may hold quotes and commas, never a tag delimiter or a quote that closes its attribute. */
+declare function isFontStack(v: string): boolean;
+/** Ceilings on what a stored override may hold — far above any real template, low
+ *  enough that a hostile body costs one issue, not one per element. */
+declare const MAX_BLOCKS = 100;
+declare const MAX_FOOTER_LINES = 20;
+declare const MAX_COPY_KEYS = 200;
+/** Brand values, ALL optional — and EMPTY is a value, not an absence (fd-sundhed
+ *  renders different, correct copy for an empty partner name). */
+declare const MailBrand: z.ZodObject<{
+    partner: z.ZodOptional<z.ZodString>;
+    senderName: z.ZodOptional<z.ZodString>;
+    senderTitle: z.ZodOptional<z.ZodString>;
+    senderEmail: z.ZodOptional<z.ZodString>;
+    logoUrl: z.ZodOptional<z.ZodString>;
+    logoWidth: z.ZodOptional<z.ZodNumber>;
+    logoCid: z.ZodOptional<z.ZodString>;
+    colorAccent: z.ZodOptional<z.ZodString>;
+    colorInk: z.ZodOptional<z.ZodString>;
+    fontSans: z.ZodOptional<z.ZodString>;
+    fontSerif: z.ZodOptional<z.ZodString>;
+    webfontHref: z.ZodOptional<z.ZodString>;
+    footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+type MailBrand = z.infer<typeof MailBrand>;
+/** Greeting, sign-off and other fixed phrases are DATA, per language (vn-leker runs da/no/sv). */
+declare const MailCopy: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>;
+type MailCopy = z.infer<typeof MailCopy>;
+/** One template, keyed on its PURPOSE (fd-sport's model: a project has a set, not one file). */
+declare const MailTemplate: z.ZodObject<{
+    purpose: z.ZodString;
+    subject: z.ZodString;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"paragraph">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"divider">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"html">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    preheader: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodObject<{
+        partner: z.ZodOptional<z.ZodString>;
+        senderName: z.ZodOptional<z.ZodString>;
+        senderTitle: z.ZodOptional<z.ZodString>;
+        senderEmail: z.ZodOptional<z.ZodString>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        logoWidth: z.ZodOptional<z.ZodNumber>;
+        logoCid: z.ZodOptional<z.ZodString>;
+        colorAccent: z.ZodOptional<z.ZodString>;
+        colorInk: z.ZodOptional<z.ZodString>;
+        fontSans: z.ZodOptional<z.ZodString>;
+        fontSerif: z.ZodOptional<z.ZodString>;
+        webfontHref: z.ZodOptional<z.ZodString>;
+        footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    copy: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>;
+type MailTemplate = z.infer<typeof MailTemplate>;
+/** What a tenant stores to change a coded default. Every field optional; `purpose` is the key, not a field. */
+declare const MailTemplateOverride: z.ZodObject<{
+    subject: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"paragraph">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"divider">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"html">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+    preheader: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodObject<{
+        partner: z.ZodOptional<z.ZodString>;
+        senderName: z.ZodOptional<z.ZodString>;
+        senderTitle: z.ZodOptional<z.ZodString>;
+        senderEmail: z.ZodOptional<z.ZodString>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        logoWidth: z.ZodOptional<z.ZodNumber>;
+        logoCid: z.ZodOptional<z.ZodString>;
+        colorAccent: z.ZodOptional<z.ZodString>;
+        colorInk: z.ZodOptional<z.ZodString>;
+        fontSans: z.ZodOptional<z.ZodString>;
+        fontSerif: z.ZodOptional<z.ZodString>;
+        webfontHref: z.ZodOptional<z.ZodString>;
+        footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    copy: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>;
+type MailTemplateOverride = z.infer<typeof MailTemplateOverride>;
+/** The class vocabulary the shell styles — SMALL AND CLOSED. fd-sundhed's dark-mode
+ *  rules target classes IN the content, so the hooks have to be agreed names. */
+declare const MAIL_CLASSES: {
+    readonly bg: "cm-bg";
+    readonly card: "cm-card";
+    readonly p: "cm-p";
+    readonly sm: "cm-sm";
+    readonly btn: "cm-btn";
+    readonly box: "cm-box";
+};
+/** The preheader, DERIVED when not given: the first paragraph or heading, cut on a
+ *  word. Omitted, the inbox shows whatever words fall first (vn-leker #6). */
+declare function derivePreheader(blocks: MailBlock[], given?: string): string;
+/** A link in a mail must be ABSOLUTE — `/da/shop/bog` has no page to resolve
+ *  against (sanne's customer). Returns the reason so a refusal can NAME the link.
+ *
+ *  `filled: true` at render time: a url that is EXACTLY one `{{token}}` is accepted
+ *  when a template is authored (it must not have to know the host's routes) and
+ *  refused once filling has happened, because a surviving token is a dead button. */
+declare function checkUrl(url: string, opts?: {
+    filled?: boolean;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The @broberg/mail-core primitives the body needs, INJECTED.
+ *
+ *  mail-core reads files at module scope (node:fs, for the logo attachment), so
+ *  importing it here would break every browser bundle that renders a preview —
+ *  cardmem measured exactly that on `vite build`. The host passes mail-core's own
+ *  functions; there is no fallback, because a fallback IS a second implementation. */
+interface MailPrimitives {
+    heading: (text: string, opts: {
+        accentColor?: string;
+        fontSerif?: string;
+    }) => string;
+    paragraph: (text: string) => string;
+    noteBox: (html: string, opts: {
+        accentColor: string;
+    }) => string;
+    cta: (href: string, label: string, opts: {
+        accentColor: string;
+    }) => string;
+}
+/** Blocks → body html, styled inline by mail-core and carrying the class hooks. */
+declare function renderBlocks(blocks: MailBlock[], opts: {
+    accentColor: string;
+    primitives: MailPrimitives;
+    fontSerif?: string;
+}): {
+    html: string;
+    notes: string[];
+};
+/** Fill `{{name}}` placeholders, escaping each value.
+ *
+ *  A MISSING value stays as the literal placeholder and is named in `missing` —
+ *  a visible `{{navn}}` is caught; a silently blank sentence is not. An EMPTY value
+ *  is honoured as empty (`in values`, not truthiness). `rawKeys` names values that
+ *  are already HTML — opt-in per call, so a caller must say which key it trusts. */
+declare function fillPlaceholders(text: string, values: Record<string, string>, rawKeys?: readonly string[]): {
+    text: string;
+    missing: string[];
+};
+/** Fill WITHOUT escaping, for a destination that escapes for itself (a subject line,
+ *  a button url). A separate function, not an `escape: false` flag someone flips on a text field. */
+declare function fillPlaceholdersRaw(text: string, values: Record<string, string>): {
+    text: string;
+    missing: string[];
+};
+interface RenderedTemplate {
+    /** The BODY html — wrap it in @broberg/mail-core's renderShell. */
+    html: string;
+    /** Plain text, filled without escaping: a mail client never renders a subject as HTML. */
+    subject: string;
+    /** Explicit or derived — never silently empty. */
+    preheader: string;
+    /** Placeholders with no value, from body, subject and button urls. */
+    missing: string[];
+    /** Findings that did not stop the render but a person should see. */
+    notes: string[];
+}
+/** The WHOLE render, in the one order that is correct: render blocks, THEN fill.
+ *
+ *  Both steps escape, so the other order escapes twice:
+ *    fill THEN render  →  "Sørensen & Søn"  →  "Sørensen &amp;amp; Søn"
+ *    render THEN fill  →  "Sørensen & Søn"  →  "Sørensen &amp; Søn"   ✓
+ *  The wrong order looks right for every customer without an `&` in their name.
+ *
+ *  ONE exception, for the same reason: a button URL is filled FIRST, unescaped, so
+ *  it goes through checkUrl (a value resolving to a relative or javascript: link
+ *  degrades to text) and then the cta primitive's own attribute escaping. */
+declare function renderTemplate(template: Pick<MailTemplate, "subject" | "blocks" | "preheader">, opts: {
+    /** Resolved by the caller (the shell needs the same value — two places deciding a brand colour disagree). */
+    accentColor: string;
+    fontSerif?: string;
+    primitives: MailPrimitives;
+    /** Value keys that are already HTML. See fillPlaceholders. */
+    rawValueKeys?: readonly string[];
+}, values?: Record<string, string>): RenderedTemplate;
+/** The EFFECTIVE template: a stored override over the coded default.
+ *
+ *  subject, blocks and preheader REPLACE; brand and copy MERGE key by key, so a
+ *  tenant that sets only its accent keeps the default's sender and footer. */
+declare function resolveTemplate(standard: MailTemplate, override?: MailTemplateOverride | null): MailTemplate;
+interface EffectiveTemplate {
+    purpose: string;
+    effective: MailTemplate;
+    /** The coded default — what "reset" goes back to. */
+    default: MailTemplate;
+    /** True when the tenant's override changes at least one field. */
+    isCustom: boolean;
+}
+/** Every coded template with its tenant's override applied — what an editor lists.
+ *
+ *  An override whose purpose has no coded default is NAMED in `unknownOverrides`,
+ *  not dropped: a template renamed in code would otherwise lose a tenant's edits
+ *  with nothing to show for it. */
+declare function listEffectiveTemplates(defaults: readonly MailTemplate[], overrides?: Readonly<Record<string, MailTemplateOverride | null | undefined>>): {
+    templates: EffectiveTemplate[];
+    unknownOverrides: string[];
+};
+/** The canonical content a version's hash is taken over: stable key ORDER, so a
+ *  moved JSON key is not reported as a change (a hash that cries wolf teaches
+ *  everyone to ignore it). Extra fields a host adds to its template are included. */
+declare function canonicalContent(t: MailTemplate & Record<string, unknown>): string;
+/** SHA-256 hex over canonical content. Submission and sync check must call THIS — two hashers drift. */
+declare function hashContent(canonical: string): Promise<string>;
+
+export { type EffectiveTemplate, MAIL_CLASSES, MAX_BLOCKS, MAX_COPY_KEYS, MAX_FOOTER_LINES, MailBlock, MailBrand, MailCopy, type MailPrimitives, MailTemplate, MailTemplateOverride, type RenderedTemplate, canonicalContent, checkUrl, derivePreheader, escapeAttr, escapeHtml, fillPlaceholders, fillPlaceholdersRaw, hashContent, isBrandColor, isFontStack, listEffectiveTemplates, renderBlocks, renderTemplate, resolveTemplate };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+
+/** Escape text for HTML. Covers quotes too, so the same function is safe in an attribute. */
+declare function escapeHtml(s: string): string;
+/** Escape an attribute value. Same job as escapeHtml here; named so a call site says which it means. */
+declare function escapeAttr(s: string): string;
+/** A body BLOCK. The template supplies structure; the shell supplies markup.
+ *
+ *  vn-leker, reviewing their own v1: a body field that takes `<p class style>`
+ *  works while one person writes both halves — a foreign filler either loses all
+ *  formatting (plain text) or breaks the layout (HTML). */
+declare const MailBlock: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"paragraph">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"note">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"button">;
+    text: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"divider">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"html">;
+    text: z.ZodString;
+}, z.core.$strip>], "type">;
+type MailBlock = z.infer<typeof MailBlock>;
+/** A brand COLOUR — REFUSED, not escaped, when it is not one.
+ *
+ *  Proved against the built shell: an accent colour of
+ *  `#fff;"></td></tr></table><a href="https://phish.example">Log ind her</a>…`
+ *  put that anchor into the mail. An escaped non-colour still leaves the building
+ *  as a broken mail nobody sees an error for; a refusal is an error the project
+ *  reads while it still has the file open. */
+declare function isBrandColor(v: string): boolean;
+/** A font STACK may hold quotes and commas, never a tag delimiter or a quote that closes its attribute. */
+declare function isFontStack(v: string): boolean;
+/** Ceilings on what a stored override may hold — far above any real template, low
+ *  enough that a hostile body costs one issue, not one per element. */
+declare const MAX_BLOCKS = 100;
+declare const MAX_FOOTER_LINES = 20;
+declare const MAX_COPY_KEYS = 200;
+/** Brand values, ALL optional — and EMPTY is a value, not an absence (fd-sundhed
+ *  renders different, correct copy for an empty partner name). */
+declare const MailBrand: z.ZodObject<{
+    partner: z.ZodOptional<z.ZodString>;
+    senderName: z.ZodOptional<z.ZodString>;
+    senderTitle: z.ZodOptional<z.ZodString>;
+    senderEmail: z.ZodOptional<z.ZodString>;
+    logoUrl: z.ZodOptional<z.ZodString>;
+    logoWidth: z.ZodOptional<z.ZodNumber>;
+    logoCid: z.ZodOptional<z.ZodString>;
+    colorAccent: z.ZodOptional<z.ZodString>;
+    colorInk: z.ZodOptional<z.ZodString>;
+    fontSans: z.ZodOptional<z.ZodString>;
+    fontSerif: z.ZodOptional<z.ZodString>;
+    webfontHref: z.ZodOptional<z.ZodString>;
+    footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+type MailBrand = z.infer<typeof MailBrand>;
+/** Greeting, sign-off and other fixed phrases are DATA, per language (vn-leker runs da/no/sv). */
+declare const MailCopy: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>;
+type MailCopy = z.infer<typeof MailCopy>;
+/** One template, keyed on its PURPOSE (fd-sport's model: a project has a set, not one file). */
+declare const MailTemplate: z.ZodObject<{
+    purpose: z.ZodString;
+    subject: z.ZodString;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"paragraph">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"divider">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"html">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    preheader: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodObject<{
+        partner: z.ZodOptional<z.ZodString>;
+        senderName: z.ZodOptional<z.ZodString>;
+        senderTitle: z.ZodOptional<z.ZodString>;
+        senderEmail: z.ZodOptional<z.ZodString>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        logoWidth: z.ZodOptional<z.ZodNumber>;
+        logoCid: z.ZodOptional<z.ZodString>;
+        colorAccent: z.ZodOptional<z.ZodString>;
+        colorInk: z.ZodOptional<z.ZodString>;
+        fontSans: z.ZodOptional<z.ZodString>;
+        fontSerif: z.ZodOptional<z.ZodString>;
+        webfontHref: z.ZodOptional<z.ZodString>;
+        footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    copy: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>;
+type MailTemplate = z.infer<typeof MailTemplate>;
+/** What a tenant stores to change a coded default. Every field optional; `purpose` is the key, not a field. */
+declare const MailTemplateOverride: z.ZodObject<{
+    subject: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"paragraph">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        text: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"divider">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"html">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+    preheader: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodObject<{
+        partner: z.ZodOptional<z.ZodString>;
+        senderName: z.ZodOptional<z.ZodString>;
+        senderTitle: z.ZodOptional<z.ZodString>;
+        senderEmail: z.ZodOptional<z.ZodString>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        logoWidth: z.ZodOptional<z.ZodNumber>;
+        logoCid: z.ZodOptional<z.ZodString>;
+        colorAccent: z.ZodOptional<z.ZodString>;
+        colorInk: z.ZodOptional<z.ZodString>;
+        fontSans: z.ZodOptional<z.ZodString>;
+        fontSerif: z.ZodOptional<z.ZodString>;
+        webfontHref: z.ZodOptional<z.ZodString>;
+        footerLines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+    copy: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>;
+type MailTemplateOverride = z.infer<typeof MailTemplateOverride>;
+/** The class vocabulary the shell styles — SMALL AND CLOSED. fd-sundhed's dark-mode
+ *  rules target classes IN the content, so the hooks have to be agreed names. */
+declare const MAIL_CLASSES: {
+    readonly bg: "cm-bg";
+    readonly card: "cm-card";
+    readonly p: "cm-p";
+    readonly sm: "cm-sm";
+    readonly btn: "cm-btn";
+    readonly box: "cm-box";
+};
+/** The preheader, DERIVED when not given: the first paragraph or heading, cut on a
+ *  word. Omitted, the inbox shows whatever words fall first (vn-leker #6). */
+declare function derivePreheader(blocks: MailBlock[], given?: string): string;
+/** A link in a mail must be ABSOLUTE — `/da/shop/bog` has no page to resolve
+ *  against (sanne's customer). Returns the reason so a refusal can NAME the link.
+ *
+ *  `filled: true` at render time: a url that is EXACTLY one `{{token}}` is accepted
+ *  when a template is authored (it must not have to know the host's routes) and
+ *  refused once filling has happened, because a surviving token is a dead button. */
+declare function checkUrl(url: string, opts?: {
+    filled?: boolean;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The @broberg/mail-core primitives the body needs, INJECTED.
+ *
+ *  mail-core reads files at module scope (node:fs, for the logo attachment), so
+ *  importing it here would break every browser bundle that renders a preview —
+ *  cardmem measured exactly that on `vite build`. The host passes mail-core's own
+ *  functions; there is no fallback, because a fallback IS a second implementation. */
+interface MailPrimitives {
+    heading: (text: string, opts: {
+        accentColor?: string;
+        fontSerif?: string;
+    }) => string;
+    paragraph: (text: string) => string;
+    noteBox: (html: string, opts: {
+        accentColor: string;
+    }) => string;
+    cta: (href: string, label: string, opts: {
+        accentColor: string;
+    }) => string;
+}
+/** Blocks → body html, styled inline by mail-core and carrying the class hooks. */
+declare function renderBlocks(blocks: MailBlock[], opts: {
+    accentColor: string;
+    primitives: MailPrimitives;
+    fontSerif?: string;
+}): {
+    html: string;
+    notes: string[];
+};
+/** Fill `{{name}}` placeholders, escaping each value.
+ *
+ *  A MISSING value stays as the literal placeholder and is named in `missing` —
+ *  a visible `{{navn}}` is caught; a silently blank sentence is not. An EMPTY value
+ *  is honoured as empty (`in values`, not truthiness). `rawKeys` names values that
+ *  are already HTML — opt-in per call, so a caller must say which key it trusts. */
+declare function fillPlaceholders(text: string, values: Record<string, string>, rawKeys?: readonly string[]): {
+    text: string;
+    missing: string[];
+};
+/** Fill WITHOUT escaping, for a destination that escapes for itself (a subject line,
+ *  a button url). A separate function, not an `escape: false` flag someone flips on a text field. */
+declare function fillPlaceholdersRaw(text: string, values: Record<string, string>): {
+    text: string;
+    missing: string[];
+};
+interface RenderedTemplate {
+    /** The BODY html — wrap it in @broberg/mail-core's renderShell. */
+    html: string;
+    /** Plain text, filled without escaping: a mail client never renders a subject as HTML. */
+    subject: string;
+    /** Explicit or derived — never silently empty. */
+    preheader: string;
+    /** Placeholders with no value, from body, subject and button urls. */
+    missing: string[];
+    /** Findings that did not stop the render but a person should see. */
+    notes: string[];
+}
+/** The WHOLE render, in the one order that is correct: render blocks, THEN fill.
+ *
+ *  Both steps escape, so the other order escapes twice:
+ *    fill THEN render  →  "Sørensen & Søn"  →  "Sørensen &amp;amp; Søn"
+ *    render THEN fill  →  "Sørensen & Søn"  →  "Sørensen &amp; Søn"   ✓
+ *  The wrong order looks right for every customer without an `&` in their name.
+ *
+ *  ONE exception, for the same reason: a button URL is filled FIRST, unescaped, so
+ *  it goes through checkUrl (a value resolving to a relative or javascript: link
+ *  degrades to text) and then the cta primitive's own attribute escaping. */
+declare function renderTemplate(template: Pick<MailTemplate, "subject" | "blocks" | "preheader">, opts: {
+    /** Resolved by the caller (the shell needs the same value — two places deciding a brand colour disagree). */
+    accentColor: string;
+    fontSerif?: string;
+    primitives: MailPrimitives;
+    /** Value keys that are already HTML. See fillPlaceholders. */
+    rawValueKeys?: readonly string[];
+}, values?: Record<string, string>): RenderedTemplate;
+/** The EFFECTIVE template: a stored override over the coded default.
+ *
+ *  subject, blocks and preheader REPLACE; brand and copy MERGE key by key, so a
+ *  tenant that sets only its accent keeps the default's sender and footer. */
+declare function resolveTemplate(standard: MailTemplate, override?: MailTemplateOverride | null): MailTemplate;
+interface EffectiveTemplate {
+    purpose: string;
+    effective: MailTemplate;
+    /** The coded default — what "reset" goes back to. */
+    default: MailTemplate;
+    /** True when the tenant's override changes at least one field. */
+    isCustom: boolean;
+}
+/** Every coded template with its tenant's override applied — what an editor lists.
+ *
+ *  An override whose purpose has no coded default is NAMED in `unknownOverrides`,
+ *  not dropped: a template renamed in code would otherwise lose a tenant's edits
+ *  with nothing to show for it. */
+declare function listEffectiveTemplates(defaults: readonly MailTemplate[], overrides?: Readonly<Record<string, MailTemplateOverride | null | undefined>>): {
+    templates: EffectiveTemplate[];
+    unknownOverrides: string[];
+};
+/** The canonical content a version's hash is taken over: stable key ORDER, so a
+ *  moved JSON key is not reported as a change (a hash that cries wolf teaches
+ *  everyone to ignore it). Extra fields a host adds to its template are included. */
+declare function canonicalContent(t: MailTemplate & Record<string, unknown>): string;
+/** SHA-256 hex over canonical content. Submission and sync check must call THIS — two hashers drift. */
+declare function hashContent(canonical: string): Promise<string>;
+
+export { type EffectiveTemplate, MAIL_CLASSES, MAX_BLOCKS, MAX_COPY_KEYS, MAX_FOOTER_LINES, MailBlock, MailBrand, MailCopy, type MailPrimitives, MailTemplate, MailTemplateOverride, type RenderedTemplate, canonicalContent, checkUrl, derivePreheader, escapeAttr, escapeHtml, fillPlaceholders, fillPlaceholdersRaw, hashContent, isBrandColor, isFontStack, listEffectiveTemplates, renderBlocks, renderTemplate, resolveTemplate };