@learncard/email-templates 1.2.1 → 1.3.0

package/src/__tests__/render.test.ts

@@ -28,6 +28,13 @@ const VETPASS_BRANDING: Partial<TenantBranding> = {
  * produce output without throwing.
  */
 const TEMPLATE_FIXTURES: { [K in TemplateId]: TemplateDataMap[K] } = {
+    announcement: {
+        title: 'New learning opportunities',
+        body: 'Explore the latest programs.',
+        ctaLabel: 'Explore',
+        ctaUrl: 'https://learncard.app/m/programs?utm_source=email',
+        unsubscribeUrl: 'https://learncard.app/unsubscribe?token=example',
+    },
     'embed-email-verification': {
         verificationCode: '123456',
         verificationEmail: 'test@example.com',
@@ -166,6 +173,13 @@ const TEMPLATE_FIXTURES: { [K in TemplateId]: TemplateDataMap[K] } = {
         releaseAfter: 'October 2, 2026, 3:00 PM',
         cancelUrl: 'https://learncard.app/recovery/cancel?token=abc123',
     },
+    'escrow-pin-sign-in': {
+        signedInAt: 'October 2, 2026, 3:00 PM',
+        secureUrl: 'https://learncard.app/account/secure',
+    },
+    'account-secured': {
+        securedAt: 'October 2, 2026, 3:00 PM',
+    },
 };
 
 const ALL_TEMPLATE_IDS = Object.keys(TEMPLATE_FIXTURES) as TemplateId[];
@@ -552,6 +566,114 @@ describe('renderEmail — escrow hold lifecycle', () => {
         expect(html).not.toContain('undefined');
     });
 
+    it('escrow-pin-sign-in includes the sign-in date and the secure-account link', async () => {
+        const data = TEMPLATE_FIXTURES['escrow-pin-sign-in'];
+        const { html, text, subject } = await renderEmail(
+            'escrow-pin-sign-in',
+            DEFAULT_BRANDING,
+            data
+        );
+
+        expect(html).toContain(data.signedInAt);
+        expect(html).toContain(data.secureUrl);
+        expect(text).toContain('Not you? Secure your account.');
+        expect(text).toContain('Secure my account');
+        expect(subject).toBe('New device signed in with your PIN');
+        assertNoJargon(html);
+        assertNoJargon(text);
+        assertNoJargon(subject);
+    });
+
+    it('escrow-pin-sign-in formats the ISO timestamp lca-api sends, per locale', async () => {
+        const iso = '2026-11-02T15:04:05.123Z';
+        const en = await renderEmail('escrow-pin-sign-in', DEFAULT_BRANDING, {
+            signedInAt: iso,
+            secureUrl: 'https://learncard.app/account/secure',
+        });
+        const fr = await renderEmail(
+            'escrow-pin-sign-in',
+            DEFAULT_BRANDING,
+            { signedInAt: iso, secureUrl: 'https://learncard.app/account/secure' },
+            'fr'
+        );
+
+        expect(en.text).not.toContain(iso);
+        expect(en.text).toContain('November 2, 2026');
+        expect(en.text).toContain('UTC');
+        expect(fr.text).toContain('2 novembre 2026');
+    });
+
+    it('escrow-pin-sign-in carries tenant branding', async () => {
+        const { html } = await renderEmail('escrow-pin-sign-in', VETPASS_BRANDING, {
+            signedInAt: 'October 2, 2026, 3:00 PM',
+            secureUrl: 'https://vetpass.app/account/secure',
+        });
+
+        expect(html).toContain('VetPass');
+        expect(html).toContain('https://vetpass.app/account/secure');
+    });
+
+    it('account-secured works for an owner who did not do it (no secure link, support first)', async () => {
+        const data = TEMPLATE_FIXTURES['account-secured'];
+        const { html, text, subject } = await renderEmail(
+            'account-secured',
+            DEFAULT_BRANDING,
+            data
+        );
+
+        expect(html).toContain(data.securedAt);
+        expect(subject).toBe('Other devices were signed out of your account');
+        // The owner's login may be gone, so the notice must not depend on the in-app action.
+        expect(html).not.toContain('/account/secure');
+        expect(text).toContain('your own sign-in may have been removed');
+        // The revoke reset every recovery method and removed automatic recovery, so the
+        // lost-login path is not offered as the way back; support is.
+        expect(text).toContain('reset its recovery methods');
+        expect(text).not.toContain('I lost access to my school email or login');
+        expect(text).toContain(`Contact ${DEFAULT_BRANDING.supportEmail} right away`);
+        expect(html).toContain(`href="${DEFAULT_BRANDING.appUrl}"`);
+        assertNoJargon(html);
+        assertNoJargon(text);
+        assertNoJargon(subject);
+    });
+
+    it('account-secured formats the ISO timestamp lca-api sends, per locale', async () => {
+        const iso = '2026-11-02T15:04:05.123Z';
+        const en = await renderEmail('account-secured', DEFAULT_BRANDING, { securedAt: iso });
+        const es = await renderEmail('account-secured', DEFAULT_BRANDING, { securedAt: iso }, 'es');
+
+        expect(en.text).not.toContain(iso);
+        expect(en.text).toContain('November 2, 2026');
+        expect(en.text).toContain('UTC');
+        expect(es.text).toContain('2 de noviembre de 2026');
+        expect(es.subject).not.toBe(en.subject);
+    });
+
+    it('account-secured carries tenant branding and the tenant support address', async () => {
+        const { html, text } = await renderEmail('account-secured', VETPASS_BRANDING, {
+            securedAt: 'October 2, 2026, 3:00 PM',
+        });
+
+        expect(html).toContain('VetPass');
+        expect(text).toContain(`Contact ${VETPASS_BRANDING.supportEmail} right away`);
+        expect(html).toContain(`href="${VETPASS_BRANDING.appUrl}"`);
+        expect(text).not.toContain(DEFAULT_BRANDING.supportEmail);
+    });
+
+    it('account-secured points to the organization when the tenant has no support address', async () => {
+        const { text } = await renderEmail(
+            'account-secured',
+            { ...DEFAULT_BRANDING, supportEmail: '' },
+            TEMPLATE_FIXTURES['account-secured']
+        );
+
+        expect(text).not.toContain('Contact  right away');
+        expect(text).toContain(
+            `Contact the organization that gave you access to ${DEFAULT_BRANDING.brandName} right away`
+        );
+        expect(text).not.toContain('I lost access to my school email or login');
+    });
+
     it('all escrow hold templates include the "This wasn\'t me" cancel CTA when a cancel URL is present', async () => {
         const started = await renderEmail(
             'escrow-hold-started',
@@ -746,3 +868,35 @@ describe('renderEmail — edge cases', () => {
         expect(html).toContain('no-recipient-token');
     });
 });
+
+describe('announcement', () => {
+    it('omits the button and fallback in HTML and text when no campaign destination exists', async () => {
+        const { ctaUrl, ...content } = TEMPLATE_FIXTURES.announcement;
+        const data = { ...content, ctaLabel: 'Unique campaign action' };
+        const { html, text } = await renderEmail('announcement', VETPASS_BRANDING, data);
+        for (const output of [html, text]) {
+            expect(output).not.toContain(ctaUrl);
+            expect(output).not.toContain(data.ctaLabel);
+            expect(output).not.toContain('/m/');
+            expect(output).toContain(data.body);
+            expect(output).toContain(data.unsubscribeUrl);
+        }
+    });
+
+    it('renders escaped authored copy, CTA and unsubscribe in HTML and text', async () => {
+        const data = {
+            ...TEMPLATE_FIXTURES.announcement,
+            body: '<script>alert(1)</script>\nSecond line',
+        };
+        const { html, text, subject } = await renderEmail('announcement', VETPASS_BRANDING, data);
+        expect(subject).toBe(data.title);
+        expect(html).toContain('VetPass');
+        expect(html).not.toContain('<script>alert');
+        expect(html).toContain('&lt;script&gt;');
+        for (const output of [html, text]) {
+            expect(output).toContain(data.ctaUrl);
+            expect(output).toContain(data.unsubscribeUrl);
+            expect(output).toContain('Second line');
+        }
+    });
+});

package/src/__tests__/tenant-registry.test.ts

@@ -70,8 +70,8 @@ describe('resolveTenantFromRequest', () => {
             expect(result.resolvedVia).toBe('origin');
         });
 
-        it('resolves vetpass from alpha.vetpass.app', () => {
-            const headers: RequestHeaders = { origin: 'https://alpha.vetpass.app' };
+        it('resolves an unlisted vetpass subdomain via its parent domain', () => {
+            const headers: RequestHeaders = { origin: 'https://preview.vetpass.app' };
             const result = resolveTenantFromRequest(headers);
 
             expect(result.id).toBe('vetpass');

package/src/components/Layout.tsx

@@ -24,6 +24,7 @@ import { SHARED, htmlLang, htmlDir, interpolate, resolveCatalogLocale } from '..
 interface LayoutProps {
     branding: TenantBranding;
     preview: string;
+    disclaimer?: string;
     children: React.ReactNode;
     /** Show the brand icon at the top of the card. Defaults to true.
      *  Set to false when the template already has an IssuerLogo. */
@@ -35,12 +36,14 @@ interface LayoutProps {
 export const Layout: React.FC<LayoutProps> = ({
     branding,
     preview,
+    disclaimer,
     children,
     showHeaderLogo = true,
     locale,
 }) => {
     const chrome = SHARED[resolveCatalogLocale(locale)];
-    const disclaimerText = interpolate(chrome.footerDisclaimer, { brandName: branding.brandName });
+    const disclaimerText =
+        disclaimer ?? interpolate(chrome.footerDisclaimer, { brandName: branding.brandName });
 
     return (
         <Html lang={htmlLang(locale)} dir={htmlDir(locale)}>

package/src/i18n.ts

@@ -108,3 +108,36 @@ export const interpolate = (template: string, params: Record<string, string | un
         const value = params[key];
         return value === undefined ? match : value;
     });
+
+/**
+ * `{ locale }` when set, `{}` otherwise — spread into props whose `locale` is optional
+ * so an absent locale is omitted rather than passed as `undefined`
+ * (safe under `exactOptionalPropertyTypes`).
+ */
+export const localeProp = (locale: string | null | undefined): { locale?: string } =>
+    locale === undefined || locale === null ? {} : { locale };
+
+/**
+ * lca-api passes ISO timestamps for security notices; show them as a readable date in
+ * the recipient's language. The recipient's time zone is unknown, so the time is shown
+ * in UTC and labelled as such. Anything that is not an ISO timestamp (previews,
+ * pre-formatted text) is shown as is.
+ */
+export const formatNoticeTimestamp = (value: string, locale: NotificationLocale): string => {
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) return value;
+
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return value;
+
+    try {
+        return new Intl.DateTimeFormat(locale, {
+            dateStyle: 'long',
+            timeStyle: 'short',
+            timeZone: 'UTC',
+        })
+            .format(date)
+            .concat(' UTC');
+    } catch {
+        return value;
+    }
+};

package/src/index.ts

@@ -44,6 +44,8 @@ export type {
     EscrowHoldReleasedData,
     EscrowHoldCancelledData,
     EscrowPinLockedData,
+    EscrowPinSignInData,
+    AccountSecuredData,
 } from './render';
 export type { EscrowHoldCancelledReason } from './templates/escrow-hold-cancelled';
 
@@ -69,3 +71,5 @@ export type { ResolvedTenant, RequestHeaders } from './tenant-registry';
 // configure `jsx` in their tsconfig. Use renderEmail() / renderSms() instead.
 // For direct component access (testing / preview), import from
 // '@learncard/email-templates/src/templates' explicitly.
+
+export type { AnnouncementData } from './render';

package/src/previews/account-secured-scenarios.tsx

@@ -0,0 +1,41 @@
+/**
+ * account-secured — all preview scenarios stacked.
+ */
+
+import * as React from 'react';
+
+import { AccountSecured } from '../templates/account-secured';
+import { LEARNCARD_BRANDING, VETPASS_BRANDING, ScenarioDivider } from './_fixtures';
+
+export default function AccountSecuredScenarios() {
+    return (
+        <>
+            <ScenarioDivider label="Default (LearnCard)" />
+            <AccountSecured branding={LEARNCARD_BRANDING} securedAt="October 2, 2026, 3:00 PM" />
+
+            <ScenarioDivider label="Spanish" />
+            <AccountSecured
+                branding={LEARNCARD_BRANDING}
+                securedAt="2 de octubre de 2026, 3:00 p.m."
+                locale="es"
+            />
+
+            <ScenarioDivider label="French" />
+            <AccountSecured
+                branding={LEARNCARD_BRANDING}
+                securedAt="2 octobre 2026, 15h00"
+                locale="fr"
+            />
+
+            <ScenarioDivider label="Arabic (RTL)" />
+            <AccountSecured
+                branding={LEARNCARD_BRANDING}
+                securedAt="2 أكتوبر 2026، 3:00 م"
+                locale="ar"
+            />
+
+            <ScenarioDivider label="VetPass tenant branding" />
+            <AccountSecured branding={VETPASS_BRANDING} securedAt="October 2, 2026, 3:00 PM" />
+        </>
+    );
+}

package/src/previews/escrow-pin-sign-in-scenarios.tsx

@@ -0,0 +1,52 @@
+/**
+ * escrow-pin-sign-in — all preview scenarios stacked.
+ */
+
+import * as React from 'react';
+
+import { EscrowPinSignIn } from '../templates/escrow-pin-sign-in';
+import { LEARNCARD_BRANDING, VETPASS_BRANDING, ScenarioDivider } from './_fixtures';
+
+export default function EscrowPinSignInScenarios() {
+    return (
+        <>
+            <ScenarioDivider label="Default (LearnCard)" />
+            <EscrowPinSignIn
+                branding={LEARNCARD_BRANDING}
+                signedInAt="October 2, 2026, 3:00 PM"
+                secureUrl="https://learncard.app/account/secure"
+            />
+
+            <ScenarioDivider label="Spanish" />
+            <EscrowPinSignIn
+                branding={LEARNCARD_BRANDING}
+                signedInAt="2 de octubre de 2026, 3:00 p.m."
+                secureUrl="https://learncard.app/account/secure"
+                locale="es"
+            />
+
+            <ScenarioDivider label="French" />
+            <EscrowPinSignIn
+                branding={LEARNCARD_BRANDING}
+                signedInAt="2 octobre 2026, 15h00"
+                secureUrl="https://learncard.app/account/secure"
+                locale="fr"
+            />
+
+            <ScenarioDivider label="Arabic (RTL)" />
+            <EscrowPinSignIn
+                branding={LEARNCARD_BRANDING}
+                signedInAt="2 أكتوبر 2026، 3:00 م"
+                secureUrl="https://learncard.app/account/secure"
+                locale="ar"
+            />
+
+            <ScenarioDivider label="VetPass tenant branding" />
+            <EscrowPinSignIn
+                branding={VETPASS_BRANDING}
+                signedInAt="October 2, 2026, 3:00 PM"
+                secureUrl="https://vetpass.app/account/secure"
+            />
+        </>
+    );
+}

package/src/render.ts

@@ -1,3 +1,4 @@
+import { Announcement, getAnnouncementSubject } from './templates/announcement';
 /**
  * render.ts — the main rendering entry point.
  *
@@ -53,6 +54,10 @@ import {
     getEscrowHoldCancelledSubject,
     EscrowPinLocked,
     getEscrowPinLockedSubject,
+    EscrowPinSignIn,
+    getEscrowPinSignInSubject,
+    AccountSecured,
+    getAccountSecuredSubject,
 } from './templates';
 
 import type {
@@ -75,7 +80,10 @@ import type {
     EscrowHoldCancelledProps,
     EscrowHoldCancelledReason,
     EscrowPinLockedProps,
+    EscrowPinSignInProps,
+    AccountSecuredProps,
 } from './templates';
+import { localeProp } from './i18n';
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -94,7 +102,17 @@ export interface RenderedEmail {
  * This provides full type safety: `renderEmail('inbox-claim', branding, data)` will
  * require `data` to match `InboxClaimData`.
  */
+export interface AnnouncementData {
+    title: string;
+    body: string;
+    heroImageUrl?: string;
+    ctaLabel: string;
+    ctaUrl?: string;
+    unsubscribeUrl: string;
+}
+
 export interface TemplateDataMap {
+    announcement: AnnouncementData;
     // -- Verification code variants ------------------------------------------
 
     /** brain-service: contact-methods.ts, embed flow */
@@ -190,6 +208,12 @@ export interface TemplateDataMap {
 
     /** lca-api: recovery PIN locked after too many failed attempts */
     'escrow-pin-locked': EscrowPinLockedData;
+
+    /** lca-api: a new device signed in with the recovery PIN — links to "Secure my account" */
+    'escrow-pin-sign-in': EscrowPinSignInData;
+
+    /** lca-api: "Secure my account" signed out every other device and login */
+    'account-secured': AccountSecuredData;
 }
 
 export type TemplateId = keyof TemplateDataMap;
@@ -304,6 +328,15 @@ export interface EscrowPinLockedData {
     cancelUrl?: string;
 }
 
+export interface EscrowPinSignInData {
+    signedInAt: string;
+    secureUrl: string;
+}
+
+export interface AccountSecuredData {
+    securedAt: string;
+}
+
 // ---------------------------------------------------------------------------
 // renderEmail()
 // ---------------------------------------------------------------------------
@@ -501,6 +534,17 @@ function buildElement(
             };
         }
 
+        case 'announcement': {
+            const d = data as AnnouncementData;
+            return {
+                element: React.createElement(Announcement, {
+                    branding,
+                    ...d,
+                    ...(locale === undefined ? {} : { locale }),
+                }),
+                subject: getAnnouncementSubject(d),
+            };
+        }
         case 'credential-updated': {
             const d = data as CredentialUpdatedData;
             const props: CredentialUpdatedProps = { branding, ...d, locale };
@@ -570,6 +614,35 @@ function buildElement(
             };
         }
 
+        case 'escrow-pin-sign-in': {
+            const d = data as EscrowPinSignInData;
+            const props: EscrowPinSignInProps = {
+                branding,
+                signedInAt: d.signedInAt,
+                secureUrl: d.secureUrl,
+                ...localeProp(locale),
+            };
+
+            return {
+                element: React.createElement(EscrowPinSignIn, props),
+                subject: getEscrowPinSignInSubject(branding, locale),
+            };
+        }
+
+        case 'account-secured': {
+            const d = data as AccountSecuredData;
+            const props: AccountSecuredProps = {
+                branding,
+                securedAt: d.securedAt,
+                ...localeProp(locale),
+            };
+
+            return {
+                element: React.createElement(AccountSecured, props),
+                subject: getAccountSecuredSubject(branding, locale),
+            };
+        }
+
         default: {
             const _exhaustive: never = templateId;
             throw new Error(`Unknown template: ${_exhaustive}`);