@learncard/email-templates 1.0.2 → 1.0.4

package/src/templates/verification-code.tsx

@@ -0,0 +1,164 @@
+/**
+ * VerificationCode — shared template for all code-based verification emails.
+ *
+ * Used by:
+ *   - login-verification-code (lca-api firebase.ts)
+ *   - recovery-email-code (lca-api keys.ts)
+ *   - embed-email-verification (brain-service contact-methods.ts)
+ *   - contact-method-verification (brain-service contact-methods.ts)
+ *
+ * The `variant` prop controls the subject line and descriptive text.
+ */
+
+import { Text } from '@react-email/components';
+import * as React from 'react';
+
+import type { TenantBranding } from '../branding';
+import { DEFAULT_BRANDING } from '../branding';
+import { Layout } from '../components/Layout';
+import { CodeBlock } from '../components/CodeBlock';
+
+export type VerificationCodeVariant =
+    | 'login'
+    | 'recovery-email'
+    | 'embed-verification'
+    | 'contact-method';
+
+export interface VerificationCodeProps {
+    branding: TenantBranding;
+    verificationCode: string;
+    verificationEmail?: string;
+    variant: VerificationCodeVariant;
+}
+
+const VARIANT_CONFIG: Record<
+    VerificationCodeVariant,
+    {
+        subject: (brandName: string) => string;
+        heading: (brandName: string) => string;
+        description: (email: string | undefined, brandName: string) => string;
+        expiry: string;
+    }
+> = {
+    login: {
+        subject: b => `Your ${b} login code`,
+        heading: b => `Your ${b} Login Code`,
+        description: (email, b) =>
+            email
+                ? `Here's your secure 6-digit code to log into ${b}`
+                : `Here's your secure 6-digit code to log into ${b}`,
+        expiry: 'This code will expire in 5 minutes. If you didn\u2019t request this, you can safely ignore this email.',
+    },
+    'recovery-email': {
+        subject: () => 'Verify your recovery email',
+        heading: b => `Your ${b} Verification Code`,
+        description: (email, b) =>
+            email
+                ? `Here's your secure 6-digit code to add ${email} as a recovery method for ${b}`
+                : `Here's your secure 6-digit code to add a recovery method for ${b}`,
+        expiry: 'This code will expire in 5 minutes. If you didn\u2019t request this, you can safely ignore this email.',
+    },
+    'embed-verification': {
+        subject: b => `Your ${b} verification code`,
+        heading: b => `Your ${b} Verification Code`,
+        description: email =>
+            email
+                ? `Enter this code to verify ${email} and claim your credential:`
+                : 'Enter this code to verify your email address and claim your credential:',
+        expiry: 'This code will expire in 10 minutes. If you didn\u2019t request this, you can safely ignore this email.',
+    },
+    'contact-method': {
+        subject: b => `Your ${b} verification code`,
+        heading: b => `Your ${b} Verification Code`,
+        description: () => 'Enter this code in the app to verify your contact information.',
+        expiry: 'This code will expire in 24 hours. If you didn\u2019t request this, you can safely ignore this email.',
+    },
+};
+
+export const VerificationCode: React.FC<VerificationCodeProps> = ({
+    branding,
+    verificationCode,
+    verificationEmail,
+    variant,
+}) => {
+    const config = VARIANT_CONFIG[variant];
+
+    return (
+        <Layout branding={branding} preview={`Your code: ${verificationCode}`}>
+            <Text style={headingStyle}>{config.heading(branding.brandName)}</Text>
+
+            <Text style={paragraph}>Hello,</Text>
+
+            <Text style={paragraph}>
+                {config.description(verificationEmail, branding.brandName)}
+            </Text>
+
+            <CodeBlock code={verificationCode} label="Verification code" />
+
+            <Text style={muted}>{config.expiry}</Text>
+
+            <Text style={paragraph}>
+                {branding.brandName} is your private, digital passport for learning and work. It
+                lets you securely collect and share your verified skills and achievements online.
+            </Text>
+
+            <Text style={signOff}>
+                Sincerely,
+                <br />
+                The {branding.brandName} Team
+            </Text>
+        </Layout>
+    );
+};
+
+export const getVerificationCodeSubject = (
+    branding: TenantBranding,
+    variant: VerificationCodeVariant
+): string => VARIANT_CONFIG[variant].subject(branding.brandName);
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const headingStyle: React.CSSProperties = {
+    fontSize: 24,
+    fontWeight: 600,
+    color: '#111827',
+    margin: '0 0 24px',
+};
+
+const paragraph: React.CSSProperties = {
+    fontSize: 16,
+    color: '#374151',
+    lineHeight: '24px',
+    margin: '0 0 24px',
+};
+
+const muted: React.CSSProperties = {
+    fontSize: 14,
+    color: '#6b7280',
+    lineHeight: '20px',
+    margin: '0 0 24px',
+};
+
+const signOff: React.CSSProperties = {
+    fontSize: 14,
+    color: '#374151',
+    lineHeight: '20px',
+    margin: '24px 0 0',
+};
+
+// ---------------------------------------------------------------------------
+// Preview (used by `bun run dev` / react-email dev server)
+// ---------------------------------------------------------------------------
+
+export default function Preview() {
+    return (
+        <VerificationCode
+            branding={DEFAULT_BRANDING}
+            verificationCode="847293"
+            verificationEmail="jane@example.com"
+            variant="login"
+        />
+    );
+}

package/src/tenant-registry.ts

@@ -0,0 +1,226 @@
+/**
+ * Server-side tenant resolution for brain-service and lca-api.
+ *
+ * Resolution order (first match wins):
+ *   1. Explicit `X-Tenant-Id` header — native apps, any client that knows its tenant
+ *   2. `Origin` / `Referer` header hostname — web apps (e.g. alpha.vetpass.app → vetpass)
+ *   3. `DEFAULT_TENANT_ID` env var — per-tenant deploys, cron jobs, server-to-server
+ *   4. Fallback to 'learncard'
+ *
+ * The registry maps tenant IDs to email branding overrides. Missing fields
+ * fall back to LearnCard defaults via `resolveBranding()`.
+ */
+
+import type { TenantBranding } from './branding';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTenant {
+    /** Canonical tenant identifier, e.g. 'vetpass', 'learncard'. */
+    id: string;
+
+    /** Partial email branding — pass to `resolveBranding()` for full defaults. */
+    emailBranding: Partial<TenantBranding>;
+
+    /** How the tenant was resolved — useful for logging / debugging. */
+    resolvedVia: 'header' | 'origin' | 'env' | 'default';
+}
+
+export interface RequestHeaders {
+    /** Value of the X-Tenant-Id header. */
+    'x-tenant-id'?: string | undefined;
+
+    /** Origin header (e.g. "https://alpha.vetpass.app"). */
+    origin?: string | undefined;
+
+    /** Referer header (fallback for Origin). */
+    referer?: string | undefined;
+
+    [key: string]: string | string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Origin → tenant ID mapping
+//
+// Add new entries when a tenant gets a web deployment.
+// Supports exact hostname match and wildcard subdomains.
+// ---------------------------------------------------------------------------
+
+const ORIGIN_MAP: Record<string, string> = {
+    // VetPass
+    'vetpass.app': 'vetpass',
+    'alpha.vetpass.app': 'vetpass',
+    'staging.vetpass.app': 'vetpass',
+
+    // ScoutPass
+    'scout.org': 'scoutpass',
+    'www.scout.org': 'scoutpass',
+    'pass.scout.org': 'scoutpass',
+    'staging.pass.scout.org': 'scoutpass',
+
+    // LearnCard
+    'learncard.app': 'learncard',
+    'staging.learncard.app': 'learncard',
+    'app.learncard.com': 'learncard',
+
+    // Local dev
+    'localhost': 'learncard',
+};
+
+// ---------------------------------------------------------------------------
+// Tenant email branding registry
+//
+// Only override fields that differ from LearnCard defaults.
+// Missing fields → resolveBranding() fills in DEFAULT_BRANDING.
+// ---------------------------------------------------------------------------
+
+const TENANT_EMAIL_BRANDING: Record<string, Partial<TenantBranding>> = {
+    learncard: {},
+
+    vetpass: {
+        brandName: 'VetPass',
+        logoUrl: 'https://vetpass.app/assets/icon/icon.png',
+        logoAlt: 'VetPass',
+        primaryColor: '#1B5E20',
+        primaryTextColor: '#ffffff',
+        supportEmail: 'support@vetpass.app',
+        websiteUrl: 'https://www.vetpass.app',
+        appUrl: 'https://vetpass.app',
+        fromDomain: 'vetpass.app',
+        copyrightHolder: 'VetPass',
+    },
+
+    scoutpass: {
+        brandName: 'ScoutPass',
+        logoUrl: 'https://pass.scout.org/assets/icon/icon.png',
+        logoAlt: 'ScoutPass',
+        primaryColor: '#00BA88',
+        primaryTextColor: '#ffffff',
+        supportEmail: 'support@scout.org',
+        websiteUrl: 'https://scout.org/scoutpass',
+        appUrl: 'https://pass.scout.org',
+        fromDomain: 'scoutnetwork.org',
+        copyrightHolder: 'ScoutPass',
+    },
+};
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a hostname from a URL string. Returns undefined if parsing fails.
+ */
+const extractHostname = (urlString: string): string | undefined => {
+    try {
+        return new URL(urlString).hostname;
+    } catch {
+        return undefined;
+    }
+};
+
+/**
+ * Look up tenant ID from a hostname, checking exact match first,
+ * then stripping subdomains progressively (e.g. "foo.bar.vetpass.app" → "vetpass.app").
+ */
+const tenantIdFromHostname = (hostname: string): string | undefined => {
+    if (ORIGIN_MAP[hostname]) return ORIGIN_MAP[hostname];
+
+    // Strip subdomains: "alpha.vetpass.app" → "vetpass.app"
+    const parts = hostname.split('.');
+
+    for (let i = 1; i < parts.length - 1; i++) {
+        const parent = parts.slice(i).join('.');
+
+        if (ORIGIN_MAP[parent]) return ORIGIN_MAP[parent];
+    }
+
+    return undefined;
+};
+
+/**
+ * Resolve the tenant from HTTP request headers.
+ *
+ * @param headers — Request headers object. Accepts plain objects, Node IncomingHttpHeaders, etc.
+ * @param envTenantId — Override for `process.env.DEFAULT_TENANT_ID` (useful for testing).
+ */
+export const resolveTenantFromRequest = (
+    headers: RequestHeaders,
+    envTenantId?: string
+): ResolvedTenant => {
+    // 1. Explicit X-Tenant-Id header (native apps, any informed client)
+    const explicit = normalizeHeader(headers['x-tenant-id']);
+
+    if (explicit) {
+        return buildTenant(explicit, 'header');
+    }
+
+    // 2. Origin / Referer header (web apps)
+    const origin = normalizeHeader(headers.origin) || normalizeHeader(headers.referer);
+
+    if (origin) {
+        const hostname = extractHostname(origin);
+
+        if (hostname) {
+            const matched = tenantIdFromHostname(hostname);
+
+            if (matched) {
+                return buildTenant(matched, 'origin');
+            }
+        }
+    }
+
+    // 3. Deploy-level env var
+    const envDefault = envTenantId ?? process.env.DEFAULT_TENANT_ID;
+
+    if (envDefault) {
+        return buildTenant(envDefault, 'env');
+    }
+
+    // 4. Safe default
+    return buildTenant('learncard', 'default');
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const normalizeHeader = (value: string | string[] | undefined): string | undefined => {
+    if (Array.isArray(value)) return value[0];
+
+    return value || undefined;
+};
+
+const buildTenant = (id: string, resolvedVia: ResolvedTenant['resolvedVia']): ResolvedTenant => ({
+    id,
+    emailBranding: TENANT_EMAIL_BRANDING[id] ?? {},
+    resolvedVia,
+});
+
+// ---------------------------------------------------------------------------
+// Admin helpers (for extending the registry at runtime via env vars)
+// ---------------------------------------------------------------------------
+
+/**
+ * Register additional origin → tenant mappings at startup.
+ * Useful for dev/staging domains configured via env vars.
+ */
+export const registerOriginMapping = (hostname: string, tenantId: string): void => {
+    ORIGIN_MAP[hostname] = tenantId;
+};
+
+/**
+ * Register or update email branding for a tenant at startup.
+ * Merges with any existing branding (does not replace).
+ */
+export const registerTenantBranding = (
+    tenantId: string,
+    branding: Partial<TenantBranding>
+): void => {
+    TENANT_EMAIL_BRANDING[tenantId] = {
+        ...TENANT_EMAIL_BRANDING[tenantId],
+        ...branding,
+    };
+};

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.