Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -26,12 +26,17 @@ describe("EmailTemplates", () => {
const rendered = EmailTemplates.WELCOME_EMAIL.parse({
appConfiguration,
data: { name: "Ada", action_url: actionUrl },
locale: "en",
});
expect(rendered.subject).toBe("Welcome to Acme Portal, Ada!");
expect(rendered.subject).toBe("Welcome to Acme Portal, Ada");
expect(rendered.body).toContain(actionUrl);
expect(rendered.body).toContain("Acme Portal");
expect(rendered.body).toContain('<html lang="en">');
expect(rendered.body.startsWith("<!DOCTYPE html>")).toBe(true);
expect(rendered.text).toContain("Great to have you here, Ada");
expect(rendered.text).toContain("Booked features unlock after payment is confirmed");
expect(rendered.text).toContain("Continue setup");
expect(rendered.data).toEqual({ name: "Ada", action_url: actionUrl });
});
@@ -57,7 +62,7 @@ describe("EmailTemplates", () => {
},
});
expect(rendered.subject).toBe("Grace invited you to Example Org on Acme Portal");
expect(rendered.subject).toBe("Grace invited you to Example Org in Acme Portal");
expect(rendered.body).toContain("Grace");
expect(rendered.body).toContain("Example Org");
expect(rendered.body).toContain(actionUrl);
@@ -69,9 +74,57 @@ describe("EmailTemplates", () => {
data: { name: "Ada", action_url: actionUrl },
});
expect(rendered.subject).toBe("Verify your Acme Portal email address");
expect(rendered.subject).toBe("Please confirm your email address");
expect(rendered.body).toContain(actionUrl);
expect(rendered.body).toMatch(/expires? in 30 minutes/i);
expect(rendered.text).toContain("review your plan, add-ons, and payment method");
expect(rendered.text).toContain("Features unlock only after payment is confirmed");
expect(rendered.body).toContain("This confirmation link is valid for 24 hours");
});
it("uses localized verification preview, expiry, outro and footer without English fallbacks", () => {
const translations: Record<string, string> = {
"emailVerification.subject": "Bestätige deine E-Mail-Adresse bei Acme Portal",
"emailVerification.previewText": "E-Mail-Adresse bei Acme Portal bestätigen",
"emailVerification.eyebrow": "E-Mail-Bestätigung",
"emailVerification.title_named": "Danke fürs Anmelden, Ada!",
"emailVerification.intro": "Bestätige deine E-Mail-Adresse, um die Einrichtung abzuschließen.",
"emailVerification.actionLabel": "E-Mail bestätigen",
"emailVerification.outro": "Wenn du diese Bestätigung nicht angefordert hast, kannst du diese E-Mail ignorieren.",
"emailVerification.expiresText": "Dieser Bestätigungslink ist 24 Stunden gültig und kann nur einmal verwendet werden.",
"common.signoff.closing": "Viele Grüße",
"common.signoff.team": "Dein Acme-Team",
"common.legal.privacyLabel": "Datenschutz",
"common.legal.termsLabel": "AGB",
"common.legal.imprintLabel": "Impressum",
"common.legal.unsubscribeLabel": "Abmelden",
"common.support.htmlBefore": "Bei Fragen kannst du uns gerne",
"common.support.emailLinkLabel": "eine E-Mail schreiben",
"common.support.htmlAfter": ".",
};
const rendered = EmailTemplates.VERIFICATION_EMAIL.parse({
appConfiguration,
data: { name: "Ada", action_url: actionUrl },
t: (key) => translations[key] ?? key,
locale: "de",
});
expect(rendered.body).toContain("Dieser Bestätigungslink ist 24 Stunden gültig");
expect(rendered.body).toContain("Wenn du diese Bestätigung nicht angefordert hast");
expect(rendered.body).toContain("Datenschutz");
expect(rendered.body).toContain('<html lang="de">');
expect(rendered.body).not.toContain("This confirmation link");
expect(rendered.body).not.toContain("If you did not request");
});
it.each(["pl", "ru", "uk", "hu"] as const)("sets the React email document language to %s", (locale) => {
const rendered = EmailTemplates.WELCOME_EMAIL.parse({
appConfiguration,
data: { name: "Ada", action_url: actionUrl },
t: (key) => key,
locale,
});
expect(rendered.body).toContain(`<html lang="${locale}">`);
});
it("renders account setup emails via the welcome template with plan-aware copy", () => {
@@ -81,7 +134,7 @@ describe("EmailTemplates", () => {
});
expect(rendered.subject).toBe("Finish setting up your Acme Portal account");
expect(rendered.body).toContain("Pro plan");
expect(rendered.body).toContain("Pro access");
expect(rendered.body).toContain("ada@example.com");
expect(rendered.body).toContain(actionUrl);
});
@@ -92,7 +145,7 @@ describe("EmailTemplates", () => {
data: { action_url: actionUrl },
});
expect(rendered.subject).toBe(`Welcome to ${defaultBrandTokens.productName}!`);
expect(rendered.subject).toBe(`Welcome to ${defaultBrandTokens.productName}`);
expect(rendered.body).toContain(defaultBrandTokens.productName);
});
@@ -111,7 +164,15 @@ describe("EmailTemplates", () => {
"welcome.title_named": `Hallo ${vars?.name}!`,
"welcome.intro": `Danke fuer ${vars?.productName}.`,
"welcome.actionLabel": "Einloggen",
"common.signoff.thanks": "Danke,",
"common.signoff.closing": "Viele Grüße",
"common.signoff.team": "Dein Acme-Team",
"common.legal.privacyLabel": "Datenschutz",
"common.legal.termsLabel": "AGB",
"common.legal.imprintLabel": "Impressum",
"common.legal.unsubscribeLabel": "Abmelden",
"common.support.htmlBefore": "Bei Fragen kannst du uns gerne",
"common.support.emailLinkLabel": "eine E-Mail schreiben",
"common.support.htmlAfter": ".",
};
return values[key] ?? key;
},
@@ -120,13 +181,22 @@ describe("EmailTemplates", () => {
expect(withTranslator.subject).toBe("Willkommen bei Acme Portal, Ada!");
expect(withTranslator.body).toContain("Hallo Ada!");
expect(withTranslator.body).toContain("Einloggen");
expect(withTranslator.body).toContain("Danke,");
expect(withTranslator.body).toContain("Viele Grüße");
expect(withTranslator.body).toContain("Dein Acme-Team");
expect(withTranslator.body).toContain('<html lang="de">');
expect(withTranslator.body).toContain("Datenschutz");
expect(withTranslator.body).toContain("Bei Fragen kannst du uns gerne");
expect(withTranslator.body).toContain("eine E-Mail schreiben");
expect(withTranslator.body).not.toMatch(/<br\s*\/?>-<br\s*\/?>/u);
expect(withTranslator.text).toContain("Hallo Ada!");
expect(withTranslator.text).toContain("Datenschutz");
expect(withTranslator.text).not.toContain("\n-\n");
expect(withTranslator.body).not.toEqual(baseline.body);
});
it("localizes registry descriptions when a mail translator is available", () => {
const t = (key: string) => (key === "registry.welcomeDescription" ? "Lokalisierte Willkommensbeschreibung" : key);
expect(EmailTemplates.WELCOME_EMAIL.describe(t)).toBe("Lokalisierte Willkommensbeschreibung");
expect(EmailTemplates.WELCOME_EMAIL.description).toBe("Welcome email with login link");
expect(EmailTemplates.WELCOME_EMAIL.description).toBe("Welcome email with setup link");
});
});
@@ -1,6 +1,8 @@
import { resolveTransactionalBrandTokens } from "@hivegrid/brand";
import { buildBrand, renderTransactionalEmail, type MailBrand } from "@hivegrid/mail";
import { AppConfiguration } from "~/utils/db/appConfiguration.db.server";
import { defaultLocale, normalizeLocaleCandidate } from "@hivegrid/i18n";
import { buildBrand, renderTransactionalEmail, type MailBrand, type MailFooterCopy, type MailLanguage } from "@hivegrid/mail";
import type { AppConfiguration } from "~/utils/db/appConfiguration.db.server";
import { localizedMailChrome } from "./LocalizedMailChrome";
/**
* Legacy template identifiers preserved for downstream call-sites.
@@ -28,9 +30,9 @@ export type MailTranslator = (key: string, vars?: Record<string, unknown>) => st
export type EmailTemplateParseInput<TData extends EmailTemplateData = EmailTemplateData> = {
appConfiguration: AppConfiguration;
data: TData;
/** Reserved for future i18n hooks. Currently a no-op. */
/** Mail namespace translator used for content and shared mail chrome. */
t?: MailTranslator;
/** User/request locale (informational; reserved for future i18n hooks). */
/** User/request locale normalized to the supported mail document languages. */
locale?: string;
};
@@ -41,6 +43,7 @@ type EmailTemplate<TData extends EmailTemplateData = EmailTemplateData> = {
parse: (input: EmailTemplateParseInput<TData>) => {
subject: string;
body: string;
text: string;
data: TData;
};
};
@@ -76,58 +79,155 @@ function description(key: string, fallback: string) {
};
}
function normalizeMailLanguage(locale?: string): MailLanguage {
return normalizeLocaleCandidate(locale) ?? defaultLocale;
}
function mailChrome(
t: MailTranslator | undefined,
locale?: string
): {
language: MailLanguage;
footerCopy: MailFooterCopy;
} {
if (t) return localizedMailChrome(t, locale);
const language = normalizeMailLanguage(locale);
const fallback = {
de: {
privacyLabel: "Datenschutz",
termsLabel: "AGB",
imprintLabel: "Impressum",
unsubscribeLabel: "Abmelden",
supportBefore: "Du hast Fragen? Dann",
supportLinkLabel: "schreib uns gerne",
supportAfter: ".",
signoffClosing: "Viele Grüße",
signoffTeam: "Dein HiveGrid-Team",
},
en: {
privacyLabel: "Privacy",
termsLabel: "Terms",
imprintLabel: "Imprint",
unsubscribeLabel: "Unsubscribe",
supportBefore: "Questions? Feel free to",
supportLinkLabel: "email us",
supportAfter: ".",
signoffClosing: "Kind regards,",
signoffTeam: "Your HiveGrid team",
},
pl: {
privacyLabel: "Polityka prywatności",
termsLabel: "Regulamin",
imprintLabel: "Nota prawna",
unsubscribeLabel: "Zrezygnuj z subskrypcji",
supportBefore: "Masz pytania?",
supportLinkLabel: "Napisz do nas",
supportAfter: ".",
signoffClosing: "Pozdrawiamy,",
signoffTeam: "Zespół HiveGrid",
},
ru: {
privacyLabel: "Конфиденциальность",
termsLabel: "Условия",
imprintLabel: "Правовая информация",
unsubscribeLabel: "Отписаться",
supportBefore: "Есть вопросы?",
supportLinkLabel: "Напишите нам",
supportAfter: ".",
signoffClosing: "С наилучшими пожеланиями,",
signoffTeam: "Команда HiveGrid",
},
uk: {
privacyLabel: "Конфіденційність",
termsLabel: "Умови",
imprintLabel: "Правова інформація",
unsubscribeLabel: "Відписатися",
supportBefore: "Є запитання?",
supportLinkLabel: "Напишіть нам",
supportAfter: ".",
signoffClosing: "З найкращими побажаннями,",
signoffTeam: "Команда HiveGrid",
},
hu: {
privacyLabel: "Adatvédelem",
termsLabel: "ÁSZF",
imprintLabel: "Impresszum",
unsubscribeLabel: "Leiratkozás",
supportBefore: "Kérdésed van?",
supportLinkLabel: "Írj nekünk",
supportAfter: ".",
signoffClosing: "Üdvözlettel,",
signoffTeam: "A HiveGrid csapata",
},
}[language];
return {
language,
footerCopy: {
privacyLabel: mailText(t, "common.legal.privacyLabel", fallback.privacyLabel),
termsLabel: mailText(t, "common.legal.termsLabel", fallback.termsLabel),
imprintLabel: mailText(t, "common.legal.imprintLabel", fallback.imprintLabel),
unsubscribeLabel: mailText(t, "common.legal.unsubscribeLabel", fallback.unsubscribeLabel),
supportBefore: mailText(t, "common.support.htmlBefore", fallback.supportBefore),
supportLinkLabel: mailText(t, "common.support.emailLinkLabel", fallback.supportLinkLabel),
supportAfter: mailText(t, "common.support.htmlAfter", fallback.supportAfter),
signoffClosing: mailText(t, "common.signoff.closing", fallback.signoffClosing),
signoffTeam: mailText(t, "common.signoff.team", fallback.signoffTeam),
},
};
}
const WELCOME_EMAIL: EmailTemplate<{ name?: string; action_url: string }> = {
name: "welcome",
...description("registry.welcomeDescription", "Welcome email with login link"),
parse: ({ appConfiguration, data, t }) => {
...description("registry.welcomeDescription", "Welcome email with setup link"),
parse: ({ appConfiguration, data, t, locale }) => {
const brand = brandFor(appConfiguration);
const subject = data.name
? mailText(t, "welcome.subject_named", "Welcome to {{productName}}, {{name}}!", { productName: brand.productName, name: data.name })
: mailText(t, "welcome.subject", "Welcome to {{productName}}!", { productName: brand.productName });
const { html } = renderTransactionalEmail("welcome", {
? mailText(t, "welcome.subject_named", "Welcome to {{productName}}, {{name}}", { productName: brand.productName, name: data.name })
: mailText(t, "welcome.subject", "Welcome to {{productName}}", { productName: brand.productName });
const { html, text } = renderTransactionalEmail("welcome", {
brand,
...mailChrome(t, locale),
recipientName: data.name,
actionUrl: data.action_url,
subject,
eyebrow: mailText(t, "welcome.eyebrow", "Welcome"),
title: data.name
? mailText(t, "welcome.title_named", "Welcome, {{name}}!", { name: data.name })
: mailText(t, "welcome.title", "Welcome!"),
intro: mailText(t, "welcome.intro", "Thanks for trying {{productName}}.", { productName: brand.productName }),
actionLabel: mailText(t, "welcome.actionLabel", "Click here to log in"),
signoffThanks: mailText(t, "common.signoff.thanks", "Thanks,"),
? mailText(t, "welcome.title_named", "Great to have you here, {{name}}", { name: data.name })
: mailText(t, "welcome.title", "Great to have you here"),
intro: mailText(t, "welcome.intro", "Your {{productName}} account has been created. Sign in to review your plan and finish setup. Booked features unlock after payment is confirmed.", {
productName: brand.productName,
}),
actionLabel: mailText(t, "welcome.actionLabel", "Continue setup"),
});
return { subject, body: html, data };
return { subject, body: html, text, data };
},
};
const PASSWORD_RESET_EMAIL: EmailTemplate<{ name?: string; action_url: string }> = {
name: "password-reset",
...description("registry.passwordResetDescription", "Email sent to users who requested a password reset"),
parse: ({ appConfiguration, data, t }) => {
parse: ({ appConfiguration, data, t, locale }) => {
const brand = brandFor(appConfiguration);
const subject = mailText(t, "passwordReset.subject", "Reset your {{productName}} password", { productName: brand.productName });
const { html } = renderTransactionalEmail("password-reset", {
const { html, text } = renderTransactionalEmail("password-reset", {
brand,
...mailChrome(t, locale),
recipientName: data.name,
actionUrl: data.action_url,
subject,
eyebrow: mailText(t, "passwordReset.eyebrow", "Password reset"),
title: data.name
? mailText(t, "passwordReset.title_named", "Hello, {{name}}!", { name: data.name })
: mailText(t, "passwordReset.title", "Hello!"),
intro: mailText(t, "passwordReset.intro", "You recently requested to reset your password for your {{productName}} account.", {
? mailText(t, "passwordReset.title_named", "Choose a new password, {{name}}", { name: data.name })
: mailText(t, "passwordReset.title", "Choose a new password"),
intro: mailText(t, "passwordReset.intro", "We received a request to reset the password for your {{productName}} account.", {
productName: brand.productName,
}),
actionLabel: mailText(t, "passwordReset.actionLabel", "Reset password"),
outro: mailText(
t,
"passwordReset.outro",
"If you did not request a password reset, please ignore this email or contact support if you have questions."
),
signoffThanks: mailText(t, "common.signoff.thanks", "Thanks,"),
actionLabel: mailText(t, "passwordReset.actionLabel", "Choose a new password"),
outro: mailText(t, "passwordReset.outro", "If you did not make this request, you can ignore this email. Your current password will remain unchanged."),
});
return { subject, body: html, data };
return { subject, body: html, text, data };
},
};
@@ -139,7 +239,7 @@ const USER_INVITATION_EMAIL: EmailTemplate<{
}> = {
name: "user-invitation",
...description("registry.userInvitationDescription", "Email sent to users who are invited to join an organization"),
parse: ({ appConfiguration, data, t }) => {
parse: ({ appConfiguration, data, t, locale }) => {
const brand = brandFor(appConfiguration);
const vars = {
productName: brand.productName,
@@ -147,87 +247,81 @@ const USER_INVITATION_EMAIL: EmailTemplate<{
senderOrganization: data.invite_sender_organization,
name: data.name,
};
const subject = mailText(t, "userInvitation.subject", "{{senderName}} invited you to {{senderOrganization}} on {{productName}}", vars);
const { html } = renderTransactionalEmail("invitation", {
const subject = mailText(t, "userInvitation.subject", "{{senderName}} invited you to {{senderOrganization}} in {{productName}}", vars);
const { html, text } = renderTransactionalEmail("invitation", {
brand,
...mailChrome(t, locale),
recipientName: data.name,
senderName: data.invite_sender_name,
senderOrganization: data.invite_sender_organization,
actionUrl: data.action_url,
subject,
eyebrow: mailText(t, "userInvitation.eyebrow", "Invitation"),
title: data.name ? mailText(t, "userInvitation.title_named", "Hello, {{name}}!", vars) : mailText(t, "userInvitation.title", "Hello!"),
intro: mailText(
t,
"userInvitation.intro",
"{{senderName}} with {{senderOrganization}} has invited you to use {{productName}} to collaborate with them.",
vars
),
title: data.name
? mailText(t, "userInvitation.title_named", "{{name}}, you have been invited", vars)
: mailText(t, "userInvitation.title", "An invitation to collaborate"),
intro: mailText(t, "userInvitation.intro", "{{senderName}} invited you to collaborate with {{senderOrganization}} in {{productName}}.", vars),
actionLabel: mailText(t, "userInvitation.actionLabel", "Join {{senderOrganization}}", vars),
signoffThanks: mailText(t, "common.signoff.thanks", "Thanks,"),
});
return { subject, body: html, data };
return { subject, body: html, text, data };
},
};
const VERIFICATION_EMAIL: EmailTemplate<{ name?: string; action_url: string }> = {
name: "email-verification",
...description("registry.emailVerificationDescription", "Email sent to users to verify their email address"),
parse: ({ appConfiguration, data, t }) => {
parse: ({ appConfiguration, data, t, locale }) => {
const brand = brandFor(appConfiguration);
const vars = { productName: brand.productName, name: data.name };
const subject = mailText(t, "emailVerification.subject", "Verify your {{productName}} email address", vars);
const { html } = renderTransactionalEmail("magic-link", {
const subject = mailText(t, "emailVerification.subject", "Please confirm your email address", vars);
const { html, text } = renderTransactionalEmail("magic-link", {
brand,
...mailChrome(t, locale),
recipientName: data.name,
actionUrl: data.action_url,
subject,
previewText: mailText(t, "emailVerification.previewText", "Verify your email address with {{productName}}", vars),
eyebrow: mailText(t, "emailVerification.eyebrow", "Email verification"),
title: data.name
? mailText(t, "emailVerification.title_named", "Thanks for signing up, {{name}}!", vars)
: mailText(t, "emailVerification.title", "Thanks for signing up!"),
intro: mailText(t, "emailVerification.intro", "Confirm your email address to finish setting up your {{productName}} account.", vars),
actionLabel: mailText(t, "emailVerification.actionLabel", "Click here to verify your email"),
expiresInMinutes: 30,
signoffThanks: mailText(t, "common.signoff.thanks", "Thanks,"),
title: data.name ? mailText(t, "emailVerification.title_named", "Almost there, {{name}}", vars) : mailText(t, "emailVerification.title", "Almost there"),
intro: mailText(
t,
"emailVerification.intro",
"Confirm your email address. Then set your password and review your plan, add-ons, and payment method. Features unlock only after payment is confirmed.",
vars
),
actionLabel: mailText(t, "emailVerification.actionLabel", "Confirm email address"),
outro: mailText(t, "emailVerification.outro", "If you did not request this confirmation, you can safely ignore this email."),
expiresText: mailText(t, "emailVerification.expiresText", "This confirmation link is valid for {{expiresInHours}} hours and can only be used once.", {
expiresInHours: 24,
}),
expiresInMinutes: 24 * 60,
});
return { subject, body: html, data };
return { subject, body: html, text, data };
},
};
const ACCOUNT_SETUP_EMAIL: EmailTemplate<{ email: string; plan: string; action_url: string }> = {
name: "account-setup",
...description("registry.accountSetupDescription", "Email sent to users to set up their account"),
parse: ({ appConfiguration, data, t }) => {
parse: ({ appConfiguration, data, t, locale }) => {
const brand = brandFor(appConfiguration);
const vars = { productName: brand.productName, plan: data.plan, email: data.email };
const subject = mailText(t, "accountSetup.subject", "Finish setting up your {{productName}} account", vars);
const { html } = renderTransactionalEmail("welcome", {
const { html, text } = renderTransactionalEmail("welcome", {
brand,
...mailChrome(t, locale),
actionUrl: data.action_url,
subject,
eyebrow: mailText(t, "accountSetup.eyebrow", "Account setup"),
title: mailText(t, "accountSetup.title", "Almost there - let's get you started", vars),
intro: mailText(
t,
"accountSetup.intro",
"Thanks for subscribing to the {{plan}} plan. Use the button below to finish setting up your account for {{email}}.",
vars
),
actionLabel: mailText(t, "accountSetup.actionLabel", "Set up account"),
signoffThanks: mailText(t, "common.signoff.thanks", "Thanks,"),
title: mailText(t, "accountSetup.title", "Your account is waiting for you", vars),
intro: mailText(t, "accountSetup.intro", "Your {{plan}} access for {{email}} is ready. Choose your password and start using {{productName}}.", vars),
actionLabel: mailText(t, "accountSetup.actionLabel", "Finish account setup"),
});
return { subject, body: html, data };
return { subject, body: html, text, data };
},
};
const allTemplates = [
WELCOME_EMAIL,
PASSWORD_RESET_EMAIL,
USER_INVITATION_EMAIL,
VERIFICATION_EMAIL,
ACCOUNT_SETUP_EMAIL,
];
const allTemplates = [WELCOME_EMAIL, PASSWORD_RESET_EMAIL, USER_INVITATION_EMAIL, VERIFICATION_EMAIL, ACCOUNT_SETUP_EMAIL];
export default {
allTemplates,
@@ -0,0 +1,35 @@
import type { MailFooterCopy, MailLanguage } from "@hivegrid/mail";
import { defaultLocale, normalizeLocaleCandidate } from "@hivegrid/i18n";
import type { MailTranslator } from "~/locale/mail-translator.server";
export type LocalizedMailChrome = {
readonly language: MailLanguage;
readonly footerCopy: MailFooterCopy;
};
function normalizeMailLanguage(locale?: string): MailLanguage {
return normalizeLocaleCandidate(locale) ?? defaultLocale;
}
/**
* Resolves the shared, user-visible mail footer from the same locale as the
* message body. Direct React-email call sites must pass this chrome explicitly
* so they cannot silently fall back to the package's English preview defaults.
*/
export function localizedMailChrome(t: MailTranslator, locale?: string): LocalizedMailChrome {
return {
language: normalizeMailLanguage(locale),
footerCopy: {
privacyLabel: t("common.legal.privacyLabel"),
termsLabel: t("common.legal.termsLabel"),
imprintLabel: t("common.legal.imprintLabel"),
unsubscribeLabel: t("common.legal.unsubscribeLabel"),
supportBefore: t("common.support.htmlBefore"),
supportLinkLabel: t("common.support.emailLinkLabel"),
supportAfter: t("common.support.htmlAfter"),
signoffClosing: t("common.signoff.closing"),
signoffTeam: t("common.signoff.team"),
},
};
}