@learncard/email-templates 1.0.2 → 1.0.3

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

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+    resolveTenantFromRequest,
+    registerOriginMapping,
+    registerTenantBranding,
+} from '../tenant-registry';
+import type { RequestHeaders } from '../tenant-registry';
+
+// ---------------------------------------------------------------------------
+// resolveTenantFromRequest
+// ---------------------------------------------------------------------------
+
+describe('resolveTenantFromRequest', () => {
+    // -- Priority 1: X-Tenant-Id header --------------------------------------
+
+    describe('X-Tenant-Id header', () => {
+        it('resolves tenant from explicit header', () => {
+            const headers: RequestHeaders = { 'x-tenant-id': 'vetpass' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('header');
+        });
+
+        it('takes priority over Origin header', () => {
+            const headers: RequestHeaders = {
+                'x-tenant-id': 'vetpass',
+                origin: 'https://learncard.app',
+            };
+
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('header');
+        });
+
+        it('takes priority over env default', () => {
+            const headers: RequestHeaders = { 'x-tenant-id': 'vetpass' };
+            const result = resolveTenantFromRequest(headers, 'learncard');
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('header');
+        });
+
+        it('handles array header values (takes first)', () => {
+            const headers: RequestHeaders = { 'x-tenant-id': ['vetpass', 'learncard'] };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+        });
+    });
+
+    // -- Priority 2: Origin / Referer header ---------------------------------
+
+    describe('Origin header', () => {
+        it('resolves learncard from learncard.app origin', () => {
+            const headers: RequestHeaders = { origin: 'https://learncard.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves vetpass from vetpass.app origin', () => {
+            const headers: RequestHeaders = { origin: 'https://vetpass.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves vetpass from alpha.vetpass.app', () => {
+            const headers: RequestHeaders = { origin: 'https://alpha.vetpass.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves vetpass from staging.vetpass.app', () => {
+            const headers: RequestHeaders = { origin: 'https://staging.vetpass.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves learncard from staging.learncard.app', () => {
+            const headers: RequestHeaders = { origin: 'https://staging.learncard.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves learncard from app.learncard.com', () => {
+            const headers: RequestHeaders = { origin: 'https://app.learncard.com' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('resolves learncard from localhost', () => {
+            const headers: RequestHeaders = { origin: 'http://localhost:3000' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('origin');
+        });
+
+        it('strips subdomains progressively (deep subdomain)', () => {
+            const headers: RequestHeaders = { origin: 'https://deep.nested.vetpass.app' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('origin');
+        });
+    });
+
+    describe('Referer fallback', () => {
+        it('uses referer when origin is missing', () => {
+            const headers: RequestHeaders = { referer: 'https://vetpass.app/some/page' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('origin');
+        });
+    });
+
+    // -- Priority 3: env default ---------------------------------------------
+
+    describe('env default', () => {
+        it('uses envTenantId when no headers match', () => {
+            const headers: RequestHeaders = {};
+            const result = resolveTenantFromRequest(headers, 'vetpass');
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('env');
+        });
+
+        it('ignores unknown origin and falls through to env', () => {
+            const headers: RequestHeaders = { origin: 'https://unknown-site.com' };
+            const result = resolveTenantFromRequest(headers, 'vetpass');
+
+            expect(result.id).toBe('vetpass');
+            expect(result.resolvedVia).toBe('env');
+        });
+    });
+
+    // -- Priority 4: safe default --------------------------------------------
+
+    describe('safe default', () => {
+        it('returns learncard when nothing matches', () => {
+            const headers: RequestHeaders = {};
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('default');
+        });
+
+        it('returns learncard for unknown origin with no env fallback', () => {
+            const headers: RequestHeaders = { origin: 'https://random-site.io' };
+            const result = resolveTenantFromRequest(headers);
+
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('default');
+        });
+    });
+
+    // -- Branding resolved correctly -----------------------------------------
+
+    describe('emailBranding', () => {
+        it('returns empty branding for learncard (uses defaults)', () => {
+            const result = resolveTenantFromRequest({ 'x-tenant-id': 'learncard' });
+
+            expect(result.emailBranding).toEqual({});
+        });
+
+        it('returns vetpass overrides for vetpass tenant', () => {
+            const result = resolveTenantFromRequest({ 'x-tenant-id': 'vetpass' });
+
+            expect(result.emailBranding.brandName).toBe('VetPass');
+            expect(result.emailBranding.primaryColor).toBe('#1B5E20');
+            expect(result.emailBranding.supportEmail).toBe('support@vetpass.app');
+        });
+
+        it('returns empty branding for unknown tenant', () => {
+            const result = resolveTenantFromRequest({ 'x-tenant-id': 'unknown-tenant' });
+
+            expect(result.emailBranding).toEqual({});
+        });
+    });
+
+    // -- Edge cases ----------------------------------------------------------
+
+    describe('edge cases', () => {
+        it('handles empty string header gracefully', () => {
+            const headers: RequestHeaders = { 'x-tenant-id': '' };
+            const result = resolveTenantFromRequest(headers);
+
+            // Empty string is falsy → falls through to default
+            expect(result.resolvedVia).not.toBe('header');
+        });
+
+        it('handles malformed origin URL gracefully', () => {
+            const headers: RequestHeaders = { origin: 'not-a-url' };
+            const result = resolveTenantFromRequest(headers);
+
+            // Should not throw, falls through to default
+            expect(result.id).toBe('learncard');
+            expect(result.resolvedVia).toBe('default');
+        });
+    });
+});
+
+// ---------------------------------------------------------------------------
+// registerOriginMapping
+// ---------------------------------------------------------------------------
+
+describe('registerOriginMapping', () => {
+    it('allows resolving a newly registered origin', () => {
+        registerOriginMapping('custom-deploy.example.com', 'custom-tenant');
+
+        const result = resolveTenantFromRequest({
+            origin: 'https://custom-deploy.example.com',
+        });
+
+        expect(result.id).toBe('custom-tenant');
+        expect(result.resolvedVia).toBe('origin');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// registerTenantBranding
+// ---------------------------------------------------------------------------
+
+describe('registerTenantBranding', () => {
+    it('adds branding for a new tenant', () => {
+        registerTenantBranding('new-tenant', { brandName: 'NewBrand' });
+
+        const result = resolveTenantFromRequest({ 'x-tenant-id': 'new-tenant' });
+
+        expect(result.emailBranding.brandName).toBe('NewBrand');
+    });
+
+    it('merges branding with existing values', () => {
+        registerTenantBranding('vetpass', { logoUrl: 'https://vetpass.app/logo.png' });
+
+        const result = resolveTenantFromRequest({ 'x-tenant-id': 'vetpass' });
+
+        // Merged — both old and new values present
+        expect(result.emailBranding.brandName).toBe('VetPass');
+        expect(result.emailBranding.logoUrl).toBe('https://vetpass.app/logo.png');
+    });
+});

package/src/branding.ts

@@ -0,0 +1,61 @@
+/**
+ * Tenant branding for email and SMS templates.
+ *
+ * Values are typically sourced from the tenant config's `email` section.
+ * Every field has a sensible LearnCard default so templates always render,
+ * even if the caller provides a partial (or empty) branding object.
+ */
+
+export interface TenantBranding {
+    /** Display name shown in email headers, subject lines, and SMS. */
+    brandName: string;
+
+    /** Full URL to a hosted logo image (PNG/SVG, ideally 200×50 or similar). */
+    logoUrl: string;
+
+    /** Alt text for the logo image. */
+    logoAlt: string;
+
+    /** Primary brand color (hex). Used for CTA buttons and accents. */
+    primaryColor: string;
+
+    /** Text color on primary buttons. */
+    primaryTextColor: string;
+
+    /** Support / reply-to email address shown in footers. */
+    supportEmail: string;
+
+    /** Marketing website URL shown in footers. */
+    websiteUrl: string;
+
+    /** Base app URL for constructing links (e.g. "https://learncard.app"). */
+    appUrl: string;
+
+    /** Email domain for the From address (e.g. "learncard.com"). */
+    fromDomain: string;
+
+    /** Copyright holder name for the footer. */
+    copyrightHolder: string;
+}
+
+export const DEFAULT_BRANDING: TenantBranding = {
+    brandName: 'LearnCard',
+    logoUrl: 'https://learncard.app/assets/icon/icon.png',
+    logoAlt: 'LearnCard',
+    primaryColor: '#6366f1',
+    primaryTextColor: '#ffffff',
+    supportEmail: 'support@learningeconomy.io',
+    websiteUrl: 'https://www.learncard.com',
+    appUrl: 'https://learncard.app',
+    fromDomain: 'learncard.com',
+    copyrightHolder: 'Learning Economy Foundation',
+};
+
+/**
+ * Merge partial branding with defaults.
+ * Any missing field falls back to the LearnCard default.
+ */
+export const resolveBranding = (partial?: Partial<TenantBranding>): TenantBranding => ({
+    ...DEFAULT_BRANDING,
+    ...partial,
+});

package/src/components/CodeBlock.tsx

@@ -0,0 +1,61 @@
+/**
+ * CodeBlock — displays a verification code or recovery key prominently.
+ *
+ * Used by verification-code and recovery-key templates.
+ */
+
+import { Section, Text } from '@react-email/components';
+import * as React from 'react';
+
+interface CodeBlockProps {
+    code: string;
+    /** Optional label above the code (e.g. "Your verification code"). */
+    label?: string;
+    /** 'code' (default) for short 6-digit codes, 'key' for long recovery keys. */
+    variant?: 'code' | 'key';
+}
+
+export const CodeBlock: React.FC<CodeBlockProps> = ({ code, label, variant = 'code' }) => (
+    <Section style={wrapper}>
+        {label && <Text style={labelStyle}>{label}</Text>}
+
+        <Text style={variant === 'key' ? keyStyle : codeStyle}>{code}</Text>
+    </Section>
+);
+
+const wrapper: React.CSSProperties = {
+    backgroundColor: '#f9fafb',
+    border: '1px solid #e5e7eb',
+    borderRadius: 8,
+    padding: '16px 24px',
+    margin: '0 0 24px',
+    textAlign: 'center' as const,
+};
+
+const labelStyle: React.CSSProperties = {
+    fontSize: 12,
+    fontWeight: 600,
+    color: '#6b7280',
+    margin: '0 0 8px',
+    textTransform: 'uppercase' as const,
+    letterSpacing: '0.05em',
+};
+
+const codeStyle: React.CSSProperties = {
+    fontSize: 32,
+    fontWeight: 700,
+    color: '#111827',
+    letterSpacing: 6,
+    margin: 0,
+    fontFamily: "'Courier New', Courier, monospace",
+};
+
+const keyStyle: React.CSSProperties = {
+    fontSize: 13,
+    fontWeight: 400,
+    color: '#111827',
+    lineHeight: '20px',
+    margin: 0,
+    fontFamily: "'Courier New', Courier, monospace",
+    wordBreak: 'break-all' as const,
+};

package/src/components/EmailButton.tsx

@@ -0,0 +1,36 @@
+/**
+ * EmailButton — branded CTA button for emails.
+ *
+ * Renders as an anchor tag with inline styles for maximum email client compatibility.
+ */
+
+import { Button } from '@react-email/components';
+import * as React from 'react';
+
+import type { TenantBranding } from '../branding';
+
+interface EmailButtonProps {
+    href: string;
+    branding: TenantBranding;
+    children: React.ReactNode;
+}
+
+export const EmailButton: React.FC<EmailButtonProps> = ({ href, branding, children }) => (
+    <Button
+        href={href}
+        style={{
+            backgroundColor: branding.primaryColor,
+            color: branding.primaryTextColor,
+            borderRadius: 4,
+            fontSize: 16,
+            fontWeight: 600,
+            textDecoration: 'none',
+            textAlign: 'center' as const,
+            display: 'inline-block',
+            padding: '16px 24px',
+            lineHeight: '1',
+        }}
+    >
+        {children}
+    </Button>
+);

package/src/components/IssuerLogo.tsx

@@ -0,0 +1,41 @@
+/**
+ * IssuerLogo — circular avatar for the credential issuer.
+ *
+ * Mirrors the 80×80 circular logo used in the original Postmark templates.
+ * Only renders when `logoUrl` is provided; otherwise renders nothing.
+ */
+
+import { Img, Section } from '@react-email/components';
+import * as React from 'react';
+
+interface IssuerLogoProps {
+    logoUrl?: string;
+    alt?: string;
+}
+
+export const IssuerLogo: React.FC<IssuerLogoProps> = ({ logoUrl, alt }) => {
+    if (!logoUrl) return null;
+
+    return (
+        <Section style={wrapper}>
+            <Img
+                src={logoUrl}
+                alt={alt ?? 'Issuer logo'}
+                width={80}
+                height={80}
+                style={avatar}
+            />
+        </Section>
+    );
+};
+
+const wrapper: React.CSSProperties = {
+    textAlign: 'center' as const,
+    margin: '0 0 24px',
+};
+
+const avatar: React.CSSProperties = {
+    borderRadius: '50%',
+    display: 'inline-block',
+    objectFit: 'cover',
+};

package/src/components/Layout.tsx

@@ -0,0 +1,192 @@
+/**
+ * TenantLayout — shared email wrapper with branded header + footer.
+ *
+ * Every email template wraps its content in this layout so branding
+ * is consistent across all tenant emails.
+ */
+
+import {
+    Html,
+    Head,
+    Body,
+    Container,
+    Section,
+    Img,
+    Text,
+    Link,
+    Preview,
+} from '@react-email/components';
+import * as React from 'react';
+
+import type { TenantBranding } from '../branding';
+
+interface LayoutProps {
+    branding: TenantBranding;
+    preview: 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. */
+    showHeaderLogo?: boolean;
+}
+
+export const Layout: React.FC<LayoutProps> = ({ branding, preview, children, showHeaderLogo = true }) => (
+    <Html lang="en">
+        <Head />
+
+        <Preview>{preview}</Preview>
+
+        <Body style={body}>
+            {/* Top spacer — Gmail strips <body> padding, so use an inline div */}
+            <div style={topSpacer}>&nbsp;</div>
+
+            {/* Wordmark — sits above the white card like the Postmark layout */}
+            <Container style={wordmarkContainer}>
+                <Text style={wordmark}>
+                    <Link href={branding.websiteUrl} style={wordmarkLink}>
+                        {branding.brandName.toUpperCase()}
+                    </Link>
+                </Text>
+            </Container>
+
+            <Container style={container}>
+                {/* Optional brand icon */}
+                {showHeaderLogo && (
+                    <Section style={headerLogo}>
+                        <Img
+                            src={branding.logoUrl}
+                            alt={branding.logoAlt}
+                            width={80}
+                            height={80}
+                            style={logoImg}
+                        />
+                    </Section>
+                )}
+
+                {/* Content */}
+                <Section style={showHeaderLogo ? contentAfterLogo : content}>
+                    {children}
+                </Section>
+            </Container>
+
+            {/* Footer — sits below the white card in the gray area */}
+            <Container style={footerContainer}>
+                <Text style={footerDisclaimer}>
+                    You received this email because someone requested to add this email
+                    to their {branding.brandName} account. Please ignore this email if
+                    this was not you.
+                </Text>
+
+                <Text style={footerCopyright}>
+                    {branding.copyrightHolder} &copy; {new Date().getFullYear()}
+                </Text>
+
+                <Text style={footerLinks}>
+                    <Link href={`mailto:${branding.supportEmail}`} style={footerLink}>
+                        Contact Support
+                    </Link>
+                </Text>
+            </Container>
+        </Body>
+    </Html>
+);
+
+// ---------------------------------------------------------------------------
+// Styles (inline for email compatibility)
+// ---------------------------------------------------------------------------
+
+const body: React.CSSProperties = {
+    backgroundColor: '#f3f4f6',
+    fontFamily: "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif",
+    margin: 0,
+    padding: 0,
+};
+
+const topSpacer: React.CSSProperties = {
+    height: 56,
+    lineHeight: '56px',
+    fontSize: 1,
+};
+
+const wordmarkContainer: React.CSSProperties = {
+    maxWidth: 560,
+    margin: '0 auto',
+    padding: '0 40px',
+    textAlign: 'center' as const,
+};
+
+const wordmark: React.CSSProperties = {
+    fontSize: 13,
+    fontWeight: 600,
+    letterSpacing: 4,
+    color: '#52597A',
+    margin: '0 0 32px',
+    padding: '8px 0 0',
+};
+
+const wordmarkLink: React.CSSProperties = {
+    color: '#52597A',
+    textDecoration: 'none',
+};
+
+const container: React.CSSProperties = {
+    backgroundColor: '#ffffff',
+    borderRadius: 4,
+    margin: '0 auto',
+    maxWidth: 600,
+    padding: 0,
+    boxShadow: '0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)',
+};
+
+const headerLogo: React.CSSProperties = {
+    padding: '48px 48px 0',
+    textAlign: 'center' as const,
+};
+
+const logoImg: React.CSSProperties = {
+    borderRadius: 10,
+    display: 'inline-block',
+};
+
+const content: React.CSSProperties = {
+    padding: '48px 48px 48px',
+};
+
+const contentAfterLogo: React.CSSProperties = {
+    padding: '24px 48px 48px',
+};
+
+const footerContainer: React.CSSProperties = {
+    maxWidth: 560,
+    margin: '0 auto',
+    padding: '32px 40px 40px',
+    textAlign: 'center' as const,
+};
+
+const footerDisclaimer: React.CSSProperties = {
+    fontSize: 12,
+    color: '#6b7280',
+    lineHeight: '18px',
+    margin: '0 0 16px',
+    textAlign: 'center' as const,
+};
+
+const footerCopyright: React.CSSProperties = {
+    fontSize: 12,
+    color: '#6b7280',
+    lineHeight: '18px',
+    margin: '0 0 8px',
+    textAlign: 'center' as const,
+};
+
+const footerLinks: React.CSSProperties = {
+    fontSize: 12,
+    color: '#6b7280',
+    lineHeight: '18px',
+    margin: 0,
+    textAlign: 'center' as const,
+};
+
+const footerLink: React.CSSProperties = {
+    color: '#6b7280',
+    textDecoration: 'underline',
+};

package/src/components/LinkFallback.tsx

@@ -0,0 +1,50 @@
+/**
+ * LinkFallback — "copy and paste this link" fallback below CTA buttons.
+ *
+ * Mirrors the fallback link pattern used in the original Postmark templates.
+ */
+
+import { Text, Link, Hr } from '@react-email/components';
+import * as React from 'react';
+
+interface LinkFallbackProps {
+    href: string;
+}
+
+export const LinkFallback: React.FC<LinkFallbackProps> = ({ href }) => (
+    <>
+        <Hr style={divider} />
+
+        <Text style={hint}>
+            If you have trouble with the button above, copy and paste this link into your browser:
+        </Text>
+
+        <Text style={linkText}>
+            <Link href={href} style={link}>{href}</Link>
+        </Text>
+    </>
+);
+
+const divider: React.CSSProperties = {
+    borderColor: '#e5e7eb',
+    margin: '24px 0 16px',
+};
+
+const hint: React.CSSProperties = {
+    fontSize: 12,
+    color: '#6b7280',
+    lineHeight: '18px',
+    margin: '0 0 4px',
+};
+
+const linkText: React.CSSProperties = {
+    fontSize: 12,
+    lineHeight: '18px',
+    margin: '0 0 4px',
+    wordBreak: 'break-all' as const,
+};
+
+const link: React.CSSProperties = {
+    color: '#6366f1',
+    textDecoration: 'none',
+};