src/lib/email/shell.ts

/**
 * Shared HTML shell for transactional emails. Centralises the table-
 * based layout + the per-port branding override surface so templates
 * don't each inline a different copy of the boilerplate.
 *
 * Per-port branding (R2-H15):
 *   - logoUrl       - replaces the default Port Nimara logo image
 *   - primaryColor  - used for the page-title accent color
 *   - emailHeaderHtml / emailFooterHtml - admin-authored HTML that
 *     appears above / below the body content (e.g. legal footer,
 *     custom marketing strip). When unset, the existing minimal
 *     "Thank you, {{portName}} CRM" sign-off is rendered by callers.
 *
 * Senders resolve a `BrandingShell` via `resolveBrandingShell(portId)`
 * (or pass `null` for no override) and forward it to the template
 * function. Templates call `renderShell({ title, body, branding })`.
 */

import { absolutizeBrandingUrl } from '@/lib/branding/url';

// Neutral defaults - no tenant-specific imagery leaks across ports.
// When branding hasn't been configured the email renders without a logo
// and on a plain off-white background. Admins upload their own assets via
// /admin/branding which then flow through via getPortBrandingConfig().
const DEFAULT_LOGO_URL: string | null = null;
const DEFAULT_BACKGROUND_URL: string | null = null;
const DEFAULT_PRIMARY_COLOR = '#1e293b';

export interface BrandingShell {
  logoUrl: string | null;
  /** Phase 5: blurred page-background image rendered behind the white
   *  card. Defaults to the Port Nimara overhead image. Ports with
   *  their own marina photography override via system_settings. */
  backgroundUrl: string | null;
  primaryColor: string | null;
  emailHeaderHtml: string | null;
  emailFooterHtml: string | null;
}

interface ShellOpts {
  title: string;
  body: string;
  branding?: BrandingShell | null;
}

export function renderShell({ title, body, branding }: ShellOpts): string {
  // Branding URLs are stored path-only (so in-app rendering works across
  // any host). Mail clients have no app origin, so re-absolutize here.
  const logoUrl = absolutizeBrandingUrl(branding?.logoUrl ?? DEFAULT_LOGO_URL);
  const backgroundUrl = absolutizeBrandingUrl(branding?.backgroundUrl ?? DEFAULT_BACKGROUND_URL);
  const headerHtml = branding?.emailHeaderHtml ?? '';
  const footerHtml = branding?.emailFooterHtml ?? '';

  const wrapperStyle = backgroundUrl
    ? `background-image: url('${backgroundUrl}'); background-size: cover; background-position: center; background-color:#f2f2f2;`
    : 'background-color:#f2f2f2;';
  const logoBlock = logoUrl
    ? `<center><img src="${logoUrl}" alt="Logo" width="100" style="margin-bottom:20px;" /></center>`
    : '';

  return `<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <title>${title}</title>
  <style type="text/css">
    table, td { mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
    img { border: 0; display: block; }
    p { margin: 0; padding: 0; }
  </style>
</head>
<body style="margin:0; padding:0; background-color:#f2f2f2;">
  <table role="presentation" width="100%" border="0" cellspacing="0" cellpadding="0" style="${wrapperStyle}">
    <tr>
      <td align="center" style="padding:30px 16px;">
        <table role="presentation" width="600" border="0" cellspacing="0" cellpadding="0" style="width:100%; max-width:600px; background-color:#ffffff; border-radius:8px; overflow:hidden; box-shadow:0 2px 4px rgba(0,0,0,0.1);">
          <tr>
            <td style="padding:20px; font-family: Arial, sans-serif; color:#333333; word-break:break-word;">
              ${logoBlock}
              ${headerHtml ? `<div>${headerHtml}</div>` : ''}
              ${body}
              ${footerHtml ? `<div style="margin-top:24px;">${footerHtml}</div>` : ''}
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</body>
</html>`;
}

/** Surface the brand primary color to template bodies. */
export function brandingPrimaryColor(branding?: BrandingShell | null): string {
  return branding?.primaryColor ?? DEFAULT_PRIMARY_COLOR;
}

/**
 * URL-safe escaper for `href="..."` interpolations inside email
 * templates. The email-deliverability audit flagged that every template
 * inlined `${data.link}` directly into href + visible text without
 * escaping - a `"` (or worse, a `javascript:` scheme) would break out
 * of the attribute or trigger an XSS when the recipient opens the email
 * in a webmail client that runs scripts.
 *
 * Two-step defense:
 *  1. Scheme allow-list - only http(s), mailto, tel survive; everything
 *     else (javascript:, data:, vbscript:, file:, …) is rewritten to
 *     `about:blank`.
 *  2. HTML-attribute escape on `"`, `<`, `>`, `&`, `'`, backtick.
 */
export function safeUrl(url: string | null | undefined): string {
  if (!url) return 'about:blank';
  const trimmed = String(url).trim();
  // Block dangerous schemes. The allow-list is intentionally short.
  const lower = trimmed.toLowerCase();
  const ok =
    lower.startsWith('http://') ||
    lower.startsWith('https://') ||
    lower.startsWith('mailto:') ||
    lower.startsWith('tel:') ||
    // Relative or root-relative paths are also acceptable - they
    // resolve against the host the email links to (rare in transactional
    // mail but used by tracking pixels and unsubscribe headers).
    lower.startsWith('/') ||
    lower.startsWith('#');
  if (!ok) return 'about:blank';
  return trimmed
    .replace(/&/g, '&amp;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/`/g, '&#96;');
}