@company-semantics/contracts 27.12.0 → 27.13.0

package/src/email/render/__tests__/render-snapshot.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Locks the rendered output (subject / text / html) of every email kind ×
+ * representative variant. This is production-parity email markup — a snapshot
+ * change means a real sent email changed. Review the diff, then `vitest -u`.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { EmailPayloads } from "../../types";
+import {
+  IMPLEMENTED_EMAIL_KINDS,
+  type ImplementedEmailKind,
+  type RenderEmailOptions,
+  type RenderedEmail,
+  renderEmail,
+} from "../index";
+
+interface Fixture {
+  kind: ImplementedEmailKind;
+  name: string;
+  render: () => RenderedEmail;
+}
+
+const fixtures: Fixture[] = [];
+function add<K extends ImplementedEmailKind>(
+  kind: K,
+  name: string,
+  payload: EmailPayloads[K],
+  options?: RenderEmailOptions,
+): void {
+  fixtures.push({
+    kind,
+    name,
+    render: () => renderEmail(kind, payload, options),
+  });
+}
+
+const APP = "https://app.companysemantics.ai";
+
+add("auth.otp", "Default", { otp: "123456", expiresInMinutes: 10 });
+add("auth.otp", "Short expiry", { otp: "902413", expiresInMinutes: 1 });
+add(
+  "auth.otp",
+  "With request metadata",
+  {
+    otp: "246810",
+    expiresInMinutes: 5,
+    requestIp: "203.0.113.4",
+    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+  },
+  { includeRequestMetadata: true },
+);
+
+add("org.invite", "Admin", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "admin",
+  acceptUrl: `${APP}/invite/abc123`,
+  expiresInDays: 7,
+});
+add("org.invite", "Member", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/def456`,
+  expiresInDays: 7,
+});
+
+add("org.unit_owner_granted", "Unit owner + message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  unitName: "Platform Engineering",
+  roleLabel: "Unit owner",
+  ctaUrl: `${APP}/org/unit/42`,
+  message: "Welcome aboard — glad to have you owning this team.",
+});
+add("org.unit_owner_granted", "Delegate, no message", {
+  granterName: "Jordan Lee",
+  unitName: "Platform Engineering",
+  roleLabel: "Delegate",
+  ctaUrl: `${APP}/org/unit/42`,
+});
+
+add("org.ownership_transfer", "With note", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok123`,
+  expiresInDays: 14,
+  note: "Handing this over as I move to an advisory role.",
+});
+add("org.ownership_transfer", "No note", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok456`,
+  expiresInDays: 14,
+});
+
+add("org.ownership_transfer_completed", "Default", {
+  orgName: "Acme Corp",
+  newOwnerEmail: "new.owner@acme.com",
+});
+
+add("security.alert", "Excessive OTP requests", {
+  alertType: "excessive_otp_requests",
+  details: "12 login codes requested in 5 minutes",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+add("security.alert", "Unusual login location", {
+  alertType: "unusual_login_location",
+  details: "Login from Berlin, DE",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+
+const CHAT_BASE = {
+  sharedByName: "Alex Rivera",
+  visibility: "private",
+} as const;
+add("chat.shared", "Default", {
+  ...CHAT_BASE,
+  chatTitle: "API design discussion",
+  shareUrl: `${APP}/share/abc123`,
+  previewText:
+    "Here are my thoughts on the REST API design for the new authentication endpoints.",
+});
+add("chat.shared", "No preview", {
+  ...CHAT_BASE,
+  chatTitle: "Quick sync notes",
+  shareUrl: `${APP}/share/xyz789`,
+});
+add("chat.shared", "Long title", {
+  ...CHAT_BASE,
+  visibility: "public",
+  chatTitle:
+    "This is a very long chat title that should be truncated to fit the layout properly",
+  shareUrl: `${APP}/share/long456`,
+  previewText: "The assistant response preview text.",
+});
+add("chat.shared", "Long preview", {
+  ...CHAT_BASE,
+  chatTitle: "Code review feedback",
+  shareUrl: `${APP}/share/preview789`,
+  previewText:
+    "I reviewed the pull request and found several areas that need improvement. The authentication logic needs better error handling, and the database queries could be optimized.",
+});
+add("chat.shared", "Short", {
+  ...CHAT_BASE,
+  chatTitle: "Hi",
+  shareUrl: `${APP}/share/short123`,
+  previewText: "Hello!",
+});
+
+add("share.granted", "Document · editor · message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  entityLabel: "document",
+  entityTitle: "Q3 Roadmap",
+  accessLevel: "editor",
+  ctaUrl: `${APP}/doc/roadmap`,
+  message: "Take a look before Thursday's planning.",
+});
+add("share.granted", "Meeting · viewer · no title", {
+  granterName: "Jordan Lee",
+  entityLabel: "meeting",
+  accessLevel: "viewer",
+  ctaUrl: `${APP}/meeting/8842`,
+});
+
+add("companyMd.access_requested", "With message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  message: "I'd like to contribute the onboarding section.",
+  reviewUrl: `${APP}/doc/handbook?request=req_123`,
+});
+add("companyMd.access_requested", "No message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  reviewUrl: `${APP}/doc/handbook?request=req_456`,
+});
+
+add("companyMd.access_request_approved", "Editor", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "editor",
+  docUrl: `${APP}/doc/handbook`,
+});
+add("companyMd.access_request_approved", "Viewer", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "viewer",
+  docUrl: `${APP}/doc/handbook`,
+});
+
+add("companyMd.access_request_denied", "With reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  reason: "This doc is limited to the platform team for now.",
+});
+add("companyMd.access_request_denied", "No reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+});
+
+describe("email render", () => {
+  it("has a fixture for every implemented kind", () => {
+    const covered = new Set(fixtures.map((f) => f.kind));
+    for (const kind of IMPLEMENTED_EMAIL_KINDS) {
+      expect(covered.has(kind), `missing fixture for ${kind}`).toBe(true);
+    }
+  });
+
+  for (const fixture of fixtures) {
+    it(`${fixture.kind} · ${fixture.name}`, () => {
+      expect(fixture.render()).toMatchSnapshot();
+    });
+  }
+});

package/src/email/render/auth-otp.ts

@@ -0,0 +1,91 @@
+/**
+ * Auth OTP email (login code). Plain text + HTML.
+ *
+ * INVARIANT: the OTP value is a runtime payload field — never a literal in this
+ * package. Request metadata (IP / user agent) is gated by the caller-supplied
+ * `includeRequestMetadata` option (backend reads its env flag and passes it).
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  asciiCodeBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  htmlShell,
+  metaRow,
+  monoParagraph,
+  signatureLine,
+} from "./blocks";
+import { COMPANY_NAME } from "./constants";
+
+export type AuthOtpPayload = EmailPayloads["auth.otp"];
+
+export interface RenderOptions {
+  /** Include request IP / device details (PII; opt-in). */
+  includeRequestMetadata?: boolean;
+}
+
+export function renderAuthOtpBody(
+  payload: AuthOtpPayload,
+  options?: RenderOptions,
+): string {
+  const { otp, expiresInMinutes, requestIp, userAgent } = payload;
+
+  const sections: string[] = [];
+  sections.push("Your login code is below.");
+  sections.push(asciiCodeBox(otp));
+  sections.push(
+    `This code expires in ${expiresInMinutes} ${expiresInMinutes === 1 ? "minute" : "minutes"}.`,
+  );
+
+  // PRIVACY: IP address is PII under GDPR, so this feature is opt-in.
+  if (options?.includeRequestMetadata && (requestIp || userAgent)) {
+    sections.push("");
+    sections.push("Request details:");
+    if (requestIp) {
+      sections.push(`  IP address: ${requestIp}`);
+    }
+    if (userAgent) {
+      const truncated =
+        userAgent.length > 80 ? userAgent.substring(0, 77) + "..." : userAgent;
+      sections.push(`  Device: ${truncated}`);
+    }
+  }
+
+  sections.push("");
+  sections.push(
+    "If you didn't request this code, you can safely ignore this email.",
+  );
+
+  return baseTextLayout(sections.join("\n"));
+}
+
+export function renderAuthOtpHtml(payload: AuthOtpPayload): string {
+  const { otp, expiresInMinutes } = payload;
+
+  return htmlShell([
+    bodyParagraph("Copy/paste code in login form:"),
+    ctaBox({
+      label: otp,
+      padding: "20px 24px",
+      fontSize: "20px",
+      borderRadiusZero: true,
+      letterSpacing: "4px",
+    }),
+    metaRow("Status", "VALID", "tight"),
+    metaRow(
+      "Expires in",
+      `${expiresInMinutes} ${expiresInMinutes === 1 ? "min" : "mins"}`,
+      "normal",
+    ),
+    footer(
+      `This code was generated to authorize a login to ${COMPANY_NAME}.`,
+      "It expires automatically and cannot be reused.",
+    ),
+    monoParagraph("If this wasn't you, no action is required."),
+    signatureLine(),
+  ]);
+}

package/src/email/render/base-text.ts

@@ -0,0 +1,26 @@
+/**
+ * Plain-text email layout.
+ */
+
+import { COMPANY_NAME, SUPPORT_EMAIL } from "./constants";
+
+/**
+ * Wrap plain-text email content in the shared footer
+ * (`--- / <signer> / Questions? Contact <support>`).
+ *
+ * @param content - Body content (without footer); trimmed.
+ * @param signer - Footer signer name; defaults to the company name.
+ *   (`security.alert` passes "Company Semantics Security".)
+ */
+export function baseTextLayout(
+  content: string,
+  signer: string = COMPANY_NAME,
+): string {
+  const footer = `
+---
+${signer}
+Questions? Contact ${SUPPORT_EMAIL}
+`;
+
+  return content.trim() + "\n" + footer.trim() + "\n";
+}

package/src/email/render/blocks.ts

@@ -0,0 +1,308 @@
+/**
+ * Shared email building blocks.
+ *
+ * The single source of truth for the styled markup every template composes.
+ * Principle: **blocks own the styling; templates supply only content text.**
+ * Editing a block here restyles every email — HTML and plain text — across the
+ * backend (real sends) and the app (Ladle preview).
+ *
+ * INVARIANTS:
+ * - Pure string functions, no side effects.
+ * - Callers pass already-escaped content for any user-controlled HTML field.
+ */
+
+import {
+  COMPANY_NAME,
+  MONO_FONT_STACK,
+  TITLE_TRUNCATE_LENGTH,
+} from "./constants";
+import { escapeHtml } from "./escape-html";
+
+const MONO = `font-family: ${MONO_FONT_STACK};`;
+
+// =============================================================================
+// HTML — shell
+// =============================================================================
+
+/** Wrap body blocks in the shared `<!DOCTYPE>` monospace shell. */
+export function htmlShell(blocks: string | string[]): string {
+  const inner = Array.isArray(blocks)
+    ? blocks.filter(Boolean).join("\n")
+    : blocks;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"></head>
+<body style="${MONO} color: #1a1a1a; margin: 0; padding: 0;">
+${inner}
+</body>
+</html>`;
+}
+
+// =============================================================================
+// HTML — paragraphs
+// =============================================================================
+
+/** Vertical spacing options for a mono paragraph. */
+export type Spacing = "normal" | "tight" | "none";
+const SPACING: Record<Spacing, string> = {
+  normal: "0 0 20px 0",
+  tight: "0 0 4px 0",
+  none: "0",
+};
+
+/** Intro / greeting / body paragraph (inherits the body monospace). */
+export function bodyParagraph(html: string): string {
+  return `<p style="margin: 0 0 20px 0; font-size: 14px;">${html}</p>`;
+}
+
+/** "Hi Name," / "Hi," greeting. Escapes the name. */
+export function greeting(recipientName?: string): string {
+  return bodyParagraph(
+    recipientName ? `Hi ${escapeHtml(recipientName)},` : "Hi,",
+  );
+}
+
+/** Monospace paragraph for meta / footer / notice lines. */
+export function monoParagraph(
+  html: string,
+  spacing: Spacing = "normal",
+): string {
+  return `<p style="${MONO} font-size: 14px; margin: ${SPACING[spacing]};">${html}</p>`;
+}
+
+/** "Label: <b>value</b>" metadata row. */
+export function metaRow(
+  label: string,
+  valueHtml: string,
+  spacing: Spacing = "tight",
+): string {
+  return monoParagraph(`${label}: <b>${valueHtml}</b>`, spacing);
+}
+
+/** Footer paragraph: first line + optional second line after a `<br>`. */
+export function footer(
+  firstLine: string,
+  secondLine?: string,
+  spacing: Spacing = "normal",
+): string {
+  return monoParagraph(
+    secondLine ? `${firstLine}<br>${secondLine}` : firstLine,
+    spacing,
+  );
+}
+
+/** Trailing company signature paragraph. */
+export function signatureLine(): string {
+  return monoParagraph(COMPANY_NAME, "none");
+}
+
+/** The standard "no action required" reassurance line (content constant). */
+export const NOTICE = "If you weren't expecting this, no action is required.";
+
+/** Human phrasing per access level (share-granted, access-approved). */
+export const ACCESS_PHRASE: Record<"editor" | "commenter" | "viewer", string> =
+  {
+    editor: "can edit",
+    commenter: "can comment",
+    viewer: "can view",
+  };
+
+/** Centered continuation dots separator (chat-shared). */
+export function chatDots(): string {
+  return `<p style="${MONO} font-size: 20px; margin: 0 0 16px 0; max-width: 320px; text-align: center;">⋮</p>`;
+}
+
+// =============================================================================
+// HTML — CTA box
+// =============================================================================
+
+/** Options for the `>> LABEL <<` call-to-action box. */
+export interface CtaBoxOptions {
+  /** Text between the chevrons (already display-safe). */
+  label: string;
+  /** When present, the label links to this URL. */
+  href?: string;
+  /** Inner-cell padding, e.g. `"16px 24px"`. */
+  padding: string;
+  /** Label font-size, e.g. `"16px"`. */
+  fontSize: string;
+  /** Optional table `max-width`, e.g. `"220px"`. */
+  maxWidth?: string;
+  /** Emit `border-radius: 0;` (OTP code box). */
+  borderRadiusZero?: boolean;
+  /** Optional `letter-spacing`, e.g. `"4px"` (OTP code box). */
+  letterSpacing?: string;
+}
+
+/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). */
+export function ctaBox(opts: CtaBoxOptions): string {
+  const {
+    label,
+    href,
+    padding,
+    fontSize,
+    maxWidth,
+    borderRadiusZero,
+    letterSpacing,
+  } = opts;
+
+  const tableStyle =
+    `border: 2px solid #1a1a1a;` +
+    (borderRadiusZero ? ` border-radius: 0;` : ``) +
+    ` margin: 0 0 20px 0;` +
+    (maxWidth ? ` max-width: ${maxWidth};` : ``);
+
+  const tdStyle =
+    `padding: ${padding}; text-align: center; ${MONO} font-size: ${fontSize};` +
+    (letterSpacing ? ` letter-spacing: ${letterSpacing};` : ``);
+
+  const chevrons = `<b>&gt;&gt; ${label} &lt;&lt;</b>`;
+  const inner = href
+    ? `<a href="${href}" style="color: #0047FF; text-decoration: underline;">${chevrons}</a>`
+    : chevrons;
+
+  return `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
+  <tr><td style="${tdStyle}">
+    ${inner}
+  </td></tr>
+</table>`;
+}
+
+// =============================================================================
+// HTML — quote block
+// =============================================================================
+
+/** The left-ruled quoted-message block. Both args must be pre-escaped. */
+export function quoteBlock(labelHtml: string, bodyHtml: string): string {
+  return `<table cellpadding="0" cellspacing="0" border="0" style="margin: 0 0 20px 0;">
+  <tr><td style="border-left: 2px solid #1a1a1a; padding: 4px 14px; ${MONO} font-size: 13px; background: #f5f5f5;">
+    <span style="color: #555;">${labelHtml}</span><br>${bodyHtml}
+  </td></tr>
+</table>`;
+}
+
+// =============================================================================
+// HTML — chat bubbles
+// =============================================================================
+
+/** Right-aligned user chat bubble. `contentHtml` must be escaped + truncated. */
+export function chatUserBubble(contentHtml: string): string {
+  return `<table cellpadding="0" cellspacing="0" border="0" style="margin: 0 0 16px 0;">
+  <tr>
+    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 0 12px; padding: 10px 14px; min-width: 280px; text-align: right; ${MONO} font-size: 13px; background: #f5f5f5;">${contentHtml}</td>
+    <td style="${MONO} font-size: 14px; padding-left: 8px; vertical-align: bottom;">(•̀_ರ╮)</td>
+  </tr>
+</table>`;
+}
+
+/** Left-aligned assistant chat bubble. `contentHtml` must be escaped + truncated. */
+export function chatAssistantBubble(contentHtml: string): string {
+  return `<table cellpadding="0" cellspacing="0" border="0" style="margin: 16px 0;">
+  <tr>
+    <td style="${MONO} font-size: 14px; padding-right: 8px; vertical-align: top;">[c_S]</td>
+    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 12px 0; padding: 10px 14px; min-width: 280px; ${MONO} font-size: 13px; background: #f5f5f5;">${contentHtml}</td>
+  </tr>
+</table>`;
+}
+
+// =============================================================================
+// Plain text — CTA / code boxes
+// =============================================================================
+
+const CTA_BOX_WIDTH = 20;
+const CODE_BOX_WIDTH = 18;
+
+function centered(value: string, width: number): string {
+  const pad = Math.max(0, width - value.length);
+  const left = Math.floor(pad / 2);
+  const right = pad - left;
+  return `${" ".repeat(left)}${value}${" ".repeat(right)}`;
+}
+
+/** Normalized `>> LABEL <<` ASCII box (`*` corners, centered). */
+export function asciiCtaBox(label: string): string {
+  const line = `>> ${label} <<`;
+  const border = `*${"-".repeat(CTA_BOX_WIDTH)}*`;
+  const blank = `|${" ".repeat(CTA_BOX_WIDTH)}|`;
+  return [
+    border,
+    blank,
+    `|${centered(line, CTA_BOX_WIDTH)}|`,
+    blank,
+    border,
+  ].join("\n");
+}
+
+/** ASCII box that displays a code value (OTP; `+` corners, centered). */
+export function asciiCodeBox(value: string): string {
+  const border = `+${"-".repeat(CODE_BOX_WIDTH)}+`;
+  const blank = `|${" ".repeat(CODE_BOX_WIDTH)}|`;
+  return [
+    border,
+    blank,
+    `|${centered(value, CODE_BOX_WIDTH)}|`,
+    blank,
+    border,
+  ].join("\n");
+}
+
+// =============================================================================
+// Plain text — quote + chat boxes
+// =============================================================================
+
+/** Plain-text quoted message: `Label:` then the quoted value. */
+export function textQuote(label: string, value: string): string {
+  return `${label}:\n"${value}"`;
+}
+
+/** Plain-text continuation dots, centered under the 38-char chat box. */
+export function chatDotsText(): string {
+  return "                  ⋮";
+}
+
+/** Right-aligned user chat box (title, kaomoji). */
+export function chatUserBoxText(title: string): string {
+  const truncated =
+    title.length > TITLE_TRUNCATE_LENGTH
+      ? title.slice(0, TITLE_TRUNCATE_LENGTH - 3) + "..."
+      : title;
+  const padded = truncated.padStart(35);
+  return `┌────────────────────────────────────┐
+│${padded} │  (•̀_ರ╮)
+└────────────────────────────────────┘`;
+}
+
+/** Left-aligned assistant chat box with `[c_S]` label (max 2 lines, 36 wide). */
+export function chatAssistantBoxText(text: string): string {
+  const lineWidth = 36;
+  const maxChars = lineWidth * 2;
+
+  let truncated = text;
+  if (text.length > maxChars - 3) {
+    truncated = text.slice(0, maxChars - 3) + "...";
+  }
+
+  const lines: string[] = [];
+  let remaining = truncated;
+  while (remaining.length > 0 && lines.length < 2) {
+    if (remaining.length <= lineWidth) {
+      lines.push(remaining);
+      remaining = "";
+    } else {
+      let breakPoint = remaining.lastIndexOf(" ", lineWidth);
+      if (breakPoint <= 0) breakPoint = lineWidth;
+      lines.push(remaining.slice(0, breakPoint));
+      remaining = remaining.slice(breakPoint).trimStart();
+    }
+  }
+
+  const top = "       ┌──────────────────────────────────────┐";
+  const bot = "       └──────────────────────────────────────┘";
+  const boxLines = lines.map((line, i) => {
+    const padded = ` ${line.padEnd(lineWidth)} `;
+    const label = i === 0 ? "[c_S]  " : "       ";
+    return `${label}│${padded}│`;
+  });
+
+  return [top, ...boxLines, bot].join("\n");
+}